# 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

```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.
- 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.
- Asset listing filters for lifecycle, asset type, sensitivity, owner, topic,
  review state, metadata record values, and confirmed-only metadata.
- 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

- 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,
- classification and metadata-record asset filtering across memory and SQLite
  repositories.