@vzn/vx-dte 0.0.650 → 0.0.652

package/src/messages.ts

@@ -2,15 +2,7 @@
 // (the relay never reads it): orders and status only. Every task's files
 // and output go through the workspace's cache, by the keys these name.
 
-import type { CacheFacts, CapturedChunk, ExecuteResult, SandboxConfig } from '@vzn/vx'
-
-/**
- * A worker says what it holds every this many heartbeats, and a task's
- * lease is three of them. Every heartbeat (2026-10-25: the fastest, not
- * a free plan's message count): a task its worker dropped while alive
- * goes back in 15 s, not 90.
- */
-export const HELD_EVERY = 1
+import type { CacheFacts, ExecuteResult, SandboxConfig } from '@vzn/vx'
 
 /** A worker's `join` info. */
 export interface WorkerInfo {
@@ -72,15 +64,25 @@ export interface RunOrder {
   /**
    * Its `exec.sandbox`, and for a cached task the projects its key answers
    * for (workspace-relative): the worker builds the request on its own
-   * paths and OS (`sandboxRequestFor`), as its orchestrator may run another.
+   * paths and OS (`sandboxRequestFor`), as its orchestrator may run another;
+   * `reads`, the dependencies' outputs it may read (workspace-relative).
    */
-  sandbox?: { config: SandboxConfig; keyed?: string[] }
+  sandbox?: { config: SandboxConfig; keyed?: string[]; reads?: string[] }
   /** Its persistent dependencies (`ServerSpec`), `cwd` workspace-relative: the worker starts each once. */
   servers?: ServerOrder[]
   /** The runtime probes its key includes, as the orchestrator answered them: the worker's must answer the same. */
   runtime?: RuntimeOrder[]
 }
 
+/**
+ * A dependency as an order carries it: whole the first time its worker is
+ * sent it under that key, then by its task's name alone.
+ */
+export type WiredDep = DepOrder | string
+
+/** A `RunOrder` as it travels: its deps `WiredDep`s, made whole again by the worker. */
+export type SentOrder = Omit<RunOrder, 'deps'> & { deps: WiredDep[] }
+
 export interface RuntimeOrder {
   command: string
   output: string
@@ -100,18 +102,22 @@ export interface ServerOrder {
 }
 
 export type ToWorker =
-  /** Tasks that fit what it has free, each begun at once; `root` is swapped for the worker's in `env`. */
+  /**
+   * Tasks that fit what it has free: taken, each runs at once. `n` counts
+   * its batches, so its report says which it had read.
+   */
   | {
       type: 'batch'
+      n: number
       root: string
       /** `root`'s real path, as sandbox paths spell it. */
       realRoot: string
-      tasks: RunOrder[]
+      tasks: SentOrder[]
       /** The run's sandboxed tasks' `exec.sandbox`, in a worker's first batch that has a sandboxed task. */
       sandboxes?: SandboxConfig[]
     }
   /** Part of an order's `deps`, ahead of the batch whose order was too long for one frame. */
-  | { type: 'deps'; task: string; deps: DepOrder[] }
+  | { type: 'deps'; task: string; deps: WiredDep[] }
   | { type: 'cancel'; task: string }
   /**
    * It was taken into the run, under the name the run's output gives it,
@@ -146,26 +152,48 @@ export interface Load {
    * `cpu` (one that sent 3, each as a task started, read 0.6 of 2.0 used).
    */
   readonly avg?: number
+  /** When it was read, by the worker's clock: its task times are read against it. */
+  readonly at?: number
+}
+
+/** A task's times on its worker, epoch ms by the worker's clock: begun, command ended. */
+export interface Ran {
+  readonly startedAt: number
+  readonly ranAt: number
 }
 
 export type ToOrchestrator =
-  /** It began the task. */
-  | { type: 'start'; task: string; load?: Load }
-  /** Its command is done; its outputs save now, its cores are free. */
-  | { type: 'ran'; task: string; load?: Load }
-  /** Each heartbeat while it runs any: what it runs, which renews its lease on each. */
-  | { type: 'held'; running: string[]; load?: Load }
+  /**
+   * Its command is done; its outputs save now, its cores are free. Never
+   * sent alone: it rides the next message, or its `end` says it.
+   */
+  | ({ type: 'ran'; task: string; load?: Load } & Ran)
+  /**
+   * A heartbeat with nothing else said: what it runs, the last batch it
+   * read, its live load. A task of that batch or before it no longer
+   * names goes back.
+   */
+  | { type: 'report'; running: string[]; batch: number; load: Load }
+  /** Messages said at one moment, as one frame: waiting `ran`s and the event they ride. */
+  | { type: 'together'; messages: ToOrchestrator[] }
   /** It could not run a task it began, not a non-zero exit: a full disk, a failed unpack. */
-  | { type: 'fault'; task: string; reason: string }
+  | { type: 'fault'; task: string; reason: string; load?: Load }
   /** It ran the task and saved it under `key`; its output is in that entry. */
-  | { type: 'end'; task: string; key: string; result: WiredResult; load?: Load }
+  | ({
+      type: 'end'
+      task: string
+      key: string
+      result: WiredResult
+      endedAt: number
+      load?: Load
+    } & Ran)
   /**
    * Ahead of an `end` too long for one relay frame, some of its lists:
    * the `end` that follows adds its own to them. One `end` with a sandboxed
    * task's 9000 violations was over the relay's 1 MiB, and the run waited
    * for it (2026-10-25).
    */
-  | ({ type: 'part'; task: string } & Partial<Pick<WiredResult, PartList>>)
+  | ({ type: 'part'; task: string; load?: Load } & Partial<Pick<WiredResult, PartList>>)
 
 /**
  * A message's JSON in UTF-8 bytes, what a relay frame holds: counted in
@@ -175,7 +203,7 @@ export type ToOrchestrator =
 export const bytesOf = (body: unknown): number => Buffer.byteLength(JSON.stringify(body))
 
 /** The lists a long result sends ahead of its `end`, in parts. */
-export const PART_LISTS = ['violations', 'changed', 'removed', 'output'] as const
+export const PART_LISTS = ['violations', 'changed', 'removed'] as const
 export type PartList = (typeof PART_LISTS)[number]
 
 /** A result as JSON carries it: its output stays in the cache entry, and a violation's time is a string. */
@@ -187,13 +215,6 @@ export type WiredResult = Omit<ExecuteResult, 'violations' | 'outputs' | 'stdout
   removed?: string[]
   /** Dependency keys whose remote copy did not read back: this machine sends its own over them. */
   unread?: string[]
-  /**
-   * No remote took its entry's upload (too big, a 429): its files are on
-   * that worker alone, and its output comes here in `output`.
-   */
-  unshared?: true
-  /** Its output, both streams in the order written, when `unshared`. */
-  output?: CapturedChunk[]
 }
 
 /**