flex-auth/docs/markitect-resource-namespace.md

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

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.