@inflexa-ai/harness 0.19.2 → 0.21.0

package/dist/state/report-session-state.js

@@ -21,6 +21,12 @@
  * document can be incomplete. A column that fails a parse reads as a typed error, and
  * it does not crash. An absent row reads as a normal absence.
  *
+ * The row also holds the derivation list of the session. One record chains a derived
+ * table to the evidence that made it: the output path, the output hash, the source
+ * paths with their hashes, the script hash, and the script text. A record is
+ * immutable, and the append refuses a repeated output path. A row that holds no list
+ * reads as an empty list.
+ *
  * A persist is a compare-and-swap. The load reads the prior document, and the persist
  * lands only when the row still holds it. Thus two concurrent turns cannot both land,
  * and the loser reads the state again.
@@ -28,12 +34,22 @@
  * A purge of the analysis removes the row through the analysis-id cascade.
  */
 import { err, ok } from "neverthrow";
+import { z } from "zod";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 import { DraftDocumentSchema } from "../report-model/draft.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
+const DerivationSourceSchema = z.object({ path: z.string(), hash: z.string() });
+const DerivationRecordSchema = z.object({
+    outputPath: z.string(),
+    outputHash: z.string(),
+    sources: z.array(DerivationSourceSchema),
+    scriptHash: z.string(),
+    script: z.string(),
+});
+const DerivationListSchema = z.array(DerivationRecordSchema);
 const _assertReadError = true;
 /** The full row projection every read shares. */
-const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, rendered_document_hash, seen_document_hash, created_at";
+const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, derivations, rendered_document_hash, seen_document_hash, created_at";
 /**
  * The insert. The row carries the snapshot at creation, and the document lands later
  * through `persistDocument`. ON CONFLICT DO NOTHING keeps the first row, thus a
@@ -72,11 +88,28 @@ function rowToState(row) {
         }
         snapshot = parsed.value;
     }
+    // A row that predates the list carries SQL NULL, and a session that derived nothing carries none
+    // either. Both read as an empty list, because a session with no derivation has none.
+    let derivations = [];
+    if (row.derivations !== null && row.derivations !== undefined) {
+        const parsed = DerivationListSchema.safeParse(row.derivations);
+        if (!parsed.success) {
+            return err({
+                type: "corrupt_session_state",
+                op: "report-session-state.read",
+                threadId: row.thread_id,
+                part: "derivations",
+                issues: reduceIssues(parsed.error),
+            });
+        }
+        derivations = parsed.data;
+    }
     return ok({
         threadId: row.thread_id,
         analysisId: row.analysis_id,
         document,
         snapshot,
+        derivations,
         renderedDocumentHash: row.rendered_document_hash,
         seenDocumentHash: row.seen_document_hash,
         createdAt: row.created_at,
@@ -173,5 +206,40 @@ export function createReportSessionStateStore({ pool }) {
             return row.copied === null ? "no-rendered" : "stamped";
         });
     }
-    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen };
+    function appendDerivation(threadId, record) {
+        return tryMutation("report-session-state.appendDerivation", async () => {
+            // One statement tells a duplicate from an absence, the same way the persist does. `existed`
+            // counts the row, and `appended` counts the update.
+            //
+            // The name rule sits in the qualification of the UPDATE, over the row that the statement locks.
+            // A read of the CTE would test the list as it stood at the start of the statement: two
+            // concurrent appends of one name would each pass that test, and both would land. Postgres
+            // re-evaluates the qualification of an UPDATE against the row that it waited for, thus the
+            // loser of the race sees the list of the winner and it appends nothing.
+            const { rows } = await pool.query({
+                text: `WITH target AS (
+    SELECT thread_id
+      FROM cortex_report_session_state
+     WHERE thread_id = $1
+  ), appended AS (
+    UPDATE cortex_report_session_state AS s
+       SET derivations = COALESCE(s.derivations, '[]'::jsonb) || $2::jsonb
+     WHERE s.thread_id = $1
+       AND NOT EXISTS (
+         SELECT 1 FROM jsonb_array_elements(COALESCE(s.derivations, '[]'::jsonb)) AS held WHERE held->>'outputPath' = $3
+       )
+    RETURNING 1
+  )
+  SELECT (SELECT COUNT(*) FROM target)::int AS existed, (SELECT COUNT(*) FROM appended)::int AS appended`,
+                // The record rides as a one-element array, thus the `||` operator appends one element and
+                // never merges the fields of an object into the list.
+                values: [threadId, JSON.stringify([record]), record.outputPath],
+            });
+            const row = rows[0];
+            if (row === undefined || row.existed === 0)
+                return "absent";
+            return row.appended > 0 ? "appended" : "duplicate";
+        });
+    }
+    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen, appendDerivation };
 }

package/dist/state/report-versions.d.ts

@@ -1,14 +1,17 @@
 /**
- * The report version store -- the append-only record of report versions.
+ * The report version store -- the one recorded version of each report thread.
  *
- * A version is one immutable row. It holds the block document, the pinned
- * snapshot, and the anchor. The store records a version and reads a version. It
- * never updates a recorded row, thus a correction is a new version.
+ * A version is one row. It holds the block document, the pinned snapshot, and the
+ * anchor. The store records a version and reads a version. A record on a thread
+ * that holds a version replaces the document, the snapshot, and the anchor of that
+ * row, whole. The version id stays, thus a consumer that names the version keeps
+ * its name.
  *
  * A thread holds at most one version, and a named unique constraint on the thread
- * id enforces it. The record reads nothing before the insert. A second record for
- * one thread trips the constraint, and the store maps that trip to the typed
- * refusal thread_already_holds_version.
+ * id enforces it. The record reads nothing before the write, and the constraint
+ * routes it: a fresh thread takes the insert arm, and a thread that holds a version
+ * takes the replace arm. The store writes the full triple each time, thus a partial
+ * update is not representable.
  *
  * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
@@ -42,9 +45,14 @@ export interface RecordVersionInput {
     /** The earlier version that this one reuses. The parent must belong to the same analysis. */
     readonly parentVersionId?: string;
 }
-/** The stable reference of a freshly recorded version. */
+/** The stable reference of a recorded version, and how the record landed. */
 export interface RecordedVersionRef {
     readonly versionId: string;
+    /**
+     * `created` minted the row. `replaced` wrote over the one version of the
+     * thread, under the same version id.
+     */
+    readonly outcome: "created" | "replaced";
 }
 /**
  * A record the store refuses as data, before or in place of a row. Distinct from
@@ -54,9 +62,9 @@ export interface RecordedVersionRef {
  * refuses a malformed document or a malformed snapshot here as typed data, and
  * no row lands.
  *
- * A second record for one thread is `thread_already_holds_version`. The unique
- * constraint on the thread id trips, and the record maps that one constraint by
- * its name. Every other constraint trip stays a `DbError`.
+ * A second record for one thread is no refusal. The unique constraint on the
+ * thread id routes it into the replace arm, and the row carries the new triple.
+ * Every constraint trip stays a `DbError`.
  *
  * A `parentVersionId` naming no row is not one of these -- the self foreign key
  * refuses an unknown parent id, and `tryMutation` classifies that refusal as the
@@ -76,10 +84,6 @@ export type RecordVersionError = {
     readonly analysisId: string;
     readonly parentVersionId: string;
     readonly parentAnalysisId: string;
-} | {
-    readonly type: "thread_already_holds_version";
-    readonly op: string;
-    readonly threadId: string;
 } | DbError;
 /**
  * A stored row that a read cannot parse with the current schemas. It names the
@@ -109,8 +113,9 @@ export interface ReportVersionStore {
     /**
      * Record a version. The record parses the document, refuses a malformed value
      * as data with no row, and refuses a parent from a different analysis. It reads
-     * nothing before the insert. A second record for one thread refuses with
-     * thread_already_holds_version. The snapshot and the anchor store as given.
+     * nothing before the write. A record on a thread that holds a version replaces
+     * that row whole, under the same version id. The snapshot and the anchor store
+     * as given, and the reference names a creation or a replacement.
      */
     record(input: RecordVersionInput): ResultAsync<RecordedVersionRef, RecordVersionError>;
     /** One version by its id, or `null` when no row holds it. */

package/dist/state/report-versions.js

@@ -1,14 +1,17 @@
 /**
- * The report version store -- the append-only record of report versions.
+ * The report version store -- the one recorded version of each report thread.
  *
- * A version is one immutable row. It holds the block document, the pinned
- * snapshot, and the anchor. The store records a version and reads a version. It
- * never updates a recorded row, thus a correction is a new version.
+ * A version is one row. It holds the block document, the pinned snapshot, and the
+ * anchor. The store records a version and reads a version. A record on a thread
+ * that holds a version replaces the document, the snapshot, and the anchor of that
+ * row, whole. The version id stays, thus a consumer that names the version keeps
+ * its name.
  *
  * A thread holds at most one version, and a named unique constraint on the thread
- * id enforces it. The record reads nothing before the insert. A second record for
- * one thread trips the constraint, and the store maps that trip to the typed
- * refusal thread_already_holds_version.
+ * id enforces it. The record reads nothing before the write, and the constraint
+ * routes it: a fresh thread takes the insert arm, and a thread that holds a version
+ * takes the replace arm. The store writes the full triple each time, thus a partial
+ * update is not representable.
  *
  * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
@@ -25,9 +28,8 @@ import { ReportDocumentSchema } from "../contracts/report-blocks.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 /**
- * The name of the unique constraint on thread_id. Postgres reports it on a
- * duplicate-thread refusal, and the record matches it to map the trip to the
- * thread_already_holds_version refusal.
+ * The name of the unique constraint on thread_id. The write names it as its
+ * conflict target, thus the replace arm binds to the one row of the thread.
  */
 const THREAD_UNIQUE_CONSTRAINT = "cortex_report_versions_one_per_thread";
 const _assertRecordError = true;
@@ -39,13 +41,30 @@ const _assertReadError = true;
  */
 const VERSION_COLUMNS = "version_id, analysis_id, thread_id, parent_thread_id, parent_seq::text AS parent_seq, parent_version_id, document, snapshot, created_at";
 /**
- * The insert. The row carries no ordinal, thus the statement writes the given
- * columns directly. `created_at` takes the column default.
+ * The write. The row carries no ordinal, thus the statement writes the given
+ * columns directly. A fresh thread takes the insert arm, and `created_at` takes
+ * the column default. A thread that holds a version trips the named constraint,
+ * and the conflict target turns the trip into the replace of that one row.
+ *
+ * The replace arm writes each given column, thus the stored row equals the input.
+ * It writes neither `version_id` nor `created_at`: the version keeps its name, and
+ * the row keeps the time of its first record.
+ *
+ * The returned id names the row that stands. It equals the minted id on the insert
+ * arm alone, thus the caller reads which arm ran.
  */
-const INSERT_SQL = `INSERT INTO cortex_report_versions
+const RECORD_SQL = `INSERT INTO cortex_report_versions
     (version_id, analysis_id, thread_id, parent_thread_id, parent_seq,
      parent_version_id, document, snapshot)
-  VALUES ($1, $2, $3, $4, $5::bigint, $6, $7::jsonb, $8::jsonb)`;
+  VALUES ($1, $2, $3, $4, $5::bigint, $6, $7::jsonb, $8::jsonb)
+  ON CONFLICT ON CONSTRAINT ${THREAD_UNIQUE_CONSTRAINT} DO UPDATE SET
+    analysis_id = EXCLUDED.analysis_id,
+    parent_thread_id = EXCLUDED.parent_thread_id,
+    parent_seq = EXCLUDED.parent_seq,
+    parent_version_id = EXCLUDED.parent_version_id,
+    document = EXCLUDED.document,
+    snapshot = EXCLUDED.snapshot
+  RETURNING version_id`;
 function rowToVersion(row) {
     const document = ReportDocumentSchema.safeParse(row.document);
     if (!document.success) {
@@ -67,16 +86,6 @@ function rowToVersion(row) {
         createdAt: row.created_at,
     });
 }
-/**
- * Map an insert failure to a record refusal. A trip of the thread constraint is
- * thread_already_holds_version. Every other DbError stays unchanged.
- */
-function mapInsertError(error, threadId) {
-    if (error.type === "constraint_violation" && error.constraint === THREAD_UNIQUE_CONSTRAINT) {
-        return { type: "thread_already_holds_version", op: "report-versions.record", threadId };
-    }
-    return error;
-}
 /**
  * Create a `ReportVersionStore` bound to a Postgres pool. The
  * `cortex_report_versions` table is provisioned by the state-init DDL.
@@ -85,7 +94,7 @@ export function createReportVersionStore({ pool }) {
     /**
      * The analysis scope of a parent version, or `null` when no such row exists.
      * Absence is not a verdict here: an unknown parent id falls through to the
-     * insert, where the self foreign key refuses it as a `DbError`.
+     * write, where the self foreign key refuses it as a `DbError`.
      */
     function parentAnalysis(parentVersionId) {
         return tryQuery("report-versions.record.parentScope", () => pool.query({
@@ -105,13 +114,13 @@ export function createReportVersionStore({ pool }) {
         if (parsedSnapshot.isErr()) {
             return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
         }
-        const insert = () => {
-            const versionId = randomUUID();
-            return tryMutation("report-versions.record.insert", async () => {
-                await pool.query({
-                    text: INSERT_SQL,
+        const write = () => {
+            const minted = randomUUID();
+            return tryMutation("report-versions.record.write", async () => {
+                const { rows } = await pool.query({
+                    text: RECORD_SQL,
                     values: [
-                        versionId,
+                        minted,
                         input.analysisId,
                         input.threadId,
                         input.parentThreadId,
@@ -121,11 +130,15 @@ export function createReportVersionStore({ pool }) {
                         JSON.stringify(input.snapshot),
                     ],
                 });
-                return { versionId };
-            }).mapErr((error) => mapInsertError(error, input.threadId));
+                // Each arm of the write returns its row. The replace arm keeps the
+                // version id of the row that stood, thus an id that differs from the
+                // minted one names a replacement.
+                const landed = rows[0]?.version_id ?? minted;
+                return { versionId: landed, outcome: landed === minted ? "created" : "replaced" };
+            });
         };
         if (input.parentVersionId === undefined) {
-            return insert();
+            return write();
         }
         const parentVersionId = input.parentVersionId;
         return parentAnalysis(parentVersionId).andThen((parentAnalysisId) => {
@@ -138,7 +151,7 @@ export function createReportVersionStore({ pool }) {
                     parentAnalysisId,
                 });
             }
-            return insert();
+            return write();
         });
     }
     function getVersion(versionId) {

package/dist/state/snapshot-parse.js

@@ -23,6 +23,11 @@ const ArtifactSnapshotSchema = z.object({
 });
 /** The citation list of a stored snapshot. A snapshot with no list reads as an absent field. */
 const CitationsSchema = z.array(z.string()).optional();
+/**
+ * The citation records of a stored snapshot, keyed by the citation key. A snapshot with no map reads as
+ * an absent field, thus a pin that predates the map loads the same as it did before.
+ */
+const CitationRecordsSchema = z.record(z.string(), z.object({ citation: z.string(), description: z.string().optional() })).optional();
 /** Reduce a zod error to the dotted path and the message of each issue. */
 export function reduceIssues(error) {
     return error.issues.map((issue) => ({
@@ -63,6 +68,10 @@ export function parseSnapshot(stored) {
     if (!citations.success) {
         return err(prefixIssues("citations", reduceIssues(citations.error)));
     }
+    const citationRecords = CitationRecordsSchema.safeParse(stored.citationRecords);
+    if (!citationRecords.success) {
+        return err(prefixIssues("citationRecords", reduceIssues(citationRecords.error)));
+    }
     // The map takes a null prototype, the same as the pin, thus a path such as
     // `__proto__` stays an ordinary entry and never reaches a prototype slot.
     const artifacts = Object.create(null);
@@ -78,5 +87,11 @@ export function parseSnapshot(stored) {
     if (issues.length > 0) {
         return err(issues);
     }
-    return citations.data === undefined ? ok({ artifacts }) : ok({ artifacts, citations: citations.data });
+    // An absent part stays absent in the parsed value. Thus a reload gives the same shape that the pin
+    // wrote, and an equality test over a stored snapshot holds across the round trip.
+    return ok({
+        artifacts,
+        ...(citations.data === undefined ? {} : { citations: citations.data }),
+        ...(citationRecords.data === undefined ? {} : { citationRecords: citationRecords.data }),
+    });
 }

package/dist/tasks/data-profile.d.ts

@@ -23,7 +23,6 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { Logger } from "../lib/logger.js";
-import type { ResolveBilling } from "../billing/resolver.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { SandboxClient } from "../sandbox/client.js";
@@ -57,9 +56,13 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
     readonly skillsDir: string;
     /** LLM usage-accounting seam for the profiler agent loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
-    /** Resolves the billing context stamped as the sandbox pod's OpenCost
-     *  labels. Absent in upstream-less (dev/OSS) wiring — pods spawn unlabeled. */
-    readonly resolveBilling?: ResolveBilling;
+    /**
+     * Host-supplied labels for the profiler's sandbox pod, resolved under the
+     * profiling session. The map is opaque to the harness: it stamps each entry
+     * and interprets none of it. Absent in a wiring that attributes nothing —
+     * the pod then carries the harness's own labels only.
+     */
+    readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -42,8 +42,6 @@ import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.j
 import { DATA_PROFILE_RUN_LITERAL } from "../contracts/data-profile.js";
 const DATA_PROFILE_STEP_LITERAL = "profile";
 const DATA_PROFILE_AGENT_ID = "data-profiler";
-/** Resolved-header key carrying the billing-context id (see `ResolveBilling`). */
-const BILLING_CONTEXT_HEADER = "X-Inflexa-Billing-Context";
 /** Sandbox-server exec budget for the profile run. */
 const DEFAULT_DEADLINE_MS = 300_000;
 /** Build the canonical artifact path for a staged input file. */
@@ -228,16 +226,18 @@ export async function runDataProfileBody(input, deps) {
         // from the agent loop would leave the longest wait of all unreported — the same defect the
         // run panel's activity readout was built to remove.
         await activity.sandboxInit();
-        let billingContextId;
-        if (deps.resolveBilling) {
+        let podLabels;
+        if (deps.resolvePodLabels) {
             try {
-                billingContextId = (await deps.resolveBilling(childSession))[BILLING_CONTEXT_HEADER];
+                podLabels = await deps.resolvePodLabels(childSession);
             }
             catch (err) {
-                logger.error("[billing] data-profile billing resolution failed", logger.errorFields(err));
+                logger.warn("pod-label resolution failed", logger.errorFields(err));
             }
-            if (!billingContextId)
-                logger.error("[billing] sandbox spawned without billing labels");
+            // A wired resolver that yields nothing is the one loud case: the host
+            // asked for attribution and the pod spawns without it.
+            if (!podLabels || Object.keys(podLabels).length === 0)
+                logger.warn("sandbox spawned with no pod labels");
         }
         const sandbox = await deps.sandboxClient.createSandbox({
             runId: DATA_PROFILE_RUN_LITERAL,
@@ -245,7 +245,7 @@ export async function runDataProfileBody(input, deps) {
             analysisId,
             childWorkflowId: workflowId,
             resources: estimateDataProfileResources(stagedInputs),
-            billing: billingContextId ? { billingContextId, userId: childSession.identity.user } : undefined,
+            podLabels,
         }, mintSandboxIdentity(DATA_PROFILE_RUN_LITERAL));
         try {
             // Checkpointed clock, not `Date.now()`: `awaitExec` gates on this absolute

package/dist/tools/define-tool.d.ts

@@ -116,6 +116,8 @@ export interface Tool<Input = unknown, Output = unknown> {
     readonly executionMode: ToolExecutionMode;
     /** See {@link ToolDefinition.describeCall}. Absent when the tool declares none. */
     describeCall?(input: Input): string;
+    /** See {@link ToolDefinition.describeResult}. Absent when the tool declares none. */
+    describeResult?(input: Input, result: Output): string;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 export interface ToolDefinition<Schema extends z.ZodType, Output> {
@@ -156,6 +158,36 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * The hook never reaches the model.
      */
     describeCall: ((input: z.infer<Schema>) => string) | "none";
+    /**
+     * One line that names what THIS call PRODUCED — the outcome-time counterpart
+     * of `describeCall`. A page path, a recorded id, and a listed count are facts
+     * of the result, thus no hook over the input can name one. The finished event
+     * carries this line, and it carries the call detail when the hook gives
+     * nothing.
+     *
+     * The decision is OPTIONAL, unlike `describeCall`. A call always has an input
+     * to describe or an input that cannot distinguish it, thus that decision is
+     * forced. A result is different: a tool whose ok value adds no fact that a
+     * reader wants leaves the call detail to stand for the whole call. Thus the
+     * absent key is the whole of "this tool describes no result", and the `"none"`
+     * sentinel has no counterpart here.
+     *
+     * The hook runs on an ok outcome only. An error outcome already names itself,
+     * and a hook over a failed call reads a shape that does not exist.
+     *
+     * A hook is synchronous and pure — no I/O, no ambient state — and a
+     * description must never fail a call: the loop guards the call and drops the
+     * detail on any failure (see the tool-call-detail capability). The result
+     * arrives as the tool produced it, thus the hook reads a value of its own
+     * declared `Output` type and no parse stands between the two.
+     *
+     * Return whatever reads best. Normalization — one line, control characters
+     * removed, secrets redacted, length capped — happens once at the emit site,
+     * never here.
+     *
+     * The hook never reaches the model.
+     */
+    readonly describeResult?: (input: z.infer<Schema>, result: Output) => string;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -75,6 +75,10 @@ export function defineTool(def) {
         // `typeof` is the discriminator, not equality with the sentinel, so a
         // hook that returns the string `"none"` still packages as a hook.
         ...(typeof def.describeCall === "function" ? { describeCall: def.describeCall } : {}),
+        // The same property-presence pattern as `describeCall`: a tool that
+        // declares no result hook carries no key, thus "has a hook" is one
+        // property check on either side.
+        ...(typeof def.describeResult === "function" ? { describeResult: def.describeResult } : {}),
         execute: def.execute,
     };
 }

package/dist/tools/detail-resolver.d.ts

@@ -15,8 +15,13 @@
  *   registry construction.
  *
  * It resolves through the same `computeDetail` the loop uses, so a reloaded
- * thread cannot show a different detail from the one the live turn showed.
- * Nothing is persisted: storage stays the pure model transcript.
+ * thread shows the same CALL detail the live turn showed.
+ *
+ * The bound is the input. A reload reconstructs from the persisted call alone, and a
+ * tool that describes its own RESULT names a fact that the input cannot carry — a page
+ * path, a recorded version. That line reaches the live surface on the finished event and
+ * it does not reappear here, thus a reloaded call falls back to its call detail. Nothing
+ * is persisted: storage stays the pure model transcript.
  */
 import { type ToolCallDetail } from "../loop/tool-detail.js";
 import type { Logger } from "../lib/logger.js";

package/dist/tools/detail-resolver.js

@@ -15,8 +15,13 @@
  *   registry construction.
  *
  * It resolves through the same `computeDetail` the loop uses, so a reloaded
- * thread cannot show a different detail from the one the live turn showed.
- * Nothing is persisted: storage stays the pure model transcript.
+ * thread shows the same CALL detail the live turn showed.
+ *
+ * The bound is the input. A reload reconstructs from the persisted call alone, and a
+ * tool that describes its own RESULT names a fact that the input cannot carry — a page
+ * path, a recorded version. That line reaches the live surface on the finished event and
+ * it does not reappear here, thus a reloaded call falls back to its call detail. Nothing
+ * is persisted: storage stays the pure model transcript.
  */
 import { computeDetail } from "../loop/tool-detail.js";
 import { createNoopLogger } from "../lib/console-logger.js";

package/dist/tools/iterate-report.d.ts

@@ -120,8 +120,8 @@ export declare const ReportBriefSchema: z.ZodObject<{
                 source: z.ZodString;
             }, z.core.$strip>>;
             chartType: z.ZodEnum<{
-                line: "line";
                 bar: "bar";
+                line: "line";
                 scatter: "scatter";
                 histogram: "histogram";
                 box: "box";

package/dist/tools/report/preview-snapshot.js

@@ -80,6 +80,7 @@ export function createPreviewSnapshotTool(state) {
                 return ok({
                     ok: true,
                     screenshotBase64: captured.screenshotBase64,
+                    coverage: captured.coverage,
                     consoleErrors: captured.consoleErrors,
                     failedRequests: captured.failedRequests,
                 });

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -22,12 +22,13 @@ import type { Scope } from "../../auth/types.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
 import { type FinishResult } from "../../report-model/draft-finish.js";
-import { type DraftDocument } from "../../report-model/draft.js";
+import type { DraftDocument } from "../../report-model/draft.js";
 import type { ReportSnapshot } from "../../report-model/reference-resolver.js";
+import type { DerivationRecord } from "../../state/report-session-state.js";
 import { type Tool } from "../define-tool.js";
 /** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
 declare const addBlockInput: z.ZodObject<{
-    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>;
+    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     place: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         end: "end";
@@ -44,7 +45,7 @@ declare const addBlockInput: z.ZodObject<{
 declare const changeBlockInput: z.ZodObject<{
     targetId: z.ZodString;
     title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>>;
+    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>>;
 }, z.core.$strip>;
 declare const removeBlockInput: z.ZodObject<{
     targetId: z.ZodString;
@@ -158,12 +159,17 @@ export interface ReportSessionState {
 export type SessionStateToken = DraftDocument | null;
 /**
  * The outcome of a gateway load. `found` carries the state, the analysis that owns the thread, the
- * concurrency token, and the seen-document hash of the look-before-record rule. `absent` and `wrong-type`
- * are permanent conditions, and `failed` is a transient fault that names its cause.
+ * concurrency token, the seen-document hash of the look-before-record rule, and the derivations of the
+ * session. `absent` and `wrong-type` are permanent conditions, and `failed` is a transient fault that names
+ * its cause.
  *
  * `seenDocumentHash` is the hash that the last eyes capture saw, or `null` before the first look. The record
  * tool compares it against the hash of the current draft, thus a never-seen page and a stale look each
  * refuse.
+ *
+ * `derivations` is the ledger of the session, in the order that the records landed. The snapshot already
+ * carries each derived path as a member, thus a tool that binds reads the snapshot. The records themselves
+ * carry the chain, and the finish, the appendix, and the prune each read them.
  */
 export type SessionStateLoad = {
     outcome: "found";
@@ -171,6 +177,7 @@ export type SessionStateLoad = {
     analysisId: string;
     token: SessionStateToken;
     seenDocumentHash: string | null;
+    derivations: readonly DerivationRecord[];
 } | {
     outcome: "absent";
 } | {
@@ -243,7 +250,7 @@ export interface ReportSessionStateGateway {
 }
 /**
  * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
- * against, and the seen-document hash of the look-before-record rule.
+ * against, the seen-document hash of the look-before-record rule, and the derivations of the session.
  */
 export interface OpenedThread {
     readonly threadId: string;
@@ -252,6 +259,8 @@ export interface OpenedThread {
     readonly token: SessionStateToken;
     /** The hash that the last eyes capture saw, or `null` before the first look. */
     readonly seenDocumentHash: string | null;
+    /** The derivations of the session, in the order that the records landed. */
+    readonly derivations: readonly DerivationRecord[];
 }
 /**
  * Resolve the report thread of a call, and load its state through the gateway.