Appendix C: Reference Implementation

Implementing the Autonomous State Control Plane as a modular, adapter-based governance runtime establishes a control boundary between AI-generated intent and domain-specific execution systems. This reference implementation makes the architecture executable while decoupling core governance from specific model providers, policy engines, or cloud backends.

This appendix provides a reference implementation blueprint for OpenKedge and related components. Rather than serving as an exhaustive operations manual, it defines the core runtime interfaces, TypeScript specifications, adapter boundaries, evidence structures, and deployment topologies required to translate these architectural concepts into functional code.

Implementation Goals

The reference implementation aligns the main runtime responsibilities: agents propose intents, OpenKedge evaluates them against policy, adapters enforce execution contracts, and evidence is recorded automatically. The system governs structured intents rather than dynamic prompts; while prompts direct probabilistic reasoning, they are unsuitable as stable governance artifacts. The primary runtime primitive must be a structured, verifiable intent.

For compatibility, the control plane uses established policy engines rather than introducing a proprietary policy language. A unified policy-engine interface integrates with engine runtimes such as Cedar and OPA/Rego, alongside custom or legacy validators. OpenKedge normalizes intents and context snapshots into policy-evaluable inputs, translating engine responses into deterministic decisions.

The architecture accommodates multiple operational domains. Cloud infrastructure management serves as an ideal baseline deployment due to its mature identity frameworks and deterministic resource APIs. The same interface boundaries govern Kubernetes resources, workflow engines, database migrations, serverless functions, case management systems, and smart-city control adapters.

Every decision path, including denials, constraints, simulations, and escalations, should emit evidence. Negative paths matter for auditability because they show active security enforcement.

Replayability requires that past decisions be reconstructable from the evidence chain regardless of inference non-determinism. Replay verifies the intent, context snapshot, policy decision, contract parameters, and derivative identity from the immutable log, bypassing the need to invoke the original reasoning model.

Execution authority relies on short-lived contracts. Rather than granting agents standing credentials, the runtime generates task-specific execution contracts, derives scoped identity tokens, and requires adapters to validate these contracts before executing mutations. Conforming implementations remain modular, enabling organizations to deploy local, private, or sovereign nodes without external SaaS dependencies.

Component Architecture

The reference architecture uses component boundaries to enforce modular decoupling. While the reasoning client generates candidate plans, it receives no direct execution authority. The IntentTranslator processes natural language or model outputs to produce an IntentCandidate which the IntentGateway then validates and normalizes before evaluation. The IntentTranslator resides outside the trusted computing base (TCB); its output remains untrusted until validated.

The orchestration logic resides in the governance engine, which coordinates context acquisition, policy evaluation, risk classification, and contract generation. The contract issuer produces a signed, bounded execution contract that defines the parameters and validity window of the operation. The identity broker then transforms the contract into a short-lived execution identity, which the execution adapter consumes to perform the mutation. All transitions emit structured evidence to the evidence store for verification.

This component model should remain small enough for an open-source implementation to be understandable, testable, and extensible. The goal is not to build a monolith. The goal is to define a stable governance path from proposed intent to bounded execution and replayable evidence.

Core Interfaces

TypeScript interfaces formalize these structural boundaries: translation must not be confused with validation, intent is decoupled from context, context remains separate from policy, and contracts bind derivative execution identity.

Core TypeScript interface families should cover intent translators, intents, context providers, policy engines, governance decisions, execution contracts, identity brokers, execution identities, execution adapters, evidence events, evidence stores, replay engines, protocols, and admission results. The concrete names are illustrative, but the implementation should preserve the separation of responsibility: translation is not validation, intent is not context, context is not policy, policy is not contract, contract is not identity, identity is not execution, and execution is not evidence.

interface IntentTranslator {
translate(input: ReasoningOutput): Promise<IntentCandidate>
}
interface Intent { ... }
interface ContextProvider {
collect(intent: Intent): Promise<ContextSnapshot>
}
interface PolicyEngine {
evaluate(input: PolicyInput): Promise<GovernanceDecision>
}
interface ContractIssuer {
issue(intent, context, decision): ExecutionContract
}
interface IdentityBroker {
derive(contract): Promise<ExecutionIdentity>
}
interface ExecutionAdapter {
execute(contract, identity): Promise<ExecutionResult>
}
interface EvidenceStore {
append(event): Promise<void>
}
interface ReplayEngine {
replay(chainId): Promise<ReplayResult>
}

interface IntentTranslator {
translate(input: ReasoningOutput): Promise<IntentCandidate>;
}

interface IntentCandidate {
rawInputRef: string;
proposedIntent: Partial<Intent>;
confidence?: number;
assumptions?: string[];
}

An intent candidate is untrusted until validation succeeds. Validation of the intent candidate at the gateway enforces structural completeness, schema correctness, and objective-action consistency. Each valid intent is bound to a unique chain identifier, enabling cryptographic correlation of all subsequent context snapshots, policy decisions, contracts, and execution events.

Conforming implementations must define rigorous conformance tests. Policy engine adapters must guarantee deterministic decision translation, execution adapters must reject actions that fall outside the contract bounds, and replay engines must detect evidence omission.

All schemas and interfaces are explicitly versioned. Structural specifications for intents, contracts, and evidence payloads must support backward compatibility, while allowing domain-specific schema extensions that do not weaken the core invariants. Adapters declare supported contract and evidence versions, enabling the governance engine to reject execution paths if an adapter lacks the capacity to enforce the active contract.

Intent Schema

Intent is the boundary artifact between reasoning and governance. The intent schema should be expressive enough to support policy evaluation, but narrow enough to prevent arbitrary model output from becoming authority. It should make the proposed action explicit, bind it to an actor and source, describe the objective, define the target and scope, capture assumptions and constraints, include justification, and carry creation and expiration metadata.

Reference fields should identify the intent, actor, source, objective, requested action, target, scope, assumptions, constraints, justification, risk hint, creation time, expiration time, and metadata. Implementations may add domain fields, but the governance engine should not accept unbounded model text as executable input. The illustrative schema below shows one compact representation.

{
"intentId": "intent-123",
"actor": "ops-agent",
"source": "external-reasoning-client",
"objective": "restore checkout service health",
"requestedAction": "shift_traffic",
"target": "service.checkout",
"scope": {
  "region": "us-west-2",
  "maxPercentage": 20
},
"assumptions": [
  "current_error_rate_above_threshold",
  "secondary_capacity_healthy"
],
"constraints": {
  "expiresIn": "10m",
  "requirePostVerification": true
},
"justification": "Reduce elevated 5xx rate by shifting traffic.",
"riskHint": "medium"
}

Intent validation should reject missing actors, ambiguous targets, expired requests, broad scopes without justification, unsupported requested actions, and mismatches between objective and requested action. It should also attach a chain identifier so later context, policy, contract, identity, execution, and verification events can be correlated.

Context Provider Interface

Context providers turn operational state into policy-evaluable evidence. They may retrieve cloud resource state, topology, health metrics, current traffic, ownership metadata, resource tags, compliance state, policy metadata, change windows, incident state, deployment state, and previous related intents.

Context collection should be scoped to the intent. A provider should gather the facts needed to evaluate the proposed action, not export broad operational state to the reasoning layer. Context should include provenance, freshness timestamps, source identifiers, and uncertainty. Missing context should be explicit. A governance engine should be able to distinguish between a confirmed safe condition, a confirmed unsafe condition, and an unknown condition.

interface ContextProvider {
name: string;
supports(intent: Intent): boolean;
collect(intent: Intent): Promise<ContextSnapshot>;
}

interface ContextSnapshot {
snapshotId: string;
collectedAt: string;
sources: ContextSource[];
facts: Record<string, unknown>;
freshness: Record<string, string>;
}

Context snapshots should be stored or referenced as evidence. Replay depends on knowing which facts were available at decision time and how fresh they were. For high-risk execution, adapters may perform a final context revalidation immediately before action.

Policy Engine Interface

OpenKedge is not a replacement for policy engines; it is the substrate that makes autonomous intent evaluable by them. The policy layer should support Cedar, OPA/Rego, institutional approval systems, custom validators, and domain-specific rules through a common adapter shape.

Policy input should include the intent, context snapshot, actor, resource, requested action, risk classification, and evidence references. Policy output should include a normalized decision, constraints, reasons, required approvals, required evidence, policy version, and obligations. The governance engine should treat the policy output as an input to contract issuance, not as executable authority by itself.

type DecisionKind =
| "allow"
| "deny"
| "constrain"
| "escalate"
| "simulate"
| "defer"
| "request_context";

interface PolicyEngine {
name: string;
evaluate(input: PolicyInput): Promise<GovernanceDecision>;
}

interface GovernanceDecision {
decisionId: string;
kind: DecisionKind;
reasons: string[];
constraints?: Record<string, unknown>;
obligations?: EvidenceObligation[];
policyVersion?: string;
}

Policy adapters should preserve policy provenance. A replay engine must know which policy set, version, bundle, approval workflow, or validator produced the decision. If the policy engine returns uncertainty or missing context, OpenKedge should request context, defer, escalate, or deny rather than convert uncertainty into permission.

Execution Contract Schema

The execution contract is the machine-enforceable bridge between governance and runtime authority. It converts a policy decision into a bounded artifact that an identity broker and execution adapter can verify.

Reference fields should identify the contract, intent, policy decision, approved action, target, bounds, constraints, validity interval, identity scope, evidence obligations, revocation conditions, rollback plan, and integrity metadata. The contract should be precise enough that an adapter can decide whether a requested runtime action is inside or outside the approved bounds.

{
"contractId": "contract-456",
"intentId": "intent-123",
"decisionId": "decision-789",
"approvedAction": "shift_traffic",
"target": "service.checkout",
"bounds": {
  "region": "us-west-2",
  "maxPercentage": 20
},
"validUntil": "2026-05-18T18:00:00Z",
"identityScope": {
  "actions": ["traffic:Shift"],
  "resources": ["service.checkout"]
},
"evidenceObligations": [
  "pre_context_snapshot",
  "policy_decision",
  "identity_issuance",
  "execution_result",
  "post_verification"
]
}

Contract issuance should be deterministic with respect to recorded intent, context, and decision. If replay reconstructs the same inputs under the same policy version, it should be able to verify that the contract was consistent with the decision.

Execution Identity Interface

The identity broker derives execution identity from an approved contract. The identity broker should never issue authority broader than the execution contract. Implementation patterns include short-lived cloud credentials, session policies, signed capability tokens, workload identity federation, workflow-scoped credentials, and sandbox capabilities.

interface IdentityBroker {
derive(contract: ExecutionContract): Promise<ExecutionIdentity>;
revoke(identityId: string, reason: string): Promise<void>;
}

interface ExecutionIdentity {
identityId: string;
contractId: string;
issuedAt: string;
expiresAt: string;
scope: IdentityScope;
materialRef: string;
}

The materialRef field should avoid storing sensitive credential material directly in evidence. Evidence should record that authority was issued, what scope it represented, which contract justified it, and when it expired. Secrets should remain in the institution's credential management system or runtime secret store.

Identity issuance should fail closed. If the contract is expired, unsigned, inconsistent with the decision, missing evidence obligations, or broader than policy allows, the broker should refuse issuance and emit an evidence event.

Execution Adapter Interface

Execution adapters enforce contracts rather than executing unstructured instructions. Each adapter maps the contract boundaries to specific infrastructure API mutations. The preflight interface verifies context freshness, resource availability, and contract integrity; the execute method executes the mutation under the short-lived identity; and the verify method validates postconditions and records runtime outcomes. An adapter must reject parameters, resources, or actions not explicitly permitted by the contract even if the identity token is valid.

interface ExecutionAdapter {
name: string;
supports(contract: ExecutionContract): boolean;
preflight(
  contract: ExecutionContract,
  identity: ExecutionIdentity
): Promise<PreflightResult>;
execute(
  contract: ExecutionContract,
  identity: ExecutionIdentity
): Promise<ExecutionResult>;
verify(
  contract: ExecutionContract,
  result: ExecutionResult
): Promise<VerificationResult>;
}

The preflight method checks context freshness, contract validity, identity scope, and feasibility. The execute method performs the bounded action. The verify method checks postconditions, records outcomes, and emits evidence. An adapter should reject parameters, resources, or actions not explicitly permitted by the contract even when the identity token appears valid.

Evidence Chain Interface

Every meaningful governance transition should emit an evidence event. Reference event types should cover intent receipt, context collection, policy evaluation, contract issuance, identity issuance, execution start, execution completion, execution denial, contract violation, verification completion, replay completion, and admission evaluation.

intent.received
context.collected
policy.evaluated
contract.issued
identity.issued
execution.started
execution.completed
execution.denied
execution.violated
verification.completed
replay.completed
admission.evaluated

interface EvidenceEvent {
eventId: string;
chainId: string;
type: string;
timestamp: string;
subject: {
  intentId?: string;
  decisionId?: string;
  contractId?: string;
  identityId?: string;
  executionId?: string;
};
payloadHash?: string;
payloadRef?: string;
previousEventHash?: string;
metadata?: Record<string, unknown>;
}

interface EvidenceStore {
append(event: EvidenceEvent): Promise<void>;
getChain(chainId: string): Promise<EvidenceEvent[]>;
}

Implementations may use hash chains, signatures, append-only logs, or trusted ledgers depending on assurance requirements. The reference implementation should begin with a simple evidence store that is easy to inspect and replay, then allow stronger storage backends as deployments mature.

Evidence storage should also support retention policy, access control, and redaction patterns. Some payloads may contain sensitive operational details, so the evidence event can store a payload hash and reference while keeping the full payload in a protected system. The replay engine should be able to retrieve authorized payloads when needed, but routine audit views should expose only the minimum detail required for review. This keeps the implementation evidence-first without turning the evidence store into an uncontrolled data lake.

Replay and Simulation Interface

Replay is the mechanism that turns evidence into operational learning. The replay engine should reconstruct intent, context, policy decision, contract, identity issuance, execution, and verification. Replay modes should include exact replay under recorded policy and context, policy replay under updated policy, what-if simulation with alternate context, incident replay, and certification replay.

interface ReplayEngine {
replay(
  chainId: string,
  options?: ReplayOptions
): Promise<ReplayResult>;
simulate(
  intent: Intent,
  scenario: SimulationScenario
): Promise<SimulationResult>;
}

interface ReplayResult {
chainId: string;
reconstructedDecision: GovernanceDecision;
contractValid: boolean;
identityWithinContract: boolean;
executionWithinContract: boolean;
evidenceComplete: boolean;
findings: ReplayFinding[];
}

Replay findings should be actionable. They should identify missing context, missing policy versions, contract inconsistencies, overbroad identity, execution outside the contract, incomplete verification, or evidence gaps. Replay should be usable by engineers, auditors, incident responders, and policy owners.

Protocol Admission Interface

Generated code enters the system through admission, not trust. The PDD layer should provide a protocol registry, candidate artifact submission, invariant evaluators, admission pipeline, sandbox execution, and evidence output. Admitted artifacts can later be referenced by execution contracts and evidence chains.

Type-theoretic admission affects this interface design. A protocol registry may expose machine-checkable schemas, typed interfaces, refinement predicates, effect constraints, and resource bounds. Invariant evaluators may include type checkers, schema validators, refinement checkers, dependency analyzers, effect checkers, and sandbox tests. Admission evidence should record which checks passed, which checks failed, and which properties were unknown or deferred to runtime verification.

interface Protocol {
protocolId: string;
version: string;
structuralInvariants: Invariant[];
behavioralInvariants: Invariant[];
operationalInvariants: Invariant[];
}

interface AdmissionPipeline {
evaluate(
  candidate: CandidateArtifact,
  protocol: Protocol
): Promise<AdmissionResult>;
}

interface AdmissionResult {
resultId: string;
kind: "admit" | "reject" | "constrain" | "review";
evidence: AdmissionEvidence[];
findings: string[];
}

interface TypeCheckResult {
artifactId: string;
protocolId: string;
judgment: "inhabits" | "rejects" | "unknown";
evidence: AdmissionEvidence[];
}

The initial PDD implementation should prioritize generated automation scripts, execution adapters, policy modules, and workflow definitions. These artifacts can affect the governance path directly and should not become operational simply because they compile or pass a few examples.

Advanced implementations of the symbolic governance layer can draw upon foundational work in refinement types [2], dependent types [3], and typed effect systems [4] to formally bound the behavior of generated code.

AWS Adapter Example

The AWS execution adapter provides a practical demonstration of intent governance applied to real-world cloud infrastructure. When an AI agent proposes EC2 instance termination for auto-recovery, the control plane intercepts the request. The gateway structures the intent, context providers gather instance metrics and Auto Scaling state, and the policy engine verifies safety bounds. The contract issuer then emits a tightly bounded contract, STS generates a task-scoped credential, and the adapter deregisters the instance, executes the drain, terminates the resource, and verifies replacement health.

The adapter validates all actions against the contract; it does not accept arbitrary API commands. Real-world AWS implementations leverage STS session policies [1], scoped IAM roles, and Config rules to enforce bounds.

Early adapter iterations should focus on a narrow, well-tested set of remediation operations. The objective is to establish an end-to-end integration path that verifies context acquisition, contract generation, transient credentials, and evidence collection before expanding the API surface.

Repository Structure

A monorepo structure segregates the core governance logic from domain-specific extensions. The core package implements validation, decision normalization, contract logic, and evidence parsing. Adapter packages integrate with external clouds and policy engines, while pdd manages type-theoretic admission.

Deployment Modes

Conformant deployments scale from local verification to enterprise and sovereign runtime environments. Local development mode utilizes SQLite and mock adapters for rapid prototyping; enterprise mode integrates with native IAM, change management, and internal telemetry; sovereign mode provides strict air-gapped isolation with offline reasoning and strict data residency controls.

In local development mode, the system can use a file-backed or SQLite evidence store, mock policy engine, mock execution adapter, and replay CLI. This mode is useful for demos, tests, protocol experimentation, and contributor onboarding.

In enterprise mode, the system is deployed inside the institution's infrastructure. It integrates with existing IAM, policy systems, observability, CI/CD, incident management, and audit tooling. Evidence is retained internally according to institutional retention policy.

In sovereign mode, the system runs in a national, regulated, or high-assurance environment with strict data and context boundaries, local policy ownership, controlled model integration, and long-term evidence retention. External reasoning may be allowed, but execution authority remains inside the sovereign control plane.

In air-gapped or restricted mode, the system can use local models or approved offline reasoning, a local evidence store, manual policy updates, and restricted adapter access. This mode is relevant when external model calls, hosted control planes, or remote telemetry are not permitted.

Implementation Roadmap

The development roadmap prioritizes end-to-end loop integration over API breadth. Early milestones demonstrate core validation and replay capabilities (v0.1-v0.2) before expanding to native cloud integration (v0.3), protocol admission (v0.4), and production-grade API stability (v1.0).

Version 0.1 should include the core intent schema, governance decision model, evidence event model, simple file or SQLite evidence store, mock policy engine, mock execution adapter, and replay CLI. This creates the minimum visible loop.

Version 0.2 should add OPA and Cedar adapters, AWS read-only context providers, execution contract issuer, and a basic replay UI. This stage should focus on policy-engine pluggability and context evidence.

Version 0.3 should add the AWS execution adapter, STS or session-policy identity broker, CloudWatch or CloudTrail integration, and an outage-prevention demo. This stage should demonstrate a real bounded action with evidence and replay.

Version 0.4 should add the PDD protocol registry, generated-code admission pipeline, sandbox execution, and CI/CD integration. This stage brings generated artifacts into the governance boundary.

Version 1.0 should stabilize APIs, document production deployment patterns, harden security controls, define adapter certification tests, verify evidence chains, and ship reference demos and contributor documentation.

This reference implementation is intentionally modular. The goal is to demonstrate how the architectural invariants can be enforced in real systems while allowing institutions to retain their own policy engines, identity systems, cloud providers, and evidence stores.