@nanobpm/nano-workforce 0.201.4 → 0.202.0

package/app/agentic/claim-registry.test.ts

@@ -112,6 +112,67 @@ test("reconnect-resync: re-register + re-claim rebuilds the same claim (never bl
   assert.equal(reg.count(), 1);
 });
 
+test("replaceInstance: an authoritative resync drops a claim the supervisor did NOT re-assert (a lost RELEASE no longer strands the job)", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8421");
+  // The hub missed the `release` for 8420 during an outage. On reconnect the supervisor restates its
+  // authoritative snapshot: wk-a now owns only 8421. The non-re-asserted 8420 is dropped.
+  reg.replaceInstance("wk-a", ["8421"]);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8421"]);
+  assert.equal(reg.isClaimed("8420"), false, "the stranded claim was dropped");
+  assert.equal(reg.count(), 1);
+});
+
+test("replaceInstance: a re-asserted claim is unchanged; an added one is claimed", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.replaceInstance("wk-a", ["8420", "8421"]);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420", "8421"]);
+  assert.equal(reg.ownerOf("8420"), "wk-a");
+  assert.equal(reg.ownerOf("8421"), "wk-a");
+});
+
+test("replaceInstance: an empty snapshot drops every claim the instance held", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8421");
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.equal(reg.count(), 0);
+});
+
+test("replaceInstance: a jobKey that moved to another instance is NOT dropped by the old instance's resync", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8420"); // 8420 moved to wk-b
+  // wk-a's authoritative resync no longer mentions 8420 (it does not run it) — and must not blank the
+  // live owner wk-b.
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8420"], "the current owner's claim survives");
+  assert.equal(reg.ownerOf("8420"), "wk-b");
+});
+
+test("replaceInstance: only the resyncing instance's claims are touched; siblings are untouched", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8500");
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8500"], "an unrelated instance's claim is untouched");
+});
+
+test("replaceInstance is idempotent and ignores empty jobKeys / an empty instance", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.replaceInstance("wk-a", ["8420", ""]); // the empty jobKey is ignored
+  reg.replaceInstance("wk-a", ["8420"]); // repeat — no churn
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
+  reg.replaceInstance("", ["9999"]); // an empty instance is ignored
+  assert.equal(reg.isClaimed("9999"), false);
+  assert.equal(reg.count(), 1);
+});
+
 test("reconcile drops claims for absent instances, keeps present ones, and reports the released", () => {
   const reg = new ClaimRegistry();
   reg.claim("wk-a", "8420");

package/app/agentic/claim-registry.ts

@@ -52,7 +52,9 @@ export interface ClaimSnapshot {
  * It needs no durable backing: claims are ephemeral and re-announced. On a WS reconnect the supervisor
  * re-`register`s every worker and re-`claim`s every active jobKey, so the registry is rebuilt from that
  * full-state resync — which is exactly what makes it survive the reconnect that the old relay-derived
- * path stranded the jobKey across.
+ * path stranded the jobKey across. A supervisor may close its resync with an AUTHORITATIVE snapshot via
+ * {@link replaceInstance} (issue #893), dropping any claim it did not re-assert so a lost `release`
+ * cannot strand a job; omitting it keeps the additive re-claim behaviour.
  */
 export class ClaimRegistry {
   /** worker instance → the set of jobKeys it currently owns (insertion-ordered). */
@@ -107,6 +109,38 @@ export class ClaimRegistry {
     this.#jobsOf.delete(instance);
   }
 
+  /**
+   * Authoritatively REPLACE every claim held by `instance` with `jobKeys` — the reconnect-resync
+   * contract (issue #893). A reconnecting supervisor restates the full, current ownership snapshot for
+   * one worker instance; its view WINS. Every claim this instance held that is NOT in `jobKeys` is
+   * dropped (so a `release` lost during a hub outage no longer strands the job as "working" until the
+   * worker exits entirely), and every jobKey in `jobKeys` is (re-)claimed — an idempotent no-op for one
+   * it already owned, a {@link claim} move for one another instance held.
+   *
+   * It keeps the registry's existing guarantees: a jobKey that has MOVED to another instance is never
+   * blanked by the OLD instance's resync (the old instance no longer holds it, so the drop pass cannot
+   * touch it), and repeated resyncs are safe. Only `instance`'s own claims are considered — a sibling's
+   * claims are untouched. An empty `instance` is ignored; empty jobKeys in the snapshot are skipped.
+   *
+   * This is ADDITIVE on the wire: a supervisor that never sends a resync snapshot keeps the pre-#893
+   * merge behaviour (claims cleared only by an explicit `release` or the presence-driven
+   * {@link reconcile}). Authoritative replacement is safe precisely because ownership is advisory,
+   * short-lived visibility the supervisor can always restate (ADR 0056 — the registry never gates a
+   * BPMN flow).
+   */
+  replaceInstance(instance: string, jobKeys: Iterable<string>): void {
+    if (instance === "") return;
+    const next = new Set<string>();
+    for (const jobKey of jobKeys) if (jobKey !== "") next.add(jobKey);
+    const current = this.#jobsOf.get(instance);
+    if (current) {
+      for (const jobKey of [...current]) {
+        if (!next.has(jobKey)) this.release(instance, jobKey);
+      }
+    }
+    for (const jobKey of next) this.claim(instance, jobKey);
+  }
+
   /**
    * Drop every claim whose owning instance is NOT in `presentInstances` — the bounded-memory
    * reconcile a maintenance tick drives against the live presence set, so a departed supervisor's

package/app/agentic/families/claim.family.test.ts

@@ -56,6 +56,10 @@ function releaseFrame(instance: string, jobKey: string): Frame {
   return { lane: "control", family: RELEASE_FAMILY, seq: 1, payload: { instance, jobKey } };
 }
 
+function resyncFrame(instance: string, jobKeys: string[]): Frame {
+  return { lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance, jobKeys } };
+}
+
 function mountClaim(): { hub: AgenticHub; transport: ReturnType<typeof memTransport> } {
   const transport = memTransport();
   const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
@@ -189,6 +193,218 @@ test("a malformed claim payload is rejected without touching the registry (advis
   }
 });
 
+test("a resync snapshot frame REPLACES an instance's claims — a RELEASE lost during an outage no longer strands the job", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-a", "8421"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420", "8421"]);
+
+    // The hub missed the `release` for 8420 during an outage. On reconnect the supervisor restates its
+    // authoritative snapshot: wk-a now owns only 8421. The non-re-asserted 8420 is dropped.
+    peer.feed(resyncFrame("wk-a", ["8421"]));
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8421"], "the stranded claim was dropped on resync");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a resync snapshot does NOT blank a jobKey that moved to another instance", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-b", "8420")); // 8420 moved to wk-b
+    await flush();
+
+    // wk-a's authoritative resync no longer mentions 8420 — and must not blank the live owner wk-b.
+    peer.feed(resyncFrame("wk-a", []));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-b"), ["8420"], "the current owner's claim survives");
+    assertEquals(reg.ownerOf("8420"), "wk-b");
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a supervisor that never sends a resync snapshot keeps today's additive claim behaviour", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    // Only per-job claims, no snapshot frame — a claim is never dropped except by an explicit release.
+    peer.feed(claimFrame("wk-a", "8420"));
+    peer.feed(claimFrame("wk-a", "8421"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420", "8421"], "additive — neither claim is dropped");
+    assertEquals(reg.count(), 2);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a resync snapshot with a non-string instance is ignored (advisory, connection kept)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // A malformed snapshot (no instance) is rejected without touching the registry.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { jobKeys: ["8421"] } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the registry was untouched by the malformed snapshot");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot frame carrying BOTH jobKeys and a malformed jobKey is rejected — the snapshot branch never bypasses validation", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // The bypass the reviewer flagged: `jobKeys` present routed the frame straight to replaceInstance,
+    // so a smuggled empty `jobKey` was never validated. The union validator rejects it.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKey: "", jobKeys: ["8421"] } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed both-fields frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a frame with a valid jobKey but a PRESENT malformed jobKeys is rejected — a broken snapshot can't launder as a per-job claim", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // The reviewer's case: `jobKeys` is PRESENT but malformed ("invalid"), while `jobKey` is valid.
+    // Presence — not validity — selects the snapshot variant, so a broken `jobKeys` must be rejected,
+    // never treated as absent and accepted as a bare per-job claim that mutates ownership.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKey: "8421", jobKeys: "invalid" } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed-snapshot frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot frame with a PRESENT malformed jobKeys array is rejected as a broken snapshot (presence is the discriminant)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    // `jobKeys` present but not a string array → a broken snapshot; it is rejected outright, never
+    // mistaken for a per-job claim. (No `jobKey` here either, but presence alone is enough to reject.)
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: "8421" } });
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the malformed frame touched nothing");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("an EMPTY snapshot is a valid authoritative resync — the supervisor asserting it now owns nothing", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+
+    // The producer emits one snapshot per instance INCLUDING empty sets — an empty `jobKeys` is the
+    // meaningful "owns nothing now" resync, not a malformed frame.
+    peer.feed(resyncFrame("wk-a", []));
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), [], "the empty snapshot cleared the instance's claims");
+    assertEquals(reg.count(), 0);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a snapshot whose jobKeys contains an EMPTY-STRING element is rejected — it can't masquerade as an 'owns nothing' resync and clear real claims", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "host-supervisor");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+
+    // The empty-ARRAY resync is valid ("owns nothing"), but a present `jobKeys` with an empty-STRING
+    // element is a BROKEN snapshot — `replaceInstance` silently skips empty keys, so `[""]` would
+    // otherwise masquerade as an authoritative empty snapshot and clear every real claim. It is held
+    // to the same non-empty bar as the per-job `jobKey` and rejected outright, touching nothing.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: [""] } });
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the sole-empty-string snapshot did not clear the real claim");
+    assertEquals(reg.count(), 1);
+
+    // A MIXED array with one empty element is equally a broken snapshot — fail closed, not partial.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a", jobKeys: ["8421", ""] } });
+    await flush();
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the mixed empty-element snapshot touched nothing — not even the valid element");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
 test("teardown clears the singleton", () => {
   mountClaim();
   assert(currentClaimRegistry() !== undefined);

package/app/agentic/families/claim.family.ts

@@ -13,7 +13,11 @@
 // the frame, NOT the connection id (`conn.id`); that is what lets one per-host supervisor multiplex N
 // distinct workers' ownership over a single connection. On a reconnect the supervisor re-`register`s
 // every worker and re-`claim`s every active jobKey, and the (idempotent) claim handler rebuilds the
-// registry from that resync.
+// registry from that resync. A supervisor may additionally close its resync with an AUTHORITATIVE
+// snapshot frame (`claim` carrying the full `jobKeys` set for an instance, issue #893 — the
+// `claim.snapshot` wire contract in `app/contracts.ts`): the handler then `replaceInstance`s, dropping
+// any claim the supervisor did NOT re-assert — so a `release` lost during a hub outage no longer
+// strands the job. A supervisor that omits the snapshot keeps the pre-#893 additive behaviour.
 //
 // Liveness: a worker holding a claim reads "working" even with ZERO transcript — visibility no longer
 // depends on terminal bytes landing/correlating. A bounded-memory maintenance tick reconciles the
@@ -46,6 +50,81 @@ function readString(value: unknown, key: string): string | undefined {
   return typeof field === "string" ? field : undefined;
 }
 
+/**
+ * The classification of a `claim` frame's `jobKeys` field. Its PRESENCE — NOT its validity — is the
+ * discriminant that tells an authoritative resync snapshot (`{ instance, jobKeys }`, issue #893) apart
+ * from a classic per-job claim (`{ instance, jobKey }`). So a PRESENT-but-malformed `jobKeys` is a
+ * BROKEN snapshot and must be rejected; it must never be treated as "absent" and laundered through the
+ * per-job validator (which tolerates the extra field), because that would let a malformed snapshot
+ * field mutate ownership on a frame that merely carries a valid `jobKey`.
+ */
+type JobKeysField =
+  | { present: false }
+  | { present: true; malformed: true }
+  | { present: true; malformed: false; jobKeys: readonly string[] };
+
+/**
+ * Classify a frame payload's `jobKeys` field. It rides the existing `claim` wire family as a
+ * forward-compatible enrichment — the protocol's structural validators tolerate the extra field, so an
+ * older hub ignores it and keeps additive behaviour. This is the SINGLE source that both the validator
+ * and the handler branch on, so the "present ⇒ snapshot" discriminant cannot drift between them.
+ */
+function readJobKeysField(value: unknown): JobKeysField {
+  if (!value || typeof value !== "object") return { present: false };
+  if (!Object.hasOwn(value, "jobKeys")) return { present: false };
+  const field = Object.getOwnPropertyDescriptor(value, "jobKeys")?.value;
+  // Each element must be a NON-EMPTY string — the canonical per-job validator requires a non-empty
+  // `jobKey`, so a snapshot entry is held to the same bar. An empty-string element is NOT a benign
+  // "owns nothing" signal (that is the empty ARRAY): `replaceInstance` silently skips empty keys, so
+  // `{ instance, jobKeys: [""] }` would otherwise masquerade as an authoritative empty snapshot and
+  // clear every real claim. Fail closed — a present `jobKeys` with any empty element is a broken
+  // snapshot and is rejected, never laundered through the per-job validator.
+  if (!Array.isArray(field) || !field.every((k) => typeof k === "string" && k !== "")) {
+    return { present: true, malformed: true };
+  }
+  return { present: true, malformed: false, jobKeys: field };
+}
+
+/**
+ * The `claim` family carries TWO payload variants (issue #893 — the `claim.snapshot` wire contract in
+ * `app/contracts.ts`): the classic per-job claim `{ instance, jobKey }` and the authoritative resync
+ * snapshot `{ instance, jobKeys }`. The pinned `@nanobpm/agentic` validator predates the snapshot
+ * variant and REQUIRES a non-empty `jobKey`, so it cannot validate the union — routing a snapshot
+ * through `validatePayload` would reject the very frame that closes a resync. Validate the union
+ * locally instead: a payload is well-formed iff it is EITHER a valid snapshot (non-empty `instance`
+ * plus a `jobKeys` array of NON-EMPTY strings — an EMPTY array is the meaningful "owns nothing now"
+ * resync) OR a valid per-job claim per the canonical validator. This is a UNION with a VALIDATED
+ * OVERLAP, not an exclusive-or: a frame carrying BOTH fields is accepted, but only when BOTH halves
+ * validate — it is validated as a snapshot AND must still pass the per-job validator, so a malformed
+ * `jobKey` can no longer smuggle past on a snapshot frame.
+ */
+function validateClaimPayload(payload: unknown): { ok: boolean; codes: string[] } {
+  const field = readJobKeysField(payload);
+  if (field.present) {
+    // PRESENCE selects the snapshot variant unconditionally. A present-but-malformed `jobKeys` is a
+    // broken snapshot — reject it here rather than letting it fall through to the per-job validator,
+    // which would accept it (extra fields tolerated) on any frame that also carries a valid `jobKey`.
+    if (field.malformed) {
+      return { ok: false, codes: ["bad-jobKeys"] };
+    }
+    const instance = readString(payload, "instance");
+    if (instance) {
+      // A frame carrying BOTH variants must satisfy both — the snapshot branch must never launder a
+      // malformed per-job field past validation. (readJobKeysField defined the value as an object.)
+      if (typeof payload === "object" && payload !== null && !Object.hasOwn(payload, "jobKey")) {
+        return { ok: true, codes: [] };
+      }
+      const both = validatePayload(CLAIM_FAMILY, payload);
+      return both.ok ? { ok: true, codes: [] } : { ok: false, codes: both.errors.map((e) => e.code) };
+    }
+    // A snapshot-shaped payload with a missing/empty instance is NOT a valid per-job claim either
+    // (jobKey is absent) — report the snapshot violation precisely.
+    return { ok: false, codes: ["bad-instance"] };
+  }
+  const result = validatePayload(CLAIM_FAMILY, payload);
+  return result.ok ? { ok: true, codes: [] } : { ok: false, codes: result.errors.map((e) => e.code) };
+}
+
 interface MountState {
   readonly registry: ClaimRegistry;
   timer: ReturnType<typeof setTimeout> | undefined;
@@ -72,9 +151,26 @@ export const family: AgenticFamily = {
     // malformed payload is rejected before it touches the registry (advisory: logged, connection
     // kept). Both mutations are idempotent, matching the wire contract.
     ctx.hub.registerFamilyHandler(CLAIM_FAMILY, (frame: Frame, _conn: HubConnection) => {
-      const result = validatePayload(CLAIM_FAMILY, frame.payload);
-      if (!result.ok) {
-        ctx.log.warn("agentic claim: malformed payload", { errors: result.errors.map((e) => e.code) });
+      // An authoritative resync SNAPSHOT (`{ instance, jobKeys }`, issue #893): the reconnecting
+      // supervisor restates the full current ownership for one instance and its view WINS —
+      // `replaceInstance` drops every claim it did NOT re-assert (so a `release` lost during a hub
+      // outage no longer strands the job). A supervisor that never sends it keeps additive behaviour.
+      // EVERY claim frame is validated first — as the snapshot/per-job union (a both-fields frame is
+      // accepted only when both halves validate) — so the snapshot
+      // branch never bypasses validation (a malformed frame is dropped before it touches the
+      // registry, exactly like a malformed per-job claim).
+      const valid = validateClaimPayload(frame.payload);
+      if (!valid.ok) {
+        ctx.log.warn("agentic claim: malformed payload", { errors: valid.codes });
+        return;
+      }
+      const field = readJobKeysField(frame.payload);
+      if (field.present && !field.malformed) {
+        // Validated above, so the instance is present and non-empty (and a malformed `jobKeys` was
+        // already rejected, so `field.present && field.malformed` can never reach the registry).
+        const instance = readString(frame.payload, "instance");
+        if (!instance) return;
+        registry.replaceInstance(instance, field.jobKeys);
         return;
       }
       const instance = readString(frame.payload, "instance");

package/app/contracts.ts

@@ -443,6 +443,14 @@ export const WIRE_CONTRACTS = {
       "Op-tagged relay control frame a worker terminal chunk producer emits and the hub consumes. The op-tagged shape superseded the legacy positional `{stream, offset, chunk}` frame (nano-ide #234/#236); a producer must emit the op-tagged shape or the hub rejects it as `malformed relay message payload`.",
     shape: '{ op: "produce", incarnation: number, stream: string, offset: number, chunk: string }',
   },
+  "claim.snapshot": {
+    category: "wire",
+    name: "claim.snapshot",
+    owner: "app/agentic/families/claim.family.ts (hub consumer); nano-supervisor#63 (producer)",
+    semantics:
+      "Authoritative reconnect-resync snapshot riding the EXISTING `claim` wire family (wire code 8, nano-ide#542) as a forward-compatible enrichment — the issue #893 resync boundary. A reconnecting supervisor closes its per-instance resync with ONE snapshot frame carrying the full current jobKey set for that instance; the hub validates it (as a snapshot/per-job UNION with a VALIDATED OVERLAP, not an exclusive-or — a both-fields frame is accepted only when BOTH halves validate; the pinned `@nanobpm/agentic` validator predates this variant and requires a non-empty `jobKey`, so the union is validated hub-side until nano-ide versions the shape into the canonical protocol payloads) and calls `ClaimRegistry.replaceInstance(instance, jobKeys)`, dropping every claim the supervisor did NOT re-assert so a `release` lost during a hub outage no longer strands the job. `jobKeys` MAY be the empty ARRAY (the meaningful 'owns nothing now' resync — this is why the producer emits one snapshot per instance INCLUDING empty sets), but every ELEMENT must be a NON-EMPTY string (held to the same bar as the per-job `jobKey`); a present `jobKeys` that is a non-array, has a non-string element, or has an empty-string element is a BROKEN snapshot and is rejected (fail closed), never laundered through the per-job validator. The frame's explicit `instance` is the owning worker, never the connection id. Compatibility: the protocol's structural validators tolerate the extra field, so an older hub ignores it and keeps additive behaviour; a supervisor that never sends a snapshot keeps the pre-#893 additive behaviour. Distinct from the classic per-job claim `{ instance, jobKey }` (the `@nanobpm/agentic` `ClaimPayload`) — consume this ONE shape for the resync boundary, do not re-declare a synonym.",
+    shape: '{ instance: string, jobKeys: string[] } — a `claim` (wire code 8) frame whose `jobKeys` array PRESENCE is the discriminant; a UNION with the per-job `{ instance: string, jobKey: string }` (a both-fields frame is accepted only when both halves validate, not an exclusive-or)',
+  },
   "io.nanobpm.agentTask.repository": {
     category: "wire",
     name: "io.nanobpm.agentTask.repository",