@stigmer/server 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/runnerauth/bound-execution.ts

@@ -0,0 +1,270 @@
+/**
+ * The execution a runner credential is bound to — the ONE reader every
+ * consumer of the binding goes through, so the verifier (who is this
+ * runner acting as?), the memory-capture capability (which session is
+ * this run's?) and the ExecutionContext decrypt lane (may a run
+ * credential still decrypt?) cannot answer "is this run live" three ways.
+ *
+ * A credential binds exactly THREE things, and the lane's vocabulary
+ * names them (`BoundExecutionKind`):
+ *
+ *   - an agent execution or a workflow execution — a RUN, whose row is
+ *     the person's run and whose liveness is its phase;
+ *   - an MCP connect (`mcp-connect`) — not an execution at all, but the
+ *     ephemeral ExecutionContext the connect lane creates for one
+ *     discovery (domain/mcpserver/connect.ts), named by the synthetic id
+ *     that module and this one recognize through one predicate
+ *     (domain/mcpserver/connect-execution-id.ts). The row is created AS
+ *     THE PERSON who asked for the connect, so its creator stamp is who
+ *     the runner acts as when it reads that connect's secrets; the lane
+ *     deletes the row when the connect settles, so the row's existence IS
+ *     the binding's liveness, and the token's own clock (every connect
+ *     token carries `exp`) bounds a row a crash left behind.
+ *
+ * Two questions, two functions, because the callers pay differently:
+ *
+ *   - `boundExecutionKindOf(id)`: which kind the binding names, read off
+ *     the id alone — the contract's own `kind_meta` prefix table
+ *     (pipeline/apiresource-meta.ts `kindByIdPrefix`) for the two runs,
+ *     the connect predicate for the third — with no store read. A
+ *     session's or an agent's id, a foreign prefix, or garbage is
+ *     `undefined`, and the caller refuses with its own sentence. The
+ *     lane-admission decorator asks only this, per run-gate check, so it
+ *     must stay free of I/O.
+ *   - `loadBoundExecution(store, id)`: the row's facts the lane needs and
+ *     nothing else — the creator stamp the verifier resolves a person
+ *     from, the org and session the capture capability scopes with, and
+ *     LIVENESS. One read (a primary key for a run; the EC's indexed
+ *     `spec.execution_id` for a connect, the read `getByExecutionId`
+ *     already makes); a missing row is `undefined` (the credential is
+ *     invalid — the run is not the caller's to learn about); any other
+ *     store failure propagates as the fault it is (the ratified
+ *     store-fault mapping), so an outage never reads as a bad credential.
+ *
+ * Liveness is the row's, not a clock's, and it is the same rule on both
+ * lanes that accept a run credential: a run is live while its phase is
+ * not terminal — a run waits on humans with no timeout, so no clock could
+ * bound it — and for RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS after the
+ * moment the row says it finished (`status.completed_at`), because two
+ * legitimate runner writes trail the terminal stamp (constants.ts). A
+ * terminal row that does not say when it finished gets no grace: fail
+ * closed. Each kind's terminal set is its own domain's predicate
+ * (agentexecution/phases.ts, workflowexecution/phases.ts), never restated
+ * here. A RECOVERED execution is live again, and so is its credential —
+ * the same principal set as the token in Temporal history (the operator
+ * who runs the engine and holds the signing key).
+ *
+ * One more rule both no-`exp` lanes share, `bindsARun(kind)`: a RUN
+ * credential — the no-`exp` token the dispatch mints (runnerauth.ts) —
+ * may bind only a run. No mint produces a clockless token for a connect,
+ * so a token shaped that way is refused by the verifier and falls closed
+ * to redaction on the decrypt lane, through this one predicate rather
+ * than two restatements of it.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { isTerminalExecutionPhase } from "../domain/agentexecution/phases.js";
+import { isConnectExecutionId } from "../domain/mcpserver/connect-execution-id.js";
+import { isTerminalWorkflowExecutionPhase } from "../domain/workflowexecution/phases.js";
+import { kindByIdPrefix } from "../pipeline/apiresource-meta.js";
+import { auditOf } from "../pipeline/steps/defaults.js";
+import type { Store } from "../store/interface.js";
+import { ResourceNotFoundError } from "../store/interface.js";
+import { RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS } from "./constants.js";
+
+/** The three things a runner credential can bind — the lane's own vocabulary, not the enum's. */
+export type BoundExecutionKind =
+  | "agent-execution"
+  | "workflow-execution"
+  | "mcp-connect";
+
+/** The facts the lane reads off a bound execution's row. */
+export interface BoundExecution {
+  readonly kind: BoundExecutionKind;
+  readonly executionId: string;
+  /** `metadata.org` — the capture capability scopes a memory to it. */
+  readonly org: string;
+  /** The creator stamp as written: an account id since 3.15.0, a raw issuer subject before. */
+  readonly createdBy: string;
+  /** The agent execution's session; empty for a workflow execution or a connect, which have none. */
+  readonly sessionId: string;
+  /** Not terminal, or terminal within the grace (see the header); a connect's row exists. */
+  readonly live: boolean;
+}
+
+export type BoundExecutionStore = Pick<Store, "getResource" | "findByField">;
+
+export function boundExecutionKindOf(
+  executionId: string,
+): BoundExecutionKind | undefined {
+  switch (kindByIdPrefix(executionId)) {
+    case ApiResourceKind.agent_execution:
+      return "agent-execution";
+    case ApiResourceKind.workflow_execution:
+      return "workflow-execution";
+    default:
+      return isConnectExecutionId(executionId) ? "mcp-connect" : undefined;
+  }
+}
+
+/** Whether a binding of this kind is a RUN — the only thing a no-`exp` credential may name (see the header). */
+export function bindsARun(kind: BoundExecutionKind): boolean {
+  switch (kind) {
+    case "agent-execution":
+    case "workflow-execution":
+      return true;
+    case "mcp-connect":
+      return false;
+    default: {
+      const exhaustive: never = kind;
+      throw new Error(`unknown bound execution kind ${String(exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Loads the bound execution's facts; `undefined` when the id names no
+ * binding kind or no row. `now` is injectable for the grace arms and
+ * defaults to the wall clock.
+ */
+export async function loadBoundExecution(
+  store: BoundExecutionStore,
+  executionId: string,
+  now: number = Date.now(),
+): Promise<BoundExecution | undefined> {
+  const kind = boundExecutionKindOf(executionId);
+  if (kind === undefined) {
+    return undefined;
+  }
+  switch (kind) {
+    case "agent-execution": {
+      const row = await getRow(
+        store,
+        ApiResourceKind.agent_execution,
+        executionId,
+        AgentExecutionSchema,
+      );
+      if (row === undefined) {
+        return undefined;
+      }
+      return {
+        kind,
+        executionId,
+        org: row.metadata?.org ?? "",
+        createdBy: creatorStampOf(AgentExecutionSchema, row),
+        sessionId: row.spec?.sessionId ?? "",
+        live: isLive(
+          row.status !== undefined &&
+            isTerminalExecutionPhase(row.status.phase),
+          row.status?.completedAt ?? "",
+          now,
+        ),
+      };
+    }
+    case "workflow-execution": {
+      const row = await getRow(
+        store,
+        ApiResourceKind.workflow_execution,
+        executionId,
+        WorkflowExecutionSchema,
+      );
+      if (row === undefined) {
+        return undefined;
+      }
+      return {
+        kind,
+        executionId,
+        org: row.metadata?.org ?? "",
+        createdBy: creatorStampOf(WorkflowExecutionSchema, row),
+        sessionId: "",
+        live: isLive(
+          row.status !== undefined &&
+            isTerminalWorkflowExecutionPhase(row.status.phase),
+          row.status?.completedAt ?? "",
+          now,
+        ),
+      };
+    }
+    case "mcp-connect": {
+      // The connect's ExecutionContext, by the execution id it was
+      // created for — the same indexed read getByExecutionId makes. The
+      // row is deleted when the connect settles, so its presence is the
+      // liveness; the token's clock is enforced by `verify` before this.
+      const row = await getExecutionContextRow(store, executionId);
+      if (row === undefined) {
+        return undefined;
+      }
+      return {
+        kind,
+        executionId,
+        org: row.metadata?.org ?? "",
+        createdBy: creatorStampOf(ExecutionContextSchema, row),
+        sessionId: "",
+        live: true,
+      };
+    }
+    default: {
+      const exhaustive: never = kind;
+      throw new Error(`unknown bound execution kind ${String(exhaustive)}`);
+    }
+  }
+}
+
+/** A row with no status has not started, which is live. */
+function isLive(terminal: boolean, completedAt: string, now: number): boolean {
+  if (!terminal) {
+    return true;
+  }
+  const finishedAt = Date.parse(completedAt);
+  if (Number.isNaN(finishedAt)) {
+    return false;
+  }
+  return now - finishedAt < RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS;
+}
+
+/** The schemas whose rows a binding can resolve to. */
+type BoundRowSchema =
+  | typeof AgentExecutionSchema
+  | typeof WorkflowExecutionSchema
+  | typeof ExecutionContextSchema;
+
+function creatorStampOf(schema: BoundRowSchema, row: Message): string {
+  return auditOf(schema, row)?.specAudit?.createdBy?.id ?? "";
+}
+
+async function getRow<
+  Desc extends typeof AgentExecutionSchema | typeof WorkflowExecutionSchema,
+>(store: BoundExecutionStore, kind: ApiResourceKind, id: string, schema: Desc) {
+  try {
+    return await store.getResource(kind, id, schema);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+async function getExecutionContextRow(
+  store: BoundExecutionStore,
+  executionId: string,
+) {
+  try {
+    return await store.findByField(
+      ApiResourceKind.execution_context,
+      "spec.executionId",
+      executionId,
+      ExecutionContextSchema,
+    );
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      return undefined;
+    }
+    throw error;
+  }
+}

package/src/runnerauth/built-in-runner-credential-provider.ts

@@ -0,0 +1,300 @@
+/**
+ * The built-in RunnerCredentialProvider — the open-source execution-scoped
+ * default (runner-credential-provider.ts) plus the three capabilities an
+ * ENFORCING self-host needs, composed under the built-in authorization
+ * posture beside the runner-subject verifier (boot/compose.ts). The
+ * cloud's shape, kept on purpose: one provider object carries the
+ * edition's whole credential story, so the composition root binds one
+ * thing and every OSS touchpoint that consults the seam sees the same
+ * policy. Mint, verify, isEnabled and the dispatch's `mintRunCredential`
+ * are the default provider's, byte for byte; under trusted-local the
+ * default alone is composed and none of what follows exists.
+ *
+ * ONE reading of "what is this runner bound to" — `runnerBindingOf` —
+ * feeds everything here and the Authorizer's lane admission
+ * (authorization/lane-admission.ts). It re-verifies the caller's own
+ * `rawToken` (the cloud's `verifiedClaims(caller.rawToken)` pattern: one
+ * HMAC, no store read) and reads the kind off the bound id's prefix
+ * through the contract's table (bound-execution.ts). It checks the
+ * caller CLASS first: the lane admission runs on every run-gate check
+ * for every caller, and only the runner-subject verifier mints `runner`,
+ * so a person costs nothing here. It never throws: a person, a runner
+ * holding no token, a token this server did not sign, or a binding that
+ * names no kind is simply "not a runner binding", and each caller
+ * answers its own default for that. A CONNECT binding (`mcp-connect`, a
+ * runner reading one discovery's secrets as the person who asked) IS a
+ * runner binding, and every capability below answers it by name: it is
+ * admitted on no run gate, vouches no lineage, captures no memory, and
+ * the exchange mints nothing for it.
+ *
+ * The capabilities, and where they follow or narrow the cloud:
+ *
+ *   - `vouchRunnerLineageLabels`: a WORKFLOW-bound runner vouches the two
+ *     lineage keys for its own workflow execution and REFUSES a stamp
+ *     naming another (the cloud's byte-pinned copy, constants.ts). Without
+ *     this, a self-host with sign-in on cannot run any workflow that
+ *     calls an agent: the child create's GuardReservedLabels asks the
+ *     Authorizer for `can_write_reserved_labels` on the platform object,
+ *     which the built-in Authorizer denies for everyone. NARROWER than the
+ *     cloud on purpose: the cloud vouches for every runner-class
+ *     credential and binds only its workflow lane; here an agent-bound
+ *     runner vouches nothing, because the workflow's `agent_call` activity
+ *     is the only producer of the lineage labels and it runs under the
+ *     workflow's credential (runner: activities/call-agent.ts). Nothing
+ *     observable diverges; do not widen this toward the cloud without a
+ *     producer that needs it.
+ *   - `authorizeMemoryCapture`: an AGENT-bound runner is ADMITTED with the
+ *     human the verifier resolved as the memory's subject — the row's one
+ *     principal under the model; without it every memory an enforcing
+ *     self-host writes belongs to nobody — and the run's session as the
+ *     proved provenance. The cloud reads both off its session-scoped
+ *     token; our token names only the execution, so this reads the row
+ *     (one primary-key read per `remember` call) and the seam allows the
+ *     promise. The cloud's org arm is kept: a capture addressed to an org
+ *     that is not the run's is "a forged address, not a routing choice"
+ *     (its byte-pinned copy). A workflow-bound runner is refused (the
+ *     cloud refuses every non-session lane); a person, or a runner whose
+ *     token does not verify, is no-opinion and the gate's own logic
+ *     applies. A run that has vanished between the verifier's read and
+ *     this one is refused: a memory the server cannot attribute to a run
+ *     must not be written as nobody's (fail closed).
+ *   - `exchangeScopedToken`: the platform exchange (getRunnerScopedToken)
+ *     becomes a MINT GATE. Under trusted-local the controller's own arms
+ *     mint a clocked decrypt-lane token for any caller naming an
+ *     execution, and that is harmless — the token unlocks a decrypt lane
+ *     and nothing more. Under this posture the same token IS an identity
+ *     (the verifier admits its bearer as the run's human), so minting
+ *     one for another person's run would be impersonation. The execution
+ *     arms therefore mint only for the run's own person — the account
+ *     the row's creator stamp resolves to, the same reading the verifier
+ *     makes — and mint the RUN credential (no `exp`; `expires_in_seconds`
+ *     0, the proto default), so under the posture there is one credential
+ *     shape and the exchange is the runner's true fallback for a dispatch
+ *     that carried none. The ladder is the platform's own: a row that
+ *     does not exist → NOT_FOUND with the load-first copy (what a `get`
+ *     on that id answers), a caller who is not the run's person, or a run
+ *     whose stamp names nobody → PERMISSION_DENIED with one sentence
+ *     (constants.ts). The id decides which execution kind is read (the
+ *     lane's rule everywhere); the request's arm only chooses the
+ *     not-found copy; an id that resolves to a CONNECT binding is
+ *     NOT_FOUND too, because the exchange mints run credentials and a
+ *     connect is not a run. Liveness is NOT judged at mint — both lanes that
+ *     accept the token judge it, by one rule (bound-execution.ts), and a
+ *     third judge here would be a divergence waiting to happen. The
+ *     pool-claim, renewal and unset arms answer not-minted, the
+ *     controller's arms verbatim; keyless answers not-minted too.
+ *
+ * Deliberately UNDEFINED here: `bootstrapCredentials`,
+ * `mintSandboxCredential`, `authorizeExecutionContextRead`,
+ * `resolvePayloadKey`. Their open-source arms stay where they are (the
+ * sandbox lane's mint, the decrypt lane's binding-equality decision);
+ * this provider adds policy an enforcing server lacks and takes over
+ * nothing that already works.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { accountForStamp } from "../domain/identityaccount/resolve.js";
+import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+import type { CallerIdentity } from "../extensions/identity.js";
+import { getKindName } from "../pipeline/apiresource-meta.js";
+import { notFoundError } from "../pipeline/errors.js";
+import {
+  bindsARun,
+  boundExecutionKindOf,
+  loadBoundExecution,
+} from "./bound-execution.js";
+import type {
+  BoundExecutionKind,
+  BoundExecutionStore,
+} from "./bound-execution.js";
+import {
+  MEMORY_CAPTURE_ORG_MISMATCH_MESSAGE,
+  RUN_CREDENTIAL_NOT_RUNS_PERSON_MESSAGE,
+  WORKFLOW_LINEAGE_BINDING_MISMATCH_MESSAGE,
+} from "./constants.js";
+import type {
+  MemoryCaptureDecision,
+  RunnerCredentialProvider,
+  RunnerScopedTokenExchange,
+  RunnerScopedTokenRequest,
+} from "./runner-credential-provider.js";
+import { newExecutionScopedRunnerCredentialProvider } from "./runner-credential-provider.js";
+import type { RunnerAuthService } from "./runnerauth.js";
+
+/** What a runner-class caller's credential is bound to. */
+export interface RunnerBinding {
+  readonly kind: BoundExecutionKind;
+  readonly executionId: string;
+}
+
+export interface BuiltInRunnerCredentialProviderDeps {
+  /** The service that signed every token this provider reads. */
+  readonly service: RunnerAuthService;
+  /** Where the bound executions live — the capture and exchange capabilities' one read each. */
+  readonly store: BoundExecutionStore;
+  /** Resolves a run's creator stamp to its person — the exchange's owner check, the verifier's reading. */
+  readonly accounts: AccountsByCaller;
+}
+
+/**
+ * The one reading of a runner's binding. `undefined` for anything that
+ * is not a runner-class caller holding a token this service signed whose
+ * binding names an execution kind; never a throw.
+ */
+export function runnerBindingOf(
+  service: RunnerAuthService,
+  caller: CallerIdentity,
+): RunnerBinding | undefined {
+  if (caller.callerClass !== "runner" || caller.rawToken === "") {
+    return undefined;
+  }
+  let executionId: string;
+  try {
+    executionId = service.verify(caller.rawToken);
+  } catch {
+    return undefined;
+  }
+  const kind = boundExecutionKindOf(executionId);
+  return kind === undefined ? undefined : { kind, executionId };
+}
+
+/** The lane-admission predicate: a runner acting for a WORKFLOW execution (the cloud's `workflow_sandbox`). */
+export function isWorkflowBoundRunner(
+  service: RunnerAuthService,
+  caller: CallerIdentity,
+): boolean {
+  return runnerBindingOf(service, caller)?.kind === "workflow-execution";
+}
+
+/** The kind name the not-found copy carries, by the request's arm (what a `get` on that kind would say). */
+function requestedKindName(
+  arm: "agent-execution" | "workflow-execution",
+): string {
+  switch (arm) {
+    case "agent-execution":
+      return getKindName(ApiResourceKind.agent_execution);
+    case "workflow-execution":
+      return getKindName(ApiResourceKind.workflow_execution);
+    default: {
+      const exhaustive: never = arm;
+      throw new Error(`unhandled exchange arm: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+export function newBuiltInRunnerCredentialProvider(
+  deps: BuiltInRunnerCredentialProviderDeps,
+): RunnerCredentialProvider {
+  const { service, store, accounts } = deps;
+  const lane = newExecutionScopedRunnerCredentialProvider(service);
+  const mintRunCredential = lane.mintRunCredential!.bind(lane);
+  return {
+    isEnabled: lane.isEnabled,
+    mint: lane.mint,
+    verify: lane.verify,
+    mintRunCredential,
+
+    async exchangeScopedToken(
+      request: RunnerScopedTokenRequest,
+      caller: CallerIdentity,
+    ): Promise<RunnerScopedTokenExchange> {
+      switch (request.arm) {
+        case "agent-execution":
+        case "workflow-execution": {
+          if (request.executionId === "" || !service.isEnabled()) {
+            return { minted: false };
+          }
+          const execution = await loadBoundExecution(
+            store,
+            request.executionId,
+          );
+          // A connect binding is not a run: the exchange mints RUN
+          // credentials, and the requested kind's row does not exist.
+          if (execution === undefined || !bindsARun(execution.kind)) {
+            throw notFoundError(
+              requestedKindName(request.arm),
+              request.executionId,
+            );
+          }
+          const person = await accountForStamp(accounts, execution.createdBy);
+          if (
+            person === undefined ||
+            person.metadata?.id !== caller.identityId
+          ) {
+            throw new ConnectError(
+              RUN_CREDENTIAL_NOT_RUNS_PERSON_MESSAGE,
+              Code.PermissionDenied,
+            );
+          }
+          return {
+            minted: true,
+            token: mintRunCredential(execution.executionId),
+            // No `exp` on a run credential; 0 is the proto default and
+            // the runner's acquire sites read no expiry from it.
+            expiresInSeconds: 0,
+          };
+        }
+        case "pool-claim":
+        case "renewal":
+        case "unset":
+          return { minted: false };
+        default: {
+          const exhaustive: never = request;
+          throw new Error(
+            `unhandled exchange arm: ${JSON.stringify(exhaustive)}`,
+          );
+        }
+      }
+    },
+
+    vouchRunnerLineageLabels(
+      caller: CallerIdentity,
+      stampedWorkflowExecutionId: string,
+    ): boolean {
+      const binding = runnerBindingOf(service, caller);
+      if (binding?.kind !== "workflow-execution") {
+        return false;
+      }
+      if (
+        stampedWorkflowExecutionId !== "" &&
+        stampedWorkflowExecutionId !== binding.executionId
+      ) {
+        throw new ConnectError(
+          WORKFLOW_LINEAGE_BINDING_MISMATCH_MESSAGE,
+          Code.InvalidArgument,
+        );
+      }
+      return true;
+    },
+
+    async authorizeMemoryCapture(
+      caller: CallerIdentity,
+      captureOrg: string,
+    ): Promise<MemoryCaptureDecision> {
+      const binding = runnerBindingOf(service, caller);
+      if (binding === undefined) {
+        return { verdict: "no-opinion" };
+      }
+      if (binding.kind !== "agent-execution") {
+        return { verdict: "refuse" };
+      }
+      const execution = await loadBoundExecution(store, binding.executionId);
+      if (execution === undefined) {
+        return { verdict: "refuse" };
+      }
+      if (captureOrg !== "" && captureOrg !== execution.org) {
+        throw new ConnectError(
+          MEMORY_CAPTURE_ORG_MISMATCH_MESSAGE,
+          Code.PermissionDenied,
+        );
+      }
+      return {
+        verdict: "admit",
+        subjectIdentityAccountId: caller.identityId,
+        provedSessionId: execution.sessionId,
+      };
+    },
+  };
+}

package/src/runnerauth/constants.ts

@@ -0,0 +1,74 @@
+/**
+ * The runner-subject lane's pinned names and copy — the one constants
+ * module for the runner-credential domain (the ts-server guideline:
+ * byte-pinned copy lives in one constants module per domain, never
+ * inline at the refusal site).
+ *
+ * Two refusal sentences for a PRESENTED credential, deliberately not
+ * more (the InvalidTokenError doctrine of runnerauth.ts: a finer reason
+ * invites branching on it). The runner is the only caller that ever
+ * presents a run credential, and the person reading these is its
+ * operator, in the runner's log:
+ *
+ *   - the TOKEN sentence: the credential itself is not one this server
+ *     will honor — forged, the wrong shape, bound to an execution or a
+ *     connect this server does not have (a connect's row is gone once
+ *     the connect settles), a clockless token bound to a connect (a shape
+ *     no mint produces), a present `exp` in the past, or minted by a key
+ *     this server does not hold. A missing row is this sentence and not
+ *     NOT_FOUND on purpose: the credential is invalid, and the run is
+ *     not the caller's to learn about.
+ *   - the LIVENESS sentence: the credential is genuine but its run is
+ *     over, or its run or connect was created by nobody this server
+ *     recognizes as a person (the schedule fire caller's
+ *     deterministic-refusal shape: no retry will make that run anyone's).
+ *
+ * And one for a REQUESTED credential — the platform exchange under the
+ * built-in posture (built-in-runner-credential-provider.ts), where the
+ * caller is a signed-in person asking for a run's credential and the
+ * answer is a permission, not a token verdict: only the person whose run
+ * it is may hold its credential. A run whose creator stamp names nobody
+ * gets the same sentence — no one is its person.
+ *
+ * The lineage mismatch copy is the cloud edition's, transcribed byte for
+ * byte (credentials/provider.ts in the composition; the Java
+ * RecordRunnerLineageLabelsStep before it) so the two editions refuse a
+ * mis-stamped lineage label with one sentence.
+ */
+
+/** The verifier's name in the boot log and in auth failures (the `oidc` / `apikey` precedent). */
+export const RUNNER_VERIFIER_NAME = "runner";
+
+/** The token arms: forged, wrong shape, unknown execution, past `exp`, keyless. */
+export const RUNNER_CREDENTIAL_INVALID_MESSAGE =
+  "runner credential is not valid on this server";
+
+/** The resolution arms: a terminal execution; a run stamped by nobody the server recognizes. */
+export const RUNNER_CREDENTIAL_NOT_LIVE_MESSAGE =
+  "runner credential names a run that is over or belongs to nobody this server recognizes";
+
+/** The exchange's refusal under the built-in posture: the caller is not the run's person (PERMISSION_DENIED). */
+export const RUN_CREDENTIAL_NOT_RUNS_PERSON_MESSAGE =
+  "a run credential is minted only for the person whose run it is";
+
+/** The cloud's byte-pinned lineage refusal (the Java step's copy). */
+export const WORKFLOW_LINEAGE_BINDING_MISMATCH_MESSAGE =
+  "workflow lineage label names a workflow execution this runner credential is not bound to";
+
+/** The cloud's byte-pinned org-mismatch refusal (MemoryPolicy.MEMORY_CAPTURE_ORG_MISMATCH_MESSAGE). */
+export const MEMORY_CAPTURE_ORG_MISMATCH_MESSAGE =
+  "memory capture is scoped to the session's organization";
+
+/**
+ * How long a run credential outlives its run, measured from the row's
+ * `status.completed_at`. A run's credential is valid while the run is
+ * not terminal — runs wait on humans with no timeout, so no clock can
+ * bound them — and for this long after, because two legitimate runner
+ * writes land after the terminal stamp: the session-subject generation
+ * the workflow fires and does not await (issue #665), and a Temporal
+ * activity retried after its completion failed to reach the engine.
+ * Ten minutes covers one model call and one retry backoff; today's
+ * exchange-lane token outlives a run by up to an hour. A terminal row
+ * with no `completed_at` gets no grace: fail closed.
+ */
+export const RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS = 10 * 60 * 1000;