Governed asset registry slice with asset creation, representations, metadata, lifecycle transitions, policy authorization, fail-closed denial, audit events, and version records

docs/architecture-core-implementation.md

@@ -87,7 +87,6 @@ SQLite, Markitect, LLM providers, or source-system SDKs.
 
 ## Next Implementation Boundary
 
-The next workplan should build on these contracts rather than reusing the old
-artifact model directly. The natural next step is `KONT-WP-0005`: asset
-registry governance and durable state.
-
+The next workplan builds on these contracts rather than reusing the old
+artifact model directly. The first `KONT-WP-0005` slice is recorded in
+`docs/asset-registry-implementation.md`.

docs/asset-registry-implementation.md

@@ -0,0 +1,83 @@
+# Asset Registry Implementation Note
+
+Date: 2026-05-05
+
+Status: first implementation slice for `KONT-WP-0005`.
+
+## Purpose
+
+This note records the first governed asset registry implementation built on the
+architecture core. It establishes the service/repository boundary needed before
+durable ingestion, retrieval, transformation, and agent operations depend on
+asset state.
+
+## Implemented Package Shape
+
+```text
+src/kontextual_engine/
+  ports/
+    policy.py
+    repositories.py
+  services/
+    asset_service.py
+  adapters/
+    memory/asset_registry.py
+    sqlite/asset_registry.py
+```
+
+The service depends on engine-owned ports and domain core contracts. The memory
+and SQLite repositories are adapters behind those ports.
+
+## Implemented Capabilities
+
+- Stable `KnowledgeAsset` creation with explicit source references.
+- Separate source, normalized, and derived `AssetRepresentation` records.
+- `MetadataRecord` persistence with inferred/confirmed semantics preserved.
+- Actor and `OperationContext` required for material mutations.
+- Policy gateway authorization before asset mutations.
+- Fail-closed policy denial through `AuthorizationError`.
+- Audit events for create, metadata update, representation update, lifecycle
+  transition, and denied mutations.
+- Asset version records for create, content/representation changes, metadata
+  changes, and lifecycle changes.
+- In-memory repository for deterministic tests.
+- SQLite repository for local-first durable asset registry state.
+- SQLite foreign-key enforcement for representation and metadata asset
+  references.
+
+## Current SQLite Tables
+
+- `actors`
+- `assets`
+- `representations`
+- `metadata_records`
+- `asset_versions`
+- `audit_events`
+
+Payloads are stored as compact JSON envelopes while indexed columns carry
+stable lookup fields such as asset ID, lifecycle, representation kind, digest,
+sequence, actor ID, target, and correlation ID.
+
+## Not Yet Implemented
+
+- Full custom metadata schema validation.
+- Relationship persistence in the new core registry.
+- Policy assignment storage and enterprise policy adapters.
+- Idempotency-key persistence for mutation deduplication.
+- Conflict detection beyond version-sequence uniqueness.
+- Restore and supersession service operations.
+- Batch partial-failure envelopes.
+
+These remain in scope for later `KONT-WP-0005` tasks or adjacent workplans.
+
+## Test Coverage
+
+`tests/test_asset_registry.py` covers:
+
+- asset creation with source reference, representation, metadata, version, and
+  audit output,
+- 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.
+