generated from coulomb/repo-seed
84 lines
2.7 KiB
Markdown
84 lines
2.7 KiB
Markdown
# 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.
|
|
|