deepline 0.2.53 → 0.2.55

package/dist/bundling-sources/sdk/src/client.ts

@@ -205,8 +205,21 @@ function resolvePlayRunRuntimeSelection(
     process.env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
   if (!configured) {
     if (configuredNamespace || configuredToken) {
+      // Name the variables that are actually set. This branch is almost always
+      // hit by a stale value auto-loaded from a .env/.env.local rather than by
+      // a deliberate export, so the message has to say where to look and how
+      // to run the command anyway.
+      const present: string[] = [];
+      if (configuredNamespace) present.push('DEEPLINE_RUNTIME_NAMESPACE');
+      if (configuredToken) present.push('DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN');
+      const isPlural = present.length > 1;
       throw new DeeplineError(
-        'DEEPLINE_RUNTIME_ENVIRONMENT=preview and DEEPLINE_RUNTIME_NAMESPACE are required when runtime selection configuration is present.',
+        [
+          `Incomplete play runtime selection: ${present.join(' and ')} ${isPlural ? 'are' : 'is'} set but DEEPLINE_RUNTIME_ENVIRONMENT is not.`,
+          'Preview routing requires DEEPLINE_RUNTIME_ENVIRONMENT=preview together with DEEPLINE_RUNTIME_NAMESPACE; the token alone authorizes nothing.',
+          `If you did not export ${isPlural ? 'these' : 'this'} yourself, ${isPlural ? 'they were' : 'it was'} most likely auto-loaded from a .env or .env.local in the current directory (bun loads those automatically, and in a git worktree .env.local is usually a symlink to the main checkout).`,
+          `To run against the app-native runtime, clear ${isPlural ? 'them' : 'it'} for this command: ${present.map((name) => `${name}=`).join(' ')} <your deepline command>`,
+        ].join('\n'),
         undefined,
         'INVALID_RUNTIME_ENVIRONMENT',
       );
@@ -2448,6 +2461,9 @@ export class DeeplineClient {
     sourceFiles?: Record<string, string>;
     description?: string;
     artifact: Record<string, unknown>;
+    /** Which exported play in `sourceCode` this artifact is, when the file
+     *  exports more than one. Omit for the default export. */
+    exportName?: string | null;
     integrationMode?: 'live' | 'eval_stub' | 'fixture';
     /**
      * Sibling plays from the same local bundle graph. Lets the server splice

package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts

@@ -39,7 +39,7 @@ export type {
 
 export { extractDefinedPlayName } from '../../../shared_libs/plays/bundling/index.js';
 
-const PLAY_BUNDLE_CACHE_VERSION = 31;
+const PLAY_BUNDLE_CACHE_VERSION = 33;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const SDK_PACKAGE_ROOT = resolve(MODULE_DIR, '..', '..');
 const SOURCE_REPO_ROOT = resolve(SDK_PACKAGE_ROOT, '..');

package/dist/bundling-sources/sdk/src/release.ts

@@ -160,7 +160,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.53',
+  version: '0.2.55',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/sdk/src/types.ts

@@ -1270,6 +1270,14 @@ export interface PlayCheckResult {
   graphHash?: string | null;
   /** SHA-256 of the exact source bytes checked by Deepline. */
   sourceHash?: string | null;
+  /**
+   * Per-export results, present ONLY when the checked file exports more than
+   * one play. Single-play files keep the exact flat shape they always had.
+   * Entry 0 is the default export and mirrors the top-level fields; the
+   * top-level `valid` is the AND over every entry, so an agent that reads only
+   * `valid` can never ship a file whose second play fails.
+   */
+  exports?: PlayCheckExportResult[];
   /** Enforceable byte budgets measured during cloud preflight. */
   limits?: {
     revisionStorage: {
@@ -1291,6 +1299,29 @@ export interface PlayCheckResult {
   };
 }
 
+/**
+ * One exported play's check result inside a multi-play file. Carries the same
+ * per-play fields as {@link PlayCheckResult}, unprefixed and unaggregated, so a
+ * consumer can attribute an error to the export that produced it.
+ */
+export interface PlayCheckExportResult {
+  /** Canonical export name: `default`, or the named export (`batch`). */
+  exportName: string;
+  /** The `definePlay` name this export declares. */
+  name?: string | null;
+  valid: boolean;
+  errors: string[];
+  warnings?: string[];
+  issues?: PlayCheckIssue[];
+  staticPipeline?: Record<string, unknown> | null;
+  artifactHash?: string | null;
+  graphHash?: string | null;
+  sourceHash?: string | null;
+  summary?: string;
+  recognized?: PlayCheckRecognizedSummary;
+  triggers?: PlayCheckTriggersSummary | null;
+}
+
 /** Severity of a {@link PlayCheckIssue}. `error` fails the check; `warning` does not. */
 export type PlayCheckIssueSeverity = 'error' | 'warning';
 
@@ -1305,6 +1336,12 @@ export interface PlayCheckIssue {
   code: string;
   severity: PlayCheckIssueSeverity;
   message: string;
+  /**
+   * Which exported play raised this issue, when the checked file exports more
+   * than one and this is not the default export. Absent everywhere else, so
+   * the structured channel stays byte-identical for single-play files.
+   */
+  exportName?: string;
   path?: string;
   hint?: string;
   validOptions?: string[];
@@ -1318,7 +1355,12 @@ export interface PlayCheckIssue {
 export interface PlayCheckRecognizedSummary {
   triggers?: PlayCheckTriggersSummary;
   tools?: string[];
-  datasets?: { name: string; columns?: string[] }[];
+  /**
+   * Durable datasets the play produces. `undrawnColumns` echoes the columns the
+   * author declared out of an authored `@mermaid` diagram with
+   * `.run({ undrawnColumns: [...] })`, so an opt-out is visible in check output.
+   */
+  datasets?: { name: string; columns?: string[]; undrawnColumns?: string[] }[];
   inputs?: string[];
   outputs?: string[];
 }

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -5,6 +5,7 @@ import { pipeline } from 'node:stream/promises';
 import type { PlaySheetContract } from '@shared_libs/plays/static-pipeline';
 import type { PlayRowUpdate } from '@shared_libs/play-runtime/ctx-types';
 import type { PlayRunTimelineEntry } from '@shared_libs/play-runtime/live-events';
+import type { PlayDatasetBornFrom } from '@shared_libs/play-runtime/cell-provenance';
 import {
   routePlayActivityObservation,
   type PlayActivityObservation,
@@ -84,6 +85,8 @@ export type RuntimeStatusUpdate = {
     succeededRows?: number;
     failedRows?: number;
     complete?: boolean;
+    /** Dataset-grain row birth, stated once per dataset (ADR 0019). */
+    bornFrom?: PlayDatasetBornFrom;
     at: number;
   }>;
   /** Sparse typed activity facts. Routing/deduplication happens server-side. */
@@ -1432,7 +1435,13 @@ async function updateRunStatusViaAppRuntimeUnlocked(
       (event.persistedRows ?? 0) > current.persistedRows ||
       (event.succeededRows ?? 0) > current.succeededRows ||
       (event.failedRows ?? 0) > current.failedRows ||
-      (event.complete === true && current.complete !== true);
+      (event.complete === true && current.complete !== true) ||
+      // A birth record the snapshot has not seen — or a larger admitted-row
+      // count from a later page — is itself a change, or the dataset would keep
+      // an unattributed or stale birth for the whole run.
+      (event.bornFrom !== undefined &&
+        (!current.bornFrom ||
+          event.bornFrom.rowCountIn > current.bornFrom.rowCountIn));
     if (!changesSnapshot) continue;
     events.push({
       type: 'dataset.lifecycle',
@@ -1453,6 +1462,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
         ? {}
         : { failedRows: event.failedRows }),
       ...(event.complete === undefined ? {} : { complete: event.complete }),
+      ...(event.bornFrom === undefined ? {} : { bornFrom: event.bornFrom }),
     });
   }
   const latestActivities = new Map(
@@ -1908,3 +1918,22 @@ export async function skipRuntimeStepReceiptViaAppRuntime(
     ...input,
   });
 }
+
+/**
+ * Post one durable docflow observation to the receipt gateway (ADR 0016 rule
+ * 2). Callers invoke this fire-and-forget; it resolves on the gateway ack and
+ * surfaces transport failures to its caller (the runner's observation sink),
+ * which swallows-and-logs so the play body is never affected.
+ */
+export async function observeDocflowNodeViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<RuntimeApiRequest, { action: 'observe_docflow_node' }>,
+    'action'
+  >,
+): Promise<void> {
+  await postAppRuntimeApi<{ ok?: boolean }>(context, {
+    action: 'observe_docflow_node',
+    ...input,
+  });
+}

package/dist/bundling-sources/shared_libs/play-runtime/cell-provenance.ts

@@ -0,0 +1,231 @@
+/**
+ * Cell-level provenance capture (ADR 0019).
+ *
+ * ADR 0018 answered *which producer* filled a cell. This module carries the
+ * other half — *what that producer was given*, *which branch was taken*, and
+ * *where the row came from* — as additive fields on writes the runtime already
+ * makes. Nothing here performs a round trip, and every value is a fact the
+ * runtime held at the write site rather than a declaration it trusted or a
+ * mapping it reconstructed afterwards.
+ *
+ * Shared by the runtime (`ctx-types`/`context`), the run ledger, and the
+ * durable sheet parse path, so all three agree on one shape and one bound.
+ */
+
+/**
+ * One cell version a cell was computed from.
+ *
+ * Both addressing components are omitted when they match the cell that carries
+ * the ref: no `table` means the same table, no `rowKey` means the same row.
+ * That is not shorthand for the reader's convenience — it is what keeps the
+ * trace inside the retained-row memory budget. Runtime sheet row keys are
+ * namespace-salted hashes, and repeating one per ref per cell inflated a
+ * mapped row by roughly forty percent, which the streaming-dataset budget test
+ * rejects. Readers fill both in from the cell's own address; the durable sheet
+ * read model does this so every consumer sees a complete ref.
+ *
+ * `version` is the attempt/fence identity of the value read and is set only
+ * where the runtime already held one: absent means "not witnessed", never
+ * "version 0".
+ */
+export interface PlayCellReadRef {
+  table?: string;
+  rowKey?: string;
+  column: string;
+  version?: number;
+}
+
+/**
+ * The branch a per-row control-flow evaluation selected, with the read-set the
+ * evaluator was handed. `branch` is the runtime's own vocabulary, never
+ * authored free text.
+ */
+export interface PlayCellDecision {
+  branch: string;
+  reads: PlayCellReadRef[];
+}
+
+/** Row-grain birth: the source row the runtime held while building this row. */
+export type PlayRowBornFromRow = { table: string; rowKey: string };
+
+/**
+ * Dataset-grain birth: rows arrived from free-form play-body code and no
+ * per-row mapping was witnessed. It names the destination table and how many
+ * rows entered, and deliberately says nothing about any single row.
+ *
+ * There is no `step` field. The only step name available at the write site is
+ * `map:<table>`, which restates `table` — a derived join key, not an observed
+ * fact — and the record already hangs off the dataset's own lifecycle entry.
+ */
+export type PlayDatasetBornFrom = {
+  table: string;
+  rowCountIn: number;
+};
+
+export type PlayRowBornFrom = PlayRowBornFromRow | PlayDatasetBornFrom;
+
+/**
+ * Per-cell cap on the durable read trace, matching the producer trace bound.
+ * The read-set is the row's column list, so an unbounded trace would put a wide
+ * row's whole schema into `_cell_meta` once per cell. Truncation keeps the
+ * first columns in row order, which is stable across runs.
+ */
+export const MAX_CELL_READ_REFS = 12;
+
+/**
+ * Cap on how many cells one row's read order describes. A dataset has a handful
+ * of columns; this only bounds pathological graphs, and it reports what it
+ * dropped rather than trimming silently.
+ */
+export const MAX_ROW_READ_CELLS = 24;
+
+/** Reserved `_cell_meta` key holding row-grain facts rather than a cell. */
+export const ROW_META_CELL_KEY = '_row';
+
+/**
+ * Row-grain read order (ADR 0019).
+ *
+ * Every cell in a row reads a prefix of the same list: the row's input columns,
+ * then each column this run wrote, in the order they became available. Storing
+ * the list once per row and a cut point per cell is the same information as a
+ * per-cell array at O(columns) instead of O(columns x cells) — which matters,
+ * because this rides the retained-row memory budget on every mapped row.
+ *
+ * A written column is appended to `columns` before its own cell runs, so its
+ * position *is* its cut point: everything before it was available, itself and
+ * everything after it was not. `upto` therefore only carries cells the list
+ * cannot place — non-persisted fields, and cells past the column cap.
+ * `droppedCells` counts cells no cut describes at all, so an incomplete order
+ * is visible instead of looking like a cell that read nothing.
+ */
+export interface PlayRowReadOrder {
+  columns: string[];
+  upto?: Record<string, number>;
+  droppedCells?: number;
+}
+
+/**
+ * How many leading `columns` entries a cell read, or null when the order
+ * describes no read for it. Null is not zero: a cell that read nothing and a
+ * cell nobody recorded must not render the same.
+ */
+export function cellReadCut(
+  order: PlayRowReadOrder | null | undefined,
+  column: string,
+): number | null {
+  if (!order) return null;
+  const explicit = order.upto?.[column];
+  if (typeof explicit === 'number' && Number.isFinite(explicit)) {
+    return Math.max(0, Math.min(Math.trunc(explicit), order.columns.length));
+  }
+  const index = order.columns.indexOf(column);
+  return index >= 0 ? index : null;
+}
+
+/** Row-grain `_cell_meta._row` record. */
+export interface PlayRowMeta {
+  reads?: PlayRowReadOrder;
+  bornFrom?: PlayRowBornFromRow;
+}
+
+/**
+ * Expand one cell's read-set out of the row order. Returns undefined when the
+ * order describes no read for that cell, which is not the same as an empty
+ * read-set and must not be rendered as one.
+ */
+export function hydrateCellReadRefs(
+  order: PlayRowReadOrder | null | undefined,
+  column: string,
+  rowKey: string,
+): Array<PlayCellReadRef & { rowKey: string }> | undefined {
+  const cut = cellReadCut(order, column);
+  if (cut === null || cut <= 0 || !order) return undefined;
+  const refs = order.columns
+    .slice(0, Math.min(cut, MAX_CELL_READ_REFS))
+    .map((readColumn) => ({ rowKey, column: readColumn }));
+  return refs.length > 0 ? refs : undefined;
+}
+
+/** Parse a stored row read order off untrusted transport. */
+export function normalizeRowReadOrder(value: unknown): PlayRowReadOrder | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const columns = Array.isArray(record.columns)
+    ? record.columns
+        .filter((column): column is string => typeof column === 'string')
+        .slice(0, MAX_CELL_READ_REFS)
+    : [];
+  if (columns.length === 0) return null;
+  const rawUpto =
+    record.upto &&
+    typeof record.upto === 'object' &&
+    !Array.isArray(record.upto)
+      ? (record.upto as Record<string, unknown>)
+      : {};
+  const upto: Record<string, number> = {};
+  let entries = 0;
+  for (const [column, cut] of Object.entries(rawUpto)) {
+    if (entries >= MAX_ROW_READ_CELLS) break;
+    if (typeof cut !== 'number' || !Number.isFinite(cut) || cut < 0) continue;
+    upto[column] = Math.min(Math.trunc(cut), columns.length);
+    entries += 1;
+  }
+  const droppedCells = finiteNonNegativeInteger(record.droppedCells);
+  return {
+    columns,
+    ...(entries > 0 ? { upto } : {}),
+    ...(droppedCells ? { droppedCells } : {}),
+  };
+}
+
+/** Enforce {@link MAX_CELL_READ_REFS} without reordering. */
+export function boundCellReadRefs<T>(refs: readonly T[]): T[] {
+  return refs.length > MAX_CELL_READ_REFS
+    ? refs.slice(0, MAX_CELL_READ_REFS)
+    : [...refs];
+}
+
+/**
+ * Fold a newly stated dataset birth into the one already on the snapshot.
+ *
+ * A paged dataset registers more than once, each registration stating the rows
+ * admitted so far, so the larger `rowCountIn` is the later truth. A phase event
+ * that states no birth never erases one that was witnessed.
+ */
+export function mergeDatasetBornFrom(
+  current: PlayDatasetBornFrom | null | undefined,
+  next: PlayDatasetBornFrom | null | undefined,
+): PlayDatasetBornFrom | null {
+  if (!next) return current ?? null;
+  if (!current) return next;
+  return next.rowCountIn > current.rowCountIn ? next : current;
+}
+
+function finiteNonNegativeInteger(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    return null;
+  }
+  return Math.trunc(value);
+}
+
+function nonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Parse a dataset-grain birth record off untrusted transport. Returns null for
+ * anything that is not a complete record: a partial birth record would claim a
+ * lineage the writer never stated.
+ */
+export function normalizeDatasetBornFrom(
+  value: unknown,
+): PlayDatasetBornFrom | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const table = nonEmptyString(record.table);
+  const rowCountIn = finiteNonNegativeInteger(record.rowCountIn);
+  if (!table || rowCountIn === null) return null;
+  return { table, rowCountIn };
+}