Unclassified

Governed Execution Runtime

The single runtime contract the platform is built around:

Intent → Capability → Tool Capability → Connection → Governance → Approval
       → Hermes → Provider → Reconciliation → Promotion → Spine → Projection

This document records what is enforced in code today, where each rule lives, and
what is not yet proven. It is an engineering record, not a plan.

1. Where the contract lives

packages/capability (@integratewise/capability) is the canonical fabric. It
is dependency-free — no provider SDK, no HTTP client, no storage driver — so
every service on the chain can import it without dragging provider logic across
a boundary.

Concern	Module
Semantic / tool capability, connection, actor contracts	`src/contracts.ts`
Registry and deterministic resolution	`src/registry.ts`
Immutable, content-hashed execution plans	`src/execution-plan.ts`
The one Governance decision engine	`src/governance.ts`
Signed, single-use approval tokens	`src/approval.ts`
The Hermes authority check	`src/authorization.ts`
Provider reconciliation	`src/reconciliation.ts`
Promotion envelope + projection invalidation keys	`src/promotion.ts`
Governed execution runtime (Hermes body)	`src/execution.ts`
D1-backed authority, replay, idempotency, connection, policy stores	`src/d1-stores.ts`
Runtime result states	`src/runtime-result.ts`
Seed catalogue (`email.send` → `gmail.email.send@2`, …)	`src/catalog.ts`

Services own the transport, never the rules:

Service	Role
`services/govern`	Resolve → plan → decide; issue approval tokens; own the authority record
`services/hermes`	Verify authority, dispatch, reconcile, emit a promotion envelope
`services/connector`	The only component holding provider credentials and protocols
`services/pipeline`	The only component that promotes an outcome into canonical Spine truth
`services/mcp-connector`	Public semantic facade; decides nothing
`packages/projection-engine`	Projects governance state for display; authorizes nothing

2. The chain, step by step

Intent → Capability → Tool Capability → Connection

A caller names a semantic capability (email.send) and never a provider.
FabricCapabilityResolver binds it to a tool capability
(gmail.email.send@2) through a tenant-owned connection, preferring the
lowest risk class and then the highest version, so resolution is deterministic.

Resolution fails — explicitly, never silently — when the capability is unknown,
every tool capability is disabled, the tenant owns no matching connection, the
connection is not healthy, or the connection does not grant the scopes the tool
capability requires.

A connector definition is not a connection. tenant_connections holds the
non-secret binding state resolution needs; credentials stay in the connector
service's vault.

Execution plan

createExecutionPlan freezes the plan and stamps a SHA-256 hash over every
field. Callers supply only a draft of each expected effect (description,
optional target and assertions); the effect's identity — kind, operation, target
type — is stamped from the tool capability's effectSignature. That is what
makes reconciliation possible: the effects a plan declares and the effects the
connector observes come from one source.

Governance

evaluate() returns exactly one of allowed | approval_required | blocked,
with sorted reason codes, from: actor, tenant, workspace, resolved capability,
tool capability, connection, plan risk and reversibility, and the policy
snapshot. It is deterministic — same inputs, same decision, same decision id.

blocked on any binding mismatch, blocked capability, disabled tool
capability, unhealthy connection, missing scopes, missing actor permission,
or a risk class the tenant forbids outright.
approval_required for every mutation, and always when the actor is not
human — Twin Law.
allowed only when every declared effect is a read.

No other component reinterprets policy. /v1/check is retained for callers
that ask "would this be permitted?", and stamps authoritative: false and
requires_execution_plan: true on its answer so it cannot be mistaken for one.

Approval

An approval token is a signed, single-use, expiring statement that a human
with an approver role approved one specific plan under one specific decision.
It is bound to the plan hash, so editing a plan after approval invalidates it,
and it can never outlive the decision it rests on.

Hermes

POST /execute accepts one payload: an AuthorizedExecutionCommand. Before any
provider is contacted, verifyAuthorizedCommand checks tenant, workspace and
actor match; plan integrity (hash recomputed); decision validity and expiry;
capability, tool-capability and connection match; that the command's input and
idempotency key are identical to the plan's; the approval token when the
decision required one; and the replay and idempotency state. Any failure throws
— there is no warn-and-continue branch.

Hermes holds no private copy of the authority record: plans, decisions, replay
and idempotency all live in Governance and are read over a trusted binding. A
Governance outage produces a refusal, never an assumption.

Provider

Hermes contains no provider-specific logic. It calls
/internal/capability/dispatch on the connector with a tool capability id and a
connection id; the connector re-verifies the binding on its own side and takes
the operation from the registry, so a caller cannot widen what it may do by
renaming its request.

Reconciliation

/internal/capability/observe reads provider state back. reconcile() compares
observed effects with the plan's expected effects and yields reconciled,
partially_reconciled or reconciliation_failed. An HTTP 200 with nothing
observed is a failure, not a success. Only reconciled and promoted may be
presented to a user as complete.

Promotion and projection invalidation

Hermes emits a promotion envelope carrying the full continuity chain and hands
it to POST /v1/promotion/execution-outcome. The Pipeline refuses an envelope
that did not reconcile or whose chain is incomplete, then queues it for
canonical promotion and invalidates the affected projection keys. Hermes writes
no canonical Spine state itself.

3. What was removed

These paths existed and are gone, because each was a way to act without
authority:

Hermes' direct Spine entity write (bypassed Pipeline promotion).
Hermes' queued execution path that returned success: true without executing.
The Durable Object's Spine execution with an approval token it never verified;
it now tracks reconciliation lifecycle state and executes nothing.
The orchestrator's http.request node — arbitrary HTTP with no capability, no
connection and no Governance — and its spine.write node.
The connector's free-form /execute, which named a tool and operation
directly, is now restricted to trusted service callers and unreachable from
the public edge.
The Projection Engine's second governance evaluation, which used a different
vocabulary (denied, escalated) and a permissive TODO default policy.

Arbitrary HTTP still exists, but only as internal.http.request — a registered
internal tool capability carrying risk class critical, disabled by default,
and subject to the identical Governance contract as any provider capability.

4. Storage authority

Store	Holds
Neon PostgreSQL	Canonical business and operational truth
R2	Files, raw payloads, immutable evidence
D1	Bounded operational state: authority records, idempotency, replay, connections, policy snapshots
KV	Ephemeral hot state, caches
Vector / AI Search	Retrieval indexes

D1 never answers a canonical read. GET /executions/:id returns
state: "stale" with source, store, cached_at and
canonical_available, so a cached read always discloses what it is.

Schema: sql-migrations/d1/013_capability_fabric_authority.sql.

5. What CI enforces

pnpm run check:architecture (strict, blocking) and
pnpm run test:governed-chain (blocking) run in the governed-chain job of
.github/workflows/ci.yml.

Boundary rules R6–R12 cover: no provider SDK in the UI; no bare fetch in
Hermes; only the Pipeline writes canonical Spine entities; exactly 19 public MCP
tools with no internal families leaking; no credential access in client code; no
fabricated success in a catch handler; one definition of the governance decision
outcome. Each rule was verified to fail against an injected violation.

Test coverage across the chain (247 tests): tenant isolation, capability
resolution, connection selection and scope gaps, governance determinism and each
outcome, approval issuance authority, token mismatch / expiry / replay,
idempotent execution, every Hermes refusal path, reconciliation success and
mismatch, promotion gating, projection invalidation keys, and the end-to-end
Customer Zero slice.

6. Not yet proven

Honest gaps. None of these are hidden behind a passing test.

No live provider execution. The chain is proven end to end against a
recording adapter and a connector stub. It has not been run against real
Gmail or Salesforce credentials, so the loader operation contract
(/internal/connections/:id/operations/:operation and …/records/:ref) that
services/connector/src/routes/capability.ts calls is specified but not yet
implemented on the loader side. Until it is, dispatch returns
provider_transport_unavailable and reconciliation refuses to report
completion — the failure is explicit, not silent.
Governance has no isolated prod environment.
services/govern/wrangler.toml has no [env.prod] section and its default
environment points at the test D1 database. A govern-prod Worker with its
own D1, SERVICE_SECRET and APPROVAL_SIGNING_SECRET must be provisioned
before governed actions run in prod. services/mcp-connector/wrangler.toml
deliberately leaves env.prod unbound rather than pointing prod at test's
governance database.
Secrets are not set. SERVICE_SECRET and APPROVAL_SIGNING_SECRET must
be set per environment with wrangler secret put. Without them Governance
refuses to issue approvals and Hermes refuses to execute — the safe failure,
but a non-functional one.
Workspace resolution on the MCP surface. Governed action tools require a
workspace, taken from the Gateway-forwarded x-workspace-id. Where One Auth
does not yet resolve a workspace the tools refuse rather than inventing one.
Connection registration is not called on connect yet. The connector
exposes POST /internal/capability/connections (upsert, trusted callers
only, refusing any connection no registered tool capability can bind) and
…/connections/revoke, and the Nango disconnect path already revokes. The
connect path does not call the upsert: the loader's auth.created webhook
carries neither the granted scopes nor a workspace, and both are required to
register a connection honestly. Wiring it means reading the granted scopes
from the Nango connection record and resolving the workspace from One Auth;
until that is done, resolution reports no_connection rather than binding
something whose authority is unknown.
Deployment verification could not run here.
pnpm run verify:continuity and any non-dry release require
CLOUDFLARE_API_TOKEN. The dry run
(pnpm release:deploy -- --environment test --service core --dry-run) passes
with the new bindings resolving to govern-test, adding no new Wrangler
warnings to the six pre-existing ones.