deepline 0.2.53 → 0.2.55

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -1,4 +1,10 @@
 // Core types for PlayContext.
+import type {
+  PlayCellReadRef,
+  PlayCellDecision,
+  PlayDatasetBornFrom,
+  PlayRowMeta,
+} from './cell-provenance';
 import type { PlayBundleArtifact } from '../plays/artifact-types';
 import type { PlayRunContractSnapshot } from '../plays/contracts';
 import type { PlayStructuredDefinition } from '../plays/definition';
@@ -29,6 +35,7 @@ import type {
   PlayExecutionGovernor,
 } from './governor/governor';
 import type { BudgetStateBackend } from './governor/budget-state-backend';
+import type { DocflowObservationUpsert } from './docflow-observation';
 import type { RuntimeMapMemoryLimits } from './map-memory-limits';
 import type { AnyBatchOperationStrategy } from './batching-types';
 import type { ToolResultMetadataInput } from './tool-result';
@@ -37,6 +44,7 @@ import type { MapRowOutcome } from './durability-store';
 import type { WorkReceiptFailureKind } from './work-receipts';
 import type { RunExecutionScope } from './run-execution-scope';
 import type { PlayCallExecution } from './play-call-execution';
+import type { PlayDocflowNodeIoPreviewMap } from './docflow-node-io';
 import type { PlayActivityEvent } from './activity-observation';
 import type {
   ToolExecutionErrorSchemaVersion,
@@ -61,6 +69,8 @@ export interface ToolCallRequest {
   requiresExecutionFence?: boolean;
   rowId: number;
   fieldName?: string;
+  /** The author-supplied `ctx.tools.execute(<id>, ...)` key (ADR 0018). */
+  contextKey?: string;
   toolId: string;
   input: Record<string, unknown>;
   timeoutMs?: number;
@@ -276,6 +286,17 @@ export interface RuntimeDatasetOptions<TItem = Record<string, unknown>> {
    * ordinary CSV enrichment reruns.
    */
   mode?: 'upsert' | 'net_new';
+  /**
+   * Columns this dataset computes that the authored `@mermaid` diagram
+   * deliberately does not draw.
+   *
+   * A Play that authors a diagram must account for every column it computes:
+   * draw the column inside the dataset's `subgraph` loop region, or name it
+   * here. `plays check` fails otherwise, and it echoes these names back so an
+   * opt-out is always visible. Purely a documentation contract — it changes no
+   * execution behavior.
+   */
+  undrawnColumns?: readonly string[];
 }
 
 export type RuntimeDatasetDefinitionOptions<TItem = Record<string, unknown>> =
@@ -283,7 +304,7 @@ export type RuntimeDatasetDefinitionOptions<TItem = Record<string, unknown>> =
 
 export type RuntimeDatasetRunOptions<TItem = Record<string, unknown>> = Pick<
   RuntimeDatasetOptions<TItem>,
-  'description' | 'key' | 'onRowError' | 'mode'
+  'description' | 'key' | 'onRowError' | 'mode' | 'undrawnColumns'
 >;
 
 export type ToolCallOptions = PlayToolCallOptions;
@@ -360,6 +381,64 @@ export interface MapExecutionScope {
 
 export type PlayExecutionEvent =
   | PlayActivityEvent
+  | {
+      type: 'docflow.node.hit';
+      nodeId: string;
+      at: number;
+    }
+  | {
+      type: 'docflow.node.started';
+      nodeId: string;
+      attempt: number;
+      invocationId: string;
+      inputs: PlayDocflowNodeIoPreviewMap;
+      inputsTruncated?: boolean;
+      at: number;
+    }
+  | {
+      type: 'docflow.node.completed';
+      nodeId: string;
+      attempt: number;
+      invocationId: string;
+      inputs: PlayDocflowNodeIoPreviewMap;
+      inputsTruncated?: boolean;
+      outputs: PlayDocflowNodeIoPreviewMap;
+      outputsTruncated?: boolean;
+      at: number;
+    }
+  | {
+      type: 'docflow.node.failed';
+      nodeId: string;
+      attempt: number;
+      invocationId: string;
+      inputs: PlayDocflowNodeIoPreviewMap;
+      inputsTruncated?: boolean;
+      error: string;
+      at: number;
+    }
+  /**
+   * Explicit tool-node lifecycle (ADR 0018). Emitted only for tool calls that
+   * are NOT row-scoped, i.e. the same call sites that used to be inferred by
+   * matching `Calling tool: <id>` against runner stdout. Row-scoped calls stay
+   * out of the ledger on purpose (ADR 0001 forbids row-heavy Run Events); their
+   * attribution is the Runtime Sheet `_cell_meta.producers` trace plus the
+   * node-scoped usage events.
+   */
+  | {
+      type: 'tool.call.started';
+      toolId: string;
+      callKey?: string | null;
+      at: number;
+    }
+  | {
+      type: 'tool.call.settled';
+      toolId: string;
+      callKey?: string | null;
+      outcome: 'completed' | 'no_result' | 'failed' | 'cached';
+      durationMs?: number | null;
+      error?: string | null;
+      at: number;
+    }
   | {
       type: 'dataset.lifecycle';
       datasetId: string;
@@ -370,6 +449,13 @@ export type PlayExecutionEvent =
       succeededRows?: number;
       failedRows?: number;
       complete?: boolean;
+      /**
+       * Dataset-grain row birth (ADR 0019). Rows entered this dataset from
+       * play-body code, so the runtime witnessed how many rows arrived at which
+       * step but no per-row source mapping. Stated once per dataset here rather
+       * than repeated — or invented — per row.
+       */
+      bornFrom?: PlayDatasetBornFrom;
       at: number;
     }
   | {
@@ -513,6 +599,12 @@ export interface ContextOptions {
   vercelProtectionBypassToken?: string | null;
   /** Optional per-run integration execution mode for provider calls. */
   integrationMode?: 'live' | 'eval_stub' | 'fixture';
+  /**
+   * Docflow rollout answer for this run, decided at admission (see
+   * `RuntimeAuthorityDescriptor.docflowEnabled`). Absent means OFF, so a run
+   * whose launch predates the field captures exactly what it captured before.
+   */
+  docflowEnabled?: boolean;
   /** Internal fixture-only simulation of provider response residence. */
   fixtureBehavior?: FixtureBehavior | null;
   /** Preview/dev test seam that applies provider pacing to fixture responses. */
@@ -558,6 +650,18 @@ export interface ContextOptions {
   onRowUpdate?: (update: PlayRowUpdate) => void | Promise<void>;
   /** Structured execution events emitted from explicit dataset scopes. */
   onExecutionEvent?: (event: PlayExecutionEvent) => void | Promise<void>;
+  /**
+   * Durable docflow observation sink (ADR 0016 rule 2). Present ONLY for
+   * instrumented (diagrammed) plays: the compiler injects the observation
+   * wrapper only when an `@mermaid` block exists, and the runtime wires this
+   * sink to the receipt gateway's `observe` action. The wrapper posts to it
+   * fire-and-forget alongside the live event emission — it must NEVER fail or
+   * slow the play body. Absent means observations are not persisted (the live
+   * `onExecutionEvent` stream is unchanged either way).
+   */
+  onDocflowObservation?: (
+    observation: DocflowObservationUpsert,
+  ) => void | Promise<void>;
   /**
    * Called when ctx.dataset() starts — inserts items into the sheet and returns
    * the pending/completed split. If not provided, all items are processed.
@@ -1036,6 +1140,45 @@ export type PlayStepRowResult = PlayStepRowResultFields &
     | { status: 'failed' | 'missed' | 'skipped'; success: false }
   );
 
+/** The producer credited with a cell's kept value. */
+export interface PlaySheetCellProducer {
+  kind: 'play' | 'tool' | 'code';
+  id?: string | null;
+  displayName?: string | null;
+  playId?: string | null;
+  toolId?: string | null;
+  runId?: string | null;
+}
+
+/**
+ * One attempted producer for a runtime sheet cell (ADR 0018).
+ *
+ * `durationMs` is the wall time of the logical invocation as observed by the
+ * runtime: it includes batching/queue wait, so summing it across a node is an
+ * upper bound on provider time, not a wall-clock span for the node.
+ */
+export interface PlayCellProducerAttempt {
+  kind: 'play' | 'tool' | 'code';
+  id?: string | null;
+  toolId?: string | null;
+  displayName?: string | null;
+  /** Attempt start, epoch ms. */
+  at: number;
+  outcome: 'running' | 'completed' | 'no_result' | 'failed' | 'cached';
+  durationMs?: number | null;
+}
+
+/** Cell-level provenance shapes (ADR 0019). Defined in `cell-provenance`. */
+export type {
+  PlayCellReadRef,
+  PlayCellDecision,
+  PlayRowBornFrom,
+  PlayRowBornFromRow,
+  PlayDatasetBornFrom,
+  PlayRowReadOrder,
+  PlayRowMeta,
+} from './cell-provenance';
+
 export interface PlayRowUpdate {
   key: string;
   rowId: number;
@@ -1050,6 +1193,12 @@ export interface PlayRowUpdate {
   provider?: string | null;
   error?: string | null;
   dataPatch?: Record<string, unknown>;
+  /**
+   * Row-grain provenance (ADR 0019), stored under the reserved `_cell_meta._row`
+   * key. It is a separate field rather than a `cellMetaPatch` entry because it
+   * is not a cell: it has no status, no producer, and no lifecycle.
+   */
+  rowMetaPatch?: PlayRowMeta;
   cellMetaPatch?: Record<
     string,
     {
@@ -1061,17 +1210,37 @@ export interface PlayRowUpdate {
         | 'cached'
         | 'missed'
         | 'skipped';
+      /**
+       * Run that produced this cell. Stamped at the emit site so a run-scoped
+       * read never has to infer ownership from the row's current `_run_id`,
+       * which a later run overwrites (ADR 0018).
+       */
+      runId?: string;
       stage?: string | null;
       provider?: string | null;
       error?: string | null;
-      producer?: {
-        kind: 'play' | 'tool' | 'code';
-        id?: string | null;
-        displayName?: string | null;
-        playId?: string | null;
-        toolId?: string | null;
-        runId?: string | null;
-      } | null;
+      producer?: PlaySheetCellProducer | null;
+      /**
+       * Every producer attempted for this cell during the run, oldest first.
+       * `producer` is patch-merged and therefore only ever holds the last leg;
+       * a waterfall's losing legs exist nowhere else (a failed tool call writes
+       * no durable receipt). See ADR 0018.
+       */
+      producers?: PlayCellProducerAttempt[] | null;
+      /**
+       * Attempts the per-cell cap dropped (ADR 0018/0019). Present only when
+       * the trace is a floor, so a capped cell cannot read as a complete count.
+       */
+      attemptsDropped?: number;
+      /**
+       * Explicit per-cell read trace (ADR 0019). Only nested step-program cells
+       * carry one, because their read-set includes sibling steps that the row's
+       * column order does not describe. Dataset columns resolve their reads
+       * through `_cell_meta._row.reads` instead of repeating a list per cell.
+       */
+      reads?: PlayCellReadRef[] | null;
+      /** Branch selected by a per-row conditional for this cell (ADR 0019). */
+      decide?: PlayCellDecision | null;
       reused?: boolean;
       completedAt?: number;
       staleAt?: number | null;