@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/workspace/workspace-search.js

@@ -15,20 +15,29 @@ import { z } from "zod";
 import { scopeResource } from "../../auth/types.js";
 import { tryQuery } from "../../lib/db-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 import { defineTool } from "../define-tool.js";
 /** pgvector / Postgres "undefined_table" — the index has no rows indexed yet. */
 const UNDEFINED_TABLE = "42P01";
 /** True when a captured driver cause is the "undefined_table" SQLSTATE. */
+const UndefinedTableCause = z.object({ code: z.literal(UNDEFINED_TABLE) });
 function isUndefinedTable(cause) {
-    return !!cause && typeof cause === "object" && cause.code === UNDEFINED_TABLE;
+    return UndefinedTableCause.safeParse(cause).success;
 }
 function indexName(analysisId) {
-    const name = `search_${analysisId.replace(/-/g, "_")}`;
-    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    const name = `search_${analysisId.replaceAll("-", "_")}`;
+    if (!isSqlIdentifier(name)) {
         throw new Error(`workspaceSearch: unusable analysis id "${analysisId}"`);
     }
     return name;
 }
+function isSqlIdentifier(name) {
+    if (name.length === 0)
+        return false;
+    const isLetterOrUnderscore = (char) => (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || char === "_";
+    const isWordChar = (char) => isLetterOrUnderscore(char) || (char >= "0" && char <= "9");
+    return isLetterOrUnderscore(name.charAt(0)) && Array.from(name).every(isWordChar);
+}
 /** Entry types that address a pattern spanning many files, never a single one. */
 const PATTERN_TYPES = new Set(["input-group", "input-dimension", "input-kind"]);
 /**
@@ -39,7 +48,7 @@ const PATTERN_TYPES = new Set(["input-group", "input-dimension", "input-kind"]);
  * segment. The consumer branches on presence, nothing else.
  */
 export function fileTargetOf(id, metadata) {
-    const meta = metadata && typeof metadata === "object" ? metadata : {};
+    const meta = parseUnknownRecord(metadata) ?? {};
     const type = typeof meta.type === "string" ? meta.type : undefined;
     if (type !== undefined && PATTERN_TYPES.has(type))
         return undefined;
@@ -47,8 +56,19 @@ export function fileTargetOf(id, metadata) {
         return undefined;
     if (typeof meta.path === "string")
         return meta.path;
-    return id.replace(/^\/[^/]+\//, "");
+    if (!id.startsWith("/"))
+        return id;
+    const afterResource = id.indexOf("/", 1);
+    return afterResource === -1 ? id : id.slice(afterResource + 1);
 }
+const WorkspaceSearchInputSchema = z.object({
+    query: z.string().min(1).describe("What to search for, in natural language"),
+    type: z
+        .enum(["input-group", "input-dimension", "input", "input-kind", "output", "summary", "synthesis"])
+        .optional()
+        .describe('Restrict results to one entry type: "input-group", "input-dimension", "input", "input-kind", "output", "summary", or "synthesis"'),
+    limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
+});
 export function createWorkspaceSearchTool(pool, embedding) {
     return defineTool({
         id: "workspace_search",
@@ -68,14 +88,7 @@ export function createWorkspaceSearchTool(pool, embedding) {
             "metadata, e.g. search input-group for a group's display pattern, then list the tree for " +
             "its members. Most input files carry no entry of their own — find them through their " +
             "group and the listing tools.",
-        inputSchema: z.object({
-            query: z.string().min(1).describe("What to search for, in natural language"),
-            type: z
-                .enum(["input-group", "input-dimension", "input", "input-kind", "output", "summary", "synthesis"])
-                .optional()
-                .describe('Restrict results to one entry type: "input-group", "input-dimension", "input", "input-kind", "output", "summary", or "synthesis"'),
-            limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
-        }),
+        inputSchema: WorkspaceSearchInputSchema,
         describeCall: ({ query, type }) => (type === undefined ? query : `${query} (${type})`),
         execute: async ({ query, type, limit }, ctx) => {
             const [vector] = unwrapOrThrow(await embedding.embed([query], ctx.session));
@@ -108,7 +121,7 @@ export function createWorkspaceSearchTool(pool, embedding) {
                     return {
                         id: r.id,
                         score: r.score,
-                        ...(path !== undefined ? { path } : {}),
+                        path,
                         metadata: r.metadata,
                     };
                 }),

package/dist/tools/workspace/write-file.d.ts

@@ -7,7 +7,8 @@
  * declares the input schema, forwards the write, and carries the record of the
  * write to the fold. `edit_file` rides the same seam.
  */
-import { type WithToolCallRecord } from "../define-tool.js";
+import { z } from "zod";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
 import type { WorkspaceMutator, WriteFileResult, WriteRecord } from "./mutator.js";
 /** The result of a `write_file` call: a success carries the record of the write for the fold. */
 type WriteFileToolResult = Exclude<WriteFileResult, {
@@ -15,11 +16,12 @@ type WriteFileToolResult = Exclude<WriteFileResult, {
 }> | WithToolCallRecord<Extract<WriteFileResult, {
     status: "ok";
 }>, WriteRecord>;
-export interface WriteFileDeps {
+declare const WriteFileInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WriteFileDeps = {
     readonly mutator: WorkspaceMutator;
-}
-export declare function createWriteFileTool(deps: WriteFileDeps): import("../define-tool.js").Tool<{
-    path: string;
-    content: string;
-}, WriteFileToolResult>;
+};
+export declare function createWriteFileTool(deps: WriteFileDeps): Tool<z.infer<typeof WriteFileInputSchema>, WriteFileToolResult>;
 export {};

package/dist/workflows/execute-analysis-scheduler.d.ts

@@ -22,18 +22,18 @@ import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
  * The minimum shape the scheduler needs from a plan step. Larger workflow-state
  * schemas are a superset of this, keeping the scheduler decoupled.
  */
-export interface PlanStep {
+export type PlanStep = {
     readonly id: string;
     readonly depends_on: readonly string[];
-}
+};
 /** Budget-admission inputs — the snapshotted machine budget from the workflow
  *  input plus each step's plan-declared resources. */
-export interface BudgetAdmission {
+export type BudgetAdmission = {
     readonly budget: MachineBudget;
     readonly resourcesByStepId: Readonly<Record<string, ResourceSpec>>;
-}
+};
 /** Partition of the dependency-satisfied steps under budget admission. */
-export interface ScheduledSteps {
+export type ScheduledSteps = {
     /** Steps to start now — they fit the remaining budget capacity. */
     readonly admit: readonly string[];
     /** Dependency-satisfied steps held until in-flight steps free capacity. */
@@ -41,7 +41,7 @@ export interface ScheduledSteps {
     /** Steps whose declared resources exceed the budget outright — they could
      *  never be admitted even against an empty budget. */
     readonly neverFits: readonly string[];
-}
+};
 /** Thrown when the plan DAG contains a dependency cycle. */
 export declare class CycleError extends Error {
     readonly involvedSteps: readonly string[];
@@ -80,8 +80,8 @@ export declare function validatePlanDag<S extends PlanStep>(steps: readonly S[])
  * not fit never blocks a later, smaller one. Determinism holds because every
  * input derives from the workflow input and checkpointed completion state.
  */
-export declare function scheduleReady<S extends PlanStep>(steps: readonly S[], completedSet: ReadonlySet<string>, startedSet?: ReadonlySet<string>): string[];
-export declare function scheduleReady<S extends PlanStep>(steps: readonly S[], completedSet: ReadonlySet<string>, startedSet: ReadonlySet<string>, admission: BudgetAdmission): ScheduledSteps;
+export declare function scheduleReady(steps: readonly PlanStep[], completedSet: ReadonlySet<string>, startedSet?: ReadonlySet<string>): string[];
+export declare function scheduleReady(steps: readonly PlanStep[], completedSet: ReadonlySet<string>, startedSet: ReadonlySet<string>, admission: BudgetAdmission): ScheduledSteps;
 /**
  * Compute a depth per step. A step with no dependencies is level 0; a step
  * with deps is `max(level(dep)) + 1`. Used by the UI for column layout in
@@ -91,4 +91,4 @@ export declare function scheduleReady<S extends PlanStep>(steps: readonly S[], c
  * Pre-condition: `validatePlanDag` has been called (no cycles, no missing
  * deps). Behaviour is undefined on an invalid DAG.
  */
-export declare function computeTopologicalLevels<S extends PlanStep>(steps: readonly S[]): Map<string, number>;
+export declare function computeTopologicalLevels(steps: readonly PlanStep[]): Map<string, number>;

package/dist/workflows/execute-analysis-scheduler.js

@@ -17,6 +17,7 @@
  * pure means parent recovery replays the same dispatch sequence given the
  * same persisted child outcomes.
  */
+import { presentGet, presentLast } from "../lib/present.js";
 // ── Errors ───────────────────────────────────────────────────────────
 /** Thrown when the plan DAG contains a dependency cycle. */
 export class CycleError extends Error {
@@ -83,10 +84,12 @@ function detectCycle(steps) {
         if (state.get(start.id) === DONE)
             continue;
         // Iterative DFS — preserves the in-progress chain so we can report it.
-        const stack = [{ id: start.id, iter: stepById.get(start.id).depends_on[Symbol.iterator]() }];
+        const stack = [
+            { id: start.id, iter: presentGet(stepById, start.id, "the step of the cycle walk").depends_on[Symbol.iterator]() },
+        ];
         state.set(start.id, VISITING);
         while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
+            const frame = presentLast(stack, "the top frame of the cycle walk");
             const next = frame.iter.next();
             if (next.done) {
                 state.set(frame.id, DONE);
@@ -105,7 +108,7 @@ function detectCycle(steps) {
             state.set(childId, VISITING);
             stack.push({
                 id: childId,
-                iter: stepById.get(childId).depends_on[Symbol.iterator](),
+                iter: presentGet(stepById, childId, "the dependency step of the cycle walk").depends_on[Symbol.iterator](),
             });
         }
     }

package/dist/workflows/execute-analysis.d.ts

@@ -39,64 +39,62 @@
  *       `partial`).
  *     - the halt cascade (cancel in-flight via
  *       `Promise.allSettled(handles.map(h => DBOS.cancelWorkflow(h.workflowID)))`,
- *       stop scheduling) survives only for a suspension of a child and the
- *       `neverFits` plan-validation guard.
- *  4. Suspension cascade (workflow-suspension spec)
- *     - a child that suspends sends a typed message on `CHILD_SUSPENDED_TOPIC`
- *       and cancels itself. The parent reads the kind of the message, never a
- *       reason string: it cancels the siblings, then self-cancels to
- *       `CANCELLED` (NOT `ERROR` — ERROR isn't resumable; NOTES #3)
- *     - a refusal of the `RunCharge.open` gate with the suspend flag suspends
- *       the run before any step starts
- *     - a `suspend` error of a synthesis model request suspends the run in
- *       place of the synthesis failure
- *     - the run row and the analysis flip to `suspended_insufficient_funds` in
- *       `collectAndComplete`. The run status is terminal and does not block a
- *       new run of the plan. The paused parent lands in `CANCELLED`, a
- *       durably reschedulable state; re-driving it is a future enhancement,
- *       not yet wired here. The reason of the host rides to the run row, the
- *       charge close, the metric, and the terminal part, unread.
+ *       stop scheduling) survives only for the `neverFits` plan-validation guard.
+ *  4. Pause (work-pause spec)
+ *     - a step pauses in its own workflow, and the parent waits for its result as
+ *       for a step that runs. The other steps go on, and the run row stays
+ *       `running`
+ *     - a refusal of the `RunCharge.open` gate with the suspend flag pauses the
+ *       run before any step starts, and the charge opens again after the resume
+ *     - a failed model request of the synthesis with a cause of a pause waits in
+ *       the loop of the synthesizer
  *  5. `synthesizeFindings` (single sequential block, no sandbox)
  *  6. `collectAndComplete` (terminal — runs on ALL paths)
  *     - determine final status from completed/cancelled/failed counts
- *     - update `cortex_runs.status` + `error`, and inside that same step record
- *       the run outcome metric plus the outcome of every settled step whose
- *       child never wrote its own terminal row (a cancelled child, or one that
- *       died before `failStep`)
- *     - close running charge with matching reason
- *     - revoke run authorization via the injected `runAuthorizer` seam
+ *     - update `cortex_runs.status` + `error`. When the write changes the row,
+ *       the same step emits `run_completed` before the commit, records the run
+ *       outcome metric plus the outcome of every settled step whose child never
+ *       wrote its own terminal row (a cancelled child, or one that died before
+ *       `failStep`), closes the running charge with the matching outcome, and
+ *       revokes the run authorization through the injected `runAuthorizer`
+ *     - the write retries with backoff on a failed transaction. When the write is
+ *       refused, or fails on each attempt, close and revoke in their own steps, then
+ *       emit `run_completed`. After a failed write the row stays `running`, so the
+ *       body records its run end as a workflow event for the run canceler
  *     - emit terminal stream part
  *     - WRITES NOTHING to the conversation thread (results are pull-only
  *       via `inspectRun`)
  */
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
-import type { CitationResolver } from "../citations/types.js";
+import { type Connectable } from "../lib/db-result.js";
 import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.js";
 import { type StepBriefing } from "../prompts/briefing.js";
 import type { WorkingMemoryStore } from "../memory/working-memory.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
-import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { KnowledgeClient } from "../tools/knowledge/client.js";
+import type { TemplateBinding } from "../tools/knowledge/template.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
+import type { Tool } from "../tools/define-tool.js";
 import type { RunCharge } from "../billing/run-charge.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type PlanStep } from "./execute-analysis-scheduler.js";
-import { type SandboxStepInput, type SandboxStepResult } from "./sandbox-step.js";
-import { type Suspension } from "./suspension.js";
+import { type WorkPause } from "./pause.js";
+import type { SandboxStepInput, SandboxStepResult } from "./sandbox-step.js";
 /** Registered child sandbox-step callable the parent's child-dispatch closes over. */
 type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /** Quick-display finding on the run-completed card. Mirrors the wire schema's RunCompletedFinding. */
-export interface RunFinding {
+export type RunFinding = {
     readonly title: string;
     readonly confidence: "high" | "medium" | "low";
-}
-export interface ExecuteAnalysisInput {
+};
+export type ExecuteAnalysisInput = {
     readonly analysisId: string;
     /** Plan id — the dedup key for the partial-unique index on cortex_runs. */
     readonly planId: string;
@@ -145,31 +143,21 @@ export interface ExecuteAnalysisInput {
      * resume — no DB read, no in-process cache.
      */
     readonly runSession: RunSession;
-    /**
-     * True when Cortex owns the run-authorization lifecycle and therefore must
-     * revoke it on the terminal path. The ownership decision is made by the
-     * `RunAuthorizer` seam at the async edge (`executePlan`).
-     *
-     * Optional because a workflow persisted before this field existed (recovered
-     * across the deploy that added it) deserializes without it; the body defaults
-     * absent → true, matching the prior Cortex-owned behavior.
-     */
-    readonly ownsMandate?: boolean;
-}
+};
 /**
  * Outcome of the trigger. `running` is what the dedup-collision recovery
  * path returns — the caller joined an in-flight run, no new workflow was
  * started. Every other variant is a terminal status the parent reached.
  */
-export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds";
-export interface ExecuteAnalysisResult {
+export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled";
+export type ExecuteAnalysisResult = {
     readonly runId: string;
     readonly workflowId: string;
     readonly status: ExecuteAnalysisFinalStatus;
     readonly completedSteps: readonly string[];
     readonly failedSteps: readonly string[];
     readonly canceledSteps: readonly string[];
-}
+};
 /**
  * A step's in-run display state. Wider than the ledger's `StepExecutionStatus`: `queued` is a
  * scheduler-only condition (dependency-satisfied but held for budget capacity) that never reaches a
@@ -183,14 +171,14 @@ export type StepRuntimeStatus = "pending" | "queued" | "running" | "completed" |
  * that says what the step is FOR. `durationMs` and `error` appear only once the step has settled
  * in a way that produced them.
  */
-export interface RunStepObservation {
+export type RunStepObservation = {
     readonly id: string;
     readonly name: string;
     readonly agent: string;
     readonly status: StepRuntimeStatus;
     readonly durationMs?: number;
     readonly error?: string;
-}
+};
 /**
  * A whole-run snapshot handed to {@link ExecuteAnalysisDeps.observeRun}.
  *
@@ -205,14 +193,14 @@ export interface RunStepObservation {
  * computable from `steps` and recorded authoritatively on the run's ledger row; carrying them here
  * would mint a second source that can disagree with the ledger a host also reads.
  */
-export interface RunObservation {
+export type RunObservation = {
     readonly runId: string;
     readonly analysisId: string;
     /** `running` for every mid-flight snapshot; the derived terminal status on the last one. */
     readonly status: ExecuteAnalysisFinalStatus;
     /** Every plan step, including ones that have not started — never a delta. */
     readonly steps: readonly RunStepObservation[];
-}
+};
 /**
  * Construction-time deps for the parent workflow. The order-of-operations is
  * the body's own: it brackets the run, dispatches children, and synthesizes
@@ -221,10 +209,10 @@ export interface RunObservation {
  * registered sandbox-step callable — plus the construction inputs (provider,
  * embedder, model, keys, roots) the in-body synthesis needs.
  */
-export interface ExecuteAnalysisDeps {
+export type ExecuteAnalysisDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-    readonly pool: Pool;
+    readonly pool: Querier & Connectable;
     /** Chat provider for the in-body literature-grounded synthesis. */
     readonly provider: ChatProvider;
     /** Write-side embedder for indexing the run synthesis. */
@@ -235,12 +223,12 @@ export interface ExecuteAnalysisDeps {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Model id for the synthesizer agent loop. */
     readonly synthesisModel: string;
-    /** API keys for the bio/chem tools the embedded literature reviewer uses. */
-    readonly bioKeys: BioToolKeys;
-    /** Shared resolver for the literature reviewer used during synthesis. */
-    readonly citationResolver: CitationResolver;
+    /** The `literature_reviewer` tool of the synthesis. The runtime registers its sub-agent one time. */
+    readonly literatureReviewer: Tool;
     /** Run-level billing-bracket seam (managed: external bracket; OSS: no-op). */
     readonly runCharge: RunCharge;
+    /** The delays of the timer of an outage. Absent: the default of the pause. */
+    readonly pauseRetryDelaysMs?: readonly number[];
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;
     /**
@@ -256,16 +244,27 @@ export interface ExecuteAnalysisDeps {
      * carries the goal and the constraints as they are at the dispatch of that step.
      */
     readonly workingMemory: WorkingMemoryStore;
+    /**
+     * The knowledge client of the composition, when the embedder binds one.
+     * The seed composition reads the contract of the template a grounded step
+     * renders through it, and binds the plan settings to that contract.
+     * Absent, the seed says the contract was not retrieved, and the step agent
+     * learns the slots from the render answers alone.
+     */
+    readonly knowledge?: KnowledgeClient;
     /**
      * The provenance seam of the composition. The body reads its run emit member,
      * and it reads no other member.
      *
-     * The emit is deliberately invoked directly in the workflow body (NOT wrapped
-     * in `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
-     * a cached step would suppress the recovery re-emission, defeating the
-     * point. Idempotency is the consumer's job, achieved via the deterministic
-     * identifiers the events carry, not via step caching. Every call site is
-     * guarded so a throwing observer never fails the run.
+     * `run_started` and `step_completed` are emitted directly in the workflow body
+     * (NOT wrapped in `DBOS.runStep`) so that body re-execution on DBOS recovery
+     * re-fires them — a cached step would suppress the recovery re-emission.
+     * `run_completed` is emitted by the won `persist-final-status` step, or by the
+     * body after that step when the step did not emit in this execution (a refused
+     * or failed write, or a won step served from the DBOS cache), so a recovery
+     * replay still fires it. Idempotency is the consumer's job, achieved via the
+     * deterministic identifiers the events carry, not via step caching. Every call
+     * site is guarded so a throwing observer never fails the run.
      *
      * Events arrive with the run's `RunSession` from durable workflow input — a
      * persisting realization needs its credential, scope, and identity.
@@ -292,7 +291,7 @@ export interface ExecuteAnalysisDeps {
      * throwing observer never fails the run.
      */
     readonly observeRun?: (observation: RunObservation) => void;
-}
+};
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
  * level computation and the seed (`prompt`, composed by `composeStepSeed` at
@@ -305,8 +304,8 @@ export declare function buildChildInput(args: {
     stepId: string;
     level: number;
     runId: string;
-    workflowId: string;
     prompt: string;
+    templateBinding?: TemplateBinding;
 }): Omit<SandboxStepInput, "runSession">;
 /**
  * Compose one step's seed — the user-content message its agent opens on.
@@ -317,17 +316,26 @@ export declare function buildChildInput(args: {
  * rendered any earlier (at plan submission, say) cannot mention them, and the
  * agent is left to rediscover its own upstream.
  *
- * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
- * checkpointed and a replay returns it verbatim — the DB and disk are not read
- * again and cannot drift the seed under a recovered run. Never call it
- * unwrapped from the workflow body.
+ * The template contract of a grounded step is read with the package, and the
+ * plan settings are bound to it: the seed describes the binding, and the child
+ * input carries it, from one checkpoint. The child fetches nothing.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed seed is
+ * checkpointed and a replay returns it verbatim — the DB, the disk, and the
+ * knowledge service are not read again and cannot drift the seed under a
+ * recovered run. Never call it unwrapped from the workflow body.
  */
 export declare function composeStepSeed(args: {
     input: ExecuteAnalysisInput;
     stepId: string;
     runId: string;
     deps: ExecuteAnalysisDeps;
-}): Promise<string>;
+}): Promise<StepSeed>;
+/** What `gatherStepPackage` gives: the data of the seed, and the binding of the plan settings when one holds. */
+export type StepPackage = {
+    readonly briefing: StepBriefing;
+    readonly templateBinding?: TemplateBinding;
+};
 /**
  * Do every read of one step's package and give the data its seed is rendered
  * from. All reads live here, so `composeStepBriefing` stays a pure renderer.
@@ -340,6 +348,9 @@ export declare function composeStepSeed(args: {
  * so an edit during a run reaches each later step, and two steps of one run
  * can carry different copies.
  *
+ * The contract of the template a grounded step renders is read here too, from
+ * the knowledge client, and the plan settings are bound to it.
+ *
  * A read failure throws (house rules): a swallowed error would be frozen into
  * the checkpointed seed and served to every replay of this step.
  */
@@ -348,27 +359,38 @@ export declare function gatherStepPackage(args: {
     stepId: string;
     runId: string;
     deps: ExecuteAnalysisDeps;
-}): Promise<StepBriefing>;
+}): Promise<StepPackage>;
+/**
+ * What `composeStepSeed` checkpoints: the seed, and the binding of the plan
+ * settings to the template of the step when the contract was retrieved and
+ * its served version is the version the plan names. JSON-serialisable, as a
+ * durable step result must be.
+ */
+export type StepSeed = {
+    readonly prompt: string;
+    readonly templateBinding?: TemplateBinding;
+};
 /**
  * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
  * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps
  * its reason in `blockedReason` — an honest agent-declared blocker, not an
  * error — and a failure carries the same reason string
  * `persist-synthesis-outcome` writes to `cortex_runs.synthesis_reason`, so the
- * two ledgers cannot disagree about why synthesis died. A suspension is not an
- * outcome: the row is canceled, as the row of a suspended step. Exported for
- * the projection tests (the `buildChildInput` pattern).
+ * two ledgers cannot disagree about why synthesis died. Exported for the
+ * projection tests (the `buildChildInput` pattern).
  */
 export declare function synthesisRowUpdate(outcome: {
     status: SynthesisStatus;
     reason: string | null;
-} | Suspension, durationMs: number): UpdateStepExecutionInput;
+}, durationMs: number): UpdateStepExecutionInput;
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is
- * skipped or produced no synthesizable content. A genuine failure re-throws
- * inside the caller's `DBOS.runStep`, failing the run (D10). Exported so
- * integration tests can drive the wired synthesis without a full parent body.
+ * skipped or produced no synthesizable content. A genuine failure re-throws,
+ * failing the run (D10). It runs in the body of the run workflow: each read and
+ * write is a step, each model call is a step, and each reviewer call starts a
+ * child workflow. Exported so integration tests can drive the wired synthesis
+ * without a full parent body.
  */
 export declare function synthesizeFindings(args: {
     analysisId: string;
@@ -376,6 +398,8 @@ export declare function synthesizeFindings(args: {
     completedSteps: readonly string[];
     session: RunSession;
     deps: ExecuteAnalysisDeps;
+    /** The pause of the run. The body of the run gives it, thus the synthesizer waits in place. */
+    pause?: WorkPause;
 }): Promise<{
     findings: readonly RunFinding[];
     synthesisStatus: Exclude<SynthesisStatus, "failed">;