generated from coulomb/repo-seed
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 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.
|