knowledge-centric-ai

Reference Implementation Architecture

This document maps the concepts and responsibilities described by Institutional Capability Lineage Architecture (ICLA) directly to the executable code in this reference implementation.

The paper defines the architecture. The sibling ../specification/ directory defines the artifact contracts. This package demonstrates that those contracts can be loaded, validated, connected, and transitioned without violating the architectural invariants.

It is intentionally a deterministic, file-based demonstrator rather than an enterprise platform. It requires no database, LLM, MCP server, cloud service, or distributed infrastructure.

Architectural flow

flowchart TD
    SPEC["Reference Specification<br/>schemas and artifact contracts"]
    REG["Registry Service<br/>stable capability identity"]
    RES["Resolution Service<br/>intent to admitted capabilities"]
    ASM["Assembly Service<br/>bounded operational mandate"]
    MAT["CEE-side Materialization<br/>local representation or access handles"]
    CEE["CEE autonomous interval<br/>local state, tools, coordination, iteration"]
    EVD["Evidence Gateway<br/>qualification and receipt"]
    GOV["Governance Service<br/>declared adjudication"]
    SUC["Succession Service<br/>append complete inactive successor"]
    FORM["Formation Service<br/>assign identity + metadata + relations + initial CKC"]
    ACT["Activation Service<br/>separate governed active-pointer transition"]
    LIN["Lineage Service<br/>connected typed trace"]

    SPEC --> REG
    REG --> RES
    RES --> ASM
    ASM -->|"mandate"| MAT
    MAT -->|"usable representation"| CEE
    CEE -->|"contract-selected evidence"| EVD
    EVD --> GOV
    GOV --> SUC
    SUC --> ACT
    GOV --> FORM
    FORM --> ACT
    ACT --> LIN

    ASM -. "exact versions" .-> LIN
    EVD -. "provenance" .-> LIN
    GOV -. "decision edges" .-> LIN

Materialization is a CEE-side projection boundary: an assembly remains logically valid independently of whether its policy-dependent local representation is a YAML bundle, workspace, payload, or governed access handles. The retained MAT record pins the assembly and CEE, versioned substrate and transformation, hash/access metadata, and evaluation/evidence bindings. The CEE box is an autonomous interval, not a step-wise service loop. Registry interaction resumes only when the mandate requires re-resolution or the CEE submits contract-selected evidence. Lineage is shown at the end of the main flow, but it is populated throughout the entire lifecycle.

Direct mapping from the paper to the code

This mapping is a traceability view over the iteratively refined artifact. It shows where declared architectural responsibilities become inspectable and executable; it does not claim that the implementation was mechanically or linearly derived from the literature.

Paper responsibility Executable responsibility Primary code
Reference Specification Load the canonical schemas from ../specification/schemas, resolve local $ref values, and validate artifacts src/icla/specification/
Organizational Memory Preserve governed source authority while annotating overlapping semantic, procedural, and episodic roles on CKC bindings and assemblies ckc.py, assembly.py
Institutional Capability Registry Preserve stable capability identity, relations, lifecycle, ownership, and active CKC pointers in immutable snapshots registry.py, registry_service.py
Capability Knowledge Contract (CKC) Represent immutable, versioned knowledge scope, obligations, evidence, evaluation, governance, projection rules, and source bindings ckc.py, ckc_repository.py
Operational Intent Capture goal, context, consumer, risk, budget, assurance, and required outcomes intent.py
Capability Resolution Perform candidate generation, relation expansion, filtering, constraint validation, and admission resolution_service.py
Contextual Assembly Bind exact versions, retain the RequiredCovered method and applicable validator, model, or review-policy version, and establish a bounded execution-scoped mandate assembly.py, assembly_service.py, mandate.py
Materialization Let the CEE adapt an immutable assembly to a versioned local substrate while retaining traceability, hash/access metadata, evaluation/evidence bindings, semantics, and authority bounds materialization_service.py
Capability Execution Environment (CEE) Record an execution-scoped situated boundary and the configuration needed for resolution, authorization, assurance, traceability, and evidence interpretation; operate autonomously inside the mandate and return only contract-selected evidence intent.py, evidence.py, conformance.py
Execution Evidence Separate governed from non-standard measurements, retain any versioned submitted-report transformation in provenance, check schema and provenance, and issue a qualification receipt evidence_gateway.py
Governance Persist an explicit institutional decision supplied by an authorized decision actor or mechanism without inferring institutional approval governance_service.py
CKC Succession Verify the decision-linked delta and append the complete successor as an inactive lineage version without moving the Registry pointer succession_service.py, ckc_repository.py
Governed Activation Activate an appended successor or initial CKC, or reactivate an eligible retained CKC, through a separately identifiable pointer transition; preserve unrelated Registry entries and the explicit no-predecessor boundary for initial activation activation_service.py
Lineage trace Build and validate a concrete connected, typed instantiation of the institutional capability lineage across artifacts and transitions lineage_service.py
Impact Analysis Identify source bindings, exact CKC versions, relation paths, retained assemblies, situated CEEs, and consumers that delimit review scope without directly invalidating or blocking canonical state impact_analysis_service.py
Capability Crystallization Validate a common pre-institutional proposal type; review identity-free proposed relations; execute governed identity assignment, approved metadata and Registry-relation update, and initial CKC append from a submitted proposal; activate the formed capability separately; preserve formation-origin links proposal.py, capability_formation_service.py, auth-evolution-formation/

Artifact flow

The reference flow transforms and appends artifacts; it does not mutate past meaning:

Operational Intent
    + immutable Registry Snapshot
    + active CKC pointers
        -> Resolution and Admission
        -> immutable Contextual Assembly
        -> Materialization or governed access handles
        -> autonomous CEE interval within the mandate
        -> contract-selected Execution Evidence Bundle
        -> Evidence Qualification Receipt
        -> declared Governance Decision
        -> inactive Successor Append Receipt
        -> separate Activation Record
        -> successor Registry Snapshot
        -> connected lineage trace

The complementary formation path is deliberately shorter because discovery and institutional review are declared inputs rather than synthesized behavior:

authorized supporting records
(unresolved intent, realized work, strategy,
 process analysis, onboarding, or pattern history)
        -> candidate proposal (no identity)
        -> submitted proposal
        -> authorized governance decision
        -> capability identity + approved metadata + Registry relations
        -> complete initial CKC v1 (inactive)
        -> separate initial activation
        -> active Registry snapshot

An assembly records the exact Registry snapshot and CKC versions used to build it. Activating a successor CKC changes future resolution; it does not rewrite a retained assembly or reinterpret historical evidence.

The worked example begins with the same rule applied before OAuth resolution: CHG-IDENTITY-POLICY-008 reaches CAP-IAM through its governed source binding, traverses the declared Registry relation neighborhood, and produces IMP-IAM-008. Governance authorizes DELTA-IAM-007-008 in DEC-IAM-008, APPEND-IAM-008 adds the complete CKC-IAM v8 without changing the pointer, and ACT-IAM-008 makes that appended version current only for later resolutions. ASM-IAM-HIST-007 remains pinned to v7. The nested history lives in capability-registry.yaml; no additional principal object or schema is needed for this reference fixture.

Organizational memory roles

The implementation represents semantic, procedural, and episodic memory as overlapping functional annotations on governed sources, not as physical stores or mandatory CKC partitions:

source_bindings declare the roles a source may play. source_snapshot and knowledge_role_composition record which authorized elements entered an assembly. The CEE consumes this governed memory and may produce new situated knowledge during execution. Evidence preserves the producer and execution identity and creates an episodic lineage record; adjudication may retain it as a precedent, update a governed source binding, or authorize a successor CKC that turns an accepted lesson into a semantic or procedural commitment.

Service responsibilities

Registry Service

The Registry Service is the navigation boundary over an immutable Registry snapshot. It retrieves capabilities, filters them by institutional metadata, traverses typed relations, and resolves active CKC pointers. Stable capability identity remains separate from versioned capability knowledge.

Resolution Service

Resolution turns an operational intent into a traceable admission result using three explicit stages:

  1. Candidate generation from required outcomes.
  2. Graph expansion through Registry relations.
  3. Constraint validation for lifecycle and authorization.

The output records the selected exact capability-to-active-CKC map, exclusions, rationale, matcher identifier and version, explicit confidence semantics, and one of the paper’s admitted, rejected, or escalated outcomes. The exact map is nonempty for an admitted outcome; rejected or escalated outcomes may have an empty selection. The reference matcher discloses qualitative, non-calibrated ranking rather than presenting its scores as probabilities. Discovery does not grant authority: only an admitted resolution may proceed to assembly.

Assembly Service

Assembly combines the intent, resolution, immutable Registry snapshot, exact CKC versions, policy references, source bindings, evaluation contracts, and evidence contracts. It refuses to produce an assembly unless these conditions hold:

The assembly correctness trace identifies the method applied to RequiredCovered and the applicable validator, model, or review-policy version. The reference path is deterministic; the schema also represents model-assisted and human-reviewed assessments without treating them as equivalent to automated validation. ConflictsResolved separately retains each applicable conflict, its assembly-compatible outcome, and the governing policy identifier and version; unresolved conflicts prevent assembly admission without prescribing a particular resolution mechanism.

The resulting assembly is authorized input to a CEE, not a claim that the CEE’s later observations or outputs are already institutional knowledge. It also records the limits of delegated authority, permitted local autonomy, evidence-disclosure boundary, and explicit re-resolution triggers.

Materialization Service

Materialization makes the mandate usable without changing it. The CEE or its sidecar infrastructure controls the local representation; there is no institutional delivery service that owns or authorizes the payload. The representation and its retention are policy-dependent and CEE-controlled. The reference implementation supports YAML bundles, workspaces, and governed access handles. Each MAT record retains the immutable assembly and CEE references, versioned substrate and transformation, representation metadata, content hash, expiry/access metadata, evaluation/evidence bindings, and explicit semantic and authority preservation. Access handles avoid copying source payloads while preserving their governed authority descriptors.

Materialization does not initiate a step-wise control loop. The CEE may reuse the admitted mandate until intent, coverage, authority, freshness, risk, or assurance changes enough to require re-resolution.

Evidence Gateway

The Evidence Gateway validates contract-selected CEE evidence and candidate knowledge before governance review. It verifies schema conformity, governed measurement conformity, producer and execution provenance, and provenance completeness. It keeps governed and non-standard measurements distinct and returns a receipt. If the submitted report was constructed through a versioned transformation, the evidence lineage retains its identifier and version. This reference is conditional and does not imply that every evidence submission uses a report transformation. Qualification means eligible for review; it is not approval or institutional admission. Transformation traceability and schema conformity do not establish semantic fidelity, substantive correctness, or evidential sufficiency, and impact identification alone does not invalidate a CKC or block admission. Internal reasoning, working memory, local stores, and intermediate artifacts remain outside submission unless the evidence contract selects them.

Governance, Succession Append, and Activation

Governance records an explicit institutional decision supplied by an authorized decision actor or mechanism. The implementation persists the declared outcome; it never synthesizes or infers institutional approval from evidence.

Successor append and activation are intentionally different services and operations:

qualified evidence -> governance decision -> complete successor append (inactive) -> activation

An approved decision alone does not mutate the Registry. The Succession Service verifies the target capability, exact predecessor, decision status, and delta recording changed CKC commitments, supporting evidence, rationale, authorizing decision, and rollback. It appends the complete immutable successor—not a reconstruction patch—only when that predecessor is still the latest appended CKC. A stale predecessor is rejected without creating a canonical branch or moving the active pointer; no locking strategy is prescribed. A successful append emits an inactive-successor receipt. The logical activate_ckc port accepts an appended lineage CKC for either succession or formation. Activation verifies the exact append reference and pointer transition, then returns a new Registry snapshot and a separate activation record. For an initial CKC, the transition is explicitly no pointer -> CKC v1; there is no invented predecessor or rollback target. Formation and activation use separate service calls even when one governance transaction authorizes both effects. An eligible retained CKC may also be made current through a new approved reactivation decision; the prior successor decision is not reused. Every activation copies the Registry snapshot and changes only the target capability’s active pointer and applicable lifecycle metadata, preserving all unrelated entries.

Lineage Service

Lineage connects intent, resolution, admission, exact CKC and source versions, assembly, materialization, execution, evidence, governance, activation, and CKC succession through typed edges such as:

The service can validate that a capability trace is connected and can traverse the graph from an execution or evidence identifier. These links belong to the broader capability lineage; Registry relations remain capability-to-capability edges and are validated independently.

Code layers

src/icla/
├── models/          Specification-aligned information model
├── specification/   Schema loading, structural validation, conformance
├── policies/        Explicit and replaceable institutional rules
├── repositories/    Persistence boundaries without domain decisions
├── storage/         Local YAML, append-only records, immutable snapshots
├── services/        Architectural operations and transitions
├── api/             Technology-neutral ports and public facade
└── cli.py           Verification-oriented command-line interface

Dependencies point inward: the CLI and facade invoke services; services operate on models and explicit policies; repositories hide storage. Storage mechanisms do not decide authorization, admission, governance, or activation.

Invariants demonstrated by the implementation

The conformance layer and tests make the main paper invariants executable:

Invariant Demonstrated property
ICLA-1 Every active capability has stable identity, owner, lifecycle, and a governed active CKC pointer
ICLA-2 Canonical CKCs declare immutable knowledge, operational relations, obligations, authorities, evidence, evaluation, source, and projection contracts, including metric interpretation and representative-case or coverage bases
ICLA-3 Every execution records its situated CEE boundary and relevant configuration; autonomy and working-state privacy remain bounded, and candidate contributions gain authority only through governed adjudication
ICLA-4 Registry entries are filterable by metadata, lifecycle, policy, and conditions and expose typed relations and source-impact paths
ICLA-5 Resolution and assembly retain intent, situated CEE boundary and configuration, Registry snapshot, matcher identity/version, confidence semantics, selected capability set, exact capability-to-active-CKC map, one of the admitted/rejected/escalated outcomes, and mandatory-constraint traceability; admitted selections are nonempty, RequiredCovered retains its method/version, and ConflictsResolved retains conflict, compatible outcome, and policy/version basis
ICLA-6 Assemblies pin exact CKC, evaluation-contract, source, policy, and projection-transformation versions without incorporating later realization state
ICLA-7 Every CEE-side materialization traces to its immutable assembly and CEE and preserves the assembly’s semantics and authority bounds while adapting only the local representation
ICLA-8 Governed and non-standard measurements remain separate, receipts originate at the Evidence Gateway, schema conformity remains distinct from evidential sufficiency, and any submitted-report transformation is version-referenced in provenance
ICLA-9 Impact identifies review scope without automatic invalidation; canonical succession requires the latest appended predecessor and rejects stale-predecessor branching; successful change retains the complete successor, decision-linked delta, inactive append, separate pointer transition, and historical immutability; any eligible retained CKC reactivation requires a new approved decision and preserves unrelated pointer mappings
ICLA-10 A retained execution trace identifies its CEE-side materialization and retains versioned substrate/transformation, hash/access, and evaluation/evidence bindings needed for reproduction and interpretation; authorized disposal remains outside the companion operation set
ICLA-11 Candidate and submitted proposals remain identity-free and their lifecycle states cannot be assigned to institutional capabilities; supporting records are general rather than pattern-only and retain resolvable repository, locator, version, and provenance metadata; proposed relations remain identity-free; governed formation records approved metadata and proposal-traceable capability relations, creates one new identity and complete initial CKC v1 with retained origins; the formed state has no active pointer; initial activation is executed separately

The corresponding tests live in tests/conformance/. The complete evidence mapping, including the clauses that remain governed judgments, is maintained in the conformance-matrix.md companion artifact. The end-to-end oauth-042 test loads the published sibling artifacts, applies ICLA-Governed checks to the implemented resolution-to-succession scope, verifies event-linked impact analysis and the separate ICLA-11 candidate-proposal boundary, generates the declared evidence receipt, records adjudication, appends the published successor CKC without activating it, then performs the separately authorized activation with its exact rollback target, preserves the historical assembly snapshot, and verifies connected lineage without creating a new capability.

The end-to-end auth-evolution-formation test replays the published history-driven before -> formed -> active snapshots, verifies exact proposal/decision/CKC/supporting-record lineage, demonstrates that prospective strategic, unresolved-intent, and onboarding references are also admissible, and rejects candidate, unauthorized, duplicate, incomplete, unappended, and repeated promotion attempts without partial state.

Scope boundary

This implementation demonstrates executable consistency with the declared architectural behavior; it does not prove organizational effectiveness or production readiness. The linked OAuth trace is a constructed demonstration. Schema validation, deterministic replay, negative cases, and invariant checks provide artificial technical evaluation within the stated succession and governed capability- formation paths. Comparative longitudinal evaluation is prospective, and independent organizational validation remains future work. Authentication infrastructure, distributed transactions, databases, REST or MCP transports, observability platforms, and human workflow systems remain outside its scope. They may be added behind the existing ports without changing the semantics of resolution, assembly, evidence, governance, activation, or lineage.

This site is open source. Improve this page.