Governed service binding v1alpha2

Specified; runtime pending

Rendered from contracts/service/v1alpha2/semantics.md by connectors-docs; the source owns every rule on this page.

• Status: proposed, not implemented. Nothing in this document is advertised by any descriptor.
• Family: service. Predecessor: service/v1alpha1 (implemented). Siblings that this envelope carries: operations mutation profile, auth.connection, auth.custody.
• Recorded: 2026-09-08.
• Why it exists: the preserved review of 2026-09-08 (gaps G1–G3, G6, G7, G9) found that the v1alpha1 wire and host carry no verified caller context, so nothing downstream of admission can be governed per caller. Every current consumer of the old Connectors passes an owner context and receives grant and audit facts. This document proposes the service envelope and admission boundary for that gap. The compatibility decision selects its local binding and exact public encoding; one-hop delegation selects its proof/approval subjects; policy/audit persistence and runtime conformance remain explicit obligations.

1. Identity

Field	Value
Wire version	v1alpha2 on /v1alpha2/describe and /v1alpha2/invoke; legacy /v1/... is a separate explicit projection
Admission profiles	static-bearer (today's shared service token), service-account-token (a projected Kubernetes service-account token for the instance's configured audience, checked with a TokenReview at each request and admitted only as the one configured system:serviceaccount:<namespace>:<name> principal; implemented on the first binding, compatibility §2.1, Admission), identity-audience (Identity access token for an exact Connectors-owned audience), delegated (federation hop carrying a gateway-signed verified context)
Vocabulary	verified context (tenant, principal, optional realm, authority, optional executor), policy decision, grant reference, audit reference, executor assertion
Preserved structure	operation ids, input/output schemas, limits, success/error response variants and request correlation, /healthz, one-hop federation, descriptor revision and stale_description protocol

The proposal changes response fields and the closed error-code vocabulary (§3.4–3.5), including audit_ref; the serialized error envelope is therefore not unchanged. The implemented v1alpha1 readers refuse those additions. The compatibility decision selects v1alpha2 for this local proposal and separates it from semantic-family and adapter-kind versions. No implemented descriptor advertises it and no release/consumer rollout is implied.

A v1alpha2 service answers four questions separately, as docs/design.md § 6.2 requires: implemented by this artifact, enabled in this instance, ready with its dependencies, authorized for this caller. The legacy binding describes implemented/enabled operations and checks dependencies on invocation; it has no per-person policy projection or readiness grant in the descriptor. The fourth needs a stable caller. Static bearer identifies one receiver-configured service principal, not the individual people sharing its bytes; it cannot provide individual caller isolation.

3. Types and binding

3.1 Authentication and admitted invocation context

AuthenticatedContext {
  tenant: Option<opaque string>  # credential-verified; configured absence for local static principal
  principal: opaque string      # credential-verified or receiver-configured static service identity
  realm: Option<opaque string>  # absent differs from "default"
  authority: Option<AuthorityRef> # current governed authority, or explicit configured local policy
  credential_executor: Option<ExecutorRef>
}

AdmittedInvocationContext {
  authenticated: AuthenticatedContext
  executor: Option<ExecutorRef> # established by credential/configuration/grant validation
  grant_ref: Option<opaque string>
  connection: admitted connection, or absent for an explicitly instance/acquisition-scoped management profile
}

Management target resolution follows the host boundary: create/list are instance-scoped and status resolves its owned acquisition, all omitting the wire connection member; describe/revoke/repair require one exact nonempty string selector. Explicit JSON null is invalid. Do not manufacture an implicit configured target for management, and reject contradictory selectors. Protected completion does not use this invocation context or become generic invoke input.

These are host values, never caller-written authority. The authentication context exists before application decoding; the admitted invocation context follows strict decode, connection/policy checks and verification of any executor assertion. A body assertion cannot overwrite authentication coordinates. If a credential binds an executor, require exact match; otherwise the policy must independently establish the asserted binding or refuse it. Local static identity and tenant/realm absence are stable configuration facts, not credential bytes or token-rotation identities. No missing/unavailable governed policy falls back to local policy.

3.2 Descriptor

Compatibility §4 is the complete closed field contract. Root additions are admission, safe auth_profiles, a managed-connections flag and safe provides metadata. Operation additions are curation, optional auth alternatives/realization, and explicit limits. The operation profile remains singular. Profile/provider registration internals and credential references are not copied into this safe descriptor.

Successful GET /v1alpha2/describe wraps this complete Descriptor in the common Response’s result, with request_id: null and required audit metadata. Both version fields equal v1alpha2; errors use the same envelope without a result. Legacy describe keeps its bare Descriptor shape.

Under all three admission profiles, operations are the caller-visible projection of implemented, fully bound, enabled and currently metadata-policy-admitted operations. Static bearer evaluates an explicit local policy for its one configured service principal; it does not distinguish people sharing that credential. Reserved, invalidly declared, unsupported-codec or unbound operations are omitted even if a package/vocabulary names them. Describe uses admitted host metadata and performs no provider probe, credential refresh, approval spending or business dispatch. Dependency readiness and possession of a current one-shot approval do not determine operation visibility. A not-ready connection can therefore retain useful admitted operation metadata and separately admitted management repair operations.

3.2.1 Visibility, lookup and refusal precedence (E12)

The public projection is not the receiver's private implementation registry. Extended invocation may use that registry to distinguish an implemented-but-disabled operation from an absent/unbound one only after current policy admits lookup in that exact operation/target scope. Lookup admission is a receiver policy decision, not a new public permission flag, caller assertion or bypass to a handler. Denial/unavailable authority returns a safe error without exposing whether an implementation, key, attempt, approval or result exists. If policy does not admit lookup of an unknown spelling, not_granted wins; not_found is observable only within a lookup scope the caller is allowed to inspect. No public disabled descriptor field is introduced.

For a valid selected envelope, apply this order: (1) transport/framing/authentication/version and syntactic identifier/size checks; (2) current host operation/lookup/result-scope policy and verified executor binding, including current host connection/resource observation authority; (3) exact current descriptor projection revision; (4) private implemented/bound lookup and enablement; (5) operation input shape and confirmation that the validated input remains inside the admitted scope; (6) mutation key observation, if keyed; (7) only for a candidate new attempt, required approval, dependency/credential/provider-permission preflight and the existing audit/attempt/spend/dispatch sequence. Step 2 may consult private host metadata and parse submitted target coordinates internally to decide current policy, but cannot disclose private lookup errors or an unadmitted target; absence/ambiguity is not authority to widen scope. Provider permission/readiness work belongs to step 7, not describe or replay. All relevant current host admission checks are repeated/fenced at the binding's dispatch boundary; a stale earlier descriptor or successful lookup is never a durable execution grant.

State / condition	Describe	Invoke (current admitted lookup and revision unless stated otherwise)
Unknown, unimplemented, invalid/unbound or unsupported operation binding	omitted	not_found; no handler, provider, approval or key lookup
Implemented/bound but configuration-disabled	omitted	forbidden; receiver identifies it privately after admitted lookup, without dispatch or original-result disclosure
Current host metadata/lookup/operation policy denies caller or executor binding	omitted where metadata denied	not_granted; deny before stale/existence/key/approval disclosure
Required current host policy is unavailable	no success claiming an admitted projection	unavailable; no fallback to static policy or cached authority
Current host connection/resource observation scope denied	metadata only if its separate scope remains admitted	forbidden; no target-existence or mutation/result disclosure
Enabled and policy-admitted, but dependency/credential/provider permission not ready for a new attempt	visible	after key observation and candidate approval, selected connection_not_ready/insufficient_scope/route refusal/unavailable/forbidden as applicable; do not collapse global viability and exact operation eligibility
Enabled/admitted, missing a fresh execution approval	visible with approval requirement	a candidate new attempt gets approval_required; exact admitted replay neither requires nor spends fresh execution approval
Enabled/admitted with exact matching retained key, new-attempt dependencies unavailable	visible	original outcome/wait/quarantine observation under F02 current result admission; no provider preflight, marker generation or new approval spend
Enabled/admitted/ready with required new-attempt approval	visible	normal invocation under existing profile/audit/dispatch rules
Supplied revision is old, while current host lookup/observation authority still admits the request	current projection on describe	stale_description before private disabled/not_found/input/key decisions; caller must deliberately refresh description and resubmit
Same stale request also loses current host lookup/observation authority	governed by current metadata scope	current not_granted/forbidden/unavailable wins without stale/existence/outcome disclosure

Every refusal before current result admission/key observation omits mutation metadata; absence does not mean not_attempted for a possibly existing original. A newly admitted candidate's later approval/preflight refusal can report not_attempted only under F01/F02's winner-recheck and dispatch-evidence rules. Descriptor freshness, current result authority, dependency readiness and approval are separate facts. Input validation cannot authorize a key lookup or expose a hidden operation schema before the prior admission steps.

The revision binds the selected codec, caller projection and effect-relevant configuration/meaning. Enable/disable, visible membership, input/output meaning or authority-binding changes invalidate affected descriptions; credential rotation or transient readiness loss alone need not change operation meaning. A caller with a current descriptor that omits a disabled operation can receive forbidden for an admitted guessed ID, while a caller presenting its old pre-disable revision receives stale_description first. Subsequent re-enable cannot authorize execution on a stale description. Invocation must re-evaluate current policy even immediately after describe.

Federation exposes only the selected gateway/leaf codec, binding, enablement and authorized metadata intersection, under the current delegated describe proof. An alias or broad downstream bearer cannot widen it. If the selected complete projection cannot establish a required current leaf admission, describe fails safely as unavailable rather than silently claiming cached policy is current; no provider probe is implied. Invoke independently admits gateway and leaf, resolves the fixed leaf meaning, and preserves refusal/unknown outcomes without fallback or resend. Legacy projection retains its separate restricted lookup rule below. These are future receiver/projection obligations; the current descriptor-vector implementation does not already provide this private extended lookup.

3.3 Invocation

The original required version/request_id/operation/revision/input fields remain. The extended codec admits optional connection, idempotency_key, approval and executor assertion with the exact shapes in compatibility §4. A read profile does not gain mutation or connection authority merely because its codec understands those members; unsupported combinations are refused before dispatch.

For example, a managed read may select connection: "conn_1"; a mutation may additionally carry approval: {reference, evidence} and a keyed operation requires idempotency_key under its profile. A malformed assertion is invalid_input; an assertion that fails its trusted executor/grant binding is not_granted. Absence is accepted only when policy admits direct principal execution. The raw assertion is never an already verified context.

First binding. The first served binding is POST /v1alpha2/invoke alone (compatibility §2.1); describe stays on legacy /v1/describe until its own binding is specified. It admits only the five original members. connection, idempotency_key, approval and executor are refused with unsupported before dispatch, and an operation that is keyed or approval-gated is not invocable on it. Every rule in this section beyond the original members applies from a later binding, not this one. The one addition: a host whose configuration sets standing_grants also admits idempotency_key and runs every write keyed under a standing grant, which is its approval (compatibility §2.1, Keyed writes under a standing grant); a host without it is as described here.

3.4 Responses and audit

Exact fields and consistency rules are in compatibility §5. These illustrative complete envelope shapes use empty placeholder business results:

{ "version": "v1alpha2", "request_id": "read-1", "status": "success", "result": {}, "audit_ref": "aud-1", "audit_status": "complete" }
{ "version": "v1alpha2", "request_id": null, "status": "error", "error": { "code": "unavailable", "message": "audit admission unavailable" }, "audit_ref": null, "audit_status": "unavailable" }

Mutation observation is under mutation, with classification, original attempt/request identity, replayed and optional secondary cause as specified in compatibility §5. A replay retains its original classification; replayed is never an effect. An admitted provider success followed by failed outcome persistence may still return success/applied with a persistence cause. If a result cannot safely be delivered after a known effect, error/applied preserves that fact. Unknown is always error/outcome_unknown, independent of a timeout cause.

On the first binding (compatibility §2.1) every admitted read and write is audited under the execution audit contract: an acknowledged admitted_execution anchor precedes attempt recording and dispatch, the response answers complete or, when the final append fails, incomplete with that record's audit_ref, an anchor that cannot be written refuses as unavailable with no dispatch, a refusal before the anchor answers unavailable with a null reference, not_required is never answered, source_audit is omitted, and mutation is present exactly for an admitted external_write operation once its attempt is recorded.

The receiver's audit_ref/audit_status and optional {instance,audit_ref,audit_status} source_audit distinguish gateway and leaf. An unacknowledged audit write never produces an invented reference. Audited reads and mutations need acknowledged pre-dispatch audit admission, then a separate linked final observation. Final audit failure preserves known/unknown business facts and reports incomplete audit; it cannot retrospectively prevent dispatch. Refusals before valid authentication/decoding leave unknown audit coordinates absent and request_id null. The explicit unavailable/no-ref failure path replaces the earlier impossible mandatory-reference promise.

3.5 Errors

The closed extended code set is listed in compatibility §5. not_granted is host policy refusal; forbidden is a selected adapter/connection/resource refusal. stale_authority requires fresh authority and a new describe before a deliberate new interaction. Payload states, private auth outcomes and media terminal reasons are not automatically ErrorCode values. Current v1alpha1 readers reject new codes; no error is tunneled through message text to pretend compatibility.

3.6 Delegated federation — selected proposal

One-hop delegated approval and dispatch now owns the complete canonical subject, safe preparation read, fixed Ed25519 JWS types, request/receiver/GET correlation, bounded time and durable nonce rules, and sole executing-leaf approval redemption. Its separate proof types replace the withdrawn HMAC sketch; they do not extend the predecessor module-request v1 token. Provider credentials remain at the executing leaf, and a broad downstream bearer supplies no originating caller authority.

The host.approval.prepare operation uses the ordinary extended envelope and its own selected approval-subject payload/limits, covering both configured and managed connections. It performs no provider use, business reservation or approval spend. Preparation/issuer presentation is not execution authority. Current policy, exact subject reconstruction and the existing keyed-outcome lookup still precede new approval redemption. Direct and federated origin are distinct; only the leaf spends and owns the business attempt.

The protocol is specified, not implemented. Delegated support remains unadvertised until the selected verifier, policy, clock, uniqueness stores and conformance exist. Multi-hop and event-claim ingress remain unavailable; no automatic resign/resend or broad-token fallback is allowed.

4. Admission and execution rules

1. Select configured endpoint and fixed version path, bound framing and authenticate into AuthenticatedContext, then strictly decode the envelope. Apply §3.2.1 precedence: current trusted lookup/observation policy and executor binding before revision/existence disclosure; private bound/enablement lookup and operation admission before any key observation; candidate-only approval and dependency preflight before dispatch. No application input chooses tenant/principal/realm/authority or expands the destination.
2. Policy failure or unavailable authority is fail-closed for reads and mutations. Describe-time visibility is not a grant. Connection refusal does not reveal whether another scope's connection exists.
3. Realm absence is distinct from Some(default) in policy, idempotency, cursors, cache and audit. Stable local static principal identity does not change when credential bytes rotate.
4. Audited invocation first acknowledges an audit admission, then follows any mutation attempt preparation/spending/dispatch fence, then records its outcome. Audit and attempt records have distinct purposes. Failure handling follows compatibility §5; no log line replaces a durable claim/attempt.
5. Federation uses only the selected per-hop codec/profile intersection and a complete trusted delegation binding. No credential/context substitution, downgrade, reroute or resend follows a refusal or lost response.
6. Legacy projection follows compatibility §3: off by default, explicit unchanged static reads only, exact projected operation/revision checked again by invoke. Hidden mutations cannot be reached with a guessed ID or the new/full descriptor revision.
7. read-refresh-once/v1alpha1 is available only when its combined native profile is explicitly authored, implemented and selected in Operation.profile. After one definitive business 401 it permits one coordinated refresh participation and at most one new-generation business redispatch, with the original request/authority/deadline and consumed permission-call ledger. A fresh DispatchAdmission is required; a refreshed capability or new generation never reopens the first admission. Existing profiles, mutations, generic realizations and mediated/federated execution gain no retry. No current adapter selects this binding.

5. Limits

Operation request/result/execution/provider/connect limits are explicit descriptor values from compatibility §7. The ordinary profile retains 64 KiB / 4 MiB and 20 s / 15 s / 5 s; every generic realization (read, mutation or page) requires 256 KiB / 4 MiB and 40 s / 30 s / 5 s. Policy evaluation's proposed 2 s ceiling is inside, not added to, the operation execution budget. Authentication, transport ingress, callbacks, session/control/data and delegation need their own bounded binding rules; ordinary unary support cannot stand in for those rules.

Identity token lifetime/verification comes from the explicitly selected Identity contract and deployment, not a universal lifetime invented by this document. The independent delegation/approval proof windows and nonce/spend rules are fixed by delegation §5. Audit admission and completion must be bounded inside the execution/delivery policy while preserving actual effect knowledge when a reply cannot be sent.

6. Conformance requirements

• The old reader matrix in compatibility §2 distinguishes shape-compatible version mismatch from unknown fields, bare errors and response correlation failure. No automatic fallback or invalid_input-to-unsupported rewrite.

• A new client explicitly selecting legacy codec sees only legacy semantics. Unsupported profile/version/authority fails before invoke; an invalid response after a sent mutation yields uncertainty, not safe retry permission.

• Guessed hidden mutation on legacy invoke is refused before dispatch; a new/full descriptor revision is not a projection revision.

• Missing/invalid credential or unknown envelope fields never create trusted body-sourced context. Safe pre-envelope replies use nullable request correlation and honest audit status/reference.

• Executor mismatch -> not_granted; policy outage -> unavailable, no dispatch. Describe/invoke authority changes are rechecked; realm None and default stay distinct.

• Admission-audit failure -> unavailable/no acknowledged ref/no dispatch. Final-audit failure after known success/refusal preserves that effect and original cause; a possible dispatch remains unknown.

• Every mutation outcome, including replayed refusal/abort/unknown, an uncertain waiter, inaccessible original and outcome-store failure, follows the exact status/classification/cause table.

• Delegation uses the selected canonical preparation/approval trace and exact proof fixtures in delegation.md, including valid/forged/replayed/expired/different-receiver/different-body, optional realm/executor, and describe/prepare/invoke separation. Actual verifier/store/provider conformance remains required before advertisement.

• The first binding's named scenarios are listed in compatibility §2.1: v1alpha2-describe-not-served, v1alpha2-invoke-wrong-version-unsupported, v1alpha2-invoke-refuses-connection, v1alpha2-invoke-refuses-idempotency-key, v1alpha2-invoke-refuses-approval, v1alpha2-invoke-refuses-executor, v1alpha2-invoke-unknown-member-invalid-input, v1alpha2-invoke-keyed-or-approval-operation-unsupported, v1alpha2-invoke-keyed-write-under-standing-grant, v1alpha2-invoke-keyed-replay, v1alpha2-invoke-write-outside-grant-refused, v1alpha2-invoke-read-audit-complete, v1alpha2-invoke-write-audit-complete, v1alpha2-invoke-write-audit-incomplete, v1alpha2-invoke-audit-anchor-refused, v1alpha2-invoke-write-applied-names-attempt, v1alpha2-invoke-write-refusal-before-attempt-has-no-mutation, v1alpha2-invoke-write-lost-answer-outcome-unknown, v1alpha2-invoke-write-provider-refusal-refused, v1alpha2-invoke-read-has-no-mutation and v1-invoke-unchanged-by-v1alpha2.

• Legacy/unselected read 401 gives one business call and its documented error. An explicitly supported combined read-refresh-once profile may give 401 → one coordinated exchange/publication → one freshly admitted redispatch; a second 401 is terminal. Expired time, consumed permission slots, narrowed grants, uncertain publication, cancellation and authority changes prevent redispatch according to the binding's textual case matrix. These are runtime obligations, not conformance established by the existing ESS models.

7. Compatibility

The common compatibility document supersedes all earlier projection/version defaults here. The extended service envelope retains v1 semantic-family names; it changes no adapter-specification format. Explicit legacy selection is a separate codec and admitted surface, not stripping fields from an arbitrary governed operation.

Old OwnerContext fields are characterization input, not trusted new context. Tenant/principal/realm must be established again by authentication; executor claims require receiver verification. Description and audit references need explicit facade mapping without equating old execution_ref to an attempt ID merely because both are strings. Historical destructive classifications require reviewed mutation curation. Old CLI protocol flags and source dependency names have separate migration decisions; a multi-codec client is allowed when selection is explicit and no fallback occurs.

8. SDK and host obligations

Obligation	Owner / boundary
Two explicit strict codecs/routes, descriptor/profile/limit selection, safe early errors and exact observation/audit shapes	future core/client/host binding; current crates stay v1alpha1
Authentication, current policy and executor/grant verification	host ports; static configuration, Identity audience and delegation are explicit different bindings
Audit admission plus linked final observation and truthful failure handling	host persistence port; no prescribed JSONL/store implementation here
Mutation attempt/approval/idempotency semantics	operations contract and existing ESS domains; wire values do not implement the dispatch fence
Delegated request/approval subjects and verification	F03 proposal; runtime binding must implement and prove it, with no broad-token substitute
Safe auth/connection metadata and protected acquisition ingress	auth family owner stories; ordinary invoke is not secret entry
Adapter authoring curation and generated schemas	Connectors-owned kind/compiler compatibility decision separate from this wire; no silent strict-format extension
CLI, service-sdk, Secrets, Identity and consumer bindings	later explicitly scoped implementation/modeling work; no external consumer or Atlas mutation authorized here

9. ESS values and unresolved owner models

Public Version, ErrorCode, MutationObservation, DiagnosticCause, AttemptReference, AuditStatus/SourceAudit, AuthAlternative and OperationLimits values, and the first binding's InvokeRequest, InvokeResponse, ResponseStatus and Error, are typed in service_wire.yaml. Effect knowledge and attempt identity reference the existing mutations types. Required-null versus omitted members are declared there with presence:. This is no runtime decoder or public attempt lookup API; the InvokeResponse cross-field rules project only as schema annotations and remain explicit codec obligations.

Authenticated/admitted contexts remain host values whose trusted derivation belongs to their owner bindings. The execution-audit owner now selects AuditRecord's private host-qualified identity, one acknowledged anchor and at most one final observation, with optional references to existing attempt and Connection records. Its ESS model declares those relations and lifecycle; actual storage acknowledgements, atomic append and trusted correlation remain implementation obligations. Grant configuration and SaaS tenant/principal ownership remain separately selected work. This document introduces no stub entity or inferred cardinality to satisfy validation.

10. Remaining binding decisions

Implement and prove the selected F03 delegation binding; choose and model policy/audit persistence bindings; verify executor and Identity/Secrets integration against their authoritative contracts; define protected callback and duplex/data codecs; and run version/profile/failure conformance before any advertisement. The wire identifier, paths, field/error shapes and legacy projection rules in compatibility.md are this local proposed contract, not unresolved implementation defaults. Consumer rollout, package installation, Atlas registration and external publication remain separately authorized work.

Private connectors.declarations.OperationAvailability and AvailabilityDecision record selected availability facts and a projection/lookup decision. They are not public descriptor fields, policy assertions, persistent entities or a computed admission algorithm. ESS does not enforce §3.2.1, result authority, revision changes, federation intersection or any dispatch fence.