open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/coordination/integration.js

@@ -0,0 +1,126 @@
+/**
+ * Candidate publication with read-version preconditions and bound receipts.
+ *
+ * A publication is admitted only when the snapshot that was verified is still
+ * the snapshot being published. Three separate facts are checked, because any
+ * one of them alone lets a stale candidate through:
+ *   - every key the proposal read is still at the version it read,
+ *   - the parent revision has not advanced,
+ *   - the receipt is bound to this candidate, contract, check set and
+ *     environment rather than to an earlier composition of them.
+ *
+ * Absence is a dependency: reading a key that did not exist records version 0,
+ * so a later creation invalidates the proposal instead of silently racing it.
+ *
+ * Bounded model: one accepted snapshot pointer, file effects abstracted as a
+ * single update. Real multi-file atomicity needs immutable candidates plus a
+ * Git CAS/outbox protocol; this class does not provide that.
+ */
+import { createHash } from "node:crypto";
+import { canonical } from "../metacognition/validation.js";
+function digest(value) {
+    return createHash("sha256").update(canonical(value), "utf8").digest("hex");
+}
+function byKey(a, b) {
+    if (a[0] < b[0])
+        return -1;
+    return a[0] > b[0] ? 1 : 0;
+}
+export class IntegrationPublisher {
+    values = new Map();
+    versions = new Map();
+    acceptedFingerprints = new Map();
+    currentRevision = 0;
+    constructor(initial) {
+        for (const [key, value] of Object.entries(initial)) {
+            this.values.set(key, value);
+            this.versions.set(key, 1);
+        }
+    }
+    get revision() {
+        return this.currentRevision;
+    }
+    snapshot() {
+        return Object.fromEntries(this.values);
+    }
+    /** Record the versions of every key this change reads or writes. */
+    propose(proposalId, reads, writes) {
+        if (typeof proposalId !== "string" || proposalId.length === 0) {
+            throw new TypeError("proposalId must be a non-empty string");
+        }
+        const touched = new Set([...reads, ...Object.keys(writes)]);
+        return Object.freeze({
+            proposalId,
+            readVersions: Object.freeze([...touched].map((key) => Object.freeze([key, this.versions.get(key) ?? 0])).sort(byKey)),
+            writes: Object.freeze(Object.entries(writes)
+                .map(([key, value]) => Object.freeze([key, value]))
+                .sort(byKey)),
+        });
+    }
+    isCurrent(proposal) {
+        const declared = new Map(proposal.readVersions);
+        if (proposal.writes.some(([key]) => !declared.has(key)))
+            return false;
+        return proposal.readVersions.every(([key, version]) => (this.versions.get(key) ?? 0) === version);
+    }
+    applied(proposal) {
+        const next = new Map(this.values);
+        for (const [key, value] of proposal.writes) {
+            if (value === null)
+                next.delete(key);
+            else
+                next.set(key, value);
+        }
+        return next;
+    }
+    stage(proposal, contractDigest = "contract-v1", checkDigest = "checks-v1", environmentDigest = "env-v1") {
+        if (!this.isCurrent(proposal))
+            return null;
+        return Object.freeze({
+            proposal,
+            parentRevision: this.currentRevision,
+            candidateDigest: digest(Object.fromEntries(this.applied(proposal))),
+            contractDigest,
+            checkDigest,
+            environmentDigest,
+        });
+    }
+    publish(staged, receipt) {
+        const proposal = staged.proposal;
+        const fingerprint = digest({
+            proposalId: proposal.proposalId,
+            readVersions: proposal.readVersions,
+            writes: proposal.writes,
+        });
+        const seen = this.acceptedFingerprints.get(proposal.proposalId);
+        if (seen !== undefined)
+            return seen === fingerprint ? "already-accepted" : "id-collision";
+        if (staged.parentRevision !== this.currentRevision || !this.isCurrent(proposal))
+            return "stale";
+        if (!sameBinding(staged, receipt))
+            return "invalid-binding";
+        if (receipt.verdict !== "pass" || receipt.pendingEffects !== 0)
+            return "unverified";
+        // Recompute the candidate: guards a staged payload swapped after verification.
+        const rebuilt = this.stage(proposal, staged.contractDigest, staged.checkDigest, staged.environmentDigest);
+        if (rebuilt === null || rebuilt.candidateDigest !== staged.candidateDigest)
+            return "invalid-binding";
+        for (const [key, value] of proposal.writes) {
+            if (value === null)
+                this.values.delete(key);
+            else
+                this.values.set(key, value);
+            this.versions.set(key, (this.versions.get(key) ?? 0) + 1);
+        }
+        this.currentRevision += 1;
+        this.acceptedFingerprints.set(proposal.proposalId, fingerprint);
+        return "accepted";
+    }
+}
+function sameBinding(staged, receipt) {
+    return (staged.candidateDigest === receipt.candidateDigest &&
+        staged.contractDigest === receipt.contractDigest &&
+        staged.checkDigest === receipt.checkDigest &&
+        staged.environmentDigest === receipt.environmentDigest);
+}
+//# sourceMappingURL=integration.js.map

package/dist/coordination/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../../src/coordination/integration.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Candidate publication with read-version preconditions and bound receipts.\n *\n * A publication is admitted only when the snapshot that was verified is still\n * the snapshot being published. Three separate facts are checked, because any\n * one of them alone lets a stale candidate through:\n *   - every key the proposal read is still at the version it read,\n *   - the parent revision has not advanced,\n *   - the receipt is bound to this candidate, contract, check set and\n *     environment rather than to an earlier composition of them.\n *\n * Absence is a dependency: reading a key that did not exist records version 0,\n * so a later creation invalidates the proposal instead of silently racing it.\n *\n * Bounded model: one accepted snapshot pointer, file effects abstracted as a\n * single update. Real multi-file atomicity needs immutable candidates plus a\n * Git CAS/outbox protocol; this class does not provide that.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { canonical } from \"../metacognition/validation.ts\";\n\nexport type PublicationOutcome =\n\t| \"accepted\"\n\t| \"already-accepted\"\n\t| \"id-collision\"\n\t| \"stale\"\n\t| \"invalid-binding\"\n\t| \"unverified\";\n\nexport type WriteValue = string | null;\n\nexport interface ChangeProposal {\n\treadonly proposalId: string;\n\t/** Every key touched, with the version observed at propose time. */\n\treadonly readVersions: readonly (readonly [string, number])[];\n\t/** `null` deletes the key. */\n\treadonly writes: readonly (readonly [string, WriteValue])[];\n}\n\nexport interface StagedChange {\n\treadonly proposal: ChangeProposal;\n\treadonly parentRevision: number;\n\treadonly candidateDigest: string;\n\treadonly contractDigest: string;\n\treadonly checkDigest: string;\n\treadonly environmentDigest: string;\n}\n\nexport interface VerificationReceipt {\n\treadonly candidateDigest: string;\n\treadonly contractDigest: string;\n\treadonly checkDigest: string;\n\treadonly environmentDigest: string;\n\treadonly verdict: \"pass\" | \"fail\" | \"inconclusive\";\n\treadonly pendingEffects: number;\n}\n\nfunction digest(value: unknown): string {\n\treturn createHash(\"sha256\").update(canonical(value), \"utf8\").digest(\"hex\");\n}\n\nfunction byKey(a: readonly [string, unknown], b: readonly [string, unknown]): number {\n\tif (a[0] < b[0]) return -1;\n\treturn a[0] > b[0] ? 1 : 0;\n}\n\nexport class IntegrationPublisher {\n\tprivate readonly values = new Map<string, string>();\n\tprivate readonly versions = new Map<string, number>();\n\tprivate readonly acceptedFingerprints = new Map<string, string>();\n\tprivate currentRevision = 0;\n\n\tconstructor(initial: Readonly<Record<string, string>>) {\n\t\tfor (const [key, value] of Object.entries(initial)) {\n\t\t\tthis.values.set(key, value);\n\t\t\tthis.versions.set(key, 1);\n\t\t}\n\t}\n\n\tget revision(): number {\n\t\treturn this.currentRevision;\n\t}\n\n\tsnapshot(): Record<string, string> {\n\t\treturn Object.fromEntries(this.values);\n\t}\n\n\t/** Record the versions of every key this change reads or writes. */\n\tpropose(proposalId: string, reads: readonly string[], writes: Readonly<Record<string, WriteValue>>): ChangeProposal {\n\t\tif (typeof proposalId !== \"string\" || proposalId.length === 0) {\n\t\t\tthrow new TypeError(\"proposalId must be a non-empty string\");\n\t\t}\n\t\tconst touched = new Set<string>([...reads, ...Object.keys(writes)]);\n\t\treturn Object.freeze({\n\t\t\tproposalId,\n\t\t\treadVersions: Object.freeze(\n\t\t\t\t[...touched].map((key) => Object.freeze([key, this.versions.get(key) ?? 0] as const)).sort(byKey),\n\t\t\t),\n\t\t\twrites: Object.freeze(\n\t\t\t\tObject.entries(writes)\n\t\t\t\t\t.map(([key, value]) => Object.freeze([key, value] as const))\n\t\t\t\t\t.sort(byKey),\n\t\t\t),\n\t\t});\n\t}\n\n\tprivate isCurrent(proposal: ChangeProposal): boolean {\n\t\tconst declared = new Map(proposal.readVersions);\n\t\tif (proposal.writes.some(([key]) => !declared.has(key))) return false;\n\t\treturn proposal.readVersions.every(([key, version]) => (this.versions.get(key) ?? 0) === version);\n\t}\n\n\tprivate applied(proposal: ChangeProposal): Map<string, string> {\n\t\tconst next = new Map(this.values);\n\t\tfor (const [key, value] of proposal.writes) {\n\t\t\tif (value === null) next.delete(key);\n\t\t\telse next.set(key, value);\n\t\t}\n\t\treturn next;\n\t}\n\n\tstage(\n\t\tproposal: ChangeProposal,\n\t\tcontractDigest = \"contract-v1\",\n\t\tcheckDigest = \"checks-v1\",\n\t\tenvironmentDigest = \"env-v1\",\n\t): StagedChange | null {\n\t\tif (!this.isCurrent(proposal)) return null;\n\t\treturn Object.freeze({\n\t\t\tproposal,\n\t\t\tparentRevision: this.currentRevision,\n\t\t\tcandidateDigest: digest(Object.fromEntries(this.applied(proposal))),\n\t\t\tcontractDigest,\n\t\t\tcheckDigest,\n\t\t\tenvironmentDigest,\n\t\t});\n\t}\n\n\tpublish(staged: StagedChange, receipt: VerificationReceipt): PublicationOutcome {\n\t\tconst proposal = staged.proposal;\n\t\tconst fingerprint = digest({\n\t\t\tproposalId: proposal.proposalId,\n\t\t\treadVersions: proposal.readVersions,\n\t\t\twrites: proposal.writes,\n\t\t});\n\t\tconst seen = this.acceptedFingerprints.get(proposal.proposalId);\n\t\tif (seen !== undefined) return seen === fingerprint ? \"already-accepted\" : \"id-collision\";\n\t\tif (staged.parentRevision !== this.currentRevision || !this.isCurrent(proposal)) return \"stale\";\n\t\tif (!sameBinding(staged, receipt)) return \"invalid-binding\";\n\t\tif (receipt.verdict !== \"pass\" || receipt.pendingEffects !== 0) return \"unverified\";\n\n\t\t// Recompute the candidate: guards a staged payload swapped after verification.\n\t\tconst rebuilt = this.stage(proposal, staged.contractDigest, staged.checkDigest, staged.environmentDigest);\n\t\tif (rebuilt === null || rebuilt.candidateDigest !== staged.candidateDigest) return \"invalid-binding\";\n\n\t\tfor (const [key, value] of proposal.writes) {\n\t\t\tif (value === null) this.values.delete(key);\n\t\t\telse this.values.set(key, value);\n\t\t\tthis.versions.set(key, (this.versions.get(key) ?? 0) + 1);\n\t\t}\n\t\tthis.currentRevision += 1;\n\t\tthis.acceptedFingerprints.set(proposal.proposalId, fingerprint);\n\t\treturn \"accepted\";\n\t}\n}\n\nfunction sameBinding(staged: StagedChange, receipt: VerificationReceipt): boolean {\n\treturn (\n\t\tstaged.candidateDigest === receipt.candidateDigest &&\n\t\tstaged.contractDigest === receipt.contractDigest &&\n\t\tstaged.checkDigest === receipt.checkDigest &&\n\t\tstaged.environmentDigest === receipt.environmentDigest\n\t);\n}\n"]}

package/dist/coordination/operation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Authorized operation lifecycle for GUI-driving adapters (Jev audit A6).
+ *
+ * Two reproduced defects shape this module:
+ *   F01 — an adapter re-interpreted a free-text instruction at execution time,
+ *         so an approved candidate and the executed action could differ. Here
+ *         dispatch consumes a recorded observation binding, never a sentence.
+ *   F02 — a cancellation signal was accepted and then ignored across the
+ *         approval await, so a cancelled operation still dispatched. Here the
+ *         permit is re-evaluated at the dispatch boundary, and cancellation
+ *         after dispatch can never be reported as cancelled-before-dispatch.
+ *
+ * Pure state machine: no browser, no driver, no timers. "Dispatched" means the
+ * command left this process, which is not evidence about the remote effect —
+ * that is why `outcome-unknown` is a first-class state rather than a failure.
+ */
+import type { Sequence } from "./types.ts";
+export type OperationState = "created" | "observed" | "proposed" | "authorized" | "dispatched" | "applied" | "verified" | "inspection-required" | "failed-confirmed" | "outcome-unknown" | "cancelled-before-dispatch";
+/** Outcomes a driver may report once a command has left the process. */
+export type SettledOutcome = "applied" | "failed-confirmed" | "outcome-unknown";
+/**
+ * Host-held reference to one observed candidate.
+ *
+ * The adapter receives these identifiers, not an instruction string, so the
+ * action that was approved is the action that runs.
+ */
+export interface ObservationBinding {
+    readonly observationId: string;
+    readonly actionId: string;
+    readonly targetId: string;
+    /** Document/DOM generation the candidate was observed against. */
+    readonly documentGeneration: Sequence;
+}
+export type PermitDenial = "cancelled" | "policy-denied" | "approval-mismatch" | "stale-lease" | "observation-invalid" | "budget-exhausted";
+export type PermitDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: PermitDenial;
+};
+export interface PermitInput {
+    readonly policyAllowed: boolean;
+    /** Digest of the intent actually about to run. */
+    readonly intentDigest: string;
+    /** Digest the operator approved; a post-approval edit breaks this equality. */
+    readonly approvalDigest: string;
+    readonly policyVersion: string;
+    readonly approvalPolicyVersion: string;
+    readonly leaseGeneration: Sequence;
+    readonly currentLeaseGeneration: Sequence;
+    readonly observationValid: boolean;
+    readonly cancelled: boolean;
+    readonly budgetAvailable: boolean;
+}
+/**
+ * Permit(I) = PolicyAllowed ∧ ApprovalMatches ∧ LeaseCurrent ∧ ObservationValid
+ *             ∧ ¬Cancelled ∧ BudgetAvailable.
+ *
+ * Cancellation is reported first: when a run is cancelled, saying "budget
+ * exhausted" would send the operator looking for the wrong problem.
+ */
+export declare function evaluatePermit(input: PermitInput): PermitDecision;
+export declare class OperationLifecycle {
+    readonly operationId: string;
+    private current;
+    private readonly states;
+    private observations;
+    private selected;
+    private hasDispatched;
+    private cancelRequested;
+    constructor(operationId: string);
+    get state(): OperationState;
+    get history(): readonly OperationState[];
+    /** True once a command left this process; it says nothing about the effect. */
+    get dispatched(): boolean;
+    get cancellationRequested(): boolean;
+    private enter;
+    private assertOpen;
+    /** Record the host-held candidate set. Without this, nothing can dispatch. */
+    observe(candidates: readonly ObservationBinding[]): void;
+    /** Select one observed candidate. Free-text re-interpretation has no path here. */
+    propose(candidate: ObservationBinding): void;
+    authorize(permit: PermitInput): PermitDecision;
+    /**
+     * Re-evaluate the permit and hand the command to the driver.
+     *
+     * The second evaluation is the point of the audit finding: approval and
+     * dispatch are separated by awaits (queueing, the operator prompt, browser
+     * startup), and state observed before those awaits is not state now.
+     */
+    dispatch(permit: PermitInput): PermitDecision;
+    private applyPreDispatchDenial;
+    /** Driver-reported outcome. Only valid once the command actually left. */
+    settle(outcome: SettledOutcome): void;
+    /** Explicit postcondition check. A driver's return value is not this. */
+    verify(postconditionMet: boolean): void;
+    /**
+     * Request cancellation.
+     *
+     * Before dispatch this is terminal. After dispatch it only records the
+     * request: the command is already outside this process, so the real outcome
+     * has to be settled separately and stays `outcome-unknown` until it is.
+     */
+    cancel(): void;
+}
+//# sourceMappingURL=operation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/coordination/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,cAAc,GACvB,SAAS,GACT,UAAU,GACV,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,UAAU,GACV,qBAAqB,GACrB,kBAAkB,GAClB,iBAAiB,GACjB,2BAA2B,CAAC;AAE/B,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAShF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC;CACtC;AAED,MAAM,MAAM,YAAY,GACrB,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,aAAa,GACb,qBAAqB,GACrB,kBAAkB,CAAC;AAEtB,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAErH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;IACnC,QAAQ,CAAC,sBAAsB,EAAE,QAAQ,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAUjE;AAED,qBAAa,kBAAkB;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAS;IAEhC,YAAY,WAAW,EAAE,MAAM,EAK9B;IAED,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED,IAAI,OAAO,IAAI,SAAS,cAAc,EAAE,CAEvC;IAED,+EAA+E;IAC/E,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,UAAU;IAMlB,8EAA8E;IAC9E,OAAO,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI,CAKvD;IAED,mFAAmF;IACnF,OAAO,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAe3C;IAED,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAU7C;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAY5C;IAED,OAAO,CAAC,sBAAsB;IAO9B,0EAA0E;IAC1E,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAMpC;IAED,yEAAyE;IACzE,MAAM,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAGtC;IAED;;;;;;OAMG;IACH,MAAM,IAAI,IAAI,CAQb;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\";\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\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 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\tthis.observations = [...candidates];\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\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.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\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 (this.current === \"verified\" || this.current === \"inspection-required\") {\n\t\t\tthrow new Error(\"outcome already verified\");\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 (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/operation.js

@@ -0,0 +1,179 @@
+/**
+ * Authorized operation lifecycle for GUI-driving adapters (Jev audit A6).
+ *
+ * Two reproduced defects shape this module:
+ *   F01 — an adapter re-interpreted a free-text instruction at execution time,
+ *         so an approved candidate and the executed action could differ. Here
+ *         dispatch consumes a recorded observation binding, never a sentence.
+ *   F02 — a cancellation signal was accepted and then ignored across the
+ *         approval await, so a cancelled operation still dispatched. Here the
+ *         permit is re-evaluated at the dispatch boundary, and cancellation
+ *         after dispatch can never be reported as cancelled-before-dispatch.
+ *
+ * Pure state machine: no browser, no driver, no timers. "Dispatched" means the
+ * command left this process, which is not evidence about the remote effect —
+ * that is why `outcome-unknown` is a first-class state rather than a failure.
+ */
+const TERMINAL_STATES = new Set([
+    "verified",
+    "inspection-required",
+    "failed-confirmed",
+    "cancelled-before-dispatch",
+]);
+/**
+ * Permit(I) = PolicyAllowed ∧ ApprovalMatches ∧ LeaseCurrent ∧ ObservationValid
+ *             ∧ ¬Cancelled ∧ BudgetAvailable.
+ *
+ * Cancellation is reported first: when a run is cancelled, saying "budget
+ * exhausted" would send the operator looking for the wrong problem.
+ */
+export function evaluatePermit(input) {
+    if (input.cancelled)
+        return { allowed: false, reason: "cancelled" };
+    if (!input.policyAllowed)
+        return { allowed: false, reason: "policy-denied" };
+    if (input.approvalDigest !== input.intentDigest || input.approvalPolicyVersion !== input.policyVersion) {
+        return { allowed: false, reason: "approval-mismatch" };
+    }
+    if (input.leaseGeneration !== input.currentLeaseGeneration)
+        return { allowed: false, reason: "stale-lease" };
+    if (!input.observationValid)
+        return { allowed: false, reason: "observation-invalid" };
+    if (!input.budgetAvailable)
+        return { allowed: false, reason: "budget-exhausted" };
+    return { allowed: true };
+}
+export class OperationLifecycle {
+    operationId;
+    current = "created";
+    states = ["created"];
+    observations = [];
+    selected;
+    hasDispatched = false;
+    cancelRequested = false;
+    constructor(operationId) {
+        if (typeof operationId !== "string" || operationId.length === 0) {
+            throw new TypeError("operationId must be a non-empty string");
+        }
+        this.operationId = operationId;
+    }
+    get state() {
+        return this.current;
+    }
+    get history() {
+        return [...this.states];
+    }
+    /** True once a command left this process; it says nothing about the effect. */
+    get dispatched() {
+        return this.hasDispatched;
+    }
+    get cancellationRequested() {
+        return this.cancelRequested;
+    }
+    enter(next) {
+        this.current = next;
+        this.states.push(next);
+    }
+    assertOpen() {
+        if (TERMINAL_STATES.has(this.current)) {
+            throw new Error(`operation ${this.operationId} is terminal in state ${this.current}`);
+        }
+    }
+    /** Record the host-held candidate set. Without this, nothing can dispatch. */
+    observe(candidates) {
+        this.assertOpen();
+        if (candidates.length === 0)
+            throw new TypeError("observation must yield at least one candidate");
+        this.observations = [...candidates];
+        this.enter("observed");
+    }
+    /** Select one observed candidate. Free-text re-interpretation has no path here. */
+    propose(candidate) {
+        this.assertOpen();
+        if (this.observations.length === 0) {
+            throw new Error("cannot propose before observe: the candidate set is unbound");
+        }
+        const match = this.observations.find((o) => o.observationId === candidate.observationId &&
+            o.actionId === candidate.actionId &&
+            o.targetId === candidate.targetId &&
+            o.documentGeneration === candidate.documentGeneration);
+        if (match === undefined)
+            throw new Error("proposed action is not among the recorded observations");
+        this.selected = match;
+        this.enter("proposed");
+    }
+    authorize(permit) {
+        this.assertOpen();
+        if (this.current !== "proposed")
+            throw new Error("authorize requires a proposed operation");
+        const decision = evaluatePermit(permit);
+        if (!decision.allowed) {
+            this.applyPreDispatchDenial(decision.reason);
+            return decision;
+        }
+        this.enter("authorized");
+        return decision;
+    }
+    /**
+     * Re-evaluate the permit and hand the command to the driver.
+     *
+     * The second evaluation is the point of the audit finding: approval and
+     * dispatch are separated by awaits (queueing, the operator prompt, browser
+     * startup), and state observed before those awaits is not state now.
+     */
+    dispatch(permit) {
+        this.assertOpen();
+        if (this.current !== "authorized")
+            throw new Error("dispatch requires an authorized operation");
+        if (this.selected === undefined)
+            throw new Error("dispatch requires a bound observation");
+        const decision = evaluatePermit(permit);
+        if (!decision.allowed) {
+            this.applyPreDispatchDenial(decision.reason);
+            return decision;
+        }
+        this.hasDispatched = true;
+        this.enter("dispatched");
+        return decision;
+    }
+    applyPreDispatchDenial(reason) {
+        if (reason === "cancelled") {
+            this.cancelRequested = true;
+            this.enter("cancelled-before-dispatch");
+        }
+    }
+    /** Driver-reported outcome. Only valid once the command actually left. */
+    settle(outcome) {
+        if (!this.hasDispatched)
+            throw new Error("settle requires a dispatched operation");
+        if (this.current === "verified" || this.current === "inspection-required") {
+            throw new Error("outcome already verified");
+        }
+        this.enter(outcome);
+    }
+    /** Explicit postcondition check. A driver's return value is not this. */
+    verify(postconditionMet) {
+        if (this.current !== "applied")
+            throw new Error("verify requires an applied outcome");
+        this.enter(postconditionMet ? "verified" : "inspection-required");
+    }
+    /**
+     * Request cancellation.
+     *
+     * Before dispatch this is terminal. After dispatch it only records the
+     * request: the command is already outside this process, so the real outcome
+     * has to be settled separately and stays `outcome-unknown` until it is.
+     */
+    cancel() {
+        this.cancelRequested = true;
+        if (TERMINAL_STATES.has(this.current))
+            return;
+        if (!this.hasDispatched) {
+            this.enter("cancelled-before-dispatch");
+            return;
+        }
+        if (this.current === "dispatched")
+            this.enter("outcome-unknown");
+    }
+}
+//# sourceMappingURL=operation.js.map

package/dist/coordination/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/coordination/operation.ts"],"names":[],"mappings":"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","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\";\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\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 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\tthis.observations = [...candidates];\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\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.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\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 (this.current === \"verified\" || this.current === \"inspection-required\") {\n\t\t\tthrow new Error(\"outcome already verified\");\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 (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; 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,CAkBvE;AAcD,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,wFAAwF;AACxF,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 (typeof input.instanceId !== \"string\" || input.instanceId.length === 0) {\n\t\tthrow new TypeError(\"claim instanceId must be a non-empty string\");\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\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 `${claim.namespace}\\u0000${claim.instanceId}\\u0000${claim.canonicalKey}\\u0000${claim.access}`;\n}\n\n/** Exact set equality by identity+access; 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,89 @@
+/**
+ * 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) {
+        throw new TypeError("claim instanceId must be a non-empty string");
+    }
+    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");
+    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 `${claim.namespace}\u0000${claim.instanceId}\u0000${claim.canonicalKey}\u0000${claim.access}`;
+}
+/** Exact set equality by identity+access; 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