effect-agent 0.1.0-beta.12 → 0.1.0-beta.121

package/src/durable/SubmissionLedger.ts

@@ -0,0 +1,1265 @@
+import type { Option, Stream } from "effect";
+import { Context, Duration, Effect, Schema } from "effect";
+
+import { InputMessage } from "../capabilities/Messaging.ts";
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
+import {
+  AgentId,
+  AttemptId,
+  ThreadId,
+  ReceiptId,
+  SettlementId,
+  SubmissionId,
+  ToolCallId,
+} from "../core/Identifiers.ts";
+import type { JoinedToHost } from "../core/Receipt.ts";
+import { IdempotencyKey, QueueSequence, Principal } from "../core/Receipt.ts";
+import { RunUsageSummary } from "../core/Usage.ts";
+import { AssignmentTerminal } from "../core/Worker.ts";
+import {
+  AbortRequested,
+  ApprovalDecision,
+  BatchId,
+  CanonicalSequence,
+  DefinitionDigests,
+  DeploymentId,
+  Digest,
+  PersistedJson,
+  ProducerEpoch,
+  ProducerId,
+  RecordEnvelope,
+  RecordId,
+  SettlementFailureDiagnostic,
+  SettlementOutcome,
+  ToolApprovalDecided,
+  ToolCallResolved,
+  ToolCallUnknown,
+  WorkerAdmission,
+} from "./Records.ts";
+
+export { IdempotencyKey, JoinedToHost, QueueSequence, Principal } from "../core/Receipt.ts";
+
+const identifier = <const Name extends string>(name: Name) =>
+  Schema.NonEmptyString.check(Schema.isMaxLength(256)).pipe(
+    Schema.brand(`@effect-agent/thread/${name}`),
+  );
+
+/**
+ * Opaque proof that one Attempt currently owns a Submission's lane. It authorizes ledger
+ * mutations only; canonical-log fencing authority remains the producer epoch (DUR-006).
+ */
+export const OwnershipToken = identifier("OwnershipToken");
+export type OwnershipToken = typeof OwnershipToken.Type;
+
+/**
+ * Ledger lifecycle states for one Submission. `settled` is the only terminal state; every other
+ * state carries an outstanding accepted-work obligation (Accepted-work Contract, DUR-002).
+ *
+ * Phase 5 states:
+ *
+ * - `joining` — a queued Submission claimed by an active host Run, before its canonical
+ *   `UserInputRecorded` append; recovery reverts it to `ready` (DUR-016).
+ * - `joined` — the input is canonical and linked to its host; the Submission settles WITH the
+ *   host Run's outcome.
+ * - `suspended` — durably waiting for explicit approval decisions; the ownership period has
+ *   ended and the lane consumes no worker permit while the obligation stays owed.
+ * - `unknown` — at least one Tool Call has a durable Unknown Outcome; this Submission is
+ *   parked until an authorized resolution covers every open call or a durable abort intent
+ *   authorizes cleanup without Tool replay. Later eligible input may run (DUR-012/DUR-017).
+ *
+ * `claim` never grants or bypasses a `joining`, `joined`, or `suspended` head. It skips unknown
+ * work without an abort intent. Any live ownership in the Thread prevents another claim.
+ */
+export const SubmissionState = Schema.Literals([
+  "admitted",
+  "ready",
+  "joining",
+  "joined",
+  "running",
+  "input-applied",
+  "suspended",
+  "unknown",
+  "terminalizing",
+  "settled",
+]);
+
+export type SubmissionState = typeof SubmissionState.Type;
+
+/**
+ * Default ownership lease duration (D5). The lease is a liveness hint that makes an abandoned
+ * claim reclaimable; correctness never depends on it because every canonical append is fenced by
+ * producer epoch. Adapters expose this as configuration and use this value when unconfigured.
+ */
+export const DEFAULT_OWNERSHIP_LEASE_DURATION: Duration.Duration = Duration.seconds(30);
+
+/**
+ * What a SubmissionLedger adapter claims about itself. `durable-node` asserts single-node
+ * process-crash durability (fsync-backed storage); `durable-cloudflare` asserts the same
+ * single-serialized-owner crash durability through Durable Object storage output gates;
+ * `non-durable` marks reference adapters whose state does not survive the process (in-memory
+ * conformance/test adapters). The label is an honest self-description for reports and
+ * evidence — no runtime behavior branches on it.
+ */
+export class LedgerCapabilities extends Schema.Class<LedgerCapabilities>(
+  "@effect-agent/thread/LedgerCapabilities",
+)({
+  durability: Schema.Literals(["durable-node", "durable-cloudflare", "non-durable"]),
+}) {}
+
+/**
+ * Immutable lineage from a child Submission to the exact parent Tool Call that established it
+ * (spec §12 step 5, SUB-004). Recorded once at admission and never rewritten; it is an
+ * identifier, not an authorization capability (D10) — the join path verifies the canonical
+ * Parent Link records, never this marker alone.
+ */
+export class ParentLinkage extends Schema.Class<ParentLinkage>(
+  "@effect-agent/thread/ParentLinkage",
+)({
+  parentSubmissionId: SubmissionId,
+  parentToolCallId: ToolCallId,
+}) {}
+
+/** Host-owned policy coordinates, interpreted only by the destination transaction owner. */
+export const AdmissionFence = Schema.Struct({
+  policyId: Schema.NonEmptyString.check(Schema.isMaxLength(128)),
+  key: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  revision: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+});
+
+export type AdmissionFence = typeof AdmissionFence.Type;
+export const AdmissionGroup = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+
+/** Fresh admission alone may be refused; unavailability never proves non-admission. */
+export class AdmissionPolicyError extends Schema.TaggedError<AdmissionPolicyError>()(
+  "AdmissionPolicyError",
+  {
+    reason: Schema.Literals(["refused", "unavailable", "occupied"]),
+    code: Schema.NonEmptyString.check(Schema.isMaxLength(128)),
+    cause: Schema.optionalKey(FailureDiagnostic.Value),
+    stack: Schema.optionalKey(Schema.String),
+  },
+) {}
+
+/**
+ * Durable admission input. `inputDigest` must be the digest of the canonical JSON encoding of
+ * `inputPayload` (see `digestJson`); admission idempotency compares digests, never re-encodes.
+ * `agentId`/`agentDigests`/`deploymentId` are persisted so recovery can complete Thread
+ * materialization without the submitting client. `parentLinkage` is present exactly when the
+ * Submission is a durable attached child (spec §12); an admission replay must repeat the same
+ * linkage (or its absence) or fail with `AdmissionConflict`.
+ */
+export class AdmissionRequest extends Schema.Class<AdmissionRequest>(
+  "@effect-agent/thread/AdmissionRequest",
+)({
+  threadId: ThreadId,
+  principal: Principal,
+  idempotencyKey: IdempotencyKey,
+  agentId: AgentId,
+  agentDigests: DefinitionDigests,
+  deploymentId: DeploymentId,
+  inputPayload: PersistedJson,
+  inputDigest: Digest,
+  parentLinkage: Schema.optionalKey(ParentLinkage),
+  workerAdmission: Schema.optionalKey(WorkerAdmission),
+  messageAdmission: Schema.optionalKey(InputMessage),
+  admissionGroup: Schema.optionalKey(AdmissionGroup),
+  admissionFence: Schema.optionalKey(AdmissionFence),
+}) {}
+
+/**
+ * The committed admission row. `replayed` is true when an identical (thread, principal,
+ * idempotencyKey, inputDigest) admission already existed; the original identities are returned
+ * unchanged so a client retry resumes rather than duplicates (DUR-001).
+ */
+export class AdmissionResult extends Schema.Class<AdmissionResult>(
+  "@effect-agent/thread/AdmissionResult",
+)({
+  submissionId: SubmissionId,
+  receiptId: ReceiptId,
+  queueSequence: QueueSequence,
+  state: SubmissionState,
+  replayed: Schema.Boolean,
+}) {}
+
+export class MarkReadyRequest extends Schema.Class<MarkReadyRequest>(
+  "@effect-agent/thread/MarkReadyRequest",
+)({
+  submissionId: SubmissionId,
+}) {}
+
+export class SubmissionLookupById extends Schema.TaggedClass<SubmissionLookupById>(
+  "@effect-agent/thread/SubmissionLookupById",
+)("SubmissionLookupById", {
+  submissionId: SubmissionId,
+}) {}
+
+export class SubmissionLookupByKey extends Schema.TaggedClass<SubmissionLookupByKey>(
+  "@effect-agent/thread/SubmissionLookupByKey",
+)("SubmissionLookupByKey", {
+  threadId: ThreadId,
+  principal: Principal,
+  idempotencyKey: IdempotencyKey,
+}) {}
+
+/** Lookup by Submission identity or by the scoped client idempotency key. */
+export const SubmissionLookup = Schema.Union([SubmissionLookupById, SubmissionLookupByKey]);
+export type SubmissionLookup = typeof SubmissionLookup.Type;
+
+/**
+ * Control-only worklist entry. Discovery validates identities, ordering and state without
+ * decoding retained execution payloads. Hydrate only the selected Thread through `lookup`
+ * or `loadRecoverySnapshot`, inside its recovery failure boundary.
+ */
+export class SubmissionWorkItem extends Schema.Class<SubmissionWorkItem>(
+  "@effect-agent/thread/SubmissionWorkItem",
+)({
+  submissionId: SubmissionId,
+  threadId: ThreadId,
+  queueSequence: QueueSequence,
+  principal: Principal,
+  idempotencyKey: IdempotencyKey,
+  deploymentId: DeploymentId,
+  receiptId: ReceiptId,
+  state: SubmissionState,
+}) {}
+
+/** The full durable ledger view of one Submission. */
+export class SubmissionSnapshot extends Schema.Class<SubmissionSnapshot>(
+  "@effect-agent/thread/SubmissionSnapshot",
+)({
+  ...SubmissionWorkItem.fields,
+  agentId: AgentId,
+  agentDigests: DefinitionDigests,
+  inputPayload: PersistedJson,
+  inputDigest: Digest,
+  settledOutcome: Schema.optionalKey(SettlementOutcome),
+  createdAt: Schema.DateTimeUtcFromString,
+  readyAt: Schema.optionalKey(Schema.DateTimeUtcFromString),
+  admissionGroup: Schema.optionalKey(AdmissionGroup),
+  admissionFence: Schema.optionalKey(AdmissionFence),
+  parentLinkage: Schema.optionalKey(ParentLinkage),
+  workerAdmission: Schema.optionalKey(WorkerAdmission),
+  messageAdmission: Schema.optionalKey(InputMessage),
+}) {}
+
+/** Bounded native control facts. Canonical input/Run records remain ThreadStore-owned. */
+export const WorkerLedgerState = Schema.Struct({
+  latest: Schema.NullOr(SubmissionSnapshot),
+  active: Schema.NullOr(SubmissionSnapshot),
+  stopped: Schema.Boolean,
+  terminal: Schema.optionalKey(AssignmentTerminal),
+}).check(Schema.makeFilter((state) => state.terminal === undefined || state.stopped));
+
+export type WorkerLedgerState = typeof WorkerLedgerState.Type;
+
+/** The authoritative store proves the scoped idempotency key was never admitted (SUB-031). */
+export class AdmissionNotAdmitted extends Schema.TaggedClass<AdmissionNotAdmitted>(
+  "@effect-agent/thread/AdmissionNotAdmitted",
+)("NotAdmitted", {}) {}
+
+/** The scoped idempotency key was admitted; the full Submission snapshot is authoritative. */
+export class AdmissionAdmitted extends Schema.TaggedClass<AdmissionAdmitted>(
+  "@effect-agent/thread/AdmissionAdmitted",
+)("Admitted", {
+  submission: SubmissionSnapshot,
+}) {}
+
+/**
+ * The adapter cannot currently prove admission or its absence (e.g. the authoritative child
+ * owner is unreachable on a partitioned platform). Callers wait and retry; an indeterminate
+ * answer NEVER permits a second admission attempt (SUB-031).
+ */
+export class AdmissionIndeterminate extends Schema.TaggedClass<AdmissionIndeterminate>(
+  "@effect-agent/thread/AdmissionIndeterminate",
+)("Indeterminate", {
+  reason: Schema.String.check(Schema.isMaxLength(4096)),
+}) {}
+
+/**
+ * The tri-state answer of `resolveAdmission` (spec §12: "absence from an eventually consistent
+ * projection is never proof"). Single strongly consistent stores derive `NotAdmitted`/`Admitted`
+ * from a direct lookup; only adapters that can genuinely fail to reach the authoritative owner
+ * answer `Indeterminate`.
+ */
+export const AdmissionResolution = Schema.Union([
+  AdmissionNotAdmitted,
+  AdmissionAdmitted,
+  AdmissionIndeterminate,
+]);
+
+export type AdmissionResolution = typeof AdmissionResolution.Type;
+
+export class ClaimRequest extends Schema.Class<ClaimRequest>("@effect-agent/thread/ClaimRequest")({
+  threadId: ThreadId,
+  producerId: ProducerId,
+}) {}
+
+/**
+ * One granted ownership period. `producerEpoch` is the fencing token for every canonical append
+ * this Attempt performs; `leaseExpiresAt` is when the claim becomes reclaimable unless renewed.
+ */
+export class Claim extends Schema.Class<Claim>("@effect-agent/thread/Claim")({
+  submissionId: SubmissionId,
+  attemptId: AttemptId,
+  ownershipToken: OwnershipToken,
+  producerEpoch: ProducerEpoch,
+  leaseExpiresAt: Schema.DateTimeUtcFromString,
+  inputPayload: PersistedJson,
+}) {}
+
+export class RenewOwnershipRequest extends Schema.Class<RenewOwnershipRequest>(
+  "@effect-agent/thread/RenewOwnershipRequest",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+}) {}
+
+/**
+ * A renewed lease. Adapters MAY rotate the token; callers must use the returned token for every
+ * later ledger mutation.
+ */
+export class OwnershipRenewal extends Schema.Class<OwnershipRenewal>(
+  "@effect-agent/thread/OwnershipRenewal",
+)({
+  ownershipToken: OwnershipToken,
+  leaseExpiresAt: Schema.DateTimeUtcFromString,
+}) {}
+
+export class ReleaseOwnershipRequest extends Schema.Class<ReleaseOwnershipRequest>(
+  "@effect-agent/thread/ReleaseOwnershipRequest",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+}) {}
+
+/**
+ * The canonical position of the applied `UserInputRecorded` record for one Submission.
+ */
+export class MarkInputAppliedRequest extends Schema.Class<MarkInputAppliedRequest>(
+  "@effect-agent/thread/MarkInputAppliedRequest",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+  recordId: RecordId,
+  sequence: CanonicalSequence,
+}) {}
+
+export class InputAppliedMarker extends Schema.Class<InputAppliedMarker>(
+  "@effect-agent/thread/InputAppliedMarker",
+)({
+  recordId: RecordId,
+  sequence: CanonicalSequence,
+}) {}
+
+/**
+ * Reservation of the single exact settlement record for one Submission (DUR-011). `record` is
+ * the complete canonical envelope that will be appended — including `createdAt` — so a recovering
+ * Attempt can re-append byte-identical content without a batch-digest conflict. `recordDigest`
+ * must be the digest of the canonical JSON encoding of the Schema-encoded envelope.
+ */
+export class SettlementReservation extends Schema.Class<SettlementReservation>(
+  "@effect-agent/thread/SettlementReservation",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+  settlementId: SettlementId,
+  outcome: SettlementOutcome,
+  record: RecordEnvelope,
+  recordDigest: Digest,
+}) {}
+
+/**
+ * The committed reservation. `replayed` is true when an identical reservation already existed;
+ * the stored exact record is returned so recovery appends precisely what was reserved.
+ */
+export class ReservedSettlement extends Schema.Class<ReservedSettlement>(
+  "@effect-agent/thread/ReservedSettlement",
+)({
+  submissionId: SubmissionId,
+  settlementId: SettlementId,
+  outcome: SettlementOutcome,
+  record: RecordEnvelope,
+  recordDigest: Digest,
+  replayed: Schema.Boolean,
+}) {}
+
+export class SettlementFinalization extends Schema.Class<SettlementFinalization>(
+  "@effect-agent/thread/SettlementFinalization",
+)({
+  submissionId: SubmissionId,
+  settlementId: SettlementId,
+}) {}
+
+const SettlementFields = Schema.Struct({
+  submissionId: SubmissionId,
+  settlementId: SettlementId,
+  receiptId: ReceiptId,
+  outcome: SettlementOutcome,
+  /** Schema-encoded application disposition materialized from the exact canonical reservation. */
+  runDisposition: Schema.optionalKey(PersistedJson),
+  /** Canonical aggregate of model usage and estimated spend for this Run. */
+  usageSummary: Schema.optionalKey(RunUsageSummary),
+  /** Present exactly for `failed`; its Schema rejects excess keys before canonical projection. */
+  failure: Schema.optionalKey(SettlementFailureDiagnostic),
+  settledAt: Schema.DateTimeUtcFromString,
+}).check(
+  Schema.makeFilter(
+    (settlement) => (settlement.outcome === "failed") === (settlement.failure !== undefined),
+    { title: "failure exactly on a failed Settlement" },
+  ),
+);
+
+/** The single durable terminal outcome recorded for one accepted Submission (DUR-002). */
+export class Settlement extends Schema.Class<Settlement>("@effect-agent/thread/Settlement")(
+  SettlementFields,
+) {}
+
+/**
+ * Project the bounded failed-settlement diagnostic from an already Schema-validated exact
+ * reservation. Storage adapters use this when materializing their operational Settlement value;
+ * the canonical record remains the authority.
+ */
+export const settlementFailureFromRecord = (
+  record: RecordEnvelope,
+): SettlementFailureDiagnostic | undefined => {
+  const payload = record.payload;
+
+  return payload._tag === "SubmissionSettled" && payload.outcome === "failed"
+    ? payload.result
+    : undefined;
+};
+
+/**
+ * Assignment intent derived only from frozen admission and exact settlement evidence.
+ * Joined receipts and cancellation before a Run starts do not finish an assignment.
+ * Adapters suppress completed intent when newer accepted input remains unapplied, then
+ * install the first seal and outstanding abort intents atomically before releasing the lane.
+ */
+export const workerTerminalFromRecord = (
+  submission: SubmissionSnapshot,
+  record: RecordEnvelope,
+): AssignmentTerminal | undefined => {
+  const payload = record.payload;
+
+  if (
+    submission.workerAdmission?.origin.lifecycle !== "assignment" ||
+    payload._tag !== "SubmissionSettled" ||
+    (payload.runId !== undefined && payload.runId !== `run:${submission.submissionId}`)
+  )
+    return undefined;
+  if (payload.outcome === "failed" || payload.finishReason === "budget-exhausted") return "failed";
+  if (payload.outcome === "aborted") return payload.runId === undefined ? undefined : "cancelled";
+
+  return payload.runDisposition === "completed" ? "completed" : undefined;
+};
+
+/** Destination-owned permanent inbox seal; recorded atomically with all outstanding abort intents. */
+export const WorkerStopCommand = Schema.Struct({
+  threadId: ThreadId,
+  author: Principal,
+});
+
+export type WorkerStopCommand = typeof WorkerStopCommand.Type;
+
+/**
+ * A durable abort command (durability §13). Field bounds are exactly those of the canonical
+ * `AbortRequested` payload so the intent can become canonical without re-validation.
+ */
+export class AbortCommand extends Schema.Class<AbortCommand>("@effect-agent/thread/AbortCommand")({
+  submissionId: SubmissionId,
+  author: AbortRequested.fields.author,
+  reason: AbortRequested.fields.reason,
+}) {}
+
+/**
+ * The recorded abort intent. `canonicalRecordId` is present once the corresponding canonical
+ * `AbortRequested` record has been appended (its identity is deterministic; see
+ * `submissionAbortRecordId`).
+ */
+export class AbortIntent extends Schema.Class<AbortIntent>("@effect-agent/thread/AbortIntent")({
+  submissionId: SubmissionId,
+  author: AbortRequested.fields.author,
+  reason: AbortRequested.fields.reason,
+  requestedAt: Schema.DateTimeUtcFromString,
+  canonicalRecordId: Schema.optionalKey(RecordId),
+}) {}
+
+/** Address one lane-local abort intent without loading unrelated recovery state. */
+export class AbortIntentRequest extends Schema.Class<AbortIntentRequest>(
+  "@effect-agent/thread/AbortIntentRequest",
+)({ submissionId: SubmissionId }) {}
+
+/**
+ * Atomic claim of the contiguous ready prefix of strictly-later queued Submissions for joining
+ * into the active host Run (plan §2.5). Fenced by the host Attempt's ownership token — no epoch
+ * bump, the host already owns the lane. An `admitted`-but-not-`ready` row breaks the prefix;
+ * an aborted-settled row is a closed obligation and is skipped as a non-gap (P7 §7(c)).
+ */
+export class ClaimJoiningRequest extends Schema.Class<ClaimJoiningRequest>(
+  "@effect-agent/thread/ClaimJoiningRequest",
+)({
+  threadId: ThreadId,
+  hostSubmissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+  maxCount: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+/** One queued Submission transitioned to `joining` under the host's ownership. */
+export class JoiningClaim extends Schema.Class<JoiningClaim>("@effect-agent/thread/JoiningClaim")({
+  submissionId: SubmissionId,
+  queueSequence: QueueSequence,
+  inputPayload: PersistedJson,
+}) {}
+
+/**
+ * The canonical position of one joined Submission's `UserInputRecorded` record (`input:{sid}`).
+ * Marking transitions `joining → joined` and records the host linkage established at claim time.
+ */
+export class MarkJoinedRequest extends Schema.Class<MarkJoinedRequest>(
+  "@effect-agent/thread/MarkJoinedRequest",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+  recordId: RecordId,
+  sequence: CanonicalSequence,
+}) {}
+
+/**
+ * Recovery-only revert of a `joining` Submission whose canonical input append never committed
+ * (DUR-016): `joining → ready`, idempotent, a no-op when the Submission already joined.
+ */
+export class RevertJoiningRequest extends Schema.Class<RevertJoiningRequest>(
+  "@effect-agent/thread/RevertJoiningRequest",
+)({
+  submissionId: SubmissionId,
+}) {}
+
+/**
+ * Why one Submission is durably suspended. Approval was the only Phase 5 reason; S2 adds
+ * `WaitingForChild` (spec §12 step 10) and the union keeps later suspension families (e.g.
+ * operator quarantine) additive.
+ */
+export class ApprovalPendingSuspension extends Schema.TaggedClass<ApprovalPendingSuspension>(
+  "@effect-agent/thread/ApprovalPendingSuspension",
+)("ApprovalPending", {
+  toolCallIds: Schema.NonEmptyArray(ToolCallId),
+}) {}
+
+/** One attached child a `waitingForChild` parent is durably waiting on (spec §12 step 10). */
+export class WaitingChild extends Schema.Class<WaitingChild>("@effect-agent/thread/WaitingChild")({
+  toolCallId: ToolCallId,
+  childSubmissionId: SubmissionId,
+}) {}
+
+/**
+ * The parent Attempt ended without settling because attached durable children must settle and
+ * join first (spec §12 step 10, SUB-030). The suspended lane holds no worker permit; each listed
+ * child settles on its own Thread lane and `recordChildSettled` wakes the parent once
+ * every listed child is settled.
+ */
+export class WaitingForChildSuspension extends Schema.TaggedClass<WaitingForChildSuspension>(
+  "@effect-agent/thread/WaitingForChildSuspension",
+)("WaitingForChild", {
+  children: Schema.NonEmptyArray(WaitingChild),
+}) {}
+
+export const SuspensionReason = Schema.Union([
+  ApprovalPendingSuspension,
+  WaitingForChildSuspension,
+]);
+
+export type SuspensionReason = typeof SuspensionReason.Type;
+
+/**
+ * Durable suspension of owned work (plan §2.6): `input-applied`/`running` → `suspended`, the
+ * ownership period ends, NO settlement occurs — the accepted-work obligation stays owed while
+ * the lane consumes no worker permit.
+ */
+export class SuspendRequest extends Schema.Class<SuspendRequest>(
+  "@effect-agent/thread/SuspendRequest",
+)({
+  submissionId: SubmissionId,
+  ownershipToken: OwnershipToken,
+  reason: SuspensionReason,
+}) {}
+
+/**
+ * `suspended` when the lane is now durably waiting; `resume-immediately` when the suspension
+ * reason is already fully covered (a covering decision or child settlement raced ahead of the
+ * suspend transaction), so the caller resumes without releasing the lane.
+ */
+export const SuspensionOutcome = Schema.Literals(["suspended", "resume-immediately"]);
+export type SuspensionOutcome = typeof SuspensionOutcome.Type;
+
+/**
+ * A durable child-settlement notification for one waitingForChild parent (spec §12 step 10).
+ * The child's canonical Settlement is the authority; this command only drives the parent lane's
+ * wake transition.
+ */
+export class ChildSettledNotification extends Schema.Class<ChildSettledNotification>(
+  "@effect-agent/thread/ChildSettledNotification",
+)({
+  parentSubmissionId: SubmissionId,
+  childSubmissionId: SubmissionId,
+}) {}
+
+/**
+ * `woken` when this notification completed the waiting set and the parent transitioned
+ * `suspended(WaitingForChild) → input-applied`; `still-waiting` while other listed children are
+ * unsettled; `not-waiting` when the parent is not (or no longer) suspended waiting on this
+ * child — including replays after a wake, so the operation is idempotent.
+ */
+export const ChildSettledOutcome = Schema.Literals(["woken", "still-waiting", "not-waiting"]);
+export type ChildSettledOutcome = typeof ChildSettledOutcome.Type;
+
+/** Parent-owned child budget reservation identity, deterministically derived by the
+ * coordinator from the parent Run and Tool Call identity (spec §12 step 2). */
+export const ChildReservationId = identifier("ChildReservationId");
+export type ChildReservationId = typeof ChildReservationId.Type;
+
+/**
+ * The reservation state machine (spec §12 steps 2 and 6): `reserved` while the child may still
+ * consume the allocation, `releasePending` once the final accounting decision is frozen, and
+ * `released` after the unused allocation returned exactly once.
+ */
+export const ChildReservationStatus = Schema.Literals(["reserved", "releasePending", "released"]);
+export type ChildReservationStatus = typeof ChildReservationStatus.Type;
+
+/**
+ * Creation input for one parent-owned child budget reservation. The allocation is an opaque
+ * Schema-encoded budget document (D8: adapters implement transitions only and never interpret
+ * budget dimensions); `allocationDigest` must be the digest of its canonical JSON encoding.
+ */
+export class ChildBudgetReservationRequest extends Schema.Class<ChildBudgetReservationRequest>(
+  "@effect-agent/thread/ChildBudgetReservationRequest",
+)({
+  reservationId: ChildReservationId,
+  parentSubmissionId: SubmissionId,
+  parentToolCallId: ToolCallId,
+  ownershipToken: OwnershipToken,
+  allocation: PersistedJson,
+  allocationDigest: Digest,
+}) {}
+
+/** One child budget reservation row as the port exposes it. */
+export class ChildBudgetReservationSnapshot extends Schema.Class<ChildBudgetReservationSnapshot>(
+  "@effect-agent/thread/ChildBudgetReservationSnapshot",
+)({
+  reservationId: ChildReservationId,
+  parentSubmissionId: SubmissionId,
+  parentToolCallId: ToolCallId,
+  childSubmissionId: Schema.optionalKey(SubmissionId),
+  status: ChildReservationStatus,
+  allocation: PersistedJson,
+  allocationDigest: Digest,
+  accounting: Schema.optionalKey(PersistedJson),
+  reservedAt: Schema.DateTimeUtcFromString,
+  releaseBeganAt: Schema.optionalKey(Schema.DateTimeUtcFromString),
+  releasedAt: Schema.optionalKey(Schema.DateTimeUtcFromString),
+}) {}
+
+/**
+ * The committed reservation. `replayed` is true when an identical reservation already existed;
+ * the stored row is returned unchanged so a recovering caller resumes rather than duplicates
+ * (SUB-016).
+ */
+export class ReservedChildBudget extends Schema.Class<ReservedChildBudget>(
+  "@effect-agent/thread/ReservedChildBudget",
+)({
+  reservation: ChildBudgetReservationSnapshot,
+  replayed: Schema.Boolean,
+}) {}
+
+/** Records the admitted child on its reservation row (repairable from `SubagentStarted`). */
+export class AttachChildToReservationRequest extends Schema.Class<AttachChildToReservationRequest>(
+  "@effect-agent/thread/AttachChildToReservationRequest",
+)({
+  reservationId: ChildReservationId,
+  ownershipToken: OwnershipToken,
+  childSubmissionId: SubmissionId,
+}) {}
+
+/**
+ * Freezes the final consumed/released accounting decision (spec §12 join step 6). The
+ * accounting is an opaque Schema-encoded document replayed from the canonical `SubagentJoined`
+ * record (or the deterministic zero-consumed decision for an orphaned reservation), so the
+ * decision itself authorizes the transition — no ownership token is consulted (DUR-015).
+ */
+export class BeginChildBudgetReleaseRequest extends Schema.Class<BeginChildBudgetReleaseRequest>(
+  "@effect-agent/thread/BeginChildBudgetReleaseRequest",
+)({
+  reservationId: ChildReservationId,
+  accounting: PersistedJson,
+}) {}
+
+/** Applies the frozen accounting decision: `releasePending → released`, exactly once. */
+export class ReleaseChildBudgetRequest extends Schema.Class<ReleaseChildBudgetRequest>(
+  "@effect-agent/thread/ReleaseChildBudgetRequest",
+)({
+  reservationId: ChildReservationId,
+}) {}
+
+/**
+ * A durable approval decision command (plan §2.6, `abort`-shaped). Field bounds are exactly those
+ * of the canonical `ToolApprovalDecided` payload so the intent can become canonical without
+ * re-validation.
+ */
+export class ApprovalDecisionCommand extends Schema.Class<ApprovalDecisionCommand>(
+  "@effect-agent/thread/ApprovalDecisionCommand",
+)({
+  submissionId: SubmissionId,
+  toolCallId: ToolCallId,
+  decision: ApprovalDecision,
+  resolver: ToolApprovalDecided.fields.resolver,
+  reason: ToolApprovalDecided.fields.reason,
+}) {}
+
+/**
+ * The recorded approval-decision intent, idempotent per `(submissionId, toolCallId)`.
+ * `canonicalRecordId` is present once the corresponding canonical `ToolApprovalDecided` record
+ * has been appended (see `toolApprovalDecisionRecordId`).
+ */
+export class ApprovalDecisionIntent extends Schema.Class<ApprovalDecisionIntent>(
+  "@effect-agent/thread/ApprovalDecisionIntent",
+)({
+  submissionId: SubmissionId,
+  toolCallId: ToolCallId,
+  decision: ApprovalDecision,
+  resolver: ToolApprovalDecided.fields.resolver,
+  reason: ToolApprovalDecided.fields.reason,
+  decidedAt: Schema.DateTimeUtcFromString,
+  canonicalRecordId: Schema.optionalKey(RecordId),
+}) {}
+
+/**
+ * Durable Unknown marking for one Submission's open ordinary Tool Calls (DUR-009): state →
+ * `unknown`, parking that Submission without changing ownership or the Thread epoch. Idempotent.
+ */
+export class MarkUnknownRequest extends Schema.Class<MarkUnknownRequest>(
+  "@effect-agent/thread/MarkUnknownRequest",
+)({
+  submissionId: SubmissionId,
+  toolCallIds: Schema.NonEmptyArray(ToolCallId),
+  reason: ToolCallUnknown.fields.reason,
+}) {}
+
+/** The recovered supplier truth: the external effect completed with this exact result. */
+export class ResolutionCompletedWithResult extends Schema.TaggedClass<ResolutionCompletedWithResult>(
+  "@effect-agent/thread/ResolutionCompletedWithResult",
+)("CompletedWithResult", {
+  result: PersistedJson,
+  isFailure: Schema.Boolean,
+}) {}
+
+/** The external effect provably never happened; the call may re-execute on resume. */
+export class ResolutionNeverHappened extends Schema.TaggedClass<ResolutionNeverHappened>(
+  "@effect-agent/thread/ResolutionNeverHappened",
+)("NeverHappened", {}) {}
+
+/** The call is safe to repeat under the external system's idempotency contract. */
+export class ResolutionSafeToRetry extends Schema.TaggedClass<ResolutionSafeToRetry>(
+  "@effect-agent/thread/ResolutionSafeToRetry",
+)("SafeToRetry", {}) {}
+
+/** Give up on the Submission: route into the abort path (unknown calls stay recorded; abort
+ * never claims external rollback, durability §13). */
+export class ResolutionAbortSubmission extends Schema.TaggedClass<ResolutionAbortSubmission>(
+  "@effect-agent/thread/ResolutionAbortSubmission",
+)("AbortSubmission", {}) {}
+
+/** How an authorized resolver closed one Unknown Outcome (DUR-017). */
+export const UnknownResolution = Schema.Union([
+  ResolutionCompletedWithResult,
+  ResolutionNeverHappened,
+  ResolutionSafeToRetry,
+  ResolutionAbortSubmission,
+]);
+
+export type UnknownResolution = typeof UnknownResolution.Type;
+
+/**
+ * A durable Unknown-Outcome resolution command (DUR-017, `abort`-shaped). Possession of the
+ * runtime service plus the mandatory `author`/`reason` audit fields is the Phase 5 authorization
+ * boundary — identical to `abort`; the authenticated operator surface is a P7 deliverable.
+ * Field bounds are exactly those of the canonical `ToolCallResolved` payload.
+ */
+export class UnknownResolutionCommand extends Schema.Class<UnknownResolutionCommand>(
+  "@effect-agent/thread/UnknownResolutionCommand",
+)({
+  submissionId: SubmissionId,
+  toolCallId: ToolCallId,
+  author: ToolCallResolved.fields.author,
+  reason: ToolCallResolved.fields.reason,
+  resolution: UnknownResolution,
+}) {}
+
+/**
+ * The recorded resolution intent, idempotent per `(submissionId, toolCallId)`. The canonical
+ * `ToolCallResolved` (+ `ToolCallSettled` for `CompletedWithResult`) is appended by the recovery
+ * pass or the next owning Attempt; `canonicalRecordId` is present once it is.
+ */
+export class UnknownResolutionIntent extends Schema.Class<UnknownResolutionIntent>(
+  "@effect-agent/thread/UnknownResolutionIntent",
+)({
+  submissionId: SubmissionId,
+  toolCallId: ToolCallId,
+  author: ToolCallResolved.fields.author,
+  reason: ToolCallResolved.fields.reason,
+  resolution: UnknownResolution,
+  resolvedAt: Schema.DateTimeUtcFromString,
+  canonicalRecordId: Schema.optionalKey(RecordId),
+}) {}
+
+/** Current ownership as recovery sees it. The live owner's token is never exposed here. */
+export class OwnershipSnapshot extends Schema.Class<OwnershipSnapshot>(
+  "@effect-agent/thread/OwnershipSnapshot",
+)({
+  attemptId: AttemptId,
+  ownerProducerId: ProducerId,
+  producerEpoch: ProducerEpoch,
+  leaseExpiresAt: Schema.DateTimeUtcFromString,
+}) {}
+
+/** A settlement reservation as recovery sees it. */
+export class SettlementReservationSnapshot extends Schema.Class<SettlementReservationSnapshot>(
+  "@effect-agent/thread/SettlementReservationSnapshot",
+)({
+  settlementId: SettlementId,
+  outcome: SettlementOutcome,
+  record: RecordEnvelope,
+  recordDigest: Digest,
+  finalized: Schema.Boolean,
+}) {}
+
+export class RecoverySnapshotRequest extends Schema.Class<RecoverySnapshotRequest>(
+  "@effect-agent/thread/RecoverySnapshotRequest",
+)({
+  submissionId: SubmissionId,
+}) {}
+
+/** One joined/joining Submission of a host Run, as the host's recovery sees it. */
+export class JoinSnapshot extends Schema.Class<JoinSnapshot>("@effect-agent/thread/JoinSnapshot")({
+  submissionId: SubmissionId,
+  state: SubmissionState,
+  hostSubmissionId: SubmissionId,
+}) {}
+
+/** A durable suspension as recovery sees it. */
+export class SuspensionSnapshot extends Schema.Class<SuspensionSnapshot>(
+  "@effect-agent/thread/SuspensionSnapshot",
+)({
+  reason: SuspensionReason,
+  suspendedAt: Schema.DateTimeUtcFromString,
+}) {}
+
+/**
+ * One attached child of this parent as its recovery sees it: the reservation's recorded child
+ * plus that child's current lane state. A disposable derived view — the canonical
+ * `SubagentRequested`/`SubagentStarted` records and the child's own canonical Settlement remain
+ * the recovery truth (DUR-015).
+ */
+export class ChildAttachmentSnapshot extends Schema.Class<ChildAttachmentSnapshot>(
+  "@effect-agent/thread/ChildAttachmentSnapshot",
+)({
+  toolCallId: ToolCallId,
+  childSubmissionId: SubmissionId,
+  childState: SubmissionState,
+  childOutcome: Schema.optionalKey(SettlementOutcome),
+}) {}
+
+/**
+ * Everything the pure recovery classifier needs about one Submission, read strongly consistently
+ * (STORE-003). Canonical history still wins over every marker in this snapshot (DUR-015).
+ *
+ * Phase 5 fields: `joins` is the host-side view (every Submission `joining`/`joined` to this
+ * one); `hostSubmissionId` is the joined-side view; `suspension` mirrors the `suspended` state;
+ * `approvalDecisions` and `unknownResolutions` are the durable intents recorded against this
+ * Submission (empty when none exist).
+ *
+ * S2 fields: `childReservations`/`childAttachments` are the parent-side subagent view (ordered
+ * by parent Tool Call id) and `parentLinkage` is the child-side view. They default to
+ * empty/absent at construction so pre-S2 call sites stay valid; adapters always populate them.
+ */
+export class RecoverySnapshot extends Schema.Class<RecoverySnapshot>(
+  "@effect-agent/thread/RecoverySnapshot",
+)({
+  submission: SubmissionSnapshot,
+  ownership: Schema.optionalKey(OwnershipSnapshot),
+  inputApplied: Schema.optionalKey(InputAppliedMarker),
+  reservation: Schema.optionalKey(SettlementReservationSnapshot),
+  abortIntent: Schema.optionalKey(AbortIntent),
+  joins: Schema.Array(JoinSnapshot),
+  hostSubmissionId: Schema.optionalKey(SubmissionId),
+  suspension: Schema.optionalKey(SuspensionSnapshot),
+  approvalDecisions: Schema.Array(ApprovalDecisionIntent),
+  unknownResolutions: Schema.Array(UnknownResolutionIntent),
+  childReservations: Schema.Array(ChildBudgetReservationSnapshot).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+  ),
+  childAttachments: Schema.Array(ChildAttachmentSnapshot).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+  ),
+  parentLinkage: Schema.optionalKey(ParentLinkage),
+}) {}
+
+/** The same idempotency key was admitted with different canonical input content. */
+export class AdmissionConflict extends Schema.TaggedError<AdmissionConflict>()(
+  "AdmissionConflict",
+  {
+    threadId: ThreadId,
+    principal: Principal,
+    idempotencyKey: IdempotencyKey,
+    existingInputDigest: Digest,
+    attemptedInputDigest: Digest,
+  },
+) {}
+
+/**
+ * The presented ownership token no longer owns the Submission's lane. `actualEpoch` is the
+ * thread's current producer epoch so a stale Attempt can prove to itself it was superseded.
+ */
+export class OwnershipLost extends Schema.TaggedError<OwnershipLost>()("OwnershipLost", {
+  submissionId: SubmissionId,
+  actualEpoch: ProducerEpoch,
+}) {}
+
+/** A conflicting terminal outcome was already reserved or finalized (DUR-002, DUR-012). */
+export class SettlementConflict extends Schema.TaggedError<SettlementConflict>()(
+  "SettlementConflict",
+  {
+    submissionId: SubmissionId,
+    existingOutcome: SettlementOutcome,
+  },
+) {}
+
+/**
+ * A divergent approval re-decision for an already-decided `(submissionId, toolCallId)` pair.
+ * Repeating the SAME decision replays the recorded intent instead (idempotency).
+ */
+export class ApprovalConflict extends Schema.TaggedError<ApprovalConflict>()("ApprovalConflict", {
+  submissionId: SubmissionId,
+  toolCallId: ToolCallId,
+  existingDecision: ApprovalDecision,
+}) {}
+
+/**
+ * A divergent unknown-outcome re-resolution for an already-resolved `(submissionId, toolCallId)`
+ * pair (DUR-017). Repeating the SAME resolution replays the recorded intent instead.
+ */
+export class UnknownResolutionConflict extends Schema.TaggedError<UnknownResolutionConflict>()(
+  "UnknownResolutionConflict",
+  {
+    submissionId: SubmissionId,
+    toolCallId: ToolCallId,
+  },
+) {}
+
+/**
+ * A child budget reservation request contradicts recorded reservation state: a divergent
+ * allocation for the same reservation id, a second reservation id for the same parent Tool
+ * Call, a divergent child attachment, a divergent accounting freeze, or an out-of-order state
+ * transition. `status` reports the existing row's status. Identical replays never conflict.
+ */
+export class ChildReservationConflict extends Schema.TaggedError<ChildReservationConflict>()(
+  "ChildReservationConflict",
+  {
+    reservationId: ChildReservationId,
+    status: ChildReservationStatus,
+    message: Schema.String,
+  },
+) {}
+
+/** Adapter-level ledger failure (storage unavailable, unknown submission, corrupt row, ...). */
+export class LedgerError extends Schema.TaggedError<LedgerError>()("LedgerError", {
+  operation: Schema.String,
+  message: Schema.String,
+  cause: Schema.optionalKey(FailureDiagnostic.Value),
+}) {}
+
+export type SubmissionLedgerFailure =
+  | AdmissionConflict
+  | OwnershipLost
+  | SettlementConflict
+  | ApprovalConflict
+  | UnknownResolutionConflict
+  | JoinedToHost
+  | ChildReservationConflict
+  | LedgerError
+  | AdmissionPolicyError;
+
+/**
+ * Operational durable state for accepted work: admission, FIFO readiness, ownership, leases,
+ * abort intent, and settlement obligations (STORE-001). The Thread Log remains the
+ * authority for applied input and terminal outcomes; every marker in this ledger can be rebuilt
+ * from canonical history (DUR-015).
+ *
+ * Operation contracts:
+ *
+ * - `admit` — atomic and idempotent by (threadId, principal, idempotencyKey). A replay
+ *   with the same `inputDigest` returns the original `AdmissionResult` with `replayed` set; a
+ *   replay with a different digest fails with `AdmissionConflict`. Admission allocates the
+ *   Submission's `queueSequence` (FIFO position, DUR-004) and mints `submissionId`/`receiptId`.
+ *   An optional `parentLinkage` is recorded immutably at first admission (SUB-016); a replay
+ *   whose linkage diverges (present vs. absent, or different identities) fails with
+ *   `AdmissionConflict` even when the input digest matches.
+ * - `resolveAdmission` — authoritative tri-state admission lookup by scoped idempotency key
+ *   (SUB-031): `NotAdmitted` proves absence, `Admitted` carries the full snapshot, and
+ *   `Indeterminate` states that the adapter cannot currently prove either. Only `NotAdmitted`
+ *   permits an admission attempt. Single strongly consistent stores derive the answer from a
+ *   direct lookup and never answer `Indeterminate`.
+ * - `markReady` — idempotent transition admitted → ready after Thread materialization.
+ *   Marking an already-ready (or later-state) Submission is a no-op.
+ * - `lookup` — read one Submission by identity or scoped idempotency key; strongly consistent
+ *   with prior ledger writes.
+ * - `claim` — claims the lowest unsettled `queueSequence` after skipping only unknown rows
+ *   without abort intent. Approval, joining and child-wait barriers remain ordered. Returns
+ *   `Option.none` when no eligible work exists or ANY lease in the Thread is live, including
+ *   a lease belonging to the same producer. A successful claim atomically bumps the Thread's producer
+ *   epoch — fencing every stale Attempt out of canonical appends (DUR-006) — mints a fresh
+ *   `attemptId` and `ownershipToken`, and starts the ownership lease (D5: adapters default to
+ *   `DEFAULT_OWNERSHIP_LEASE_DURATION`, configurable). An expired lease makes the head
+ *   claimable; expiry alone never revokes correctness, only permission to assume liveness.
+ * - `renewOwnership` — extends the lease while the token still owns the lane; fails with
+ *   `OwnershipLost` once superseded. Renewal after lease expiry succeeds if no other claim has
+ *   taken the lane in between.
+ * - `releaseOwnership` — graceful drain: ends the ownership period without settling, returning
+ *   a nonterminal head to claimable state. Fails with `OwnershipLost` once superseded.
+ * - `markInputApplied` — idempotent marker that the deterministic `UserInputRecorded` record is
+ *   canonical (state → input-applied). Recovery repairs this marker from history when the append
+ *   committed but the marker write was lost.
+ * - `reserveSettlement` — reserves the Submission's single exact settlement record
+ *   (state → terminalizing). Idempotent: an identical reservation replays with `replayed` set; a
+ *   different outcome or content fails with `SettlementConflict{existingOutcome}` (DUR-011).
+ *   For a `joined` Submission the reservation is authorized by its recorded host linkage — a
+ *   joined lane is never worker-claimable, so no ownership token can exist for it and the
+ *   presented token is not consulted (plan §2.5: joined Submissions settle with the host).
+ *   Likewise, an ABORTED reservation for a `ready`/`terminalizing` Submission that carries a
+ *   durable abort intent and holds no live ownership is authorized by that intent (P7 §7(c)):
+ *   recovery settles aborted never-claimed queued work immediately, without waiting for it to
+ *   head the lane. Both exceptions are outcome- and state-narrow; everything else stays fenced.
+ * - `finalizeSettlement` — idempotent terminal transition (state → settled) after the reserved
+ *   record is canonical. Native adapters seal opted-in worker assignments atomically before
+ *   releasing the lane. Otherwise the next `queueSequence` becomes claimable. It
+ *   requires no ownership token: canonical history authorizes finalization (DUR-015). A
+ *   finalization that disagrees with the recorded outcome fails with `SettlementConflict`.
+ * - `requestAbort` — durable, idempotent by `submissionId`: repeating returns the recorded
+ *   intent unchanged (DUR-012). Fails with `SettlementConflict` once the Submission is settled;
+ *   abort never rewrites a terminal outcome. Fails with `JoinedToHost` for a `joined` Submission
+ *   — it settles with its host, so the abort target is the host (plan §2.5). Abort of a
+ *   `joining` Submission records the intent; it is honored only if the host has not consumed the
+ *   input (revert-then-abort).
+ * - `claimJoining` — atomic: transitions the contiguous `ready` prefix of strictly-later
+ *   `queueSequence`s (up to `maxCount`) to `joining` under the host's ownership token, recording
+ *   the host linkage; no epoch bump (the host Attempt already owns the lane). An
+ *   `admitted`-not-`ready` row breaks the prefix; an aborted-settled row is a closed obligation
+ *   and is skipped as a non-gap (P7 §7(c)). Fails with `OwnershipLost` once superseded.
+ * - `markJoined` — idempotent `joining → joined` with the canonical input record position;
+ *   repairable from history when the append committed but the marker write was lost (DUR-016).
+ * - `revertJoining` — recovery-only, idempotent `joining → ready`; a no-op when already joined.
+ * - `suspend` — `input-applied`/`running` → `suspended`; ends the ownership period WITHOUT
+ *   settling (the obligation stays owed, the lane consumes no worker permit). Returns
+ *   `resume-immediately` when the reason is already fully covered: for `ApprovalPending`,
+ *   recorded decisions cover every pending call; for `WaitingForChild`, every listed child is
+ *   already provably settled. Adapters must guarantee that a child settlement reported before
+ *   the suspend transaction commits is observed by that suspend (single-store adapters derive
+ *   this from the child's own row; cross-store adapters record a durable notification marker).
+ *   Fails with `SettlementConflict` once settled.
+ * - `recordApprovalDecision` — durable, idempotent per `(submissionId, toolCallId)`: repeating
+ *   the same decision replays the intent; a divergent re-decision fails with `ApprovalConflict`.
+ *   Transitions `suspended(ApprovalPending) → input-applied` once every pending call of the
+ *   suspension reason is decided, waking the lane. Fails with `SettlementConflict` once settled.
+ * - `recordChildSettled` — idempotent cross-lane wake (spec §12 step 10): transitions
+ *   `suspended(WaitingForChild) → input-applied` exactly when EVERY listed child is settled,
+ *   answering `woken`; `still-waiting` while any listed child is unsettled; `not-waiting` when
+ *   the parent is not suspended waiting on this child (including replays after the wake). The
+ *   child's canonical Settlement is the authority. The runtime reports it after the exact
+ *   reserved record is appended and before ledger finalization, so same-store adapters accept
+ *   `terminalizing` only when its exact reservation exists; an earlier child is an
+ *   adapter-checked caller error. It never settles the parent and requires no ownership token:
+ *   the canonically recorded child settlement authorizes the wake.
+ * - `reserveChildBudget` — idempotent get-or-create of the parent-owned child budget
+ *   reservation (spec §12 step 2), fenced by the parent lane's live `OwnershipToken`. An
+ *   identical replay returns the stored row with `replayed` set (unfenced, mirroring
+ *   `reserveSettlement`); a divergent allocation for the same id, or a second id for the same
+ *   `(parentSubmissionId, parentToolCallId)`, fails with `ChildReservationConflict`.
+ * - `attachChildToReservation` — idempotent: records the admitted child on the reservation row
+ *   (repairable from the canonical `SubagentStarted` record). A replay with the recorded child
+ *   is a no-op; the first attach is fenced by the parent token and requires status `reserved`;
+ *   a divergent child fails with `ChildReservationConflict`.
+ * - `beginChildBudgetRelease` — `reserved → releasePending`: freezes the final accounting
+ *   decision exactly once. Replaying the identical accounting (at `releasePending` or
+ *   `released`) is a no-op; a divergent accounting fails with `ChildReservationConflict`.
+ *   Requires no ownership token: the accounting is replayed from the canonical `SubagentJoined`
+ *   record (or is the deterministic zero-consumed decision for an orphaned reservation), so
+ *   canonical history authorizes the transition (DUR-015) and the freeze comparison — not a
+ *   fence — guarantees one decision.
+ * - `releaseChildBudget` — `releasePending → released`, applied exactly once; replaying returns
+ *   the released row unchanged. Releasing a still-`reserved` row (no frozen accounting) fails
+ *   with `ChildReservationConflict`. "A crash before release leaves budget unavailable until
+ *   repair, never available twice" (spec §12).
+ * - `markUnknown` — idempotent, ownership-free (canonical evidence authorizes it): state →
+ *   `unknown`, parking the Submission while its accepted settlement obligation stays visible.
+ *   Existing ownership must release or expire before another claim (DUR-009/DUR-017).
+ *   Fails with `SettlementConflict` once settled.
+ * - `recordUnknownResolution` — durable, idempotent per `(submissionId, toolCallId)`; a
+ *   divergent re-resolution fails with `UnknownResolutionConflict`. Transitions
+ *   `unknown → input-applied` once no open call remains, waking the lane. Fails with
+ *   `SettlementConflict` once settled.
+ * - `scanNonterminal` — streams control-only entries for every Submission whose state is not
+ *   `settled`, ordered by (threadId, queueSequence); recovery's admission-independent worklist
+ *   (DUR-014). It must not decode execution payloads. SQL or control-identity corruption fails
+ *   the scan; selected-Thread payload hydration belongs inside the caller's isolation boundary.
+ * - `loadRecoverySnapshot` — strongly consistent full snapshot for the pure recovery classifier.
+ *
+ * No operation claims exactly-once external side effects; the ledger records decisions
+ * exactly once (DUR-003).
+ */
+export class SubmissionLedger extends Context.Service<
+  SubmissionLedger,
+  {
+    readonly capabilities: Effect.Effect<LedgerCapabilities>;
+    readonly admit: (
+      request: AdmissionRequest,
+    ) => Effect.Effect<AdmissionResult, AdmissionConflict | AdmissionPolicyError | LedgerError>;
+    readonly markReady: (request: MarkReadyRequest) => Effect.Effect<void, LedgerError>;
+    readonly lookup: (
+      request: SubmissionLookup,
+    ) => Effect.Effect<Option.Option<SubmissionSnapshot>, LedgerError>;
+    readonly resolveAdmission: (
+      request: SubmissionLookupByKey,
+    ) => Effect.Effect<AdmissionResolution, LedgerError>;
+    readonly claim: (request: ClaimRequest) => Effect.Effect<Option.Option<Claim>, LedgerError>;
+    readonly renewOwnership: (
+      request: RenewOwnershipRequest,
+    ) => Effect.Effect<OwnershipRenewal, OwnershipLost | LedgerError>;
+    readonly releaseOwnership: (
+      request: ReleaseOwnershipRequest,
+    ) => Effect.Effect<void, OwnershipLost | LedgerError>;
+    readonly markInputApplied: (
+      request: MarkInputAppliedRequest,
+    ) => Effect.Effect<void, OwnershipLost | LedgerError>;
+    readonly reserveSettlement: (
+      request: SettlementReservation,
+    ) => Effect.Effect<ReservedSettlement, SettlementConflict | OwnershipLost | LedgerError>;
+    readonly finalizeSettlement: (
+      request: SettlementFinalization,
+    ) => Effect.Effect<Settlement, SettlementConflict | LedgerError>;
+    /** Optional for third-party adapters. Remaining ownership must reach zero before stop acknowledgement. */
+    readonly inspectWorker?: (threadId: ThreadId) => Effect.Effect<WorkerLedgerState, LedgerError>;
+    readonly stopWorker?: (request: WorkerStopCommand) => Effect.Effect<number, LedgerError>;
+    readonly requestAbort: (
+      request: AbortCommand,
+    ) => Effect.Effect<AbortIntent, SettlementConflict | JoinedToHost | LedgerError>;
+    /**
+     * Strongly consistent lane-local read. Unknown Submissions fail with LedgerError. Canonical
+     * proof has the same meaning as in RecoverySnapshot; this read grants no execution authority.
+     */
+    readonly readAbortIntent: (
+      request: AbortIntentRequest,
+    ) => Effect.Effect<AbortIntent | undefined, LedgerError>;
+    readonly claimJoining: (
+      request: ClaimJoiningRequest,
+    ) => Effect.Effect<ReadonlyArray<JoiningClaim>, OwnershipLost | LedgerError>;
+    readonly markJoined: (
+      request: MarkJoinedRequest,
+    ) => Effect.Effect<void, OwnershipLost | LedgerError>;
+    readonly revertJoining: (request: RevertJoiningRequest) => Effect.Effect<void, LedgerError>;
+    readonly suspend: (
+      request: SuspendRequest,
+    ) => Effect.Effect<SuspensionOutcome, OwnershipLost | SettlementConflict | LedgerError>;
+    readonly recordApprovalDecision: (
+      command: ApprovalDecisionCommand,
+    ) => Effect.Effect<ApprovalDecisionIntent, ApprovalConflict | SettlementConflict | LedgerError>;
+    readonly markUnknown: (
+      request: MarkUnknownRequest,
+    ) => Effect.Effect<void, SettlementConflict | LedgerError>;
+    readonly recordUnknownResolution: (
+      command: UnknownResolutionCommand,
+    ) => Effect.Effect<
+      UnknownResolutionIntent,
+      UnknownResolutionConflict | SettlementConflict | LedgerError
+    >;
+    readonly recordChildSettled: (
+      request: ChildSettledNotification,
+    ) => Effect.Effect<ChildSettledOutcome, LedgerError>;
+    readonly reserveChildBudget: (
+      request: ChildBudgetReservationRequest,
+    ) => Effect.Effect<ReservedChildBudget, ChildReservationConflict | OwnershipLost | LedgerError>;
+    readonly attachChildToReservation: (
+      request: AttachChildToReservationRequest,
+    ) => Effect.Effect<
+      ChildBudgetReservationSnapshot,
+      ChildReservationConflict | OwnershipLost | LedgerError
+    >;
+    readonly beginChildBudgetRelease: (
+      request: BeginChildBudgetReleaseRequest,
+    ) => Effect.Effect<ChildBudgetReservationSnapshot, ChildReservationConflict | LedgerError>;
+    readonly releaseChildBudget: (
+      request: ReleaseChildBudgetRequest,
+    ) => Effect.Effect<ChildBudgetReservationSnapshot, ChildReservationConflict | LedgerError>;
+    readonly scanNonterminal: Stream.Stream<SubmissionWorkItem, LedgerError>;
+    readonly loadRecoverySnapshot: (
+      request: RecoverySnapshotRequest,
+    ) => Effect.Effect<RecoverySnapshot, LedgerError>;
+  }
+>()("@effect-agent/thread/SubmissionLedger") {}
+
+const decodeBatchId = Schema.decodeSync(BatchId);
+const decodeRecordId = Schema.decodeSync(RecordId);
+const decodeSettlementId = Schema.decodeSync(SettlementId);
+
+/**
+ * Deterministic identity rules shared by every adapter and the durable coordinator. The batch
+ * carrying one Submission's canonical `UserInputRecorded` record is `submission-input:{sid}` and
+ * the record is `input:{sid}`, so batch idempotency (DUR-007) makes the input append
+ * exactly-once-canonical across Attempts.
+ */
+export const submissionInputBatchId = (submissionId: SubmissionId): BatchId =>
+  decodeBatchId(`submission-input:${submissionId}`);
+
+/** Deterministic canonical record identity of one Submission's `UserInputRecorded` record. */
+export const submissionInputRecordId = (submissionId: SubmissionId): RecordId =>
+  decodeRecordId(`input:${submissionId}`);
+
+/** Deterministic `SettlementId` for one Submission: `settlement:{sid}`. */
+export const submissionSettlementId = (submissionId: SubmissionId): SettlementId =>
+  decodeSettlementId(`settlement:${submissionId}`);
+
+/** Deterministic batch identity of one Submission's canonical `SubmissionSettled` append. */
+export const submissionSettlementBatchId = (submissionId: SubmissionId): BatchId =>
+  decodeBatchId(`submission-settlement:${submissionId}`);
+
+/** Deterministic canonical record identity of one Submission's `SubmissionSettled` record. */
+export const submissionSettlementRecordId = (submissionId: SubmissionId): RecordId =>
+  decodeRecordId(`settlement:${submissionId}`);
+
+/** Deterministic batch identity of one Submission's canonical `AbortRequested` append. */
+export const submissionAbortBatchId = (submissionId: SubmissionId): BatchId =>
+  decodeBatchId(`submission-abort:${submissionId}`);
+
+/** Deterministic canonical record identity of one Submission's `AbortRequested` record. */
+export const submissionAbortRecordId = (submissionId: SubmissionId): RecordId =>
+  decodeRecordId(`abort:${submissionId}`);
+
+/** Destination policy, captured when the ledger is acquired. It runs inside fresh admission's
+ * serialization after replay lookup. The host must keep it bounded and must not reenter admit.
+ * The callback must read authoritative policy in this SAME local transaction, through the
+ * acquired SqlClient. Memory evaluates the callback synchronously inside its atomic mutation;
+ * an async callback fails with `unavailable/synchronous-memory-policy-required`. Remote reads do not fence remote changes.
+ * All policy writers must use that transaction owner. Do not fork, reenter admission, or retain
+ * transaction resources. Failure/defect/interruption commits no fresh admission.
+ * Current policy never invalidates an exact retained receipt. A supplied fence fails closed
+ * unless the destination installed an interpreter for it. */
+export const SubmissionAdmissionFence = Context.Reference<{
+  readonly check: (request: AdmissionRequest) => Effect.Effect<void, AdmissionPolicyError>;
+}>("@effect-agent/thread/SubmissionAdmissionFence", {
+  defaultValue: () => ({
+    check: (request) =>
+      request.admissionFence === undefined
+        ? Effect.void
+        : AdmissionPolicyError.make({
+            reason: "refused",
+            code: "unsupported-policy",
+          }),
+  }),
+});