kontextual-engine/docs/asset-registry-implementation.md

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

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.