@inflexa-ai/harness 0.31.0 → 0.32.0

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;
+        }
+    };
+}

package/dist/report-model/authoring-grammar.d.ts

@@ -398,15 +398,15 @@ declare const AUTHORING_ATOM_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/report-render/assets.d.ts

@@ -66,6 +66,16 @@ export declare const ECHARTS_ASSET: PageAsset;
  * entries alone, thus this specifier resolves as a path under the installed package directory.
  */
 export declare const AG_GRID_ASSET: PageAsset;
+/**
+ * The provenance library. The page-side popover reads the `tsprov` global that this file declares.
+ *
+ * The entry names the browser bundle of the package. The package `exports` map publishes the module entries
+ * alone, thus this specifier resolves as a path under the installed package directory.
+ *
+ * The harness imports no API of the library. It stages these bytes and nothing more, thus the walk of a
+ * chain belongs to the page and the renderer stays free of every provenance API.
+ */
+export declare const TSPROV_ASSET: PageAsset;
 /** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
 export declare const SANS_FONT_ASSET: PageAsset;
 /**

package/dist/report-render/assets.js

@@ -77,6 +77,19 @@ export const AG_GRID_ASSET = {
     file: `${DEPS_DIR}/ag-grid-community.min.js`,
     specifier: "ag-grid-community/dist/ag-grid-community.min.js",
 };
+/**
+ * The provenance library. The page-side popover reads the `tsprov` global that this file declares.
+ *
+ * The entry names the browser bundle of the package. The package `exports` map publishes the module entries
+ * alone, thus this specifier resolves as a path under the installed package directory.
+ *
+ * The harness imports no API of the library. It stages these bytes and nothing more, thus the walk of a
+ * chain belongs to the page and the renderer stays free of every provenance API.
+ */
+export const TSPROV_ASSET = {
+    file: `${DEPS_DIR}/tsprov.min.js`,
+    specifier: "@inflexa-ai/tsprov/dist/browser/tsprov.min.js",
+};
 /** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
 export const SANS_FONT_ASSET = {
     file: `${DEPS_DIR}/space-grotesk-latin-wght-normal.woff2`,
@@ -112,6 +125,7 @@ export const MONO_FONT_700_ASSET = {
 export const PAGE_ASSETS = [
     ECHARTS_ASSET,
     AG_GRID_ASSET,
+    TSPROV_ASSET,
     SANS_FONT_ASSET,
     MONO_FONT_400_ASSET,
     MONO_FONT_500_ASSET,

package/dist/report-render/design.js

@@ -116,6 +116,7 @@ export const DESIGN_CSS = `${FONT_FACES}
 
   /* Semantic tags */
   --color-high-bg:     #f0fdf4;
+  --color-high-border: #bbf7d0;
   --color-high-text:   #15803d;
   --color-medium-bg:   #fffbeb;
   --color-medium-text: #b45309;
@@ -378,6 +379,251 @@ img {
   text-decoration: underline;
 }
 
+/* ── Lineage control and popover ──────────────────────── */
+/* The control sits beside the bracket marker. It reads as a quiet branch glyph and never as a second
+   marker, thus it takes the muted color until a hover. The button carries no browser chrome, because a
+   chrome box inside a line of prose would break the line. */
+.report-lineage {
+  display: inline-flex;
+  align-items: center;
+  margin-left: 2px;
+  padding: 0;
+  line-height: 0;
+  vertical-align: -2px;
+  color: var(--color-text-muted);
+  background: none;
+  border: 0;
+  cursor: pointer;
+}
+.report-lineage:hover {
+  color: var(--color-primary-500);
+}
+/* The drawing strokes in the current color, thus the two color rules above reach it and the sheet holds one
+   color for the two states. */
+.report-lineage-glyph {
+  display: block;
+}
+/* The panel floats over the page. A data card clips its own overflow, thus the page script places the panel
+   against the document and no card cuts it. The panel takes the width of its longest row, thus a name reads
+   whole and a cut is the exception. The cap bounds it against the design and against the viewport, and the
+   viewport half holds the same margin at each side as the clamp of the script. Thus a narrow window shows
+   the panel between the two margins. */
+.report-lineage-popover {
+  position: absolute;
+  z-index: 50;
+  width: max-content;
+  max-width: min(48rem, calc(100vw - 24px));
+  background: var(--color-card);
+  border: 1px solid var(--color-border);
+  box-shadow: 0 12px 32px -12px rgba(15, 23, 42, 0.18);
+  animation: report-lineage-open 0.12s ease-out;
+}
+.report-lineage-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--color-border-subtle);
+}
+.report-lineage-title {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--color-text-muted);
+}
+/* The header names the marker that opened the panel and the depth of the chain under it. Thus the reader
+   reads the size of the chain before the body scrolls. */
+.report-lineage-count {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--color-text-secondary);
+}
+.report-lineage-close {
+  margin-left: auto;
+  padding: 0;
+  font-family: var(--font-mono);
+  font-size: 14px;
+  line-height: 1;
+  color: var(--color-text-muted);
+  background: none;
+  border: 0;
+  cursor: pointer;
+}
+.report-lineage-close:hover {
+  color: var(--color-heading);
+}
+/* A deep pipeline builds more rows than a window holds. The cap reads against the viewport, thus the body
+   scrolls inside the panel and the panel never grows the page. */
+.report-lineage-body {
+  max-height: 60vh;
+  overflow-y: auto;
+  padding: 16px 16px 8px;
+}
+/* One base row carries each file of the rail. A modifier marks the pinned artifact and a raw input, and a
+   row with no modifier is an artifact that the rail continues past. */
+.report-lineage-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  background: var(--color-bg-alt);
+  border: 1px solid var(--color-border-subtle);
+}
+.report-lineage-row + .report-lineage-row {
+  margin-top: 4px;
+}
+.report-lineage-row-pin {
+  padding: 8px 10px;
+  background: var(--color-primary-50);
+  border-color: var(--color-primary-100);
+}
+.report-lineage-row-producer {
+  padding: 8px 10px;
+  background: var(--color-card);
+  border-color: var(--color-border);
+}
+/* The terminal tint marks a file that no command of this analysis made. It is where a branch ends, thus the
+   tint and the tag of the row state the same fact. */
+.report-lineage-row-raw {
+  background: var(--color-high-bg);
+  border-color: var(--color-high-border);
+}
+.report-lineage-tag {
+  flex-shrink: 0;
+  padding: 2px 6px;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.06em;
+  color: var(--color-text-secondary);
+  background: var(--color-border);
+}
+.report-lineage-tag-pin {
+  font-weight: 600;
+  color: var(--color-card);
+  background: var(--color-primary-500);
+}
+.report-lineage-tag-raw {
+  font-weight: 600;
+  color: var(--color-card);
+  background: var(--color-high-text);
+}
+/* The path takes the whole free width of the row, and it never wraps the row into two lines. The panel grows
+   to the longest path, thus a window that gives the panel its cap needs no cut. In a narrow window the page
+   script cuts a long path at its start, and it cuts an over-long file name in the middle of that name. Thus
+   the ellipsis of this rule is the last guard, for a row too narrow to hold even a cut name. */
+.report-lineage-path {
+  flex: 1;
+  overflow: hidden;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--color-text);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.report-lineage-row-pin .report-lineage-path,
+.report-lineage-row-raw .report-lineage-path {
+  color: var(--color-text-strong);
+}
+/* The directory prefix dims, thus the file name reads first inside a long path. */
+.report-lineage-dir {
+  color: var(--color-text-muted);
+}
+.report-lineage-hash {
+  flex-shrink: 0;
+  margin-left: auto;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--color-text-muted);
+}
+.report-lineage-prompt {
+  flex-shrink: 0;
+  color: var(--color-text-secondary);
+}
+.report-lineage-script {
+  overflow: hidden;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--color-text-strong);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.report-lineage-meta {
+  flex-shrink: 0;
+  margin-left: auto;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--color-text-muted);
+}
+/* The connector sits between two levels of the rail. The page script gives it the indent of its level, thus
+   one rule serves each depth. */
+.report-lineage-link {
+  display: flex;
+  gap: 10px;
+  padding: 2px 0;
+}
+.report-lineage-rail {
+  width: 1px;
+  background: var(--color-border);
+}
+.report-lineage-rail-pin {
+  background: var(--color-primary-100);
+}
+.report-lineage-link-label {
+  padding: 6px 0;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  color: var(--color-text-muted);
+}
+/* The dashed edge marks a row that names files and shows none of them. Thus a count row never reads as one
+   more hop of the chain. */
+.report-lineage-more {
+  margin-top: 4px;
+  padding: 5px 10px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--color-text-muted);
+  /* One line always: a wrapped count row breaks the rail rhythm in a narrow
+     window, and a cut count loses nothing that the rows above do not show. */
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  border: 1px dashed var(--color-border);
+}
+.report-lineage-footer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 16px;
+  background: var(--color-bg-alt);
+  border-top: 1px solid var(--color-border-subtle);
+}
+.report-lineage-check {
+  flex-shrink: 0;
+  color: var(--color-high-text);
+}
+/* The footer states that the chain is complete, or it states the absence or the truncation that stopped it.
+   A reader must read the rail against what it does not hold, thus the note sits under the rail and never
+   beside one row of it. */
+.report-lineage-note {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  line-height: 1.5;
+  color: var(--color-text-secondary);
+}
+@keyframes report-lineage-open {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
 /* ── Corner-accent card ───────────────────────────────── */
 /* The data cards keep square corners. The L-shaped accents grow on hover. */
 .corner-accents {
@@ -789,6 +1035,10 @@ a.report-citation-source:hover {
     opacity: 1;
     transform: none;
   }
+  /* The panel stands at once, thus the open costs no motion. */
+  .report-lineage-popover {
+    animation: none;
+  }
 }
 
 /* ── Print ────────────────────────────────────────────── */
@@ -796,6 +1046,12 @@ a.report-citation-source:hover {
   .report-nav {
     display: none;
   }
+  /* The control opens a panel, and paper opens nothing. The appendix carries the same references, thus the
+     printed page loses no evidence. */
+  .report-lineage,
+  .report-lineage-popover {
+    display: none;
+  }
   /* The printer gives the page margin. Thus the screen padding of the container drops out. */
   body:has(#report-sidebar) {
     padding-left: 0;