@elaraai/e3-types 1.0.79 → 1.0.80

package/src/repository.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * A repository's own records: the record of the forms it keeps — the release
+ * of e3 that last wrote it, and the store upgrades it has had — and its
+ * metadata: its name, its lifecycle status and when each began.
+ */
+
+import {
+  ArrayType,
+  VariantType,
+  StructType,
+  StringType,
+  DateTimeType,
+  NullType,
+  ValueTypeOf,
+} from '@elaraai/east';
+
+/**
+ * The repository record: the release of e3 that last wrote it, and the store
+ * upgrades the repository has had, which an e3 opening it reads before
+ * anything else.
+ */
+export const RepositoryRecordType = StructType({
+  /** The release of e3 that last wrote the record */
+  release: StringType,
+  /** The store upgrades the repository has had, in the order they were
+   *  applied: each by its name, with the release of e3 that applied it */
+  upgrades: ArrayType(StructType({ name: StringType, release: StringType })),
+});
+
+export type RepositoryRecord = ValueTypeOf<typeof RepositoryRecordType>;
+
+/**
+ * Where a repository is in its lifecycle.
+ */
+export const RepoStatusType = VariantType({
+  /** Being initialised */
+  creating: NullType,
+  /** Ready for use */
+  active: NullType,
+  /** A garbage collection is running */
+  gc: NullType,
+  /** Being deleted */
+  deleting: NullType,
+});
+
+export type RepoStatus = ValueTypeOf<typeof RepoStatusType>;
+
+/**
+ * A repository's metadata.
+ */
+export const RepoMetadataType = StructType({
+  /** The repository's name */
+  name: StringType,
+  /** Where it is in its lifecycle */
+  status: RepoStatusType,
+  /** When it was created */
+  createdAt: DateTimeType,
+  /** When its status last changed */
+  statusChangedAt: DateTimeType,
+});
+
+export type RepoMetadata = ValueTypeOf<typeof RepoMetadataType>;

package/src/runner.spec.ts

@@ -4,25 +4,18 @@
  */
 
 /**
- * Gating contract for {@link withRunnerVerbose}.
+ * Gating contract for {@link withRunnerLifeline}.
  *
- * `-v` is a pure runtime toggle: it is spliced into an already-built argv just
- * before spawn. These tests pin the two things that make it safe — it reaches
- * the known runtimes (which all accept `-v`) at the right argv position, and it
- * never touches a `custom` runner's user-authored command. Because it only
- * rewrites the argv (never the runner variant or any hash), it is
- * cache-irrelevant by construction.
+ * `--exit-with-parent` is a pure runtime toggle: it is spliced into an
+ * already-built argv just before spawn. These tests pin the two things that
+ * make it safe — it reaches the known runtimes at the right argv position, and
+ * it never touches a `custom` runner's user-authored command.
  */
 
 import { describe, it } from 'node:test';
 import * as assert from 'node:assert';
 import { variant } from '@elaraai/east';
-import { runnerToArgv, withRunnerLifeline, withRunnerVerbose, type RunnerValue } from './runner.js';
-
-/** A realistic fully-built argv: runner prefix + the `-i`/`-o`/`<ir>` suffix. */
-function fullArgv(runner: RunnerValue): string[] {
-  return [...runnerToArgv(runner), '-i', 'in.beast2', '-o', 'out.beast2', 'body.beast2'];
-}
+import { withRunnerLifeline, type RunnerValue } from './runner.js';
 
 const KNOWN: Array<[string, RunnerValue, string]> = [
   ['east_node', variant('east_node', { platforms: ['@elaraai/east-node-std'] }), 'east-node'],
@@ -30,100 +23,24 @@ const KNOWN: Array<[string, RunnerValue, string]> = [
   ['east_c', variant('east_c', { platforms: ['east-c-std'] }), 'east-c'],
 ];
 
-describe('withRunnerVerbose', () => {
-  for (const [tag, runner, bin] of KNOWN) {
-    it(`inserts -v after the 'run' subcommand for ${tag}`, () => {
-      const args = fullArgv(runner);
-      const out = withRunnerVerbose(runner, args, true);
-      // `[<bin>, 'run', '-v', …rest]` — position 2, ahead of -p/-i/-o and the IR.
-      assert.deepStrictEqual(out.slice(0, 3), [bin, 'run', '-v']);
-      // Exactly one -v, and the rest of the argv is preserved in order.
-      assert.strictEqual(out.filter((a) => a === '-v').length, 1);
-      assert.deepStrictEqual(out.slice(3), args.slice(2));
-      // The IR path is still last.
-      assert.strictEqual(out[out.length - 1], 'body.beast2');
-    });
-
-    it(`leaves the argv untouched when verbose is off for ${tag}`, () => {
-      const args = fullArgv(runner);
-      assert.deepStrictEqual(withRunnerVerbose(runner, args, false), args);
-      assert.deepStrictEqual(withRunnerVerbose(runner, args, undefined), args);
-    });
-  }
-
-  it('never splices -v into a custom runner (user-authored argv)', () => {
-    const runner: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
-    const args = fullArgv(runner);
-    // Even with verbose requested, a custom command is passed through verbatim —
-    // we cannot know it understands `-v`.
-    assert.deepStrictEqual(withRunnerVerbose(runner, args, true), args);
-    assert.ok(!withRunnerVerbose(runner, args, true).includes('-v'));
-  });
-
-  it('does not mutate the input argv (returns a new array)', () => {
-    const runner = variant('east_node', { platforms: ['@elaraai/east-node-std'] });
-    const args = fullArgv(runner);
-    const before = [...args];
-    withRunnerVerbose(runner, args, true);
-    assert.deepStrictEqual(args, before, 'input array must be unchanged');
-  });
-
-  it('is a no-op on a degenerate (too-short) argv rather than throwing', () => {
-    const runner = variant('east_node', { platforms: [] });
-    assert.deepStrictEqual(withRunnerVerbose(runner, ['east-node'], true), ['east-node']);
-    assert.deepStrictEqual(withRunnerVerbose(runner, [], true), []);
-  });
-
-  it('inserts -v after the merge subcommand too', () => {
-    const runner = variant('east_c', { platforms: ['east-c-std'] });
-    const args = [...runnerToArgv(runner, 'merge'), '--union', '-i', 'p0.beast2', '-o', 'out.beast2'];
-    assert.deepStrictEqual(withRunnerVerbose(runner, args, true).slice(0, 3), ['east-c', 'merge', '-v']);
-  });
-});
-
-describe('runnerToArgv', () => {
-  for (const [tag, runner, bin] of KNOWN) {
-    it(`resolves the run and merge commands of ${tag}`, () => {
-      assert.deepStrictEqual(runnerToArgv(runner).slice(0, 2), [bin, 'run']);
-      assert.deepStrictEqual(runnerToArgv(runner, 'run'), runnerToArgv(runner));
-      const merge = runnerToArgv(runner, 'merge');
-      assert.deepStrictEqual(merge.slice(0, 2), [bin, 'merge']);
-      // The platform flags follow either command unchanged.
-      assert.deepStrictEqual(merge.slice(2), runnerToArgv(runner).slice(2));
-    });
-  }
-
-  it('resolves a custom runner to its own command, and has no merge command for it', () => {
-    const runner: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
-    assert.deepStrictEqual(runnerToArgv(runner), ['uv', 'run', 'east-py', 'run']);
-    assert.throws(() => runnerToArgv(runner, 'merge'), { message: 'a custom runner has no merge command' });
-  });
-});
-
 describe('withRunnerLifeline', () => {
   for (const [tag, runner, bin] of KNOWN) {
-    it(`inserts --exit-with-parent after the subcommand for ${tag}, on run and merge`, () => {
-      const args = fullArgv(runner);
-      const out = withRunnerLifeline(runner, args);
-      assert.deepStrictEqual(out.slice(0, 3), [bin, 'run', '--exit-with-parent']);
-      assert.deepStrictEqual(out.slice(3), args.slice(2));
-      const merge = [...runnerToArgv(runner, 'merge'), '--union', '-i', 'p0.beast2', '-o', 'out.beast2'];
-      assert.deepStrictEqual(withRunnerLifeline(runner, merge).slice(0, 3), [bin, 'merge', '--exit-with-parent']);
-      // Composed with -v, both sit ahead of the flags, in either order.
-      assert.deepStrictEqual(withRunnerVerbose(runner, withRunnerLifeline(runner, args), true).slice(0, 4), [bin, 'run', '-v', '--exit-with-parent']);
+    it(`inserts --exit-with-parent after the subcommand for ${tag}`, () => {
+      const args = [bin, 'exec', 'unit.beast2', '-v'];
+      assert.deepStrictEqual(withRunnerLifeline(runner, args), [bin, 'exec', '--exit-with-parent', 'unit.beast2', '-v']);
     });
   }
 
   it('never splices the flag into a custom runner, which keeps an ignored stdin', () => {
     const runner: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
-    const args = fullArgv(runner);
+    const args = ['uv', 'run', 'east-py', 'run', '-i', 'in.beast2', '-o', 'out.beast2', 'program.beast2'];
     assert.deepStrictEqual(withRunnerLifeline(runner, args), args);
   });
 
   it('is a no-op on a degenerate argv and does not mutate its input', () => {
     const runner = variant('east_c', { platforms: [] });
     assert.deepStrictEqual(withRunnerLifeline(runner, ['east-c']), ['east-c']);
-    const args = fullArgv(runner);
+    const args = ['east-c', 'exec', 'unit.beast2'];
     const before = [...args];
     withRunnerLifeline(runner, args);
     assert.deepStrictEqual(args, before);

package/src/runner.ts

@@ -4,31 +4,25 @@
  */
 
 /**
- * Runner wire types for e3 functions.
+ * Runner wire types for e3 tasks, functions and records.
  *
- * `RunnerType` is the wire image of the SDK's `Runner` union (minus its
- * `custom` raw-argv runtime — see the security note below). It pins the
- * executable to a known runtime for every tag, so a function call can never
- * name its own executable; only platform flags vary.
- *
- * A `platforms` entry is just a `-p <name>` flag on the wire; the SDK's
- * `Platform<Known> | { custom }` distinction is authoring sugar that
- * collapses to a string.
+ * `RunnerType` is the wire image of the SDK's `Runner` union. A known-runtime
+ * tag pins the executable to one of the stock runners, which runs units through
+ * its `exec` command; `custom` names a command of the author's own.
  */
 
 import { VariantType, StructType, ArrayType, StringType, ValueTypeOf } from '@elaraai/east';
 
 /**
- * Wire representation of a runner — shared by tasks and functions
- * (symmetric: both carry `runner: RunnerType`).
- *
- * The known-runtime tags name a runtime binary; `platforms` are passed as
- * `-p` flags. `custom` carries a raw argv prefix: for functions it is the
- * executed command (the standard `-i/-o/<ir>` suffix is appended, so the
- * command must speak the runner CLI convention); for tasks it is routing
- * metadata only — a task's `commandIr` remains authoritative for execution.
- * Package authors can already execute arbitrary commands via custom tasks,
- * so `custom` grants no capability that tasks don't have.
+ * Wire representation of a runner — shared by tasks, functions and records.
+ *
+ * A known-runtime tag names a stock runner, and `platforms` names the platform
+ * packages the units it runs load. `custom` carries a command, which e3 runs
+ * with the arguments of a stock runner's `run`: `-i` for each input, `-o` for
+ * the output, then the program's file. A custom task's body is its own
+ * command, and its runner's is empty. Package authors can already execute
+ * arbitrary commands via custom tasks, so `custom` grants no capability that
+ * tasks don't have.
  */
 export const RunnerType = VariantType({
   east_node: StructType({ platforms: ArrayType(StringType) }),
@@ -40,63 +34,6 @@ export type RunnerType = typeof RunnerType;
 
 export type RunnerValue = ValueTypeOf<typeof RunnerType>;
 
-function flags(platforms: string[]): string[] {
-  return platforms.flatMap((p) => ['-p', p]);
-}
-
-/**
- * Resolve a {@link RunnerType} value to the argv prefix of one of its
- * commands (the wire-value analogue of the SDK's `runnerToCommand`): `run`,
- * the default — `[<bin>, 'run', -p…]` — or `merge`, the blob merge every
- * stock runner ships — `[<bin>, 'merge', -p…]`, the fan-in of a partitioned
- * task's keyed partials (issue #770). Lives in e3-types so both e3-core
- * (local) and the cloud execution kernel import the one resolver.
- *
- * Variant tags use underscores (`east_node`) mapped to the binary name
- * (`east-node`) here. A `custom` runner's command is its `run`; it has no
- * merge command.
- *
- * @param r - the runner
- * @param command - the runner command, `run` by default
- * @returns the argv prefix
- * @throws {Error} When `merge` is asked of a custom runner.
- */
-export function runnerToArgv(r: RunnerValue, command: 'run' | 'merge' = 'run'): string[] {
-  switch (r.type) {
-    case 'east_node': return ['east-node', command, ...flags(r.value.platforms)];
-    case 'east_py':   return ['east-py',   command, ...flags(r.value.platforms)];
-    case 'east_c':    return ['east-c',    command, ...flags(r.value.platforms)];
-    case 'custom':
-      if (command !== 'run') throw new Error(`a custom runner has no ${command} command`);
-      return [...r.value.command];
-  }
-}
-
-/**
- * Insert the runner's `-v/--verbose` flag into a fully-built argv, for the
- * known runtimes only.
- *
- * All three known runners (`east-node`/`east-py`/`east-c`, `run` and `merge`)
- * accept `-v` among their options and print timing/perf detail to stderr; a
- * `custom` runner's argv is user-authored, so a flag is never spliced into
- * it. A known-runtime argv always starts `[<bin>, <command>, …]` (see
- * {@link runnerToArgv} and the SDK's `runnerToCommand`), so `-v` goes at
- * index 2 — ahead of the `-p`/`-i`/`-o` flags and the trailing IR path.
- *
- * This is a pure **runtime** toggle: it is applied to the *evaluated* argv
- * immediately before spawn and never touches the task's `commandIr`, the
- * {@link RunnerType}, or any hash — so it cannot affect caching.
- *
- * @param runner - the runner the argv was built for (gates the injection)
- * @param args - the fully-built argv (runner prefix + `-i`/`-o`/`<ir>` suffix)
- * @param verbose - when true, request the runner's verbose output
- * @returns the argv, with `-v` inserted for known runtimes when verbose
- */
-export function withRunnerVerbose(runner: RunnerValue, args: string[], verbose?: boolean): string[] {
-  if (!verbose || runner.type === 'custom' || args.length < 2) return args;
-  return [...args.slice(0, 2), '-v', ...args.slice(2)];
-}
-
 /**
  * Insert the runner's `--exit-with-parent` flag into a fully-built argv, for
  * the known runtimes only — the stdin lifeline (issue #770).
@@ -104,10 +41,9 @@ export function withRunnerVerbose(runner: RunnerValue, args: string[], verbose?:
  * A stock runner given the flag and a stdin pipe its parent never writes to
  * exits as soon as the pipe reaches end of file: when the parent dies. A
  * `custom` runner's argv is user-authored, so the flag is never spliced into
- * it, and it keeps an ignored stdin. Like {@link withRunnerVerbose} the flag
- * goes at index 2, after `[<bin>, <command>]`, and is a pure runtime toggle
- * applied just before spawn — never part of the task's `commandIr` or any
- * hash.
+ * it, and it keeps an ignored stdin. The flag goes at index 2, after
+ * `[<bin>, <command>]`, and is a pure runtime toggle applied just before
+ * spawn — never part of the task object or any hash.
  *
  * @param runner - the runner the argv was built for (gates the injection)
  * @param args - the fully-built argv

package/src/structure.ts

@@ -61,14 +61,6 @@ export type StructureType = typeof StructureType;
 
 export type Structure = ValueTypeOf<typeof StructureType>;
 
-// Backwards compatibility alias
-/** @deprecated Use StructureType instead */
-export const DatasetSchemaType = StructureType;
-/** @deprecated Use Structure instead */
-export type DatasetSchemaType = StructureType;
-/** @deprecated Use Structure instead */
-export type DatasetSchema = Structure;
-
 /**
  * Path segment for navigating data trees.
  *

package/src/task.spec.ts

@@ -4,205 +4,84 @@
  */
 
 /**
- * Partition and stream task wire helpers (issue #770): the partition
- * metadata's merge fields and its triple decoder, the stream metadata's
- * `merge` mode and its dual decoder, the partition plan round trip, and the
- * `by` projection shapes the orchestrator evaluates by reading key fields
- * instead of compiling the projection.
+ * Task object wire: the typed task object's round trip and its refusals.
  */
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ArrayType, BlobType, BooleanType, East, IntegerType, OptionType, StringType, StructType, compareFor, encodeBeast2For, encodeEastIR, isTypeValueEqual, none, some, toEastTypeValue, variant } from '@elaraai/east';
-import type { FunctionIR } from '@elaraai/east';
+import { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, encodeBeast2For, none, some, variant } from '@elaraai/east';
 import {
-  decodePartitionPlan,
-  decodePartitionTaskMetadata,
-  decodeStreamTaskMetadata,
-  encodePartitionPlan,
-  encodePartitionTaskMetadata,
-  encodeStreamTaskMetadata,
-  partitionProjectionShape,
-  projectKey,
-  projectedKeyType,
-  type PartitionPlan,
-  type PartitionTaskMetadata,
-  type ProjectionShape,
-  type StreamTaskMetadata,
+  TASK_OBJECT_KIND,
+  TaskObjectType,
+  decodeTaskObject,
+  type TaskObject,
 } from './task.js';
-import { mergeCommandIr } from './stream.js';
-
-describe('PartitionTaskMetadataType', () => {
-  const mergeIr = encodeEastIR(East.function([IntegerType, StringType, StringType], StringType, (_$, _key, acc, value) => acc.concat(value)).toIR());
-  const mergeCommand = encodeEastIR(mergeCommandIr(variant('east_c', { platforms: ['east-c-std'] }), 'function'));
-
-  /** The metadata with every blob as a plain Uint8Array — the decoder hands
-   *  back Buffers, whose prototype strict deep equality would reject. */
-  function plain(meta: PartitionTaskMetadata): PartitionTaskMetadata {
-    const blob = (option: { type: string; value: unknown }) =>
-      option.type === 'some' ? some(new Uint8Array(option.value as Uint8Array)) : none;
-    return { ...meta, by: blob(meta.by), combine: blob(meta.combine), merge: blob(meta.merge), mergeCommand: blob(meta.mergeCommand) };
-  }
-
-  it('round-trips the merge fields and the merge command', () => {
-    const meta: PartitionTaskMetadata = {
-      partitions: 1n, by: none, combine: none, targetPartitionBytes: 1024n,
-      merge: some(mergeIr), mergeSets: false, mergeCommand: some(mergeCommand),
-    };
-    assert.deepEqual(plain(decodePartitionTaskMetadata(encodePartitionTaskMetadata(meta))), meta);
-  });
-
-  it('decodes v1.0.77 metadata, exported before merge commands, with mergeCommand none', () => {
-    const shape = StructType({
-      partitions: IntegerType, by: OptionType(BlobType), combine: OptionType(BlobType), targetPartitionBytes: IntegerType,
-      merge: OptionType(BlobType), mergeSets: BooleanType,
+import { RunnerType } from './runner.js';
+import { TreePathType } from './structure.js';
+
+describe('TaskObjectType', () => {
+  const sales = [variant('field', 'inputs'), variant('field', 'sales')];
+  const rates = [variant('field', 'inputs'), variant('field', 'rates')];
+  const totals = [variant('field', 'tasks'), variant('field', 'totals'), variant('field', 'output')];
+  const base: TaskObject = {
+    kind: TASK_OBJECT_KIND,
+    body: variant('east', { program: 'a'.repeat(64) }),
+    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+    inputs: [{ path: sales, partition: none }],
+    output: { path: totals, kind: variant('value', null) },
+    role: variant('data', null),
+    environment: none,
+  };
+
+  it('round-trips every body, output kind and role', () => {
+    const tasks: TaskObject[] = [
+      base,
+      {
+        ...base,
+        body: variant('command', { commandIr: 'b'.repeat(64) }),
+        runner: variant('custom', { command: [] }),
+        environment: some('c'.repeat(64)),
+      },
+      {
+        ...base,
+        inputs: [{ path: sales, partition: some({ by: ['account', 'at.day'] }) }, { path: rates, partition: none }],
+        output: { path: totals, kind: variant('dict', { merge: some('d'.repeat(64)) }) },
+      },
+      { ...base, output: { path: totals, kind: variant('fold', { zero: 'e'.repeat(64), combine: 'f'.repeat(64) }) } },
+      { ...base, output: { path: totals, kind: variant('set', null) } },
+      { ...base, role: variant('ui', { paths: [sales], functions: ['forecast'], records: ['plans'], pages: [rates] }) },
+    ];
+    const encode = encodeBeast2For(TaskObjectType);
+    for (const original of tasks) assert.deepEqual(decodeTaskObject(encode(original)), original);
+  });
+
+  it('refuses a task object an older SDK exported, saying to re-export the package', () => {
+    const PreCutoverTaskObjectType = StructType({
+      commandIr: StringType,
+      inputs: ArrayType(TreePathType),
+      output: TreePathType,
+      kind: OptionType(StringType),
+      metadata: OptionType(BlobType),
+      runner: RunnerType,
+      environment: OptionType(StringType),
     });
-    const legacy = encodeBeast2For(shape)({ partitions: 2n, by: none, combine: none, targetPartitionBytes: 512n, merge: some(mergeIr), mergeSets: false });
-    assert.deepEqual(plain(decodePartitionTaskMetadata(legacy)), {
-      partitions: 2n, by: none, combine: none, targetPartitionBytes: 512n, merge: some(mergeIr), mergeSets: false, mergeCommand: none,
+    const older = encodeBeast2For(PreCutoverTaskObjectType)({
+      commandIr: 'a'.repeat(64),
+      inputs: [[variant('field', 'tasks'), variant('field', 'totals'), variant('field', 'function_ir')], sales],
+      output: totals,
+      kind: none,
+      metadata: none,
+      runner: variant('east_node', { platforms: [] }),
+      environment: none,
     });
+    assert.throws(() => decodeTaskObject(older), /exported by an older e3 SDK — re-export it with the current one/);
   });
 
-  it('decodes metadata exported before merge assembly with every merge field off', () => {
-    const shape = StructType({ partitions: IntegerType, by: OptionType(BlobType), combine: OptionType(BlobType), targetPartitionBytes: IntegerType });
-    const legacy = encodeBeast2For(shape)({ partitions: 1n, by: none, combine: none, targetPartitionBytes: 256n });
-    assert.deepEqual(decodePartitionTaskMetadata(legacy), {
-      partitions: 1n, by: none, combine: none, targetPartitionBytes: 256n, merge: none, mergeSets: false, mergeCommand: none,
-    });
-  });
-
-  it('throws for bytes of no known metadata shape', () => {
-    assert.throws(() => decodePartitionTaskMetadata(encodeBeast2For(IntegerType)(7n)));
-  });
-});
-
-describe('StreamTaskMetadataType', () => {
-  it('round-trips the merge mode', () => {
-    const meta: StreamTaskMetadata = { stream: true, emit: 'dict', merge: 'function' };
-    assert.deepEqual(decodeStreamTaskMetadata(encodeStreamTaskMetadata(meta)), meta);
-  });
-
-  it('decodes metadata exported before merge modes as merge none', () => {
-    const legacy = encodeBeast2For(StructType({ stream: BooleanType, emit: StringType }))({ stream: false, emit: 'set' });
-    assert.deepEqual(decodeStreamTaskMetadata(legacy), { stream: false, emit: 'set', merge: 'none' });
-  });
-
-  it('throws for bytes of no known metadata shape', () => {
-    assert.throws(() => decodeStreamTaskMetadata(encodeBeast2For(IntegerType)(7n)));
-  });
-});
-
-describe('PartitionPlanType', () => {
-  it('round-trips a plan, before and after its slices are carved and its merge ranges planned', () => {
-    const plan: PartitionPlan = {
-      partitions: ['a'.repeat(64), 'b'.repeat(64)],
-      boundaries: [0n, 4n, 9n],
-      splits: [[{ seg: 0n, offset: 0n }, { seg: 3n, offset: 17n }, { seg: 8n, offset: 0n }, { seg: 12n, offset: 0n }]],
-      slices: [],
-      merges: [],
-    };
-    assert.deepEqual(decodePartitionPlan(encodePartitionPlan(plan)), plan);
-
-    const carved: PartitionPlan = { ...plan, slices: [['c'.repeat(64), 'd'.repeat(64), 'e'.repeat(64)], ['f'.repeat(64), '0'.repeat(64), '1'.repeat(64)]] };
-    assert.deepEqual(decodePartitionPlan(encodePartitionPlan(carved)), carved);
-
-    const merged: PartitionPlan = {
-      ...carved,
-      merges: [{ partials: ['2'.repeat(64), '3'.repeat(64)], ranges: ['4'.repeat(64), '5'.repeat(64)] }],
-    };
-    assert.deepEqual(decodePartitionPlan(encodePartitionPlan(merged)), merged);
-  });
-
-  it('decodes a plan recorded before merge ranges existed, with none', () => {
-    // The pre-`merges` wire shape, encoded directly.
-    const PreMergesPlanType = StructType({
-      partitions: ArrayType(StringType),
-      boundaries: ArrayType(IntegerType),
-      splits: ArrayType(ArrayType(StructType({ seg: IntegerType, offset: IntegerType }))),
-      slices: ArrayType(ArrayType(StringType)),
-    });
-    const older = encodeBeast2For(PreMergesPlanType)({
-      partitions: ['a'.repeat(64)],
-      boundaries: [0n, 2n],
-      splits: [],
-      slices: [['b'.repeat(64), 'c'.repeat(64)]],
-    });
-    assert.deepEqual(decodePartitionPlan(older), {
-      partitions: ['a'.repeat(64)],
-      boundaries: [0n, 2n],
-      splits: [],
-      slices: [['b'.repeat(64), 'c'.repeat(64)]],
-      merges: [],
-    });
-  });
-});
-
-describe('partition projections', () => {
-  const AtType = StructType({ day: IntegerType, hour: IntegerType });
-  const KeyType = StructType({ region: StringType, at: AtType, sku: StringType });
-  const keyTypeValue = toEastTypeValue(KeyType);
-  type Key = { region: string; at: { day: bigint; hour: bigint }; sku: string };
-  const keys: Key[] = [
-    { region: 'eu', at: { day: 2n, hour: 7n }, sku: 'b' },
-    { region: 'eu', at: { day: 2n, hour: 7n }, sku: 'a' },
-    { region: 'eu', at: { day: 1n, hour: 9n }, sku: 'c' },
-    { region: 'ap', at: { day: 3n, hour: 0n }, sku: 'a' },
-  ];
-
-  /** A `by` projection over the key, compiled, and its shape. */
-  function projection(by: ($: any, key: any) => any): { compiled: (key: Key) => unknown; shape: ProjectionShape | null } {
-    const bundle = East.function([KeyType], undefined, by).toIR();
-    return {
-      compiled: bundle.compile([]) as (key: Key) => unknown,
-      shape: partitionProjectionShape(bundle.ir as FunctionIR),
-    };
-  }
-
-  /** Whether two comparisons agree in sign. */
-  const sameSign = (a: number, b: number): boolean => Math.sign(a) === Math.sign(b);
-
-  it('reads the identity, a leading field, a struct literal of leading fields and a nested first-field path', () => {
-    assert.deepEqual(projection(($, key) => key).shape, { kind: 'fields', names: [] });
-    assert.deepEqual(projection(($, key) => key.region).shape, { kind: 'fields', names: ['region'] });
-    assert.deepEqual(projection(($, key) => ({ region: key.region, at: key.at })).shape, { kind: 'fields', names: ['region', 'at'] });
-    assert.deepEqual(projection(($, key) => key.at.day).shape, { kind: 'path', names: ['at', 'day'] });
-  });
-
-  it('returns null for a projection that computes', () => {
-    assert.equal(projection(($, key) => key.region.concat('-')).shape, null);
-  });
-
-  it('projects the identity to the key itself', () => {
-    const shape: ProjectionShape = { kind: 'fields', names: [] };
-    assert.ok(isTypeValueEqual(projectedKeyType(shape, keyTypeValue), keyTypeValue));
-    assert.equal(projectKey(shape, keys[0]), keys[0]);
-  });
-
-  it('projects a struct literal of leading fields exactly as the compiled projection does', () => {
-    const { compiled, shape } = projection(($, key) => ({ region: key.region, at: key.at }));
-    assert.ok(isTypeValueEqual(projectedKeyType(shape!, keyTypeValue), toEastTypeValue(StructType({ region: StringType, at: AtType }))));
-    for (const key of keys) assert.deepEqual(projectKey(shape!, key), compiled(key));
-  });
-
-  it('projects a nested first-field path exactly as the compiled projection does', () => {
-    const { compiled, shape } = projection(($, key) => key.at.day);
-    assert.ok(isTypeValueEqual(projectedKeyType(shape!, keyTypeValue), toEastTypeValue(IntegerType)));
-    for (const key of keys) assert.equal(projectKey(shape!, key), compiled(key));
-  });
-
-  it('orders a single leading field as the compiled projection does', () => {
-    const { compiled, shape } = projection(($, key) => key.region);
-    const cmp = compareFor(projectedKeyType(shape!, keyTypeValue) as any) as (a: unknown, b: unknown) => number;
-    const cmpCompiled = compareFor(StringType);
-    for (const a of keys) {
-      for (const b of keys) {
-        assert.ok(sameSign(cmp(projectKey(shape!, a), projectKey(shape!, b)), cmpCompiled(compiled(a) as string, compiled(b) as string)));
-      }
-    }
+  it('refuses an object of the task shape that carries another kind tag', () => {
+    assert.throws(() => decodeTaskObject(encodeBeast2For(TaskObjectType)({ ...base, kind: '$plan' })), /its kind is '\$plan', not '\$task'/);
   });
 
-  it('throws when a shape reads a field the key type does not have', () => {
-    assert.throws(() => projectedKeyType({ kind: 'fields', names: ['store'] }, keyTypeValue), /field 'store'/);
-    assert.throws(() => projectedKeyType({ kind: 'path', names: ['at', 'minute'] }, keyTypeValue), /field 'minute'/);
+  it('throws for bytes of no known task shape', () => {
+    assert.throws(() => decodeTaskObject(encodeBeast2For(IntegerType)(7n)), /re-export/);
   });
 });