Define Markitect resource namespace

2026-05-17 06:14:04 +02:00
parent 4c9f964425
commit 6586adb4f5
5 changed files with 281 additions and 1 deletions
--- a/docs/markitect-resource-namespace.md
+++ b/docs/markitect-resource-namespace.md
@@ -0,0 +1,76 @@
+# Markitect Resource Namespace
+
+This document defines the Markitect protected-system namespace consumed by
+flex-auth. It is the P3.1 contract between Markitect resource metadata and the
+generic flex-auth registry.
+
+The namespace is intentionally Markitect-specific at the edge and generic once
+registered. Markitect may keep its local frontmatter and backend metadata
+names, but emitted resource manifests should normalize them into the resource
+types and CARING dimensions below.
+
+## Hierarchy
+
+```text
+knowledge_base
+  -> repository
+  -> document
+  -> section
+  -> span
+  -> context_package
+  -> workflow_artifact
+  -> export
+```
+
+Markitect may emit a partial tree. For example, a document can be parented
+directly to a knowledge base when the repository boundary is not material to a
+policy decision. flex-auth treats `parent` as a stable relationship hint; P3.2
+and P3.4 add importer and check fixtures that make inherited behavior explicit.
+
+## CARING Mapping
+
+| Markitect resource type | Parent types | CARING scope | CARING planes | Notes |
+| --- | --- | --- | --- | --- |
+| `knowledge_base` | none | `Workspace` | `Intent`, `Data` | Top-level user-visible knowledge container. |
+| `repository` | `knowledge_base` | `Project` | `Build`, `Data` | Versioned source or storage boundary behind a knowledge base. |
+| `document` | `repository`, `knowledge_base` | `Resource` | `Data` | Renderable document or page. Markitect `path` maps to resource `path`. |
+| `section` | `document` | `Subresource` | `Data` | Stable heading or block region inside a document. |
+| `span` | `section`, `document` | `Field` | `Data` | Fine-grained text range, cell, token span, or field-level surface. |
+| `context_package` | `knowledge_base`, `repository`, `document` | `Dataset` | `Intent`, `Data`, `Policy` | Bundled context prepared for model/tool use. |
+| `workflow_artifact` | `context_package`, `document` | `Process` | `Execution`, `Data`, `Audit` | Generated workflow output, review artifact, or intermediate. |
+| `export` | `workflow_artifact`, `context_package`, `document` | `Record` | `Data`, `Audit` | Materialized package, file, archive, or external transfer. |
+
+## Frontmatter Compatibility
+
+Markitect document frontmatter can remain local, but manifests should preserve
+the following mappings:
+
+- `id` or stable slug -> `resources[].id`
+- document kind -> `resources[].type`
+- source path -> `resources[].path`
+- parent knowledge base, repository, or document -> `resources[].parent`
+- labels, classification, or visibility -> `resources[].labels`
+- tenant/customer boundary -> `resources[].attributes.tenant` when it is not
+  already represented by the request subject/resource tenant
+- owner team or steward -> `resources[].owner`
+- freshness, workflow state, and source revision -> `resources[].attributes`
+
+## Backend Metadata Compatibility
+
+Backend metadata can be richer than the flex-auth contract. The manifest should
+keep durable values in `attributes` and avoid embedding backend-only transient
+state in resource ids.
+
+Recommended backend metadata keys:
+
+- `markitect_path`
+- `frontmatter_visibility`
+- `source_revision`
+- `workflow_state`
+- `freshness_seconds`
+- `data_classes`
+- `tenant`
+
+The examples in `examples/markitect/protected_system_manifest.yaml` and
+`examples/markitect/namespace_resource_manifest.yaml` are the pinned schema
+examples for this namespace.
--- a/examples/markitect/namespace_resource_manifest.yaml
+++ b/examples/markitect/namespace_resource_manifest.yaml
@@ -0,0 +1,83 @@
+id: markitect-namespace-example
+system: markitect-tool
+caring_profile: caring-0.4.0-rc2
+resources:
+  - id: knowledge-base:markitect-example
+    type: knowledge_base
+    labels:
+      - internal
+    trust_zone: internal
+    owner: team:platform-architecture
+  - id: repository:markitect-policy
+    type: repository
+    parent: knowledge-base:markitect-example
+    path: repos/markitect-policy
+    labels:
+      - internal
+    trust_zone: internal
+    owner: team:platform-architecture
+  - id: document:internal-note
+    type: document
+    parent: repository:markitect-policy
+    path: examples/policy/private/internal-note.md
+    labels:
+      - internal
+      - pii
+    trust_zone: internal
+    owner: team:platform-architecture
+    attributes:
+      markitect_path: examples/policy/private/internal-note.md
+      frontmatter_visibility: internal
+      source_revision: rev:example
+  - id: section:internal-note#risk
+    type: section
+    parent: document:internal-note
+    path: examples/policy/private/internal-note.md#risk
+    labels:
+      - internal
+    trust_zone: internal
+  - id: span:internal-note#risk:customer-email
+    type: span
+    parent: section:internal-note#risk
+    labels:
+      - pii
+    trust_zone: restricted
+    attributes:
+      data_classes:
+        - email
+  - id: context-package:internal-note-review
+    type: context_package
+    parent: document:internal-note
+    labels:
+      - internal
+      - generated
+    trust_zone: internal
+    attributes:
+      freshness_seconds: 900
+      workflow_state: prepared
+  - id: workflow-artifact:internal-note-review-run
+    type: workflow_artifact
+    parent: context-package:internal-note-review
+    labels:
+      - generated
+    trust_zone: internal
+    attributes:
+      workflow_state: completed
+  - id: export:internal-note-review-bundle
+    type: export
+    parent: workflow-artifact:internal-note-review-run
+    labels:
+      - export
+    trust_zone: external
+actions:
+  - read
+  - query
+  - search
+  - package
+  - activate_context
+  - export
+  - workflow_run
+  - admin
+metadata:
+  source: examples/markitect/namespace_resource_manifest.yaml
+  flex_auth_contract: resource-registration-v0
--- a/examples/markitect/protected_system_manifest.yaml
+++ b/examples/markitect/protected_system_manifest.yaml
@@ -0,0 +1,69 @@
+id: markitect-tool
+name: Markitect Tool
+description: Markitect protected-system namespace for flex-auth.
+caring_profiles:
+  - caring-0.4.0-rc2
+resource_types:
+  - name: knowledge_base
+    scope_level: Workspace
+    planes:
+      - Intent
+      - Data
+  - name: repository
+    parent_types:
+      - knowledge_base
+    scope_level: Project
+    planes:
+      - Build
+      - Data
+  - name: document
+    parent_types:
+      - repository
+      - knowledge_base
+    scope_level: Resource
+    planes:
+      - Data
+  - name: section
+    parent_types:
+      - document
+    scope_level: Subresource
+    planes:
+      - Data
+  - name: span
+    parent_types:
+      - section
+      - document
+    scope_level: Field
+    planes:
+      - Data
+  - name: context_package
+    parent_types:
+      - knowledge_base
+      - repository
+      - document
+    scope_level: Dataset
+    planes:
+      - Intent
+      - Data
+      - Policy
+  - name: workflow_artifact
+    parent_types:
+      - context_package
+      - document
+    scope_level: Process
+    planes:
+      - Execution
+      - Data
+      - Audit
+  - name: export
+    parent_types:
+      - workflow_artifact
+      - context_package
+      - document
+    scope_level: Record
+    planes:
+      - Data
+      - Audit
+metadata:
+  source: examples/markitect/protected_system_manifest.yaml
+  namespace_doc: docs/markitect-resource-namespace.md
--- a/pkg/api/resource_manifest_test.go
+++ b/pkg/api/resource_manifest_test.go
@@ -87,3 +87,55 @@ resources:
 		t.Fatalf("minimal manifest did not round-trip: %+v", m)
 	}
 }
+
+func TestMarkitectProtectedSystemNamespaceExampleParses(t *testing.T) {
+	path := filepath.Join("..", "..", "examples", "markitect", "protected_system_manifest.yaml")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+
+	var got api.ProtectedSystemManifest
+	if err := yaml.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	if got.ID != "markitect-tool" {
+		t.Fatalf("ID = %q; want markitect-tool", got.ID)
+	}
+	if len(got.ResourceTypes) != 8 {
+		t.Fatalf("ResourceTypes len = %d; want 8", len(got.ResourceTypes))
+	}
+	if got.ResourceTypes[0].Name != "knowledge_base" || got.ResourceTypes[0].ScopeLevel != api.ScopeLevelWorkspace {
+		t.Fatalf("first ResourceType = %+v; want knowledge_base Workspace", got.ResourceTypes[0])
+	}
+	if got.ResourceTypes[7].Name != "export" || got.ResourceTypes[7].ScopeLevel != api.ScopeLevelRecord {
+		t.Fatalf("last ResourceType = %+v; want export Record", got.ResourceTypes[7])
+	}
+}
+
+func TestMarkitectNamespaceResourceManifestExampleParses(t *testing.T) {
+	path := filepath.Join("..", "..", "examples", "markitect", "namespace_resource_manifest.yaml")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+
+	var got api.ResourceManifest
+	if err := yaml.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	if got.CaringProfile != api.CaringProfileCaring040RC2 {
+		t.Fatalf("CaringProfile = %q; want %q", got.CaringProfile, api.CaringProfileCaring040RC2)
+	}
+	if len(got.Resources) != 8 {
+		t.Fatalf("Resources len = %d; want 8", len(got.Resources))
+	}
+	if got.Resources[4].Type != "span" || got.Resources[4].TrustZone != "restricted" {
+		t.Fatalf("resources[4] = %+v; want restricted span", got.Resources[4])
+	}
+	if got.Resources[7].Type != "export" || got.Resources[7].Parent != "workflow-artifact:internal-note-review-run" {
+		t.Fatalf("resources[7] = %+v; want export child of workflow artifact", got.Resources[7])
+	}
+}
--- a/workplans/FLEX-WP-0003-markitect-consumer-integration.md
+++ b/workplans/FLEX-WP-0003-markitect-consumer-integration.md
@@ -38,7 +38,7 @@ Markitect-specific assumptions part of the generic core.

 ```task
 id: FLEX-WP-0003-T001
-status: todo
+status: done
 priority: high
 state_hub_task_id: "53f2fa67-780b-4e40-bbda-e669e4cecc32"
 ```