@elaraai/e3-types 1.0.84 → 1.0.85

package/src/execution.spec.ts

@@ -5,15 +5,16 @@
 
 /**
  * Execution status wire: the typed outcomes with their peaks, a split task's
- * plan and whether the execution is a unit, what each keeps from gc, and the
- * refusal of a record an older e3 wrote before `cancelled` and `interrupted`
- * were cases of it, before a runner's peak was recorded, before a split task's
- * plan was, or before a record said whether it is a unit.
+ * plan, whether the execution is a unit and why a stopped one stopped, what
+ * each keeps from gc, and the refusal of a record an older e3 wrote before
+ * `cancelled` and `interrupted` were cases of it, before a runner's peak was
+ * recorded, before a split task's plan was, before a record said whether it
+ * is a unit, or before a stopped one said why.
  */
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ArrayType, DateTimeType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
+import { ArrayType, BooleanType, DateTimeType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
 import { ExecutionStatusType, decodeExecutionStatus, executionStatusRoots, type ExecutionStatus } from './execution.js';
 
 /** The four-case wire every record had before the typed outcomes. */
@@ -45,7 +46,7 @@ describe('ExecutionStatusType', () => {
   };
   const encodeOlder = encodeBeast2For(PreOutcomeExecutionStatusType);
 
-  it('round-trips the typed outcomes, with a runner\'s peak or without one, a task\'s own or a unit\'s', () => {
+  it('round-trips the typed outcomes, with a runner\'s peak or without one, a task\'s own or a unit\'s, and why a stopped one stopped', () => {
     const own = { ...stopped, unit: false };
     const statuses: ExecutionStatus[] = [
       variant('success', { ...own, outputHash: 'b'.repeat(64), peakBytes: some(96n * 1024n ** 2n), plan: none }),
@@ -54,8 +55,11 @@ describe('ExecutionStatusType', () => {
       variant('running', { executionId: '0199-b', inputHashes: ['a'.repeat(64)], startedAt: new Date(1000), pid: 4242n, pidStartTime: 7n, bootId: 'boot', unit: true }),
       variant('failed', { ...own, exitCode: 1n, peakBytes: some(412n * 1024n ** 2n) }),
       variant('failed', { ...own, exitCode: -1n, peakBytes: none }),
-      variant('cancelled', own),
-      variant('interrupted', { ...own, pid: 4242n }),
+      variant('cancelled', { ...own, reason: { kind: variant('aborted', null), message: 'cancelled: e3 stopped the runner because the run was aborted' } }),
+      variant('interrupted', { ...own, pid: 4242n, reason: { kind: variant('owner_gone', null), message: 'its runner and its owner are gone' } }),
+      variant('interrupted', { ...own, pid: 0n, unit: true, reason: { kind: variant('yielded', null), message: 'its run yielded' } }),
+      variant('interrupted', { ...own, pid: 0n, reason: { kind: variant('host', 'OutOfMemoryError'), message: 'its container ran out of memory' } }),
+      variant('interrupted', { ...own, pid: 0n, reason: { kind: variant('unrecorded', null), message: '' } }),
       variant('error', { ...own, message: 'Failed to read output: no such file' }),
     ];
     const encode = encodeBeast2For(ExecutionStatusType);
@@ -67,7 +71,7 @@ describe('ExecutionStatusType', () => {
     assert.deepEqual(executionStatusRoots(variant('success', { ...success, plan: none })), ['b'.repeat(64)]);
     assert.deepEqual(executionStatusRoots(variant('success', { ...success, plan: some('c'.repeat(64)) })), ['b'.repeat(64), 'c'.repeat(64)]);
     assert.deepEqual(executionStatusRoots(variant('failed', { ...stopped, exitCode: 1n, peakBytes: none, unit: false })), []);
-    assert.deepEqual(executionStatusRoots(variant('cancelled', { ...stopped, unit: false })), []);
+    assert.deepEqual(executionStatusRoots(variant('cancelled', { ...stopped, unit: false, reason: { kind: variant('aborted', null), message: '' } })), []);
   });
 
   it('keeps from gc the inputs a running attempt reads, passing over a merge\'s tag', () => {
@@ -113,6 +117,24 @@ describe('ExecutionStatusType', () => {
       }),
     });
     assert.throws(() => decodeExecutionStatus(encodeBeast2For(withoutUnits)(variant('success', { ...stopped, outputHash: 'b'.repeat(64), peakBytes: none, plan: none }))), refusal);
+    // With units, before a stopped record said why it stopped: only the
+    // repository upgrade that carries such a record forward reads it, and every
+    // case of it is refused, since its type names the cases that changed.
+    const withoutReasons = VariantType({
+      ...ExecutionStatusType.cases,
+      cancelled: StructType({ executionId: StringType, inputHashes: ArrayType(StringType), startedAt: DateTimeType, completedAt: DateTimeType, unit: BooleanType }),
+      interrupted: StructType({
+        executionId: StringType, inputHashes: ArrayType(StringType), startedAt: DateTimeType, completedAt: DateTimeType, pid: IntegerType, unit: BooleanType,
+      }),
+    });
+    const own = { ...stopped, unit: false };
+    for (const record of [
+      variant('cancelled', own),
+      variant('interrupted', { ...own, pid: 4242n }),
+      variant('success', { ...own, outputHash: 'b'.repeat(64), peakBytes: none, plan: none }),
+    ] as const) {
+      assert.throws(() => decodeExecutionStatus(encodeBeast2For(withoutReasons)(record)), refusal);
+    }
   });
 
   it('throws for bytes of no status shape', () => {

package/src/execution.ts

@@ -15,7 +15,7 @@
  * - For success: output hash, timing, peak memory and a split task's last plan
  * - For failed: exit code, timing and peak memory
  * - For error: internal error message and timing
- * - For cancelled and interrupted: how e3, not the task, ended it
+ * - For cancelled and interrupted: how e3, not the task, ended it, and why
  *
  * Every case says whether the execution is a unit of a split task — a piece,
  * or a merge of the pieces' outputs — which is recorded under its task's hash
@@ -31,10 +31,42 @@ import {
   IntegerType,
   BooleanType,
   DateTimeType,
+  NullType,
   ValueTypeOf,
   decodeBeast2For,
 } from '@elaraai/east';
 
+/**
+ * Why an execution stopped without finishing: what a `cancelled` or an
+ * `interrupted` record says, written in the same write as the record.
+ *
+ * - `aborted`: the signal it ran under was aborted — its run was cancelled,
+ *   or the call it ran for ended
+ * - `yielded`: its run yielded mid-stage, and a run resumed takes the stage up
+ *   again
+ * - `owner_gone`: its runner and the process, or the browser tab, that owned
+ *   it are gone
+ * - `host`: a host's own reason, by its code — e3-cloud's for a container
+ *   that stopped, say
+ * - `unrecorded`: it stopped before e3 recorded reasons; only the repository
+ *   upgrade that carried its record forward writes it
+ *
+ * `message` is what e3 wrote as the attempt's log's last line, after its
+ * `e3: `, or the host's words; empty for `unrecorded`.
+ */
+export const StopReasonType = StructType({
+  kind: VariantType({
+    aborted: NullType,
+    yielded: NullType,
+    owner_gone: NullType,
+    host: StringType,
+    unrecorded: NullType,
+  }),
+  message: StringType,
+});
+
+export type StopReason = ValueTypeOf<typeof StopReasonType>;
+
 /** A running execution's process identification. */
 const RunningStatusType = StructType({
   /** Unique execution ID (UUIDv7) */
@@ -126,10 +158,14 @@ const ErrorStatusType = StructType({
  * - `success`: Task ran and returned exit code 0
  * - `failed`: Task ran and returned non-zero exit code
  * - `error`: e3 execution engine had an internal error (runner not found, output missing, etc.)
- * - `cancelled`: e3 stopped the execution because the run was aborted, before
- *   its runner started or while it ran — not the task's own failure
- * - `interrupted`: the orchestrator that owned the execution exited before it
- *   finished, and its runner is gone too, so nothing will write its outcome
+ * - `cancelled`: e3 stopped the execution because the signal it ran under was
+ *   aborted, before its runner started or while it ran — not the task's own
+ *   failure
+ * - `interrupted`: the execution can no longer finish, and nothing will write
+ *   its outcome: its runner and its owner are gone, its host says it cannot,
+ *   or its run yielded mid-stage
+ *
+ * Each of the two says why it stopped ({@link StopReasonType}).
  *
  * The `running` state includes process identification fields (pid, pidStartTime, bootId)
  * to enable detection of crashed executions. See design/e3-execution.md for details.
@@ -154,6 +190,8 @@ export const ExecutionStatusType = VariantType({
      *  the pieces' outputs — rather than a task's own execution, which the one
      *  unit of a task whose input closes no piece is */
     unit: BooleanType,
+    /** Why it stopped: `aborted` */
+    reason: StopReasonType,
   }),
   interrupted: StructType({
     /** Unique execution ID (UUIDv7) */
@@ -170,6 +208,9 @@ export const ExecutionStatusType = VariantType({
      *  the pieces' outputs — rather than a task's own execution, which the one
      *  unit of a task whose input closes no piece is */
     unit: BooleanType,
+    /** Why it can no longer finish: `owner_gone`, `yielded`, or its host's
+     *  reason */
+    reason: StopReasonType,
   }),
 });
 
@@ -209,8 +250,12 @@ const decodeCurrentStatus = decodeBeast2For(ExecutionStatusType);
  * Decode an execution status.
  *
  * @remarks
- * Stored state, so it changes by hard cutover: a repository an older e3 wrote
- * is re-created rather than read, and this says so.
+ * Stored state, which changes as `docs/conventions/WIRE_MIGRATION.md` says:
+ * this reads the current form alone. A repository's upgrade steps carry its
+ * records into it when an e3 first opens the repository — the stop reasons'
+ * step those from before a stopped execution recorded why — so a record in an
+ * earlier form here is one from before repositories recorded their upgrades,
+ * whose repository is re-created, and this says so.
  *
  * @param data - the stored bytes
  * @returns the status

package/src/index.ts

@@ -92,6 +92,7 @@ export {
   treePath,
   pathToString,
   parsePath,
+  parseKeypath,
   parseDatasetPath,
   parsePackageRef,
   urlPathToTreePath,
@@ -185,6 +186,8 @@ export {
 
 // Execution status
 export {
+  StopReasonType,
+  type StopReason,
   ExecutionStatusType,
   type ExecutionStatus,
   decodeExecutionStatus,
@@ -224,6 +227,8 @@ export {
 export {
   RepositoryRecordType,
   type RepositoryRecord,
+  RepositoryUpgradeProgressType,
+  type RepositoryUpgradeProgress,
   RepoStatusType,
   type RepoStatus,
   RepoMetadataType,
@@ -233,8 +238,8 @@ export {
 // The release of e3 this build is, which what it keeps and ships records
 export { E3_RELEASE, compareReleases } from './release.js';
 
-// The names e3 makes paths of
-export { type NamedKind, nameProblem } from './names.js';
+// The names e3 makes paths of, and the hashes and ids
+export { type NamedKind, type HashKind, type IdKind, type IdentifierKind, nameProblem } from './names.js';
 
 // Dataset transfer types
 export {
@@ -257,6 +262,7 @@ export {
   isCollectionRoot,
   encodeDatasetBlob,
   writeCollectionManifest,
+  SEGMENT_WRITES_IN_FLIGHT,
   type CollectionSegmentRef,
   type CollectionPiece,
   type SegmentSink,
@@ -356,6 +362,7 @@ export {
   // Execution
   DataflowRequestType,
   LogChunkType,
+  TaskLogChunkType,
   TaskExecutionResultType,
   DataflowResultType,
   // Dataflow API polling
@@ -366,9 +373,12 @@ export {
   UnitWaitType,
   SplitProgressType,
   ApiDataflowExecutionStateType,
+  DATAFLOW_POLL_EVENTS_MAX,
   // Task Execution History
   ExecutionHistoryStatusType,
   ExecutionListItemType,
+  TASK_EXECUTIONS_PAGE_DEFAULT,
+  TASK_EXECUTIONS_PAGE_MAX,
   // Dataset List
   TreeKindType,
   ListEntryType,
@@ -378,6 +388,7 @@ export {
   ExecuteLimitsType,
   DiagnosticType,
   ExecuteResultType,
+  CallArgType,
   FunctionCallRequestType,
   FunctionSignatureType,
   OneShotRequestType,
@@ -389,9 +400,16 @@ export {
   SplitCallPlanType,
   MutationCallRequestType,
   MutationResultType,
+  RecordMigrationAppliedType,
   RecordSignatureType,
   RecordCommitInfoType,
+  RecordArgPreviewType,
+  RecordCommitArgsType,
+  RecordHistoryCommitType,
   RecordHistoryResultType,
+  RECORD_ARG_TEXT_CHARS,
+  RECORD_ARG_TEXT_BYTES,
+  RECORD_ARGS_READ_BYTES,
   // Type aliases
   type Error,
   type RepositoryStatus,
@@ -425,6 +443,7 @@ export {
   type TaskDetails,
   type DataflowRequest,
   type LogChunk,
+  type TaskLogChunk,
   type TaskExecutionResult,
   type DataflowResult,
   type DataflowEvent,
@@ -442,6 +461,7 @@ export {
   type ExecuteLimits,
   type Diagnostic,
   type ExecuteResult,
+  type CallArg,
   type FunctionCallRequest,
   type FunctionSignature,
   type OneShotRequest,
@@ -452,8 +472,12 @@ export {
   type SplitCallPlan,
   type MutationCallRequest,
   type MutationResult,
+  type RecordMigrationApplied,
   type RecordSignature,
   type RecordCommitInfo,
+  type RecordArgPreview,
+  type RecordCommitArgs,
+  type RecordHistoryCommit,
   type RecordHistoryResult,
 } from './api.js';
 
@@ -474,9 +498,17 @@ export {
   ExecutionEventType,
   type ExecutionEvent,
   type PartitionProgress,
+  DataflowForceType,
+  type DataflowForce,
+  dataflowForce,
+  dataflowForceOption,
   DataflowExecutionStateType,
   type DataflowExecutionState,
   decodeDataflowExecutionState,
+  ExecutionStateSummaryType,
+  type ExecutionStateSummary,
+  executionStateSummary,
+  lastEventSeq,
   // Dataflow run history
   DataflowRunStatusType,
   type DataflowRunStatus,
@@ -488,6 +520,10 @@ export {
   type DataflowRun,
 } from './dataflow.js';
 
+// The sizes e3 cuts a split task's input into pieces at, which a caller
+// planning a split call weighs a dataset against
+export { PIECE_SIZES, type PieceSizes } from './pieces.js';
+
 // A split task's unit graph, a stage at a time
 export {
   UNIT_PLAN_KIND,

package/src/names.ts

@@ -13,6 +13,18 @@
 /** What a name names. */
 export type NamedKind = 'repository' | 'workspace' | 'package' | 'package version' | 'lock';
 
+/** What a hash e3 makes a path or a key of names: an object, or an
+ *  execution's task or inputs. */
+export type HashKind = 'object hash' | 'task hash' | 'inputs hash';
+
+/** What an id e3 makes a path or a key of names: an execution attempt, a
+ *  dataflow run, or a gc run in steps. */
+export type IdKind = 'execution id' | 'run id' | 'gc run id';
+
+/** What a hash or an id e3 makes a path or a key of names: not a name, so
+ *  checked for its form rather than by {@link nameProblem}. */
+export type IdentifierKind = HashKind | IdKind;
+
 /** What no name may hold: a path separator, a character a Windows file name
  *  refuses, or a control character. */
 const REFUSED = /[/\\:*?"<>|\u0000-\u001f]/;

package/src/pieces.spec.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * The platform's piece sizes, which e3-core's piece rule closes pieces at and
+ * a caller planning a split call weighs a dataset against.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { PIECE_SIZES } from './index.js';
+
+describe('PIECE_SIZES', () => {
+  it('is 16, 64 and 256 MiB, exported from the package', () => {
+    assert.deepEqual(PIECE_SIZES, { min: 16 * 2 ** 20, target: 64 * 2 ** 20, max: 256 * 2 ** 20 });
+  });
+
+  it('orders its sizes: the least a piece holds, its middle, and the most', () => {
+    assert.ok(PIECE_SIZES.min < PIECE_SIZES.target && PIECE_SIZES.target < PIECE_SIZES.max);
+  });
+});

package/src/pieces.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * The sizes e3 cuts a split task's input into pieces at.
+ *
+ * They live here, beside the wire types, so a caller that plans a split call
+ * in a browser — the query builder — weighs a dataset against the smallest
+ * piece e3 cuts without importing e3-core. e3-core's piece rule closes pieces
+ * at these sizes, and its `pieceSizes()` gives the sizes a process plans with:
+ * these, or the sizes a test sets.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The sizes the piece rule closes pieces at, in stored bytes: a piece closes
+ * only once it holds `min`, weighs its segments against `max` until it holds
+ * `target` and against `min` after, and always closes once it holds `max`.
+ *
+ * @remarks
+ * A dataset that weighs no more than `min` is one piece, which is why a
+ * caller compares a dataset's stored bytes with `min` to tell whether a split
+ * call would split it.
+ */
+export interface PieceSizes {
+  /** The least a piece holds, unless the input ends first. */
+  readonly min: number;
+  /** Where a piece starts closing readily: the pieces' middle size, which a
+   *  merge range aims for too. */
+  readonly target: number;
+  /** The most a piece holds, but for the rest of a `by` group. */
+  readonly max: number;
+}
+
+/**
+ * The platform's piece sizes: 16, 64 and 256 MiB.
+ *
+ * @example
+ * ```ts
+ * import { PIECE_SIZES } from '@elaraai/e3-types';
+ *
+ * // A dataset within one piece is read in one call.
+ * const split = storedBytes > PIECE_SIZES.min;
+ * ```
+ */
+export const PIECE_SIZES: PieceSizes = { min: 16 * 2 ** 20, target: 64 * 2 ** 20, max: 256 * 2 ** 20 };

package/src/release.ts

@@ -17,7 +17,7 @@
  */
 
 /** The release of e3 this build is. */
-export const E3_RELEASE = '1.0.84';
+export const E3_RELEASE = '1.0.85';
 
 /** A semantic version: its core, a pre-release, and build metadata. */
 const RELEASE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;

package/src/repository.ts

@@ -34,6 +34,24 @@ export const RepositoryRecordType = StructType({
 
 export type RepositoryRecord = ValueTypeOf<typeof RepositoryRecordType>;
 
+/**
+ * A store upgrade under way in a repository, kept beside the repository
+ * record: the step, the release of e3 applying it, and where its last part
+ * stopped. A step applies in parts, and the next part takes it up from here,
+ * in this process or another; the record lists the step only once it is done.
+ */
+export const RepositoryUpgradeProgressType = StructType({
+  /** The step's name */
+  step: StringType,
+  /** The release of e3 applying it */
+  release: StringType,
+  /** Where its last part stopped: the step's own cursor, which the next part
+   *  takes it up from */
+  cursor: StringType,
+});
+
+export type RepositoryUpgradeProgress = ValueTypeOf<typeof RepositoryUpgradeProgressType>;
+
 /**
  * Where a repository is in its lifecycle.
  */

package/src/structure.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * Keypaths: `parseKeypath` reads back what `pathToString` writes, whatever a
+ * field is named, with no structure to check it against; `parsePath` reads the
+ * same syntax and checks each field against a structure as it reads it.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { IntegerType, equalFor, printFor, toEastTypeValue, variant } from '@elaraai/east';
+import { TreePathType, parseKeypath, parsePath, pathToString, type Structure, type TreePath } from './structure.js';
+
+const equalPath = equalFor(TreePathType);
+const printPath = printFor(TreePathType);
+
+describe('parseKeypath', () => {
+  it('reads back what pathToString writes, whatever a field is named', () => {
+    const names = ['inputs', 'my field', 'a.b', 'a/b', 'back`tick', 'back\\slash', 'café', '1st', '', '`'];
+    for (const name of names) {
+      const path: TreePath = [variant('field', 'inputs'), variant('field', name)];
+      const printed = pathToString(path);
+      if (name === '') {
+        // An empty field name prints as nothing a keypath can read.
+        assert.throws(() => parseKeypath(printed));
+        continue;
+      }
+      const read = parseKeypath(printed);
+      assert.ok(equalPath(read, path), `${JSON.stringify(name)}: ${printed} read back as ${printPath(read)}`);
+    }
+  });
+
+  it('reads the empty string as the root', () => {
+    assert.ok(equalPath(parseKeypath(''), []));
+  });
+
+  it('refuses a string that is not a keypath, naming where', () => {
+    assert.throws(() => parseKeypath('inputs.x'), { message: "parseKeypath: unexpected character at position 0: 'i'" });
+    assert.throws(() => parseKeypath('.inputs.'), { message: "parseKeypath: expected identifier after '.' at position 8" });
+    assert.throws(() => parseKeypath('.inputs!'), { message: "parseKeypath: unexpected character at position 7: '!'" });
+  });
+});
+
+describe('parsePath', () => {
+  const structure: Structure = variant('struct', new Map([
+    ['inputs', variant('struct', new Map([
+      ['sales', variant('value', { type: toEastTypeValue(IntegerType), writable: true })],
+    ]))],
+  ]));
+
+  it('reads a keypath, and the structure at it', () => {
+    const { path, structure: at } = parsePath('.inputs.sales', structure);
+    assert.ok(equalPath(path, [variant('field', 'inputs'), variant('field', 'sales')]));
+    assert.equal(at.type, 'value');
+  });
+
+  it('refuses a field the structure lacks before a malformed one after it, and a path into a dataset', () => {
+    assert.throws(() => parsePath('.nope!', structure), { message: "parsePath: field 'nope' not found at ''. Available: inputs" });
+    assert.throws(() => parsePath('.inputs!', structure), { message: "parsePath: unexpected character at position 7: '!'" });
+    assert.throws(() => parsePath('.inputs.sales.more', structure), { message: "parsePath: cannot descend into dataset at '.inputs.sales'" });
+  });
+});

package/src/structure.ts

@@ -181,10 +181,69 @@ export interface ParsePathResult {
  * ```
  */
 export function parsePath(pathStr: string, structure: Structure): ParsePathResult {
-  if (pathStr === '') return { path: [], structure };
-
   const segments: TreePath = [];
   let currentStructure = structure;
+
+  // Each field is checked as it is read, so a field the structure lacks is
+  // refused before a malformed one after it.
+  for (const fieldName of keypathFields(pathStr, 'parsePath')) {
+    if (currentStructure.type === 'value') {
+      throw new Error(`parsePath: cannot descend into dataset at '${pathToString(segments)}'`);
+    }
+
+    // currentStructure.type === 'struct' (only other option after 'value' check)
+    const fields = currentStructure.value;
+    const childStructure = fields.get(fieldName);
+    if (childStructure === undefined) {
+      const available = [...fields.keys()].map(k => printIdentifier(k)).join(', ');
+      throw new Error(`parsePath: field '${fieldName}' not found at '${pathToString(segments)}'. Available: ${available}`);
+    }
+    segments.push(variant('field', fieldName));
+    currentStructure = childStructure;
+  }
+
+  return { path: segments, structure: currentStructure };
+}
+
+/**
+ * Parses an East keypath string into a path, with no structure to check it
+ * against: the inverse of {@link pathToString}.
+ *
+ * @remarks
+ * The syntax is {@link parsePath}'s: `.field` for a simple identifier, and
+ * `` .`field` `` for one that needs quoting, with `` \` `` for a literal
+ * backtick and `\\` for a backslash. Whether the path names anything is the
+ * caller's to judge, as a status asked for named datasets leaves out a path
+ * the workspace does not hold.
+ *
+ * @param pathStr - A keypath string (e.g., ".inputs.sales", or ".inputs.`my field`")
+ * @returns The path; the root's, `[]`, for the empty string
+ *
+ * @throws {Error} When the string is not a keypath, such as one that does not
+ *   start with `.`
+ *
+ * @example
+ * ```ts
+ * parseKeypath('.inputs.sales');
+ * // [field('inputs'), field('sales')]
+ *
+ * parseKeypath(pathToString([variant('field', 'inputs'), variant('field', 'my field')]));
+ * // [field('inputs'), field('my field')]
+ * ```
+ */
+export function parseKeypath(pathStr: string): TreePath {
+  return [...keypathFields(pathStr, 'parseKeypath')].map((fieldName) => variant('field', fieldName));
+}
+
+/**
+ * Reads a keypath string's field names in order, refusing a malformed one when
+ * it reaches it.
+ *
+ * @param pathStr - The keypath string
+ * @param caller - The function a refusal names
+ * @internal
+ */
+function* keypathFields(pathStr: string, caller: string): Generator<string> {
   let pos = 0;
 
   while (pos < pathStr.length) {
@@ -221,29 +280,13 @@ export function parsePath(pathStr: string, structure: Structure): ParsePathResul
       }
 
       if (fieldName.length === 0) {
-        throw new Error(`parsePath: expected identifier after '.' at position ${pos}`);
-      }
-
-      // Validate against structure
-      if (currentStructure.type === 'value') {
-        throw new Error(`parsePath: cannot descend into dataset at '${pathToString(segments)}'`);
+        throw new Error(`${caller}: expected identifier after '.' at position ${pos}`);
       }
-
-      // currentStructure.type === 'struct' (only other option after 'value' check)
-      const fields = currentStructure.value;
-      const childStructure = fields.get(fieldName);
-      if (childStructure === undefined) {
-        const available = [...fields.keys()].map(k => printIdentifier(k)).join(', ');
-        throw new Error(`parsePath: field '${fieldName}' not found at '${pathToString(segments)}'. Available: ${available}`);
-      }
-      segments.push(variant('field', fieldName));
-      currentStructure = childStructure;
+      yield fieldName;
     } else {
-      throw new Error(`parsePath: unexpected character at position ${pos}: '${pathStr[pos]}'`);
+      throw new Error(`${caller}: unexpected character at position ${pos}: '${pathStr[pos]}'`);
     }
   }
-
-  return { path: segments, structure: currentStructure };
 }
 
 /**