@inflexa-ai/harness 0.14.2 → 0.15.1

package/dist/runtime/assemble.d.ts

@@ -15,6 +15,7 @@
  * before launch — a blue/green drain treats them as a single cohort.
  */
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
@@ -27,12 +28,20 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * Deps bundles for the durable workflows. `executeAnalysis` is a builder
  * because its `sandboxStepCallable` is the registered sandbox-step callable,
  * which does not exist until registration runs inside `assembleCoreRuntime`.
+ *
+ * Each bag omits `usageRecorder` for the same reason `ConversationAssemblyDeps`
+ * does: the recorder is resolved once below and stamped onto every bag this
+ * call registers, so one runtime reports to one ledger. Leaving it settable
+ * here would let an embedder wire a recorder the workflows use and the
+ * conversation agent does not — a half-wired ledger that reads as a complete
+ * one. The protection has to hold on both sides of the assembly, not just the
+ * conversation side.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: SandboxStepDeps;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => ExecuteAnalysisDeps;
-    readonly executeTargetAssessment: ExecuteTargetAssessmentDeps;
-    readonly dataProfile: DataProfileDeps;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder">;
+    readonly executeTargetAssessment: Omit<ExecuteTargetAssessmentDeps, "usageRecorder">;
+    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -42,11 +51,12 @@ export interface RegisteredWorkflows {
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
 }
 /**
- * Conversation-agent deps minus the workflow callable and the resource
- * policy — `assembleCoreRuntime` supplies those itself so a caller cannot wire
- * a stale callable or a policy that diverges from the one the workflows see.
+ * Conversation-agent deps minus the workflow callable, the resource policy, and
+ * the usage recorder — `assembleCoreRuntime` supplies those itself so a caller
+ * cannot wire a stale callable, a policy that diverges from the one the
+ * workflows see, or a recorder that only half the agent tree reports to.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -55,6 +65,13 @@ export interface CoreRuntimeDeps {
      * point for planner/routing guidance and workflow-input budget snapshots.
      */
     readonly resourcePolicy?: ResourcePolicy;
+    /**
+     * LLM usage-accounting seam. Resolved once here and stamped onto the
+     * conversation agent and every workflow deps bag this call registers, so
+     * one runtime reports to one ledger. Omitted falls back to
+     * `createNoopUsageRecorder()`.
+     */
+    readonly usageRecorder?: UsageRecorder;
 }
 export interface CoreRuntime {
     readonly conversationAgent: AgentDefinition;

package/dist/runtime/assemble.js

@@ -15,20 +15,23 @@
  * before launch — a blue/green drain treats them as a single cohort.
  */
 import { createConversationAgent } from "../agents/conversation-agent.js";
+import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
-    const sandboxStep = registerSandboxStep(wf.sandboxStep);
-    const executeAnalysis = registerExecuteAnalysis(wf.buildExecuteAnalysis(sandboxStep));
-    const executeTargetAssessment = registerExecuteTargetAssessment(wf.executeTargetAssessment);
-    const dataProfile = registerDataProfileWorkflow(wf.dataProfile);
+    const usageRecorder = deps.usageRecorder ?? createNoopUsageRecorder();
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, usageRecorder });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), usageRecorder });
+    const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
+    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
         resourcePolicy,
+        usageRecorder,
     });
     return {
         conversationAgent,

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -6,6 +6,7 @@
  * into its emitters.
  */
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
+import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 /**
  * Stable reconciliation id for a step's reconciling parts
  * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
@@ -18,7 +19,27 @@ import type { ChatDataPart, EmitFn } from "../loop/types.js";
  * producers construct it identically.
  */
 export declare function stepPartId(kind: string, runId: string, stepId: string): string;
-export declare function activityForTool(name: string, input?: unknown): string;
+/**
+ * The live-activity phrase for one tool call: the tool's name, then its own
+ * description of this call when it has one.
+ *
+ * The description comes from the tool's `describeCall` hook, resolved through
+ * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
+ * use. A caller supplies the resolver for the agent whose calls it is
+ * describing, because a sandbox agent's tool list is not the conversation
+ * roster's and no single list serves both.
+ *
+ * The name always leads, and that is load-bearing rather than cosmetic. This
+ * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
+ * which prints the name itself and can afford a bare detail. `write_file` and
+ * `edit_file` both describe a call by its path, so a detail on its own would
+ * render a write and an edit of the same file identically.
+ *
+ * A tool with no hook, an unknown tool, and an input its schema rejects all fall
+ * back to the name alone. No verb is added: the phrase is carried on a part that
+ * already states the phase, so "Running" would only restate it.
+ */
+export declare function activityForTool(name: string, input?: unknown, resolveDetail?: ToolDetailResolver): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */
 export interface SandboxTreeDelta {

package/dist/sandbox/sandbox-step-translate.js

@@ -19,42 +19,29 @@
 export function stepPartId(kind, runId, stepId) {
     return `${kind}-${runId}-${stepId}`;
 }
-/** Friendly live-activity label per sandbox tool id. Falls back to the raw
- *  tool name so a newly added tool still reads sensibly. */
-const TOOL_ACTIVITY = {
-    execute_command: "Running script",
-    write_file: "Writing file",
-    edit_file: "Editing file",
-    read_file: "Reading file",
-    grep: "Searching files",
-    list_files: "Listing files",
-};
-/** Last path segment of a posix/win path-like string. */
-function baseName(p) {
-    const parts = p.split(/[\\/]/);
-    return parts[parts.length - 1] || p;
-}
-/** Display file name for a tool's live-activity label, or null when the input
- *  carries no sensible name. Path tools (`write_file`/`edit_file`/`read_file`)
- *  carry `path`; `execute_command` carries an argv `command` whose first
- *  script-like token names what's running. */
-function activityFileName(name, input) {
-    if (input === null || typeof input !== "object")
-        return null;
-    const obj = input;
-    if (name === "execute_command") {
-        const cmd = obj.command;
-        if (!Array.isArray(cmd))
-            return null;
-        const script = cmd.find((a) => typeof a === "string" && /\.(py|R|r|sh|js|ts|ipynb)$/.test(a));
-        return script ? baseName(script) : null;
-    }
-    return typeof obj.path === "string" && obj.path.length > 0 ? baseName(obj.path) : null;
-}
-export function activityForTool(name, input) {
-    const label = TOOL_ACTIVITY[name] ?? `Running ${name}`;
-    const file = activityFileName(name, input);
-    return file ? `${label} ${file}` : label;
+/**
+ * The live-activity phrase for one tool call: the tool's name, then its own
+ * description of this call when it has one.
+ *
+ * The description comes from the tool's `describeCall` hook, resolved through
+ * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
+ * use. A caller supplies the resolver for the agent whose calls it is
+ * describing, because a sandbox agent's tool list is not the conversation
+ * roster's and no single list serves both.
+ *
+ * The name always leads, and that is load-bearing rather than cosmetic. This
+ * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
+ * which prints the name itself and can afford a bare detail. `write_file` and
+ * `edit_file` both describe a call by its path, so a detail on its own would
+ * render a write and an edit of the same file identically.
+ *
+ * A tool with no hook, an unknown tool, and an input its schema rejects all fall
+ * back to the name alone. No verb is added: the phrase is carried on a part that
+ * already states the phase, so "Running" would only restate it.
+ */
+export function activityForTool(name, input, resolveDetail) {
+    const detail = resolveDetail?.(name, input);
+    return detail === undefined ? name : `${name} ${detail}`;
 }
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by

package/dist/schemas/run-synthesis.d.ts

@@ -57,6 +57,7 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "clinical-evidence": "clinical-evidence";
         }>;
         actionType: z.ZodOptional<z.ZodEnum<{
+            none: "none";
             "therapeutic-target": "therapeutic-target";
             "predictive-biomarker": "predictive-biomarker";
             "prognostic-biomarker": "prognostic-biomarker";
@@ -65,7 +66,6 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "resistance-mechanism": "resistance-mechanism";
             "patient-stratification": "patient-stratification";
             "mechanism-of-action": "mechanism-of-action";
-            none: "none";
         }>>;
         rationale: z.ZodString;
     }, z.core.$strip>>;
@@ -123,6 +123,7 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "clinical-evidence": "clinical-evidence";
             }>;
             actionType: z.ZodOptional<z.ZodEnum<{
+                none: "none";
                 "therapeutic-target": "therapeutic-target";
                 "predictive-biomarker": "predictive-biomarker";
                 "prognostic-biomarker": "prognostic-biomarker";
@@ -131,7 +132,6 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "resistance-mechanism": "resistance-mechanism";
                 "patient-stratification": "patient-stratification";
                 "mechanism-of-action": "mechanism-of-action";
-                none: "none";
             }>>;
             rationale: z.ZodString;
         }, z.core.$strip>>;

package/dist/state/index.d.ts

@@ -23,6 +23,8 @@ export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { createAnalysisPurge } from "./purge-analysis.js";
+export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./purge-analysis.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/index.js

@@ -16,5 +16,8 @@ export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes,
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+// Not per-entity: one analysis's whole Postgres footprint, reached from its id
+// alone, with the workflow ledger behind an injected seam.
+export { createAnalysisPurge } from "./purge-analysis.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.js

@@ -8,6 +8,9 @@
  */
 import { backfillAiSdkMessageEnvelopes } from "../memory/message-backfill.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+// No ';' may appear anywhere in this text, comments included: it is executed by
+// splitting on ';' (see `DDL.split` below), so a semicolon inside a comment cuts
+// the statement it precedes in half and Postgres rejects the fragment.
 const DDL = `
 -- Analysis-level state (status, context, data-profile tracking, billing identity).
 --
@@ -227,6 +230,25 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- re-sent to the provider on the next turn, where a reordered prefix misses the
 -- prompt cache. JSON stores the text verbatim. Nothing indexes this column, and
 -- the JSON operators retractLastTurn uses work the same on either type.
+--
+-- reported_usage holds a whole turn's TokenUsageRollup — what providers reported
+-- for the turn this row completed — and is written only on the LAST assistant row
+-- of a turn, so a reloaded transcript can show the figure the live turn showed.
+-- It is NOT the tokens column beside it, and the two must never be read for
+-- each other: tokens is an offline js-tiktoken estimate stamped on EVERY row so
+-- the read path can window by budget without a provider round trip, and it exists
+-- for rows no provider ever saw. reported_usage is a provider's own report, and
+-- covers a turn rather than a row. Both are plausible-looking integers on one row,
+-- which is exactly why the column names carry the distinction.
+--
+-- Nullable with no default: absent means nothing was reported, and a zero would
+-- claim a turn cost nothing. A row written before this column existed is absent
+-- for the same reason, so the migration needs no backfill.
+--
+-- JSONB here, unlike message_envelope above. The verbatim-bytes requirement that
+-- forces JSON on the envelope is about model content that is re-sent to the
+-- provider. This record is harness-generated, has a fixed field set, and never
+-- reaches a prompt, so it does not share that requirement.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
@@ -234,6 +256,7 @@ CREATE TABLE IF NOT EXISTS messages (
   content_jsonb JSONB,
   message_envelope JSON,
   tokens        INTEGER NOT NULL,
+  reported_usage JSONB,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
 );
@@ -432,6 +455,11 @@ export async function initCortexState(pool, injected) {
                 // dropping an absent NOT NULL no-ops, so this is a no-op on fresh DBs.
                 "ALTER TABLE cortex_analysis_state ALTER COLUMN data_profile_status DROP NOT NULL",
                 "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSON",
+                // The turn's reported usage rollup (see the CREATE TABLE comment).
+                // Purely additive: nullable with no default, so adding it rewrites no
+                // row and every pre-existing message reads back with no rollup — which
+                // is the honest value, the figures having never been recorded.
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS reported_usage JSONB",
                 // Demote an existing JSONB envelope column to JSON (see the CREATE
                 // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
                 // whole table and this runs at every boot; scoped to

package/dist/state/purge-analysis.d.ts

@@ -0,0 +1,74 @@
+/**
+ * purgeAnalysis — the single place that knows what an analysis's persisted
+ * Postgres footprint is.
+ *
+ * A host asks for it with an `analysisId` and nothing else: every keyed store,
+ * the analysis's dynamic vector-table name, and its workflow ids are all
+ * derivable from that id, so no caller enumerates tables or supplies a run list.
+ * The workflow ledger is part of the footprint, not a follow-on — the sandbox
+ * transcripts and run-event streams live there and are the dominant share of an
+ * analysis's stored bytes — and it is reached through the injected
+ * `WorkflowPurger` seam so the durability engine stays out of the state layer.
+ *
+ * There is no single transaction across the stages: the purge spans app tables, a
+ * DDL `DROP TABLE`, and the engine's system schema, so instead of faking atomicity
+ * every stage is idempotent and the whole operation is safe to re-run. A purge of
+ * an unknown or already-purged analysis therefore succeeds, reporting zeroes. Each
+ * stage carries the reason it sits where it does.
+ *
+ * A purge is NOT serialized against work still starting on the analysis. The
+ * mapping from an analysis to its workflows is read once, up front, out of
+ * `cortex_runs`; a run inserted after that read is outside the captured set, and
+ * the `cortex_runs` delete later in the same purge removes the only row that could
+ * ever have named it. Its workflow row and every byte cascading off it then belong
+ * to no analysis — no retry reaches them, because nothing is left that attributes
+ * them to one. Quiesce the analysis before purging it: no new runs, no new
+ * data-profile triggers. This module cannot observe a host's in-flight work, so it
+ * does not enforce that.
+ *
+ * What it does not reach, so that absent coverage is never read as delivered:
+ * scheduled operational workflows (they belong to no analysis and accumulate
+ * independently of any purge), target assessments and their annotations (a
+ * separate top-level entity), the shared regulatory corpus, `messages` rows whose
+ * thread row is already gone (nothing attributes them to an analysis), and
+ * workspace files on disk (the embedder owns their disposal).
+ */
+import { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import type { WorkflowPurger } from "../execution/workflow-purger.js";
+import { type DbError } from "../lib/db-result.js";
+import type { Logger } from "../lib/logger.js";
+/**
+ * What one invocation reclaimed. It is a report of this call, not a claim that the
+ * analysis is now empty: a re-run still reclaims whatever a failed stage left
+ * behind, and rows written under a workflow the purge already deleted, which trip
+ * their foreign key.
+ */
+export interface AnalysisPurgeOutcome {
+    readonly threads: number;
+    readonly messages: number;
+    /**
+     * How many workflows the ledger delete targeted, counted immediately before it
+     * and outside any transaction, because the engine owns the delete and reports no
+     * count of its own. It is not a post-delete tally: a row arriving between the
+     * count and the delete is deleted without being counted.
+     */
+    readonly workflows: number;
+    readonly vectorIndexDropped: boolean;
+}
+export interface AnalysisPurgeDeps {
+    readonly pool: Pool;
+    /** The workflow-ledger seam. Cancellation and deletion by id, engine-agnostic. */
+    readonly workflows: WorkflowPurger;
+    readonly logger?: Logger;
+}
+export interface AnalysisPurge {
+    /**
+     * Remove the analysis's entire persisted Postgres footprint. Absence is a
+     * normal outcome: an unknown or already-purged analysis succeeds with zeroes.
+     * Every failure rides the error channel — the operation never reports a purge
+     * it did not achieve. The caller quiesces the analysis first (module note).
+     */
+    purgeAnalysis(analysisId: string): ResultAsync<AnalysisPurgeOutcome, DbError>;
+}
+export declare function createAnalysisPurge({ pool, workflows, logger: injected }: AnalysisPurgeDeps): AnalysisPurge;

package/dist/state/purge-analysis.js

@@ -0,0 +1,205 @@
+/**
+ * purgeAnalysis — the single place that knows what an analysis's persisted
+ * Postgres footprint is.
+ *
+ * A host asks for it with an `analysisId` and nothing else: every keyed store,
+ * the analysis's dynamic vector-table name, and its workflow ids are all
+ * derivable from that id, so no caller enumerates tables or supplies a run list.
+ * The workflow ledger is part of the footprint, not a follow-on — the sandbox
+ * transcripts and run-event streams live there and are the dominant share of an
+ * analysis's stored bytes — and it is reached through the injected
+ * `WorkflowPurger` seam so the durability engine stays out of the state layer.
+ *
+ * There is no single transaction across the stages: the purge spans app tables, a
+ * DDL `DROP TABLE`, and the engine's system schema, so instead of faking atomicity
+ * every stage is idempotent and the whole operation is safe to re-run. A purge of
+ * an unknown or already-purged analysis therefore succeeds, reporting zeroes. Each
+ * stage carries the reason it sits where it does.
+ *
+ * A purge is NOT serialized against work still starting on the analysis. The
+ * mapping from an analysis to its workflows is read once, up front, out of
+ * `cortex_runs`; a run inserted after that read is outside the captured set, and
+ * the `cortex_runs` delete later in the same purge removes the only row that could
+ * ever have named it. Its workflow row and every byte cascading off it then belong
+ * to no analysis — no retry reaches them, because nothing is left that attributes
+ * them to one. Quiesce the analysis before purging it: no new runs, no new
+ * data-profile triggers. This module cannot observe a host's in-flight work, so it
+ * does not enforce that.
+ *
+ * What it does not reach, so that absent coverage is never read as delivered:
+ * scheduled operational workflows (they belong to no analysis and accumulate
+ * independently of any purge), target assessments and their annotations (a
+ * separate top-level entity), the shared regulatory corpus, `messages` rows whose
+ * thread row is already gone (nothing attributes them to an analysis), and
+ * workspace files on disk (the embedder owns their disposal).
+ */
+import { errAsync, okAsync } from "neverthrow";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { searchIndexName } from "../workspace/search-config.js";
+import { isSqlIdentifier } from "./vector-store.js";
+/**
+ * The shape an `analysisId` must take to be purgeable. It is load-bearing twice
+ * over, and neither job survives the other being dropped:
+ *
+ *  - Safe DDL interpolation. The analysis's vector-table name is derived from the
+ *    id and interpolated into `DROP TABLE`, because an identifier cannot be a bind
+ *    parameter. Confining the id to `[a-z0-9_-]` is what makes that derived name an
+ *    identifier at all.
+ *  - An unambiguous `dataprofile:` namespace. Profile workflows are found by the id
+ *    prefix `dataprofile:{analysisId}:`, matched with `starts_with` and no
+ *    delimiter check. An id holding a `:` makes analysis `a`'s prefix equally a
+ *    prefix of every workflow id of an analysis named `a:x` — and each id that
+ *    prefix returns is cancelled, then deleted with its descendants, taking another
+ *    analysis's ledger rows and everything cascading off them. Excluding `:` is the
+ *    only thing that keeps a purge inside the analysis it was asked for.
+ *
+ * Empty is outside the shape too: it derives the bare table prefix, which is a
+ * perfectly legal identifier and belongs to no analysis.
+ */
+const PURGEABLE_ANALYSIS_ID = /^[a-z0-9_-]+$/;
+/**
+ * The analysis-keyed deletes that follow the thread/message pair, in the order
+ * they run.
+ *
+ * `cortex_plans` carries its own statement, immediately ahead of the
+ * `cortex_analysis_state` row it hangs off. The foreign key between the two
+ * cascades, so on a schema that has the key the statement is redundant — but the
+ * table is provisioned with `CREATE TABLE IF NOT EXISTS`, which adds no
+ * constraint to a table that already exists, so a database whose `cortex_plans`
+ * predates the key never acquires one. Resting on the cascade alone would make
+ * the completeness of a purge contingent on a constraint being present, and would
+ * silently leave the plans behind wherever it is not. The statement removes the
+ * rows either way; the cascade stays a backstop behind it.
+ */
+const ANALYSIS_KEYED_DELETES = [
+    { op: "purgeAnalysis.artifacts", sql: "DELETE FROM cortex_artifacts WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.stepExecutions", sql: "DELETE FROM cortex_step_executions WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.runs", sql: "DELETE FROM cortex_runs WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.workingMemory", sql: "DELETE FROM cortex_working_memory WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.asks", sql: "DELETE FROM cortex_asks WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.askGrants", sql: "DELETE FROM cortex_ask_grants WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.plans", sql: "DELETE FROM cortex_plans WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.analysisState", sql: "DELETE FROM cortex_analysis_state WHERE analysis_id = $1" },
+];
+/**
+ * A refusal raised before any stage runs, so nothing is cancelled, no workflow row
+ * and no `cortex_*` row is gone, and a retry answers the same way at the same cost.
+ * `op` names the check that raised it.
+ */
+function refuse(op, message) {
+    return errAsync({ type: "mutation_failed", op, cause: new Error(message) });
+}
+/** Run one delete on the transaction's client and report how many rows it took. */
+function deleteRows(client, op, text, analysisId) {
+    return tryMutation(op, async () => {
+        const { rowCount } = await client.query({ text, values: [analysisId] });
+        return rowCount ?? 0;
+    });
+}
+export function createAnalysisPurge({ pool, workflows, logger: injected }) {
+    const logger = (injected ?? createNoopLogger()).named("purge-analysis");
+    /**
+     * Every workflow id the analysis can still be traced to, read while the rows
+     * that record them are all still on disk. `cortex_runs.run_id` IS the parent
+     * workflow id, and those rows together with the `dataprofile:{analysisId}:` id
+     * namespace are the ONLY mapping from an analysis to its workflows: a delete
+     * of `cortex_runs` that lands before this read completes strands the largest
+     * part of the footprint permanently out of reach.
+     */
+    const collectWorkflowIds = (analysisId) => tryQuery("purgeAnalysis.runWorkflowIds", async () => {
+        const { rows } = await pool.query({
+            text: "SELECT run_id FROM cortex_runs WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        return rows.map((row) => row.run_id);
+    }).andThen((runIds) => workflows.findByIdPrefix(`dataprofile:${analysisId}:`).map((profileIds) => {
+        logger.debug("collected workflow identity", { analysisId, runs: runIds.length, dataProfiles: profileIds.length });
+        // The two id sources cannot overlap, but collapsing duplicates keeps a
+        // repeated id out of the reclaimed count regardless.
+        return [...new Set([...runIds, ...profileIds])];
+    }));
+    /**
+     * One transaction for the whole `cortex_*` stage, so a mid-stage failure leaves
+     * no half-deleted analysis behind.
+     */
+    const deleteCortexRows = (analysisId) => withTransaction(pool, "purgeAnalysis.cortexRows", (client) => 
+    // `messages` has no `analysis_id` column and no foreign key: the only
+    // route from an analysis to its messages is a join through its thread
+    // rows. So the messages go first and the thread rows that name them go
+    // second — reversed, the messages become unattributable and unreachable
+    // by any later reclamation. No `deleted_at` filter on either: an archived
+    // thread is still the analysis's, and a purge takes it too.
+    deleteRows(client, "purgeAnalysis.messages", `DELETE FROM messages
+                 WHERE thread_id IN (SELECT thread_id FROM cortex_analysis_threads WHERE analysis_id = $1)`, analysisId)
+        .andThen((messages) => deleteRows(client, "purgeAnalysis.threads", "DELETE FROM cortex_analysis_threads WHERE analysis_id = $1", analysisId).map((threads) => ({
+        threads,
+        messages,
+    })))
+        // Folded so the first failure short-circuits the rest. Submitting them
+        // together would not: the transaction is aborted the moment one raises,
+        // every statement behind it comes back `25P02`, and the `op` naming the
+        // delete that actually broke is buried under theirs.
+        .andThen((counts) => ANALYSIS_KEYED_DELETES.reduce((stage, { op, sql }) => stage.andThen(() => deleteRows(client, op, sql, analysisId).map(() => undefined)), okAsync(undefined)).map(() => counts)));
+    /**
+     * `vectorIndexDropped` is established by a `to_regclass` probe taken
+     * immediately before the drop, because `DROP TABLE IF EXISTS` reports nothing
+     * about whether it found anything. The probe resolves the name exactly as the
+     * drop does — both go through `search_path`, and the probe is handed the same
+     * double-quoted form the drop interpolates, since `to_regclass` parses its
+     * argument as an SQL identifier and would fold an unquoted one to lower case.
+     * The drop runs regardless of what the probe saw, so the window between them can
+     * at worst misreport the flag for an analysis already being destroyed, never
+     * leave a table behind.
+     *
+     * `indexName` arrives already accepted at the entry point; that is the whole
+     * warrant for interpolating it into the DDL below.
+     */
+    const dropVectorIndex = (indexName) => tryQuery("purgeAnalysis.vectorIndexPresent", async () => {
+        const { rows } = await pool.query({
+            text: "SELECT to_regclass($1::text) IS NOT NULL AS present",
+            values: [`"${indexName}"`],
+        });
+        return rows[0]?.present ?? false;
+    }).andThen((present) => tryMutation("purgeAnalysis.dropVectorIndex", async () => {
+        await pool.query(`DROP TABLE IF EXISTS "${indexName}"`);
+    }).map(() => present));
+    const purgeAnalysis = (analysisId) => {
+        if (!PURGEABLE_ANALYSIS_ID.test(analysisId)) {
+            return refuse("purgeAnalysis.analysisId", `purge-analysis: refusing unpurgeable analysis id "${analysisId}"`);
+        }
+        const indexName = searchIndexName(analysisId);
+        // The id's shape already settles the derived name's characters; what it cannot
+        // settle is how long the derivation makes it. This is the same guard the vector
+        // store applies to the same name on the write side, so the accepted shape
+        // cannot drift between the two, and a name Postgres would silently truncate
+        // onto another analysis's table is refused rather than dropped.
+        if (!isSqlIdentifier(indexName)) {
+            return refuse("purgeAnalysis.vectorIndexName", `purge-analysis: unsafe vector index name "${indexName}"`);
+        }
+        return (collectWorkflowIds(analysisId)
+            // Cancel before delete. Removing the status row of a running workflow
+            // does not stop the executor running it, and that executor goes on
+            // writing rows behind the delete — re-materializing exactly the orphans
+            // the purge exists to remove. A failed cancel leaves that risk in place,
+            // so it ends the purge rather than being absorbed into a completeness
+            // claim the operation can no longer make.
+            .andThen((ids) => workflows.cancel(ids).map(() => ids))
+            // Workflow rows go before the `cortex_*` ledger that names them: a failure
+            // here leaves the id mapping on disk and a retry finds it, whereas the
+            // reverse order turns one transient failure into a permanent orphan.
+            // Descendants are included because a run's child step workflows carry the
+            // sandbox transcripts and are reachable only through their parent.
+            .andThen((ids) => workflows.deleteWorkflows(ids, true))
+            .andThen((workflowsTargeted) => deleteCortexRows(analysisId).map((counts) => ({ ...counts, workflows: workflowsTargeted })))
+            // The vector table is dropped after the transaction rather than inside
+            // it: `DROP TABLE` takes an ACCESS EXCLUSIVE lock, and enlisting it would
+            // hold that lock for the duration of every row delete above.
+            .andThen((reclaimed) => dropVectorIndex(indexName).map((vectorIndexDropped) => ({ ...reclaimed, vectorIndexDropped })))
+            .map((outcome) => {
+            logger.info("purged analysis", { analysisId, ...outcome });
+            return outcome;
+        }));
+    };
+    return { purgeAnalysis };
+}

package/dist/state/vector-store.d.ts

@@ -15,6 +15,12 @@
 import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * Whether `name` may be interpolated into a statement as an identifier. Shared
+ * with the reclaim side, which guards the same derived names against the same
+ * shape — one invariant, one place to read it.
+ */
+export declare function isSqlIdentifier(name: string): boolean;
 export interface CreateIndexInput {
     readonly indexName: string;
     readonly dimension: number;

package/dist/state/vector-store.js

@@ -14,9 +14,29 @@
  */
 import { okAsync } from "neverthrow";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
-const IDENT = /^[a-z_][a-z0-9_]*$/;
+/**
+ * The identifier shape and length the harness may interpolate into a statement.
+ * An identifier cannot be a bind parameter, so a name reaching SQL has to be
+ * checked rather than bound, and lower-snake is the whole of what the harness ever
+ * derives. The bound is as load-bearing as the shape: Postgres keeps only the
+ * first 63 bytes of an identifier and truncates the rest silently, so two longer
+ * names sharing a 63-byte prefix resolve to one table — a write that lands in
+ * another resource's index, and a drop that takes it. The shape is ASCII-only, so
+ * a name that matches it has one byte per character and `length` is the byte count
+ * the limit is measured in.
+ */
+const SQL_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+const MAX_SQL_IDENTIFIER_BYTES = 63;
+/**
+ * Whether `name` may be interpolated into a statement as an identifier. Shared
+ * with the reclaim side, which guards the same derived names against the same
+ * shape — one invariant, one place to read it.
+ */
+export function isSqlIdentifier(name) {
+    return SQL_IDENTIFIER.test(name) && name.length <= MAX_SQL_IDENTIFIER_BYTES;
+}
 function assertIdent(name) {
-    if (!IDENT.test(name)) {
+    if (!isSqlIdentifier(name)) {
         throw new Error(`vector-store: unsafe index name "${name}"`);
     }
 }