@jinn-network/task-execution-testing 0.0.0 → 0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b

package/README.md

@@ -1 +1,63 @@
-Placeholder. Real versions come from stack-npm-publish.yml.
+# @jinn-network/task-execution-testing
+
+The Jinn Task Execution Protocol (TEP) v1 conformance kit. Ships design §24's Layers 1 and 2:
+protocol conformance over the golden + adversarial fixtures, the backend contract sanity suite,
+and the in-memory fake backend that both are proven against first. Depends on
+`@jinn-network/task-execution-protocol` and `@jinn-network/task-execution-backend`.
+
+See the design: `docs/superpowers/specs/2026-07-27-task-execution-protocol-and-stack-design.md`
+§24 (conformance and fixture strategy). Carried-amendment implementation notes:
+`docs/superpowers/specs/2026-07-28-tep-v1-implementation-addendum.md`.
+
+## What ships here
+
+- **`createInMemoryBackend()` / `InMemoryTaskExecutionBackend`** — a durable-in-memory
+  `TaskExecutionBackend` reference implementation (single-party Attempt minting, §9.2). This is
+  the kit's own proof surface: both conformance layers below are proven against it *before* any
+  real binding exists (design §26).
+- **`TestableBackend`** — the frozen `TaskExecutionBackend` contract plus a minimal, documented
+  test-only seam (`drive`, `recordDelivery`, `simulateReconciliation`) that lets the Layer-2
+  suite drive lifecycle facts and force `recover` outcomes without widening the frozen §22
+  contract itself. A binding wanting to run the Layer-2 suite against itself implements this
+  seam alongside the real contract.
+- **`describeProtocolConformance()`** — a vitest `describe` block asserting the §24 Layer-1
+  rules (schema validation of all five families, producer-/consumer-side seal and digest rules,
+  reference and cardinality rules, extension preservation, observation ordering and fold
+  correctness, Delivery binding, and the full adversarial minimum set) over the golden
+  local+marketplace scenario pair and the adversarial fixtures
+  `@jinn-network/task-execution-protocol` ships.
+- **`describeTaskExecutionBackendContract(makeBackend)`** — the csi-sanity-style Layer-2 suite:
+  byte-exact idempotent submit, honest `observe`, `recover` across all three reconciliation
+  outcomes, cancel races including cancel-after-terminal, unsupported-requirement rejection
+  naming the field, failure-category mapping (operational error vs. Attempt outcome), result
+  retrieval on terminal Attempts, and concurrent Attempts within declared bounds.
+- **`describeLocalBackendContract(makeBackend)`** from the `./backend-local` subpath — registers
+  that unchanged Layer-2 suite against the real local assembly, then adds the one-live-writer,
+  `attempts` 1..1, seal-once recovery, and evidence-finalization/indexing posture checks.
+
+## Using the kit from a binding
+
+```ts
+import { describeProtocolConformance, describeTaskExecutionBackendContract } from "@jinn-network/task-execution-testing";
+
+describeProtocolConformance();
+describeTaskExecutionBackendContract(() => createMyBinding());
+```
+
+Both are ordinary vitest `describe` blocks — run them from any `.test.ts` file under the
+consumer's own vitest configuration. `vitest` is an optional peer dependency of this package: a
+consumer already running vitest need not install anything extra.
+
+## The kit-precedes-bindings rule (design §26)
+
+The in-memory fake is proven against `describeTaskExecutionBackendContract` first, in this
+package, before any real binding is written. A binding is conformant once it passes the same
+suite against itself.
+
+## Two honestly-Layer-3 boundaries
+
+Two adversarial cases are *not* caught by Layer-1 protocol structure alone — dispatch-context
+grafting into a re-sealed crate, and capability-grant misuse via a leaked-Task resubmission. The
+kit documents this boundary explicitly (§24) rather than faking a catch: both require the
+Layer-3 `dispatch-binding` verification check, which compares a crate's captured inputs against
+the backend's own dispatch record — out of this package's scope.

package/dist/backend-contract.d.ts

@@ -0,0 +1,9 @@
+import type { TestableBackend } from "./fake-backend.js";
+export type DescribeTaskExecutionBackendContract = typeof describeTaskExecutionBackendContract;
+/**
+ * The §24 Layer-2 csi-sanity-style backend contract suite: any `TaskExecutionBackend`
+ * implementation satisfying the documented `TestableBackend` seam (drive, recordDelivery,
+ * simulateReconciliation — test-only, not part of the frozen §22 contract) can run this suite.
+ * Proven first against the in-memory fake (design §26); bindings run it against themselves.
+ */
+export declare function describeTaskExecutionBackendContract(makeBackend: () => TestableBackend): void;

package/dist/backend-contract.js

@@ -0,0 +1,394 @@
+import { TaskExecutionError } from "@jinn-network/task-execution-backend";
+import { documentDigest, sealDelivery, sealSubmission, sealTask } from "@jinn-network/task-execution-protocol";
+import { describe, expect, test } from "vitest";
+let counter = 0;
+function unique(prefix) {
+    counter += 1;
+    return `${prefix}-${counter}`;
+}
+const PROFILE = {
+    uri: "https://spec.jinn.network/task-profiles/repository-work/1.0",
+    digest: { sha256: "3917f0428b2626fd2cc93675172731cc000b69d7d783f9adaf5159be56fd10a6" },
+};
+function taskBytes() {
+    return sealTask({
+        protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+        profile: PROFILE,
+        instructions: "Backend-contract sanity fixture.",
+        outputs: [{ name: "patch", mediaType: "text/x-diff", required: true }],
+    });
+}
+function submissionBytes(taskDigest, overrides = {}) {
+    return sealSubmission({
+        protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+        submission: `urn:uuid:${crypto.randomUUID()}`,
+        task: { digest: { sha256: taskDigest.replace(/^sha256:/, "") } },
+        requester: `urn:uuid:${crypto.randomUUID()}`,
+        idempotencyKey: unique("backend-contract"),
+        nonce: unique("nonce"),
+        deadline: "2099-01-01T00:00:00Z",
+        ...overrides,
+    });
+}
+function deliveryBytesFor(taskDigest, attempt) {
+    return sealDelivery({
+        protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+        attempt,
+        task: taskDigest,
+        outputs: [{ name: "patch", mediaType: "text/x-diff", digest: { sha256: "b".repeat(64) } }],
+        outcome: "fulfilled",
+        createdAt: "2026-07-28T00:05:00Z",
+    });
+}
+// `foldObservations` self-filters to the authoritative source pinned by `attempt-engaged`
+// (§10.1/§10.4): a driven observation must carry that same envelope `source` to count toward
+// derived state, so every fixture below takes the attempt's real authoritative `source` as a
+// parameter rather than inventing its own producer identity.
+function terminalObservation(attempt, source, state, blame) {
+    return {
+        specversion: "1.0",
+        id: unique("evt"),
+        source,
+        subject: attempt,
+        time: new Date().toISOString(),
+        datacontenttype: "application/json",
+        sequence: "9999999999999999",
+        type: "network.jinn.task-execution.attempt-terminal.v1",
+        data: { state, ...(blame !== undefined ? { blame } : {}) },
+    };
+}
+function startedObservation(attempt, source) {
+    return {
+        specversion: "1.0",
+        id: unique("evt"),
+        source,
+        subject: attempt,
+        time: new Date().toISOString(),
+        datacontenttype: "application/json",
+        sequence: "0000000000000050",
+        type: "network.jinn.task-execution.attempt-started.v1",
+        data: { startedAt: new Date().toISOString() },
+    };
+}
+async function submitAccepted(backend, overrides = {}) {
+    const task = taskBytes();
+    const taskDigest = documentDigest(task);
+    const submission = submissionBytes(taskDigest, overrides);
+    const ack = await backend.submit(task, submission);
+    if (!ack.accepted)
+        throw new Error(`expected acceptance, got ${JSON.stringify(ack.error)}`);
+    const snapshot = await backend.observe(ack.submission);
+    const engaged = snapshot.observations.find((observation) => observation.type === "network.jinn.task-execution.attempt-engaged.v1");
+    if (engaged === undefined)
+        throw new Error("expected an attempt-engaged observation on submit");
+    return { attempt: snapshot.descriptor.attempt, taskDigest, source: engaged.source };
+}
+// TEP Addendum 2026-07-28-b (two-party engagement, program §7.2/§7.22): builds a well-formed
+// engagement whose dispatch-context content agrees with the Submission it accompanies.
+function engagementFor(taskDigest, submission, nonce, attemptUri) {
+    return {
+        attemptUri,
+        dispatchContext: { taskDigest, submission, nonce, attempt: attemptUri },
+    };
+}
+/**
+ * The §24 Layer-2 csi-sanity-style backend contract suite: any `TaskExecutionBackend`
+ * implementation satisfying the documented `TestableBackend` seam (drive, recordDelivery,
+ * simulateReconciliation — test-only, not part of the frozen §22 contract) can run this suite.
+ * Proven first against the in-memory fake (design §26); bindings run it against themselves.
+ */
+export function describeTaskExecutionBackendContract(makeBackend) {
+    describe("TEP Layer 2: backend contract sanity suite", () => {
+        test("submit is byte-exact idempotent: same-key/same-bytes returns the same acknowledgement", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const submission = submissionBytes(documentDigest(task));
+            const first = await backend.submit(task, submission);
+            const second = await backend.submit(task, submission);
+            expect(second).toEqual(first);
+        });
+        test("submit rejects same-key/different-bytes as a typed submission-conflict", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const requester = `urn:uuid:${crypto.randomUUID()}`;
+            const key = unique("conflict-key");
+            const first = submissionBytes(taskDigest, { requester, idempotencyKey: key });
+            const second = submissionBytes(taskDigest, { requester, idempotencyKey: key, nonce: unique("different-nonce") });
+            const firstAck = await backend.submit(task, first);
+            expect(firstAck.accepted).toBe(true);
+            const secondAck = await backend.submit(task, second);
+            expect(secondAck.accepted).toBe(false);
+            if (secondAck.accepted)
+                throw new Error("unreachable");
+            expect(secondAck.error).toBeInstanceOf(TaskExecutionError);
+            expect(secondAck.error.category).toBe("submission-conflict");
+        });
+        test("observe is honest: distinguishes pending, running, and a failed terminal (never infers success from liveness)", async () => {
+            const backend = makeBackend();
+            const { attempt, source } = await submitAccepted(backend);
+            const pending = await backend.observe(attempt);
+            expect(pending.descriptor.derived.state).toBe("pending");
+            expect(pending.descriptor.derived.terminal).toBe(false);
+            await backend.drive(attempt, [startedObservation(attempt, source)]);
+            const running = await backend.observe(attempt);
+            expect(running.descriptor.derived.state).toBe("running");
+            expect(running.descriptor.derived.terminal).toBe(false);
+            await backend.drive(attempt, [terminalObservation(attempt, source, "failed", "task")]);
+            const failed = await backend.observe(attempt);
+            expect(failed.descriptor.derived.state).toBe("failed");
+            expect(failed.descriptor.derived.terminal).toBe(true);
+            expect(failed.descriptor.derived.blame).toBe("task");
+        });
+        test("recover classifies matching, absent, and contradictory, and fail-loud never guesses on contradictory", async () => {
+            const backend = makeBackend();
+            const { attempt } = await submitAccepted(backend);
+            const matching = await backend.recover(attempt);
+            expect(matching.classification).toBe("matching");
+            backend.simulateReconciliation(attempt, { classification: "absent", detail: "no durable record found" });
+            const absent = await backend.recover(attempt);
+            expect(absent.classification).toBe("absent");
+            backend.simulateReconciliation(attempt, {
+                classification: "contradictory",
+                detail: "durable record disagrees with backend-native state",
+            });
+            const contradictory = await backend.recover(attempt);
+            expect(contradictory.classification).toBe("contradictory");
+            expect(contradictory.detail).toBeDefined();
+        });
+        test("cancel is idempotent and terminal-state-aware, including cancel-after-terminal (cancel races)", async () => {
+            const backend = makeBackend();
+            if (backend.cancel === undefined)
+                return; // optional capability (§14)
+            const cancel = backend.cancel.bind(backend);
+            const { attempt, source } = await submitAccepted(backend);
+            const beforeTerminal = await cancel(attempt, "no longer needed");
+            expect(beforeTerminal.requested).toBe(true);
+            expect(beforeTerminal.terminalState).toBeUndefined();
+            await backend.drive(attempt, [terminalObservation(attempt, source, "delivered")]);
+            const afterTerminalFirst = await cancel(attempt, "race: caller A");
+            const afterTerminalSecond = await cancel(attempt, "race: caller B");
+            expect(afterTerminalFirst).toEqual({ requested: false, terminalState: "delivered" });
+            expect(afterTerminalSecond).toEqual(afterTerminalFirst);
+        });
+        test("submit names the field it rejects: an undeclared run-pinning key is unsupported-requirement", async () => {
+            const backend = makeBackend();
+            const capabilities = await backend.capabilities();
+            const declared = new Set(capabilities.runPinning.keys.map((entry) => entry.key));
+            const undeclaredKey = ["harness", "model", "loadout", "isolationPolicy"].find((key) => !declared.has(key))
+                ?? "x-conformance-kit/definitely-unsupported-key";
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submission = submissionBytes(taskDigest, { requirements: { [undeclaredKey]: { id: "unsupported-value" } } });
+            const ack = await backend.submit(task, submission);
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("unsupported-requirement");
+        });
+        test("failure-category mapping: an operational rejection is a TaskExecutionError, distinct from a failed Attempt terminal", async () => {
+            const backend = makeBackend();
+            // A structurally malformed Task (missing the required outputs[] field, never run through
+            // the sealer's own validation) is an operational rejection, not an Attempt outcome.
+            const malformedTaskBytes = new TextEncoder().encode(JSON.stringify({
+                protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+                profile: PROFILE,
+                instructions: "missing the required outputs[] field",
+            }));
+            const malformedAck = await backend.submit(malformedTaskBytes, submissionBytes(`sha256:${"0".repeat(64)}`));
+            expect(malformedAck.accepted).toBe(false);
+            if (malformedAck.accepted)
+                throw new Error("unreachable");
+            expect(malformedAck.error).toBeInstanceOf(TaskExecutionError);
+            expect(malformedAck.error.category).toBe("invalid-document");
+            // observe() on a reference the backend never engaged is an operational rejection too.
+            await expect(backend.observe("urn:uuid:00000000-0000-5000-8000-000000000000")).rejects.toBeInstanceOf(TaskExecutionError);
+            await expect(backend.observe("urn:uuid:00000000-0000-5000-8000-000000000000")).rejects.toMatchObject({
+                category: "attempt-not-found",
+            });
+            // By contrast, a *failed* Attempt terminal is a successful, honest observe() — a work
+            // outcome, never an operational error (§13).
+            const { attempt, source } = await submitAccepted(backend);
+            await backend.drive(attempt, [terminalObservation(attempt, source, "failed", "task")]);
+            const snapshot = await backend.observe(attempt);
+            expect(snapshot.descriptor.derived.state).toBe("failed");
+        });
+        test("result retrieval on terminal Attempts: deliveries + fetchDelivery return exact bytes; result-unavailable is loud otherwise", async () => {
+            const backend = makeBackend();
+            const { attempt, taskDigest, source } = await submitAccepted(backend);
+            const delivery = deliveryBytesFor(taskDigest, attempt);
+            await backend.recordDelivery(attempt, delivery);
+            await backend.drive(attempt, [terminalObservation(attempt, source, "delivered")]);
+            const refs = await backend.deliveries(attempt);
+            expect(refs).toHaveLength(1);
+            const fetched = await backend.fetchDelivery(refs[0]);
+            expect(fetched).toEqual(delivery);
+            await expect(backend.fetchDelivery({ attempt, digest: `sha256:${"c".repeat(64)}` })).rejects.toMatchObject({ category: "result-unavailable" });
+        });
+        test("idempotency scope is delimited: concatenation-colliding (requester, idempotencyKey) pairs never conflict or capture each other (§12.2)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            // Chosen so naive concatenation ("requester" + "idempotencyKey") collides: "ab" + "c" ===
+            // "a" + "bc" === "abc". A scope key with no delimiter between the two fields would treat
+            // these as the same scope — exactly the cross-requester capture §12.2 forbids.
+            const first = submissionBytes(taskDigest, { requester: "ab", idempotencyKey: "c" });
+            const second = submissionBytes(taskDigest, { requester: "a", idempotencyKey: "bc" });
+            const firstAck = await backend.submit(task, first);
+            const secondAck = await backend.submit(task, second);
+            expect(firstAck.accepted).toBe(true);
+            expect(secondAck.accepted).toBe(true);
+            if (!firstAck.accepted || !secondAck.accepted)
+                throw new Error("unreachable");
+            expect(firstAck.submission).not.toBe(secondAck.submission);
+            const firstSnapshot = await backend.observe(firstAck.submission);
+            const secondSnapshot = await backend.observe(secondAck.submission);
+            expect(firstSnapshot.descriptor.attempt).not.toBe(secondSnapshot.descriptor.attempt);
+        });
+        test("the same idempotencyKey under two different requesters yields two distinct accepted Submissions (no conflict, no capture, §12.2)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const sharedKey = unique("shared-key");
+            const requesterA = `urn:uuid:${crypto.randomUUID()}`;
+            const requesterB = `urn:uuid:${crypto.randomUUID()}`;
+            const firstAck = await backend.submit(task, submissionBytes(taskDigest, { requester: requesterA, idempotencyKey: sharedKey }));
+            const secondAck = await backend.submit(task, submissionBytes(taskDigest, { requester: requesterB, idempotencyKey: sharedKey }));
+            expect(firstAck.accepted).toBe(true);
+            expect(secondAck.accepted).toBe(true);
+            if (!firstAck.accepted || !secondAck.accepted)
+                throw new Error("unreachable");
+            expect(firstAck.submission).not.toBe(secondAck.submission);
+        });
+        test("submit rejects when the Submission's task digest does not match the provided Task bytes (invalid-reference, §8)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const wrongDigest = `sha256:${"0".repeat(64)}`;
+            const submission = submissionBytes(wrongDigest);
+            const ack = await backend.submit(task, submission);
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("invalid-reference");
+            expect(ack.error.retryable).toBe(false);
+        });
+        test("submit rejects supplied evaluationRequirements this backend does not declare/interpret (unsupported-requirement, §8)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submission = submissionBytes(taskDigest, { evaluationRequirements: { minConfidenceBps: 900 } });
+            const ack = await backend.submit(task, submission);
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("unsupported-requirement");
+        });
+        test("submit rejects supplied capabilityGrants this backend does not declare/interpret (unsupported-requirement, §8)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submission = submissionBytes(taskDigest, { capabilityGrants: { "x-conformance-kit/grant": true } });
+            const ack = await backend.submit(task, submission);
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("unsupported-requirement");
+        });
+        test("submit rejects a requested attempts bound outside this backend's declared range (unsupported-requirement, §8)", async () => {
+            const backend = makeBackend();
+            const capabilities = await backend.capabilities();
+            const declaredMaxTotal = capabilities.attempts.maxTotal;
+            if (declaredMaxTotal === undefined) {
+                throw new Error("fixture expects this backend to declare attempts.maxTotal bounds");
+            }
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const outOfRange = declaredMaxTotal[1] + 1;
+            const submission = submissionBytes(taskDigest, { attempts: { maxTotal: outOfRange } });
+            const ack = await backend.submit(task, submission);
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("unsupported-requirement");
+        });
+        test("concurrent Attempts on one Task, under separate Submissions, are legal within declared bounds (§9.2)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const bounds = { attempts: { maxConcurrent: 1, maxTotal: 1 } };
+            const firstAck = await backend.submit(task, submissionBytes(taskDigest, bounds));
+            const secondAck = await backend.submit(task, submissionBytes(taskDigest, bounds));
+            if (!firstAck.accepted || !secondAck.accepted)
+                throw new Error("unreachable");
+            const first = await backend.observe(firstAck.submission);
+            const second = await backend.observe(secondAck.submission);
+            expect(first.descriptor.attempt).not.toBe(second.descriptor.attempt);
+            expect(first.descriptor.derived.terminal).toBe(false);
+            expect(second.descriptor.derived.terminal).toBe(false);
+        });
+        test("two-party engagement: submit adopts the caller-supplied attemptUri instead of minting one (TEP Addendum 2026-07-28-b)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submissionUri = `urn:uuid:${crypto.randomUUID()}`;
+            const nonce = unique("engaged-nonce");
+            const submission = submissionBytes(taskDigest, { submission: submissionUri, nonce });
+            const attemptUri = `urn:uuid:${crypto.randomUUID()}`;
+            const ack = await backend.submit(task, submission, engagementFor(taskDigest, submissionUri, nonce, attemptUri));
+            expect(ack.accepted).toBe(true);
+            if (!ack.accepted)
+                throw new Error("unreachable");
+            const snapshot = await backend.observe(ack.submission);
+            expect(snapshot.descriptor.attempt).toBe(attemptUri);
+        });
+        test("two-party engagement: a malformed attemptUri is rejected as invalid-document, never adopted (TEP Addendum 2026-07-28-b)", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submissionUri = `urn:uuid:${crypto.randomUUID()}`;
+            const nonce = unique("malformed-nonce");
+            const submission = submissionBytes(taskDigest, { submission: submissionUri, nonce });
+            const malformedAttemptUri = "urn:uuid:not-a-real-uuid";
+            const ack = await backend.submit(task, submission, engagementFor(taskDigest, submissionUri, nonce, malformedAttemptUri));
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error).toBeInstanceOf(TaskExecutionError);
+            expect(ack.error.category).toBe("invalid-document");
+        });
+        test("two-party engagement absent: submit mints a random Attempt URI, single-party semantics unchanged (TEP Addendum 2026-07-28-b)", async () => {
+            const backend = makeBackend();
+            const { attempt } = await submitAccepted(backend);
+            expect(attempt).toMatch(/^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+        });
+        test("two-party engagement scopes the attempts honor-or-reject to the single caller-identified attempt (marketplace-binding-design Finding F4)", async () => {
+            const backend = makeBackend();
+            const capabilities = await backend.capabilities();
+            const declaredMaxTotal = capabilities.attempts.maxTotal;
+            if (declaredMaxTotal === undefined) {
+                throw new Error("fixture expects this backend to declare attempts.maxTotal bounds");
+            }
+            // Out of the backend's own declared range — rejected in single-party mode (see the
+            // "outside this backend's declared range" test above), but a chain enforces `maxClaims`
+            // in two-party mode, not this backend, so it must be honored here.
+            const outOfRange = declaredMaxTotal[1] + 1;
+            const task = taskBytes();
+            const taskDigest = documentDigest(task);
+            const submissionUri = `urn:uuid:${crypto.randomUUID()}`;
+            const nonce = unique("scoped-nonce");
+            const submission = submissionBytes(taskDigest, {
+                submission: submissionUri,
+                nonce,
+                attempts: { maxTotal: outOfRange },
+            });
+            const attemptUri = `urn:uuid:${crypto.randomUUID()}`;
+            const ack = await backend.submit(task, submission, engagementFor(taskDigest, submissionUri, nonce, attemptUri));
+            expect(ack.accepted).toBe(true);
+        });
+    });
+}

package/dist/backend-local/backend-contract.d.ts

@@ -0,0 +1,26 @@
+import type { LocalTaskExecutionBackend } from "@jinn-network/task-execution-backend-local";
+import type { TestableBackend } from "../fake-backend.js";
+export interface LocalBackendConformanceSubject extends TestableBackend, Pick<LocalTaskExecutionBackend, "close" | "deliveryCheckpointPath" | "drain"> {
+    /** Local backend extension: drain workers/inflight before releasing the writer lock. */
+    shutdown(): Promise<void>;
+}
+export interface LocalBackendContractFactory {
+    (): LocalBackendConformanceSubject;
+    readonly lockedPair: () => {
+        readonly first: LocalBackendConformanceSubject;
+        readonly second: LocalBackendConformanceSubject;
+    };
+    readonly evidenceScenario: (mode: "success" | "finalization-failure") => {
+        readonly backend: LocalBackendConformanceSubject;
+        readonly indexingCalls: () => number;
+    };
+    readonly sealOnceScenario: () => {
+        readonly backend: LocalBackendConformanceSubject;
+        readonly restart: () => LocalBackendConformanceSubject;
+    };
+}
+/**
+ * The exact local binding suite. It registers the unchanged TEP core kit first, then exercises
+ * the binding-specific one-writer, one-attempt, seal-once, and evidence-capture postures.
+ */
+export declare function describeLocalBackendContract(makeBackend: LocalBackendContractFactory): void;

package/dist/backend-local/backend-contract.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+import { TaskExecutionError } from "@jinn-network/task-execution-backend";
+import { documentDigest, sealDelivery, sealSubmission, sealTask, } from "@jinn-network/task-execution-protocol";
+import { describeTaskExecutionBackendContract, } from "../backend-contract.js";
+import { describe, expect, test } from "vitest";
+const PROFILE = {
+    uri: "https://spec.jinn.network/task-profiles/repository-work/1.0",
+    digest: {
+        sha256: "3917f0428b2626fd2cc93675172731cc000b69d7d783f9adaf5159be56fd10a6",
+    },
+};
+function taskBytes() {
+    return sealTask({
+        protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+        profile: PROFILE,
+        instructions: "Local backend conformance fixture.",
+        outputs: [{ name: "patch", mediaType: "text/x-diff", required: true }],
+    });
+}
+function submissionBytes(task, overrides = {}) {
+    return sealSubmission({
+        protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+        submission: `urn:uuid:${crypto.randomUUID()}`,
+        task: { digest: { sha256: documentDigest(task).slice("sha256:".length) } },
+        requester: `urn:uuid:${crypto.randomUUID()}`,
+        idempotencyKey: crypto.randomUUID(),
+        nonce: crypto.randomUUID(),
+        deadline: "2099-01-01T00:00:00Z",
+        ...overrides,
+    });
+}
+async function acceptedAttempt(backend, task, submission) {
+    const ack = await backend.submit(task, submission);
+    if (!ack.accepted)
+        throw new Error(`expected accepted: ${ack.error.category}`);
+    return (await backend.observe(ack.submission)).descriptor.attempt;
+}
+/**
+ * The exact local binding suite. It registers the unchanged TEP core kit first, then exercises
+ * the binding-specific one-writer, one-attempt, seal-once, and evidence-capture postures.
+ */
+export function describeLocalBackendContract(makeBackend) {
+    describeTaskExecutionBackendContract(makeBackend);
+    describe("Local backend conformance (design §16)", () => {
+        test("two live instances on one root fail the second submit/recover as backend-unavailable", async () => {
+            const { first, second } = makeBackend.lockedPair();
+            const task = taskBytes();
+            const submission = submissionBytes(task);
+            const firstAck = await first.submit(task, submission);
+            if (!firstAck.accepted)
+                throw new Error("expected first instance acceptance");
+            const anotherTask = taskBytes();
+            const secondAck = await second.submit(anotherTask, submissionBytes(anotherTask));
+            expect(secondAck.accepted).toBe(false);
+            if (secondAck.accepted)
+                throw new Error("unreachable");
+            expect(secondAck.error).toBeInstanceOf(TaskExecutionError);
+            expect(secondAck.error.category).toBe("backend-unavailable");
+            await expect(second.recover(firstAck.submission)).rejects.toMatchObject({
+                category: "backend-unavailable",
+            });
+        });
+        test("single-party attempts bounds outside 1..1 are unsupported-requirement", async () => {
+            const backend = makeBackend();
+            const task = taskBytes();
+            const ack = await backend.submit(task, submissionBytes(task, { attempts: { maxTotal: 2 } }));
+            expect(ack.accepted).toBe(false);
+            if (ack.accepted)
+                throw new Error("unreachable");
+            expect(ack.error.category).toBe("unsupported-requirement");
+        });
+        test("seal-once recovery reuses the exact checkpoint after the scripted post-checkpoint crash", async () => {
+            const scenario = makeBackend.sealOnceScenario();
+            const task = taskBytes();
+            const attempt = await acceptedAttempt(scenario.backend, task, submissionBytes(task));
+            const delivery = sealDelivery({
+                protocol: "https://spec.jinn.network/profiles/task-execution/v1",
+                attempt,
+                task: documentDigest(task),
+                outputs: [],
+                outcome: "fulfilled",
+                createdAt: "2026-07-28T00:05:00Z",
+            });
+            await expect(scenario.backend.recordDelivery(attempt, delivery)).rejects.toThrow("scripted crash after checkpoint");
+            await scenario.backend.shutdown();
+            const recovered = scenario.restart();
+            expect(await recovered.recover(attempt)).toEqual({ classification: "matching" });
+            const refs = await recovered.deliveries(attempt);
+            expect(refs).toHaveLength(1);
+            expect(refs[0]?.digest).toBe(documentDigest(delivery));
+            expect(await recovered.fetchDelivery(refs[0])).toEqual(delivery);
+        });
+        test("capture always finalizes before delivered and indexing never gates Delivery", async () => {
+            const scenario = makeBackend.evidenceScenario("success");
+            const task = taskBytes();
+            const submission = submissionBytes(task);
+            const ack = await scenario.backend.submit(task, submission);
+            if (!ack.accepted)
+                throw new Error(`expected accepted: ${ack.error.category}`);
+            await scenario.backend.drain();
+            const snapshot = await scenario.backend.observe(ack.submission);
+            expect(snapshot.descriptor.derived.state).toBe("delivered");
+            const types = snapshot.observations.map(({ type }) => type);
+            expect(types.indexOf("network.jinn.task-execution.execution-observed.v1"))
+                .toBeLessThan(types.indexOf("network.jinn.task-execution.delivery-recorded.v1"));
+            expect(types.indexOf("network.jinn.task-execution.delivery-recorded.v1"))
+                .toBeLessThan(types.indexOf("network.jinn.task-execution.attempt-terminal.v1"));
+            expect(scenario.indexingCalls()).toBe(0);
+            const refs = await scenario.backend.deliveries(snapshot.descriptor.attempt);
+            const delivery = JSON.parse(new TextDecoder().decode(await scenario.backend.fetchDelivery(refs[0])));
+            expect(delivery.evidenceRecords).toHaveLength(1);
+            expect(delivery.executionIds).toHaveLength(1);
+        });
+        test("capture always finalization failure is failed[infrastructure] with no Delivery", async () => {
+            const { backend } = makeBackend.evidenceScenario("finalization-failure");
+            const task = taskBytes();
+            const ack = await backend.submit(task, submissionBytes(task));
+            if (!ack.accepted)
+                throw new Error(`expected accepted: ${ack.error.category}`);
+            await backend.drain();
+            const snapshot = await backend.observe(ack.submission);
+            expect(snapshot.descriptor.derived).toMatchObject({
+                state: "failed",
+                terminal: true,
+                blame: "infrastructure",
+            });
+            expect(await backend.deliveries(snapshot.descriptor.attempt)).toEqual([]);
+        });
+    });
+}

package/dist/backend-local/canonical.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test-infra-only canonicalization for PINNING fixture digests (design §16, program §7.14). This
+ * is NOT one of the tree's per-package sealing implementations (Global Constraints — those live
+ * in each of the four backend-local packages' own `order.ts`/`canonical-json.ts`, copied
+ * verbatim and re-implemented per package); it exists only so this kit's fixtures can carry a
+ * golden sha256 digest that a real implementation (Milestone A5 onward) is expected to
+ * reproduce once it seals the same logical record through its OWN canonical serializer. The
+ * sorting rule is identical (UTF-16 code-unit order, never `localeCompare`) so the pinned
+ * digests are meaningful golden values, not incidental to this file's own ordering choice.
+ */
+/** UTF-16 code-unit order — never `localeCompare` (see any package's `order.ts`). */
+export declare function compareCodeUnitStrings(left: string, right: string): number;
+/** Deterministic canonical-JSON string for a fixture record (sorted keys, code-unit order). */
+export declare function serializeCanonicalFixture(value: unknown): string;