@cotal-ai/core 0.85.0 → 0.87.0

package/dist/endpoint-call.d.ts

@@ -0,0 +1,176 @@
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type EpCaller, type EpRoute } from "./endpoint-subjects.js";
+import { type EndpointReply, type EpCorrelation, type EpRegistryReadFailedDetail, type EpErrorDetail, type EpBindBlock } from "./endpoint-envelope.js";
+import type { CompiledContract } from "./schema-profile.js";
+/** A verb's target: one input shape that builds BOTH halves of the §13.2/§13.3 targeted form —
+ *  the subject's authorization-mode token block and the body target block — so they can never
+ *  disagree. `self` carries no body target (the caller triple IS the target, §13.3). */
+export type EpVerbTarget = {
+    mode: "self";
+} | {
+    mode: "owner" | "any" | "child" | "ledger" | "handle" | "exact";
+    owner: string;
+    actor: string;
+    lifecycleUid: string;
+    mappingRevision?: number;
+};
+/** What every verb needs to address one command: the compiled §13.7 contracts (digests derive
+ *  from `closureDigest`, exactly like the serve table), the caller triple the credential pins,
+ *  and an optional display name for the advisory `from.name`. */
+export interface EpVerbOp {
+    endpoint: string;
+    command: string;
+    contract: {
+        input: CompiledContract;
+        output: CompiledContract;
+    };
+    caller: EpCaller;
+    args?: Record<string, unknown>;
+    target?: EpVerbTarget;
+    /** The incarnation this caller resolved against (§13.3). Carrying it makes a responder that is
+     *  not that incarnation refuse BEFORE running the command, which is the only place the refusal
+     *  can be a guard rather than a report. Omitted ⇒ any member of the class may serve the call. */
+    bind?: EpBindBlock;
+    correlation?: EpCorrelation;
+    /** Opaque signed authorization-context slot (§13.3); carried as-is. */
+    auth?: string;
+    goalId?: string;
+    /**
+     * A caller-PINNED envelope id, replacing the per-publish nonce. A goal-accepting command binds
+     * its goal under the envelope id, so a durable caller that must resubmit idempotently — a
+     * workflow run resuming across a crash re-derives the same `requestId` and the far side serves
+     * the recorded acceptance instead of accepting twice — pins the id it derived BEFORE submitting.
+     * Validated as an id token; reply correlation still rides the per-publish subject nonce, so two
+     * calls pinning one id cannot cross-deliver replies.
+     */
+    id?: string;
+    /** Advisory display name for `from.name`; `from.id` is DERIVED from the caller triple, so it
+     *  always equals the broker-authenticated sender principal (§13.3). */
+    name?: string;
+}
+export declare function buildRequest(space: string, route: EpRoute, op: EpVerbOp, verb: {
+    replyExpected: boolean;
+    deadlineMs?: number;
+}): {
+    subject: string;
+    requestId: string;
+    n: string;
+    body: Uint8Array;
+};
+export declare function assertDeadline(deadlineMs: number, what?: string): number;
+/** What a liveness probe can establish about ONE frozen instance (§13.5). Only `gone` is an
+ *  AFFIRMATIVE fact — the broker itself reporting that the instance holds no subscription on its
+ *  own rail. `live` and `unknown` are handled identically by the gather: they license nothing and
+ *  the full deadline stands. There is deliberately NO verdict for "its presence entry expired":
+ *  a lapsed heartbeat is absence of evidence, and reading absence of evidence as death is how a
+ *  slow correct answer becomes a fast wrong one. */
+export type EpInstanceLiveness = "gone" | "live" | "unknown";
+/**
+ * Ask the BROKER whether one instance still holds a subscription on its own `inst` rail (§13.2).
+ *
+ * A serving incarnation subscribes `ep.inst.<endpoint>.<instanceId>.<command>.>` for every command
+ * it serves, so a request published there with a reply-to only the broker can reach either draws
+ * the broker's no-responders 503 — an affirmative statement that this instance holds no
+ * subscription — or draws nothing at all.
+ *
+ * NOTHING IS `unknown` BUT A REFUSED PUBLISH, AND NOTHING IS EVER DEATH. A slow broker, a responder
+ * that receives the request and declines to answer, and a perfectly healthy instance are
+ * indistinguishable from here, and every one of them must keep the caller waiting. A REFUSED
+ * PUBLISH IS THE ONE EXCEPTION, and it is a refusal rather than a verdict: `nc.publish` returns
+ * normally on a violation, so the permission watch (see {@link openPublishDenialWatch}, registered
+ * before the publish and released in the `finally`) races the budget and settles the probe
+ * `permission-denied` naming the refused subject as soon as the connection reports it — never a
+ * silent `unknown` that consumes the full budget on a permission problem. The failure direction is
+ * otherwise the whole safety argument: because only a 503 says anything, a short probe budget can
+ * never turn a live instance into a fast `missing` — it can only fail to speed up a dead one.
+ *
+ * It rides `describe` because §13.7 makes every endpoint serve it and it carries no effect, and it
+ * rides as a CAST: the verdict comes from the transport, not from an answer, so nothing is read and
+ * an instance whose describe is broken still reads as present.
+ */
+export declare function epProbeInstanceInterest(nc: NatsConnection, space: string, endpoint: string, instanceId: string, caller: EpCaller, opts: {
+    deadlineMs: number;
+}): Promise<EpInstanceLiveness>;
+/** Race a caller-supplied read against a bounded budget so a never-settling hook cannot exceed the
+ *  operation deadline (SPEC 13.5: deadline mandatory). Clears its timer on either outcome. */
+export declare function raceBounded<T>(read: () => Promise<T> | T, ms: number, what: string, details?: EpErrorDetail[]): Promise<T>;
+/** The {@link EP_REGISTRY_READ_FAILED} detail for `op`: set where the scatter's OWN registry read
+ *  (freeze or reconcile) failed, so the failure is never read as the responders' silence. */
+export declare const registryReadDetail: (op: EpVerbOp) => EpRegistryReadFailedDetail;
+/** The caller's per-request reply subscription: its own rail narrowed to exactly this request's
+ *  nonce (contained in the §13.9 reply-read grant), so concurrent calls never see each other. */
+export declare function replySubjectFor(space: string, caller: EpCaller, n: string): string;
+/** One attributed reply: the structural attribution comes from the reply SUBJECT (§13.2), never
+ *  from the body. */
+export interface EpAttributedReply {
+    reply: EndpointReply;
+    responder: {
+        endpoint: string;
+        instanceId: string;
+        epoch: number;
+    };
+}
+export declare function parseAttributedReply(space: string, subject: string, data: Uint8Array, requestId: string, op: EpVerbOp, expect?: {
+    instanceId?: string;
+    epoch?: number;
+}): EpAttributedReply;
+/**
+ * Call one command and await its reply within `deadlineMs`: on the `one` (queue-group anycast) or
+ * `inst` (stable incarnation) rail with `replyExpected: true`, subscribe the caller's own
+ * nonce-scoped reply subject BEFORE publishing, and resolve the first attributed reply — BOUND to
+ * the invoked identity (§13.2, the stale-reply rejection rule: "callers reject" stale-process replies), on BOTH rails:
+ *  - `inst` pins the addressed `(instanceId, epoch)` incarnation up front; a stale-epoch reply is
+ *    `expired` and a wrong-instance reply `internal`.
+ *  - `one` cannot pin an instance up front (the queue picks the responder), so the caller MUST supply
+ *    `currentEpoch(instanceId)`: after the reply lands, the answering incarnation's epoch is checked
+ *    against its current registry epoch, and a superseded-but-still-connected queue member's reply is
+ *    `expired`. The queue winner is NOT implicitly current — that is a check, not an assumption.
+ *    `currencyReference` says what that hook returns, for the refusal's wording and marker: the
+ *    documented `registry` read (default), or `bind` when a caller supplies its own resolve's epoch
+ *    instead (the describe-bound default in {@link invokeCommand}), where a responder ahead of it is
+ *    a successor and the caller's handle is the stale side.
+ *
+ * Application-level failure is NOT a throw: the resolved `reply` carries `ok: false` with the
+ * responder's structured error (§13.3). This boundary throws only for its own refusals: invalid args
+ * `bad-request`; an unparseable/mis-echoed/mis-attributed reply `internal` (a raw decode error never
+ * escapes); a throwing `currentEpoch` hook `internal` and a garbled (non-integer/negative) currency
+ * value `failed-precondition` (the read's own failure, never mislabeled staleness); a stale reply `expired`;
+ * NO responder `unavailable` (SPEC 13.5, the broker no-responders answer — the broker's no-responders 503 lands on a reply-to that
+ * sits on THIS caller's own rail, so a manual, fully-disposed probe distinguishes it from a slow
+ * responder without leaving a lingering request); a failed reply subscription `unavailable`; a
+ * broker publish violation `permission-denied` naming the refused subject (the connection-status
+ * watch that keeps a missing GRANT from reading as an unanswered deadline); the elapsed budget
+ * `deadline-exceeded`. Every subscription, timer, and status watch is released in the `finally`.
+ */
+export declare function epCall(nc: NatsConnection, space: string, route: {
+    mode: "one";
+} | {
+    mode: "inst";
+    instanceId: string;
+    epoch: number;
+}, op: EpVerbOp, opts: {
+    deadlineMs: number;
+    currentEpoch?: (instanceId: string) => Promise<number> | number;
+    currencyReference?: "bind" | "registry";
+    signal?: AbortSignal;
+}): Promise<EpAttributedReply>;
+/**
+ * Cast one command: the same request form with `replyExpected: false` — the responder never
+ * replies, even on failure (§13.5 at-most-once), so this resolves once the request is flushed to
+ * the broker. `deadlineMs` is optional and advisory for `one`/`inst` (the envelope requires it only
+ * for calls and journal submissions, §13.3), but MANDATORY for `all`: §13.2's
+ * `checkRequestSubjectAgreement` refuses an all-rail request without a deadline regardless of
+ * `replyExpected`, and a cast has no reply on which that refusal could surface — so an all-cast
+ * without a deadline would be silently dropped by every responder. Fail loud at the caller instead.
+ *
+ * A broker publish refusal is NOT a flushed cast: `nc.publish` returns normally on a violation, so
+ * the permission watch (see {@link openPublishDenialWatch}, registered before the publish and
+ * released in the `finally`) races the flush, and a refused cast settles `permission-denied`
+ * naming the refused subject as soon as the connection reports it — never a resolution the caller
+ * could read as "it was cast". Nothing is added to the healthy path: a permitted publish is
+ * unaffected and the flush round-trip stands as the settling time.
+ */
+export declare function epCast(nc: NatsConnection, space: string, route: EpRoute, op: EpVerbOp, opts?: {
+    deadlineMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=endpoint-call.d.ts.map

package/dist/endpoint-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-call.d.ts","sourceRoot":"","sources":["../src/endpoint-call.ts"],"names":[],"mappings":"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"}