generated from coulomb/repo-seed
93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# Architecture Core Implementation Note
|
|
|
|
Date: 2026-05-05
|
|
|
|
Status: first implementation slice for `KONT-WP-0004`.
|
|
|
|
## Purpose
|
|
|
|
This note records the initial implementation of the architecture core described
|
|
in `docs/architecture-blueprint.md`. It does not replace the older flat
|
|
runtime modules yet. Instead, it introduces canonical domain contracts that the
|
|
next workplans can build on while keeping existing tests and compatibility
|
|
exports stable.
|
|
|
|
## Implemented Core Package
|
|
|
|
New package:
|
|
|
|
```text
|
|
src/kontextual_engine/core/
|
|
actors.py
|
|
assets.py
|
|
audit.py
|
|
metadata.py
|
|
policy.py
|
|
primitives.py
|
|
provenance.py
|
|
relationships.py
|
|
```
|
|
|
|
Implemented primitives:
|
|
|
|
- `KnowledgeAsset`,
|
|
- `SourceReference`,
|
|
- `AssetRepresentation`,
|
|
- `AssetVersion`,
|
|
- `Classification`,
|
|
- `MetadataRecord`,
|
|
- `Actor`,
|
|
- `OperationContext`,
|
|
- `PolicyDecision`,
|
|
- `AuditEvent`,
|
|
- `ContextEntity`,
|
|
- `CoreRelationship`,
|
|
- `DerivedArtifactLineage`.
|
|
|
|
The package is deterministic, import-light, and has no dependency on HTTP,
|
|
SQLite, Markitect, LLM providers, or source-system SDKs.
|
|
|
|
## Current Module Mapping
|
|
|
|
| Existing module | V0.2 interpretation | Current posture |
|
|
| --- | --- | --- |
|
|
| `artifacts.py` | Early artifact and collection facade. | Reusable temporarily as compatibility layer; maps toward `KnowledgeAsset`, `AssetRepresentation`, and collection scope. |
|
|
| `relationships.py` | In-memory graph helper over artifact relationships. | Reusable as test helper; richer relationship contracts now start in `core.relationships`. |
|
|
| `ingestion.py` | First adapter-oriented ingestion facade. | Reusable for plain text and Markitect markdown adapter behavior; needs job model in `KONT-WP-0006`. |
|
|
| `query.py` | Early in-memory artifact query helper. | Reusable for tests; governed retrieval moves into `KONT-WP-0007`. |
|
|
| `workflows.py` | Early operation run and manifest contracts. | Reusable as a stepping stone; workflow services and run persistence move into `KONT-WP-0008`. |
|
|
| `context.py` | Early agent-facing context package helper. | Reusable as a facade; governed context packages move into `KONT-WP-0009`. |
|
|
| `storage.py` | In-memory repository for early artifacts. | Reusable for deterministic tests; durable repository begins in `KONT-WP-0005`. |
|
|
|
|
## Architectural Decisions Captured
|
|
|
|
- Asset identity is not derived from source path, filename, backend, or
|
|
representation.
|
|
- Source, normalized, and derived representations are separate records.
|
|
- Markitect snapshot IDs and adapter provenance belong in representation
|
|
metadata, not in engine identity.
|
|
- Actor context and correlation IDs are explicit inputs to material operations.
|
|
- Ambiguous permission state can be represented as `fail_closed`.
|
|
- Audit events carry actor, operation, target, outcome, correlation ID, and
|
|
optional policy decision.
|
|
- Derived artifact lineage carries source assets, source versions,
|
|
transformation run, actor, parameters, policy context, adapter provenance,
|
|
and output representation.
|
|
- Inferred metadata and confirmed metadata are distinguishable.
|
|
|
|
## Test Coverage
|
|
|
|
`tests/test_core_architecture.py` covers the first core contracts:
|
|
|
|
- stable asset identity across source movement,
|
|
- distinct source, normalized, and derived representations,
|
|
- explicit actor, policy, and audit context,
|
|
- derived output version and lineage explanation,
|
|
- inferred versus confirmed metadata records.
|
|
|
|
## Next Implementation Boundary
|
|
|
|
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`.
|