@inflexa-ai/harness 0.31.1 → 0.32.0

package/dist/agents/conversation-agent.d.ts

@@ -35,6 +35,7 @@ import { type BioToolKeys } from "../tools/bio/keys.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
@@ -111,6 +112,12 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * at a page reads that same answer.
      */
     readonly eyes?: AcquireEyes;
+    /**
+     * The provenance seam. `start_report_session` hands it to its spawn, which
+     * emits the creation of the session at the moment that the child lands. No
+     * other tool of this roster reads it.
+     */
+    readonly provenance?: ProvenanceSeam;
     /**
      * Host resource policy — per-step ceilings + machine budget. `generate_plan`
      * states the ceilings to the planner and validates against them;

package/dist/agents/conversation-agent.js

@@ -122,6 +122,7 @@ export function createConversationAgent(deps) {
             chrome,
             anchorSession: deps.anchorReportSession,
             ...(deps.eyes ? { eyes: deps.eyes } : {}),
+            ...(deps.provenance ? { provenance: deps.provenance } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         // Display.

package/dist/agents/report-session-agent.d.ts

@@ -38,6 +38,7 @@ import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import { type MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
@@ -114,6 +115,14 @@ export interface ReportSessionAgentDeps {
      * tool navigates through a `file://` URL of the page path.
      */
     readonly resolvePageUrl?: ResolvePageUrl;
+    /**
+     * The provenance seam -- the acts of the session as typed events, and the frozen document of the
+     * analysis as opaque bytes. The tools that change the draft, derive a table, preview the page, and
+     * record a version each emit through the session member, thus one bound member carries the whole
+     * session. The preview asks the read member before each render, and the page then carries the
+     * document. An unbound member emits nothing, or gives absence, and every tool acts the same.
+     */
+    readonly provenance?: ProvenanceSeam;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

package/dist/agents/report-session-agent.js

@@ -39,8 +39,11 @@ const REPORT_SESSION_MAX_ITERATIONS = 200;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl } = deps;
-    const authoring = createReportAuthoringTools(gateway);
+    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl, provenance } = deps;
+    // The seam rides into each tool that lands an act of the session, thus the composition binds it one
+    // time and no tool reads a second source.
+    const observation = provenance ? { provenance } : {};
+    const authoring = createReportAuthoringTools(gateway, { ...observation, ...(logger ? { logger } : {}) });
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
         createReadFileTool(workspaceFs),
@@ -75,6 +78,7 @@ export function createReportSessionAgent(deps) {
             derivations,
             ...(runDerivation ? { runDerivation } : {}),
             ...(runAuthorizer ? { runAuthorizer } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The render-and-preview tool. It resolves the page root per call.
@@ -84,6 +88,9 @@ export function createReportSessionAgent(deps) {
             ...(makeResolver ? { makeResolver } : {}),
             ...(resolvePageAsset ? { resolvePageAsset } : {}),
             ...(makeSessionPages ? { makeSessionPages } : {}),
+            // The preview is the one site that carries the document into the page, thus the read member
+            // reaches this tool alone.
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The eyes tool. It opens the rendered page in headless Chrome.
@@ -103,6 +110,7 @@ export function createReportSessionAgent(deps) {
             threads,
             resolveWorkspaceRoot,
             ...(makeResolver ? { makeResolver } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
     ];

package/dist/app/chat-turn.d.ts

@@ -16,10 +16,21 @@ import type { Pool } from "pg";
 import { type ThreadType } from "../memory/thread-store.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 export interface PrepareChatTurnDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly pool: Pool;
+    /**
+     * The provenance seam. The turn reads its session emit member, and no other
+     * member. The turn holds the one site that writes the conversation thread of
+     * an analysis, thus it is the one site that can tell the embedder the true
+     * moment of that creation.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each site
+     * of a report session.
+     */
+    readonly provenance?: ProvenanceSeam;
 }
 export interface PrepareChatTurnParams {
     readonly analysisId: string;

package/dist/app/chat-turn.js

@@ -21,6 +21,7 @@ import { loadAnalysisStatus, queryNonTerminalRunsByAnalysis } from "../state/ind
 import { assembleMessages } from "./message-assembly.js";
 import { renderRunActivity, renderRunActivityUnavailable, RUN_ACTIVITY_DETAIL_LIMIT } from "./run-activity.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
@@ -29,6 +30,10 @@ import { createNoopLogger } from "../lib/console-logger.js";
 export async function prepareChatTurn(deps, params) {
     const { pool } = deps;
     const { analysisId, threadId, userInput } = params;
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    // An unbound member gives a call that does nothing, thus the emit below needs
+    // no test of its own.
+    const observe = bindSessionEmit(deps.provenance, logger);
     // Ownership check before any read/write of the thread — a `threadId`
     // owned by a different analysis is indistinguishable from a missing one.
     const store = createThreadStore(pool);
@@ -54,13 +59,24 @@ export async function prepareChatTurn(deps, params) {
                 title: deriveThreadTitle(userInput),
             }));
             threadType = created.threadType;
+            // The row that comes back is not proof that this call wrote it. The read
+            // above hides an archived thread, and the idempotent insert then reads
+            // that same row back. Thus a turn on an archived thread reaches here with
+            // a row that a different site created, and an emit would record a start
+            // that never happened.
+            //
+            // This site writes a live conversation thread and nothing else. An
+            // archived row, or a row of another kind, is therefore one that already
+            // existed. A root session has no parent, thus the event carries none.
+            if (created.deletedAt === null && created.threadType === "conversation") {
+                observe({ type: "create-session", analysisId, threadId, sessionKind: created.threadType });
+            }
         }
         else if (!existing.title || existing.title.length === 0) {
             unwrapOrThrow(await store.updateTitle(threadId, deriveThreadTitle(userInput)));
         }
     }
     catch (err) {
-        const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
         logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
     const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);

package/dist/app/spawn-report-session.d.ts

@@ -66,6 +66,7 @@ import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
 import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 import type { EnsureSessionStateResult } from "./report-session-runtime.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -192,6 +193,17 @@ export interface ReportSessionSpawnDeps {
      * is idempotent.
      */
     readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    /**
+     * The provenance seam. The spawn reads its session emit member, and no other
+     * member. The spawn is the birth of the session, thus it is the one site that
+     * can tell the embedder the true moment of the ask. A consumer that waits for
+     * the first authoring act reads a later moment, and it reads nothing at all
+     * for a session that stays empty.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each
+     * authoring site.
+     */
+    readonly provenance?: ProvenanceSeam;
     /** Operational logging seam. An omitted logger falls back to the no-op. */
     readonly logger?: Logger;
 }

package/dist/app/spawn-report-session.js

@@ -65,6 +65,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { conversationRecordTurn, createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 const _assertDomainError = true;
 /**
  * Whether the composition gives a route to a look at the rendered page. The
@@ -165,6 +166,9 @@ export function createReportSessionSpawn(deps) {
     // The routes are fixed at construction, thus the gate reads one boolean and
     // never a live probe of the sidecar.
     const eyesAvailable = compositionHasEyes(deps);
+    // An unbound member gives a call that does nothing, thus the spawn emits at
+    // one site with no test of its own.
+    const observe = bindSessionEmit(deps.provenance, log);
     /**
      * Write the one seed message of the child and give the child back. The
      * message rides as a record, not as user input: nobody typed it in the child
@@ -250,7 +254,7 @@ export function createReportSessionSpawn(deps) {
         if (!eyesAvailable) {
             return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
         }
-        return store.getThread(parentThreadId).andThen((parent) => {
+        const spawned = store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.
             if (parent === null) {
@@ -288,6 +292,22 @@ export function createReportSessionSpawn(deps) {
                     .andThen((child) => ResultAsync.fromSafePromise(pinSessionSnapshot(child))));
             });
         });
+        // The emit rides the ok channel alone, thus a refusal and a fault tell the
+        // embedder nothing. The child row is on disk at this point, and no
+        // authoring act of the session ran yet.
+        //
+        // The kind comes from the row and not from the input, because the insert
+        // is idempotent and the store tells a caller to read the type back.
+        return spawned.map((child) => {
+            observe({
+                type: "create-session",
+                analysisId: child.analysisId,
+                threadId: child.threadId,
+                sessionKind: child.threadType,
+                parentThreadId,
+            });
+            return child;
+        });
     }
     function listReportSessions(analysisId, paging = {}) {
         return store.listThreads({ analysisId, type: "report", ...paging });

package/dist/contracts/report-blocks.d.ts

@@ -200,15 +200,15 @@ export declare const ChartAxesSchema: z.ZodObject<{
     x: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
     y: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -297,15 +297,15 @@ export declare const ChartCompositionSchema: z.ZodObject<{
         x: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
         y: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -724,15 +724,15 @@ export declare const ChartBlockSchema: z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -1168,15 +1168,15 @@ export declare const ATOM_BLOCK_SCHEMAS: readonly [z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

package/dist/contracts/schemas/chat-parts.d.ts

@@ -240,9 +240,9 @@ export declare const StepOutputFileSchema: z.ZodObject<{
     fileType: z.ZodEnum<{
         output: "output";
         summary: "summary";
-        script: "script";
-        figure: "figure";
         log: "log";
+        figure: "figure";
+        script: "script";
         notebook: "notebook";
     }>;
     description: z.ZodString;
@@ -259,9 +259,9 @@ export declare const StepOutputPartSchema: z.ZodObject<{
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;
@@ -597,9 +597,9 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;

package/dist/index.d.ts

@@ -36,6 +36,9 @@ export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
 export type { MakeSessionPagePublisher, SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
+export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";
+export type { DerivationSource } from "./state/report-session-state.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
@@ -140,7 +143,7 @@ export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.j
 export { ExecEventMessageSchema } from "./sandbox/types.js";
 export type { ExecEventMessage, DoneMarker } from "./sandbox/types.js";
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
-export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
+export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
 export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";

package/dist/index.js

@@ -47,6 +47,14 @@ export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.j
 // state. The URL seam of the eyes rides beside the publisher factory: a host whose
 // browser cannot reach the workspace tree binds a served URL for the look.
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
+// Seam: the one provenance surface. The embedder records the facts of a run and the acts of a
+// session in the document of the analysis that it owns, and it gives the bytes of that document
+// back for the report page. Thus the seam and its vocabulary belong on the front door: an embedder
+// cannot type its realization without them. The two binders ride beside the types, because an
+// embedder that calls `prepareChatTurn` or one tool factory directly binds the same total forms
+// that the assembly binds. `DerivationSource` rides beside the event union, because the derivation
+// event carries the chain of the derived table.
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 // Seam: workflow-ledger reclamation — cancels and deletes an analysis's rows in

package/dist/provenance/seam.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The provenance seam -- the one surface through which the harness tells an embedder what happened.
+ *
+ * Three duties answer one host concern. A durable run states the facts of its own lifecycle. A session
+ * states the acts that make a report. The report page needs the signed document of the analysis back, as
+ * bytes. The embedder holds that document, thus the harness declares the vocabulary and the seam alone,
+ * and it keeps no ledger of its own.
+ *
+ * One surface carries the three, and each member is optional alone. Thus a composition binds the members
+ * that it records, and the harness reads an absent member as absence and never as an error. The run emit
+ * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
+ * its credential. A session act carries no session, thus the session emit takes the event alone.
+ *
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
+ * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
+ * happened.
+ */
+import type { RunSession } from "../auth/types.js";
+import type { Logger } from "../lib/logger.js";
+import type { ProvenanceExport } from "../report-render/provenance-data.js";
+import type { AuthoringBlock } from "../report-model/authoring-grammar.js";
+import type { ExecuteAnalysisFinalStatus } from "../workflows/execute-analysis.js";
+export type { ProvenanceExport } from "../report-render/provenance-data.js";
+/**
+ * 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;
+};
+/**
+ * One act on one block of a draft.
+ *
+ * The kind rides beside the id, because an id alone tells a reader nothing about what the act touched.
+ * The kind is the one that the document holds after the act: a change is permitted to change the kind,
+ * and a remove states the kind that the draft carried before it.
+ */
+type BlockAct = {
+    analysisId: string;
+    threadId: string;
+    blockId: string;
+    blockKind: AuthoringBlock["kind"];
+};
+/**
+ * One observation of a session.
+ *
+ * The union names one event for each act: the start of a session, the four block operations, the title,
+ * the derivation, the preview, and the record. Each event carries the analysis and the thread, thus a
+ * consumer places it with no lookup. The title sits on the document, thus the title event names no block.
+ *
+ * Each member carries what its own site holds at the moment that the act lands, and nothing more. The
+ * derivation carries the chain of the table, because the site pins it and a consumer cannot rebuild it
+ * from the path. The preview carries the page and the hash of the draft that it shows, thus a consumer
+ * ties a page to the document that made it.
+ *
+ * The `create-session` event names the kind of the new session, and it names the parent thread of a child
+ * session. An analysis holds sessions of more than one kind, and the thread id alone says neither. Thus
+ * the document of the analysis tells the whole tree of the sessions, and a reader walks it with no second
+ * read of the seam. A root session carries no parent, thus `parentThreadId` is absent on it.
+ */
+export type SessionProvenanceEvent = {
+    type: "create-session";
+    analysisId: string;
+    threadId: string;
+    sessionKind: "conversation" | "report";
+    parentThreadId?: string;
+} | ({
+    type: "add-block";
+} & BlockAct) | ({
+    type: "change-block";
+} & BlockAct) | ({
+    type: "remove-block";
+} & BlockAct) | ({
+    type: "move-block";
+} & BlockAct) | {
+    type: "set-title";
+    analysisId: string;
+    threadId: string;
+    title: string;
+} | {
+    type: "run-derivation";
+    analysisId: string;
+    threadId: string;
+    outputPath: string;
+    outputHash: string;
+    scriptHash: string;
+    sources: ReadonlyArray<{
+        path: string;
+        hash: string;
+    }>;
+} | {
+    type: "preview";
+    analysisId: string;
+    threadId: string;
+    pagePath: string;
+    documentHash: string;
+} | {
+    type: "record-version";
+    analysisId: string;
+    threadId: string;
+    versionId: string;
+    replaced: boolean;
+};
+/**
+ * The provenance seam of the harness. An embedder realizes the members that it records, and the harness
+ * never branches on which realization is bound.
+ */
+export type ProvenanceSeam = {
+    /**
+     * The run engine emits the facts of one run here.
+     *
+     * Synchronous by signature (`void`, never a promise): a host that needs input and output dispatches
+     * the work rather than making a workflow body wait behind it. The `RunSession` rides from the durable
+     * workflow input, because a persisting realization needs the credential, the scope, and the identity
+     * of the run. A realization can ignore the parameter.
+     */
+    readonly emitRunEvent?: (event: RunProvenanceEvent, session: RunSession) => void;
+    /**
+     * A session emits one act here. A session act runs under no authorized run, thus this member takes
+     * the event alone. It is synchronous by signature for the same reason as the run emit.
+     */
+    readonly emitSessionEvent?: (event: SessionProvenanceEvent) => void;
+    /**
+     * The page staging reads the signed document of one analysis here.
+     *
+     * The member can be async, because a source can read a file or ask a service. It gives the bytes and
+     * the attestation, or `undefined`. Absence is a normal result, not a fault: the page then carries no
+     * provenance asset, and each other part of the render is what it was.
+     */
+    readonly readExport?: (analysisId: string) => ProvenanceExport | undefined | Promise<ProvenanceExport | undefined>;
+};
+/**
+ * Bind the optional session emit and the logger of one site into a total emit.
+ *
+ * An absent member gives a call that does nothing. Thus a site emits where its act lands with no test of
+ * its own, and absence stays a normal condition.
+ *
+ * The harness is host-agnostic, and it cannot assume that a host callback is total. Thus a throw of the
+ * realization reaches the log and stops there: an observation is a record of an act, and a defect in it
+ * must never undo the act that already landed.
+ */
+export declare function bindSessionEmit(seam: ProvenanceSeam | undefined, logger: Logger): (event: SessionProvenanceEvent) => void;
+/**
+ * Bind the optional document read and the logger of one site into a total read.
+ *
+ * An absent member gives a call that answers absence. Thus a site asks at its one place with no test of
+ * its own, and an unbound composition needs no branch.
+ *
+ * A throw of the realization reaches the log and becomes absence, for the same reason that a throw of an
+ * emit stops at the log: the provenance of the page is an addition to the report, and a defect in it must
+ * never cost the render.
+ */
+export declare function bindReadExport(seam: ProvenanceSeam | undefined, logger: Logger): (analysisId: string) => Promise<ProvenanceExport | undefined>;

package/dist/provenance/seam.js

@@ -0,0 +1,71 @@
+/**
+ * The provenance seam -- the one surface through which the harness tells an embedder what happened.
+ *
+ * Three duties answer one host concern. A durable run states the facts of its own lifecycle. A session
+ * states the acts that make a report. The report page needs the signed document of the analysis back, as
+ * bytes. The embedder holds that document, thus the harness declares the vocabulary and the seam alone,
+ * and it keeps no ledger of its own.
+ *
+ * One surface carries the three, and each member is optional alone. Thus a composition binds the members
+ * that it records, and the harness reads an absent member as absence and never as an error. The run emit
+ * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
+ * its credential. A session act carries no session, thus the session emit takes the event alone.
+ *
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
+ * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
+ * happened.
+ */
+/**
+ * Bind the optional session emit and the logger of one site into a total emit.
+ *
+ * An absent member gives a call that does nothing. Thus a site emits where its act lands with no test of
+ * its own, and absence stays a normal condition.
+ *
+ * The harness is host-agnostic, and it cannot assume that a host callback is total. Thus a throw of the
+ * realization reaches the log and stops there: an observation is a record of an act, and a defect in it
+ * must never undo the act that already landed.
+ */
+export function bindSessionEmit(seam, logger) {
+    const emit = seam?.emitSessionEvent;
+    if (emit === undefined) {
+        return () => undefined;
+    }
+    return (event) => {
+        try {
+            emit(event);
+        }
+        catch (cause) {
+            logger.error("the session emit of the provenance seam threw", {
+                analysisId: event.analysisId,
+                threadId: event.threadId,
+                event: event.type,
+                ...logger.errorFields(cause),
+            });
+        }
+    };
+}
+/**
+ * Bind the optional document read and the logger of one site into a total read.
+ *
+ * An absent member gives a call that answers absence. Thus a site asks at its one place with no test of
+ * its own, and an unbound composition needs no branch.
+ *
+ * A throw of the realization reaches the log and becomes absence, for the same reason that a throw of an
+ * emit stops at the log: the provenance of the page is an addition to the report, and a defect in it must
+ * never cost the render.
+ */
+export function bindReadExport(seam, logger) {
+    const read = seam?.readExport;
+    if (read === undefined) {
+        return () => Promise.resolve(undefined);
+    }
+    return async (analysisId) => {
+        try {
+            return await read(analysisId);
+        }
+        catch (cause) {
+            logger.error("the document read of the provenance seam threw", { analysisId, ...logger.errorFields(cause) });
+            return undefined;
+        }
+    };
+}