@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/execution/dbos-run-launcher.d.ts

@@ -3,16 +3,36 @@
  * shared by every embedder. Host-neutral: it references only DBOS and the OTel
  * API, which the harness already depends on, so it ships in the harness.
  *
+ * Outside a workflow the launch starts the run with `DBOS.startWorkflow`. A
+ * tool call of a chat turn runs inside a step, and DBOS refuses a start or an
+ * enqueue from a step. Thus inside a workflow the launch enqueues the run
+ * through a `DBOSClient` on the run queue, which no step check covers, and
+ * which keeps the run out of the children of the caller. Both paths take the
+ * run id as the workflow id, and DBOS gives back the existing workflow for an
+ * id that it holds. Thus a second launch of one run id starts nothing. A launch
+ * that fails while a workflow of its run id exists resolves, because the run is
+ * durably started.
+ *
  * A launch detaches the run from the caller's trace. The DBOS workflow span
  * takes the active context as its parent, and the caller is a chat request
  * (or another short-lived operation) whose span ends in milliseconds while the
  * run lasts hours. So the launch opens a root span of its own, runs
  * `startWorkflow` under it, and joins the two traces by a span link back to
- * the originating span plus `inflexa.run_id` on both sides. With no
- * TracerProvider registered every call here is a no-op on the API's
- * non-recording span.
+ * the originating span plus `inflexa.run_id` on both sides. An enqueued run
+ * starts on the dispatch loop of the queue, in no trace of the launch, and
+ * `inflexa.run_id` joins it. With no TracerProvider registered every call here
+ * is a no-op on the API's non-recording span.
  */
+import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
 import type { RunLauncher } from "./run-launcher.js";
 /** Attribute carrying the run id on the originating span and on the run's root span. */
 export declare const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
-export declare function createDbosRunLauncher(): RunLauncher;
+/** The queue of a run that a launch inside a workflow enqueues. It has no limit, thus a run waits only for the poll of the queue. */
+export declare const RUN_QUEUE = "analysis-runs";
+export type DbosRunLauncherDeps = {
+    /** A pool onto the system database of the engine: the same database that the application pool holds. */
+    readonly pool: Pool;
+    readonly logger?: Logger;
+};
+export declare function createDbosRunLauncher(deps: DbosRunLauncherDeps): RunLauncher;

package/dist/execution/dbos-run-launcher.js

@@ -3,23 +3,68 @@
  * shared by every embedder. Host-neutral: it references only DBOS and the OTel
  * API, which the harness already depends on, so it ships in the harness.
  *
+ * Outside a workflow the launch starts the run with `DBOS.startWorkflow`. A
+ * tool call of a chat turn runs inside a step, and DBOS refuses a start or an
+ * enqueue from a step. Thus inside a workflow the launch enqueues the run
+ * through a `DBOSClient` on the run queue, which no step check covers, and
+ * which keeps the run out of the children of the caller. Both paths take the
+ * run id as the workflow id, and DBOS gives back the existing workflow for an
+ * id that it holds. Thus a second launch of one run id starts nothing. A launch
+ * that fails while a workflow of its run id exists resolves, because the run is
+ * durably started.
+ *
  * A launch detaches the run from the caller's trace. The DBOS workflow span
  * takes the active context as its parent, and the caller is a chat request
  * (or another short-lived operation) whose span ends in milliseconds while the
  * run lasts hours. So the launch opens a root span of its own, runs
  * `startWorkflow` under it, and joins the two traces by a span link back to
- * the originating span plus `inflexa.run_id` on both sides. With no
- * TracerProvider registered every call here is a no-op on the API's
- * non-recording span.
+ * the originating span plus `inflexa.run_id` on both sides. An enqueued run
+ * starts on the dispatch loop of the queue, in no trace of the launch, and
+ * `inflexa.run_id` joins it. With no TracerProvider registered every call here
+ * is a no-op on the API's non-recording span.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { context, isSpanContextValid, ROOT_CONTEXT, trace } from "@opentelemetry/api";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { dbosClientFor } from "./dbos-workflow-purger.js";
 /** Attribute carrying the run id on the originating span and on the run's root span. */
 export const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
+/** The queue of a run that a launch inside a workflow enqueues. It has no limit, thus a run waits only for the poll of the queue. */
+export const RUN_QUEUE = "analysis-runs";
 const TRACER_NAME = "inflexa.harness.run-launcher";
-export function createDbosRunLauncher() {
+export function createDbosRunLauncher(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("run-launcher");
+    let queueRegistered;
+    const registerRunQueue = (client) => {
+        queueRegistered ??= client.registerQueue(RUN_QUEUE, { onConflict: "never_update" }).catch((cause) => {
+            queueRegistered = undefined;
+            throw cause;
+        });
+        return queueRegistered;
+    };
+    const enqueue = async (workflow, opts, input) => {
+        const client = await dbosClientFor(deps.pool, logger);
+        await registerRunQueue(client);
+        // The run runs the code of this version, the same as a start in this process.
+        await client.enqueue({ workflowName: workflow.name, queueName: RUN_QUEUE, workflowID: opts.workflowId, appVersion: DBOS.applicationVersion }, input);
+    };
+    // An earlier launch of the run id can start the run, and a later launch can then fail for a transient reason.
+    // The run is durably started, thus the fault is not a fault of the launch. The read goes through the client,
+    // because a status read of `DBOS` in a workflow body takes a checkpoint, and only this failure path reads.
+    // A failed read keeps the fault of the start, because the existence of the run is then unknown.
+    const workflowExists = async (workflowId) => {
+        try {
+            const client = await dbosClientFor(deps.pool, logger);
+            return (await client.getWorkflow(workflowId)) !== undefined;
+        }
+        catch (cause) {
+            logger.warn("the workflow of a run whose launch failed was not read", { runId: workflowId, ...logger.errorFields(cause) });
+            return false;
+        }
+    };
     return {
         async launch(workflow, opts, input) {
+            const inWorkflow = DBOS.isWithinWorkflow();
             const originating = trace.getSpan(context.active());
             const links = [];
             if (originating !== undefined && isSpanContextValid(originating.spanContext())) {
@@ -28,8 +73,17 @@ export function createDbosRunLauncher() {
             }
             const root = trace.getTracer(TRACER_NAME).startSpan("launch run", { links, attributes: { [ATTR_INFLEXA_RUN_ID]: opts.workflowId } }, ROOT_CONTEXT);
             try {
+                if (inWorkflow) {
+                    await enqueue(workflow, opts, input);
+                    return;
+                }
                 await context.with(trace.setSpan(ROOT_CONTEXT, root), () => DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input));
             }
+            catch (cause) {
+                if (await workflowExists(opts.workflowId))
+                    return;
+                throw cause;
+            }
             finally {
                 root.end();
             }

package/dist/execution/dbos-workflow-purger.d.ts

@@ -13,18 +13,19 @@
  * injected pool already reaches the ledger.
  *
  * The engine owns the deletion itself, including the breadth-first walk over
- * `parent_workflow_id` that reaches child step workflows. Its single
- * `DELETE FROM dbos.workflow_status WHERE workflow_uuid = ANY(...)` is all the
- * dependent tables need: step outputs, streams, inputs, events, notifications,
- * and queue rows each hold an `ON DELETE CASCADE` foreign key to
+ * `parent_workflow_id` that reaches child step workflows. It deletes the step
+ * outputs, the inputs, and the output of each workflow by name. The streams, the
+ * events, and the notifications each hold an `ON DELETE CASCADE` foreign key to
  * `workflow_status`, so they go with the status row.
  */
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
 import type { WorkflowPurger } from "./workflow-purger.js";
-export interface DbosWorkflowPurgerDeps {
+export type DbosWorkflowPurgerDeps = {
     /** Pool onto the engine's system database — the same database the application pool holds. */
     readonly pool: Pool;
     readonly logger?: Logger;
-}
+};
+export declare function dbosClientFor(pool: Pool, logger: Logger): Promise<DBOSClient>;
 export declare function createDbosWorkflowPurger({ pool, logger: injected }: DbosWorkflowPurgerDeps): WorkflowPurger;

package/dist/execution/dbos-workflow-purger.js

@@ -13,12 +13,13 @@
  * injected pool already reaches the ledger.
  *
  * The engine owns the deletion itself, including the breadth-first walk over
- * `parent_workflow_id` that reaches child step workflows. Its single
- * `DELETE FROM dbos.workflow_status WHERE workflow_uuid = ANY(...)` is all the
- * dependent tables need: step outputs, streams, inputs, events, notifications,
- * and queue rows each hold an `ON DELETE CASCADE` foreign key to
+ * `parent_workflow_id` that reaches child step workflows. It deletes the step
+ * outputs, the inputs, and the output of each workflow by name. The streams, the
+ * events, and the notifications each hold an `ON DELETE CASCADE` foreign key to
  * `workflow_status`, so they go with the status row.
  */
+import { textOf } from "../lib/unknown-text.js";
+import { z } from "zod";
 import { DBOSClient } from "@dbos-inc/dbos-sdk";
 import { errAsync, okAsync } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -36,9 +37,9 @@ const SYSTEM_SCHEMA = "dbos";
  * the first is nothing to purge, so the code on its own settles nothing.
  */
 const UNDEFINED_TABLE = "42P01";
+const UndefinedTableCause = z.object({ code: z.literal(UNDEFINED_TABLE) });
 function isUndefinedTable(e) {
-    const cause = e.cause;
-    return cause !== null && typeof cause === "object" && "code" in cause && cause.code === UNDEFINED_TABLE;
+    return UndefinedTableCause.safeParse(e.cause).success;
 }
 /**
  * Route the client's own diagnostics — pool errors and idle-client errors — onto
@@ -56,7 +57,7 @@ function isUndefinedTable(e) {
  * message and drops the one stack the SDK bothered to hand over.
  */
 function asEngineLogger(logger) {
-    const render = (entry) => (typeof entry === "string" ? entry : String(entry));
+    const render = (entry) => (typeof entry === "string" ? entry : textOf(entry));
     return {
         debug: (entry) => logger.debug(render(entry)),
         info: (entry) => logger.info(render(entry)),
@@ -64,23 +65,30 @@ function asEngineLogger(logger) {
         error: (entry, metadata) => logger.error(render(entry), metadata?.stack === undefined ? undefined : { stack: metadata.stack }),
     };
 }
-export function createDbosWorkflowPurger({ pool, logger: injected }) {
-    const logger = (injected ?? createNoopLogger()).named("workflow-purger");
-    // One client per factory, not per call. Creating a client does no I/O, but the
-    // client registers `error` and `connect` handlers on the pool it is handed, so a
-    // client per purge would accumulate handler pairs on a long-lived pool. Its
-    // `destroy()` ends that pool, so a client over an injected pool must never be
-    // destroyed either — which leaves a per-call client nothing to release. Creation
-    // is lazy so building a purger stays free for a host that never purges.
-    let pending;
-    const engine = () => {
+/**
+ * One client for each pool, shared by every purger and by the run canceler. A client registers
+ * `error` and `connect` handlers on the pool it is handed, so a client for each caller would
+ * accumulate handler pairs on a long-lived pool. Its `destroy()` ends that pool, so a client over
+ * an injected pool must never be destroyed either — which leaves a per-call client nothing to
+ * release. Creation is lazy so a host that never reaches the engine builds no client. The logger of
+ * the first caller for a pool becomes the engine logger of that pool.
+ */
+const clients = new WeakMap();
+export function dbosClientFor(pool, logger) {
+    let client = clients.get(pool);
+    if (client === undefined) {
         // `create` never initializes the system database, and initialization is the
         // only path that reads the connection string once a pool is supplied — so the
         // url is unreachable from this client rather than merely untaken, and there is
-        // none to thread through the seam.
-        pending ??= DBOSClient.create({ systemDatabaseUrl: "", systemDatabasePool: pool, logger: asEngineLogger(logger) });
-        return pending;
-    };
+        // no url to pass.
+        client = DBOSClient.create({ systemDatabaseUrl: "", systemDatabasePool: pool, logger: asEngineLogger(logger) });
+        clients.set(pool, client);
+    }
+    return client;
+}
+export function createDbosWorkflowPurger({ pool, logger: injected }) {
+    const logger = (injected ?? createNoopLogger()).named("workflow-purger");
+    const engine = () => dbosClientFor(pool, logger);
     /**
      * Whether the engine's schema exists at all — the only thing that separates a
      * ledger the engine never created from one that is broken. It costs a round trip

package/dist/execution/input-signature.d.ts

@@ -15,7 +15,7 @@
 import type { DataProfileInputSignature } from "../state/data-profile.js";
 import type { StagedInput } from "./staged-input.js";
 /** The fields a signature covers. A manifest entry satisfies it structurally. */
-export interface SignableInput {
+export type SignableInput = {
     readonly fileId: string;
     readonly size: number;
     readonly mtimeMs?: number;
@@ -25,7 +25,7 @@ export interface SignableInput {
      * not junk, and dropping it would be the one outcome worse than including it.
      */
     readonly relativePath?: string;
-}
+};
 /**
  * Digest a staged input set, quarantine first.
  *

package/dist/execution/post-step-pipeline.d.ts

@@ -12,10 +12,10 @@
  * fail-fast vs. best-effort. This module owns only the stage bodies.
  */
 import { type Result } from "neverthrow";
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { LoopMessage } from "../loop/types.js";
-import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
+import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
@@ -29,24 +29,24 @@ import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflo
  * The subset of `SandboxStepDeps` the post-step stages consume. The sandbox-step
  * body passes its own `deps` straight through (it is a structural superset).
  */
-export interface PostStepPipelineDeps {
-    readonly pool: Pool;
+export type PostStepPipelineDeps = {
+    readonly pool: Querier;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** LLM usage-accounting seam for the metadata + summary continuations; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** The store of the task, thus a reference of the task stays readable in the metadata + summary continuations. */
     readonly toolOutputStore?: ToolOutputStore;
-    /** Non-streaming chat — the provider of the task, which the metadata + summary continuations extend. */
-    readonly provider: AgentChat;
+    /** The provider of the task, which the metadata and summary follow-up requests extend. */
+    readonly provider: ChatProvider;
     /** Write-side embedder for the vector index. */
     readonly embedding: EmbeddingProvider;
     readonly artifactRegistry: ArtifactRegistry;
     /** Workspace-root resolution seam (see workspace/paths.ts). */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
-}
+};
 /** The product of the file-metadata stage, as its `DBOS.runStep` checkpoints it. */
-export interface StepFileMetadata {
+export type StepFileMetadata = {
     /** One entry per manifest file, described or fallback. */
     readonly entries: readonly FileMetadataEntry[];
     /**
@@ -54,7 +54,7 @@ export interface StepFileMetadata {
      * `DBOS.runStep`, so a replay must give the summary the same prefix.
      */
     readonly messages: readonly LoopMessage[];
-}
+};
 /** Describes each manifest file; a file the model cannot describe gets a deterministic fallback, never a dropped entry. */
 export declare function generateStepFileMetadata(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<StepFileMetadata>;
 /**

package/dist/execution/post-step-pipeline.js

@@ -123,7 +123,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         agentId: input.agentId,
         manifest: [...manifest],
         collector: lineageCollector,
-        ...(deps.logger ? { logger: deps.logger } : {}),
+        logger: deps.logger,
     });
     if (reconciled.manifest.length === 0)
         return ok(reconciled.manifest);

package/dist/execution/post-step.js

@@ -12,6 +12,7 @@ import { join, relative } from "node:path";
 import { inferArtifactType } from "../schemas/artifact-manifest.js";
 import { computeSha256File } from "../lib/fs-helpers.js";
 import { IGNORED_DIRS } from "../sandbox/ignored-dirs.js";
+import { errnoOf } from "../lib/fs-result.js";
 /**
  * Walk a step's writable artifact directory and produce a fully-hashed
  * `ArtifactManifestEntry[]`. Skips IGNORED_DIRS. Paths are relative to
@@ -26,8 +27,7 @@ export async function walkStepArtifacts(args) {
             entries = await readdir(dir, { withFileTypes: true });
         }
         catch (err) {
-            const code = err.code;
-            if (code === "ENOENT")
+            if (errnoOf(err) === "ENOENT")
                 return;
             throw err;
         }

package/dist/execution/reconcile-manifest.d.ts

@@ -1,7 +1,7 @@
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { ProvenanceCollector } from "../provenance/collector.js";
 import type { Logger } from "../lib/logger.js";
-export interface ReconcileManifestInput {
+export type ReconcileManifestInput = {
     /** Absolute host root of the analysis's workspace tree. */
     workspaceRoot: string;
     /** Analysis (resource) ID. */
@@ -22,11 +22,11 @@ export interface ReconcileManifestInput {
      * the sole account of why lineage changed or a step died.
      */
     logger?: Logger;
-}
-export interface ReconcileManifestResult {
+};
+export type ReconcileManifestResult = {
     /** Reconciled manifest — phantoms removed, every entry rehashed from disk. */
     manifest: ArtifactManifestEntry[];
     /** Number of entries dropped because their file was missing. */
     droppedCount: number;
-}
+};
 export declare function reconcileManifestWithDisk(input: ReconcileManifestInput): Promise<ReconcileManifestResult>;

package/dist/execution/reconcile-manifest.js

@@ -24,6 +24,7 @@ import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { classifyWithinRoot, computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
 import { recordArtifactReconcileDropped, recordLineageInputDropped } from "../lib/metrics.js";
+import { errnoOf } from "../lib/fs-result.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -58,7 +59,7 @@ export async function reconcileManifestWithDisk(input) {
             info = await stat(absPath);
         }
         catch (err) {
-            if (err.code === "ENOENT") {
+            if (errnoOf(err) === "ENOENT") {
                 logger.debug("dropping phantom entry", { path: entry.path });
                 collector.removeRecord(entry.path);
                 droppedCount++;
@@ -168,7 +169,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             info = await stat(hostPath);
         }
         catch (err) {
-            if (err.code === "ENOENT") {
+            if (errnoOf(err) === "ENOENT") {
                 // Warn, not debug: a capture layer named a file this step never
                 // consumed, and the count of those is how a reader tells a noisy
                 // hook from an artifact that genuinely vanished under the step.

package/dist/execution/run-authorizer.d.ts

@@ -1,63 +1,72 @@
 /**
- * RunAuthorizer — the async-edge run-authorization seam.
+ * RunAuthorizer — run authorization at the async edge.
  *
  * Every async edge that starts durable work (`execute_analysis`,
  * data-profile) must turn the caller's opaque auth into a durable `RunSession`
  * before dispatching a workflow. That turning is the ONE place the credential
- * kind matters (a live caller credential → mint a fresh run credential Cortex
- * owns; an existing run credential → reuse it, caller-owned) — so it lives
- * behind this seam, not in the harness tools. The managed impl owns the
- * mint/reuse + revoke against the host authority; an OSS impl issues a local
- * `RunSession` with no host call, no jti, no revoke. The harness's tools depend only on
- * this interface and never read a credential.
+ * kind matters (a live caller credential → create a run credential; a run
+ * credential handed over by the caller → take it) — so it lives in this
+ * interface, not in the harness tools. Either way the work owns the credential.
+ * An OSS impl issues a local `RunSession` with no host call and nothing to
+ * revoke. The harness's tools depend only on this interface and never read a
+ * credential.
  *
- * Mirrors the `SessionPagePublisher` seam: a narrow interface in the harness, the managed
+ * Mirrors `SessionPagePublisher`: a narrow interface in the harness, the managed
  * realization injected at the composition root.
  */
 import type { ResultAsync } from "neverthrow";
 import type { AuthContext, Provenance, RunFrame, RunSession, Scope } from "../auth/types.js";
 import type { GateFailure, NoticeFailure } from "../lib/hooks.js";
 /**
- * Locates a run credential when no `RunAuthorization` exists: the persisted
- * jti from `cortex_runs` plus the revoking caller's opaque `auth` — the sole
- * carrier of credential/org behind a session, downcast only by managed
+ * Locates a run credential when no `RunSession` exists: the persisted
+ * mandate id from `cortex_runs` plus the revoking caller's opaque `auth` — the
+ * sole carrier of credential/org behind a session, downcast only by managed
  * realizations.
  */
-export interface RevokeByJtiRef {
-    readonly jti: string;
+export type RevokeByMandateRef = {
+    readonly mandateId: string;
     readonly auth: AuthContext;
-}
+};
 /** What an async edge knows when it authorizes a run: the opaque caller auth,
  * the scope + provenance to stamp on the run, and the run frame to mint for. */
-export interface AuthorizeRunInput {
+export type AuthorizeRunInput = {
     readonly auth: AuthContext;
     readonly scope: Scope;
     readonly provenance: Provenance;
     readonly frame: RunFrame;
-}
-export interface RunAuthorization {
-    readonly runSession: RunSession;
-    /**
-     * True when this authorizer minted the run credential and therefore owns its
-     * lifecycle — the run's terminal path must `revoke`. False when an existing
-     * run credential was reused (the caller owns it; `revoke` is a no-op).
-     */
-    readonly ownsMandate: boolean;
-}
+};
 /**
  * Authorize durable work at the async edge. `authorize` produces the durable
- * `RunSession`; `revoke` releases a self-minted run credential on the terminal
- * path (a no-op for reused or local authorizations).
+ * `RunSession`. The terminal path of the work revokes the mandate that the work
+ * holds, whoever created it; a realization with no mandate does nothing in
+ * `revoke`.
+ *
+ * The `RunSession` is a durable reference to the run credential, not a
+ * time-bound secret: the work has no time limit, and a pause can last days. A
+ * realization resolves the reference to a short-lived credential where it
+ * calls its host, and `suspend` and `renew` follow the pause of the work.
  */
-export interface RunAuthorizer {
-    authorize(input: AuthorizeRunInput): ResultAsync<RunAuthorization, GateFailure>;
-    revoke(authorization: RunAuthorization, reason: string): ResultAsync<void, NoticeFailure>;
+export type RunAuthorizer = {
+    authorize(input: AuthorizeRunInput): ResultAsync<RunSession, GateFailure>;
+    revoke(runSession: RunSession, reason: string): ResultAsync<void, NoticeFailure>;
+    /**
+     * Out-of-band revocation for paths holding no `RunSession`. Normal
+     * terminal paths use `revoke(runSession, reason)` under the run
+     * credential; `revokeByMandateId` covers external cancellation, where only
+     * the reference on `cortex_runs` survives. Local/OSS authorizers no-op —
+     * they record no reference.
+     */
+    revokeByMandateId(ref: RevokeByMandateRef, reason: string): ResultAsync<void, NoticeFailure>;
+    /**
+     * The work paused and waits for a person: stop the run credential until a
+     * renewal. A notice — the work waits whatever the outcome. A wait that only
+     * a timer ends does not suspend, because no person resumes it.
+     */
+    suspend(runSession: RunSession, reason: string): ResultAsync<void, NoticeFailure>;
     /**
-     * Out-of-band revocation for paths holding no `RunAuthorization`. Normal
-     * terminal paths use `revoke(authorization, reason)` under the run
-     * credential; `revokeByJti` covers external cancellation, where the run
-     * credential's JWT was never persisted and only its jti survives on
-     * `cortex_runs`. Local/OSS authorizers no-op — they mint no jti.
+     * A person resumes paused work: renew the run credential under the opaque
+     * `auth` of that person. A gate — a refusal keeps the work paused and sends
+     * no resume.
      */
-    revokeByJti(ref: RevokeByJtiRef, reason: string): ResultAsync<void, NoticeFailure>;
-}
+    renew(runSession: RunSession, auth: AuthContext): ResultAsync<void, GateFailure>;
+};

package/dist/execution/run-authorizer.js

@@ -1,17 +1,17 @@
 /**
- * RunAuthorizer — the async-edge run-authorization seam.
+ * RunAuthorizer — run authorization at the async edge.
  *
  * Every async edge that starts durable work (`execute_analysis`,
  * data-profile) must turn the caller's opaque auth into a durable `RunSession`
  * before dispatching a workflow. That turning is the ONE place the credential
- * kind matters (a live caller credential → mint a fresh run credential Cortex
- * owns; an existing run credential → reuse it, caller-owned) — so it lives
- * behind this seam, not in the harness tools. The managed impl owns the
- * mint/reuse + revoke against the host authority; an OSS impl issues a local
- * `RunSession` with no host call, no jti, no revoke. The harness's tools depend only on
- * this interface and never read a credential.
+ * kind matters (a live caller credential → create a run credential; a run
+ * credential handed over by the caller → take it) — so it lives in this
+ * interface, not in the harness tools. Either way the work owns the credential.
+ * An OSS impl issues a local `RunSession` with no host call and nothing to
+ * revoke. The harness's tools depend only on this interface and never read a
+ * credential.
  *
- * Mirrors the `SessionPagePublisher` seam: a narrow interface in the harness, the managed
+ * Mirrors `SessionPagePublisher`: a narrow interface in the harness, the managed
  * realization injected at the composition root.
  */
 export {};