kedgeflow

KedgeFlow

KedgeFlow proposes component boundaries and programmable interfaces for control over consequential agent actions. An existing agent workflow proposes an exact action; independently administered control services admit it and issue bounded authority; an Execution Gateway and Resource Adapter enforce the protected effect.

This repository contains the Rust 0.9.0-alpha.1 reference implementation, a Node Agent Adapter, and the preserved language-independent KF-JSON-0.2 schemas and signed fixtures. The Python 0.1.0a1 package is a separate legacy demo. The protocols remain proposed; the Rust services implement a bounded single-action profile, with additional M6d2b/M6d3a and M7a/M7b/M7c/M7d1/M7d2/M8a/M8b1/M8b2/M8c1/M8c2/M8c3/M8c4/M8c5/M8d1/M8d2a/M8d2b1/M8d2b2a/M8d2b2/M8d3a/M8d3b/M8d3c/M8d3d/M8d3e/M9a software prerequisites as of 17 October 2026. These add pinned SQL peer transport, logical restore rehearsal, native reviewed evidence/static leases, reservation libraries, native fixed-cost leaf reservations with signed history/refinement, authenticated A2A root-reference views, audited static hierarchical authority, shared family budgets with live narrowed delegation, core A2A family tasks, durable query-only saga observations, native forward-DAG authority, signed inverse-proof qualification, paired exact action controls, actual SQL compensation with SDK execution and complete bounded lineage, inverse crash/recovery qualification, and a conformance runner. Enterprise acceptance, physical storage/restore qualification and release conformance remain open.

The white paper v0.9 was frozen on 6 October 2026. Its schema and all 22 shared fixture files remain byte-identical. The milestone plan tracks delivered increments and release gates; remaining enterprise work identifies the inputs needed to proceed. RFCs 0001–0054 are engineering drafts, and the profile index distinguishes implemented draft bindings from proposed and legacy contracts.

RFC 0054's multi-contract saga proposal now has strict protected-plan, owner-intent and complete native-inventory validation. Its execution profile is disabled while native global phases, atomic capture, the multi-contract runner and aggregate checkpoint are unfinished. M8 remains open.

flowchart LR
  W[Existing agent workflow] --> AA[Agent Adapter]
  AA --> AC[Admission Controller]
  PA[Policy Authority] --> AC
  RR[Resource Registry] --> AC
  EP[Evidence Provider] --> AC
  AC --> GA[Grant Authority]
  GA -->|exact signed grant| AA
  AA -->|governed tool call| EG[Execution Gateway]
  GA -->|authority ledger and revocation| EG
  EG --> RA[Resource Adapter]
  RA --> T[Protected target]
  EG --> OS[Outcome Service]
  RA -->|correlated outcome| OS

Implementation state

Area	Implemented and tested	Limits and remaining acceptance
Records and execution	Closed integer-only canonical JSON, Ed25519 signatures and digests; authenticated Model Context Protocol (MCP) discovery/remediation/calls under KF-MCP-0.1 and revision 2026-07-28; atomic etcd issuance, replacement, claim, dispatch and outbox	One-resource leaf profile described below; target effects remain outside ledger transactions
Admission and control (M2)	Signed proposal/descriptor/manifest/evidence verification, Cedar evaluation, constrained certificates, operation-wide issuance deduplication, issuer-owned IDs/nonces/fences; native admission/issuer and signed administration/install/revoke services with gateway acknowledgements	Approved policy/provider pins, production enrollment/RBAC, broader component coverage, counter bootstrap and migration
Agent integration (M3a–M3b)	Node Agent Adapter with official MCP client 2.3.0, fresh admission/issuance, grant persistence before execution, retained attempt status and signed-proposal lookup after ambiguous replies	Mock or named PostgreSQL action; real evidence providers, power-loss storage and crash-lock recovery remain unqualified
Outcomes and history (M4a–M4b4)	Query-only recovery, signed receipts, authenticated collector, durable acknowledgements; offline admission lineage, governance history and control-binding verification	Observer/ledger correctness, clock and historical key custody remain trusted; verification does not establish actual target effects
Failure handling (M4c1–M4c3)	Nine shipping-binary process kill/restart cases; independent write-ahead restore quarantine; owned unknown incidents and ordered automatic delivery	Same-host software fixtures; pending-witness repair, migration, physical failure domains, external incident routing and combined managed restore deployment remain open
Identity and credentials (M5a–M5c3)	Optional shared DPoP replay/registration; original-claim broker authorization; subject/JWT-SVID signatures; native one-shot token exchange and separately verified reference target token; per-exchange signed identity refresh with live key rotation and rollback refusal	Actual AS/SVID provisioning, publisher administration, independent head/floor custody, production credential/RBAC/bypass controls and provider-specific target tokens remain open; native SQL verifies its reference token
PostgreSQL storage (M6a)	Conditional reservation update, atomic version/incarnation/fence checks, retained attempt/root/grant deduplication and query; real PostgreSQL concurrency, rollback, replay, missing-status and restart tests	M6b1 supplies the native target/query and M6b2 connects the fresh signed leaf path; production writer/bypass/restore qualification remains open
Native PostgreSQL target (M6b1)	Authenticated target/query service, fixed Unix-socket driver, explicit COMMIT acknowledgement, independent signed grant/reference-token checks, fixed adapter client and shipping process restart	Six target tests use generated preissued authority; M6b2 adds fresh admission/issuer/native broker/SQL recovery composition
PostgreSQL leaf binding (M6b2)	Named SQL action, exact CTD schema, explicit gateway adapter, official Node client, native broker/SQL commit and lost-target-reply recovery	Disposable same-host SQL and generated identity/evidence; M6c adds bounded crash/restore/incident composition; enterprise acceptance remains open
SQL failure qualification (M6c)	Eleven combined cases: shipping gateway/broker/target/recovery/supervisor kills, witnessed quarantine, retained incidents and signed collector acknowledgements	Stopped logical ledger restore only; pending repair, stale SQL backup/storage loss, deployed custody/writer coverage and independent collector storage remain open
SQL enrollment (M6d1)	Shared runtime/preflight check: standalone function roles, effective column/PUBLIC grants, membership/delegation, database ownership/CREATE and admin/replication refusal; explicit read-only --check-database	Catalog observation only; deployed OS/socket/peer and secret custody, administrator changes and enterprise acceptance remain open
SQL target custody (M6d2a)	Explicit protected-file loading, verified descriptor/mode snapshots, native custody check and real PostgreSQL peer-map negatives	Same-UID fixture; independent OS accounts, ACL/mount/socket administration, rotation, other service loaders and deployed agent bypass coverage remain open
SQL transport/restore prerequisites	Kernel peer pin before SQL bytes and fenced stale logical restore, external lost-commit history and storage budget; Linux separate-account CI harness	Linux account observation pending; all-service custody/rotation, physical restore/cutover/retention and accepted pilot open
Review integration (M7a/M7b)	Native review provider, closed signed evidence, server rendering and consumed challenge/enrollment comparisons in admission/issuance	Software authenticator, native revocation races and shipping crash/retry tested; browser/physical enrollment/hardware and frozen HITL open
Static leases and audit (M7c/M7d1/M7d2)	Exact-proposal prevalidation, retained static discharges, fresh JIT evidence and membership generation/CAS through native admission/issuance	Shipping crash/retry, withdrawal races and v0.2 historical lease verification tested; Node static-cache/JIT acquisition delivered; approved membership/provider lifecycle and hardware qualification open
Reservations (M8a/M8b1/M8b2)	Hierarchical capacity state and native fixed-cost leaf issuance/claim/dispatch; allocation shares the fence transaction and claim holds unknown with the original attempt	Opt-in v0.2 history and native signed-outcome refinement, contention, stop/receipt races and shipping SDK/CLI recovery tested; allowances stay held; separate family/task/saga profiles add higher-level bindings; complete multi-contract workflow/drain and enterprise acceptance remain open
A2A root views (M8c1)	Activated root-reference resolution, immutable reader ACL, narrowed action/resource views, pinned mTLS client and shipping control CLI	Read-only draft extension; no allocation or child execution authority; RFC 0053 adds core tasks and independent authority-peer acceptance remains open
Static hierarchical authority (M8c2/M8c3)	Signed nonexecutable composites and fresh leaf bindings, scoped identity assignments, atomic child-cost/issuance, original claim/dispatch and permanent stop; opt-in complete history and signed refinement	All issued leaves have independently replayed admission proofs; both allowances stay held; one fixed contract/static generation-one skeleton; dynamic delegation and enterprise acceptance remain open
Inverse SDK workflow (M8d3b)	Official MCP client through fresh inverse admission, native broker and real SQL restore; lost target reply and separate-process query-only restart after stop/expiry	One exact original contract/operation; no remint/resend/refund. Multi-contract runner, independent whole-saga and deployed acceptance remain open
Inverse SQL restore (M8d3e)	Real stale dump/restore with native consumed authority, fenced query-only copy, unchanged held costs and original unknown/committed receipts	Stopped local logical copy; historical compensation is distinct from restored live state. Physical cutover/custody, fresh deployment enrollment and accepted production restore remain open
Inverse failure recovery (M8d3d)	Shipping target SIGKILL before effect/after COMMIT and separate-witness stale authority quarantine; original query-only receipt and held costs	Local stopped logical authority rollback; physical inverse SQL restore, wider process/partial-failure matrix and independent/deployed acceptance remain open
Compound saga evidence (M8d3c)	Complete bounded forward/qualification/inverse lineage, protected native export and independently pinned offline verifier; explicit partial/unknown states	One selected inverse contract; complete evidence is distinct from compensation success. Multi-contract execution, independent peer and failure/deployment acceptance remain open
SQL inverse target (M8d3a)	Protected snapshot, actual conditional restore, target barrier and separate applicability evaluator; explicit native adapter and original-attempt query	Local real-SQL/native broker/mTLS/software qualification; bounded inverse SDK composition is in M8d3b; multi-contract runner, independent whole-saga and deployed writer acceptance remain open
Fresh inverse authority (M8d2b2)	Explicit fresh inverse admission and mandatory signed compound binding, atomic spending from original held capacity, common fences and original-attempt recovery	One selected inverse contract per paired service; RFC 0048 adds the SQL target/barrier and RFC 0049 bounded compound evidence. Multi-contract and M8d3/M8e acceptance remain open
Shared family authority (M8c4)	Live signed narrowed delegation and common held child budgets, mandatory native authority CAS, paired inverse recovery and separate-observer allocation history	One namespace, fixed catalog, no refunds; independent authority-peer acceptance, multi-contract real-SQL runner/aggregate evidence, drain and external acceptance remain open
A2A family tasks (M8c5)	Core v1 JSON-RPC peer, actual official A2A SDK 1.0.1 discovery and task exchange, signed narrowed coordination, stable replay and shipping process restart	Completed coordination conveys no execution authority; independent authority peer, complete multi-contract saga and physical drain acceptance remain open
Paired action controls (M8d2b2a)	Explicit fresh physical-domain topology, separate exact installations, shared resource fences and permanent shared stop	Legacy roots refuse adoption; RFC 0047 adds the explicit inverse execution opt-in. M8 remains open
Inverse prerequisites (M8d2b1)	Protected inverse CTD/contracts and signed proof qualification, original commit/barrier/applicability verification, durable journal and shipping CLI	Qualification alone supplies no authority; RFC 0047 separately adds fresh inverse authority. Actual inverse and independent saga acceptance remain M8d3
Native forward saga (M8d2a)	Protected preallocated DAG, signed predecessor commits at admission/issuance/claim/dispatch and complete issued-leaf budget replay	Eight fixed forward operations under one executable contract; selected inverse execution/audit is in M8d3a–c. Multi-contract inverse, failure/deployment acceptance and physical drain remain open
Saga observations (M8d1)	Protected DAG and durable query-only reconciliation, original admission/grant/attempt/receipt proofs, blocked inverse intent, bounded journal and shipping kf-saga CLI	No forward runner, native dependency enforcement, fresh inverse admission/dispatch, exclusive whole-DAG reservation or complete independent saga replay; M8d2/M8d3 remain open
Conformance prerequisite (M9a)	Required software runner, source/tool/log pins and explicit open release gates	Independent controller, second runtime/target and reproduced release acceptance open
Enterprise and wider protocols (M6–M9)	Roadmap and acceptance requirements	Complete real-target pilot, Rust human-review/lease path with enrolled hardware, accepted dynamic delegation/saga/drain and independent protocol peers remain future milestones

The frozen executable grant supports one nondelegated resource, one version_eq predicate, Level_A / FencingToken, and dispatch_bound completion. M8c2 supports static hierarchy only through its separately versioned signed composite / leaf-binding profile and mandatory native ledger checks. Direct parent/saga fields in the frozen executable grant, unbound delegation, other guards, multiple predicates/resources and commit_bound validity are refused. RFC 0052 family delegation and the native saga profiles use their separate protected bindings. Protected gateway configuration selects a fixed HTTPS fenced mock target or the explicit RFC 0025 SQL reservation adapter. An authenticated, exactly correlated terminal receipt establishes that target's commit. Generic MCP success, tool error, timeout or asynchronous acceptance cannot establish commit or absence of an effect.

The baseline must match the active CTD's registered version_eq clause. Subsequent versions require an updated registered descriptor; automated rollover remains unqualified.

Unknown attempts remain consumed. Recovery and status queries do not retry mutations or refund authority. The native broker authorizes one mint from the original undispatched claim; failed or lost mint replies do not permit another mint, and no token redelivery API is supplied. Its reference target credential requires the separately implemented target-side guard/effect/outcome contract.

The next acceptance gate is M5c approved identity/credential providers and protected deployment custody, followed by M6's isolated enterprise pilot acceptance. M6c qualifies the bounded disposable SQL failure composition. The delivered M5c1–M5c3 software prerequisites do not close that gate. M0 toolchain/reproduction qualification and M1 owner acceptance also remain open; full M2–M4 deployment gates remain tracked in the roadmap.

Build and verify

The workspace declares Rust 1.88 or newer; the SDK harness declares Node 20 or newer. The latest retained required-mode run used Rust 1.98.0, Node 25.2.1 and etcd 3.6.5 on Darwin ARM64. Execution on the declared minimum Rust/Node versions remains unqualified. Rust dependencies are fixed in Cargo.lock; the official MCP client is pinned in tests/sdk/package-lock.json.

cargo build --locked --workspace --bins
cargo run --locked --bin kf-proxy -- --help
cargo run --locked --bin kf-broker -- --help
cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets -- -D warnings
python scripts/verify-whitepaper.py

Run the full Rust suite with PostgreSQL 18.3 server/client binaries, a real three-member etcd 3.6.5 cluster and the pinned MCP client SDK:

npm ci --prefix tests/sdk
KF_REQUIRE_SDK=1 ETCD_BINARY=/absolute/path/to/etcd \
  python scripts/test-postgres.py --bindir /absolute/path/to/postgresql-18.3/bin --peer --recovery-rehearsal \
  --command scripts/start-etcd.sh -- \
  cargo test --locked --workspace --all-targets -- --nocapture --test-threads=1
node tests/sdk/agent-vectors.mjs
node tests/sdk/lease-vectors.mjs

See real-etcd testing for Bash, curl and cluster prerequisites. The retained run serialized test cases to fit host disk capacity; explicit actor concurrency still races inside tests. A plain cargo test can skip tests requiring unconfigured etcd, SDK or PostgreSQL dependencies. The SQL CI job requires the disposable database, etcd and official SDK for target, fresh SQL leaf and combined failure tests. Required mode and CI fail if those dependencies are absent.

Use the conformance runner for one source-pinned required-mode bundle. The A2A task qualification records its exact source, official SDK and shipping process tests. New family qualification is recorded in the family authority verification, with retained source/tool/log pins and explicit open gates. The inverse SQL restore verification records 441 Rust tests across 52 binaries, 26 SQL storage/peer/restore groups and 32 Python tests, both Node suites and quality checks. Two new native cases preserve consumed original authority and unknown/committed signed outcomes across real stale SQL copy restoration with only the query role reopened. A historical compensated report does not assert restored live state. Physical restore/cutover and deployment acceptance remain open. The preceding inverse failure verification records 439 Rust tests across 52 binaries, 26 SQL storage/peer/restore groups and 32 Python tests, both Node suites and quality checks. Three new native cases qualify shipping target SIGKILL at a real SQL lock and after COMMIT, plus separate-witness stale authority quarantine. Original attempts, held costs and query-only receipts survive; physical inverse SQL restore and wider crash acceptance remain open. The preceding compound lineage verification records 436 Rust tests across 52 binaries, 26 SQL storage/peer/restore groups and 32 Python tests, plus agent/lease client vectors and quality checks. Six native audits verify complete original chains, held/unknown/committed states, two-node omission refusal, re-signed semantic substitutions and receipt loss racing the final export CAS. The preceding SDK record retains 430 tests for fresh inverse execution and separate-process query-only recovery, including a lost target reply without another mint or send. The SQL target record retains 428 Rust tests; the fresh inverse authority record retains 422 tests and 18 SQL groups; the paired control record retains 414 tests. Independent peer acceptance, multi-contract inverse families, independent whole-saga acceptance, physical inverse SQL restore/cutover and wider crash acceptance, actual drain and enterprise acceptance remain open. The preceding M8d2b1 record retains 404 tests for inverse prerequisites; the M8d2a record retains 394 tests for native forward DAG authority; the M8d1 record retains 383 tests for query-only saga observations. The preceding M8c3 record retains the 372-test implementation; the M8c2 record retains the 358-test implementation. The preceding M8c1 record retains the 343-test implementation. The preceding M8b2 record retains the 331-test implementation. The preceding M8b1 record retains the 320-test implementation. Separate Linux account and minimum Rust CI execution are unobserved locally.

The earlier M6d2a verification records 269 Rust tests across 40 binaries, 15 SQL storage/peer groups and 32 Python tests, with no Rust failures/ignored/skipped and SQL/etcd/SDK required. The shipping target consumes protected file bytes under explicit custody mode; the required SQL run now uses actual kernel peer authentication. This is same-UID mechanics, not deployed account isolation or enterprise acceptance.

The M6d1 verification records 263 Rust tests passing with no failures/ignored/skipped, 11 real SQL storage groups and 32 Python tests. Three isolated enrollment groups prove column and SET ROLE bypasses and verify preflight/runtime refusal. The shipping CLI checks both fixed roles without a listener or probe mutation; the existing --check remains offline. This tightens supported role enrollment.

The M6c verification records 260 Rust tests passing with no failures/ignored/skipped, including 11 fresh SQL failure/restore/incident cases, plus 11 real PostgreSQL storage groups. Recovery retains the original attempt and consumed authority without another mint or mutation. The collector uses shared retained receipt storage; logical ledger rollback is refused against a separately retained witness. M6b2 retains its 249-test run and deterministic ID-schema regression covering all 256 leading entropy bytes. M6b1 retains its 243-test run. M6a retains 237 passing Rust tests for its pinned sources; M5c3 retains its earlier 233-test run. These are same-host software fixtures with generated authority, not production or distributed failure-domain qualification. The paper artifact is a separate historical reproduction.

Run the SQL and native mTLS target cases with PostgreSQL 18.3 server/client binaries; the launcher creates only its own disposable Unix-socket database:

python scripts/test-postgres.py --bindir /absolute/path/to/postgresql-18.3/bin --peer --recovery-rehearsal \
  --command cargo test --locked --test postgres_target -- --nocapture --test-threads=1

See storage prerequisites and native target setup and integration limits.

Services and tools

cargo build --locked --workspace --bins builds all sixteen Rust executables. Provision protected material using the linked guides and configuration templates; the examples contain placeholders and are not an enrolled deployment.

Executable	Purpose	Guide / configuration
kf-proxy	Authenticated MCP execution/discovery and negotiated retained status	Gateway guide, gateway config
kf-control	Authenticated admission, issuance, operation lookup and opt-in A2A root views	Control guide, control config
kf-family-peer	Core A2A v1 signed family coordination tasks; no target authority from task IDs	A2A family guide, protected operator files
kf-governance	Authorized signed policy/registry publication, installation and revocation	Governance guide, governance config
kf-broker	One-shot RFC 8693 exchange with KedgeFlow grant/attempt extension and reference target mint	Broker guide, static config, signed-refresh config
kf-recover	Query-only retained-attempt recovery and receipt signing	Recovery guide, recovery config
kf-outcomes	Authenticated retained receipt collector and signed delivery acknowledgements	Collector guide, collector config
kf-supervise	Owned unknown deadlines, recovery polling and ordered delivery	Supervision guide, supervision config
kf-postgres-target	Authenticated SQL reservation dispatch and separate retained outcome query	Target guide, target config
kf-restore	Privileged empty-namespace witness enrollment and live status checks	Restore guide
kf-review	Native rendered review challenges and signed reviewed evidence	Review guide
kf-verify-reservation	Offline issuer-signed reservation binding verification	Reserved leaf guide
kf-verify-reserved-lineage	Offline reserved history and signed-outcome lineage verification	Reserved history guide
kf-verify-outcomes	Offline grant/receipt-chain verification	Recovery guide
kf-verify-lineage	Offline signed admission-lineage verification	Lineage guide
kf-verify-history	Offline observer-attested governance/key-history verification	History guide
kf-verify-control-bindings	Offline per-transition control comparison verification	Control-bindings guide

Run the gateway and broker

Provision independently trusted identity, authority, credential and target services. Keep configuration, keys, actor assertions and backing target credentials outside the agent's authority domain.

cargo run --locked --bin kf-proxy -- --config /etc/kedgeflow/gateway.json --check
cargo run --locked --bin kf-proxy -- --config /etc/kedgeflow/gateway.json
cargo run --locked --bin kf-broker -- --config /etc/kedgeflow/broker.json --check
cargo run --locked --bin kf-broker -- --config /etc/kedgeflow/broker.json

These --check commands validate configuration and local TLS/identity material; they do not probe remote services, publish authority or certify current provider freshness. Native services require HTTPS and verified client certificates. Admission/issuance and administrative operations have separate authenticated service boundaries. Managed configurations require live installed-state checks and gateway acknowledgement renewal; legacy direct publication/issuance/replacement ports refuse managed domains.

Broker static mode requires protected restart to reload identity snapshots. Signed-refresh mode reads authenticated snapshots against an exact protected head on every exchange; it requires an external approved publisher and independently retained head/floor. The broker does not publish updates or advance that floor. The execution-grant gateway_audience and subject-token delegation_audience are separate pins. The custom exchange extension and reference target token are draft bindings; a third-party authorization server or target needs an explicitly compatible integration.

Optional KF-GRANT-REF-0.1 retrieval supplies a pinned mTLS resolver with requester scope/size/time limits. Its grant store still needs independently administered publication, authorization, retention and rate controls. The target must implement its declared fenced transaction and correlated outcome contract; configuration alone cannot supply target atomicity.

For local agents, loopback access and MCP routing must be paired with operating system isolation of native shell, filesystem, socket and network paths. The gateway installs no workstation sandbox. See the deployment guide and enterprise gates for rollout requirements.

Existing Python demo

The Python 0.1.0a1 package remains a compatibility and learning demo. Its in-process HMAC authority and lifecycle use a different profile; this integration does not convert them into v0.9 execution grants. Use Python 3.11 or newer.

python -m pip install -e '.[dev,spec]'
kedgeflow demo
ruff check .
mypy src
pytest -v
python spec/validate.py

The Python compatibility/freeze suite contains 32 tests. It is separate from the current Rust and PostgreSQL verification records.

Architecture, implementation handoff, initial review, 10 October review baseline, paper references, Rust verification history, schema tooling, legacy demo. Earlier reviews and handoff counts are historical snapshots; use the milestone plan and current verification records for subsequent implementation progress. Licensed under Apache 2.0.