# Connector V2 Execution Architecture

Status: candidate target architecture for Connector V2. This document is a
design reference, not an automatic implementation backlog. A current-tree
closure decision must select the parts needed to resolve a proved production
contradiction before they become implementation requirements. This document
does not change the currently serving V1 protocol. The existing WorkItem and
source-projection documents remain the sole production authority until
exhaustive supported-path qualification passes and one atomic whole-service V2
activation commits after V1 drain, process termination, and provider-egress
isolation. No walking slice, conformance claimant, partial account wave, or
pre-activation repository may admit V2 work, claim it, or perform provider I/O.

## Decision

Connector V2 is a replacement execution model, not another compatibility layer
inside V1 WorkItem. Its design follows one rule throughout:

> One fact has one owner, one source of truth, and one read path.

V2 therefore separates immutable transport and application facts from mutable
claims, dependencies, and external-effect progress. It binds every admitted
fact to one exact serving generation and never falls back to mutable pack,
route, mapping, or tenant configuration.

V2 is provider-neutral. L0 contains reusable integration mechanism only. A
provider name, object name, event vocabulary, field mapping, or tenant decision
must not appear in L0 code or schema.

The V1-to-V2 upgrade is a planned, whole-service maintenance cutover, not a
rolling or backward-compatible transition. Source owners first stop new V1
root work while the unchanged V1 runtime finishes everything it already
accepted, including any required outbound work. The old V1 deployment is then
terminated and its provider-egress capability is isolated before a durable
shutdown certificate can move the service to `v1_drained`. A complete
post-drain V1 recovery point then preserves a cold rollback window while the V2
candidate is applied and validated with every production execution path
disabled. The atomic first V2 production activation closes that window. V1 and
V2 claimants or dispatchers never run simultaneously.

First V2 activation and V2-to-V2 succession are different protocols. First
activation is whole-service because unchanged V1 claimants and dispatchers do
not read `AccountServingGate`, provider-egress isolation applies to a deployment
generation, and cold rollback restores one complete database. Activating one
account at a time would require simultaneous V1 and V2 execution plus
per-account process, egress, transport-identity, ordering, and restore
isolation. This architecture defines none of those boundaries; a per-account
first activation requires a separate protocol and cannot be inferred from the
presence of per-account gate rows.

After first activation, every change to any frozen byte, including Catalog
lineage or receipt changes when binding rows otherwise match, mints an exact
successor ServingEpoch. The supported successor transition is `requires_drain`;
apparent compatibility or operator assertion never permits in-place mutation of
the active epoch or bypasses the terminal-work and ordering-handoff proof.

No `online_compatible` successor class is currently authorized. Defining one
later requires a versioned mechanical compatibility proof over the complete
canonical owner views and an atomic predecessor-to-successor transition. At a
minimum, that proof must establish unchanged transport identity, route
selection for admitted facts, ordering partition/comparator/successor
semantics, Runtime command/result correlation, outbound effect identity and
request semantics, and every credential generation used by crossing work. It
must also define a dual-epoch gate and fence protocol under which new admission
binds only the successor while predecessor facts finish under their original
epoch, with real-TiDB concurrency and crash proof. Any unproved field or
unsupported digest-profile change remains `requires_drain`.

## Ownership boundaries

| Fact | Owner and source of truth | Sole read path |
| --- | --- | --- |
| Authorized connector binding membership | Catalog `IntegrationBindingView`, referencing exact immutable pack generations | Exact-generation Catalog view; a binding row is authorization and identity, never standalone definition proof |
| Connector binding definition payloads | Exact pack-installation or local definition owner for inbound route, callout profile, field mapping, and push contract | Kind-specific exact-generation owner reader by complete Catalog binding identity and payload digest |
| Tenant connector configuration | L2 `ConnectorServiceConfigurationGeneration`, containing the exhaustive ordered account set, enabled route references, tenant mapping selections or overrides, policy values, and the exhaustive account/binding-credential-to-generation relation | Exact-generation owner read by ID and byte-comparison with its deterministic receipt |
| Credential configuration | Connector credential-generation authority over L2-authored immutable `CredentialGeneration` facts | Exact generation ID and immutable secret-backend version reference; mutable credential names are authoring locators only |
| Credential dispatch eligibility | Connector `CredentialGenerationDispatchGate`, changed only by authorized L2 revocation or reenablement policy | Permit acquisition and `granted -> sending` lock the exact generation gate and compare its fence; status never mutates `CredentialGeneration` |
| Canonicalization and digest semantics | Versioned neutral `ConnectorDigestProfile` contract | Closed profile selected by exact ID; unknown, cross-profile, or no-longer-readable profiles fail closed |
| Verified execution generation | Connector `ServingEpoch` | Serving-epoch repository, addressed by exact ID and digest |
| Cutover readiness and liveness admission | Connector `CutoverReadinessCertificate` over the exact L2 budget plan and authoritative owner proofs | Cutover coordinator, addressed by unique service cutover attempt and binding exact ServingEpoch and configuration generation |
| V2 account admission and protocol mode | Connector `AccountServingGate` | One fenced per-account row read by every V2 ingress, replay, claim, outbound-authoring, and dispatch path, plus the cutover coordinator |
| V1 root-work maintenance barriers | Ingress and application/API owners, frozen in Connector `MaintenanceBarrierReceipt` | Cutover coordinator verifies exact owner and service-cutover-attempt references |
| V1 execution and external-effect state | Existing V1 repositories until first `v2_serving` | Cutover inventory readers selected by the frozen current-tree egress and state manifest; cold rollback restores this complete authority before V1 restarts |
| V1 deployment termination and provider-egress isolation | Deployment supervisor and egress controller, frozen in Connector `V1ShutdownCertificate` | Cutover coordinator verifies exact process-generation and egress-isolation receipts |
| Offline V1 shutdown certification | Connector `V1ShutdownCertificate` | Cutover coordinator, addressed by exact service cutover attempt and evidence digests |
| Whole-service cutover coverage | L2 `ConnectorServiceConfigurationGeneration` and Connector gate repository, frozen only as digests in `V1ShutdownCertificate` | Cutover coordinator rereads both owners and byte-compares the exhaustive account/gate set before each phase |
| Activation-time external-owner freeze | Catalog, every binding-definition owner, L2 configuration, and credential authorities, each holding a fenced publication barrier whose receipt is frozen in Connector `ServingPublicationBarrierSet` | Activation coordinator, addressed by exact activation attempt and owner fence until post-commit readback |
| Cold V1 rollback authority | L2 release/restore coordinator and database backup owner, frozen in `V1RestorePoint` | L2 `RestoreAttempt` consumes one exact post-drain snapshot plus previous V1 release tuple; Connector only verifies its receipt |
| Activation-versus-restore decision | L2 `CutoverDecision` | One durable CAS journal outside the restored database; activation and RestoreAttempt resume the winning decision rather than relying on timeout |
| Transport idempotency identity | Connector `ReceiptAdmissionKey` | Receipt repository, with one key namespace across retained V1 identities and V2 Receipts |
| Accepted transport input | Connector `Receipt` | Receipt repository |
| Normalized external event | Connector `Event` | Event repository |
| Explicit replay authorization | Connector `ReplayRequest` | Fenced replay-admission repository, addressed by stable ReplayRequest ID and the current AccountServingGate transaction |
| Source ordering and claim guard | Connector `OrderingLane` | Ordering-lane repository and fenced compare-and-swap |
| Cross-epoch ordering transfer | Connector `OrderingHandoff` | ServingEpoch activation repository, addressed by exact predecessor/successor epoch, route, and partition |
| Application input | Connector `Projection` | Projection repository |
| Execution ownership | Connector `Execution` | Execution repository and lease compare-and-swap |
| Application outcome | Runtime `ApplicationResult` | Runtime result service, addressed by exact Command ID and ExecutionRef digest |
| Outbound application intent | Runtime `OutboundCommand`, inserted by the owning application transaction | Runtime outbound-command feed, addressed by stable OutboundCommand ID |
| External side effect | Connector `RemoteEffect` | Remote-effect repository |
| V2 provider-I/O authorization | Connector `DispatchPermit` | Sole Connector V2 egress adapter, addressed by exact Permit ID and holder fence |
| External identity | Connector `RemoteLink` | Remote-link repository |
| Audit evidence | Platform audit service | Platform audit read path; audit never controls execution |

`ServingEpoch` is an execution admission fact, not a second metadata registry.
It records the admitted Catalog view digest, exact pack and Runtime generations,
the exact `ConnectorServiceConfigurationGeneration`, exact references to every
`CredentialGeneration` and their owner receipts, the
`ConnectorDigestProfileID`, and deterministic verification receipts from those
owners. It does not copy editable definitions or accept a caller-echoed receipt
as verification. An OutboundCommand freezes the exact credential-generation
reference selected from its epoch; each effect Attempt records the same
reference as dispatch evidence. Secret material is never copied into
ServingEpoch or another durable execution fact.

`CredentialGeneration` owns immutable configuration identity; revocation is a
different mutable fact. `CredentialGenerationDispatchGate` is keyed by exact
generation ID and carries an eligibility mode plus fence. Permit acquisition
locks it in the same transaction as the account gate, requires `enabled`, and
copies its current fence into the Permit. An authorized revocation locks the
same row, advances its fence, and blocks every later Permit. Because `granted`
is still durably pre-I/O, the sole egress adapter must lock this generation gate
again during `granted -> sending` and require the copied fence and `enabled`
mode. Revocation committing first makes that Permit safely abandonable with
proof of no I/O; `sending` committing first authorizes its one call, after which
revocation may commit and the Attempt must settle. Revocation never rewrites the
generation or an existing Permit. Reenablement, if policy permits it, advances
the fence again and cannot revive an abandoned or terminal attempt.

`CutoverReadinessCertificate` is immutable and unique by service cutover attempt.
It binds the exact ServingEpoch ID and digest and exact
`ConnectorServiceConfigurationGeneration`, and freezes every route's ordering
migration disposition and proof, the L2-authored quantitative budget plan,
representative measurements and conservative projections, and the closed
reason-code, alert, owner, and remediation map. Changing any input creates a new
attempt and certificate; the cutover coordinator has no fallback to an operator
note or mutable deployment default.

`ServingPublicationBarrierSet` is activation evidence, not another metadata
authority. Before first or successor activation, the coordinator acquires a
fenced barrier from the Catalog, every binding-definition owner, the L2
configuration owner, and credential authority for the exact candidate scope and
owner generations. Every authoring,
publication, current-selector, or credential-revocation write for that scope
must lock its owner barrier and fail while the activation attempt holds it. The
coordinator verifies and freezes the exact owner receipts, holds all barriers
through the local activation commit and exact readback, and releases them only
after the outcome is durable. Barriers do not expire into release; only an
explicit fenced release may reopen publication. While first activation remains
`CutoverDecision=rollback_open`, an urgent credential-revocation request aborts
the attempt and releases the barrier before applying the revocation; it never
bypasses the fence. After `activating_v2` wins, the request waits through
activation and readback, then applies forward after release. For a successor,
urgent revocation aborts before its local activation transaction begins and
waits after that transaction records `activation_committed`. A missing,
released, or mismatched barrier blocks activation.

The barrier set is crash-recoverable rather than lease-healed. A coordinator
writes `acquiring` before requesting owner fences and records each receipt
idempotently. For first activation, a fenced successor coordinator for the same
attempt loads `CutoverDecision` and the exact owner receipts: while rollback
remains open it may resume acquisition or explicitly release; if restore wins
before the activation commit, it must release so restore can proceed; after
activation wins it must resume activation; after the local commit it verifies
readback and releases. For V2-to-V2 succession, recovery reads the atomic local
barrier-set state: `held` proves there was no activation commit, but release may
resume the predecessor only when no OrderingHandoff exists; after that cutoff,
release is legal only for fenced forward replacement while all gates stay
halted. `activation_committed` requires readback before release. Holder fences
reject a stale coordinator's acquire or release, and an
alert deadline escalates a held set without treating elapsed time as release.

## Layer contract

L0 owns:

- account serving gates, receipts, idempotency, canonical identity, source-order
  guards, claims, leases, dispatch permits, fencing, retries, dependencies,
  projection windows, result receipts, and audit emission;
- provider-neutral verification of V1 shutdown and restore-point receipts; the
  deployment supervisor, database backup owner, egress controller, and L2
  restore coordinator remain the owners of process, snapshot, restore, and
  network-isolation facts;
- provider-neutral webhook, polling, stream, file-ingress, callout, credential,
  throttle, cursor, and reconciliation mechanisms;
- interpretation of closed Connector digest profiles, authoritative verification
  of exact binding-definition, L2, and credential generations, and fail-closed
  exact-generation resolution without secret-byte persistence in execution
  facts;
- credential-generation dispatch gates, immutable cutover-readiness
  certification, and verification of externally owned publication barriers;
- interpreters and extension contracts whose behavior is selected by an exact
  generation.

L1 connector/application packs own:

- component extraction and event normalization definitions;
- routes, grouping and window policy, application projections, field mappings,
  field ownership, match policy, and remote-effect classification;
- provider protocol extensions when the generic interpreters are insufficient.
  Such extensions implement a neutral contract and are bound by generation;
  L0 never imports them.

L2 owns:

- authoring one immutable `ConnectorServiceConfigurationGeneration` containing
  the exhaustive ordered account set, provider organizations, enabled route
  references, tenant mapping selections or overrides, tenant-owned policy
  choices, and exact credential-generation selections;
- credential material and rotation decisions expressed through immutable
  generations, credential revocation and reenablement decisions, the
  quantitative cutover budget plan, cutover authorization, exact V1 release
  selection, full-database recovery-point capture, and cold restore.

## Existing foundations and schema ownership

V2 reuses the current `IntegrationBindingView`, durable Runtime command inbox,
`RuntimeCommandHandoff` transport adapter, Flow command codecs, Runtime worker
supervision, named-credential resolution, callout transport, and immutable pack
generation authority. Acceptance into the Runtime inbox remains useful, but it
is not application completion. The V1 handoff receipt remains a V1 recovery
ledger until V1 drains; V2 completion is based only on Runtime
`ApplicationResult`.

Reusing named credentials means reusing the generic resolver and transport
mechanism; a mutable NamedCredential row or developer name is not V2 execution
authority. Rotation mints an immutable `CredentialGeneration` containing the
stable credential identity, generation ID, provider/account scope, immutable
secret-backend version reference, and digest of non-secret transport
configuration. Rotation also requires a new
`ConnectorServiceConfigurationGeneration` and successor ServingEpoch. The
Connector never copies secret bytes into an epoch, receipt, command, or effect
fact. Generation metadata and its owner receipt remain readable while admitted
work references them. ServingEpoch verification reads that metadata, never
secret bytes. Dispatch resolves the exact secret-backend version at use time;
revocation may make it unavailable under the frozen remediation policy but
never silently falls forward to newer material.

Before `prepared -> verified` exists, L2 must expose one authoritative
exact-generation reader for `ConnectorServiceConfigurationGeneration`. Its
canonical bytes contain the exhaustive, deterministically ordered account set
and each account's enabled route references, tenant mapping selections or
overrides, policy values, and one canonical exhaustive relation from
`(account, binding CredentialRef)` to `CredentialGenerationID`. Every mapped
generation's stable credential identity and account/provider scope must match
the binding reference. Missing, extra, or duplicate mappings are invalid. The
owner returns a deterministic, byte-stable receipt. Connector rereads that
owner by exact generation ID and reconstructs the digest; candidate bytes or an
opaque caller-supplied receipt alone prove nothing.

Catalog verification likewise fresh-reads the exact `IntegrationBindingView`
and then verifies the referenced owner definition for each of the four closed
binding kinds: inbound route, callout profile, field mapping, and push contract.
A Catalog revision is a freshness lower bound, not an exact historical
selector, so verification byte-compares the complete current view, lineage,
receipts, ordered bindings, and every owner generation against the prepared
candidate. A temporarily unavailable owner leaves the candidate `prepared`;
authoritative absence, mutability, or mismatch must move it to `rejected`.
Each exact definition generation and its receipt remain immutable and readable
while an active or resumable ServingEpoch references them; uninstall or
retention cannot strand the sole definition read path.

Connector code does not own system-table DDL. New V2 physical tables and
indexes are declared once in the NexusCRM schema catalog; controlplane consumes
the published catalog and converges it. Connectors add a repository only after
that schema is available, and only in the same slice as a real writer/read path.
No unused table, shadow registry, or connector-local DDL becomes a second
schema authority.

## Compressed durable model

The mandatory inbound chain is intentionally short:

```text
ServingEpoch
  ReceiptAdmissionKey -> Receipt { ReceiptComponent* }
    -> Event
      -> Projection { ProjectionWindow? }
        -> Execution { ExecutionAttempt*, ExecutionDependency* }
          -> Runtime-owned ApplicationResult
```

The outbound chain is independent, but it is admitted under one exact epoch:

```text
Active ServingEpoch
  -> Application transaction
    -> OutboundCommand [frozen dispatch binding]
      -> RemoteEffect { RemoteEffectAttempt { DispatchPermit? }* }
        -> RemoteLink?
```

The braced records are subordinate ledgers, not additional peer authorities.
Audit is omitted from both chains because it observes transitions and never
decides them.

The one-time offline cutover has a separate, non-executable evidence chain:

```text
CutoverReadinessCertificate
  + MaintenanceBarrierReceipts
  + frozen ConnectorServiceConfigurationGeneration and exhaustive gate-set digest
  + initial V1 zero-work observation
    -> ProcessGenerationTerminationReceipt
    + ProviderEgressIsolationReceipt
      -> v1_stopped
        -> post-isolation terminal-state inventory
        + identity and ordering coverage
          -> V1ShutdownCertificate -> v1_drained
            -> full-database post-drain snapshot + exact V1 release tuple
              -> V1RestorePoint -> v2_validating
                -> atomic ServingEpoch activation + v2_serving
                \-> cold restore -> v1_drained -> v1_serving
```

`V1ShutdownCertificate` is not a compatibility execution model and grants no
V1 work or provider I/O. It freezes exact owner references and evidence digests
needed to prove that the old process generation cannot execute again. A
termination receipt must prove that the supervisor disabled that exact
generation and cannot restart it, not merely that its observed replica count
was zero. Cold rollback never revives it: after restoring the full V1 recovery
point, the coordinator starts a new process generation of the exact certified
V1 release. A reset-only backup receipt without a tested full restore path is
not a `V1RestorePoint`. If the environment cannot isolate generations, capture
and restore the full database, or fence provider egress, this upgrade is
unsupported.

`V1RestorePoint` is an externally durable recovery receipt, not another live
Connector state owner. The database backup owner creates it after the final
`v1_stopped` reconciliation and `v1_drained` commit, and before any V2 schema or
data mutation. It binds a transactionally consistent full-database snapshot or
log position, its schema and content digests, the exact V1 release and
configuration tuple, the shutdown certificate, source cursors, exhaustive
account/gate set, and reconciled external-effect evidence. The L2
`RestoreAttempt` journal and recovery receipt live outside the database being
restored, so a crash can resume without trusting candidate V2 state. A recovery
point is valid only after an isolated restore rehearsal proves those bindings
and the exact V1 binary can read the restored database. A snapshot taken before
the final V1 reconciliation is invalid because it could omit provider outcomes
that completed during the drain.

The external L2 `CutoverDecision` is the sole activation-versus-restore owner:
`rollback_open -> activating_v2 -> v2_committed` or
`rollback_open -> restoring_v1 -> v1_restored`. It never changes branch because
a timeout elapsed. A successor may resume the same branch only after isolating
the prior coordinator and comparing the database state. An `activating_v2`
recovery that observes the atomic V2 database commit must finish
`v2_committed`; a `restoring_v1` recovery must finish or safely restart that
same RestoreAttempt. Thus an external restore cannot race a database activation
without first winning the one durable decision.

### Inbound facts

- **ReceiptAdmissionKey** is the sole transport-idempotency authority across
  the protocol boundary. It is unique by connector account, ingress channel,
  and transport idempotency key and points either to one V2 Receipt or to an
  immutable V1 acceptance tombstone containing the authorized payload digest
  and predecessor ref. The V1-to-V2 upgrade imports only these non-executable
  identity tombstones after V1 drains. New V2 admission locks the account gate
  and its exact ServingEpoch, requires `v2_serving`, current gate fence and
  epoch state `active`, then atomically reserves the key and Receipt; a
  duplicate loads and byte-compares the existing key. A matching V1 tombstone
  returns already accepted and creates no V2 descendant; a digest mismatch
  fails closed. This is identity preservation, not replay or migration of V1
  work.
- **Receipt** is immutable evidence for one accepted V2 admission. A transport
  Receipt is bound to one ReceiptAdmissionKey. A replay Receipt is outside the
  transport namespace and is unique by account and stable ReplayRequest ID. A
  retry of a V2 transport key resolves the original V2 Receipt; V2 never adopts
  a V1 Receipt or epoch.
- **ReceiptComponent** is one deterministic item extracted from a possibly
  batched Receipt. It is keyed by Receipt and ordinal. It has no worker state.
- **Event** is an immutable, normalized external event with an opaque payload,
  canonical event kind, external source locator, occurrence time, L1-owned
  SourceEventKey, typed source-order facts, and EventGeneration identity. It has
  no lease, retry counter, or execution-owner fields. Live admission has one
  canonical generation; replay uses the authorizing ReplayRequest ID as a new
  generation and keeps predecessor lineage outside the live identity.
- **ReplayRequest** is immutable operator authorization, never an Event state.
  It binds one target V2 ServingEpoch to a disclosure-safe predecessor ref:
  protocol version, V1 Receipt/Event/WorkItem identities, original epoch,
  payload/result digests, requested reason, and authorizing principal. The ref
  is read-only evidence, not a claimable foreign owner. Duplicate submission of
  the same ReplayRequest ID must byte-match and resolves the same V2 descendants.
  Creation is a V2 admission write: its transaction locks AccountServingGate
  and the exact ServingEpoch, requires `v2_serving`, current fence, an exact
  gate-to-epoch match, and epoch state `active`, then atomically inserts the
  request and replay Receipt.
- **Projection** is an immutable application-input generation derived under one
  route definition. It owns the canonical projection identity and the pointer
  used to mint at most one active Execution generation.
- **ProjectionWindow** is optional. Immediate routes skip it. Grouped, latest,
  batch, or settle policies use one explicit window with an immutable grouping
  key and close policy. Orthogonal metadata dimensions replace a growing list
  of invocation-mode names.
- **Execution** is one immutable execution generation. Retry reuses its stable
  identity; replay, changed input, or changed definition mints a successor
  generation with explicit lineage.
- **ExecutionAttempt** is append-only operational evidence for one claim. A
  lease is temporary worker ownership and is not a semantic execution state.
- **ExecutionDependency** owns a requirement and immutable deadline. Waiting
  does not hold a worker lease and is never represented as `processing`.

### Durable source ordering

Arrival time and database insertion order never decide application order. Every
exact L1 route freezes one `OrderingContract` in its ServingEpoch:

- `order_independent` is allowed only when route conformance proves operations
  commute or otherwise cannot overwrite newer source state;
- `latest_source_position` requires a canonical OrderingPartition, typed totally
  ordered SourcePosition, deterministic tie-breaker, and settle policy; or
- `strict_source_sequence` additionally requires an exact successor rule and a
  frozen gap deadline/disposition.

Event stores the contract digest, OrderingPartition, SourcePosition kind/value,
and tie-breaker as exact bytes. L0 interprets only the closed generic ordering
shape; L1 owns extraction and the comparator version. A route with neither an
order-independent proof nor complete source-order facts cannot pass the V2
cutover preflight and therefore never enters maintenance.

`OrderingLane` is the sole mutable claim guard, unique by ServingEpoch, route
definition identity/version, and OrderingPartition. It stores the completed
high-water source position, the immutable baseline from which that high-water
was established, and at most one active Execution. Claim and terminal result
recording use fenced compare-and-swap:

- `order_independent` bypasses the lane;
- `latest_source_position` seals any configured settle window, selects only the
  greatest ready position, and records lower or late positions as append-only
  superseded decisions without calling Runtime;
- `strict_source_sequence` claims only the exact successor; a gap waits without
  a worker lease and then follows the frozen deadline disposition.

The lane high-water advances only when the active Execution's Runtime result
receipt is durably recorded under the frozen terminal-disposition policy. A
failed or ambiguous execution cannot release a later position by lease expiry.
Replay inherits the predecessor's source-order facts and enters the same guard;
it cannot bypass a newer high-water mark.

Before maintenance begins, every enabled account and route receives one
immutable ordering-migration disposition in the exact
`CutoverReadinessCertificate`:

- `order_independent`, with its exact conformance proof;
- `v1_high_water`, only when the current V1 owner exposes a typed durable
  position, comparator, tie-breaker, and exhaustive partition set;
- `provider_snapshot_barrier`, with lossless ingress fencing, exhaustive
  partition enumeration, canonical positions, and a bounded capture and retry
  contract; or
- `unsupported`.

`EnqueueOrdinal`, arrival order, or the existence of a V1 queue row is not a
source high-water proof. Any `unsupported` route blocks the whole-service first
activation unless a separately authorized
`ConnectorServiceConfigurationGeneration` disables it before the exhaustive
account set is frozen. Eligibility is established by
dry-run preflight and reverified against that frozen generation before shutdown
certification. Final positions may be captured after the drain, but the cutover
must execute an already proved plan rather than discover ordering infeasibility
after V1 has stopped.

An order-dependent route may cross the V1-to-V2 gate only with a byte-exact
`OrderingBaseline` for every partition. The halted upgrade derives it from the
drained V1 ordering authority or from an L1-defined provider snapshot barrier
captured while ingress is fenced. The baseline records its origin, comparator
version, last completed source position, tie-breaker, and evidence digest, and
is installed as the initial OrderingLane high-water before V2 admission opens.
It does not migrate a V1 event or make that event claimable by V2. If V1 lacks
a comparable durable high-water and no snapshot barrier can establish one, the
route is `unsupported` and the cutover attempt is rejected before maintenance;
it is never allowed to apply updates in arrival order.

A successor V2 ServingEpoch never starts an order-dependent lane from an empty
or independently sampled high-water. Before activation, whole-service owner
barriers close live ingress, replay, and root outbound authoring. Every
predecessor Receipt descendant, Window, Execution, OutboundCommand,
RemoteEffect, and DispatchPermit reaches a terminal decision and every gate
reaches `v2_halted`. The `OrderingHandoff` transaction then locks the
predecessor lane and fence, proves that it has no active or nonterminal
execution, freezes its final high-water, comparator and partition contract, and
invalidates every stale predecessor claim. A predecessor result race either
commits first and is included in the high-water or causes handoff to fail; it
cannot advance the lane after the handoff fence commits.

The successor lane is staged with that exact handoff as its immutable baseline.
ServingEpoch activation locks and byte-compares every required handoff and lane
before making the successor epoch active. If comparator or partition derivation
changes, the L1 contract must provide a total, deterministic transformation and
snapshot barrier that covers every successor partition; otherwise activation
is rejected. `order_independent` routes require their existing conformance proof
but no lane handoff. Consequently a successor position `99` is superseded when
the predecessor handoff certified high-water `100`; it cannot execute merely
because it belongs to a new epoch.

### Runtime-owned result

Runtime owns `ApplicationResult` because only Runtime can commit application
behavior. It commits the result atomically with the application transaction or
with an outbox in that transaction. The result is immutable and addressed by
the Runtime Command ID plus the digest of the complete ExecutionRef carried
once in the V2 command payload. That ref includes the Connector Execution ID,
opaque PackGeneration ID, serving-epoch digest, definition identity, and input
digest; these facts are not copied into a second Runtime identity surface.

Submitting the same command and ExecutionRef digest returns the existing
result. A mismatched digest is indistinguishable from a missing result and
fails closed. A Connector worker response, successful handoff, HTTP status, or
expired lease is never evidence that application behavior committed.

Connector stores only immutable result correlation: Command ID, ExecutionRef
digest, result digest, and Runtime commit receipt. Outcome remains Runtime's
source of truth and is read from Runtime; the generic contract does not copy
the raw result payload into Connector. An execution admitted to Runtime can be
marked complete only from that receipt.

### Outbound facts

- **OutboundCommand** is Runtime's immutable outbox intent, inserted atomically
  with the application transaction that requested the external effect. Its
  stable logical-effect key is `(trusted application scope, EffectRootID,
  EffectSlotID, EffectGenerationID)`. EffectRootID is derived from the original
  application intent and is preserved through replay lineage; the exact
  metadata-authored slot distinguishes multiple effects from one operation.
  The initial EffectGenerationID is stable across application transaction and
  outbox retries. Its canonical tuple digest is the immutable
  `OutboundCommand.IdempotencyKey`; the derived OutboundCommand ID and a unique
  constraint on the same tuple make a retry the same intent.
- **FrozenDispatchBinding** is carried by OutboundCommand and contains the exact
  Connector account, ServingEpoch ID and digest, owner PackGeneration ID and
  payload digest, effect definition ref/version, route/policy digest, versioned
  `ConnectorServiceConfigurationGeneration`, immutable
  `CredentialGeneration`, `ConnectorDigestProfileID`, and canonical request
  digest. It also binds EffectRootID, EffectGenerationID, and any
  successor-effect authorization and predecessor digest. When the frozen L1
  contract supports remote idempotency, it contains the one exact provider
  idempotency key; all Attempts reuse that key, and its absence is explicit.
  Secret bytes are never stored. Missing,
  revoked, or mismatched exact references fail closed; dispatch never
  substitutes the current account, route, policy, pack, configuration, or
  credential. The application transaction locks the account gate and its exact
  ServingEpoch, requires `v2_serving`, current fence, exact ID and digest match,
  and epoch state `active` while authoring the command; it never consults the
  mutable admission pointer again for that command.
- **RemoteEffect** is the sole lifecycle authority for one logical external
  side effect. It has one required, unique foreign key to OutboundCommand and
  repeats that command's logical-effect digest for fail-closed comparison.
  Outbox redelivery loads the same row; it cannot create a second dispatchable
  effect. Attempts append request, idempotency, response, and reconciliation
  evidence without becoming the effect's state authority.
- **DispatchPermit** is the durable, one-shot V2 authorization for the sole
  egress adapter to cross the provider-I/O boundary for one
  RemoteEffectAttempt. It is acquired in the same transaction that locks
  AccountServingGate, verifies its
  mode and fence token, locks the exact `CredentialGenerationDispatchGate`,
  requires its `enabled` mode, binds both fences and the frozen dispatch facts,
  records a `granted` Permit, transitions the effect to `dispatching`, and adds
  the Permit to the account gate's open-permit set. An Attempt has at most one
  Permit. To send bytes, the adapter must lock and revalidate the same
  credential gate and win the Permit-and-holder-fenced
  `granted -> sending` compare-and-swap that records `io_may_have_started`;
  every later invocation is rejected. Both `granted` and `sending` remain open
  across the provider boundary. A Permit is not a lease and does not expire
  into safety.
- **RemoteLink** is the optional, provider-account-scoped authority connecting
  a local owner slot to a proven remote identity. It is separate from field
  ownership and exists only after remote identity is unambiguous.

The V2 replacements for connector-push and connected-delivery converge on this
one effect model. Their V1 implementations remain unchanged until the offline
shutdown and are never read by V2; they must not survive as parallel sources of
truth for the same external effect.

## Identity rules

V2 does not encode type, namespace, generation, or ownership in a concatenated
Work ID. Internal relations use typed identifiers and foreign keys.

Every external locator and metadata key is canonicalized and validated before
insert, then compared byte-for-byte. Noncanonical whitespace, empty values,
invalid encoding, and ambiguous null/blank representations are rejected. Query
time `TRIM`, case folding, or fallback normalization is forbidden because it
creates a different identity read path from uniqueness and lookup.

Every V2 Connector-owned durable digest governed by this architecture is paired
with an exact `ConnectorDigestProfileID`. The closed profile defines its domain
separator, included fields, field order, length framing, text and binary
encodings, null representation, normalization rules, and digest algorithm. The
profile ID participates in the ServingEpoch digest and in every frozen binding
or request digest derived under it.

The supported ServingEpoch digest states are exact and disjoint:

| Stored form | New authoring | Retained read | Semantics |
| --- | --- | --- | --- |
| Legacy unprofiled | Rejected | Exact legacy reader only | The reproducibility header and every binding-owner and credential-generation side row are absent. The candidate is inert, can never become `verified`, and is replaced rather than assigned an inferred profile. |
| `nexuscrm.connector-digest-profile.v1` | Rejected | Exact V1 reader | V1 bytes remain byte-stable and are interpreted only by the V1 recipe. They are never recomputed, relabeled, or compared as V2 bytes. |
| `nexuscrm.connector-digest-profile.v2` | Permitted | Exact V2 reader | V2 is the sole profile that can author a complete profiled prepared candidate. Its complete reproducibility graph is required; a missing header, missing or extra proof, or mixed-profile graph is invalid. |

An empty profile ID is not an alias for any row in this table. A resolver never
infers V1 or V2 from digest shape, table age, or the presence of legacy base
rows. Read support cannot be removed while an active epoch or any nonterminal,
resumable, or retained fact references that profile. A profile change mints a
new exact generation; stored bytes and digests are never silently recomputed.

The V2 ServingEpoch preimage has one closed nested order:

1. The V2 epoch domain prefix, which frames the exact V2 profile ID, followed by
   the epoch ID and ServingScopeDigest.
2. The Catalog attestation: organization, application installation, authorized
   workload, lineage revision tuple, source snapshot and view digests, then the
   receipt protocol, repeated revision tuple, security epoch, and capability
   version.
3. The Service Configuration proof: generation protocol, receipt protocol,
   exact generation ID and generation digest, then exact owner receipt bytes and
   owner receipt digest. These fields form the Service Configuration component
   of the complete reproducibility envelope.
4. The binding count, then each Catalog binding in ordinal order. Every item
   appends its ordinal, derived row ID, identity digest, kind, OwnerPack,
   PackInstallationID, PackPayloadDigest, BusinessKey, definition version,
   canonical CredentialRefs blob, and exact optional Runtime tuple. Its
   binding-owner proof immediately follows: opaque PackGeneration storage ID,
   definition-envelope version, definition-receipt version,
   canonical-definition digest, exact definition-owner receipt bytes, and
   definition-owner receipt digest. The proof identities must match the Catalog
   binding set one-for-one.
5. The credential-generation proof count, then the exhaustive unique generation
   set in ascending byte order by exact CredentialGeneration ID. Each proof
   appends its zero-based ordinal, exact generation ID, receipt protocol,
   transport-configuration digest, exact owner receipt bytes, and owner receipt
   digest. The set must equal the credential generations referenced by the
   Service Configuration generation; duplicates, omissions, and additions are
   invalid.

Counts and ordinals use the profile's fixed-width integer encoding. Text and
binary values use its length framing, and every receipt is defensively copied.
The V2 profile does not retain canonical binding-definition bytes, Service
Configuration payload bytes, credential transport configuration, or secret
material in ServingEpoch. It does not recanonicalize or independently replace a
Catalog ViewDigest, pack payload digest, Service Configuration generation or
receipt digest, binding-owner digest or receipt, credential transport digest or
receipt, or any other owner fact. Each external owner validates its own
versioned canonical bytes and digest; Connector includes the resulting identity,
digest, and receipt as exact opaque bytes in the V2 preimage. In particular, the
stored L2 verification receipt digest is the Service Configuration owner's exact
receipt digest, not a Connector-side rehash. Verification accepts only an
explicitly supported profile and never compares digests across profiles.

The minimum uniqueness rules are:

- one ReceiptAdmissionKey per account, channel, and transport idempotency key,
  bound to one V2 Receipt or one immutable V1 acceptance tombstone, and one
  replay Receipt per account and ReplayRequest ID;
- one Component per Receipt and ordinal;
- one live Event per account and L1-derived SourceEventKey, plus one deliberate
  replay Event generation per account, SourceEventKey, and ReplayRequest ID;
- one ReplayRequest per account and ReplayRequest ID, with byte-exact target
  epoch and predecessor-digest comparison on duplicate insertion;
- one `CredentialGenerationDispatchGate` per immutable credential generation,
  with every Permit carrying the exact gate fence observed at acquisition;
- one `CutoverReadinessCertificate` per unique service cutover attempt, binding
  exactly one ServingEpoch identity/digest and configuration generation with a
  unique canonical certificate digest;
- at most one nonreleased `ServingPublicationBarrierSet` per activation scope,
  with exactly one fenced receipt for the Catalog, every binding-definition
  owner, the L2 configuration owner, and credential authority;
- one MaintenanceBarrierReceipt per required owner and service cutover attempt,
  with byte-exact owner, root-admission boundary, cursor, and evidence digest;
- one V1ShutdownCertificate per service cutover attempt, with byte-exact V1
  deployment generation, `ConnectorServiceConfigurationGeneration`, exhaustive
  account/gate-set, egress-manifest, barrier, terminal-inventory, termination,
  isolation, identity-coverage, and ordering-coverage digests;
- one V1RestorePoint per certified service cutover attempt, binding the complete
  post-drain database snapshot generation/position and schema digest to the
  V1ShutdownCertificate, exact V1 release/configuration tuple, owner cursors,
  barriers, account/gate set, and reconciled-effect evidence;
- one OrderingLane per epoch, route definition identity/version, and canonical
  OrderingPartition, with at most one fenced active Execution;
- one OrderingHandoff per predecessor epoch, successor epoch, route lineage,
  and predecessor partition, with the successor lane baseline byte-equal to the
  certified predecessor high-water or explicit snapshot transformation;
- one open Window per epoch, route, and canonical grouping key;
- at most one active Execution generation per Projection;
- one Runtime ApplicationResult per Execution generation;
- one OutboundCommand per trusted application scope, EffectRoot ID,
  metadata-authored EffectSlot ID, and EffectGeneration ID, with the canonical
  digest also uniquely constraining its byte-exact `IdempotencyKey`;
- exactly one RemoteEffect per OutboundCommand ID, enforced by a non-null
  unique foreign key and byte-exact logical-effect digest comparison;
- one RemoteEffectAttempt ordinal per RemoteEffect, with every attempt bound to
  the command's frozen epoch, policy, request, and credential-generation refs;
- at most one DispatchPermit per RemoteEffectAttempt, with every open Permit
  present in exactly one AccountServingGate open-permit set;
- one active RemoteLink for each remote identity and destination owner slot.

Any ambiguous match, duplicate authority row, mismatched digest, or missing
exact-generation reference is quarantined or rejected; it is never resolved by
row order or a preferred legacy path.

## State machines

Only the following semantic transitions are valid:

```text
AccountServingGate:
  v1_serving -> halting_v1
  halting_v1 -> v1_serving | v1_stopped
  v1_stopped -> v1_drained
  v1_drained -> v1_serving | v2_validating
  v2_validating --full V1RestorePoint restore--> v1_drained
  v2_validating --atomic first activation--> v2_serving
  v2_serving -> halting_v2 -> v2_halted
  v2_halted --no OrderingHandoff committed, abort--> v2_serving (predecessor)
  v2_halted --successor activation--> v2_serving (successor)

ServingEpoch:
  prepared -> verified | rejected
  verified -> active | rejected
  active -> draining -> retired

CredentialGenerationDispatchGate:
  enabled -> revoked
  revoked -> enabled       (explicit authorized reenablement only)

ServingPublicationBarrierSet:
  acquiring -> held | released
  held -> activation_committed | released
  activation_committed -> released

ProjectionWindow: open -> sealed
                        \-> quarantined

Execution: ready -> waiting_dependency | completed | quarantined
           waiting_dependency -> ready | quarantined

ExecutionDependency: waiting -> satisfied | expired | rejected

ApplicationResult: applied | noop | rejected | failed   (immutable terminal fact)

RemoteEffect: prepared -> dispatching | quarantined
              dispatching -> remote_confirmed | uncertain | no_effect
              dispatching -> prepared       (proved no effect; retry allowed)
              uncertain -> remote_confirmed | no_effect | quarantined
              uncertain -> prepared         (proved no effect, or exact repeat is idempotent)
              remote_confirmed -> finalized

DispatchPermit: granted -> sending | abandoned
                sending -> returned | abandoned

RemoteLink: active -> retired
```

`ServingPublicationBarrierSet: held -> released` is an abort transition allowed
while first activation is still `CutoverDecision=rollback_open`, after a
competing RestoreAttempt has won `restoring_v1` with no activation commit, or
for a successor before its activation transaction begins. A successor release
with no OrderingHandoff may abort to the predecessor; after any handoff, it may
only replace the candidate/barrier set while every gate remains halted. The
local activation transaction atomically records `activation_committed`; after the
first-activation decision chooses `activating_v2`, recovery must reach that
state and may release only after exact activation readback. `released` is
terminal.

`prepared -> verified | rejected` is an external-owner verification transition,
not validation of self-consistent candidate bytes. Before its database
transaction, Connector fresh-reads the exact Catalog view, all four binding
owners, the `ConnectorServiceConfigurationGeneration`, and every referenced
`CredentialGeneration`; validates each fact under its owner's protocol; then
uses the candidate's stored `ConnectorDigestProfileID` only to reconstruct the
Connector-owned epoch and binding envelopes from those exact opaque owner
identities, digests, and receipts. It byte-compares every prepared field, and
the transaction then compare-and-swaps the unchanged prepared
candidate. A caller-echoed receipt, merely sufficient Catalog revision, mutable
credential locator, omitted account or binding, unsupported profile, or stale
owner generation cannot produce `verified`. Retryable owner unavailability
leaves the candidate `prepared`; authoritative absence or mismatch must
transition it to `rejected`.

`verified` records exact-generation evidence at one point in time; it is not a
permanent assertion that the candidate remains current. First or successor
activation acquires and verifies the exact `ServingPublicationBarrierSet`, then
rereads the frozen-current L2 generation, Catalog view, credential generations,
and gates before the atomic transition. Retryable owner or barrier
unavailability leaves the candidate `verified` and refuses activation; exact
authoritative absence or mismatch must use the allowed `verified -> rejected`
transition.

Every AccountServingGate and CredentialGenerationDispatchGate transition
increments its own fence token. Every production V2 transaction that admits
transport or replay input, materializes an ordinary
or replay descendant, claims an Execution, authors an OutboundCommand, or
acquires a DispatchPermit must lock both the gate and its referenced exact
ServingEpoch. It requires `v2_serving`, the current fence token, an exact
gate-to-epoch ID and digest match, and epoch state `active`. A process that read
an older mode or a merely `verified`, `draining`, `retired`, or `rejected` epoch
cannot perform one of those writes. Settling a previously committed V2 Permit
is the sole exception: it uses the Permit and holder fences, not a stale gate
token, and remains legal while the gate drains its open-permit set.

`AccountServingGate` is an intentional per-account serialization point, but the
logical fence does not by itself prove that one physical row is an acceptable
hot-path design. Before the gate schema and API are frozen for production use,
and before any production claimant is enabled, the complete transaction mix
must pass a real-TiDB capacity test for the projected hottest account. The
frozen test plan
records the offered workload and concurrency for transport and replay
admission, materialization, claims, outbound authoring, Permit acquisition,
credential revocation, halt, and Permit settlement; the forecast peak and
required headroom; end-to-end throughput and p95/p99 latency budgets; p95/p99
gate-lock wait; deadlock and retry budgets; and a starvation bound for every
operation class. The test must
meet every declared quantitative target at the required headroom with no
unaccounted availability rejection. Failure requires redesigning the fencing
protocol or its physical serialization, not dropping a lock from one path or
weakening exact-epoch checks.

The hot-account proof does not cover the separate whole-service activation
transaction. Before first activation or the supported successor protocol is
enabled, a real-TiDB scale test must execute the exact barrier-set, ServingEpoch,
exhaustive gate-set, and applicable OrderingHandoff lock/update/readback shape at
the target deployment's maximum projected account and partition cardinality
plus declared headroom. It records gate and handoff rows, transaction bytes,
locks, commit and readback p95/p99 duration, deadlock/retry behavior, and crash
recovery time against quantitative budgets. Failure requires redesigning the
activation authority shape while preserving whole-service atomicity; it never
permits partial activation or an unbounded all-row transaction.

V1 is not retrofitted to read AccountServingGate. In `halting_v1`, verified
owner-level maintenance barriers reject new root V1 ingress and new root
outbound requests, but the unchanged V1 runtime may claim and finish work it
already accepted, including authoring and dispatching outbound work required by
that execution. An input or application transaction that crossed a barrier
before it closed is part of the drain. After the observed drain reaches zero,
the operator terminates every V1 process generation and isolates that
generation's provider egress. Those irreversible receipts enter `v1_stopped`,
which permits only cutover-coordinator-fenced evidence reconciliation and
post-isolation inventory, never V1 execution or effect-producing provider I/O.
Each reconciliation write locks the account gate, requires the exact
`v1_stopped` token and service cutover attempt, binds the exact V1 effect and
request digest, and appends remote-finalized or proved-no-effect evidence while
terminalizing that authoritative V1 row. Only a
`V1ShutdownCertificate` over that inventory may enter `v1_drained`.

`v1_stopped`, `v1_drained`, and `v2_validating` are whole-service offline
states. `v1_stopped` permits only the fenced reconciliation needed for the
shutdown certificate. `v1_drained` permits no V1 execution, but remains a
recoverable V1 authority state until the first V2 production activation.
`v2_validating` permits only candidate schema work and validation that cannot
admit production input, create a production execution or effect fact, submit
Runtime work, or cross provider egress; write-bearing fixtures use an isolated
database. V1 operational tables become terminal read-only only when the first
atomic activation commits `v2_serving`.

Returning from `halting_v1` to `v1_serving` is an abort allowed only before the
V1 process and egress-isolation receipts commit and uses a new fence token after
the maintenance barriers are safely restored. From `v1_drained`, a cold abort
may start a new process generation of the exact certified V1 release before any
V2 mutation. From `v2_validating`, only the L2 full-database restore contract may
return to the snapshotted `v1_drained` state; it must then start a new exact-V1
process generation before gates return to `v1_serving`. The terminated V1
process generation is never reenabled. The first atomic transition to
`v2_serving`, under `CutoverDecision=activating_v2`, closes the rollback branch
and is the irreversible protocol boundary: no V2 mode transitions to V1.

`v2_serving` permits only V2 paths. `halting_v2` rejects new admission,
materialization, outbound authoring, claims, and Permit acquisition, while
already open Permits may perform their one authorized call and settle. It is
therefore not yet a no-I/O state. A planned successor switch first drains
continuation work under the still-active predecessor and `v2_serving` gates,
with owner barriers blocking new roots; only then may it enter `halting_v2` and
prove `v2_halted`. That halted state permits evidence-only reconciliation or
local finalization, never new admission or provider I/O. The successor
activation transaction locks the current active epoch, the exact verified
successor, every frozen account gate, and every required OrderingHandoff. It
atomically changes the predecessor `active -> draining`, the successor
`verified -> active`, advances every gate's epoch reference and fence, and
returns every gate to `v2_serving`. No gate can reference a verified-only epoch,
and no nonterminal work crosses an epoch boundary.

A dependency-free Execution follows `ready -> completed` after the exact
Runtime ApplicationResult receipt is durably recorded. A dependent Execution
follows `ready -> waiting_dependency -> ready -> completed`; every transition
to `completed` requires that same Runtime-owned receipt. Recording completion
and advancing the OrderingLane high-water occur in one fenced transaction.

Claiming an Execution or a `prepared` RemoteEffect creates an Attempt and a
fenced lease; it does not itself authorize external I/O. An expired Execution
claim may be reacquired only with the same immutable identity. A dependency may
make an Execution ready again, but cannot mutate its projection or definition.

Before any provider call, the RemoteEffect owner must acquire the
DispatchPermit transaction described above. Acquisition alone cannot send: the
worker must present the exact `granted` Permit, holder fence, and credential-gate
fence to the sole egress adapter. The adapter locks and requires the same
enabled credential gate, atomically transitions that Permit to `sending`, and
records `io_may_have_started`; provider I/O remains forbidden until this second
transaction commits. Only the caller that wins this one-shot transition may
call the provider; a retry that observes `sending`, `returned`, or `abandoned`
cannot send. A crash before Permit acquisition leaves the effect `prepared`; a
crash after acquisition but before `sending` is durably proven pre-I/O but
still requires holder isolation before the Permit can close. The Permit remains
in the gate's open set until one of two transactions closes it:

- normal settlement appends the provider result or ambiguity evidence,
  transitions RemoteEffect accordingly, removes the Permit from the gate set,
  and records `returned`; or
- abandonment records durable proof that the holder process is terminated and
  its provider-egress capability is revoked, removes the Permit from the gate
  set, and records `abandoned`. A `granted` Permit proves no I/O and may return
  the effect to `prepared`; a `sending` Permit transitions it to `uncertain`.

A Permit never closes because its lease or wall-clock deadline expired. If the
holder cannot settle and process/egress isolation cannot be proven, the Permit
stays open and AccountServingGate stays `halting_v2`; reporting the account as
`v2_halted` would be unsafe. The `halting_v2 -> v2_halted` transaction locks the
same gate row used for Permit acquisition and succeeds only when the open set is
empty, so concurrent acquisition either commits before halting and must drain,
or observes `halting_v2` and fails. A worker paused with a `granted` or `sending`
Permit may still perform or finish that one call while the gate is
`halting_v2`, but its open Permit prevents the no-I/O `v2_halted` state until
the call settles or the holder is durably isolated.

`no_effect` is an immutable Attempt or reconciliation outcome, not a retryable
RemoteEffect state. With proof that the provider performed no effect, the same
transaction either transitions to `prepared` when the frozen L1 policy permits
another Attempt, or to terminal `no_effect` when it does not. No transition
leaves terminal `no_effect`. `uncertain -> prepared` requires either that proof
or a frozen provider idempotency contract proving that the byte-identical
request and idempotency key cannot create a second logical effect. In the latter
case the prior Attempt remains immutably `uncertain` and the new Attempt reuses
the same key; uncertainty evidence is never rewritten. Remote confirmation
followed by a local crash resumes local finalization and never redispatches.

## Transaction and crash rules

| Crash boundary | Required recovery |
| --- | --- |
| Receipt committed before transport acknowledgement | Retry resolves the original Receipt and epoch |
| Receipt committed before all Components or Events exist | Reconciliation materializes only missing children |
| Window close races with new input | One transaction seals the selected membership; later input enters a successor window |
| Execution claimed before Runtime accepts the command | Lease expiry retries the same Execution identity |
| Runtime commits application behavior before its response arrives | Repeating or querying the command returns the same ApplicationResult |
| Connector receives the result before local completion commits | The stored Runtime result receipt closes the same Execution without re-execution |
| Application transaction retries or the outbox redelivers | The stable logical-effect key resolves one OutboundCommand and its one RemoteEffect |
| A V1 transaction crosses a maintenance barrier before it closes | Let it commit under V1 and include every resulting row in the drain; the shutdown certificate is taken only after V1 termination and a second inventory |
| V1 is terminated while provider I/O may be in flight | Enter `v1_stopped`, treat the durable V1 call as ambiguous, and reconcile to remote-finalized or proved-no-effect evidence before certification; never restart that process generation |
| The process crashes after `v1_stopped` but before certification | Keep the service offline, reverify termination and isolation receipts, and resume post-stop inventory or evidence reconciliation |
| The coordinator crashes after `v1_drained` but before V2 mutation | Keep both runtimes offline; either resume recovery-point capture and V2 validation or cold-abort by starting a new process generation of the exact certified V1 release |
| V2 validation fails after candidate schema or data mutation | Keep both runtimes and production paths disabled; the external RestoreAttempt restores the complete post-drain V1 recovery point before a new exact-V1 process generation can start |
| The restore coordinator crashes at any restore boundary | Keep owner barriers closed and both generations isolated; resume the same externally journaled RestoreAttempt, verify full snapshot and release bindings, and expose no partially restored database |
| First activation races a cold restore or crashes | CutoverDecision chooses exactly one branch; activation atomically advances the exact epoch and exhaustive gate set, so either restore wins with every gate offline or the epoch is active with every gate `v2_serving`, never both or a partial serving set |
| Predecessor completion races successor OrderingHandoff | Completion commits first and its final high-water is in the handoff, or the handoff observes nonterminal work and fails; no predecessor completion can advance after the handoff fence |
| Successor fails before or after the first OrderingHandoff | Before any handoff, release barriers and resume the predecessor; after the first handoff, keep gates halted and activate the same or a newly verified successor from the immutable frozen high-water, never the predecessor |
| V2 admission races ServingEpoch activation | Admission locks the gate and exact epoch; before the atomic switch it writes nothing, and after the switch it can bind only the newly active epoch |
| Worker crashes before DispatchPermit acquisition commits | Provider I/O was forbidden; expire the Attempt lease and reclaim the still-`prepared` RemoteEffect |
| Credential revocation races Permit acquisition or `granted -> sending` | Both operations lock the exact CredentialGenerationDispatchGate; revocation first invalidates or safely abandons the pre-I/O Permit, while `sending` first authorizes its one call and revocation waits for settlement evidence |
| Halt begins with a `granted` DispatchPermit | The gate remains `halting_v2`; that Permit may enter `sending`, or holder isolation may abandon it with proof of no I/O |
| A `sending` DispatchPermit holder disappears or loses its lease | Permit expiry proves nothing; after holder-process and egress isolation, abandon the Permit and transition `dispatching -> uncertain` |
| Provider or reconciliation proves no external effect | Append `no_effect`; transition to `prepared` only when frozen policy permits another Attempt, otherwise terminal `no_effect` |
| Worker may have completed external I/O but lacks proof | Effect remains `uncertain`; repeat requires durable no-effect proof or the frozen exact-repeat idempotency contract, otherwise automatic retry stops |
| Remote success is proven before RemoteLink or local finalization commits | Resume finalization from attempt evidence; do not call the provider again |
| Replay admission or materialization races a gate transition | Both transactions lock AccountServingGate; either the replay write commits under the current `v2_serving` token before the transition, or it makes no change |
| Activation coordinator crashes while publication barriers are held | A fenced successor resumes the same set; first activation follows CutoverDecision, releasing while rollback is open or restore won and completing activation if `activating_v2` won, while V2 succession follows the atomic local `held` versus `activation_committed` state |

Reconciliation derives missing subordinate facts from immutable parents. It
must not repair a conflict by changing generation identity, choosing a
noncanonical locator, or copying a mutable status from a compatibility table.

## Generation and replay

A serving epoch freezes:

- the complete Catalog Integration binding view and digest;
- exact owner-pack installation identities and payload digests;
- exact Runtime command definition identities and versions;
- the exact `ConnectorServiceConfigurationGeneration` and its owner receipt;
- every immutable `CredentialGeneration` referenced by that configuration; and
- the `ConnectorDigestProfileID` governing every Connector-owned canonical
  digest in the epoch.

Every V2 Receipt and all descendants retain the V2 epoch that admitted that
Receipt. Runtime resolution during execution uses only the frozen references.
A replay predecessor may name an older V1 epoch as evidence, but no descendant
inherits or executes under it. Absence of a target activation row, generation,
route, or companion definition fails closed; V2 has no fallback to an active
InstalledPack, current route name, or mutable tenant mapping.

Every OutboundCommand, RemoteEffect, and Attempt likewise retains the outbound
ServingEpoch and complete FrozenDispatchBinding selected in the application
transaction. Exact credential resolution uses only the frozen generation and
immutable secret-backend version; rotation, mutable-name lookup, or a newer
current secret is never a fallback. That generation's metadata and owner
receipt remain retained until every bound command and effect is terminal.
Missing material or revocation blocks or quarantines dispatch under the frozen
policy and requires explicit remediation; it does not change the binding.

The only currently supported successor ServingEpoch protocol is the planned
offline `requires_drain` transition, not a rolling overlap: owner barriers close,
every predecessor Receipt descendant, Window, Execution, OutboundCommand,
RemoteEffect, and DispatchPermit reaches a terminal decision, and all gates
reach `v2_halted` before lane
handoffs or activation. No nonterminal command continues under a predecessor
epoch after a successor begins serving. The initial V1-to-V2 upgrade likewise
cannot activate V2 while any V1 outbound intent or effect is nonterminal or
ambiguous. An unavailable exact reference quarantines the effect rather than
falling forward. A successor OutboundCommand generation requires a separate
authorized business intent and is admitted only after its predecessor is proven
`no_effect`, as defined below.

Successor activation uses the same stop-the-world discipline. L2 first verifies
the successor epoch while it remains inert and closes every live-ingress,
replay, and new-root outbound barrier. With the gates still `v2_serving` on the
active predecessor, continuation work drains to a terminal decision. The
frozen gate set may move `v2_serving -> halting_v2 -> v2_halted` only after that
inventory and every Permit are terminal. The coordinator then acquires and
verifies a `ServingPublicationBarrierSet` for the successor's exact Catalog, L2,
definition-owner, and credential scope and rereads those owners under the held
fences. For each order-dependent partition, the OrderingHandoff transaction
then freezes the terminal predecessor
high-water and initializes the successor lane from that byte-exact baseline. A
changed comparator or partition contract requires a total deterministic L1
transformation plus a provider snapshot barrier covering every successor
partition; absent either proof, activation fails. An `order_independent` route
uses its existing conformance proof and has no lane handoff.

Before any OrderingHandoff commits, a failed successor attempt may
fenced-release its publication barriers and return every gate from `v2_halted`
to `v2_serving` on the predecessor after proving that no handoff exists. The
first committed handoff is the forward-only cutoff: every predecessor lane is
or will be frozen, and gate resume must reject the predecessor epoch. Recovery
keeps all gates `v2_halted` and either completes the same verified successor or
stages a new verified successor whose handoffs derive from the immutable frozen
predecessor high-water and cite the abandoned successor evidence. It may replace
the held publication-barrier set under a new fence, but it never unfreezes the
predecessor or resets ordering. A candidate that cannot satisfy this forward
proof leaves the service halted rather than taking the generic abort path.

With publication barriers and both execution generations stopped, one
transaction locks the local barrier-set evidence, predecessor active epoch,
exact verified successor, every frozen gate, and every required handoff. It
byte-compares the successor lanes, records the barrier set
`held -> activation_committed`, changes the predecessor `active -> draining`,
changes the successor `verified -> active`, and advances all gates
`v2_halted -> v2_serving` with the successor ID, digest, and new fences. Only
after exact readback may the coordinator durably release the publication
barriers, restart V2, and reopen owner barriers. The
predecessor becomes `retired` after its immutable terminal facts satisfy
retention requirements. There is no rolling epoch overlap and no independent
high-water namespace: if the handoff freezes predecessor position `100`, a
successor input at position `99` is durably superseded without Runtime
execution.

### Replay identity and predecessor

Upgrade itself never replays V1 work. A later operator-authorized replay starts
with a new V2 ReplayRequest and never reuses a V1 Receipt, Event, WorkItem,
Execution, or epoch:

1. The replay-admission transaction locks AccountServingGate and its exact
   ServingEpoch, requires `v2_serving`, compares the current fence token and
   gate-to-epoch ID and digest, requires epoch state `active`, and byte-compares
   any existing ReplayRequest ID. It atomically commits the ReplayRequest and
   its V2 replay Receipt; a gate or epoch transition and replay admission
   therefore cannot pass each other.
2. The request binds the target V2 ServingEpoch, predecessor ref/digests,
   reason, principal, and external-effect mode. The replay Receipt is keyed by
   ReplayRequest ID and copies only the exact predecessor payload bytes whose
   digest was authorized. The request and Receipt alone are inert and cannot
   execute.
3. Every transaction that reconciles or materializes replay Components,
   Events, Projections, or Executions locks the same AccountServingGate and
   exact ServingEpoch rows, requires current `v2_serving` and epoch state
   `active`, compares the current fence token, ID, and digest, and verifies the
   request's exact target epoch before inserting anything. A gate or epoch
   change aborts the transaction without a partial executable descendant.
4. Each derived Event uses `(account, SourceEventKey, ReplayRequestID)` as its
   deliberate new EventGeneration identity and records the predecessor ref.
   Projection and Execution receive new V2 identities and the target V2 epoch.
5. Repeating the same ReplayRequest ID loads and byte-compares the existing
   request and descendants. A mismatch fails closed; a different ID is a
   separate explicit replay generation.
6. The V1 predecessor remains terminal and byte-identical. Its ref is lineage
   evidence only: no V2 claimant locks, adopts, terminalizes, or changes a V1
   row.

A read-only lookup may return an existing ReplayRequest while V2 is halted, but
it cannot create or repair a descendant. If V2 later returns to `v2_serving`,
materialization resumes only through a new current-token gate transaction; the
stored target epoch and request bytes never change.

Replay retains the predecessor's source-order partition and position and must
pass the current target epoch's OrderingContract. A position at or below the
lane high-water is durably superseded without Runtime execution. Recomputing
current source state requires a new provider read and a new live V2 Event with
its own current source position; replay cannot relabel an old position.

### Replay and external effects

Every ReplayRequest must carry the sole valid replay mode,
`suppress_external_effects`, frozen into ReplayRequest, ExecutionRef, and the
Runtime command digest. Any other mode is rejected before replay materializes.
Runtime must reject OutboundCommand authoring from that execution context.
Replay preserves EffectRootID for correlation but cannot mint another
EffectGenerationID, so an application replay cannot duplicate a predecessor's
remote side effect.

An intentional new remote call is a separate operator-authorized business
intent, not a replay side effect. Its admission reconciles every predecessor
RemoteEffect for the same EffectRootID and EffectSlotID:

- `prepared` or `dispatching` resumes the existing effect and blocks a new one;
- `remote_confirmed` or `finalized` proves the effect occurred and rejects a
  new generation;
- `uncertain` blocks until reconciliation reaches confirmed or proven
  `no_effect`; and
- only proven terminal `no_effect` may authorize a successor
  EffectGenerationID, with explicit predecessor linkage and a newly frozen
  dispatch binding.

No replay or operator request reopens a terminal fact. Original payloads,
result receipts, attempts, remote evidence, and terminal history remain
immutable.

## Operational liveness and maintenance admission

Safety transitions never occur because a timeout elapsed, but every cutover
attempt must have one verified `CutoverReadinessCertificate` before maintenance.
There is no universal provider-neutral outage number: the target deployment's
exact L2 budget plan declares quantitative budgets for owner-barrier closure, V1 drain,
ordering-baseline capture, recovery-point capture, isolated restore rehearsal,
offline validation, activation readback, and full restore. Preflight measures
the current workload and uses it to project accepted work, leases, dependency
deadlines, ambiguous effects, source partitions, snapshot size, and owner
latencies against those budgets. Preflight includes a representative restore rehearsal
against the candidate schema and projected snapshot size; the exact post-drain
`V1RestorePoint` still requires its own isolated rehearsal during the outage. A
route without a lossless halt contract, proved ordering-migration disposition,
authoritative remediation owner, or successful representative rehearsal is
ineligible. A candidate whose measured preflight evidence or conservative
projection exceeds any budget does not enter `halting_v1`.

Budgets are go/no-go and escalation thresholds, not evidence that work or
provider I/O is safe. Before process termination and egress isolation, a breach
uses the fenced abort back to V1 after barriers are safely restored. After
`v1_drained` but before V2 mutation, it uses the certified cold abort. During
`v2_validating`, it uses the externally journaled full restore. After first
activation, recovery is forward-only. An unresolved possible provider effect
or unproved holder isolation has no finite safety timeout and may keep the
service halted.

Every halted or quarantined reason has a closed reason code, evidence query,
alert deadline, responsible owner, and allowed remediation. Remediation may
append authoritative evidence, mint a corrected immutable upstream generation,
restore through the permitted pre-activation path, or leave the route
explicitly unsupported. A quarantined execution fact remains immutable;
remediation creates the separately authorized successor, replay, or
reconciliation fact prescribed by its owner. It never relabels uncertainty,
mutates an admitted generation, reopens a terminal fact, or invents an unlisted
state transition. Planned V2 halt has no timeout-driven cancellation transition;
if its proof cannot complete, forward remediation is the only path.

## Offline V1 shutdown, cold rollback, and V2 cutover

V1 executable work is never migrated into V2 rows. The first V2 activation is
a planned outage for the whole connector service, not a per-account rolling
upgrade. It adds no V1 gate reader, V1 DispatchPermit, dual-write path, schema
fallback, or V1/V2 compatibility adapter. Cold rollback restores the complete
pre-V2 database and exact V1 release while both protocols are stopped; it is
not execution compatibility and is unavailable after V2 first serves
production work. Because V1 ignores the per-account gates, process and egress
isolation are deployment-wide, and the recovery point is the complete database,
activating even one V2 account would make the only available whole-database
restore erase that account's V2 facts while the remaining accounts still depend
on V1. The all-account activation boundary is therefore a consequence of the
defined owners, not an availability preference.

Before entering maintenance, the operator verifies the V2 schema, binary,
ServingEpoch, Catalog view, `ConnectorServiceConfigurationGeneration`, exact
`CutoverReadinessCertificate`, and all conformance proofs offline with V2
admission, replay, claims, Runtime submission, and provider I/O disabled. The
operator also freezes the exact V1 deployment generation and a current-tree V1
egress manifest. That manifest must enumerate every provider-I/O call site, its
authoritative V1 effect row, and the durable state written before bytes may
leave the process. It is evidence for the post-stop inventory, not a new V1
execution path. An untracked call site or a call without a durable pre-I/O
marker makes the upgrade unsupported.

The operator also verifies three classes of halt contract:

- each ingress owner can stop pollers and streams without advancing its durable
  cursor, while push or file delivery remains unacknowledged and is durably
  retried by the source or an existing upstream transport; and
- each application/API owner can reject a new root V1 outbound request
  retryably, without committing the associated application behavior; and
- the `ConnectorServiceConfigurationGeneration` owner can freeze account creation, removal,
  enablement, and cutover-relevant configuration at one exact generation while
  the Connector gate repository returns exactly one gate for every account in
  that generation and no gate for an unknown account.

These owner-level maintenance barriers stop new roots; they do not fence V1
continuation work. The unchanged V1 runtime must remain able to finish an input
it already accepted, including durably authoring and dispatching every outbound
effect required by that input. A transaction already crossing a barrier when
it closes may commit and becomes part of the drain. This ordering avoids a
terminal parent with a missing outbound child without introducing a legacy
handoff protocol. A route or application entry point without a lossless root
halt contract cannot enter the upgrade.

The cutover is then:

1. Close account/configuration authoring, every ingress, and every new-root
   outbound maintenance barrier, then wait for their in-flight transactions to
   return. Lock and byte-compare the exact `CutoverReadinessCertificate`, freeze
   its `ConnectorServiceConfigurationGeneration`, require an exhaustive
   one-to-one AccountServingGate set for it, and store its canonical digest with
   the cursor and authoring evidence. Move every gate in that set from
   `v1_serving` to `halting_v1`, referencing the same service cutover attempt.
   With no new roots and all barrier-crossing transactions returned, remeasure
   the actual accepted backlog, partitions, dependency deadlines, and effect
   states against the certificate's projections and budgets. A breach restores
   the owner barriers and takes the fenced `halting_v1 -> v1_serving` abort
   before process termination or egress isolation. The gates record cutover
   coordination only; unchanged V1 execution does not rely on their tokens. V2
   remains completely disabled and materializes no account fact.
2. Let V1 finish all work accepted before the barriers closed under its current
   authority and state machines. Continuation outbound authoring remains open
   during this step. Drain is blocked by any accepted inbound item without its
   terminal result, open window or scheduler work, live claim or lease,
   uncheckpointed cursor, pending existing V1 handoff, or outbound intent/effect
   that is reserved, dispatching, accepted-but-unfinalized, uncertain,
   ambiguous, or otherwise lacks durable proof of `no_effect` or completed
   remote finalization. A timeout, expired lease, or nominally terminal status
   label never converts possible provider I/O into safety. Unresolved ambiguity
   keeps the service in `halting_v1`; it is not relabeled, discarded, or
   converted into V2 work.
3. After the live V1 inventory first reaches zero, terminate every process in
   the exact V1 deployment generation: ingress, schedulers, claimants,
   reconcilers, and dispatchers. At the environment's process and network
   boundary, permanently deny that generation's provider-egress capability and
   record exact termination and isolation receipts. Compare-and-swap every gate
   in the frozen set `halting_v1 -> v1_stopped`, binding those exact receipts
   and the service cutover attempt; V2 remains stopped. A provider call
   interrupted by termination is treated as
   `io_may_have_started`; its authoritative V1 row must be reconciled to exact
   remote-finalized or proved-no-effect evidence before cutover can continue.
4. In `v1_stopped`, an isolated cutover reconciler may append exact
   remote-finalized or proved-no-effect evidence and terminalize the same V1
   authority row through the fenced transaction above, but may not dispatch an
   effect or restart a V1 claimant. After its final write, take the second
   authoritative V1 inventory while locking the same gates. Export every
   accepted V1 transport identity into ReceiptAdmissionKey as an immutable
   tombstone and byte-compare its payload digest and predecessor ref. Establish
   each order-dependent route's OrderingBaseline from the drained V1 high-water
   or a frozen provider snapshot barrier. Tombstones and baselines carry no
   lease, command, or executable state.
5. Enter `v1_drained` only when one durable `V1ShutdownCertificate` binds the
   exact V1 binary, schema, frozen `ConnectorServiceConfigurationGeneration`,
   exact `CutoverReadinessCertificate`, exhaustive account/gate-set digest,
   current-tree egress manifest, all maintenance-barrier receipts, the
   post-isolation terminal-state inventory, complete ReceiptAdmissionKey and
   OrderingBaseline coverage, the process-generation termination receipt, the
   provider-egress isolation receipt, and every evidence digest. Every gate in
   the frozen set locks and references that same certificate. Any current account outside the set,
   missing or extra gate, live process, egress-capable old generation,
   nonterminal or ambiguous V1 row, live lease, missing identity, or missing
   baseline rejects the transition. A crash while gates are being advanced
   from `v1_stopped` leaves the whole service offline; it does not authorize
   either runtime. V1 execution remains prohibited, but this complete V1
   authority is still recoverable until first V2 activation.
6. After the last reconciliation and `v1_drained` write, and before any V2
   schema or data mutation, the L2 backup owner captures a transactionally
   consistent full-database recovery point. It freezes the exact V1 release and
   configuration tuple, schema and content digests, source cursors, account/gate
   set, shutdown certificate, identity and ordering coverage, and reconciled
   provider-effect evidence in `V1RestorePoint`. An isolated restore rehearsal
   must boot that exact V1 release against the restored database and verify
   every binding. A pre-drain snapshot, a reset-only receipt, retained V1
   binaries, or a successful SQL read is insufficient. No candidate mutation
   starts until this receipt is durable outside the database being restored.
7. Move every frozen gate `v1_drained -> v2_validating`, apply the candidate V2
   schema and binary, initialize OrderingLane rows from the certified V1
   baselines, and repeat exact-generation and conformance verification against
   the candidate. Both runtime generations, all owner barriers, production
   transport and replay admission, materialization, claims, Runtime submission,
   outbound authoring, DispatchPermit acquisition, and provider egress remain
   disabled. Any write-bearing fixture uses an isolated database, never the
   production candidate. Failure leaves the service offline and invokes the
   full restore contract below.
8. While `CutoverDecision=rollback_open`, first production activation acquires
   the exact Catalog, binding-definition-owner, L2 configuration, and credential
   publication barriers and freezes their receipts in
   `ServingPublicationBarrierSet`. Under those held fences it rereads the owner
   generations, `CutoverReadinessCertificate`,
   V1ShutdownCertificate, V1RestorePoint, and exhaustive gate set. An urgent
   revocation or mismatch aborts and releases here while rollback remains open.
   Otherwise, while retaining every barrier, the coordinator wins
   `CutoverDecision: rollback_open -> activating_v2`. If a RestoreAttempt wins
   `restoring_v1` instead, activation records no commit and fenced-releases its
   held barriers so that restore can proceed. After activation wins, one
   database transaction locks the local barrier-set evidence, exact verified
   ServingEpoch, and every frozen gate; rejects any owner, account-set, or baseline drift;
   transitions the barrier set `held -> activation_committed`, transitions the
   epoch `verified -> active`, and advances every gate from `v2_validating` to
   `v2_serving` with that exact epoch ID, digest, and a new fence. It commits all
   facts or none; a gate can never point at a verified-only epoch. This commit
   closes the V1 restore window and makes V1 operational tables terminal
   read-only. After a fresh readback proves the epoch and entire gate set active,
   L2 commits `v2_committed`; only then does the coordinator durably release the
   publication barriers, start V2 processes, and reopen owner barriers. A V1
   transport duplicate resolves its ReceiptAdmissionKey tombstone and creates
   no V2 descendant.

Before the termination and egress-isolation receipts commit, an operator may
abort `halting_v1 -> v1_serving` only by proving V2 is stopped, restoring the
owner barriers, and issuing a new fence token. After `v1_drained` but before V2
mutation, cold abort starts a new process generation of the exact certified V1
release; it never revives the terminated generation. During `v2_validating`, an
L2 RestoreAttempt first wins
`CutoverDecision: rollback_open -> restoring_v1`, stops and isolates every V2
candidate process, proves no ServingEpoch was active and no production V2
admission, Runtime submission, provider I/O, or source acknowledgement
occurred, then restores the complete V1RestorePoint. It verifies the restored
schema, content, cursors, account/gate set, identity, ordering, and effect
digests, records a durable recovery receipt and `v1_restored` decision outside
the restored database, and only then starts a new exact-V1 process generation,
advances restored gates `v1_drained -> v1_serving`, and reopens egress and owner
barriers. A crash keeps both protocols offline and resumes the same
RestoreAttempt.

Once the first `verified -> active` transaction commits, backup-based downgrade
is forbidden: V2 may acknowledge source input, commit Runtime behavior, or
cause provider effects that a V1 snapshot cannot represent. Supporting that
path would require the V2-to-V1 execution handoff and effect reconciliation
protocol intentionally excluded here. A later V2 failure instead requests
`halting_v2` and reaches `v2_halted` only after every open DispatchPermit drains
or is safely abandoned. If that proof is unavailable, the account remains
`halting_v2` and recovery moves forward on V2.

An operator-authorized historical replay may occur only after V2 is serving
and follows the fenced ReplayRequest contract above. It is not part of upgrade
or drain. V1 tables may be removed after the certified ReceiptAdmissionKey
tombstones, ordering baselines, replay predecessor evidence, and audit
retention no longer depend on them. No V1 executable read path survives
cutover.

## V1 concepts to retire

V2 retains provider-neutral ingress, named-credential resolution, callout
transport, throttling, cursor, and exact-generation pack mechanisms. It
replaces or retires:

- Event execution status, lease, retry, replay, and execution-owner mirrors;
- WorkItem-encoded projection ownership, `csp:` identities, projection locator
  columns, and generation strings;
- SchedulerLease participation in durable execution ownership;
- Runtime handoff acceptance as a substitute for ApplicationResult;
- mutable live route or pack fallbacks;
- duplicate connector-push and connected-delivery effect authorities;
- giant durable snapshots that copy route, mapping, credential, result, and
  remote-link facts into one row.

These paths remain the recoverable V1 authority through `v1_drained` and
`v2_validating`; they become retired execution authority only when first
`v2_serving` commits. They are not deleted piecemeal while a V1 claimant can
still run or cold restore remains authorized, and no V2 executable path reads
them after cutover.

## Required proof

Each implementation slice must encode its invariants as automated tests. The V2
claimant may not be enabled until TiDB-backed concurrency and crash-injection
tests prove at least:

- exact-generation verification rejects incomplete, mixed, or mismatched Catalog
  and L2 references, while production activation atomically changes the exact
  epoch `verified -> active` and the exhaustive gate set to reference it;
- verification fresh-reads the authoritative Catalog view, all four binding
  owners, `ConnectorServiceConfigurationGeneration`, and every
  `CredentialGeneration`; it rejects a caller-echoed receipt, stale or mutable
  owner locator, omitted account, route, binding, or credential, and secret
  version-reference drift without reading secret bytes;
- L2 verification rejects a missing, extra, or duplicate
  `(account, binding CredentialRef) -> CredentialGenerationID` mapping and any
  generation whose stable identity or provider/account scope disagrees with the
  binding;
- pack uninstall, local-definition replacement, and retention races cannot
  remove or mutate an exact binding-definition generation while any active or
  resumable epoch references it; loss of its sole owner read path fails closed;
- unknown, cross-profile, or silently recanonicalized digests fail closed,
  profile IDs participate in the epoch and frozen request identities, and every
  active or resumable retained V2 fact governed by this architecture keeps its
  exact `ConnectorDigestProfile` readable;
- Connector digest profiles treat Catalog, pack, L2, and credential owner
  identities, digests, and receipts as opaque exact bytes; they cannot reinterpret
  or replace an owner's canonicalization protocol or read path;
- live transport, replay, ordinary and replay materialization, Execution claim,
  OutboundCommand authoring, and DispatchPermit acquisition each lock the gate
  and exact ServingEpoch and reject stale fences, ID or digest mismatch, or any
  epoch state other than `active`; even a corrupt gate that names a verified
  epoch produces no production fact;
- the real-TiDB hottest-account transaction mix meets its declared throughput,
  p95/p99 latency, gate-lock wait, retry, starvation, and headroom budgets for
  admission, replay, materialization, claims, outbound authoring, Permit
  acquisition, credential revocation, halt, and settlement without weakening
  fence serialization;
- the exact whole-service first and successor activation transactions meet their
  maximum projected account/partition cardinality, transaction-byte, lock,
  commit/readback, retry, crash-recovery, and headroom budgets on real TiDB;
  exceeding any bound rejects the authority shape rather than permitting a
  partial gate set;
- byte-exact keys reject whitespace, empty/null aliases, invalid encoding, and
  digest disagreement before persistence;
- transport redelivery and partial batch recovery materialize every Component
  and live Event once without changing the original V2 epoch; a retained V1
  ReceiptAdmissionKey tombstone returns already accepted and materializes no
  V2 descendant;
- repeated submission of one ReplayRequest converges on the same V2 Receipt and
  Event generation, a byte mismatch fails closed, a distinct ReplayRequest ID
  creates a distinct generation, and the V1 predecessor remains unchanged;
- replay admission and every replay-materialization transaction serialize with
  halt on AccountServingGate, reject a stale fence or inactive target epoch,
  and cannot create an executable descendant outside current `v2_serving`;
- cutover admission rejects, before maintenance, every enabled route lacking an
  immutable `order_independent`, `v1_high_water`, or
  `provider_snapshot_barrier` migration disposition; final baseline capture
  revalidates the preflight plan and cannot substitute `EnqueueOrdinal` or
  arrival order;
- out-of-order `latest_source_position` input cannot execute below the lane
  high-water, `strict_source_sequence` cannot cross a gap, and concurrent claim
  and result recording advance the high-water through one fenced transaction;
- a successor epoch cannot activate with any nonterminal predecessor fact or
  Permit; predecessor completion racing OrderingHandoff either commits first
  and is included or makes handoff fail, and no high-water advances afterward;
- a successor attempt may return `v2_halted -> v2_serving` on the predecessor
  only when no OrderingHandoff exists; after the first handoff, every predecessor
  resume fails and recovery activates the same or a newly verified successor
  from the immutable frozen high-water without resetting ordering;
- a predecessor lane ending at position `100` initializes its successor from
  the byte-exact handoff so successor position `99` is superseded without
  Runtime execution; changed comparator or partition derivation fails without
  the total L1 transformation and complete snapshot barrier;
- concurrent window close and Execution minting produce one active generation;
- a dependency-free Execution follows `ready -> completed` only from the exact
  Runtime ApplicationResult receipt and advances its OrderingLane high-water in
  the same transaction;
- lease loss creates a new Attempt for the same Execution, never a second
  application execution identity;
- Runtime commit followed by response loss returns the original
  ApplicationResult and cannot apply behavior twice;
- dependencies do not hold leases, deadlines do not move, and satisfy/expire
  races have one result;
- application transaction retry and concurrent outbox redelivery converge on
  one OutboundCommand and exactly one RemoteEffect;
- V2 halting leaves an already committed command bound to its original epoch,
  pack, route, policy, configuration, and credential generation, and successor
  activation remains blocked until that command and effect are terminal;
- credential rotation while a command is queued or dispatching retains and
  resolves its immutable generation metadata and owner receipt until terminal
  completion; secret access follows the frozen revocation and remediation
  policy, and missing or revoked material never falls forward to the current
  mutable name or secret;
- Permit acquisition and `granted -> sending` each serialize with credential
  revocation on the exact `CredentialGenerationDispatchGate`; revocation-first
  produces no I/O, sending-first permits one call and settles, reenablement uses
  a new fence, and no stale Permit revives;
- crash injection around Permit acquisition and the one-shot
  `granted -> sending` boundary proves that pre-acquisition is directly
  reclaimable, isolated `granted` abandonment proves no I/O, `sending`
  abandonment is uncertain, and Permit expiry alone proves nothing;
- concurrent Permit acquisition and `v2_serving -> halting_v2` serialize on the
  gate row; a worker paused with an open Permit keeps the gate in `halting_v2`,
  and only Permit return or proven holder/egress isolation permits
  `v2_halted`;
- durable no-effect proof creates another Attempt of the same effect only when
  frozen policy permits it; terminal `no_effect` never reopens;
- an idempotent repeat from `uncertain` reuses byte-identical request bytes and
  the frozen provider key while preserving the prior uncertain Attempt;
- remote ambiguity blocks unsafe retries, while proven remote success survives
  a crash before local finalization;
- RemoteLink conflicts fail closed and field ownership cannot influence remote
  identity selection;
- replay suppresses Runtime outbound authoring, and confirmed or uncertain
  predecessor effects cannot produce a successor command; only proven terminal
  `no_effect` plus a separate authorized business intent can mint the next
  EffectGenerationID;
- owner-level maintenance barriers reject new root V1 admission and root
  outbound requests without preventing already accepted V1 work from authoring
  and finalizing its required effects; a transaction crossing barrier close is
  included in the post-stop inventory;
- preflight rejects a cutover whose measured drain, baseline-capture,
  recovery-point, restore-rehearsal, validation, activation-readback, or restore
  plan exceeds its declared quantitative budget; budget breach exercises the
  phase-appropriate safe abort or restore path, while elapsed time alone never
  resolves possible external I/O;
- `CutoverReadinessCertificate` creation rejects incomplete route dispositions,
  budgets, measurements, alert ownership, or remediation mappings; a changed
  input requires a new attempt and byte-distinct certificate;
- after owner barriers close, the cutover remeasures the actual accepted
  backlog, partitions, deadlines, and effects against the certificate; a budget
  breach takes `halting_v1 -> v1_serving` before termination and never continues
  on stale preflight projections;
- every halted or quarantined reason exposes its closed reason code, evidence
  query, alert deadline, responsible owner, and authorized immutable
  remediation path; unprovable safety may remain halted rather than advancing;
- account creation and cutover-relevant configuration races serialize with the
  configuration barrier; shutdown and V2 activation reject any current account
  or gate outside the certificate's frozen exhaustive set;
- V1 shutdown cannot certify with any nonterminal or ambiguous work, live
  process generation, live lease, incomplete current-tree egress-manifest,
  identity, or ordering coverage, or old-generation provider-egress
  capability; a V1 call interrupted at every pre-I/O and post-I/O boundary
  remains blocking until exact reconciliation;
- cutover reconciliation and shutdown certification serialize on the same
  `v1_stopped` gate rows, so the certificate observes every terminalization or
  rejects it and no reconciliation write can commit after `v1_drained`;
- V1RestorePoint capture fails unless it occurs after the final reconciliation
  and `v1_drained` commit but before every V2 mutation, binds the exact complete
  database and V1 release tuple, and passes a real isolated restore rehearsal;
  corrupt content, a partial/reset-only backup, or account/cursor/effect drift
  rejects it;
- `v2_validating` rejects every production admission, descendant, claim,
  Runtime submission, outbound command, Permit, source acknowledgement, and
  provider call; candidate failure restores the complete V1 point while both
  runtimes remain stopped, then a new process generation of the exact V1 release
  resumes with unchanged cursor, idempotency, ordering, and terminal-effect
  evidence;
- attempts to restart the terminated V1 process generation or restore its egress
  fail closed, but a certified cold abort or full restore before first V2
  activation may start a new exact-V1 generation; activation and RestoreAttempt
  serialize on the durable CutoverDecision, which never chooses a competing
  branch because of timeout;
- crash injection at every first-activation boundary yields either one verified
  epoch with every gate offline and restore still authorized, or one active
  epoch with the entire gate set `v2_serving`; it never exposes a partial set or
  a gate pointing at a verified-only epoch;
- Catalog publication, binding-definition publication or retention, L2
  configuration publication, credential revocation, and activation serialize
  through the exact non-expiring publication barriers;
  urgent revocation can abort only while CutoverDecision remains open, and no
  external owner changes between the final reread and activation commit;
- a coordinator crash at every publication-barrier boundary is recovered by one
  holder-fenced takeover of the same barrier set and CutoverDecision; stale
  acquire/release fails, activation-winning recovery completes readback before
  release, and elapsed time alone never unlocks an owner;
- activation losing the CutoverDecision race to `restoring_v1` records no local
  activation commit, fenced-releases the held publication barriers, and permits
  restore to proceed; a stale activation coordinator cannot reacquire or commit;
- once any ServingEpoch first becomes active, every V1 downgrade or restored
  snapshot is rejected; V2 halt and forward recovery are the only paths;
- successor activation crash injection leaves the predecessor active with every
  gate `v2_halted`, or atomically makes the predecessor draining, successor
  active, and every gate `v2_serving` on the successor; no mixed serving epoch is
  accepted;
- every successor transition class other than `requires_drain`, including
  `online_compatible`, is rejected regardless of supplied compatibility
  evidence; enabling another class requires a separate normative state-machine,
  gate/fence, schema, and crash-proof change;
- two structurally different external-application conformance fixtures pass
  through the same L0 model with no provider literals or branches in L0.

State-transition tests must enumerate and reject every transition not listed in
this document. Repository tests must exercise real uniqueness constraints and
concurrent transactions, not only mocks.

## Outcome-gated delivery plan

This design is implemented only when it is the smallest coherent way to close
a current production contradiction recorded by the read-only architecture task
[pingcap-inc/nexuscrm-pingcap-pack#4739](https://github.com/pingcap-inc/nexuscrm-pingcap-pack/issues/4739).
The existence of a table, repository, protocol type, or box in this document is
not by itself a reason to implement it. Already merged foundation may be reused
by a selected walking slice, but foundation with no production claimant is not
delivery progress.

### Final L0 result

The delivered L0 result is exhaustive coverage of every supported
provider-neutral integration path through the public Connector composition
boundary with one end-to-end consistency contract. A representative walking
slice proves that the contract composes, but is explicitly non-completing and
cannot authorize production activation:

- one authenticated provider operation has one durable transport identity and
  one application execution authority;
- the CRM business mutation and its Runtime/ApplicationResult terminal outcome
  compose without a crash gap that can lose accepted work or repeat committed
  work;
- each outbound provider effect has one immutable intent and one convergent
  effect identity across retry ambiguity;
- source ordering and every pack, definition, configuration, and credential
  generation needed by live work remain exact and readable;
- cutover admits exactly one execution claimant, with a proved rollback or
  forward-recovery boundary and no simultaneous V1/V2 authority; and
- normal admission and retry work is bounded by the current operation and its
  exact parents, never by an unbounded scan of retained account history.

L0 owns the provider-neutral mechanism, public composition boundary, and
conformance contract. L1/L2 own provider definitions, tenant adoption,
provider-specific production acceptance, and rollout. Those downstream proofs
may consume this mechanism but are not requirements authored by this document.
Within L0, inert schemas, fixture-only writers, and unclaimed readers do not
satisfy the result.

### Delivery gates

1. **Current-tree closure decision.** Re-audit every contradiction in the
   architecture task against current main, current L0 consumers, and downstream
   incident evidence. For each contradiction, record its current owner and read
   path, the exact still-failing scenario, and one disposition: already closed,
   directly repairable in V1, or requiring a replacement protocol. Delete stale
   requirements. Select the smallest coherent migration that closes all
   remaining contradictions; do not assume the whole design in this document is
   required.
2. **Non-completing walking slice.** In an isolated conformance environment,
   prove one authenticated provider-neutral operation from admission through
   CRM mutation, immutable Runtime result, outbound intent, and convergent remote
   effect. Inject retries and crashes at every commit boundary and exercise the
   real public composition wiring. Keep every production V2 admission, claim,
   and egress path disabled; this proof cannot authorize activation or
   retirement.
3. **Exhaustive whole-service qualification.** Build a closed inventory and
   prove the selected authority for every enabled route, source-order partition,
   account, gate, ingress, replay, materialization, claim, execution, outbound,
   and dispatch path. Prove exact retained owner generations, absence of mutable
   fallback, unsupported-candidate rejection before maintenance, and declared
   capacity and latency bounds at the exhaustive cardinality plus headroom. Any
   uncovered supported path blocks activation.
4. **Whole-service activation and L0 retirement.** Halt new V1 root work; drain
   all accepted V1 work including outbound effects; terminate V1 claimants;
   isolate V1 provider egress; capture and verify the recovery point; and
   validate the qualified V2 candidate offline. Only then atomically activate
   the exhaustive V2 account/gate set. There is no per-account first-activation
   wave or simultaneous V1/V2 claimant. Enable provider I/O and remove or
   permanently disable superseded L0 paths only after exact activation readback.
   Publish downstream adoption prerequisites; provider and tenant rollout remain
   owned by L1/L2.

Each gate must end in an executable business assertion. A gate is not complete
because its supporting repositories or conformance fixtures exist.

### Pull-request admission rule

Every implementation PR must do one of the following:

- eliminate one proved current contradiction on the selected production
  walking slice; or
- provide the smallest release-order prerequisite for the immediately
  following walking-slice PR, naming that consumer and its end-to-end test.

Do not admit a future-only schema or read path, duplicate a fact owner, add an
account-history-dependent hot-path scan, or preserve two selectable consistency
contracts. Tests may corrupt states reachable through a supported production or
migration path; direct database mutations do not justify permanent hot-path
defenses against otherwise impossible states.

Until the whole-service activation in Gate 4 commits, the production composition
root must keep every V2 writer, claimant, and provider-egress path unreachable,
and AccountServingGate must continue rejecting V2 admission.

If review feedback expands a PR into another subsystem or makes its work scale
with retained history, stop and revisit the selected result rather than add
another compensating authority. No PR combines a new authority with removal of
the prior authority unless the same change proves complete cutover for every
live consumer.

### Completion evidence

Completion requires all of the following on the exact release candidate:

- the current contradictions in the architecture task each have a verified
  closed disposition;
- the non-completing provider-neutral walking slice passes through the public L0
  composition boundary under retry, crash, restart, credential rotation, pack
  generation change, and release transition without enabling production V2;
- a closed inventory proves the selected authority for every supported route,
  partition, account, gate, ingress, replay, materialization, claim, execution,
  outbound, and dispatch path, and rejects every uncovered candidate;
- accepted work is never lost, committed CRM work and remote effects are never
  duplicated, and every nonterminal item has one live owner;
- hot-path latency and database work remain within declared bounds independent
  of retained account history;
- the L0 composition root uses the new authority with no simultaneous V1/V2
  claimant or hidden compatibility fallback, and no V2 production admission,
  claim, or provider I/O occurs before atomic whole-service activation; and
- rollback or forward recovery, operational observability, and retirement of
  superseded code and data paths are proved.