@cotal-ai/core 0.85.0 → 0.87.0

package/dist/endpoint-invoke.js

@@ -1,171 +1,55 @@
-/**
- * The GENERIC caller path: describe an endpoint, fetch its
- * registered contracts from the §13.7 content store, recompile the digest-matching validators,
- * and invoke a named command — WITHOUT the caller compiling the endpoint's schemas ahead of time.
- * This is what a `cotal describe`/`cotal invoke` CLI and every migrated control consumer ride, so
- * a consumer no longer hand-imports the manager's contract module.
- *
- * The trust chain is the §13.7 one, end to end:
- *  - `describe` (the reserved, authorization-scoped command every endpoint serves) answers the
- *    caller's VISIBLE command set + the registered CLUSTER closure digests;
- *  - each cluster document is fetched from the store at its closure digest and VERIFIED
- *    (two-stage manifest→root, content-addressed) — the command's input/output CLOSURE digests
- *    come from those verified bytes, never a caller assertion;
- *  - each schema closure is fetched + PROFILE-recompiled; the recompiled contract's closureDigest
- *    MUST equal the registered digest (a store that served the wrong bytes fails here);
- *  - the invoke pins those digests, so the responder's digest-bound serve boundary honors exactly
- *    the schema the caller validated against.
- */
-import { randomBytes, randomUUID } from "node:crypto";
-import { PermissionViolationError } from "@nats-io/transport-node";
-import { openPublishDenialWatch } from "./endpoint-publish-denial.js";
 import { jetstreamManager } from "@nats-io/jetstream";
-import { EpEnvelopeError, EP_UNBOUND_RESPONDER, EP_UNANSWERED, renderLifecycleBlocked, lifecycleBlockedFrom, replyRefusedBeforeEffect, replyTargetUnmapped, unansweredRequest } from "./endpoint-envelope.js";
+import { EpEnvelopeError, replyRefusedBeforeEffect, replyTargetUnmapped } from "./endpoint-envelope.js";
 import { compileContract } from "./schema-profile.js";
-import { parseGoalResultFact, } from "./endpoint-action.js";
-import { contractStoreContext, fetchContractClosure, contractRefToHex, contractArtifactDigestHex, } from "./endpoint-contract-store.js";
+import { parseGoalResultFact } from "./endpoint-action.js";
+import { submitAndFollowGoalWith } from "./endpoint-goal-follow.js";
+import { contractStoreContext, fetchContractClosure, contractRefToHex, contractArtifactDigestHex } from "./endpoint-contract-store.js";
 import { parseClusterDocument } from "./endpoint-cluster.js";
-import { epCall, epScatterService } from "./endpoint-verbs.js";
-import { epGoalProgressGrantRow } from "./endpoint-grants.js";
-import { epRequestSubject, epCallerReplyFilter, epPlaneTokens, parseEpSubject } from "./endpoint-subjects.js";
-import { parseEndpointReply } from "./endpoint-envelope.js";
-const dec = new TextDecoder(), enc = new TextEncoder();
-const nonce = () => randomBytes(24).toString("base64url");
-/** A describe is the reserved read-only discovery bootstrap, so an unanswered request may be
- *  re-published within its ORIGINAL deadline. Core NATS does not retain a request sent before a
- *  responder subscribes; without this bounded retry, a responder that registers one moment later
- *  is invisible until the caller pays the whole deadline. Commands are never retried here. */
-const DESCRIBE_RETRY_MS = 250;
-/** Format a caught value on a path that cannot afford to throw (timer/callback). A
- *  poisoned `Error.message` getter or `toString` must not escape the catch; the
- *  fallback is the detail, never a reason to skip the rejection. */
-function caughtText(e, fallback) {
-    try {
-        return e instanceof Error ? e.message : String(e);
-    }
-    catch {
-        return fallback;
-    }
-}
-/** Delivery margin above an action owner's accepted readiness budget. Spawn's established generic
- *  invariant was 40s client > 30s manager; preserve that measured 10s separation when a connector
- *  declares a different budget instead of inventing a second timeout policy. */
-const GOAL_FOLLOW_MARGIN_MS = 10_000;
+import { epScatterService } from "./endpoint-verbs.js";
+import { BIND_SPLIT_REISSUES, dec, describeEndpoint, invokeCommand } from "./endpoint-caller.js";
+export { BIND_SPLIT_REISSUES, describeEndpoint, goalFollowRefusal, invokeCommand } from "./endpoint-caller.js";
 /**
- * The reserved `describe` command as a raw request/reply (§13.7: describe pins NO contract, so it
- * carries no `op` digests — {@link epCall} always stamps digests and the serve boundary rejects a
- * digest-bearing describe as `contract-mismatch`, so this is a purpose-built raw path). It
- * REQUEST-BINDS its reply exactly as {@link epCall}'s `parseAttributedReply` does (§13.2): the
- * responder grant `epResponderReplyPattern` spans EVERY caller suffix, so any live responder can
- * publish on the caller's rail at any nonce — acceptance therefore checks the reply SUBJECT's
- * endpoint + nonce AND the body's echoed request id, not just "first `{ok:true}` on the rail".
- * A reply that fails any of these is IGNORED (not rejected: an attacker racing a wrong-nonce reply
- * must not be able to fail an honest describe), and the wait continues to the deadline. A signal
- * that aborts with a `TimeoutError` ends the wait as that deadline would.
+ * {@link invokeCommand} with a SPEC 13.2 bind refusal repaired rather than surfaced.
+ *
+ * An unpinned handle binds the instance that answered its describe, and the invoke is a second,
+ * independent trip through the same class queue, so in a multi-instance space another member
+ * routinely receives it and refuses before dispatching. That refusal states the command did not
+ * run ({@link replyRefusedBeforeEffect}), so re-resolving and re-issuing is a first attempt and is
+ * safe for any command, mutations included. A targeted call that reaches a member holding no
+ * mapping for its target ({@link replyTargetUnmapped}) is re-issued the same way, because with an
+ * instance-local resolver only the member hosting the target can serve it. The re-issue repeats
+ * until a member serves the call or {@link BIND_SPLIT_REISSUES} runs out, and then the last refusal
+ * surfaces unchanged, or the last no-mapping refusal when there was one.
+ *
+ * `reresolve` defaults to a fresh class resolve as the handle's caller; a caller that memoizes its
+ * handle passes one that drops the memo first, so later calls do not start from the refused bind.
+ * When it throws, the refusal surfaces, because it states that nothing ran, which the resolve
+ * failure raised in its place would lose.
+ *
+ * A pinned handle is never repaired: it names its instance, so a refusal from it is that instance
+ * answering about itself, and re-resolving on the class rail would reach another one.
  */
-export async function describeEndpoint(nc, space, endpoint, caller, opts = {}) {
-    opts.signal?.throwIfAborted();
-    const deadlineMs = opts.deadlineMs ?? 10_000;
-    const n = nonce();
-    const requestId = nonce();
-    // `--on <instance>`: PIN the describe to one instance's `inst` route so a multi-manager
-    // space resolves the exact instance addressed, not whichever wins the class `one` queue. Default =
-    // class anycast (mode "one"), unchanged for every existing caller.
-    const route = opts.instanceId !== undefined ? { mode: "inst", instanceId: opts.instanceId } : { mode: "one" };
-    const subject = epRequestSubject(space, { route, endpoint, command: "describe", caller, nonce: n });
-    // The plane this describe rides, recorded on the unanswered marker so a surface that renders a
-    // reachability verdict can scope it (SPEC 13.15: the legacy and versioned rails are disjoint subject spaces,
-    // an endpoint serves both, and a caller holds rows on one of them only). Silence on the versioned rail is
-    // therefore consistent with a responder that predates the versioned rail and serves `ep` alone.
-    const rail = epPlaneTokens(caller).join(".");
-    const env = {
-        v: 1, id: requestId, op: { endpoint, command: "describe" }, class: "ephemeral",
-        replyExpected: true, deadlineMs, from: { id: `${caller.owner}.${caller.actor}`, name: caller.actor },
-    };
-    let sub;
-    let timer;
-    let retryTimer;
-    let denialWatch;
-    let onAbort;
-    const startedAt = performance.now();
-    const unanswered = (ms) => new EpEnvelopeError("deadline-exceeded", `no describe reply from ${endpoint}${opts.instanceId !== undefined ? ` instance ${opts.instanceId}` : ""} within ${ms}ms on the ${rail} rail`, [{ kind: EP_UNANSWERED, endpoint, command: "describe", rail }]);
-    const cancelled = new Promise((_, reject) => {
-        onAbort = () => reject(opts.signal?.reason?.name === "TimeoutError"
-            ? unanswered(Math.round(performance.now() - startedAt))
-            : new EpEnvelopeError("unavailable", `describe(${endpoint}) observation cancelled`));
-        opts.signal?.addEventListener("abort", onAbort, { once: true });
-    });
-    try {
-        // REGISTER THE PERMISSION WATCH BEFORE THE PUBLISH IT IS WATCHING. See
-        // {@link openPublishDenialWatch}: a refused publish is otherwise indistinguishable
-        // from an unanswered describe.
-        denialWatch = openPublishDenialWatch(nc, subject, () => new EpEnvelopeError("permission-denied", `the describe for ${endpoint} was REFUSED BY THE BROKER, not unanswered: this caller's credential does not authorize publishing to "${subject}"${opts.instanceId !== undefined ? ` (the instance rail for ${opts.instanceId}: an instance-addressed call needs a credential minted with that instance, not a class-rail one)` : ""}. The responder may be perfectly healthy; the grant is what is missing (SPEC 13.2)`, undefined, "not-executed"), "describe");
-        const got = new Promise((resolve, reject) => {
-            sub = nc.subscribe(epCallerReplyFilter(space, caller), {
-                callback: (err, msg) => {
-                    if (err) {
-                        reject(new EpEnvelopeError("unavailable", `describe reply subscription failed: ${err.message}`));
-                        return;
-                    }
-                    // REQUEST-BIND off the reply SUBJECT first (§13.2): the responder triple + nonce are
-                    // broker-pinned by the serve publish grant. A reply for a DIFFERENT endpoint, or on a
-                    // nonce that is not the one we published (the rail is shared across our concurrent
-                    // requests, and a hostile responder can publish at any nonce), is NOT ours — ignore it
-                    // and keep waiting, never fail the honest describe on an injected reply.
-                    const parsed = parseEpSubject(msg.subject);
-                    if (!parsed || parsed.plane !== "reply" || parsed.endpoint !== endpoint || parsed.nonce !== n)
-                        return;
-                    // Then the body: it must parse as an EndpointReply and ECHO our request id on this
-                    // nonce-scoped rail (§13.3) — the second half of the confused-deputy binding.
-                    let reply;
-                    try {
-                        reply = parseEndpointReply(JSON.parse(dec.decode(msg.data)));
-                    }
-                    catch {
-                        return;
-                    } // a malformed body on our nonce is not a usable answer; wait for a valid one
-                    if (reply.id !== requestId)
-                        return;
-                    resolve({ body: reply, responder: { instanceId: parsed.instanceId, epoch: parsed.epoch } });
-                },
-            });
-            const request = enc.encode(JSON.stringify(env));
-            nc.publish(subject, request);
-            // The first publish may precede the responder's subscription during startup. Re-publish the
-            // SAME read-only describe under the SAME request binding until one answer wins or the original
-            // deadline expires; this neither extends the budget nor retries the command being resolved.
-            // `publish` throws synchronously after close/drain. A timer throw escapes the caller's promise
-            // and crashes the process, so make transport loss settle this describe instead.
-            retryTimer = setInterval(() => {
-                try {
-                    nc.publish(subject, request);
-                }
-                catch (e) {
-                    reject(new EpEnvelopeError("unavailable", `the describe retry for ${endpoint} could not publish: ${caughtText(e, "unknown publish failure")}`));
-                }
-            }, DESCRIBE_RETRY_MS);
-        });
-        const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(unanswered(deadlineMs)), deadlineMs); });
-        const { body: reply, responder } = await Promise.race([got, timeout, denialWatch.denied, cancelled]);
-        if (reply.ok !== true) {
-            // A responder ANSWERED with a refusal: it is rethrown under the responder's own code (which
-            // may be `unavailable`) and deliberately without the EP_UNANSWERED marker the deadline above
-            // carries, so a consumer keyed on that marker never reads an answering responder as absent.
-            const e = reply.error;
-            throw new EpEnvelopeError(e?.code ?? "unavailable", `describe(${endpoint}) failed: ${e?.message ?? "unknown"}`);
+export async function invokeRepairingSplit(nc, space, service, command, args, opts, reresolve = () => resolveService(nc, space, service.endpoint, service.caller, { deadlineMs: opts.deadlineMs ?? 10_000, ...(opts.signal ? { signal: opts.signal } : {}) })) {
+    let handle = service;
+    // A member that looked the target up and found no mapping says more about it than a bind refusal,
+    // which says nothing, so a call that runs out of re-issues surfaces the latest such refusal.
+    let unmapped;
+    for (let reissues = 0;; reissues += 1) {
+        const r = await invokeCommand(nc, space, handle, command, args, opts);
+        if (replyTargetUnmapped(r.reply.error))
+            unmapped = r;
+        else if (r.reply.ok !== false || !replyRefusedBeforeEffect(r.reply.error))
+            return r;
+        if (handle.pinnedInstanceId !== undefined)
+            return r;
+        if (reissues === BIND_SPLIT_REISSUES)
+            return unmapped ?? r;
+        try {
+            handle = await reresolve();
+        }
+        catch {
+            return unmapped ?? r;
         }
-        return { answer: reply.data, responder };
-    }
-    finally {
-        sub?.unsubscribe();
-        if (timer !== undefined)
-            clearTimeout(timer);
-        if (retryTimer !== undefined)
-            clearInterval(retryTimer);
-        if (onAbort)
-            opts.signal?.removeEventListener("abort", onAbort);
-        // Release on EVERY exit, success included. See {@link openPublishDenialWatch}.
-        denialWatch?.release();
     }
 }
 /** Fetch + verify ONE cluster document from the store at its closure digest (two-stage §13.7:
@@ -234,7 +118,8 @@ function extractSchemaRefs(bytes) {
  *  so is this one. High enough that real surfaces overlap freely, low enough to stay a bound. */
 const RESOLVE_MAX_INFLIGHT_READS = 32;
 /** Run `work` over `items` with at most `limit` in flight, preserving RESULT ORDER (the resolved
- *  surface must not depend on read timing). Rejects like `Promise.all`: the first failure wins. */
+ *  surface must not depend on read timing). Rejects like `Promise.all`: the first failure wins,
+ *  and no item starts after it. */
 async function pooled(items, limit, work) {
     const out = new Array(items.length);
     let next = 0;
@@ -243,7 +128,15 @@ async function pooled(items, limit, work) {
             const i = next++;
             if (i >= items.length)
                 return;
-            out[i] = await work(items[i]);
+            try {
+                out[i] = await work(items[i]);
+            }
+            catch (e) {
+                // This failure rejects the pool, so a later item would spend store reads on a result
+                // nobody reads. Items already in flight finish on their own.
+                next = items.length;
+                throw e;
+            }
         }
     };
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
@@ -311,447 +204,9 @@ export async function resolveService(nc, space, endpoint, caller, opts = {}) {
         commands.set(rc.command, rc);
     return { endpoint: answer.descriptor.endpoint, owner: answer.descriptor.owner, caller, responder, commands, ...(opts.instanceId !== undefined ? { pinnedInstanceId: opts.instanceId } : {}) };
 }
-/** How many times a call is re-issued after a `not-executed` bind refusal. Every
- *  re-issue is a first attempt, so this is a loop guard and not a duplication guard. Each attempt
- *  splits with probability (m-1)/m in a space of m managers, so seventeen attempts leave a
- *  three-manager space about 1 in 1000 where the unrepaired call failed 2 in 3 (#398). An attempt
- *  costs an answered describe and invoke, never an elapsed deadline. */
-export const BIND_SPLIT_REISSUES = 16;
-/**
- * INVOKE one named command on a resolved service: validate nothing here (the compiled input
- * contract in {@link epCall}'s request builder gates args before publish, and the responder's
- * digest-bound boundary re-validates), route on the `one` rail, return the attributed reply. A
- * command absent from the resolved surface is `not-found` (the caller cannot see it, or it does
- * not exist); a targeted command needs its `target`.
- *
- * Currency: `opts.currentEpoch` (e.g. the registry-read `serviceEpochReader`) when supplied;
- * otherwise the DESCRIBE-BOUND default - accept exactly the incarnation that answered this
- * service's resolve (its broker-authenticated `instanceId`+`epoch` off the describe reply
- * subject) and refuse `failed-precondition` when a DIFFERENT instance wins the `one` queue
- * (a superseded-or-split responder; re-resolve to adopt a legitimate successor). The bind needs
- * no registry read grant, and it is strictly stronger than no check: two live instances of a
- * single-instance endpoint can never both pass one resolved handle.
- */
-export async function invokeCommand(nc, space, service, command, args, opts) {
-    const resolved = service.commands.get(command);
-    if (resolved === undefined)
-        throw new EpEnvelopeError("not-found", `command "${command}" is not in ${service.endpoint}'s visible surface; describe lists ${[...service.commands.keys()].sort().join(", ") || "(none)"}`);
-    if (resolved.targeted && opts.target === undefined)
-        throw new EpEnvelopeError("bad-request", `command "${command}" is targeted (modes: ${resolved.modes.join(", ")}); an invoke needs its target`);
-    if (!resolved.targeted && opts.target !== undefined)
-        throw new EpEnvelopeError("bad-request", `command "${command}" is untargeted; an invoke must not carry a target`);
-    const caller = service.caller;
-    // "No args" marshals to the CONTRACT's canonical empty form: absent args ride as null on the
-    // wire, so when this command's input rejects null but accepts the empty object (e.g. an
-    // all-optional `{type:"object"}` input like despawn's), send `{}` — that IS the caller's
-    // intent in that contract's vocabulary (a targeted CLI stop has nothing left after the alias
-    // becomes the target block). Contract-derived, never a guess: an input that requires fields
-    // accepts neither form and still refuses loud at the pre-publish validation below.
-    let sendArgs = args;
-    if (sendArgs === undefined && !resolved.contract.input.validate(null) && resolved.contract.input.validate({}))
-        sendArgs = {};
-    const describeBound = (instanceId) => {
-        if (instanceId !== service.responder.instanceId) {
-            // The refusal is unchanged; what it SAYS is not. One message used to cover two situations
-            // that call for opposite responses, and it described only the rarer one.
-            //
-            // PINNED: the caller named an instance and a different one answered. Genuinely wrong.
-            //
-            // UNPINNED: the caller addressed the CLASS. The describe and the invoke are two independent
-            // trips through the same anycast queue, so in a multi-instance space they routinely land on
-            // different instances and this fires on an ordinary, correct request - not on a supersession.
-            // Calling that "superseded-or-split" sends the reader hunting a restart that never happened.
-            // The old text's remedy is also not executable by the surfaces that print it most (`stop`,
-            // `despawn` and `attach` have no adopt path and no pin), so it advised an action the caller
-            // could not take. Say which case this is, and stop asserting a cause that is usually wrong.
-            // The marker, not the prose, is what stops an automatic re-invoke: reaching here means a
-            // responder ANSWERED (executed or refused; the reply does not say which), so a retry is a
-            // second attempt that may duplicate an effect rather than a repair. Callers that recover
-            // from `failed-precondition` by re-resolving must consult `respondedButUnbound`.
-            // The remedy is stated in core vocabulary (address one instance), never as a CLI flag: core
-            // cannot know whether its caller has one, and most `invokeService` callers (a connector's
-            // tools, a manifest deploy) do not. The CLI names its own flag when it renders this.
-            throw new EpEnvelopeError("failed-precondition", service.pinnedInstanceId !== undefined
-                ? `the ${service.endpoint} instance ${instanceId} answered but this handle is PINNED to ${service.pinnedInstanceId}; a pinned call names its instance and never accepts another. ${instanceId} did receive and answer the request, so if "${command}" mutates, that effect may already have landed - verify before re-issuing (SPEC 13.2)`
-                : `the ${service.endpoint} instance ${instanceId} won the class queue but this UNPINNED handle resolved against ${service.responder.instanceId}; the describe and the invoke are separate trips through the same queue, so in a multi-instance space this is an ordinary split and not necessarily a supersession - the handle cannot currently adopt a different winner. THIS SAYS NOTHING ABOUT WHETHER THE COMMAND RAN: ${instanceId} received the request and answered it, possibly after this error was raised. For a read that is harmless and re-issuing is safe; if "${command}" mutates, verify the outcome ('ps'/'inspect'/roster) before re-issuing, because a retry that assumes failure duplicates the effect. A call that addresses one instance does not split (SPEC 13.2)`, [{ kind: EP_UNBOUND_RESPONDER, endpoint: service.endpoint, command, answeredBy: instanceId, boundTo: service.responder.instanceId, pinned: service.pinnedInstanceId !== undefined }]);
-        }
-        return service.responder.epoch;
-    };
-    // `--on`: a PINNED service routes to its exact instance's `inst` rail (the same instance the
-    // describe resolved to, at its resolved epoch), never the class `one` queue — so the command reaches
-    // the addressed manager in a multi-manager space. Unpinned ⇒ class anycast `one` (unchanged). The
-    // describeBound currency check still holds: an inst-routed reply carries that instance's id.
-    const route = service.pinnedInstanceId !== undefined
-        ? { mode: "inst", instanceId: service.pinnedInstanceId, epoch: service.responder.epoch }
-        : { mode: "one" };
-    // The bind travels WITH the request, so the responder can refuse before running the command
-    // rather than leaving `describeBound` to report the split afterwards. It is sent exactly when
-    // this handle's own resolve is the currency reference — that is the caller saying "this
-    // incarnation or none", and it is the same population the check below already refuses. A caller
-    // that supplied its own `currentEpoch` is asking a REGISTRY whether the answerer is current, and
-    // deliberately accepts any current member; binding it would refuse calls that succeed today.
-    const bind = opts.currentEpoch === undefined
-        ? { instanceId: service.pinnedInstanceId ?? service.responder.instanceId, epoch: service.responder.epoch }
-        : undefined;
-    return epCall(nc, space, route, {
-        endpoint: service.endpoint, command, contract: resolved.contract, caller,
-        ...(sendArgs !== undefined ? { args: sendArgs } : {}),
-        ...(opts.target ? { target: opts.target } : {}),
-        ...(bind !== undefined ? { bind } : {}),
-        ...(opts.id !== undefined ? { id: opts.id } : {}),
-    }, {
-        deadlineMs: opts.deadlineMs ?? 10_000,
-        signal: opts.signal,
-        currentEpoch: opts.currentEpoch ?? describeBound,
-        // What the currency hook returns decides how a stale-epoch refusal is worded and marked: the
-        // describe-bound default is this handle's own bind (a responder ahead of it is a successor and
-        // the handle is the stale side); a caller-supplied hook is a registry read by epCall's contract.
-        currencyReference: opts.currentEpoch ? "registry" : "bind",
-    });
-}
-/** The refusal a goal-following call meets on a handle whose endpoint serves no `goal-result`: an
- *  accepted goal could never be read back to its terminal (SPEC 13.6), so nothing is submitted.
- *  `undefined` when the handle can follow. */
-export function goalFollowRefusal(service) {
-    if (service.commands.has("goal-result"))
-        return undefined;
-    return {
-        reply: { v: 1, id: randomUUID(), ok: false, error: {
-                code: "failed-precondition", outcome: "not-executed",
-                message: `endpoint "${service.endpoint}" does not support "goal-result"; upgrade manager to enable durable goal following (SPEC 13.6)`,
-            } },
-        responder: { endpoint: service.endpoint, instanceId: service.responder.instanceId, epoch: service.responder.epoch },
-    };
-}
-/**
- * {@link invokeCommand} with a SPEC 13.2 bind refusal repaired rather than surfaced.
- *
- * An unpinned handle binds the instance that answered its describe, and the invoke is a second,
- * independent trip through the same class queue, so in a multi-instance space another member
- * routinely receives it and refuses before dispatching. That refusal states the command did not
- * run ({@link replyRefusedBeforeEffect}), so re-resolving and re-issuing is a first attempt and is
- * safe for any command, mutations included. A targeted call that reaches a member holding no
- * mapping for its target ({@link replyTargetUnmapped}) is re-issued the same way, because with an
- * instance-local resolver only the member hosting the target can serve it. The re-issue repeats
- * until a member serves the call or {@link BIND_SPLIT_REISSUES} runs out, and then the last refusal
- * surfaces unchanged, or the last no-mapping refusal when there was one.
- *
- * `reresolve` defaults to a fresh class resolve as the handle's caller; a caller that memoizes its
- * handle passes one that drops the memo first, so later calls do not start from the refused bind.
- * When it throws, the refusal surfaces, because it states that nothing ran, which the resolve
- * failure raised in its place would lose.
- *
- * A pinned handle is never repaired: it names its instance, so a refusal from it is that instance
- * answering about itself, and re-resolving on the class rail would reach another one.
- */
-export async function invokeRepairingSplit(nc, space, service, command, args, opts, reresolve = () => resolveService(nc, space, service.endpoint, service.caller, { deadlineMs: opts.deadlineMs ?? 10_000, ...(opts.signal ? { signal: opts.signal } : {}) })) {
-    let handle = service;
-    // A member that looked the target up and found no mapping says more about it than a bind refusal,
-    // which says nothing, so a call that runs out of re-issues surfaces the latest such refusal.
-    let unmapped;
-    for (let reissues = 0;; reissues += 1) {
-        const r = await invokeCommand(nc, space, handle, command, args, opts);
-        if (replyTargetUnmapped(r.reply.error))
-            unmapped = r;
-        else if (r.reply.ok !== false || !replyRefusedBeforeEffect(r.reply.error))
-            return r;
-        if (handle.pinnedInstanceId !== undefined)
-            return r;
-        if (reissues === BIND_SPLIT_REISSUES)
-            return unmapped ?? r;
-        try {
-            handle = await reresolve();
-        }
-        catch {
-            return unmapped ?? r;
-        }
-    }
-}
-/** Subscribe before a single submission, then observe its accepted goal through live progress and
- *  mediated canonical reads. Local failures before an attributed reply throw; they never invent a
- *  responder. Once accepted, observation failures retain that responder and never authorize retry.
- *  A terminal other than `succeeded` keeps the acceptance as its data, so the caller still holds the
- *  allocated identity of a goal that settled `uncertain` and may yet converge. */
-export async function submitAndFollowGoal(nc, space, endpoint, caller, deadlineMs, submit, opts) {
-    if (!Number.isSafeInteger(deadlineMs) || deadlineMs <= 0)
-        throw new EpEnvelopeError("bad-request", "goal following requires a positive integer deadline", undefined, "not-executed");
-    const acceptingCaller = { ...caller };
-    const terminals = new Map();
-    const progressSubject = epGoalProgressGrantRow(space, endpoint, acceptingCaller);
-    const work = new AbortController();
-    const timers = new Set();
-    let activeNc = nc;
-    let activeSub;
-    let generation = 0;
-    let unbindReconnect;
-    let completed = false;
-    let stopped = opts?.signal?.aborted === true;
-    let submitted = false;
-    let subError;
-    let observationError;
-    let wake;
-    let abortPhase;
-    let needsReconcile = false;
-    let reading = false;
-    let progressReady = false;
-    const aborted = new Promise((resolve) => { abortPhase = resolve; });
-    const onAbort = () => {
-        stopped = true;
-        work.abort();
-        abortPhase?.();
-        wake?.();
-    };
-    const phaseError = (code) => new EpEnvelopeError(code, submitted
-        ? "the goal submission was interrupted while in flight; its outcome is unknown. It may have been accepted or executed; do NOT retry without inspecting 'ps'/'inspect' first (SPEC 13.6)"
-        : "goal observation stopped or exceeded its deadline before submission; the manager request WAS NOT RUN", undefined, submitted ? "unknown" : "not-executed");
-    let deadline = Date.now() + deadlineMs;
-    const bounded = async (operation, until) => {
-        if (stopped || completed)
-            throw phaseError("unavailable");
-        const remaining = until - Date.now();
-        if (remaining <= 0)
-            throw phaseError("deadline-exceeded");
-        let timer;
-        try {
-            return await Promise.race([
-                operation(),
-                aborted.then(() => { throw phaseError("unavailable"); }),
-                new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(phaseError("deadline-exceeded")), Math.min(remaining, 2_147_483_647));
-                    timers.add(timer);
-                }),
-            ]);
-        }
-        finally {
-            if (timer !== undefined) {
-                clearTimeout(timer);
-                timers.delete(timer);
-            }
-        }
-    };
-    const subscribe = (next) => {
-        if (completed || stopped)
-            return;
-        const mine = ++generation;
-        activeSub?.unsubscribe();
-        activeNc = next;
-        progressReady = false;
-        subError = undefined;
-        activeSub = next.subscribe(progressSubject, {
-            callback: (err, msg) => {
-                if (completed || stopped || mine !== generation)
-                    return;
-                if (err) {
-                    subError ??= err;
-                    wake?.();
-                    return;
-                }
-                let ev;
-                try {
-                    ev = JSON.parse(dec.decode(msg.data));
-                }
-                catch {
-                    return;
-                }
-                if (ev?.phase === "terminal" && typeof ev.goalId === "string") {
-                    terminals.set(ev.goalId, { state: String(ev.state), data: ev.data });
-                    wake?.();
-                }
-            },
-        });
-    };
-    const replaceConnection = (next) => {
-        if (completed || stopped)
-            return;
-        try {
-            subscribe(next);
-        }
-        catch (err) {
-            subError = err instanceof Error ? err : new Error(String(err));
-            wake?.();
-            return;
-        }
-        const mine = generation;
-        void bounded(() => next.flush(), deadline).then(() => {
-            if (completed || stopped || mine !== generation)
-                return;
-            progressReady = true;
-            needsReconcile = true;
-            wake?.();
-        }, (err) => {
-            if (completed || stopped || mine !== generation)
-                return;
-            subError = err instanceof Error ? err : new Error(String(err));
-            wake?.();
-        });
-    };
-    try {
-        opts?.signal?.addEventListener("abort", onAbort, { once: true });
-        if (stopped)
-            throw phaseError("unavailable");
-        if (opts?.prepare) {
-            // The deadline first aborts the prepare's signal, so a describe the prepare started after other
-            // steps reports that it drew no reply. A prepare that ignores its signal is cut off a turn later.
-            let timer;
-            try {
-                await Promise.race([opts.prepare(work.signal, deadline), aborted, new Promise((resolve) => {
-                        timer = setTimeout(() => {
-                            work.abort(new DOMException("the goal follow's deadline passed", "TimeoutError"));
-                            setImmediate(resolve);
-                        }, Math.min(deadline - Date.now(), 2_147_483_647));
-                    })]);
-                work.signal.throwIfAborted();
-            }
-            catch (err) {
-                throw stopped ? phaseError("unavailable") : work.signal.aborted && !unansweredRequest(err) ? phaseError("deadline-exceeded") : err;
-            }
-            finally {
-                clearTimeout(timer);
-            }
-        }
-        subscribe(opts?.currentNc?.() ?? nc);
-        unbindReconnect = opts?.onReconnect?.(replaceConnection);
-        // A borrowed submit can publish on another connection. Confirm broker interest first,
-        // including a replacement that arrived while the first connection's flush was pending.
-        for (;;) {
-            const preparing = activeNc;
-            try {
-                await bounded(() => preparing.flush(), deadline);
-            }
-            catch (err) {
-                if (!stopped && preparing !== activeNc)
-                    continue;
-                throw err;
-            }
-            if (stopped)
-                throw phaseError("unavailable");
-            const current = opts?.currentNc?.();
-            if (current && current !== activeNc)
-                subscribe(current);
-            if (preparing === activeNc) {
-                progressReady = true;
-                break;
-            }
-        }
-        if (stopped)
-            throw phaseError("unavailable");
-        submitted = true;
-        let attributed;
-        try {
-            attributed = await bounded(() => submit(work.signal), deadline);
-        }
-        catch (err) {
-            if (stopped)
-                throw phaseError("unavailable");
-            if (err instanceof EpEnvelopeError && err.outcome === "not-executed")
-                throw err;
-            throw new EpEnvelopeError(err instanceof EpEnvelopeError ? err.code : "unavailable", `${err instanceof Error ? err.message : String(err)}; the submission outcome is unknown. It may have been accepted or executed; do NOT retry without inspecting 'ps'/'inspect' first (SPEC 13.6)`, undefined, "unknown");
-        }
-        if (attributed.reply.ok !== true)
-            return attributed;
-        const acceptance = attributed.reply.data;
-        const goalId = acceptance?.goalId;
-        if (typeof goalId !== "string")
-            return attributed;
-        const acceptedFingerprint = typeof acceptance?.fingerprint === "string" ? acceptance.fingerprint : undefined;
-        const readinessDeadlineMs = acceptance?.readinessDeadlineMs;
-        const followDeadlineMs = typeof readinessDeadlineMs === "number"
-            && Number.isSafeInteger(readinessDeadlineMs) && readinessDeadlineMs >= 0
-            ? Math.max(deadlineMs, readinessDeadlineMs + GOAL_FOLLOW_MARGIN_MS) : deadlineMs;
-        deadline = Date.now() + followDeadlineMs;
-        const reconcileAt = deadline - Math.min(deadlineMs, followDeadlineMs / 2);
-        let finalReadRequested = false;
-        const reconcile = async () => {
-            if (!opts?.reconcile || completed || stopped || reading || !progressReady)
-                return;
-            reading = true;
-            needsReconcile = false;
-            try {
-                const result = await opts.reconcile(goalId, attributed, {
-                    caller: { ...acceptingCaller }, signal: work.signal, deadlineMs: Math.max(1, deadline - Date.now()),
-                });
-                if (completed || stopped || Date.now() >= deadline)
-                    return;
-                if (!result || typeof result !== "object" || result.goalId !== goalId)
-                    throw new EpEnvelopeError("internal", "goal-result reply is malformed or names a different goal; it cannot authorize this outcome (SPEC 13.6)");
-                if (result.result !== undefined) {
-                    const ref = { endpoint, caller: acceptingCaller, goalId };
-                    const fact = parseGoalResultFact(result.result, "goal-result reply", ref);
-                    if (acceptedFingerprint !== undefined && fact.fingerprint !== acceptedFingerprint)
-                        throw new EpEnvelopeError("internal", "goal result fingerprint does not match the accepted goal (SPEC 13.6)");
-                    terminals.set(goalId, { state: fact.state, data: fact.data });
-                }
-            }
-            catch (err) {
-                if (!completed && !stopped && Date.now() < deadline)
-                    observationError = err instanceof Error ? err : new Error(String(err));
-            }
-            finally {
-                reading = false;
-                if (!completed && !stopped)
-                    wake?.();
-            }
-        };
-        const current = opts?.currentNc?.();
-        if (current && current !== activeNc && !stopped)
-            replaceConnection(current);
-        needsReconcile = true; // Also covers a terminal lost before the acceptance arrived.
-        while (!terminals.has(goalId) && !stopped && !observationError && !subError && Date.now() < deadline) {
-            if (!finalReadRequested && Date.now() >= reconcileAt) {
-                finalReadRequested = true;
-                needsReconcile = true;
-            }
-            if (needsReconcile && !reading)
-                void reconcile();
-            if (terminals.has(goalId) || stopped || observationError || subError)
-                break;
-            await new Promise((resolve) => {
-                const until = finalReadRequested ? deadline : reconcileAt;
-                const timer = setTimeout(() => { timers.delete(timer); wake = undefined; resolve(); }, Math.max(0, Math.min(until - Date.now(), 2_147_483_647)));
-                timers.add(timer);
-                wake = () => { clearTimeout(timer); timers.delete(timer); wake = undefined; resolve(); };
-            });
-        }
-        const terminal = terminals.get(goalId);
-        const observationFailure = (code, reason) => ({
-            ...attributed,
-            reply: { ...attributed.reply, ok: false, data: undefined, error: {
-                    code, outcome: "unknown",
-                    message: `the goal "${goalId}" was accepted, but ${reason}. THE GOAL IS UNAFFECTED - it may already have succeeded; this is not evidence the goal failed. Do NOT retry: another submission could duplicate the effect. Inspect 'ps'/'inspect' first (SPEC 13.6)`,
-                } },
-        });
-        if (stopped)
-            return observationFailure("unavailable", "the endpoint was stopped while awaiting its outcome");
-        if (observationError)
-            return observationFailure("unavailable", `following its outcome failed: ${observationError.message}`);
-        if (!terminal && subError)
-            return subError instanceof PermissionViolationError
-                ? observationFailure("permission-denied", `this caller is NOT PERMITTED to hear its outcome: the broker refused the per-goal progress subscription \"${progressSubject}\" (${subError.message}); grant this caller the per-goal progress read row`)
-                : observationFailure("unavailable", `the per-goal progress subscription \"${progressSubject}\" FAILED (${subError.name}: ${subError.message}); this is NOT a grant refusal, so changing ACLs is the wrong remedy`);
-        if (!terminal)
-            return observationFailure("deadline-exceeded", `no terminal arrived within ${followDeadlineMs}ms; this is a timeout on the WAIT`);
-        if (terminal.state === "succeeded")
-            return { ...attributed, reply: { ...attributed.reply, ok: true, data: terminal.data, error: undefined } };
-        const d = (terminal.data ?? {});
-        const raw = typeof d.error === "string" ? d.error : typeof d.reason === "string" ? d.reason : `the goal settled ${terminal.state}`;
-        const details = Array.isArray(d.details) ? d.details : undefined;
-        const message = renderLifecycleBlocked(raw, details ? { details } : undefined);
-        const fromAccept = lifecycleBlockedFrom(attributed.reply.error);
-        const merged = details ?? (fromAccept ? [fromAccept] : undefined);
-        return { ...attributed, reply: { ...attributed.reply, ok: false, error: { code: terminal.state, message, ...(merged ? { details: merged } : {}) } } };
-    }
-    finally {
-        completed = true;
-        opts?.signal?.removeEventListener("abort", onAbort);
-        unbindReconnect?.();
-        activeSub?.unsubscribe();
-        for (const timer of timers)
-            clearTimeout(timer);
-        timers.clear();
-        wake = undefined;
-        work.abort();
-        abortPhase?.();
-    }
+/** {@link submitAndFollowGoalWith} with the root's synchronous fact verifier. */
+export function submitAndFollowGoal(nc, space, endpoint, caller, deadlineMs, submit, opts) {
+    return submitAndFollowGoalWith(parseGoalResultFact, nc, space, endpoint, caller, deadlineMs, submit, opts);
 }
 /**
  * SCATTER one untargeted command to the LIVE class (§13.5): resolve the command's contract off the