From 6586adb4f50796bb8375a163584ddf5e01d87f78 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 17 May 2026 06:14:04 +0200 Subject: [PATCH] Define Markitect resource namespace --- docs/markitect-resource-namespace.md | 76 +++++++++++++++++ .../namespace_resource_manifest.yaml | 83 +++++++++++++++++++ .../markitect/protected_system_manifest.yaml | 69 +++++++++++++++ pkg/api/resource_manifest_test.go | 52 ++++++++++++ ...-WP-0003-markitect-consumer-integration.md | 2 +- 5 files changed, 281 insertions(+), 1 deletion(-) create mode 100644 docs/markitect-resource-namespace.md create mode 100644 examples/markitect/namespace_resource_manifest.yaml create mode 100644 examples/markitect/protected_system_manifest.yaml diff --git a/docs/markitect-resource-namespace.md b/docs/markitect-resource-namespace.md new file mode 100644 index 0000000..79e196f --- /dev/null +++ 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. diff --git a/examples/markitect/namespace_resource_manifest.yaml b/examples/markitect/namespace_resource_manifest.yaml new file mode 100644 index 0000000..e1c7c68 --- /dev/null +++ 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 diff --git a/examples/markitect/protected_system_manifest.yaml b/examples/markitect/protected_system_manifest.yaml new file mode 100644 index 0000000..461a3c4 --- /dev/null +++ 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 diff --git a/pkg/api/resource_manifest_test.go b/pkg/api/resource_manifest_test.go index 52eec3f..6f672fb 100644 --- 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]) + } +} diff --git a/workplans/FLEX-WP-0003-markitect-consumer-integration.md b/workplans/FLEX-WP-0003-markitect-consumer-integration.md index e2ac2e7..31bea0a 100644 --- 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" ```