kontextual-engine/docs/architecture-core-implementation.md

# 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`.