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:

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.

3.5 KiB Raw Blame History