Markitect schema-validation integration use case and fixture for Markdown proxy documents

docs/architecture-blueprint.md

@@ -206,6 +206,11 @@ Adapter rules:
   checks, and context-package interoperability. Engine domain code must not
   import it directly; adapter code should persist serializable Markitect
   outputs as adapter provenance or representation metadata.
+- Markdown proxy documents are allowed as adapter projections for managed
+  assets. They can make every asset inspectable and contract-checkable through
+  Markitect where useful, but they are not the canonical engine identity or
+  storage model. The canonical layer remains asset, representation, metadata,
+  lifecycle, policy, lineage, and audit state.
 - `llm-connect` or equivalent is an adapter for LLM providers.
 - `phase-memory` is an adjacent memory runtime; this engine may exchange opaque
   memory references or context packages but should not implement memory phases.

docs/asset-registry-implementation.md

@@ -35,6 +35,8 @@ and SQLite repositories are adapters behind those ports.
 - `MetadataRecord` persistence with inferred/confirmed semantics preserved.
 - Custom metadata schema primitives with structured validation issues.
 - Metadata schema validation before asset create and metadata update writes.
+- Durable metadata schema registry and assignment rules for policy-selected
+  validation.
 - Actor and `OperationContext` required for material mutations.
 - Policy gateway authorization before asset mutations.
 - Fail-closed policy denial through `AuthorizationError`.
@@ -59,6 +61,8 @@ and SQLite repositories are adapters behind those ports.
 - `assets`
 - `representations`
 - `metadata_records`
+- `metadata_schemas`
+- `metadata_schema_assignments`
 - `context_entities`
 - `core_relationships`
 - `asset_versions`
@@ -72,7 +76,6 @@ idempotency key.
 
 ## Not Yet Implemented
 
-- Schema registry persistence and policy-assigned schema selection.
 - Standard metadata filtering beyond lifecycle and asset type.
 - Policy assignment storage and enterprise policy adapters.
 - Conflict detection beyond version-sequence uniqueness.
@@ -90,9 +93,10 @@ These remain in scope for later `KONT-WP-0005` tasks or adjacent workplans.
 - lifecycle denial with fail-closed policy and denied audit event,
 - SQLite reload preserving asset lifecycle, representation, metadata, versions,
   and audit history,
-- SQLite referential integrity for representation asset references.
+- SQLite referential integrity for representation asset references,
 - idempotent asset creation and conflicting idempotency-key reuse,
 - relationship creation with source-asset versioning and audit,
 - SQLite reload preserving context entities, relationships, and idempotency
   records,
-- custom metadata schema validation before registry writes.
+- custom metadata schema validation before registry writes,
+- persistent metadata schema registry and assignment reload behavior.

docs/markitect-tool-integration-usecases.md

@@ -218,6 +218,34 @@ Engine expectation:
 - The engine owns workflow templates, run state, retries, review gates,
   exceptions, audit, and derived artifacts.
 
+## Use Case 7: Markdown Proxy Schema Validation
+
+Intent: validate Markdown source or proxy documents through Markitect document
+schemas instead of adding a second Markdown schema validator to the engine.
+
+Expected Markitect APIs:
+
+- `load_schema_file(...)`
+- `validate_schema(...)`
+- `validate_document(...)`
+- `validate_markdown_file(...)`
+
+Example:
+
+```python
+from markitect_tool import validate_markdown_file
+
+result = validate_markdown_file("asset-proxy.md", "asset-proxy.schema.md")
+```
+
+Engine expectation:
+
+- Markdown proxy documents are adapter representations of governed assets.
+- Markitect owns Markdown document schema validation for those proxies.
+- Engine metadata schema validation remains registry-owned because it governs
+  asset metadata records, confirmation state, policy assignment, write
+  rejection, and audit behavior.
+
 ## Integration Test Matrix
 
 | Test area | Boundary protected |
@@ -228,6 +256,7 @@ Engine expectation:
 | Snapshot identity | Engine stores Markitect snapshot metadata without owning the algorithm. |
 | Context package policy filtering | Agent context can reuse Markitect packages and local label policy. |
 | Document contracts | Markdown validation can call Markitect contracts without moving contract semantics into the engine. |
+| Markdown document schemas | Markdown source/proxy validation uses Markitect schema APIs instead of duplicating them. |
 | Capacity sentinels | Larger generated examples expose likely parser, selector, include, context-package, and snapshot bottlenecks. |
 
 These tests are intentionally small but example-backed. They are not a

docs/markitect-tool-reuse-boundary.md

@@ -21,6 +21,13 @@ state should persist serializable envelopes, source references, digests,
 lineage, policy decisions, and audit events rather than storing Markitect
 runtime objects as canonical engine entities.
 
+Markdown proxy documents are a supported adapter pattern. The engine may create
+or store Markdown representations that proxy non-Markdown assets so Markitect
+selectors, contracts, document schemas, functions, and workflows can operate on
+them. Those proxies are representations of governed assets, not replacements
+for engine-owned asset identity, metadata, lifecycle, policy, lineage, or audit
+state.
+
 Required integration behavior is captured in
 `docs/markitect-tool-integration-usecases.md` and exercised by
 `tests/test_markitect_tool_contract.py`. These tests are allowed to skip when
@@ -35,6 +42,7 @@ stability checks for the boundary when the `markdown` extra is installed.
 | Document-level selectors and extraction | `markitect_tool.query`, `docs/query-extraction.md` | Use for markdown source extraction and context package creation. Engine query should operate over persisted artifacts and relationships. |
 | Deterministic transforms, composition, and includes | `markitect_tool.ops.engine`, `docs/transform-compose-include.md` | Treat as external operations invoked by workflows. Store operation provenance and derived artifacts in the engine. |
 | Contract checks, runtime context, forms, and assessments | `markitect_tool.contract.*`, `markitect_tool.runtime.*`, `docs/runtime-context-forms-assessments.md` | Use as validation/assessment step adapters. Engine owns run state and audit trail. |
+| Markdown document schema validation | `markitect_tool.schema.*` | Use for Markdown document/proxy validation. Engine-owned asset metadata validation stays in the registry layer. |
 | Backend manifests, local snapshots, FTS, and query adapters | `markitect_tool.backend.*`, `docs/backend-fabric.md` | Reuse snapshot identity and local index concepts. Engine storage remains separate and cross-format. |
 | Agent working memory context packages | `markitect_tool.memory.engine`, `docs/agent-working-memory.md` | Reuse as a portable context-package format for markdown-backed context. Engine should provide durable context registries across formats. |
 | Workflow definition syntax and markdown-centered step kinds | `markitect_tool.workflow.*`, `docs/workflow-definition-standard.md` | Reuse where workflows consume markdown inputs. Engine workflows should generalize to artifact collections, external tools, and service operations. |
@@ -44,7 +52,8 @@ stability checks for the boundary when the `markdown` extra is installed.
 ## Adapter Ownership Rules
 
 - Markdown ingestion adapters may call `parse_markdown`, `parse_markdown_file`,
-  `query_document`, `extract_document`, and `snapshot_identity_for_file`.
+  `query_document`, `extract_document`, `validate_document`,
+  `validate_markdown_file`, and `snapshot_identity_for_file`.
 - Markdown transformation adapters may call `transform_markdown`,
   `compose_files`, `resolve_includes`, Markitect contract checks, document
   functions, templates, and workflow helpers.