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

Asset Registry Implementation Note

Date: 2026-05-06

Status: active implementation note 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.
• 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.
• 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.
• Context entity persistence.
• Relationship persistence for asset-to-asset and asset-to-context-entity links.
• Relationship changes create source-asset version records and audit events.
• Idempotency records for safe asset creation retries.
• Idempotency-key reuse with a different payload raises a validation error.
• 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
• metadata_schemas
• metadata_schema_assignments
• context_entities
• core_relationships
• asset_versions
• audit_events
• idempotency_records

Payloads are stored as compact JSON envelopes while indexed columns carry stable lookup fields such as asset ID, lifecycle, representation kind, digest, sequence, relationship source/target, actor ID, target, correlation ID, and idempotency key.

Not Yet Implemented

• Standard metadata filtering beyond lifecycle and asset type.
• Policy assignment storage and enterprise policy adapters.
• 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,
• 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,
• persistent metadata schema registry and assignment reload behavior.