Architecture core for Knowledge Assets

docs/architecture-core-implementation.md

@@ -0,0 +1,93 @@
+# 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 should build on these contracts rather than reusing the old
+artifact model directly. The natural next step is `KONT-WP-0005`: asset
+registry governance and durable state.
+