open-multi-agent-kit 1.0.0 → 1.2.2

package/dist/coordination/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/coordination/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkBtC,MAAM,eAAe,GAAgC,IAAI,GAAG,CAAiB;IAC5E,UAAU;IACV,qBAAqB;IACrB,kBAAkB;IAClB,2BAA2B;CAC3B,CAAC,CAAC;AAyCH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAkB,EAAkB;IAClE,KAAK,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3G,IAAI,OAAO,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAC;IACtF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAClH,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YAC5E,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;QAC1E,CAAC;IACF,CAAC;IACD,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACpE,IAAI,CAAC,KAAK,CAAC,aAAa;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7E,IAAI,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,qBAAqB,KAAK,KAAK,CAAC,aAAa,EAAE,CAAC;QACxG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACxD,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,KAAK,CAAC,sBAAsB;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC7G,IAAI,CAAC,KAAK,CAAC,gBAAgB;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IACtF,IAAI,CAAC,KAAK,CAAC,eAAe;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAClF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAAA,CACzB;AAED,MAAM,OAAO,kBAAkB;IACrB,WAAW,CAAS;IACrB,OAAO,GAAmB,SAAS,CAAC;IAC3B,MAAM,GAAqB,CAAC,SAAS,CAAC,CAAC;IAChD,YAAY,GAAkC,EAAE,CAAC;IACjD,QAAQ,CAAiC;IACzC,gBAAgB,CAAoC;IACpD,aAAa,GAAG,KAAK,CAAC;IACtB,eAAe,GAAG,KAAK,CAAC;IAEhC,YAAY,WAAmB,EAAE;QAChC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAAA,CAC/B;IAED,IAAI,KAAK,GAAmB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC;IAAA,CACpB;IAED,IAAI,OAAO,GAA8B;QACxC,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAAA,CACxB;IAED,+EAA+E;IAC/E,IAAI,UAAU,GAAY;QACzB,OAAO,IAAI,CAAC,aAAa,CAAC;IAAA,CAC1B;IAED,IAAI,qBAAqB,GAAY;QACpC,OAAO,IAAI,CAAC,eAAe,CAAC;IAAA,CAC5B;IAEO,KAAK,CAAC,IAAoB,EAAQ;QACzC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAAA,CACvB;IAEO,UAAU,GAAS;QAC1B,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,WAAW,yBAAyB,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IAAA,CACD;IAED,8EAA8E;IAC9E,OAAO,CAAC,UAAyC,EAAQ;QACxD,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;QAClG,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;YAC/C,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACvF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;oBAC5E,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;gBAC/E,CAAC;YACF,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,CAAC;gBACpB,aAAa,EAAE,SAAS,CAAC,aAAa;gBACtC,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,kBAAkB,EAAE,QAAQ,CAAC,SAAS,CAAC,kBAAkB,CAAC;aAC1D,CAAC,CAAC;QAAA,CACH,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAAA,CACvB;IAED,mFAAmF;IACnF,OAAO,CAAC,SAA6B,EAAQ;QAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CACnC,CAAC,CAAC,EAAE,EAAE,CACL,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC,aAAa;YAC3C,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;YACjC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;YACjC,CAAC,CAAC,kBAAkB,KAAK,SAAS,CAAC,kBAAkB,CACtD,CAAC;QACF,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QACnG,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAAA,CACvB;IAED,SAAS,CAAC,MAAmB,EAAkB;QAC9C,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC5F,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACvB,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC7C,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACzB,OAAO,QAAQ,CAAC;IAAA,CAChB;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,MAAmB,EAAkB;QAC7C,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAChG,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC1F,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACvB,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC7C,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACvC,IACC,QAAQ,KAAK,SAAS;YACtB,QAAQ,CAAC,YAAY,KAAK,MAAM,CAAC,YAAY;YAC7C,QAAQ,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc;YACjD,QAAQ,CAAC,aAAa,KAAK,MAAM,CAAC,aAAa;YAC/C,QAAQ,CAAC,qBAAqB,KAAK,MAAM,CAAC,qBAAqB,EAC9D,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QACxD,CAAC;QACD,IAAI,QAAQ,CAAC,eAAe,KAAK,MAAM,CAAC,eAAe,EAAE,CAAC;YACzD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAClD,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACzB,OAAO,QAAQ,CAAC;IAAA,CAChB;IAEO,sBAAsB,CAAC,MAAoB,EAAQ;QAC1D,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACzC,CAAC;IAAA,CACD;IAED,0EAA0E;IAC1E,MAAM,CAAC,OAAuB,EAAQ;QACrC,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACnF,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,kBAAkB,IAAI,OAAO,KAAK,iBAAiB,EAAE,CAAC;YAC9F,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;QAChD,CAAC;QACD,4EAA4E;QAC5E,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO;QACrC,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,iBAAiB,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAAA,CACpB;IAED,yEAAyE;IACzE,MAAM,CAAC,gBAAyB,EAAQ;QACvC,IAAI,OAAO,gBAAgB,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;QAClG,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC;IAAA,CAClE;IAED;;;;;;OAMG;IACH,MAAM,GAAS;QACd,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO;QAC9C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACxC,OAAO;QACR,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY;YAAE,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAAA,CACjE;CACD","sourcesContent":["/**\n * Authorized operation lifecycle for GUI-driving adapters (Jev audit A6).\n *\n * Two reproduced defects shape this module:\n *   F01 — an adapter re-interpreted a free-text instruction at execution time,\n *         so an approved candidate and the executed action could differ. Here\n *         dispatch consumes a recorded observation binding, never a sentence.\n *   F02 — a cancellation signal was accepted and then ignored across the\n *         approval await, so a cancelled operation still dispatched. Here the\n *         permit is re-evaluated at the dispatch boundary, and cancellation\n *         after dispatch can never be reported as cancelled-before-dispatch.\n *\n * Pure state machine: no browser, no driver, no timers. \"Dispatched\" means the\n * command left this process, which is not evidence about the remote effect —\n * that is why `outcome-unknown` is a first-class state rather than a failure.\n */\n\nimport type { Sequence } from \"./types.ts\";\nimport { sequence } from \"./types.ts\";\n\nexport type OperationState =\n\t| \"created\"\n\t| \"observed\"\n\t| \"proposed\"\n\t| \"authorized\"\n\t| \"dispatched\"\n\t| \"applied\"\n\t| \"verified\"\n\t| \"inspection-required\"\n\t| \"failed-confirmed\"\n\t| \"outcome-unknown\"\n\t| \"cancelled-before-dispatch\";\n\n/** Outcomes a driver may report once a command has left the process. */\nexport type SettledOutcome = \"applied\" | \"failed-confirmed\" | \"outcome-unknown\";\n\nconst TERMINAL_STATES: ReadonlySet<OperationState> = new Set<OperationState>([\n\t\"verified\",\n\t\"inspection-required\",\n\t\"failed-confirmed\",\n\t\"cancelled-before-dispatch\",\n]);\n\n/**\n * Host-held reference to one observed candidate.\n *\n * The adapter receives these identifiers, not an instruction string, so the\n * action that was approved is the action that runs.\n */\nexport interface ObservationBinding {\n\treadonly observationId: string;\n\treadonly actionId: string;\n\treadonly targetId: string;\n\t/** Document/DOM generation the candidate was observed against. */\n\treadonly documentGeneration: Sequence;\n}\n\nexport type PermitDenial =\n\t| \"cancelled\"\n\t| \"policy-denied\"\n\t| \"approval-mismatch\"\n\t| \"stale-lease\"\n\t| \"observation-invalid\"\n\t| \"budget-exhausted\";\n\nexport type PermitDecision = { readonly allowed: true } | { readonly allowed: false; readonly reason: PermitDenial };\n\nexport interface PermitInput {\n\treadonly policyAllowed: boolean;\n\t/** Digest of the intent actually about to run. */\n\treadonly intentDigest: string;\n\t/** Digest the operator approved; a post-approval edit breaks this equality. */\n\treadonly approvalDigest: string;\n\treadonly policyVersion: string;\n\treadonly approvalPolicyVersion: string;\n\treadonly leaseGeneration: Sequence;\n\treadonly currentLeaseGeneration: Sequence;\n\treadonly observationValid: boolean;\n\treadonly cancelled: boolean;\n\treadonly budgetAvailable: boolean;\n}\n\n/**\n * Permit(I) = PolicyAllowed ∧ ApprovalMatches ∧ LeaseCurrent ∧ ObservationValid\n *             ∧ ¬Cancelled ∧ BudgetAvailable.\n *\n * Cancellation is reported first: when a run is cancelled, saying \"budget\n * exhausted\" would send the operator looking for the wrong problem.\n */\nexport function evaluatePermit(input: PermitInput): PermitDecision {\n\tfor (const value of [input.cancelled, input.policyAllowed, input.observationValid, input.budgetAvailable]) {\n\t\tif (typeof value !== \"boolean\") throw new TypeError(\"permit flags must be booleans\");\n\t}\n\tfor (const value of [input.intentDigest, input.approvalDigest, input.policyVersion, input.approvalPolicyVersion]) {\n\t\tif (typeof value !== \"string\" || value.length === 0 || value.length > 4096) {\n\t\t\tthrow new TypeError(\"permit binding must be a bounded non-empty string\");\n\t\t}\n\t}\n\tsequence(input.leaseGeneration);\n\tsequence(input.currentLeaseGeneration);\n\tif (input.cancelled) return { allowed: false, reason: \"cancelled\" };\n\tif (!input.policyAllowed) return { allowed: false, reason: \"policy-denied\" };\n\tif (input.approvalDigest !== input.intentDigest || input.approvalPolicyVersion !== input.policyVersion) {\n\t\treturn { allowed: false, reason: \"approval-mismatch\" };\n\t}\n\tif (input.leaseGeneration !== input.currentLeaseGeneration) return { allowed: false, reason: \"stale-lease\" };\n\tif (!input.observationValid) return { allowed: false, reason: \"observation-invalid\" };\n\tif (!input.budgetAvailable) return { allowed: false, reason: \"budget-exhausted\" };\n\treturn { allowed: true };\n}\n\nexport class OperationLifecycle {\n\treadonly operationId: string;\n\tprivate current: OperationState = \"created\";\n\tprivate readonly states: OperationState[] = [\"created\"];\n\tprivate observations: readonly ObservationBinding[] = [];\n\tprivate selected: ObservationBinding | undefined;\n\tprivate authorizedPermit: Readonly<PermitInput> | undefined;\n\tprivate hasDispatched = false;\n\tprivate cancelRequested = false;\n\n\tconstructor(operationId: string) {\n\t\tif (typeof operationId !== \"string\" || operationId.length === 0) {\n\t\t\tthrow new TypeError(\"operationId must be a non-empty string\");\n\t\t}\n\t\tthis.operationId = operationId;\n\t}\n\n\tget state(): OperationState {\n\t\treturn this.current;\n\t}\n\n\tget history(): readonly OperationState[] {\n\t\treturn [...this.states];\n\t}\n\n\t/** True once a command left this process; it says nothing about the effect. */\n\tget dispatched(): boolean {\n\t\treturn this.hasDispatched;\n\t}\n\n\tget cancellationRequested(): boolean {\n\t\treturn this.cancelRequested;\n\t}\n\n\tprivate enter(next: OperationState): void {\n\t\tthis.current = next;\n\t\tthis.states.push(next);\n\t}\n\n\tprivate assertOpen(): void {\n\t\tif (TERMINAL_STATES.has(this.current)) {\n\t\t\tthrow new Error(`operation ${this.operationId} is terminal in state ${this.current}`);\n\t\t}\n\t}\n\n\t/** Record the host-held candidate set. Without this, nothing can dispatch. */\n\tobserve(candidates: readonly ObservationBinding[]): void {\n\t\tthis.assertOpen();\n\t\tif (candidates.length === 0) throw new TypeError(\"observation must yield at least one candidate\");\n\t\tif (this.current !== \"created\" && this.current !== \"observed\") {\n\t\t\tthrow new Error(\"observe requires a created or observed operation\");\n\t\t}\n\t\tconst snapshots = candidates.map((candidate) => {\n\t\t\tfor (const value of [candidate.observationId, candidate.actionId, candidate.targetId]) {\n\t\t\t\tif (typeof value !== \"string\" || value.length === 0 || value.length > 4096) {\n\t\t\t\t\tthrow new TypeError(\"observation binding must be a bounded non-empty string\");\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Object.freeze({\n\t\t\t\tobservationId: candidate.observationId,\n\t\t\t\tactionId: candidate.actionId,\n\t\t\t\ttargetId: candidate.targetId,\n\t\t\t\tdocumentGeneration: sequence(candidate.documentGeneration),\n\t\t\t});\n\t\t});\n\t\tthis.observations = Object.freeze(snapshots);\n\t\tthis.enter(\"observed\");\n\t}\n\n\t/** Select one observed candidate. Free-text re-interpretation has no path here. */\n\tpropose(candidate: ObservationBinding): void {\n\t\tthis.assertOpen();\n\t\tif (this.observations.length === 0) {\n\t\t\tthrow new Error(\"cannot propose before observe: the candidate set is unbound\");\n\t\t}\n\t\tif (this.current !== \"observed\" && this.current !== \"proposed\") {\n\t\t\tthrow new Error(\"propose requires an observed or proposed operation\");\n\t\t}\n\t\tconst match = this.observations.find(\n\t\t\t(o) =>\n\t\t\t\to.observationId === candidate.observationId &&\n\t\t\t\to.actionId === candidate.actionId &&\n\t\t\t\to.targetId === candidate.targetId &&\n\t\t\t\to.documentGeneration === candidate.documentGeneration,\n\t\t);\n\t\tif (match === undefined) throw new Error(\"proposed action is not among the recorded observations\");\n\t\tthis.selected = match;\n\t\tthis.enter(\"proposed\");\n\t}\n\n\tauthorize(permit: PermitInput): PermitDecision {\n\t\tthis.assertOpen();\n\t\tif (this.current !== \"proposed\") throw new Error(\"authorize requires a proposed operation\");\n\t\tconst decision = evaluatePermit(permit);\n\t\tif (!decision.allowed) {\n\t\t\tthis.applyPreDispatchDenial(decision.reason);\n\t\t\treturn decision;\n\t\t}\n\t\tthis.authorizedPermit = Object.freeze({ ...permit });\n\t\tthis.enter(\"authorized\");\n\t\treturn decision;\n\t}\n\n\t/**\n\t * Re-evaluate the permit and hand the command to the driver.\n\t *\n\t * The second evaluation is the point of the audit finding: approval and\n\t * dispatch are separated by awaits (queueing, the operator prompt, browser\n\t * startup), and state observed before those awaits is not state now.\n\t */\n\tdispatch(permit: PermitInput): PermitDecision {\n\t\tthis.assertOpen();\n\t\tif (this.current !== \"authorized\") throw new Error(\"dispatch requires an authorized operation\");\n\t\tif (this.selected === undefined) throw new Error(\"dispatch requires a bound observation\");\n\t\tconst decision = evaluatePermit(permit);\n\t\tif (!decision.allowed) {\n\t\t\tthis.applyPreDispatchDenial(decision.reason);\n\t\t\treturn decision;\n\t\t}\n\t\tconst approved = this.authorizedPermit;\n\t\tif (\n\t\t\tapproved === undefined ||\n\t\t\tapproved.intentDigest !== permit.intentDigest ||\n\t\t\tapproved.approvalDigest !== permit.approvalDigest ||\n\t\t\tapproved.policyVersion !== permit.policyVersion ||\n\t\t\tapproved.approvalPolicyVersion !== permit.approvalPolicyVersion\n\t\t) {\n\t\t\treturn { allowed: false, reason: \"approval-mismatch\" };\n\t\t}\n\t\tif (approved.leaseGeneration !== permit.leaseGeneration) {\n\t\t\treturn { allowed: false, reason: \"stale-lease\" };\n\t\t}\n\t\tthis.hasDispatched = true;\n\t\tthis.enter(\"dispatched\");\n\t\treturn decision;\n\t}\n\n\tprivate applyPreDispatchDenial(reason: PermitDenial): void {\n\t\tif (reason === \"cancelled\") {\n\t\t\tthis.cancelRequested = true;\n\t\t\tthis.enter(\"cancelled-before-dispatch\");\n\t\t}\n\t}\n\n\t/** Driver-reported outcome. Only valid once the command actually left. */\n\tsettle(outcome: SettledOutcome): void {\n\t\tif (!this.hasDispatched) throw new Error(\"settle requires a dispatched operation\");\n\t\tif (outcome !== \"applied\" && outcome !== \"failed-confirmed\" && outcome !== \"outcome-unknown\") {\n\t\t\tthrow new TypeError(\"invalid settled outcome\");\n\t\t}\n\t\t// Exact duplicate reports are idempotent. A final result cannot be revised.\n\t\tif (this.current === outcome) return;\n\t\tif (this.current !== \"dispatched\" && this.current !== \"outcome-unknown\") {\n\t\t\tthrow new Error(\"settle requires an unresolved dispatched outcome\");\n\t\t}\n\t\tthis.enter(outcome);\n\t}\n\n\t/** Explicit postcondition check. A driver's return value is not this. */\n\tverify(postconditionMet: boolean): void {\n\t\tif (typeof postconditionMet !== \"boolean\") throw new TypeError(\"postcondition must be a boolean\");\n\t\tif (this.current !== \"applied\") throw new Error(\"verify requires an applied outcome\");\n\t\tthis.enter(postconditionMet ? \"verified\" : \"inspection-required\");\n\t}\n\n\t/**\n\t * Request cancellation.\n\t *\n\t * Before dispatch this is terminal. After dispatch it only records the\n\t * request: the command is already outside this process, so the real outcome\n\t * has to be settled separately and stays `outcome-unknown` until it is.\n\t */\n\tcancel(): void {\n\t\tthis.cancelRequested = true;\n\t\tif (TERMINAL_STATES.has(this.current)) return;\n\t\tif (!this.hasDispatched) {\n\t\t\tthis.enter(\"cancelled-before-dispatch\");\n\t\t\treturn;\n\t\t}\n\t\tif (this.current === \"dispatched\") this.enter(\"outcome-unknown\");\n\t}\n}\n"]}

package/dist/coordination/resource.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resource claim identity and conflict algebra.
+ *
+ * Two claims conflict when they name overlapping resources and at least one
+ * side writes. Overlap is prefix containment on path components, so `src`
+ * covers `src/a/x` but never `src/ab` — a shared character prefix that straddles
+ * a component boundary is a different resource, not a nested one.
+ */
+import type { ResourceClaim } from "./types.ts";
+export interface ResourceClaimInput {
+    readonly namespace: string;
+    readonly instanceId: string;
+    readonly canonicalKey: string;
+    readonly access: string;
+    readonly generation: string;
+}
+/**
+ * Validate and freeze one claim.
+ *
+ * A non-canonical key is rejected rather than normalized: normalizing
+ * `a/../b` here would let one session hold `a/../b` and another hold `b`
+ * while both believe their scopes are disjoint.
+ */
+export declare function canonicalClaim(input: ResourceClaimInput): ResourceClaim;
+/** Same resource identity, or one key nested under the other. Ignores access. */
+export declare function resourcesOverlap(a: ResourceClaim, b: ResourceClaim): boolean;
+export declare function claimsConflict(a: ResourceClaim, b: ResourceClaim): boolean;
+export declare function claimSetsConflict(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean;
+/** Stable key for exact-set comparison when binding a start to its reservation. */
+export declare function claimKey(claim: ResourceClaim): string;
+/** Exact set equality by identity+access+generation; a post-hook that widened scope fails this. */
+export declare function sameClaimSet(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean;
+//# sourceMappingURL=resource.d.ts.map

package/dist/coordination/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/coordination/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAA+B,aAAa,EAAE,MAAM,YAAY,CAAC;AAc7E,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAuBvE;AAiBD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAI5E;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAE1E;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,aAAa,EAAE,EAAE,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAEnG;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAErD;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,aAAa,EAAE,EAAE,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAS9F","sourcesContent":["/**\n * Resource claim identity and conflict algebra.\n *\n * Two claims conflict when they name overlapping resources and at least one\n * side writes. Overlap is prefix containment on path components, so `src`\n * covers `src/a/x` but never `src/ab` — a shared character prefix that straddles\n * a component boundary is a different resource, not a nested one.\n */\n\nimport type { ClaimAccess, ClaimNamespace, ResourceClaim } from \"./types.ts\";\nimport { sequence } from \"./types.ts\";\n\nconst CLAIM_NAMESPACES: ReadonlySet<string> = new Set<ClaimNamespace>([\n\t\"filesystem\",\n\t\"git-ref\",\n\t\"contract\",\n\t\"socket\",\n\t\"database\",\n\t\"host-budget\",\n]);\nconst CLAIM_ACCESS: ReadonlySet<string> = new Set<ClaimAccess>([\"read\", \"write\"]);\nconst MAX_KEY_LENGTH = 4096;\n\nexport interface ResourceClaimInput {\n\treadonly namespace: string;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: string;\n\treadonly generation: string;\n}\n\n/**\n * Validate and freeze one claim.\n *\n * A non-canonical key is rejected rather than normalized: normalizing\n * `a/../b` here would let one session hold `a/../b` and another hold `b`\n * while both believe their scopes are disjoint.\n */\nexport function canonicalClaim(input: ResourceClaimInput): ResourceClaim {\n\tif (!CLAIM_NAMESPACES.has(input.namespace)) {\n\t\tthrow new TypeError(`unsupported claim namespace: ${String(input.namespace)}`);\n\t}\n\tif (!CLAIM_ACCESS.has(input.access)) {\n\t\tthrow new TypeError(`unsupported claim access: ${String(input.access)}`);\n\t}\n\tif (\n\t\ttypeof input.instanceId !== \"string\" ||\n\t\tinput.instanceId.length === 0 ||\n\t\tinput.instanceId.length > MAX_KEY_LENGTH ||\n\t\tinput.instanceId.includes(\"\\u0000\")\n\t) {\n\t\tthrow new TypeError(\"claim instanceId must be a bounded non-empty string without NUL\");\n\t}\n\tassertCanonicalKey(input.canonicalKey);\n\treturn Object.freeze({\n\t\tnamespace: input.namespace as ClaimNamespace,\n\t\tinstanceId: input.instanceId,\n\t\tcanonicalKey: input.canonicalKey,\n\t\taccess: input.access as ClaimAccess,\n\t\tgeneration: sequence(input.generation),\n\t});\n}\n\nfunction assertCanonicalKey(key: unknown): asserts key is string {\n\tif (typeof key !== \"string\" || key.length === 0 || key.length > MAX_KEY_LENGTH) {\n\t\tthrow new TypeError(\"claim canonicalKey must be a bounded non-empty string\");\n\t}\n\tif (key.startsWith(\"/\")) throw new TypeError(\"claim canonicalKey must be relative\");\n\tif (key.includes(\"\\u0000\") || key.includes(\"\\\\\")) {\n\t\tthrow new TypeError(\"claim canonicalKey must use slash components without NUL\");\n\t}\n\tfor (const part of key.split(\"/\")) {\n\t\tif (part === \"\" || part === \".\" || part === \"..\") {\n\t\t\tthrow new TypeError(`claim canonicalKey is not canonical: ${key}`);\n\t\t}\n\t}\n}\n\n/** Same resource identity, or one key nested under the other. Ignores access. */\nexport function resourcesOverlap(a: ResourceClaim, b: ResourceClaim): boolean {\n\tif (a.namespace !== b.namespace || a.instanceId !== b.instanceId) return false;\n\tif (a.canonicalKey === b.canonicalKey) return true;\n\treturn a.canonicalKey.startsWith(`${b.canonicalKey}/`) || b.canonicalKey.startsWith(`${a.canonicalKey}/`);\n}\n\nexport function claimsConflict(a: ResourceClaim, b: ResourceClaim): boolean {\n\treturn resourcesOverlap(a, b) && (a.access === \"write\" || b.access === \"write\");\n}\n\nexport function claimSetsConflict(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\treturn a.some((x) => b.some((y) => claimsConflict(x, y)));\n}\n\n/** Stable key for exact-set comparison when binding a start to its reservation. */\nexport function claimKey(claim: ResourceClaim): string {\n\treturn JSON.stringify([claim.namespace, claim.instanceId, claim.canonicalKey, claim.access, claim.generation]);\n}\n\n/** Exact set equality by identity+access+generation; a post-hook that widened scope fails this. */\nexport function sameClaimSet(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\tif (a.length !== b.length) return false;\n\tconst byCodeUnit = (x: string, y: string): number => {\n\t\tif (x < y) return -1;\n\t\treturn x > y ? 1 : 0;\n\t};\n\tconst left = a.map(claimKey).sort(byCodeUnit);\n\tconst right = b.map(claimKey).sort(byCodeUnit);\n\treturn left.every((value, index) => value === right[index]);\n}\n"]}

package/dist/coordination/resource.js

@@ -0,0 +1,95 @@
+/**
+ * Resource claim identity and conflict algebra.
+ *
+ * Two claims conflict when they name overlapping resources and at least one
+ * side writes. Overlap is prefix containment on path components, so `src`
+ * covers `src/a/x` but never `src/ab` — a shared character prefix that straddles
+ * a component boundary is a different resource, not a nested one.
+ */
+import { sequence } from "./types.js";
+const CLAIM_NAMESPACES = new Set([
+    "filesystem",
+    "git-ref",
+    "contract",
+    "socket",
+    "database",
+    "host-budget",
+]);
+const CLAIM_ACCESS = new Set(["read", "write"]);
+const MAX_KEY_LENGTH = 4096;
+/**
+ * Validate and freeze one claim.
+ *
+ * A non-canonical key is rejected rather than normalized: normalizing
+ * `a/../b` here would let one session hold `a/../b` and another hold `b`
+ * while both believe their scopes are disjoint.
+ */
+export function canonicalClaim(input) {
+    if (!CLAIM_NAMESPACES.has(input.namespace)) {
+        throw new TypeError(`unsupported claim namespace: ${String(input.namespace)}`);
+    }
+    if (!CLAIM_ACCESS.has(input.access)) {
+        throw new TypeError(`unsupported claim access: ${String(input.access)}`);
+    }
+    if (typeof input.instanceId !== "string" ||
+        input.instanceId.length === 0 ||
+        input.instanceId.length > MAX_KEY_LENGTH ||
+        input.instanceId.includes("\u0000")) {
+        throw new TypeError("claim instanceId must be a bounded non-empty string without NUL");
+    }
+    assertCanonicalKey(input.canonicalKey);
+    return Object.freeze({
+        namespace: input.namespace,
+        instanceId: input.instanceId,
+        canonicalKey: input.canonicalKey,
+        access: input.access,
+        generation: sequence(input.generation),
+    });
+}
+function assertCanonicalKey(key) {
+    if (typeof key !== "string" || key.length === 0 || key.length > MAX_KEY_LENGTH) {
+        throw new TypeError("claim canonicalKey must be a bounded non-empty string");
+    }
+    if (key.startsWith("/"))
+        throw new TypeError("claim canonicalKey must be relative");
+    if (key.includes("\u0000") || key.includes("\\")) {
+        throw new TypeError("claim canonicalKey must use slash components without NUL");
+    }
+    for (const part of key.split("/")) {
+        if (part === "" || part === "." || part === "..") {
+            throw new TypeError(`claim canonicalKey is not canonical: ${key}`);
+        }
+    }
+}
+/** Same resource identity, or one key nested under the other. Ignores access. */
+export function resourcesOverlap(a, b) {
+    if (a.namespace !== b.namespace || a.instanceId !== b.instanceId)
+        return false;
+    if (a.canonicalKey === b.canonicalKey)
+        return true;
+    return a.canonicalKey.startsWith(`${b.canonicalKey}/`) || b.canonicalKey.startsWith(`${a.canonicalKey}/`);
+}
+export function claimsConflict(a, b) {
+    return resourcesOverlap(a, b) && (a.access === "write" || b.access === "write");
+}
+export function claimSetsConflict(a, b) {
+    return a.some((x) => b.some((y) => claimsConflict(x, y)));
+}
+/** Stable key for exact-set comparison when binding a start to its reservation. */
+export function claimKey(claim) {
+    return JSON.stringify([claim.namespace, claim.instanceId, claim.canonicalKey, claim.access, claim.generation]);
+}
+/** Exact set equality by identity+access+generation; a post-hook that widened scope fails this. */
+export function sameClaimSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const byCodeUnit = (x, y) => {
+        if (x < y)
+            return -1;
+        return x > y ? 1 : 0;
+    };
+    const left = a.map(claimKey).sort(byCodeUnit);
+    const right = b.map(claimKey).sort(byCodeUnit);
+    return left.every((value, index) => value === right[index]);
+}
+//# sourceMappingURL=resource.js.map

package/dist/coordination/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/coordination/resource.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource claim identity and conflict algebra.\n *\n * Two claims conflict when they name overlapping resources and at least one\n * side writes. Overlap is prefix containment on path components, so `src`\n * covers `src/a/x` but never `src/ab` — a shared character prefix that straddles\n * a component boundary is a different resource, not a nested one.\n */\n\nimport type { ClaimAccess, ClaimNamespace, ResourceClaim } from \"./types.ts\";\nimport { sequence } from \"./types.ts\";\n\nconst CLAIM_NAMESPACES: ReadonlySet<string> = new Set<ClaimNamespace>([\n\t\"filesystem\",\n\t\"git-ref\",\n\t\"contract\",\n\t\"socket\",\n\t\"database\",\n\t\"host-budget\",\n]);\nconst CLAIM_ACCESS: ReadonlySet<string> = new Set<ClaimAccess>([\"read\", \"write\"]);\nconst MAX_KEY_LENGTH = 4096;\n\nexport interface ResourceClaimInput {\n\treadonly namespace: string;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: string;\n\treadonly generation: string;\n}\n\n/**\n * Validate and freeze one claim.\n *\n * A non-canonical key is rejected rather than normalized: normalizing\n * `a/../b` here would let one session hold `a/../b` and another hold `b`\n * while both believe their scopes are disjoint.\n */\nexport function canonicalClaim(input: ResourceClaimInput): ResourceClaim {\n\tif (!CLAIM_NAMESPACES.has(input.namespace)) {\n\t\tthrow new TypeError(`unsupported claim namespace: ${String(input.namespace)}`);\n\t}\n\tif (!CLAIM_ACCESS.has(input.access)) {\n\t\tthrow new TypeError(`unsupported claim access: ${String(input.access)}`);\n\t}\n\tif (\n\t\ttypeof input.instanceId !== \"string\" ||\n\t\tinput.instanceId.length === 0 ||\n\t\tinput.instanceId.length > MAX_KEY_LENGTH ||\n\t\tinput.instanceId.includes(\"\\u0000\")\n\t) {\n\t\tthrow new TypeError(\"claim instanceId must be a bounded non-empty string without NUL\");\n\t}\n\tassertCanonicalKey(input.canonicalKey);\n\treturn Object.freeze({\n\t\tnamespace: input.namespace as ClaimNamespace,\n\t\tinstanceId: input.instanceId,\n\t\tcanonicalKey: input.canonicalKey,\n\t\taccess: input.access as ClaimAccess,\n\t\tgeneration: sequence(input.generation),\n\t});\n}\n\nfunction assertCanonicalKey(key: unknown): asserts key is string {\n\tif (typeof key !== \"string\" || key.length === 0 || key.length > MAX_KEY_LENGTH) {\n\t\tthrow new TypeError(\"claim canonicalKey must be a bounded non-empty string\");\n\t}\n\tif (key.startsWith(\"/\")) throw new TypeError(\"claim canonicalKey must be relative\");\n\tif (key.includes(\"\\u0000\") || key.includes(\"\\\\\")) {\n\t\tthrow new TypeError(\"claim canonicalKey must use slash components without NUL\");\n\t}\n\tfor (const part of key.split(\"/\")) {\n\t\tif (part === \"\" || part === \".\" || part === \"..\") {\n\t\t\tthrow new TypeError(`claim canonicalKey is not canonical: ${key}`);\n\t\t}\n\t}\n}\n\n/** Same resource identity, or one key nested under the other. Ignores access. */\nexport function resourcesOverlap(a: ResourceClaim, b: ResourceClaim): boolean {\n\tif (a.namespace !== b.namespace || a.instanceId !== b.instanceId) return false;\n\tif (a.canonicalKey === b.canonicalKey) return true;\n\treturn a.canonicalKey.startsWith(`${b.canonicalKey}/`) || b.canonicalKey.startsWith(`${a.canonicalKey}/`);\n}\n\nexport function claimsConflict(a: ResourceClaim, b: ResourceClaim): boolean {\n\treturn resourcesOverlap(a, b) && (a.access === \"write\" || b.access === \"write\");\n}\n\nexport function claimSetsConflict(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\treturn a.some((x) => b.some((y) => claimsConflict(x, y)));\n}\n\n/** Stable key for exact-set comparison when binding a start to its reservation. */\nexport function claimKey(claim: ResourceClaim): string {\n\treturn JSON.stringify([claim.namespace, claim.instanceId, claim.canonicalKey, claim.access, claim.generation]);\n}\n\n/** Exact set equality by identity+access+generation; a post-hook that widened scope fails this. */\nexport function sameClaimSet(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\tif (a.length !== b.length) return false;\n\tconst byCodeUnit = (x: string, y: string): number => {\n\t\tif (x < y) return -1;\n\t\treturn x > y ? 1 : 0;\n\t};\n\tconst left = a.map(claimKey).sort(byCodeUnit);\n\tconst right = b.map(claimKey).sort(byCodeUnit);\n\treturn left.every((value, index) => value === right[index]);\n}\n"]}

package/dist/coordination/session.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).
+ *
+ *   idle → initializing(g) → ready(g) → draining(g) → closed(g)
+ *                        ↘ init failure → idle
+ *        ready | draining → close failure → close-failed(g)
+ *
+ * Two reproduced defects motivate every rule here:
+ *   R09 — shutdown read an empty session slot while init was in flight, then
+ *         the init completed and assigned it, resurrecting a closed session.
+ *   R10 — close cleared the handle before the driver call resolved, so a close
+ *         that threw left no handle and the next call claimed success.
+ *
+ * The invariant is that a handle is never dropped on the floor: a late init
+ * from a superseded generation is moved to `discardedHandles` for the caller
+ * to clean up, and a failed close keeps its handle in `close-failed`.
+ */
+import type { Sequence } from "./types.ts";
+export type SessionState = "idle" | "initializing" | "ready" | "draining" | "closed" | "close-failed";
+export declare class SessionLifecycle<THandle = unknown> {
+    private currentState;
+    private generation;
+    private currentHandle;
+    private failure;
+    private shutdownRequested;
+    private readonly discarded;
+    get state(): SessionState;
+    get currentGeneration(): Sequence;
+    get handle(): THandle | undefined;
+    /** Handles from superseded or unknown generations; the caller must close them. */
+    get discardedHandles(): readonly THandle[];
+    get closeFailure(): Error | undefined;
+    /** Only a completed close counts. A close failure is not closed. */
+    get isClosed(): boolean;
+    /**
+     * Open a new generation.
+     *
+     * Refused while a close failure is unresolved: launching a second browser
+     * on top of one that may still be running is how orphan processes and
+     * duplicate effects start.
+     */
+    beginInit(): Sequence;
+    /**
+     * Adopt an initialized handle.
+     *
+     * Returns false when this generation is no longer the one being awaited —
+     * the handle is retained for cleanup rather than installed, because the
+     * session it belonged to is already gone.
+     */
+    completeInit(generation: Sequence, handle: THandle): boolean;
+    failInit(generation: Sequence, error: Error): boolean;
+    /**
+     * Ask the session to stop.
+     *
+     * With no handle yet there is nothing to drain, so this closes immediately
+     * and any in-flight init will be discarded on arrival. With a live handle
+     * the session must drain: the caller still has to close the driver.
+     */
+    requestShutdown(): void;
+    beginClose(): void;
+    /** The driver confirmed the session is gone; only now is the handle released. */
+    completeClose(): void;
+    /** The close attempt threw. Keep the handle so a retry can still reach it. */
+    failClose(error: Error): void;
+    /**
+     * Fencing gate: accept a command only from the current generation of a
+     * ready session. A generation number in a log proves nothing; the gate that
+     * hands commands to the driver has to be the one refusing stale ones.
+     */
+    accepts(generation: Sequence): boolean;
+    /** True once a shutdown was asked for, regardless of how far draining got. */
+    get shutdownPending(): boolean;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/coordination/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/coordination/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEtG,qBAAa,gBAAgB,CAAC,OAAO,GAAG,OAAO;IAC9C,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAE3C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,iBAAiB,IAAI,QAAQ,CAEhC;IAED,IAAI,MAAM,IAAI,OAAO,GAAG,SAAS,CAEhC;IAED,kFAAkF;IAClF,IAAI,gBAAgB,IAAI,SAAS,OAAO,EAAE,CAEzC;IAED,IAAI,YAAY,IAAI,KAAK,GAAG,SAAS,CAEpC;IAED,oEAAoE;IACpE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;OAMG;IACH,SAAS,IAAI,QAAQ,CAWpB;IAED;;;;;;OAMG;IACH,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAQ3D;IAED,QAAQ,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAOpD;IAED;;;;;;OAMG;IACH,eAAe,IAAI,IAAI,CAOtB;IAED,UAAU,IAAI,IAAI,CAMjB;IAED,iFAAiF;IACjF,aAAa,IAAI,IAAI,CAOpB;IAED,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAM5B;IAED;;;;OAIG;IACH,OAAO,CAAC,UAAU,EAAE,QAAQ,GAAG,OAAO,CAErC;IAED,8EAA8E;IAC9E,IAAI,eAAe,IAAI,OAAO,CAE7B;CACD","sourcesContent":["/**\n * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).\n *\n *   idle → initializing(g) → ready(g) → draining(g) → closed(g)\n *                        ↘ init failure → idle\n *        ready | draining → close failure → close-failed(g)\n *\n * Two reproduced defects motivate every rule here:\n *   R09 — shutdown read an empty session slot while init was in flight, then\n *         the init completed and assigned it, resurrecting a closed session.\n *   R10 — close cleared the handle before the driver call resolved, so a close\n *         that threw left no handle and the next call claimed success.\n *\n * The invariant is that a handle is never dropped on the floor: a late init\n * from a superseded generation is moved to `discardedHandles` for the caller\n * to clean up, and a failed close keeps its handle in `close-failed`.\n */\n\nimport type { Sequence } from \"./types.ts\";\nimport { nextSequence, sequence } from \"./types.ts\";\n\nexport type SessionState = \"idle\" | \"initializing\" | \"ready\" | \"draining\" | \"closed\" | \"close-failed\";\n\nexport class SessionLifecycle<THandle = unknown> {\n\tprivate currentState: SessionState = \"idle\";\n\tprivate generation: Sequence = sequence(\"0\");\n\tprivate currentHandle: THandle | undefined;\n\tprivate failure: Error | undefined;\n\tprivate shutdownRequested = false;\n\tprivate readonly discarded: THandle[] = [];\n\n\tget state(): SessionState {\n\t\treturn this.currentState;\n\t}\n\n\tget currentGeneration(): Sequence {\n\t\treturn this.generation;\n\t}\n\n\tget handle(): THandle | undefined {\n\t\treturn this.currentHandle;\n\t}\n\n\t/** Handles from superseded or unknown generations; the caller must close them. */\n\tget discardedHandles(): readonly THandle[] {\n\t\treturn [...this.discarded];\n\t}\n\n\tget closeFailure(): Error | undefined {\n\t\treturn this.failure;\n\t}\n\n\t/** Only a completed close counts. A close failure is not closed. */\n\tget isClosed(): boolean {\n\t\treturn this.currentState === \"closed\";\n\t}\n\n\t/**\n\t * Open a new generation.\n\t *\n\t * Refused while a close failure is unresolved: launching a second browser\n\t * on top of one that may still be running is how orphan processes and\n\t * duplicate effects start.\n\t */\n\tbeginInit(): Sequence {\n\t\tif (this.currentState === \"close-failed\") {\n\t\t\tthrow new Error(\"cannot initialize while a close-failed session is unresolved\");\n\t\t}\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"ready\" || this.currentState === \"draining\") {\n\t\t\tthrow new Error(`cannot initialize from state ${this.currentState}`);\n\t\t}\n\t\tthis.generation = nextSequence(this.generation);\n\t\tthis.shutdownRequested = false;\n\t\tthis.currentState = \"initializing\";\n\t\treturn this.generation;\n\t}\n\n\t/**\n\t * Adopt an initialized handle.\n\t *\n\t * Returns false when this generation is no longer the one being awaited —\n\t * the handle is retained for cleanup rather than installed, because the\n\t * session it belonged to is already gone.\n\t */\n\tcompleteInit(generation: Sequence, handle: THandle): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") {\n\t\t\tthis.discarded.push(handle);\n\t\t\treturn false;\n\t\t}\n\t\tthis.currentHandle = handle;\n\t\tthis.currentState = \"ready\";\n\t\treturn true;\n\t}\n\n\tfailInit(generation: Sequence, error: Error): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") return false;\n\t\tthis.failure = undefined;\n\t\tthis.currentHandle = undefined;\n\t\tthis.currentState = \"idle\";\n\t\tvoid error;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Ask the session to stop.\n\t *\n\t * With no handle yet there is nothing to drain, so this closes immediately\n\t * and any in-flight init will be discarded on arrival. With a live handle\n\t * the session must drain: the caller still has to close the driver.\n\t */\n\trequestShutdown(): void {\n\t\tthis.shutdownRequested = true;\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"idle\") {\n\t\t\tthis.currentState = \"closed\";\n\t\t\treturn;\n\t\t}\n\t\tif (this.currentState === \"ready\") this.currentState = \"draining\";\n\t}\n\n\tbeginClose(): void {\n\t\tif (this.currentState !== \"ready\" && this.currentState !== \"close-failed\") {\n\t\t\tthrow new Error(`cannot close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"draining\";\n\t}\n\n\t/** The driver confirmed the session is gone; only now is the handle released. */\n\tcompleteClose(): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot complete close from state ${this.currentState}`);\n\t\t}\n\t\tthis.currentHandle = undefined;\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"closed\";\n\t}\n\n\t/** The close attempt threw. Keep the handle so a retry can still reach it. */\n\tfailClose(error: Error): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot fail close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = error;\n\t\tthis.currentState = \"close-failed\";\n\t}\n\n\t/**\n\t * Fencing gate: accept a command only from the current generation of a\n\t * ready session. A generation number in a log proves nothing; the gate that\n\t * hands commands to the driver has to be the one refusing stale ones.\n\t */\n\taccepts(generation: Sequence): boolean {\n\t\treturn this.currentState === \"ready\" && generation === this.generation;\n\t}\n\n\t/** True once a shutdown was asked for, regardless of how far draining got. */\n\tget shutdownPending(): boolean {\n\t\treturn this.shutdownRequested;\n\t}\n}\n"]}

package/dist/coordination/session.js

@@ -0,0 +1,143 @@
+/**
+ * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).
+ *
+ *   idle → initializing(g) → ready(g) → draining(g) → closed(g)
+ *                        ↘ init failure → idle
+ *        ready | draining → close failure → close-failed(g)
+ *
+ * Two reproduced defects motivate every rule here:
+ *   R09 — shutdown read an empty session slot while init was in flight, then
+ *         the init completed and assigned it, resurrecting a closed session.
+ *   R10 — close cleared the handle before the driver call resolved, so a close
+ *         that threw left no handle and the next call claimed success.
+ *
+ * The invariant is that a handle is never dropped on the floor: a late init
+ * from a superseded generation is moved to `discardedHandles` for the caller
+ * to clean up, and a failed close keeps its handle in `close-failed`.
+ */
+import { nextSequence, sequence } from "./types.js";
+export class SessionLifecycle {
+    currentState = "idle";
+    generation = sequence("0");
+    currentHandle;
+    failure;
+    shutdownRequested = false;
+    discarded = [];
+    get state() {
+        return this.currentState;
+    }
+    get currentGeneration() {
+        return this.generation;
+    }
+    get handle() {
+        return this.currentHandle;
+    }
+    /** Handles from superseded or unknown generations; the caller must close them. */
+    get discardedHandles() {
+        return [...this.discarded];
+    }
+    get closeFailure() {
+        return this.failure;
+    }
+    /** Only a completed close counts. A close failure is not closed. */
+    get isClosed() {
+        return this.currentState === "closed";
+    }
+    /**
+     * Open a new generation.
+     *
+     * Refused while a close failure is unresolved: launching a second browser
+     * on top of one that may still be running is how orphan processes and
+     * duplicate effects start.
+     */
+    beginInit() {
+        if (this.currentState === "close-failed") {
+            throw new Error("cannot initialize while a close-failed session is unresolved");
+        }
+        if (this.currentState === "initializing" || this.currentState === "ready" || this.currentState === "draining") {
+            throw new Error(`cannot initialize from state ${this.currentState}`);
+        }
+        this.generation = nextSequence(this.generation);
+        this.shutdownRequested = false;
+        this.currentState = "initializing";
+        return this.generation;
+    }
+    /**
+     * Adopt an initialized handle.
+     *
+     * Returns false when this generation is no longer the one being awaited —
+     * the handle is retained for cleanup rather than installed, because the
+     * session it belonged to is already gone.
+     */
+    completeInit(generation, handle) {
+        if (generation !== this.generation || this.currentState !== "initializing") {
+            this.discarded.push(handle);
+            return false;
+        }
+        this.currentHandle = handle;
+        this.currentState = "ready";
+        return true;
+    }
+    failInit(generation, error) {
+        if (generation !== this.generation || this.currentState !== "initializing")
+            return false;
+        this.failure = undefined;
+        this.currentHandle = undefined;
+        this.currentState = "idle";
+        void error;
+        return true;
+    }
+    /**
+     * Ask the session to stop.
+     *
+     * With no handle yet there is nothing to drain, so this closes immediately
+     * and any in-flight init will be discarded on arrival. With a live handle
+     * the session must drain: the caller still has to close the driver.
+     */
+    requestShutdown() {
+        this.shutdownRequested = true;
+        if (this.currentState === "initializing" || this.currentState === "idle") {
+            this.currentState = "closed";
+            return;
+        }
+        if (this.currentState === "ready")
+            this.currentState = "draining";
+    }
+    beginClose() {
+        if (this.currentState !== "ready" && this.currentState !== "close-failed") {
+            throw new Error(`cannot close from state ${this.currentState}`);
+        }
+        this.failure = undefined;
+        this.currentState = "draining";
+    }
+    /** The driver confirmed the session is gone; only now is the handle released. */
+    completeClose() {
+        if (this.currentState !== "draining") {
+            throw new Error(`cannot complete close from state ${this.currentState}`);
+        }
+        this.currentHandle = undefined;
+        this.failure = undefined;
+        this.currentState = "closed";
+    }
+    /** The close attempt threw. Keep the handle so a retry can still reach it. */
+    failClose(error) {
+        if (this.currentState !== "draining") {
+            throw new Error(`cannot fail close from state ${this.currentState}`);
+        }
+        this.failure = error;
+        this.currentState = "close-failed";
+    }
+    /**
+     * Fencing gate: accept a command only from the current generation of a
+     * ready session. A generation number in a log proves nothing; the gate that
+     * hands commands to the driver has to be the one refusing stale ones.
+     */
+    accepts(generation) {
+        return this.currentState === "ready" && generation === this.generation;
+    }
+    /** True once a shutdown was asked for, regardless of how far draining got. */
+    get shutdownPending() {
+        return this.shutdownRequested;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/coordination/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/coordination/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIpD,MAAM,OAAO,gBAAgB;IACpB,YAAY,GAAiB,MAAM,CAAC;IACpC,UAAU,GAAa,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrC,aAAa,CAAsB;IACnC,OAAO,CAAoB;IAC3B,iBAAiB,GAAG,KAAK,CAAC;IACjB,SAAS,GAAc,EAAE,CAAC;IAE3C,IAAI,KAAK,GAAiB;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC;IAAA,CACzB;IAED,IAAI,iBAAiB,GAAa;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC;IAAA,CACvB;IAED,IAAI,MAAM,GAAwB;QACjC,OAAO,IAAI,CAAC,aAAa,CAAC;IAAA,CAC1B;IAED,kFAAkF;IAClF,IAAI,gBAAgB,GAAuB;QAC1C,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAAA,CAC3B;IAED,IAAI,YAAY,GAAsB;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC;IAAA,CACpB;IAED,oEAAoE;IACpE,IAAI,QAAQ,GAAY;QACvB,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,CAAC;IAAA,CACtC;IAED;;;;;;OAMG;IACH,SAAS,GAAa;QACrB,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO,IAAI,IAAI,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;YAC/G,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,cAAc,CAAC;QACnC,OAAO,IAAI,CAAC,UAAU,CAAC;IAAA,CACvB;IAED;;;;;;OAMG;IACH,YAAY,CAAC,UAAoB,EAAE,MAAe,EAAW;QAC5D,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,EAAE,CAAC;YAC5E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5B,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IAAA,CACZ;IAED,QAAQ,CAAC,UAAoB,EAAE,KAAY,EAAW;QACrD,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc;YAAE,OAAO,KAAK,CAAC;QACzF,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;QAC3B,KAAK,KAAK,CAAC;QACX,OAAO,IAAI,CAAC;IAAA,CACZ;IAED;;;;;;OAMG;IACH,eAAe,GAAS;QACvB,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC9B,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,IAAI,IAAI,CAAC,YAAY,KAAK,MAAM,EAAE,CAAC;YAC1E,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;YAC7B,OAAO;QACR,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO;YAAE,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC;IAAA,CAClE;IAED,UAAU,GAAS;QAClB,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC;IAAA,CAC/B;IAED,iFAAiF;IACjF,aAAa,GAAS;QACrB,IAAI,IAAI,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;IAAA,CAC7B;IAED,8EAA8E;IAC9E,SAAS,CAAC,KAAY,EAAQ;QAC7B,IAAI,IAAI,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,cAAc,CAAC;IAAA,CACnC;IAED;;;;OAIG;IACH,OAAO,CAAC,UAAoB,EAAW;QACtC,OAAO,IAAI,CAAC,YAAY,KAAK,OAAO,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,CAAC;IAAA,CACvE;IAED,8EAA8E;IAC9E,IAAI,eAAe,GAAY;QAC9B,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAAA,CAC9B;CACD","sourcesContent":["/**\n * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).\n *\n *   idle → initializing(g) → ready(g) → draining(g) → closed(g)\n *                        ↘ init failure → idle\n *        ready | draining → close failure → close-failed(g)\n *\n * Two reproduced defects motivate every rule here:\n *   R09 — shutdown read an empty session slot while init was in flight, then\n *         the init completed and assigned it, resurrecting a closed session.\n *   R10 — close cleared the handle before the driver call resolved, so a close\n *         that threw left no handle and the next call claimed success.\n *\n * The invariant is that a handle is never dropped on the floor: a late init\n * from a superseded generation is moved to `discardedHandles` for the caller\n * to clean up, and a failed close keeps its handle in `close-failed`.\n */\n\nimport type { Sequence } from \"./types.ts\";\nimport { nextSequence, sequence } from \"./types.ts\";\n\nexport type SessionState = \"idle\" | \"initializing\" | \"ready\" | \"draining\" | \"closed\" | \"close-failed\";\n\nexport class SessionLifecycle<THandle = unknown> {\n\tprivate currentState: SessionState = \"idle\";\n\tprivate generation: Sequence = sequence(\"0\");\n\tprivate currentHandle: THandle | undefined;\n\tprivate failure: Error | undefined;\n\tprivate shutdownRequested = false;\n\tprivate readonly discarded: THandle[] = [];\n\n\tget state(): SessionState {\n\t\treturn this.currentState;\n\t}\n\n\tget currentGeneration(): Sequence {\n\t\treturn this.generation;\n\t}\n\n\tget handle(): THandle | undefined {\n\t\treturn this.currentHandle;\n\t}\n\n\t/** Handles from superseded or unknown generations; the caller must close them. */\n\tget discardedHandles(): readonly THandle[] {\n\t\treturn [...this.discarded];\n\t}\n\n\tget closeFailure(): Error | undefined {\n\t\treturn this.failure;\n\t}\n\n\t/** Only a completed close counts. A close failure is not closed. */\n\tget isClosed(): boolean {\n\t\treturn this.currentState === \"closed\";\n\t}\n\n\t/**\n\t * Open a new generation.\n\t *\n\t * Refused while a close failure is unresolved: launching a second browser\n\t * on top of one that may still be running is how orphan processes and\n\t * duplicate effects start.\n\t */\n\tbeginInit(): Sequence {\n\t\tif (this.currentState === \"close-failed\") {\n\t\t\tthrow new Error(\"cannot initialize while a close-failed session is unresolved\");\n\t\t}\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"ready\" || this.currentState === \"draining\") {\n\t\t\tthrow new Error(`cannot initialize from state ${this.currentState}`);\n\t\t}\n\t\tthis.generation = nextSequence(this.generation);\n\t\tthis.shutdownRequested = false;\n\t\tthis.currentState = \"initializing\";\n\t\treturn this.generation;\n\t}\n\n\t/**\n\t * Adopt an initialized handle.\n\t *\n\t * Returns false when this generation is no longer the one being awaited —\n\t * the handle is retained for cleanup rather than installed, because the\n\t * session it belonged to is already gone.\n\t */\n\tcompleteInit(generation: Sequence, handle: THandle): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") {\n\t\t\tthis.discarded.push(handle);\n\t\t\treturn false;\n\t\t}\n\t\tthis.currentHandle = handle;\n\t\tthis.currentState = \"ready\";\n\t\treturn true;\n\t}\n\n\tfailInit(generation: Sequence, error: Error): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") return false;\n\t\tthis.failure = undefined;\n\t\tthis.currentHandle = undefined;\n\t\tthis.currentState = \"idle\";\n\t\tvoid error;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Ask the session to stop.\n\t *\n\t * With no handle yet there is nothing to drain, so this closes immediately\n\t * and any in-flight init will be discarded on arrival. With a live handle\n\t * the session must drain: the caller still has to close the driver.\n\t */\n\trequestShutdown(): void {\n\t\tthis.shutdownRequested = true;\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"idle\") {\n\t\t\tthis.currentState = \"closed\";\n\t\t\treturn;\n\t\t}\n\t\tif (this.currentState === \"ready\") this.currentState = \"draining\";\n\t}\n\n\tbeginClose(): void {\n\t\tif (this.currentState !== \"ready\" && this.currentState !== \"close-failed\") {\n\t\t\tthrow new Error(`cannot close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"draining\";\n\t}\n\n\t/** The driver confirmed the session is gone; only now is the handle released. */\n\tcompleteClose(): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot complete close from state ${this.currentState}`);\n\t\t}\n\t\tthis.currentHandle = undefined;\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"closed\";\n\t}\n\n\t/** The close attempt threw. Keep the handle so a retry can still reach it. */\n\tfailClose(error: Error): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot fail close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = error;\n\t\tthis.currentState = \"close-failed\";\n\t}\n\n\t/**\n\t * Fencing gate: accept a command only from the current generation of a\n\t * ready session. A generation number in a log proves nothing; the gate that\n\t * hands commands to the driver has to be the one refusing stale ones.\n\t */\n\taccepts(generation: Sequence): boolean {\n\t\treturn this.currentState === \"ready\" && generation === this.generation;\n\t}\n\n\t/** True once a shutdown was asked for, regardless of how far draining got. */\n\tget shutdownPending(): boolean {\n\t\treturn this.shutdownRequested;\n\t}\n}\n"]}

package/dist/coordination/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Wire contracts for parallel-session coordination.
+ *
+ * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination
+ * design. These are new contracts, not pre-existing OMK exports.
+ *
+ * The central distinction the types encode: an authorization deadline is not a
+ * termination proof. A grant whose deadline passed while an external effect was
+ * live becomes `quarantined` — still holding its claims — rather than free.
+ */
+/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */
+export type Sequence = string & {
+    readonly __sequence: unique symbol;
+};
+export declare function sequence(value: unknown): Sequence;
+export declare function nextSequence(value: Sequence): Sequence;
+/**
+ * Lifecycle of an authorized effect.
+ *
+ * The in-process broker currently mints `reserved`, `running`, `quarantined`,
+ * `terminated` and `cancelled`. `starting` and `terminating` are reserved for
+ * the out-of-process supervisor that reports those transitions over the wire;
+ * nothing emits them yet, and the broker must not infer them.
+ */
+export type EffectState = "reserved" | "starting" | "running" | "terminating" | "quarantined" | "terminated" | "cancelled";
+/** States in which a grant no longer holds its claims. */
+export declare const SETTLED_EFFECT_STATES: ReadonlySet<EffectState>;
+export type ClaimNamespace = "filesystem" | "git-ref" | "contract" | "socket" | "database" | "host-budget";
+export type ClaimAccess = "read" | "write";
+/**
+ * One declared resource claim.
+ *
+ * `canonicalKey` must already be normalized by the caller: the broker rejects
+ * rather than guesses, because silently normalizing `a/../b` would let two
+ * sessions believe they hold disjoint keys.
+ */
+export interface ResourceClaim {
+    readonly namespace: ClaimNamespace;
+    readonly instanceId: string;
+    readonly canonicalKey: string;
+    readonly access: ClaimAccess;
+    readonly generation: Sequence;
+}
+/**
+ * Proof of admission for exactly one operation of one session incarnation.
+ *
+ * `authorizationDeadline` bounds the authorization only. Termination is a
+ * separate, supervisor-reported fact.
+ */
+export interface GrantToken {
+    readonly authorityEpoch: Sequence;
+    readonly grantSequence: Sequence;
+    readonly sessionId: string;
+    readonly sessionIncarnation: Sequence;
+    readonly authorizationDeadline: number;
+}
+export type AdmissionOutcome = {
+    readonly status: "granted";
+    readonly token: GrantToken;
+} | {
+    readonly status: "blocked";
+    readonly blockers: readonly Sequence[];
+} | {
+    readonly status: "over-capacity";
+    readonly requestedWeight: number;
+    readonly availableWeight: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/coordination/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAKvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAMjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAEtD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACpB,UAAU,GACV,UAAU,GACV,SAAS,GACT,aAAa,GACb,aAAa,GACb,YAAY,GACZ,WAAW,CAAC;AAEf,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,WAAW,CAAqD,CAAC;AAEjH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;AAC3G,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC","sourcesContent":["/**\n * Wire contracts for parallel-session coordination.\n *\n * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination\n * design. These are new contracts, not pre-existing OMK exports.\n *\n * The central distinction the types encode: an authorization deadline is not a\n * termination proof. A grant whose deadline passed while an external effect was\n * live becomes `quarantined` — still holding its claims — rather than free.\n */\n\n/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */\nexport type Sequence = string & { readonly __sequence: unique symbol };\n\nconst SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;\nconst MAX_SEQUENCE_LENGTH = 40;\n\nexport function sequence(value: unknown): Sequence {\n\tif (typeof value !== \"string\" || !SEQUENCE_PATTERN.test(value)) {\n\t\tthrow new TypeError(\"sequence must be a canonical nonnegative decimal string\");\n\t}\n\tif (value.length > MAX_SEQUENCE_LENGTH) throw new RangeError(\"sequence too long\");\n\treturn value as Sequence;\n}\n\nexport function nextSequence(value: Sequence): Sequence {\n\treturn sequence(String(BigInt(sequence(value)) + 1n));\n}\n\n/**\n * Lifecycle of an authorized effect.\n *\n * The in-process broker currently mints `reserved`, `running`, `quarantined`,\n * `terminated` and `cancelled`. `starting` and `terminating` are reserved for\n * the out-of-process supervisor that reports those transitions over the wire;\n * nothing emits them yet, and the broker must not infer them.\n */\nexport type EffectState =\n\t| \"reserved\"\n\t| \"starting\"\n\t| \"running\"\n\t| \"terminating\"\n\t| \"quarantined\"\n\t| \"terminated\"\n\t| \"cancelled\";\n\n/** States in which a grant no longer holds its claims. */\nexport const SETTLED_EFFECT_STATES: ReadonlySet<EffectState> = new Set<EffectState>([\"terminated\", \"cancelled\"]);\n\nexport type ClaimNamespace = \"filesystem\" | \"git-ref\" | \"contract\" | \"socket\" | \"database\" | \"host-budget\";\nexport type ClaimAccess = \"read\" | \"write\";\n\n/**\n * One declared resource claim.\n *\n * `canonicalKey` must already be normalized by the caller: the broker rejects\n * rather than guesses, because silently normalizing `a/../b` would let two\n * sessions believe they hold disjoint keys.\n */\nexport interface ResourceClaim {\n\treadonly namespace: ClaimNamespace;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: ClaimAccess;\n\treadonly generation: Sequence;\n}\n\n/**\n * Proof of admission for exactly one operation of one session incarnation.\n *\n * `authorizationDeadline` bounds the authorization only. Termination is a\n * separate, supervisor-reported fact.\n */\nexport interface GrantToken {\n\treadonly authorityEpoch: Sequence;\n\treadonly grantSequence: Sequence;\n\treadonly sessionId: string;\n\treadonly sessionIncarnation: Sequence;\n\treadonly authorizationDeadline: number;\n}\n\nexport type AdmissionOutcome =\n\t| { readonly status: \"granted\"; readonly token: GrantToken }\n\t| { readonly status: \"blocked\"; readonly blockers: readonly Sequence[] }\n\t| { readonly status: \"over-capacity\"; readonly requestedWeight: number; readonly availableWeight: number };\n"]}

package/dist/coordination/types.js

@@ -0,0 +1,26 @@
+/**
+ * Wire contracts for parallel-session coordination.
+ *
+ * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination
+ * design. These are new contracts, not pre-existing OMK exports.
+ *
+ * The central distinction the types encode: an authorization deadline is not a
+ * termination proof. A grant whose deadline passed while an external effect was
+ * live becomes `quarantined` — still holding its claims — rather than free.
+ */
+const SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;
+const MAX_SEQUENCE_LENGTH = 40;
+export function sequence(value) {
+    if (typeof value !== "string" || !SEQUENCE_PATTERN.test(value)) {
+        throw new TypeError("sequence must be a canonical nonnegative decimal string");
+    }
+    if (value.length > MAX_SEQUENCE_LENGTH)
+        throw new RangeError("sequence too long");
+    return value;
+}
+export function nextSequence(value) {
+    return sequence(String(BigInt(sequence(value)) + 1n));
+}
+/** States in which a grant no longer holds its claims. */
+export const SETTLED_EFFECT_STATES = new Set(["terminated", "cancelled"]);
+//# sourceMappingURL=types.js.map

package/dist/coordination/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAY;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,mBAAmB;QAAE,MAAM,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAClF,OAAO,KAAiB,CAAC;AAAA,CACzB;AAED,MAAM,UAAU,YAAY,CAAC,KAAe,EAAY;IACvD,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAAA,CACtD;AAmBD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAA6B,IAAI,GAAG,CAAc,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Wire contracts for parallel-session coordination.\n *\n * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination\n * design. These are new contracts, not pre-existing OMK exports.\n *\n * The central distinction the types encode: an authorization deadline is not a\n * termination proof. A grant whose deadline passed while an external effect was\n * live becomes `quarantined` — still holding its claims — rather than free.\n */\n\n/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */\nexport type Sequence = string & { readonly __sequence: unique symbol };\n\nconst SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;\nconst MAX_SEQUENCE_LENGTH = 40;\n\nexport function sequence(value: unknown): Sequence {\n\tif (typeof value !== \"string\" || !SEQUENCE_PATTERN.test(value)) {\n\t\tthrow new TypeError(\"sequence must be a canonical nonnegative decimal string\");\n\t}\n\tif (value.length > MAX_SEQUENCE_LENGTH) throw new RangeError(\"sequence too long\");\n\treturn value as Sequence;\n}\n\nexport function nextSequence(value: Sequence): Sequence {\n\treturn sequence(String(BigInt(sequence(value)) + 1n));\n}\n\n/**\n * Lifecycle of an authorized effect.\n *\n * The in-process broker currently mints `reserved`, `running`, `quarantined`,\n * `terminated` and `cancelled`. `starting` and `terminating` are reserved for\n * the out-of-process supervisor that reports those transitions over the wire;\n * nothing emits them yet, and the broker must not infer them.\n */\nexport type EffectState =\n\t| \"reserved\"\n\t| \"starting\"\n\t| \"running\"\n\t| \"terminating\"\n\t| \"quarantined\"\n\t| \"terminated\"\n\t| \"cancelled\";\n\n/** States in which a grant no longer holds its claims. */\nexport const SETTLED_EFFECT_STATES: ReadonlySet<EffectState> = new Set<EffectState>([\"terminated\", \"cancelled\"]);\n\nexport type ClaimNamespace = \"filesystem\" | \"git-ref\" | \"contract\" | \"socket\" | \"database\" | \"host-budget\";\nexport type ClaimAccess = \"read\" | \"write\";\n\n/**\n * One declared resource claim.\n *\n * `canonicalKey` must already be normalized by the caller: the broker rejects\n * rather than guesses, because silently normalizing `a/../b` would let two\n * sessions believe they hold disjoint keys.\n */\nexport interface ResourceClaim {\n\treadonly namespace: ClaimNamespace;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: ClaimAccess;\n\treadonly generation: Sequence;\n}\n\n/**\n * Proof of admission for exactly one operation of one session incarnation.\n *\n * `authorizationDeadline` bounds the authorization only. Termination is a\n * separate, supervisor-reported fact.\n */\nexport interface GrantToken {\n\treadonly authorityEpoch: Sequence;\n\treadonly grantSequence: Sequence;\n\treadonly sessionId: string;\n\treadonly sessionIncarnation: Sequence;\n\treadonly authorizationDeadline: number;\n}\n\nexport type AdmissionOutcome =\n\t| { readonly status: \"granted\"; readonly token: GrantToken }\n\t| { readonly status: \"blocked\"; readonly blockers: readonly Sequence[] }\n\t| { readonly status: \"over-capacity\"; readonly requestedWeight: number; readonly availableWeight: number };\n"]}

package/dist/core/adaptorch-bridge.d.ts

@@ -119,7 +119,7 @@ export declare function sanitizeConsultPayload(candidate: unknown): AdaptorchCon
 export declare function sanitizeAdvisoryResult(candidate: unknown): AdaptorchAdvisoryResult | null;
 /**
  * Read-only/local AdaptOrch MCP tool names this bridge may ever reference,
- * grounded in the real 10-tool surface documented in
+ * grounded in the eleven-tool surface documented in
  * packages/adaptorch-wpl/src/adaptorch-client.ts (cross-checked there
  * against the AdaptOrch server's own docs) and narrowed to the two tools the
  * read-first plan puts in scope for a reasoning-effort hint (plan 4.2): the