@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/memory/thread-store.d.ts

@@ -44,8 +44,9 @@
  * so it does not enforce that.
  */
 import { type ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
-import { type DbError } from "../lib/db-result.js";
+import { type DbError, type Connectable } from "../lib/db-result.js";
+import type { Querier } from "../state/db.js";
+import { type ConversationTurn } from "./thread-history.js";
 /**
  * The kind of session a thread holds. `conversation` is the analysis
  * conversation the product has always had; `report` is a report session spawned
@@ -65,7 +66,7 @@ import { type DbError } from "../lib/db-result.js";
 declare const THREAD_TYPES: readonly ["conversation", "report"];
 export type ThreadType = (typeof THREAD_TYPES)[number];
 /** One conversation thread's metadata, as returned by the store. */
-export interface Thread {
+export type Thread = {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title: string | null;
@@ -93,13 +94,13 @@ export interface Thread {
      * fall through and render a tombstoned conversation as live.
      */
     readonly deletedAt: Date | null;
-}
-export interface CreateThreadInput {
+};
+export type CreateThreadInput = {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title?: string | null;
-    /** Omitted is `conversation` — what a thread is when nothing says otherwise. */
-    readonly type?: ThreadType;
+    /** Omitted is `conversation` — what a thread is when nothing says otherwise. The store refuses a value outside the closed set at runtime: an untyped caller (a JSON body across a package boundary) can hand in any string, and `unknown_thread_type` is the declared refusal for it. */
+    readonly type?: string;
     /**
      * The thread this one is spawned from. It must belong to the same analysis
      * as the child; whether it exists at all is the foreign key's verdict, not
@@ -112,7 +113,13 @@ export interface CreateThreadInput {
      * and either half alone describes no place.
      */
     readonly parentSeq?: number;
-}
+    /**
+     * The first turn of the new thread. The row and the turn commit in one
+     * transaction. A create that finds the row already there writes no turn,
+     * thus a second create with the same id gives the thread with one turn.
+     */
+    readonly firstTurn?: ConversationTurn;
+};
 /**
  * A create the store refuses on its own, before any row is written. Distinct
  * from `DbError`: nothing failed at the driver — the request described a thread
@@ -143,7 +150,7 @@ export type ThreadInputError = {
     readonly threadId: string;
     readonly threadType: string;
 };
-export interface ListThreadsInput {
+export type ListThreadsInput = {
     readonly analysisId: string;
     readonly page?: number;
     readonly perPage?: number;
@@ -168,21 +175,21 @@ export interface ListThreadsInput {
     readonly type?: ThreadType;
     /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
     readonly parentThreadId?: string;
-}
-export interface ListRecentThreadsInput {
+};
+export type ListRecentThreadsInput = {
     /** The most threads to give. It clamps to 1 to 200, the bounds of a page of `listThreads`. */
     readonly limit: number;
     /** Narrow to one kind of session, exact match. Omitting it narrows nothing. */
     readonly type?: ThreadType;
-}
-export interface ThreadPage {
+};
+export type ThreadPage = {
     readonly threads: Thread[];
     readonly total: number;
     readonly page: number;
     readonly perPage: number;
     readonly hasMore: boolean;
-}
-export interface ThreadStore {
+};
+export type ThreadStore = {
     /**
      * Create a thread row. Idempotent on `thread_id` — a second create for an
      * existing id is a no-op that preserves the existing row (including its
@@ -260,11 +267,13 @@ export interface ThreadStore {
      * archived thread is never in it.
      */
     listRecentThreads(input: ListRecentThreadsInput): ResultAsync<Thread[], DbError>;
-}
+};
 /**
  * Create a `ThreadStore` bound to a Postgres pool — a factory closure
  * capturing `pool` (dependency injection per the harness-durable-runtime spec). The
  * `cortex_analysis_threads` table is provisioned by the state-init DDL.
  */
-export declare function createThreadStore(pool: Pool): ThreadStore;
+/** What this module reads of the pool: the direct `query` plus the transactional `connect`. */
+type ThreadStorePool = Querier & Connectable;
+export declare function createThreadStore(pool: ThreadStorePool): ThreadStore;
 export {};

package/dist/memory/thread-store.js

@@ -45,6 +45,8 @@
  */
 import { errAsync, okAsync } from "neverthrow";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { presentFirst } from "../lib/present.js";
+import { appendTurnIn } from "./thread-history.js";
 /**
  * The kind of session a thread holds. `conversation` is the analysis
  * conversation the product has always had; `report` is a report session spawned
@@ -106,11 +108,6 @@ function toThread(row) {
 }
 const DEFAULT_PER_PAGE = 100;
 const MAX_PER_PAGE = 200;
-/**
- * Create a `ThreadStore` bound to a Postgres pool — a factory closure
- * capturing `pool` (dependency injection per the harness-durable-runtime spec). The
- * `cortex_analysis_threads` table is provisioned by the state-init DDL.
- */
 export function createThreadStore(pool) {
     /**
      * The parent's own analysis scope, or `null` when no such row exists.
@@ -141,16 +138,22 @@ export function createThreadStore(pool) {
      * returned row.
      */
     function insertThread(input) {
-        return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title, thread_type, parent_thread_id, parent_seq)
+        const { firstTurn } = input;
+        if (firstTurn === undefined)
+            return insertRow(pool, input).map(({ thread }) => thread);
+        return withTransaction(pool, "thread-store.createThread", (client) => insertRow(client, input).andThen(({ thread, inserted }) => inserted ? appendTurnIn(client, thread.threadId, firstTurn).map(() => thread) : okAsync(thread)));
+    }
+    function insertRow(querier, input) {
+        return tryMutation("thread-store.createThread.insert", () => querier.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title, thread_type, parent_thread_id, parent_seq)
          VALUES ($1, $2, $3, $4, $5, $6)
          ON CONFLICT (thread_id) DO NOTHING
          RETURNING ${THREAD_COLUMNS}`, [input.threadId, input.analysisId, input.title ?? null, input.type ?? "conversation", input.parentThreadId ?? null, input.parentSeq ?? null])).andThen(({ rows }) => {
             if (rows[0])
-                return okAsync(toThread(rows[0]));
+                return okAsync({ thread: toThread(rows[0]), inserted: true });
             // Row already existed — ON CONFLICT DO NOTHING returns nothing. Read it
             // back (it may be archived; return it regardless so the caller sees
             // the existing row's identity).
-            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT ${THREAD_COLUMNS} FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
+            return tryQuery("thread-store.createThread.readback", () => querier.query(`SELECT ${THREAD_COLUMNS} FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => ({ thread: toThread(presentFirst(existing, "the thread row read back")), inserted: false }));
         });
     }
     function createThread(input) {
@@ -289,6 +292,7 @@ export function createThreadStore(pool) {
         // `cortex_analysis_threads` either, so the cascade cannot reach it. Its row
         // holds a whole draft document, and a purged thread can never be composed
         // again, so a row left behind is dead weight until the analysis purge runs.
+        // The stored results of its authoring calls go with it, for the same reason.
         //
         // Messages go first, and the thread rows go last: the walk every statement
         // shares reads the very rows the last one removes. Thus a thread delete before
@@ -305,6 +309,8 @@ export function createThreadStore(pool) {
          DELETE FROM cortex_thread_turns WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             .andThen(() => tryMutation("thread-store.purgeThread.reportSessionState", () => client.query(`${SUBTREE_CTE}
          DELETE FROM cortex_report_session_state WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
+            .andThen(() => tryMutation("thread-store.purgeThread.authoringResults", () => client.query(`${SUBTREE_CTE}
+         DELETE FROM cortex_authoring_results WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             // A kept text of a run names no thread, thus it stays for the analysis purge.
             .andThen(() => tryMutation("thread-store.purgeThread.toolOutputs", () => client.query(`${SUBTREE_CTE}
          DELETE FROM cortex_tool_outputs WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
@@ -352,7 +358,7 @@ export function createThreadStore(pool) {
         return tryQuery("thread-store.listThreads.count", () => pool.query(`SELECT COUNT(*)::text AS count
          FROM cortex_analysis_threads
          WHERE ${scope}`, scopeValues)).andThen((totalResult) => {
-            const total = Number(totalResult.rows[0].count);
+            const total = Number(presentFirst(totalResult.rows, "the thread count row").count);
             return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT ${THREAD_COLUMNS}
            FROM cortex_analysis_threads
            WHERE ${scope}

package/dist/memory/tool-call-integrity.d.ts

@@ -18,10 +18,10 @@ import type { ModelMessage, ToolCallPart, ToolResultPart } from "ai";
 export declare const NOT_RUN_TOOL_RESULT = "Not run: the turn ended before this call ran.";
 export declare function notRunResult(call: Pick<ToolCallPart, "toolCallId" | "toolName">): ToolResultPart;
 /** One tool call that {@link answerUnansweredToolCalls} answered, identified for the caller's diagnostic record. */
-export interface AnsweredToolCall {
+export type AnsweredToolCall = {
     readonly toolCallId: string;
     readonly toolName: string;
-}
+};
 /**
  * Answer, in place, every tool call at or past `fromIndex` that has no matching
  * tool result anywhere in `messages`. No message is removed or changed. Returns

package/dist/memory/tool-call-integrity.js

@@ -14,6 +14,7 @@
  * because a signed thinking block and the prompt cache both key on the exact
  * prior prefix.
  */
+import { presentAt } from "../lib/present.js";
 export const NOT_RUN_TOOL_RESULT = "Not run: the turn ended before this call ran.";
 export function notRunResult(call) {
     return {
@@ -67,14 +68,14 @@ export function answerUnansweredToolCalls(messages, fromIndex = 0) {
     // Backward, so an insertion after a message cannot shift an index this walk
     // has yet to visit.
     for (let idx = messages.length - 1; idx >= fromIndex; idx--) {
-        const message = messages[idx];
+        const message = presentAt(messages, idx, "the message at the index");
         if (message.role !== "assistant" || typeof message.content === "string")
             continue;
-        const unanswered = message.content.filter((part) => part.type === "tool-call" && needsClientResult(part) && !resultIds.has(part.toolCallId));
+        const unanswered = message.content.flatMap((part) => part.type === "tool-call" && needsClientResult(part) && !resultIds.has(part.toolCallId) ? [part] : []);
         if (unanswered.length === 0)
             continue;
         let insertAt = idx + 1;
-        while (insertAt < messages.length && messages[insertAt].role === "tool")
+        while (insertAt < messages.length && presentAt(messages, insertAt, "the message at the insert point").role === "tool")
             insertAt++;
         messages.splice(insertAt, 0, { role: "tool", content: unanswered.map((part) => notRunResult(part)) });
         // Prepended as a batch: the walk visits messages tail-first, but the

package/dist/memory/working-memory.d.ts

@@ -28,9 +28,9 @@
  *    list; the run's detail stays retrievable via `inspect_run`.
  */
 import { type ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
 import { z } from "zod";
-import { type DbError } from "../lib/db-result.js";
+import { type Connectable, type DbError } from "../lib/db-result.js";
+import type { Querier } from "../state/db.js";
 /**
  * The write-time bounds on working memory. `updateSection` enforces them, the
  * `update_working_memory` input schema declares them to the model (importing
@@ -53,8 +53,8 @@ export declare const constraintSchema: z.ZodObject<{
     id: z.ZodString;
     text: z.ZodString;
     origin: z.ZodEnum<{
-        user: "user";
         agent: "agent";
+        user: "user";
     }>;
 }, z.core.$strip>;
 export type Constraint = z.infer<typeof constraintSchema>;
@@ -85,8 +85,8 @@ export declare const workingMemorySchema: z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
         origin: z.ZodEnum<{
-            user: "user";
             agent: "agent";
+            user: "user";
         }>;
     }, z.core.$strip>>;
     hypotheses: z.ZodArray<z.ZodObject<{
@@ -107,10 +107,10 @@ export declare function emptyWorkingMemory(): WorkingMemory;
  * written for the model and says what to do next (shorten this, retire that).
  * The tool surfaces it as an `is_error` tool result; the row is untouched.
  */
-export interface WorkingMemoryRejection {
+export type WorkingMemoryRejection = {
     readonly type: "working_memory_rejected";
     readonly message: string;
-}
+};
 /** `updateSection`'s error channel: a storage failure, or a refused write. */
 export type WorkingMemoryError = DbError | WorkingMemoryRejection;
 /** Narrow a `WorkingMemoryError` to the model-correctable branch. */
@@ -162,21 +162,21 @@ export type FindingOp = {
     readonly id: string;
 };
 /** The `value` argument of `updateSection`, keyed by the `section` name. */
-export interface SectionValue {
+export type SectionValue = {
     readonly goal: {
         readonly text: string;
     };
     readonly constraint: ConstraintOp;
     readonly hypothesis: ListOp;
     readonly finding: FindingOp;
-}
+};
 export type Section = keyof SectionValue;
 /**
  * The working-memory store. Three methods — `load` reads the structured
  * shape, `updateSection` amends one section, `render` serializes to the
  * Markdown the chat route injects.
  */
-export interface WorkingMemoryStore {
+export type WorkingMemoryStore = {
     /** Read the row; return the empty shape if absent (no lazy insert). */
     load(analysisId: string): ResultAsync<WorkingMemory, DbError>;
     /**
@@ -184,11 +184,15 @@ export interface WorkingMemoryStore {
      * left byte-identical; the row is upserted if absent. A write that breaks a
      * cap or addresses an unknown id is refused — `err(WorkingMemoryRejection)`,
      * and the row is left exactly as it was.
+     *
+     * `callKey` names the durable step of the call. The edit records it in its
+     * own transaction, and an edit whose key is recorded already changes nothing
+     * and gives ok. Thus a rerun of the step applies the edit one time.
      */
-    updateSection<S extends Section>(analysisId: string, section: S, value: SectionValue[S]): ResultAsync<void, WorkingMemoryError>;
+    updateSection<S extends Section>(analysisId: string, section: S, value: SectionValue[S], callKey?: string): ResultAsync<void, WorkingMemoryError>;
     /** Serialize working memory to a Markdown document for injection. */
     render(analysisId: string): ResultAsync<string, DbError>;
-}
+};
 /**
  * Serialize working memory to the Markdown document of the working-memory context record.
  *
@@ -212,4 +216,4 @@ export declare function renderWorkingMemory(wm: WorkingMemory): string;
  * `cortex_working_memory` table is provisioned by the project's state-init
  * DDL.
  */
-export declare function createWorkingMemory(pool: Pool): WorkingMemoryStore;
+export declare function createWorkingMemory(pool: Querier & Connectable): WorkingMemoryStore;

package/dist/memory/working-memory.js

@@ -30,6 +30,7 @@
 import { err, ok, okAsync } from "neverthrow";
 import { z } from "zod";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { presentGet } from "../lib/present.js";
 /**
  * The write-time bounds on working memory. `updateSection` enforces them, the
  * `update_working_memory` input schema declares them to the model (importing
@@ -140,7 +141,7 @@ function countFindings(findings) {
 }
 /** The run a finding id hangs under, or `undefined` if no run holds it. */
 function runOfFinding(findings, id) {
-    return Object.keys(findings).find((runId) => findings[runId].some((f) => f.id === id));
+    return Object.keys(findings).find((runId) => presentGet(findings, runId, "the run's findings").some((f) => f.id === id));
 }
 function applyFindingOp(findings, op) {
     switch (op.op) {
@@ -159,59 +160,51 @@ function applyFindingOp(findings, op) {
                 return rejectUnknownId("finding", op.id);
             return checkEntryText("finding", op.text).map((text) => ({
                 ...findings,
-                [runId]: findings[runId].map((f) => (f.id === op.id ? { ...f, text } : f)),
+                [runId]: presentGet(findings, runId, "the run's findings").map((f) => (f.id === op.id ? { ...f, text } : f)),
             }));
         }
         case "retire": {
             const runId = runOfFinding(findings, op.id);
             if (runId === undefined)
                 return rejectUnknownId("finding", op.id);
-            const kept = findings[runId].filter((f) => f.id !== op.id);
+            const kept = presentGet(findings, runId, "the run's findings").filter((f) => f.id !== op.id);
             const next = { ...findings };
             // An emptied run bucket is dropped whole: memory references a run only
             // for as long as it holds a finding from it.
             if (kept.length === 0)
-                delete next[runId];
+                Reflect.deleteProperty(next, runId);
             else
                 next[runId] = kept;
             return ok(next);
         }
     }
 }
-/**
- * Pure section-addressable amendment. Sibling sections are never touched; a
- * refused write returns `err` and the caller writes nothing.
- */
-function applySectionUpdate(wm, section, value) {
-    switch (section) {
-        case "goal": {
-            const text = value.text.trim();
-            if (text.length > WORKING_MEMORY_LIMITS.goalChars) {
-                return reject(`the goal is ${text.length} characters — the cap is ${WORKING_MEMORY_LIMITS.goalChars}. It was NOT ` +
-                    `recorded. State the objective in a sentence or two; the supporting detail belongs in ` +
-                    `constraints and findings, not in the goal.`);
-            }
-            return ok({ ...wm, goal: text });
+const sectionWriters = {
+    goal: (wm, value) => {
+        const text = value.text.trim();
+        if (text.length > WORKING_MEMORY_LIMITS.goalChars) {
+            return reject(`the goal is ${text.length} characters — the cap is ${WORKING_MEMORY_LIMITS.goalChars}. It was NOT ` +
+                `recorded. State the objective in a sentence or two; the supporting detail belongs in ` +
+                `constraints and findings, not in the goal.`);
         }
-        case "constraint": {
-            const op = value;
-            const origin = op.op === "add" ? op.origin : "agent";
-            return applyEntryOp(wm.constraints, op, "constraints", WORKING_MEMORY_LIMITS.constraints, (text) => ({
-                id: newId(),
-                text,
-                origin,
-            })).map((constraints) => ({ ...wm, constraints }));
-        }
-        case "hypothesis":
-            return applyEntryOp(wm.hypotheses, value, "hypotheses", WORKING_MEMORY_LIMITS.hypotheses, (text) => ({
-                id: newId(),
-                text,
-            })).map((hypotheses) => ({ ...wm, hypotheses }));
-        case "finding":
-            return applyFindingOp(wm.findings, value).map((findings) => ({ ...wm, findings }));
-    }
-    // Unreachable — `section` is exhaustively a `Section`.
-    return ok(wm);
+        return ok({ ...wm, goal: text });
+    },
+    constraint: (wm, op) => {
+        const origin = op.op === "add" ? op.origin : "agent";
+        return applyEntryOp(wm.constraints, op, "constraints", WORKING_MEMORY_LIMITS.constraints, (text) => ({
+            id: newId(),
+            text,
+            origin,
+        })).map((constraints) => ({ ...wm, constraints }));
+    },
+    hypothesis: (wm, op) => applyEntryOp(wm.hypotheses, op, "hypotheses", WORKING_MEMORY_LIMITS.hypotheses, (text) => ({
+        id: newId(),
+        text,
+    })).map((hypotheses) => ({ ...wm, hypotheses })),
+    finding: (wm, op) => applyFindingOp(wm.findings, op).map((findings) => ({ ...wm, findings })),
+};
+function applySectionUpdate(wm, section, value) {
+    return sectionWriters[section](wm, value);
 }
 /** Every finding, in insertion order, each carrying its run reference. */
 function flattenFindings(findings) {
@@ -283,33 +276,51 @@ export function createWorkingMemory(pool) {
         // The driver read is the only thing wrapped; `workingMemorySchema.parse`
         // runs in `.map` so a schema-validation throw propagates verbatim rather
         // than being miscaptured as a `DbError`.
-        return tryQuery("working-memory.load", () => pool.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])).map(({ rows }) => (rows.length === 0 ? emptyWorkingMemory() : workingMemorySchema.parse(rows[0].data)));
+        return tryQuery("working-memory.load", () => pool.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])).map(({ rows }) => {
+            const [stored] = rows;
+            return stored === undefined ? emptyWorkingMemory() : workingMemorySchema.parse(stored.data);
+        });
     }
-    function updateSection(analysisId, section, value) {
-        return withTransaction(pool, "working-memory.updateSection", (client) => 
-        // Serialize concurrent read-modify-write on this analysis — the lock
-        // covers the not-yet-existing-row case an `SELECT ... FOR UPDATE`
-        // would miss. Released automatically at COMMIT/ROLLBACK. The cap check
-        // runs under it too, so two racing adds cannot both slip past a full
-        // section.
-        tryQuery("working-memory.updateSection.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [analysisId]))
-            .andThen(() => tryQuery("working-memory.updateSection.read", () => client.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])))
-            .map(({ rows }) => {
-            // Schema parse stays outside the driver wrapper — a validation throw
-            // propagates verbatim (and `withTransaction` still rolls back).
-            const current = rows.length === 0 ? emptyWorkingMemory() : workingMemorySchema.parse(rows[0].data);
-            return applySectionUpdate(current, section, value);
-        })
-            .andThen((amended) => 
-        // A rejection rides the transaction's ok channel: it is a decision, not a
-        // storage failure. The transaction commits having written nothing, and the
-        // rejection is lifted back into the error channel below.
-        amended.isErr()
-            ? okAsync(err(amended.error))
-            : tryMutation("working-memory.updateSection.upsert", () => client.query(`INSERT INTO cortex_working_memory (analysis_id, data, updated_at)
+    function updateSection(analysisId, section, value, callKey) {
+        const written = ok(undefined);
+        return withTransaction(pool, "working-memory.updateSection", (client) => {
+            // The key is read under the analysis lock, thus a second run of one call
+            // waits for the first and then finds its key.
+            const alreadyApplied = () => callKey === undefined
+                ? okAsync(false)
+                : tryQuery("working-memory.updateSection.appliedKey", () => client.query("SELECT 1 FROM cortex_applied_memory_edits WHERE call_key = $1", [callKey])).map(({ rows }) => rows.length > 0);
+            const recordKey = () => callKey === undefined
+                ? okAsync(undefined)
+                : tryMutation("working-memory.updateSection.recordKey", () => client.query("INSERT INTO cortex_applied_memory_edits (call_key, analysis_id) VALUES ($1, $2)", [callKey, analysisId])).map(() => undefined);
+            const amend = () => tryQuery("working-memory.updateSection.read", () => client.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId]))
+                .map(({ rows }) => {
+                // Schema parse stays outside the driver wrapper — a validation throw
+                // propagates verbatim (and `withTransaction` still rolls back).
+                const [stored] = rows;
+                const current = stored === undefined ? emptyWorkingMemory() : workingMemorySchema.parse(stored.data);
+                return applySectionUpdate(current, section, value);
+            })
+                .andThen((amended) => 
+            // A rejection rides the transaction's ok channel: it is a decision, not a
+            // storage failure. The transaction commits having written nothing, and the
+            // rejection is lifted back into the error channel below.
+            amended.isErr()
+                ? okAsync(err(amended.error))
+                : tryMutation("working-memory.updateSection.upsert", () => client.query(`INSERT INTO cortex_working_memory (analysis_id, data, updated_at)
                VALUES ($1, $2::jsonb, NOW())
                ON CONFLICT (analysis_id)
-               DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`, [analysisId, JSON.stringify(amended.value)])).map(() => ok(undefined)))).andThen((written) => written);
+               DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`, [analysisId, JSON.stringify(amended.value)]))
+                    .andThen(recordKey)
+                    .map(() => written));
+            // Serialize concurrent read-modify-write on this analysis — the lock
+            // covers the not-yet-existing-row case an `SELECT ... FOR UPDATE`
+            // would miss. Released automatically at COMMIT/ROLLBACK. The cap check
+            // runs under it too, so two racing adds cannot both slip past a full
+            // section.
+            return tryQuery("working-memory.updateSection.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [analysisId]))
+                .andThen(alreadyApplied)
+                .andThen((done) => (done ? okAsync(written) : amend()));
+        }).andThen((result) => result);
     }
     function render(analysisId) {
         return load(analysisId).map(renderWorkingMemory);

package/dist/prompts/briefing.d.ts

@@ -24,14 +24,20 @@
 import { type WorkingMemory } from "../memory/working-memory.js";
 import type { DataProfileResult } from "../state/data-profile.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
+import type { TemplateParameter } from "../tools/knowledge/client.js";
+import type { TemplateBindingValue } from "../tools/knowledge/template.js";
 /** Completed dependencies rendered as upstream blocks; the tail is counted, not rendered. */
 export declare const MAX_UPSTREAM_DEPS = 5;
 /** Characters of each dependency's summary carried in the seed — the gist, not the document. */
 export declare const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export declare const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export declare const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export declare const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
-export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats"];
+export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats", "grounding"];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
  * threaded separately through the workflow input, execution knobs, and result
@@ -41,7 +47,7 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * {@link renderResources} section, because the budget is an execution bound,
  * not a task instruction.
  */
-export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages"];
+export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages", "capability"];
 /**
  * The step's own instructions. Only `question` is guaranteed present; the
  * remaining task fields are appended as dedicated sections when populated, so a
@@ -50,7 +56,7 @@ export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type",
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export declare function renderTask(step: AnalysisStep): string;
+export declare function renderTask(step: AnalysisStep, contract?: Pick<StepBriefing, "template" | "templateNotRetrieved">): string;
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
  * prompt names this same text, thus a test pins the two together.
@@ -75,6 +81,46 @@ export declare function emptyStepMemory(): StepMemory;
  * entry — it has no memory tool.
  */
 export declare function renderMemory(memory: StepMemory): string;
+/** A file the script of the template reads. `path` names the slot that gives it, for example `{{counts_path}}`. */
+export type TemplateBriefInput = {
+    readonly name: string;
+    readonly path: string;
+    readonly description?: string;
+};
+/** One plan setting bound to an adaptable slot of the template. */
+export type TemplateBoundSetting = {
+    readonly name: string;
+    readonly value: TemplateBindingValue;
+    /** The source of the value (a doi or a document), or `plan` when the procedure names none. */
+    readonly source: string;
+};
+/**
+ * The contract of the template a step renders, projected for the seed. The
+ * parent fetches it at dispatch and binds the plan settings to it; the
+ * section is what lets an agent that has never seen the template make one
+ * valid render call.
+ */
+export type TemplateBrief = {
+    /** The template reference of the plan step, with its version when the plan names one. */
+    readonly ref: string;
+    /** The version the service serves. Differs from the version of `ref` when the snapshot moved on. */
+    readonly version_served: string;
+    /** The adaptable slots of the contract, in the order the template declares them. A pinned slot is never rendered. */
+    readonly slots: readonly TemplateParameter[];
+    readonly inputs: readonly TemplateBriefInput[];
+    /** The plan settings bound to a slot, in plan order. Empty when the served version differs from the plan. */
+    readonly bound: readonly TemplateBoundSetting[];
+    /** The plan settings no bound slot carries, one line each with the reason. */
+    readonly unbound_settings: readonly string[];
+};
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export declare function renderTemplateContract(brief: TemplateBrief | undefined): string;
 /**
  * What anchors every path the agent writes or reads: the id the tree is mounted
  * at, and the step's writable directory.
@@ -84,12 +130,12 @@ export declare function renderMemory(memory: StepMemory): string;
  * every other path in the briefing is rooted with, thus one field serves the
  * workspace section and the orientation alike.
  */
-export interface WorkspaceFrame {
+export type WorkspaceFrame = {
     /** The analysis id. The sandbox mounts the read-only analysis tree at `/{analysisId}`. */
     readonly analysisId: string;
     /** In-sandbox working directory — this step's writable artifact directory, and its cwd. */
     readonly workingDir: string;
-}
+};
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export declare function analysisRootOf(frame: WorkspaceFrame): string;
 export declare function renderWorkspace(frame: WorkspaceFrame): string;
@@ -113,7 +159,7 @@ export declare function renderOrientation(profile: DataProfileResult | null | un
  * to the rest — an agent that needs more than the excerpt reads the summary at
  * `summaryPath` rather than having the whole document pushed into its context.
  */
-export interface UpstreamHandoff {
+export type UpstreamHandoff = {
     readonly stepId: string;
     readonly agentId: string;
     /** The dependency's step summary. Clamped to {@link UPSTREAM_SUMMARY_MAX_CHARS} here, not by the caller. */
@@ -124,10 +170,10 @@ export interface UpstreamHandoff {
     readonly outputDir: string;
     /** In-sandbox absolute paths of the artifacts the dependency registered. */
     readonly artifacts: readonly string[];
-}
+};
 export declare function renderUpstream(handoffs: readonly UpstreamHandoff[]): string;
 /** Everything one step's seed is composed from — all of it known at dispatch time. */
-export interface StepBriefing {
+export type StepBriefing = {
     readonly step: AnalysisStep;
     readonly workspace: WorkspaceFrame;
     /** The analysis's persisted data profile; `null` when never profiled or still pending. */
@@ -136,7 +182,15 @@ export interface StepBriefing {
     readonly upstream: readonly UpstreamHandoff[];
     /** The goal and the constraints of the analysis, read from the working memory at dispatch. */
     readonly memory: StepMemory;
-}
+    /** The contract of the template the step renders, with the plan settings bound to it. Absent when none was retrieved. */
+    readonly template?: TemplateBrief;
+    /**
+     * Why the seed carries no template contract for a step whose grounding
+     * names one: no client is bound, the service did not answer, or the
+     * service does not hold the template. Read only when `template` is absent.
+     */
+    readonly templateNotRetrieved?: string;
+};
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step
  * with no profile and an empty memory yields exactly the task and workspace sections, byte-identical