@inflexa-ai/harness 0.1.1

package/dist/memory/reconstruct-cards.js

@@ -0,0 +1,64 @@
+/**
+ * Read-path reconstruction of display cards from a persisted turn.
+ *
+ * `show_plan` / `show_user` / `show_file` / `execute_plan` / `iterate_report` emit
+ * `data-plan` / `data-presentation` / `data-file-reference` / `data-run-card` /
+ * `data-report-preview` cards
+ * live over the chat SSE stream. On reload, `content-to-cortex` calls this
+ * resolver for each AI SDK tool-call part: a recognised display tool yields its card (rebuilt via the
+ * shared `card-builders`); anything else yields `null` and falls back to a
+ * generic `tool-call` chip. Keyed by the analysis `Pool` + id (plan / run) or
+ * the analysis's workspace root (preview, filesystem-backed) so the card can
+ * be re-loaded.
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { validatePath } from "../tools/lib/path-validation.js";
+import { buildFileReferenceCardData, buildPlanCardData, buildPresentationCardData, buildPreviewCardData, buildRunCardData } from "./card-builders.js";
+export function createCardResolver(pool, analysisId, workspaceRoot) {
+    return async (block) => {
+        if (block.type !== "tool_use")
+            return null;
+        const input = (block.input ?? {});
+        // The harness tool id is `iterate_report`; legacy transcripts carry
+        // `iterateReport` — accept both.
+        if (block.name === "iterate_report" || block.name === "iterateReport") {
+            const report = (input.report ?? null);
+            const card = await buildPreviewCardData(workspaceRoot, {
+                previewId: typeof input.previewId === "string" ? input.previewId : undefined,
+                title: report && typeof report.title === "string" ? report.title : undefined,
+                format: input.format === "pdf" || input.format === "html" ? input.format : undefined,
+            });
+            return card ? { type: "data-report-preview", ...card } : null;
+        }
+        if (block.name === "show_user") {
+            // The live tool rejects a malformed/traversal echart `dataPath` and emits nothing; the
+            // persisted tool_use still carries it, so the reload path MUST re-validate before building
+            // the card — otherwise an unvalidated path is resurrected for the host to join into the
+            // workspace root. Invalid → no card (chip fallback), matching the live "emitted nothing".
+            if (typeof input.dataPath === "string" && validatePath(input.dataPath) !== null)
+                return null;
+            const card = buildPresentationCardData(input);
+            return card ? { type: "data-presentation", ...card } : null;
+        }
+        if (block.name === "show_file") {
+            const card = buildFileReferenceCardData(input);
+            return card ? { type: "data-file-reference", ...card } : null;
+        }
+        if (block.name === "show_plan") {
+            const planId = typeof input.planId === "string" ? input.planId : null;
+            if (!planId)
+                return null;
+            const title = typeof input.title === "string" ? input.title : undefined;
+            const card = unwrapOrThrow(await buildPlanCardData(pool, planId, analysisId, title));
+            return card ? { type: "data-plan", ...card } : null;
+        }
+        if (block.name === "execute_plan") {
+            const planId = typeof input.planId === "string" ? input.planId : null;
+            if (!planId)
+                return null;
+            const card = unwrapOrThrow(await buildRunCardData(pool, { planId, analysisId }));
+            return card ? { type: "data-run-card", ...card } : null;
+        }
+        return null;
+    };
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Conversation message store — the harness's owned `ThreadHistory`.
+ *
+ * Conversation-scoped store with an explicit two-method interface and
+ * nothing else bundled in (no semantic recall, no working memory, no title
+ * generation). It is also the home of context-window management — the read
+ * side, `loadRecent`, returns a token-bounded window.
+ *
+ * Scope (see the harness-thread-store spec): conversation threads only. A `threadId` is the
+ * UI-generated id of one conversation thread (a random UUID — an analysis
+ * has many threads); it is opaque to this module. Workflow and sandbox
+ * agent loops never call this; their message durability is the DBOS step
+ * cache. The interface vocabulary (`appendTurn` / `loadRecent`) is
+ * conversation-turn shaped on purpose, so reaching for it inside a
+ * workflow step feels immediately wrong.
+ *
+ * The window is always a valid AI SDK model-message sequence: it begins on a
+ * `user` message that is genuine user input — never a `tool`-role
+ * continuation — and never splits a tool-call/tool-result pair. The turn
+ * is the atomic unit; `appendTurn` writes one atomically and `loadRecent`
+ * rounds the budget walk to turn boundaries.
+ */
+import type { ModelMessage } from "ai";
+import { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "../lib/db-result.js";
+import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+/** One stored message, as returned by the display read (`loadPage`). */
+export interface StoredMessage {
+    readonly seq: number;
+    readonly envelope: StoredMessageEnvelope;
+    readonly message: ModelMessage;
+}
+/**
+ * A page of stored messages plus pagination metadata. Pagination is
+ * turn-based: `total` is the thread's turn count and `page`/`perPage` index
+ * turns, while `messages` is the flattened rows of the page's turns.
+ */
+export interface MessagePage {
+    readonly messages: StoredMessage[];
+    readonly total: number;
+    readonly page: number;
+    readonly perPage: number;
+    readonly hasMore: boolean;
+}
+/**
+ * The conversation message store. Two methods, by design — no generic row
+ * insert (see the harness-thread-store spec). `threadId` is the conversation scope — one UI thread.
+ */
+export interface ThreadHistory {
+    /**
+     * Append one conversation turn — every message written in a single
+     * transaction with a `seq` monotonically increasing per thread.
+     */
+    appendTurn(threadId: string, messages: readonly ModelMessage[]): ResultAsync<void, DbError>;
+    /**
+     * Return the most recent messages whose cumulative `tokens` fit
+     * `tokenBudget`, oldest-first, snapped to a valid AI SDK model-message sequence.
+     */
+    loadRecent(threadId: string, tokenBudget: number): ResultAsync<ModelMessage[], DbError>;
+    /**
+     * Return one page of a thread's messages oldest-first for UI display —
+     * NOT token-windowed (that is `loadRecent`'s job for the agent loop). No
+     * eviction. Paginated by whole turns: `page`, `perPage`, and `total` count
+     * turns, not rows, so a multi-row turn always reloads intact. `messages`
+     * holds the flattened rows of the selected turns.
+     */
+    loadPage(threadId: string, page: number, perPage: number): ResultAsync<MessagePage, DbError>;
+}
+/**
+ * Drop the memoized instruments so the next `loadRecent` rebinds to a
+ * freshly-registered `MeterProvider`. Test-only.
+ */
+export declare function __resetThreadHistoryMetricsForTest(): void;
+/**
+ * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
+ * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is
+ * provisioned by the project's state-init DDL.
+ */
+export declare function createThreadHistory(pool: Pool): ThreadHistory;

package/dist/memory/thread-history.js

@@ -0,0 +1,187 @@
+/**
+ * Conversation message store — the harness's owned `ThreadHistory`.
+ *
+ * Conversation-scoped store with an explicit two-method interface and
+ * nothing else bundled in (no semantic recall, no working memory, no title
+ * generation). It is also the home of context-window management — the read
+ * side, `loadRecent`, returns a token-bounded window.
+ *
+ * Scope (see the harness-thread-store spec): conversation threads only. A `threadId` is the
+ * UI-generated id of one conversation thread (a random UUID — an analysis
+ * has many threads); it is opaque to this module. Workflow and sandbox
+ * agent loops never call this; their message durability is the DBOS step
+ * cache. The interface vocabulary (`appendTurn` / `loadRecent`) is
+ * conversation-turn shaped on purpose, so reaching for it inside a
+ * workflow step feels immediately wrong.
+ *
+ * The window is always a valid AI SDK model-message sequence: it begins on a
+ * `user` message that is genuine user input — never a `tool`-role
+ * continuation — and never splits a tool-call/tool-result pair. The turn
+ * is the atomic unit; `appendTurn` writes one atomically and `loadRecent`
+ * rounds the budget walk to turn boundaries.
+ */
+import { metrics } from "@opentelemetry/api";
+import { ResultAsync, ok } from "neverthrow";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { countTokens } from "./count-tokens.js";
+import { envelopeMessage, parseStoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+/** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
+function okVoid() {
+    return new ResultAsync(Promise.resolve(ok(undefined)));
+}
+/**
+ * A turn starts on a `user` message. In AI SDK message terms tool results
+ * are `tool`-role messages, so a mid-turn tool continuation never carries
+ * the `user` role and cannot open a turn.
+ */
+function isGenuineUserStart(message) {
+    return message.role === "user";
+}
+/**
+ * Group rows (oldest-first) into turns at genuine-user-start boundaries.
+ * Generic over the row shape so the token-windowed read (`loadRecent`) and
+ * the display read (`loadPage`) share it, each supplying its own start
+ * predicate.
+ */
+function groupTurns(rows, isStart) {
+    const turns = [];
+    for (const row of rows) {
+        if (turns.length === 0 || isStart(row)) {
+            turns.push([row]);
+        }
+        else {
+            turns[turns.length - 1].push(row);
+        }
+    }
+    return turns;
+}
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex.harness.memory");
+        instruments = {
+            totalTokens: meter.createHistogram("cortex.harness.thread.total_tokens", {
+                description: "Total token count of a conversation thread, sampled on every loadRecent",
+                unit: "{token}",
+            }),
+            turnsEvicted: meter.createHistogram("cortex.harness.thread.turns_evicted", {
+                description: "Conversation turns dropped by loadRecent's token-budget window",
+                unit: "{turn}",
+            }),
+        };
+    }
+    return instruments;
+}
+/**
+ * Drop the memoized instruments so the next `loadRecent` rebinds to a
+ * freshly-registered `MeterProvider`. Test-only.
+ */
+export function __resetThreadHistoryMetricsForTest() {
+    instruments = undefined;
+}
+/**
+ * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
+ * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is
+ * provisioned by the project's state-init DDL.
+ */
+export function createThreadHistory(pool) {
+    function appendTurn(threadId, messages) {
+        if (messages.length === 0)
+            return okVoid();
+        return withTransaction(pool, "thread-history.appendTurn", (client) => 
+        // Serialize concurrent appends on this thread — without the lock, two
+        // transactions can both read the same MAX(seq) and collide on the
+        // (thread_id, seq) primary key. Released automatically at COMMIT/ROLLBACK.
+        tryQuery("thread-history.appendTurn.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [threadId]))
+            .andThen(() => tryQuery("thread-history.appendTurn.maxSeq", async () => {
+            const { rows } = await client.query("SELECT COALESCE(MAX(seq), -1)::text AS max_seq FROM messages WHERE thread_id = $1", [threadId]);
+            return Number(rows[0].max_seq) + 1;
+        }))
+            .andThen((startSeq) => 
+        // Insert the turn's messages in order. Each insert chains off the
+        // prior so the first `err` short-circuits — and `withTransaction`
+        // re-throws it to force ROLLBACK (a returned `err` that does not
+        // reach `withTransaction` would COMMIT silently).
+        messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(`INSERT INTO messages (thread_id, seq, message_envelope, tokens)
+                     VALUES ($1, $2, $3::jsonb, $4)
+                     ON CONFLICT (thread_id, seq) DO UPDATE
+                       SET message_envelope = EXCLUDED.message_envelope,
+                           tokens = EXCLUDED.tokens`, [threadId, startSeq + i, JSON.stringify(envelopeMessage(message)), countTokens(message.content)])).map(() => undefined)), okVoid())));
+    }
+    function loadRecent(threadId, tokenBudget) {
+        return tryQuery("thread-history.loadRecent", async () => {
+            const { rows } = await pool.query(
+            // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
+            // `seq::text AS seq` output alias (Postgres resolves an unqualified
+            // ORDER BY name to the output column), sorting the bigint as text:
+            // "10" before "2". Scrambled order splits a tool-call/tool-result pair
+            // across an intervening turn. The qualified name forces the bigint column.
+            `SELECT seq::text AS seq, message_envelope, tokens
+         FROM messages WHERE thread_id = $1 ORDER BY messages.seq ASC`, [threadId]);
+            const parsed = rows.map((row) => ({
+                message: parseStoredMessageEnvelope(row.message_envelope, `${threadId}/${row.seq}`).message,
+                tokens: row.tokens,
+            }));
+            const turns = groupTurns(parsed, (row) => isGenuineUserStart(row.message));
+            const turnTokens = turns.map((turn) => turn.reduce((sum, row) => sum + row.tokens, 0));
+            const threadTotal = turnTokens.reduce((sum, n) => sum + n, 0);
+            // Walk turns newest-first, accumulating token cost. The most recent turn
+            // is always included — even if it alone exceeds the budget, a valid
+            // sequence beats an under-budget one. Older turns join while they fit.
+            let included = 0;
+            let cumulative = 0;
+            for (let t = turns.length - 1; t >= 0; t--) {
+                if (included > 0 && cumulative + turnTokens[t] > tokenBudget)
+                    break;
+                cumulative += turnTokens[t];
+                included++;
+            }
+            const turnsEvicted = turns.length - included;
+            const { totalTokens, turnsEvicted: turnsEvictedHist } = getInstruments();
+            const attributes = { eviction: turnsEvicted > 0 };
+            totalTokens.record(threadTotal, attributes);
+            turnsEvictedHist.record(turnsEvicted, attributes);
+            return turns
+                .slice(turns.length - included)
+                .flat()
+                .map((row) => row.message);
+        });
+    }
+    function loadPage(threadId, page, perPage) {
+        const safePerPage = Math.min(Math.max(perPage, 1), 200);
+        const safePage = Math.max(page, 0);
+        return tryQuery("thread-history.loadPage", async () => {
+            // Display pages are turn-bounded, not row-bounded. A serial-tool assistant
+            // turn is persisted as one row per step (plus its tool_result `user` rows),
+            // so a row-windowed page could split a turn — truncating the trailing
+            // report card/text out of the page the UI fetches. Read the thread, group
+            // into turns, and slice whole turns so a turn always reloads intact.
+            // Threads are conversation-scoped and bounded, so reading every row here
+            // matches `loadRecent`'s existing whole-thread read.
+            const { rows } = await pool.query(
+            // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
+            // `seq::text AS seq` output alias (Postgres resolves an unqualified
+            // ORDER BY name to the output column), sorting the bigint as text:
+            // "10" before "2". The qualified name forces the bigint column.
+            `SELECT seq::text AS seq, message_envelope
+         FROM messages WHERE thread_id = $1
+         ORDER BY messages.seq ASC`, [threadId]);
+            const stored = rows.map((r) => {
+                const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
+                return { seq: Number(r.seq), envelope, message: envelope.message };
+            });
+            const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
+            const total = turns.length;
+            const offset = safePage * safePerPage;
+            const pageTurns = turns.slice(offset, offset + safePerPage);
+            return {
+                messages: pageTurns.flat(),
+                total,
+                page: safePage,
+                perPage: safePerPage,
+                hasMore: offset + pageTurns.length < total,
+            };
+        });
+    }
+    return { appendTurn, loadRecent, loadPage };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Conversation thread metadata store — the harness's owned `ThreadStore`.
+ *
+ * The analysis-scope, ownership, listing, and title that the harness
+ * `messages` table (`thread-history.ts`) deliberately lacks. One row per
+ * conversation thread in `cortex_analysis_threads`, keyed by the
+ * UI-generated `thread_id` (a random UUID — an analysis has many threads).
+ *
+ * Scope (see the harness-thread-store spec): conversation threads only. Like `thread-history.ts`,
+ * the vocabulary is conversation-shaped on purpose — reaching for it inside
+ * a workflow step feels immediately wrong.
+ *
+ * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
+ * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
+ * survive a delete and a tombstoned thread is indistinguishable from absent.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "../lib/db-result.js";
+/** One conversation thread's metadata, as returned by the store. */
+export interface Thread {
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly title: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+export interface CreateThreadInput {
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly title?: string | null;
+}
+export interface ListThreadsInput {
+    readonly analysisId: string;
+    readonly page?: number;
+    readonly perPage?: number;
+}
+export interface ThreadPage {
+    readonly threads: Thread[];
+    readonly total: number;
+    readonly page: number;
+    readonly perPage: number;
+    readonly hasMore: boolean;
+}
+export interface 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
+     * `created_at`). Returns the live row.
+     */
+    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
+    /** The live thread by id, or `null` if absent or soft-deleted. */
+    getThread(threadId: string): ResultAsync<Thread | null, DbError>;
+    /** Set only the title (and bump `updated_at`). No-op on a missing/deleted row. */
+    updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
+    /** Soft-delete: set `deleted_at`. The row and its messages remain. */
+    deleteThread(threadId: string): ResultAsync<void, DbError>;
+    /** Live threads for one analysis, newest-updated first, paginated. */
+    listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, 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;

package/dist/memory/thread-store.js

@@ -0,0 +1,88 @@
+/**
+ * Conversation thread metadata store — the harness's owned `ThreadStore`.
+ *
+ * The analysis-scope, ownership, listing, and title that the harness
+ * `messages` table (`thread-history.ts`) deliberately lacks. One row per
+ * conversation thread in `cortex_analysis_threads`, keyed by the
+ * UI-generated `thread_id` (a random UUID — an analysis has many threads).
+ *
+ * Scope (see the harness-thread-store spec): conversation threads only. Like `thread-history.ts`,
+ * the vocabulary is conversation-shaped on purpose — reaching for it inside
+ * a workflow step feels immediately wrong.
+ *
+ * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
+ * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
+ * survive a delete and a tombstoned thread is indistinguishable from absent.
+ */
+import { okAsync } from "neverthrow";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+function toThread(row) {
+    return {
+        threadId: row.thread_id,
+        analysisId: row.analysis_id,
+        title: row.title,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+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) {
+    function createThread(input) {
+        return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (thread_id) DO NOTHING
+         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
+            if (rows[0])
+                return okAsync(toThread(rows[0]));
+            // Row already existed — ON CONFLICT DO NOTHING returns nothing. Read it
+            // back (it may be soft-deleted; return it regardless so the caller sees
+            // the existing row's identity).
+            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+           FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
+        });
+    }
+    function getThread(threadId) {
+        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+         FROM cortex_analysis_threads
+         WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
+    }
+    function updateTitle(threadId, title) {
+        return tryMutation("thread-store.updateTitle", () => pool.query(`UPDATE cortex_analysis_threads
+         SET title = $2, updated_at = NOW()
+         WHERE thread_id = $1 AND deleted_at IS NULL
+         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
+    }
+    function deleteThread(threadId) {
+        return tryMutation("thread-store.deleteThread", () => pool.query(`UPDATE cortex_analysis_threads
+         SET deleted_at = NOW()
+         WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(() => undefined);
+    }
+    function listThreads(input) {
+        const perPage = Math.min(Math.max(input.perPage ?? DEFAULT_PER_PAGE, 1), MAX_PER_PAGE);
+        const page = Math.max(input.page ?? 0, 0);
+        const offset = page * perPage;
+        return tryQuery("thread-store.listThreads.count", () => pool.query(`SELECT COUNT(*)::text AS count
+         FROM cortex_analysis_threads
+         WHERE analysis_id = $1 AND deleted_at IS NULL`, [input.analysisId])).andThen((totalResult) => {
+            const total = Number(totalResult.rows[0].count);
+            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+           FROM cortex_analysis_threads
+           WHERE analysis_id = $1 AND deleted_at IS NULL
+           ORDER BY updated_at DESC, thread_id
+           LIMIT $2 OFFSET $3`, [input.analysisId, perPage, offset])).map(({ rows }) => ({
+                threads: rows.map(toThread),
+                total,
+                page,
+                perPage,
+                hasMore: offset + rows.length < total,
+            }));
+        });
+    }
+    return { createThread, getThread, updateTitle, deleteThread, listThreads };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Working memory — the harness's structured, analysis-scoped interpretive
+ * store.
+ *
+ * Structured JSONB object the agent updates one section at a time, serialized
+ * to Markdown only when injected (see the harness-thread-store spec).
+ *
+ * Four sections. `goal`, `constraints`, `hypotheses` are analysis-flat;
+ * `findings` is run-scoped, keyed by `runId`, so a finding stays attributable
+ * to the run that produced it. There is deliberately no `context` section —
+ * analysis context lives in `cortex_analysis_state.context` and is injected
+ * separately by the chat route.
+ *
+ * `updateSection` is a section-addressable read-modify-write: the named
+ * section is replaced or amended and the other three are left byte-identical.
+ */
+import type { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { z } from "zod";
+import { type DbError } from "../lib/db-result.js";
+/** A binding rule — user-stated or agent-derived. The highest-value section. */
+export declare const constraintSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    origin: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+    }>;
+}, z.core.$strip>;
+export type Constraint = z.infer<typeof constraintSchema>;
+/** An active hypothesis under exploration. */
+export declare const hypothesisSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type Hypothesis = z.infer<typeof hypothesisSchema>;
+/** A durable conclusion, attributed to the run that produced it. */
+export declare const findingSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type Finding = z.infer<typeof findingSchema>;
+/**
+ * The persisted `data` shape — one JSONB object per analysis. `findings` is
+ * keyed by `runId`; an analysis with no recorded findings has an empty map.
+ */
+export declare const workingMemorySchema: z.ZodObject<{
+    goal: z.ZodString;
+    constraints: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        origin: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+        }>;
+    }, z.core.$strip>>;
+    hypotheses: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+    findings: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WorkingMemory = z.infer<typeof workingMemorySchema>;
+/** The shape `load` returns for an analysis with no working-memory row. */
+export declare function emptyWorkingMemory(): WorkingMemory;
+/**
+ * A list-section amendment: append a new entry, revise an existing one's
+ * text, or retire a stale one. `revise`/`retire` address an entry by the
+ * `id` the agent copies from the rendered working memory.
+ */
+export type ListOp = {
+    readonly op: "add";
+    readonly text: string;
+} | {
+    readonly op: "revise";
+    readonly id: string;
+    readonly text: string;
+} | {
+    readonly op: "retire";
+    readonly id: string;
+};
+/** As `ListOp`, but `add` also carries the constraint's `origin`. */
+export type ConstraintOp = {
+    readonly op: "add";
+    readonly text: string;
+    readonly origin: "user" | "agent";
+} | {
+    readonly op: "revise";
+    readonly id: string;
+    readonly text: string;
+} | {
+    readonly op: "retire";
+    readonly id: string;
+};
+/** The `value` argument of `updateSection`, keyed by the `section` name. */
+export interface SectionValue {
+    readonly goal: {
+        readonly text: string;
+    };
+    readonly constraint: ConstraintOp;
+    readonly hypothesis: ListOp;
+    readonly finding: {
+        readonly runId: string;
+        readonly text: string;
+    };
+}
+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 {
+    /** Read the row; return the empty shape if absent (no lazy insert). */
+    load(analysisId: string): ResultAsync<WorkingMemory, DbError>;
+    /**
+     * Atomically read-modify-write one section. The other three sections are
+     * left byte-identical; the row is upserted if absent.
+     */
+    updateSection<S extends Section>(analysisId: string, section: S, value: SectionValue[S]): ResultAsync<void, DbError>;
+    /** Serialize working memory to a Markdown document for injection. */
+    render(analysisId: string): ResultAsync<string, DbError>;
+}
+/** Serialize working memory to the Markdown document injected each turn. */
+export declare function renderWorkingMemory(wm: WorkingMemory): string;
+/**
+ * Create a `WorkingMemoryStore` bound to a Postgres pool — a factory closure
+ * capturing `pool` (dependency injection per the harness-durable-runtime spec). The
+ * `cortex_working_memory` table is provisioned by the project's state-init
+ * DDL.
+ */
+export declare function createWorkingMemory(pool: Pool): WorkingMemoryStore;