@inflexa-ai/harness 0.31.0 → 0.32.0

package/dist/schemas/artifact-manifest.d.ts

@@ -8,9 +8,9 @@ import { z } from "zod";
 /** Artifact type inferred from the step subdirectory. */
 export declare const ArtifactTypeSchema: z.ZodEnum<{
     output: "output";
-    script: "script";
-    figure: "figure";
     log: "log";
+    figure: "figure";
+    script: "script";
     notebook: "notebook";
 }>;
 export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
@@ -22,9 +22,9 @@ export declare const ArtifactManifestEntrySchema: z.ZodObject<{
     size: z.ZodNumber;
     type: z.ZodEnum<{
         output: "output";
-        script: "script";
-        figure: "figure";
         log: "log";
+        figure: "figure";
+        script: "script";
         notebook: "notebook";
     }>;
     hash: z.ZodOptional<z.ZodString>;

package/dist/tools/display/show-user.d.ts

@@ -23,7 +23,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "markdown" | "echart" | "svg" | "table";
+    kind: "code" | "markdown" | "table" | "echart" | "svg";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

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

@@ -19,6 +19,8 @@
 import { type Result } from "neverthrow";
 import { z } from "zod";
 import type { Scope } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import { type ProvenanceSeam } from "../../provenance/seam.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";
@@ -289,12 +291,25 @@ export interface ReportAuthoringTools {
     readonly read_block: Tool<ReadBlockInput, ReadBlockResult>;
     readonly finish_draft: Tool<FinishDraftInput, FinishToolResult>;
 }
+/**
+ * The optional deps of the authoring surface. The gateway is the one mandatory part, thus it stays a
+ * parameter of its own and this bag holds what a composition can leave out.
+ */
+export interface ReportAuthoringToolDeps {
+    /** The provenance seam; an unbound session emit emits nothing and each tool acts the same. */
+    readonly provenance?: ProvenanceSeam;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
+}
 /**
  * Make the eight authoring tools over a session-state gateway.
  *
  * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
+ *
+ * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
+ * failed persist each emit nothing.
  */
-export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway): ReportAuthoringTools;
+export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway, deps?: ReportAuthoringToolDeps): ReportAuthoringTools;
 export {};

package/dist/tools/report-authoring/authoring-tools.js

@@ -19,7 +19,9 @@
 import { err, ok } from "neverthrow";
 import { basename } from "node:path";
 import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
@@ -299,6 +301,23 @@ function addedSubject(kind, block) {
 function holderIdOf(document, blockId) {
     return locate(document, blockId)?.parent?.id;
 }
+/**
+ * The event of one block act, or `undefined` when the document holds no block of that id.
+ *
+ * The kind rides beside the id, thus a reader of the record sees what the act touched and it needs no
+ * document of its own. The kind comes out of the document that holds the block after the act: the next
+ * document for an add, a change, and a move, and the previous one for a remove.
+ *
+ * A lookup of a landed operation always finds its block. The absent arm keeps the read total, and it drops
+ * the event rather than state a kind that no block carries.
+ */
+function blockActOf(type, scope, document, blockId) {
+    const kind = locate(document, blockId)?.block.kind;
+    if (kind === undefined) {
+        return undefined;
+    }
+    return { type, analysisId: scope.analysisId, threadId: scope.threadId, blockId, blockKind: kind };
+}
 /** Read the child order of one container out of a document. */
 function containerIn(document, parentId) {
     if (parentId === undefined) {
@@ -326,8 +345,12 @@ const AUTHORING_EXECUTION_MODE = "inline";
  * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
+ *
+ * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
+ * failed persist each emit nothing.
  */
-export function createReportAuthoringTools(gateway) {
+export function createReportAuthoringTools(gateway, deps = {}) {
+    const observe = bindSessionEmit(deps.provenance, (deps.logger ?? createNoopLogger()).named("report-authoring"));
     /**
      * Resolve the thread of the call, and load its state.
      *
@@ -346,8 +369,13 @@ export function createReportAuthoringTools(gateway) {
      *
      * The persist is a compare-and-swap against the token that the load read. A concurrent turn that landed
      * first turns the persist into a conflict, and the tool refuses with `stale-state`.
+     *
+     * `event` is the observation of the operation, and it emits after the persist landed. Thus one site owns
+     * the rule, and a refusal, a conflict, and a persist fault each emit nothing. It reads the two documents
+     * for the same reason that `holders` does: a removed block sits in the first alone, and an added block
+     * sits in the second alone. A caller that cannot name the block of its own operation gives no event.
      */
-    const land = async (threadId, token, previous, result, holders) => {
+    const land = async (threadId, token, previous, result, holders, event) => {
         if (result.isErr()) {
             return { applied: false, refusal: result.error };
         }
@@ -362,6 +390,10 @@ export function createReportAuthoringTools(gateway) {
         if (persisted.outcome === "failed") {
             return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
         }
+        const observed = event(previous, next);
+        if (observed !== undefined) {
+            observe(observed);
+        }
         // A move inside one container names the same holder two times.
         const unique = [...new Set(holders(previous, next))];
         return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
@@ -390,14 +422,17 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
             const block = decodeBlockPayload(input.block);
             const addedId = readId(block);
-            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)]));
+            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)], 
+            // The grammar requires an id on the payload, thus a landed add always names one. A
+            // payload with no id reaches the core, which refuses it, and no event is due.
+            (_previous, next) => (addedId === undefined ? undefined : blockActOf("add-block", { analysisId, threadId }, next, addedId))));
         },
     });
     const change_block = defineTool({
@@ -413,14 +448,15 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const operation = toChangeOperation(input);
             if (operation.isErr()) {
                 return ok(refuse(operation.error));
             }
-            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [
-                holderIdOf(next, input.targetId),
-            ]));
+            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [holderIdOf(next, input.targetId)], 
+            // A change is permitted to change the kind, thus the event states the kind that the
+            // document holds after the act.
+            (_previous, next) => blockActOf("change-block", { analysisId, threadId }, next, input.targetId)));
         },
     });
     const remove_block = defineTool({
@@ -434,10 +470,11 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [
-                holderIdOf(previous, input.targetId),
-            ]));
+            const { threadId, analysisId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [holderIdOf(previous, input.targetId)], 
+            // The next document holds no removed block, thus the event states the kind that the
+            // previous one carried.
+            (previous) => blockActOf("remove-block", { analysisId, threadId }, previous, input.targetId)));
         },
     });
     const move_block = defineTool({
@@ -452,12 +489,12 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
-            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)]));
+            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)], (_previous, next) => blockActOf("move-block", { analysisId, threadId }, next, input.targetId)));
         },
     });
     const set_title = defineTool({
@@ -473,8 +510,13 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => []));
+            const { threadId, analysisId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => [], () => ({
+                type: "set-title",
+                analysisId,
+                threadId,
+                title: input.title,
+            })));
         },
     });
     const read_outline = defineTool({

package/dist/tools/report-session/derive-table.d.ts

@@ -42,6 +42,7 @@ import type { DerivationSource, ReportSessionStateStore } from "../../state/repo
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 /** The input of one derivation: the script, the declared pinned inputs, and the name of the output file. */
 declare const deriveTableInput: z.ZodObject<{
     script: z.ZodString;
@@ -114,6 +115,8 @@ export interface DeriveTableToolDeps {
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     readonly runDerivation?: DeriveTableRunner;
     readonly runAuthorizer?: RunAuthorizer;
+    /** The provenance seam; an unbound session emit emits nothing and the derivation runs the same. */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /** The synthetic run id and step id of one derivation. Both are constants, and neither names a run row. */

package/dist/tools/report-session/derive-table.js

@@ -45,6 +45,7 @@ import { generateExecutionId } from "../../sandbox/execution-id.js";
 import { isSafeId, reportSessionDerivedDir, toSandboxPath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 import { readHeaderColumns } from "./list-artifacts.js";
 /** The input of one derivation: the script, the declared pinned inputs, and the name of the output file. */
 const deriveTableInput = z.object({
@@ -128,6 +129,7 @@ export function describeExecFailure(result) {
  */
 export function createDeriveTableTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table");
+    const observe = bindSessionEmit(deps.provenance, logger);
     const { runDerivation, runAuthorizer } = deps;
     return defineTool({
         id: "derive_table",
@@ -252,6 +254,19 @@ export function createDeriveTableTool(deps) {
                     outputName: input.output,
                     logger,
                 });
+                // The record of the derivation lands before this point, thus the event states a table that
+                // the session already holds as evidence. Each other arm derived nothing.
+                if (result.outcome === "derived") {
+                    observe({
+                        type: "run-derivation",
+                        analysisId,
+                        threadId,
+                        outputPath: result.path,
+                        outputHash: result.hash,
+                        scriptHash: result.scriptHash,
+                        sources: result.sources,
+                    });
+                }
                 return ok(result);
             }
             finally {

package/dist/tools/report-session/preview-report.d.ts

@@ -7,10 +7,12 @@
  * and renders the page.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
- * them beside the figures. It also writes the script of each derivation that the document references, from
- * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
- * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
- * wrote stays, and each other file goes.
+ * them beside the figures. The tool asks the optional provenance source for the frozen document of the
+ * analysis first, and the renderer turns the opaque text into data assets of the same kind. It also writes
+ * the script of each derivation that the document references, from the text of the durable record. The
+ * shipped libraries and fonts stage under `assets/deps/`, and each report-side file at the root of
+ * `assets/`. The stage is authoritative over that root: what this preview wrote stays, and each other file
+ * goes.
  *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
@@ -45,6 +47,7 @@ import { type BridgeMismatch } from "../../report-render/value-bridge.js";
 import type { RenderProblem } from "../../report-render/types.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type MakeSessionPagePublisher } from "./session-page-publisher.js";
 /** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
 declare const previewReportInput: z.ZodObject<{}, z.core.$strip>;
@@ -135,6 +138,12 @@ export interface PreviewReportToolDeps {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly resolvePageAsset?: ResolvePageAsset;
     readonly makeSessionPages?: MakeSessionPagePublisher;
+    /**
+     * The provenance seam. An unbound session emit emits nothing and the render runs the same. An unbound
+     * document read, and a read that holds no document for the analysis, both give absence, and the page
+     * then carries no provenance asset.
+     */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

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

@@ -7,10 +7,12 @@
  * and renders the page.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
- * them beside the figures. It also writes the script of each derivation that the document references, from
- * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
- * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
- * wrote stays, and each other file goes.
+ * them beside the figures. The tool asks the optional provenance source for the frozen document of the
+ * analysis first, and the renderer turns the opaque text into data assets of the same kind. It also writes
+ * the script of each derivation that the document references, from the text of the durable record. The
+ * shipped libraries and fonts stage under `assets/deps/`, and each report-side file at the root of
+ * `assets/`. The stage is authoritative over that root: what this preview wrote stays, and each other file
+ * goes.
  *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
@@ -55,6 +57,7 @@ import { ASSETS_DIR, DEPS_DIR, derivationScriptName, PAGE_ASSETS, stagedSource,
 import { renderReportPage } from "../../report-render/render.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindReadExport, bindSessionEmit } from "../../provenance/seam.js";
 import { describeSessionPageMintFailure } from "./session-page-publisher.js";
 /** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
 const previewReportInput = z.object({});
@@ -383,6 +386,8 @@ async function mintAccess(makeSessionPages, analysisId, threadId, auth, logger)
  */
 export function createPreviewReportTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("preview-report");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    const readProvenance = bindReadExport(deps.provenance, logger);
     const resolvePageAsset = deps.resolvePageAsset ?? resolvePageAssetFromInstallation;
     return defineTool({
         id: "preview_report",
@@ -438,7 +443,15 @@ export function createPreviewReportTool(deps) {
             // relative links of its entry, thus the renderer states them and it stages nothing.
             const used = referencedDerivations(document, derivations);
             const sessionDir = reportSessionDir(threadId);
-            const rendered = renderReportPage(document, bridged.value, snapshot.citationRecords, used.map((record) => chainOf(record, sessionDir)));
+            // The provenance is the frozen document of the analysis. It rides the render as opaque text, thus
+            // the renderer moves it into a data asset and no part of this path reads a field of it. Absence
+            // gives a page with no provenance asset, and each other part of the render is unchanged.
+            const provenance = await readProvenance(analysisId);
+            const rendered = renderReportPage(document, bridged.value, {
+                records: snapshot.citationRecords,
+                derivations: used.map((record) => chainOf(record, sessionDir)),
+                provenance,
+            });
             if (rendered.isErr()) {
                 return ok({ outcome: "render-problems", problems: rendered.error });
             }
@@ -471,7 +484,8 @@ export function createPreviewReportTool(deps) {
             // The page shows the draft that the finish read. The stamp records that draft, thus the eyes
             // copy this hash and the record compares against it. A failed stamp is a transient store fault,
             // and the page stays on disk. The agent runs the preview again to stamp the marker.
-            const stamped = await deps.gateway.stampRendered(threadId, computeDraftHash(draft));
+            const renderedHash = computeDraftHash(draft);
+            const stamped = await deps.gateway.stampRendered(threadId, renderedHash);
             if (stamped.outcome !== "stamped") {
                 const detail = stamped.outcome === "failed" ? stamped.detail : "the session state row is absent";
                 logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
@@ -483,6 +497,9 @@ export function createPreviewReportTool(deps) {
                 type: "data-report-rendered",
                 data: { id: randomUUID(), renderedAt: new Date().toISOString(), title: document.title },
             });
+            // The event rides the rendered arm alone, the same as the part above. The hash is the hash of
+            // the draft that the page shows, thus a consumer ties the page to the document that made it.
+            observe({ type: "preview", analysisId, threadId, pagePath: written.value, documentHash: renderedHash });
             const access = await mintAccess(deps.makeSessionPages, analysisId, threadId, ctx.session.auth, logger);
             return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}) });
         },

package/dist/tools/report-session/record-version.d.ts

@@ -39,6 +39,7 @@ import type { ReportVersionStore } from "../../state/report-versions.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
 declare const recordVersionInput: z.ZodObject<{}, z.core.$strip>;
 export type RecordVersionInput = z.infer<typeof recordVersionInput>;
@@ -101,6 +102,8 @@ export interface RecordVersionToolDeps {
         analysisId: string;
         auth: AuthContext;
     }) => ReferenceResolver;
+    /** The provenance seam; an unbound session emit emits nothing and the record runs the same. */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

package/dist/tools/report-session/record-version.js

@@ -42,6 +42,7 @@ import { validateReport } from "../../report-model/validate.js";
 import { reportSessionDerivedDir, resolveWorkspacePath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
 const recordVersionInput = z.object({});
 /** A short account of a record refusal, for the detail of a transient failure. */
@@ -122,6 +123,7 @@ async function pruneUnusedDerivations(args) {
  */
 export function createRecordVersionTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("record-report-version");
+    const observe = bindSessionEmit(deps.provenance, logger);
     return defineTool({
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
@@ -203,9 +205,11 @@ export function createRecordVersionTool(deps) {
                 parentSeq: thread.value.parentSeq,
             });
             if (recorded.isOk()) {
-                // The version stands from here. The prune reclaims the bytes of each derivation that the
-                // recorded document ignores, and it decides nothing about the outcome. It runs on each
-                // record, thus an output that an amend unbound goes at the next record.
+                // The version stands from here, thus the event states a version that a reader can open.
+                observe({ type: "record-version", analysisId, threadId, versionId: recorded.value.versionId, replaced: recorded.value.outcome === "replaced" });
+                // The prune reclaims the bytes of each derivation that the recorded document ignores, and it
+                // decides nothing about the outcome. It runs on each record, thus an output that an amend
+                // unbound goes at the next record.
                 await pruneUnusedDerivations({
                     resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
                     analysisId,

package/dist/tools/start-report-session.d.ts

@@ -24,6 +24,7 @@ import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
 import type { ThreadType } from "../memory/thread-store.js";
 import { type Tool } from "./define-tool.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 /**
  * The brief of the ask, plus the one override of the advice.
  *
@@ -101,6 +102,12 @@ export interface StartReportSessionToolDeps {
      * carries no stale value of its own.
      */
     readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    /**
+     * The provenance seam of the composition. The tool hands it to the spawn,
+     * which emits the creation of the session at the moment that the child lands.
+     * The tool emits nothing of its own.
+     */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

package/dist/tools/start-report-session.js

@@ -111,6 +111,7 @@ export function createStartReportSessionTool(deps) {
         chrome: deps.chrome,
         ...(deps.eyes ? { eyes: deps.eyes } : {}),
         ...(deps.anchorSession ? { anchorSession: deps.anchorSession } : {}),
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
         ...(deps.logger ? { logger: deps.logger } : {}),
     };
     const spawn = createReportSessionSpawn(spawnDeps);

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

@@ -69,6 +69,7 @@ import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.j
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { RunCharge } from "../billing/run-charge.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type PlanStep } from "./execute-analysis-scheduler.js";
@@ -154,63 +155,6 @@ export interface ExecuteAnalysisResult {
     readonly failedSteps: readonly string[];
     readonly canceledSteps: readonly string[];
 }
-/**
- * A run-lifecycle provenance observation handed to an optional host observer.
- * Harness-owned plain union — the harness stays tsprov-free and bus-free; the
- * host maps these execution facts onto its own ledger vocabulary.
- *
- * Every `atMs` is epoch milliseconds read via `await DBOS.now()`, a checkpointed
- * step: a body re-executed by DBOS recovery reads the recorded value, so a
- * re-emitted event carries the identical timestamp and merges on the host's
- * ledger without a value conflict. Never source these from a wall clock
- * (`Date.now()`) — that would diverge across replays and defeat the merge.
- *
- * `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
- * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span.
- *
- * `step_completed` fires once at EVERY scheduler-loop settlement — the only site
- * that observes every executed step (registration sees only artifact-producing
- * steps, and a child cannot observe its own parent-driven cancel). Steps that
- * were never dispatched (dependents of a failed sibling) emit nothing by design;
- * the run's terminal status carries that outcome. `status` maps the settlement
- * outcome: `complete` → `"completed"`, `canceled` → `"canceled"`,
- * `failed`/`blocked`/child-error → `"failed"`.
- *
- * `run_completed` fires at BOTH terminal boundaries (success and failure); the
- * `status` field distinguishes them.
- */
-export type RunProvenanceEvent = {
-    type: "run_started";
-    analysisId: string;
-    runId: string;
-    planSummary: string;
-    stepCount: number;
-    atMs: number;
-} | {
-    type: "step_completed";
-    analysisId: string;
-    runId: string;
-    stepId: string;
-    /** Settlement outcome mapped to a terminal step status. */
-    status: "completed" | "failed" | "canceled";
-    /** The child's durable execution duration; absent when the child settled by throwing. */
-    durationMs?: number;
-    atMs: number;
-} | {
-    type: "run_completed";
-    analysisId: string;
-    runId: string;
-    /**
-     * The body's terminal status. Both boundary sites resolve it through `deriveFinalStatus`,
-     * which records a budget pause as `"canceled"` — so `"suspended_insufficient_funds"` (a
-     * `RunStatus` member) is never emitted here and is deliberately absent from this narrower
-     * `ExecuteAnalysisFinalStatus`-minus-`"running"` set.
-     */
-    status: Exclude<ExecuteAnalysisFinalStatus, "running">;
-    atMs: number;
-    /** `atMs − run_started.atMs`: the workflow-observed run span in ms. */
-    durationMs: number;
-};
 /**
  * A step's in-run display state. Wider than the ledger's `StepExecutionStatus`: `queued` is a
  * scheduler-only condition (dependency-satisfied but held for budget capacity) that never reaches a
@@ -291,9 +235,11 @@ export interface ExecuteAnalysisDeps {
      */
     readonly usageRecorder?: UsageRecorder;
     /**
-     * Optional, fire-and-forget provenance observation of the run lifecycle.
-     * Deliberately invoked directly in the workflow body (NOT wrapped in
-     * `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
+     * The provenance seam of the composition. The body reads its run emit member,
+     * and it reads no other member.
+     *
+     * The emit is deliberately invoked directly in the workflow body (NOT wrapped
+     * in `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
      * a cached step would suppress the recovery re-emission, defeating the
      * point. Idempotency is the consumer's job, achieved via the deterministic
      * identifiers the events carry, not via step caching. Every call site is
@@ -303,19 +249,19 @@ export interface ExecuteAnalysisDeps {
      * persisting realization needs its credential, scope, and identity.
      * Implementations may ignore the parameter.
      */
-    readonly emitProvenance?: (event: RunProvenanceEvent, session: RunSession) => void;
+    readonly provenance?: ProvenanceSeam;
     /**
      * Optional, fire-and-forget observation of the run's live shape, for a host driving a UI.
      *
-     * Independent of {@link emitProvenance} in every direction: neither is implemented in terms of
-     * the other, they share no payload, and supplying one does not imply the other. They exist
-     * separately because provenance closes a signed, hash-chained record under a single-writer
-     * lock, while this is a lossy-tolerant display channel — coupling them would put a UI repaint
-     * behind the chain's write discipline and force provenance to carry step names and agent ids it
-     * has no reason to record.
+     * Independent of the run emit of {@link provenance} in every direction: neither is implemented
+     * in terms of the other, they share no payload, and supplying one does not imply the other.
+     * They exist separately because provenance closes a signed, hash-chained record under a
+     * single-writer lock, while this is a lossy-tolerant display channel — coupling them would put
+     * a UI repaint behind the chain's write discipline and force provenance to carry step names and
+     * agent ids it has no reason to record.
      *
-     * Invoked directly in the workflow body (NOT wrapped in `DBOS.runStep`) for the same reason
-     * `emitProvenance` is: body re-execution on recovery must re-fire it, and a cached step would
+     * Invoked directly in the workflow body (NOT wrapped in `DBOS.runStep`) for the same reason the
+     * run emit is: body re-execution on recovery must re-fire it, and a cached step would
      * suppress that. Idempotency comes free for rendering because the payload is a whole-run
      * snapshot; a host taking a DURABLE side effect on one must key it by run id and status itself.
      *

package/dist/workflows/execute-analysis.js

@@ -88,14 +88,15 @@ function emitStreamPart(part) {
  * host's own ledger, not here.
  */
 function emitProvenanceGuarded(deps, event, session) {
-    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
-    if (!deps.emitProvenance)
+    const emit = deps.provenance?.emitRunEvent;
+    if (!emit)
         return;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
     try {
-        deps.emitProvenance(event, session);
+        emit(event, session);
     }
     catch (err) {
-        logger.error("emitProvenance threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
+        logger.error("the run emit of the provenance seam threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.31.0",
+    "version": "0.32.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -56,6 +56,7 @@
         "@dbos-inc/dbos-sdk": "^4.23.6",
         "@fontsource-variable/space-grotesk": "5.1.1",
         "@fontsource/ibm-plex-mono": "5.1.1",
+        "@inflexa-ai/tsprov": "0.6.0",
         "@kubernetes/client-node": "^1.4.0",
         "@opentelemetry/api": "^1.9.1",
         "@opentelemetry/core": "^2.9.0",