@hotmeshio/long-tail 0.28.0 → 0.28.2

package/build/services/machines/gateway/plan-machine.js

@@ -36,7 +36,10 @@ function planMachineMessage(state, parsed, env, dispatchTtlMs) {
 function planByKind(state, m, parsed, env, b, ttl) {
     switch (parsed.kind) {
         case protocol_1.MESSAGE_KIND.REPLY:
-            return ack([{ kind: 'settleReply', cmdId: b.cmdId, status: b.status, reason: b.reason, ...(typeof b.code === 'string' ? { code: b.code } : {}) }]);
+            return ack([{
+                    kind: 'settleReply', cmdId: b.cmdId, status: b.status, reason: b.reason,
+                    ...(typeof b.code === 'string' ? { code: b.code } : {}), ...(b.preparing === true ? { preparing: true } : {}),
+                }]);
         case protocol_1.MESSAGE_KIND.JOB:
             return planJob(state, m, b, env?.at, ttl);
         case protocol_1.MESSAGE_KIND.ALARM:
@@ -191,7 +194,9 @@ function planAlarm(state, parsed, alarmId, env) {
                 payload: { decision: contracts_1.DECISION.CLEARED, clearedBy: b.clearedBy ?? null, note: `cleared at ${m}${b.clearedBy ? ` by ${b.clearedBy}` : ''}` },
             }]);
     }
-    if (!protocol_1.STOPPING_LEVELS.includes(b.level))
+    // A stopping level needs a person; so does any alarm the machine flags, at the level it said.
+    const stopping = protocol_1.STOPPING_LEVELS.includes(b.level);
+    if (!stopping && b.needsPerson !== true)
         return ack();
     const known = state.alarms.get(key);
     if (known && (!known.raisedAt || !b.raisedAt || known.raisedAt === b.raisedAt))
@@ -201,7 +206,7 @@ function planAlarm(state, parsed, alarmId, env) {
         : [];
     const track = { machineId: m, alarmId, raisedAt: b.raisedAt, level: b.level, open: true };
     state.alarms.set(key, track);
-    return ack([...superseded, ...(0, lifecycle_1.notePause)(state, track, b), {
+    return ack([...superseded, ...(stopping ? (0, lifecycle_1.notePause)(state, track, b) : []), {
             kind: 'createAlarmRow', machineId: m, alarmId,
             row: {
                 type: contracts_1.ROW_TYPE.ALARM, subtype: b.level, role: contracts_1.LINE_ROLE.OPERATOR, priority: b.level === protocol_1.LEVEL.EMERGENCY ? 1 : 2,
@@ -254,27 +259,37 @@ function planPresence(state, m, b) {
     }
     return ack(actions);
 }
-/** A new boot id means the machine restarted and lost its queue: send its open dispatches again. */
+/**
+ * A new boot id means the machine restarted and lost its queue: send its open
+ * dispatches again, and the jobs it had ready for units it still holds, from
+ * the rows that sent them. A lost job nothing is remembered for is logged.
+ */
 function planSnapshot(state, m, b, ttl) {
     const link = state.link(m);
     if (b.software)
         link.software = b.software;
     const jobIds = Array.isArray(b.jobs) ? b.jobs.map((j) => j?.jobId).filter((id) => typeof id === 'string') : [];
+    // A snapshot without a boot id says nothing about restarts.
+    const rebooted = typeof b.bootId === 'string' && !!link.bootId && link.bootId !== b.bootId;
+    const held = new Set(jobIds);
+    const lost = rebooted ? state.lostAfterReboot(m, held) : { resend: [], unknown: [] };
     if (Array.isArray(b.jobs)) {
-        state.keepHeld(m, new Set(jobIds));
+        state.keepHeld(m, new Set([...jobIds, ...lost.resend.map((l) => l.jobId)]));
         link.jobs = b.jobs;
     }
+    if (typeof b.bootId === 'string')
+        link.bootId = b.bootId;
     const fresh = !state.retainedAlarms && !state.readingRetained && Array.isArray(b.alarms);
     const cleared = fresh ? alarmsNoLongerListed(state, m, b.alarms) : [];
     const answer = { kind: 'settleSnapshot', machineId: m, jobIds };
-    const previous = link.bootId;
-    link.bootId = b.bootId;
-    if (!previous || previous === b.bootId)
+    if (!rebooted)
         return ack([...cleared, answer]);
-    const held = new Set(jobIds);
     const missing = (r) => (0, jobs_1.dispatchJobs)(r.jobId, r.units, state.unitsPerDispatch).some((j) => !held.has(j.jobId));
-    const lost = state.open().filter((r) => r.toMachine === m && r.dispatch === state_1.DISPATCH_STATE.ACCEPTED && missing(r));
-    return ack([...cleared, answer, ...lost.map((r) => (0, pacing_1.dispatchAction)(r, m, ttl))]);
+    const open = state.open().filter((r) => r.toMachine === m && r.dispatch === state_1.DISPATCH_STATE.ACCEPTED && missing(r));
+    const rows = new Map(lost.resend.map((l) => [l.row.id, l.row]));
+    const again = [...rows.values()].map((r) => ({ ...(0, pacing_1.dispatchAction)(r, m, ttl), ended: true }));
+    const unknown = lost.unknown.length ? [{ kind: 'unrecoverable', machineId: m, jobs: lost.unknown }] : [];
+    return ack([...cleared, answer, ...open.map((r) => (0, pacing_1.dispatchAction)(r, m, ttl)), ...again, ...unknown]);
 }
 /** Alarm rows for `m` whose alarm its snapshot no longer lists: they cleared at the machine. */
 function alarmsNoLongerListed(state, m, listed) {

package/build/services/machines/gateway/plan-shared.d.ts

@@ -5,9 +5,11 @@ import { type GatewayState, type HandoffRow } from './state';
 /** A cancel for each job a handoff's units became at `machineId`, or for those `keep` leaves out. */
 export declare function cancelJobs(state: GatewayState, row: HandoffRow, machineId: string, jobId: string, tag?: string, keep?: (job: DispatchJob) => boolean): Action[];
 /**
- * Withdraw a dispatch that may still sit in the receiver's queue. A job some
- * of whose units already reached the receiver is under way: it stays, and
- * what happens to it is the workflow's next decision (a machine-command row).
+ * Withdraw a dispatch that may still sit in the receiver's queue: one sent or
+ * accepted. A job that never went out (the row waiting for room, or for its
+ * units to arrive) leaves the receiver nothing to withdraw. A job some of whose
+ * units already reached the receiver is under way: it stays, and what happens
+ * to it is the workflow's next decision (a machine-command row).
  */
 export declare function cancelDispatch(state: GatewayState, row: HandoffRow): Action[];
 /**

package/build/services/machines/gateway/plan-shared.js

@@ -14,13 +14,15 @@ function cancelJobs(state, row, machineId, jobId, tag = '', keep = () => false)
     }));
 }
 /**
- * Withdraw a dispatch that may still sit in the receiver's queue. A job some
- * of whose units already reached the receiver is under way: it stays, and
- * what happens to it is the workflow's next decision (a machine-command row).
+ * Withdraw a dispatch that may still sit in the receiver's queue: one sent or
+ * accepted. A job that never went out (the row waiting for room, or for its
+ * units to arrive) leaves the receiver nothing to withdraw. A job some of whose
+ * units already reached the receiver is under way: it stays, and what happens
+ * to it is the workflow's next decision (a machine-command row).
  */
 function cancelDispatch(state, row) {
     const to = row.toMachine;
-    if (!to || row.dispatch === state_1.DISPATCH_STATE.NONE || row.dispatch === state_1.DISPATCH_STATE.REFUSED)
+    if (!to || (row.dispatch !== state_1.DISPATCH_STATE.PENDING && row.dispatch !== state_1.DISPATCH_STATE.ACCEPTED))
         return [];
     return cancelJobs(state, row, to, row.jobId, '', (job) => job.units.some((u) => state.heldJob(to, u.unitId) === job.jobId));
 }

package/build/services/machines/gateway/reply-waiter.d.ts

@@ -10,6 +10,8 @@ export interface CommandReply {
     reason: string;
     /** The machine's structured code for the outcome, when its reply carried one. */
     code?: string;
+    /** An acceptance the machine will follow with `completed` or `failed` once the job is prepared. */
+    preparing?: boolean;
 }
 /** The jobs a machine reports holding, queued or in work. */
 export type HeldJobs = Set<string>;

package/build/services/machines/gateway/state.d.ts

@@ -35,6 +35,8 @@ export interface HandoffRow extends HandoffFacets {
     trace?: TraceEntry[];
     /** Each unit's arrival event, as its receiver reported it (dispatch on arrival). */
     arrivals?: Record<string, Record<string, any>>;
+    /** Dispatch commands accepted as preparing; on arrival dispatch the row is received once each is ready. */
+    awaitingReady?: Set<string>;
     /** Lifecycle item keys already on the row (lifecycle.ts). */
     noted?: string[];
     /** Parked with a limit on its items, which lifecycle notes must never use up. */
@@ -98,6 +100,10 @@ export declare class GatewayState {
     holdDispatch: boolean;
     /** Units at each machine that arrived and have not left: machine → unit → job. */
     private held;
+    /** Jobs sent and taken, by machine: job → the row that sent it, kept while the machine holds the job's units. */
+    private sentJobs;
+    /** Jobs whose units left each machine since its last snapshot: they ended, a snapshot without them lost nothing. */
+    private endedJobs;
     private openRows;
     private closedRows;
     readonly alarms: Map<string, AlarmTrack>;
@@ -122,6 +128,8 @@ export declare class GatewayState {
     private strangers;
     index(row: HandoffRow): void;
     get(id: string): HandoffRow | undefined;
+    /** A row that ended, while the gateway still remembers it. */
+    closedRow(id: string): HandoffRow | undefined;
     close(id: string, ended?: RowEnd): HandoffRow | undefined;
     isClosed(id: string): boolean;
     open(): HandoffRow[];
@@ -130,11 +138,26 @@ export declare class GatewayState {
     closedFor(unitId: string, pred: (r: HandoffRow) => boolean): HandoffRow | undefined;
     hold(machineId: string, unitId: string, jobId: string): void;
     letGo(machineId: string, unitId: string): void;
+    /** A job the machine took, remembered by its row while the machine holds the job's units. */
+    rememberSent(machineId: string, jobId: string, rowId: string): void;
+    /**
+     * After a restart, the jobs the machine lost: those its units are held under
+     * or its last snapshot listed, that the new snapshot lacks and no open row
+     * will send again. `resend` names the rows remembered for them; `unknown`
+     * the jobs nothing is remembered for.
+     */
+    lostAfterReboot(machineId: string, listed: Set<string>): {
+        resend: {
+            jobId: string;
+            row: HandoffRow;
+        }[];
+        unknown: string[];
+    };
     /** The job a unit arrived under at `machineId`, while it is still there. */
     heldJob(machineId: string, unitId: string): string | undefined;
     heldAt(machineId: string): string[];
     heldUnitsAt(machineId: string): HeldUnit[];
-    /** Keep only units whose job the machine still lists (its snapshot). */
+    /** Keep only units whose job the machine still lists (its snapshot); a job it no longer lists is over. */
     keepHeld(machineId: string, jobIds: Set<string>): void;
     /** Keep a sender's finished record until its row is known, so an arrival cannot close the row without it. */
     rememberFinish(machineId: string, unitId: string, body: Record<string, any>): void;

package/build/services/machines/gateway/state.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayState = exports.ROW_END = exports.DISPATCH_STATE = void 0;
+const jobs_1 = require("./jobs");
 const project_1 = require("./project");
 const trace_1 = require("./trace");
 /**
@@ -44,6 +45,10 @@ class GatewayState {
         this.holdDispatch = false;
         /** Units at each machine that arrived and have not left: machine → unit → job. */
         this.held = new Map();
+        /** Jobs sent and taken, by machine: job → the row that sent it, kept while the machine holds the job's units. */
+        this.sentJobs = new Map();
+        /** Jobs whose units left each machine since its last snapshot: they ended, a snapshot without them lost nothing. */
+        this.endedJobs = new Map();
         this.openRows = new Map();
         this.closedRows = new Map();
         this.alarms = new Map();
@@ -75,13 +80,17 @@ class GatewayState {
         this.openRows.set(row.id, existing
             ? {
                 ...row, dispatch: existing.dispatch, trace: (0, trace_1.mergeTrace)(row.trace, existing.trace), arrivals: existing.arrivals,
-                dueAt: existing.dueAt, noted: existing.noted ?? row.noted,
+                dueAt: existing.dueAt, noted: existing.noted ?? row.noted, awaitingReady: existing.awaitingReady,
             }
             : row);
     }
     get(id) {
         return this.openRows.get(id);
     }
+    /** A row that ended, while the gateway still remembers it. */
+    closedRow(id) {
+        return this.closedRows.get(id);
+    }
     close(id, ended = exports.ROW_END.RESOLVED) {
         const row = this.openRows.get(id);
         if (!row)
@@ -115,7 +124,53 @@ class GatewayState {
         this.held.get(machineId).set(unitId, jobId);
     }
     letGo(machineId, unitId) {
-        this.held.get(machineId)?.delete(unitId);
+        const units = this.held.get(machineId);
+        const jobId = units?.get(unitId);
+        units?.delete(unitId);
+        if (jobId === undefined || [...units.values()].includes(jobId))
+            return;
+        this.sentJobs.get(machineId)?.delete(jobId);
+        if (!this.endedJobs.has(machineId))
+            this.endedJobs.set(machineId, new Set());
+        this.endedJobs.get(machineId).add(jobId);
+    }
+    /** A job the machine took, remembered by its row while the machine holds the job's units. */
+    rememberSent(machineId, jobId, rowId) {
+        if (!this.sentJobs.has(machineId))
+            this.sentJobs.set(machineId, new Map());
+        this.sentJobs.get(machineId).set(jobId, rowId);
+    }
+    /**
+     * After a restart, the jobs the machine lost: those its units are held under
+     * or its last snapshot listed, that the new snapshot lacks and no open row
+     * will send again. `resend` names the rows remembered for them; `unknown`
+     * the jobs nothing is remembered for.
+     */
+    lostAfterReboot(machineId, listed) {
+        const link = this.links.get(machineId);
+        const before = new Set(this.heldAt(machineId));
+        for (const job of link?.jobs ?? [])
+            if (typeof job?.jobId === 'string')
+                before.add(job.jobId);
+        const ended = this.endedJobs.get(machineId) ?? new Set();
+        const sendsAgain = new Set();
+        for (const row of this.openRows.values()) {
+            if (row.toMachine === machineId)
+                for (const job of (0, jobs_1.dispatchJobs)(row.jobId, row.units, this.unitsPerDispatch))
+                    sendsAgain.add(job.jobId);
+        }
+        const resend = [];
+        const unknown = [];
+        for (const jobId of before) {
+            if (listed.has(jobId) || ended.has(jobId) || sendsAgain.has(jobId))
+                continue;
+            const row = this.closedRows.get(this.sentJobs.get(machineId)?.get(jobId) ?? '');
+            if (row)
+                resend.push({ jobId, row });
+            else
+                unknown.push(jobId);
+        }
+        return { resend, unknown };
     }
     /** The job a unit arrived under at `machineId`, while it is still there. */
     heldJob(machineId, unitId) {
@@ -127,14 +182,18 @@ class GatewayState {
     heldUnitsAt(machineId) {
         return [...(this.held.get(machineId)?.entries() ?? [])].map(([unitId, jobId]) => ({ unitId, jobId }));
     }
-    /** Keep only units whose job the machine still lists (its snapshot). */
+    /** Keep only units whose job the machine still lists (its snapshot); a job it no longer lists is over. */
     keepHeld(machineId, jobIds) {
+        this.endedJobs.delete(machineId);
         const units = this.held.get(machineId);
         if (!units)
             return;
-        for (const [unitId, jobId] of units)
-            if (!jobIds.has(jobId))
-                units.delete(unitId);
+        for (const [unitId, jobId] of units) {
+            if (jobIds.has(jobId))
+                continue;
+            units.delete(unitId);
+            this.sentJobs.get(machineId)?.delete(jobId);
+        }
     }
     /** Keep a sender's finished record until its row is known, so an arrival cannot close the row without it. */
     rememberFinish(machineId, unitId, body) {
@@ -268,6 +327,8 @@ class GatewayState {
             retainedAlarms: this.retainedAlarms, readingRetained: this.readingRetained, takenAt: this.takenAt, progressStep: this.progressStep, holdDispatch: this.holdDispatch,
         });
         copyInto(this.held, copy.held, (units) => new Map(units));
+        copyInto(this.sentJobs, copy.sentJobs, (jobs) => new Map(jobs));
+        copyInto(this.endedJobs, copy.endedJobs, (jobs) => new Set(jobs));
         copyInto(this.openRows, copy.openRows, (row) => ({ ...row, units: [...row.units], ...(row.noted ? { noted: [...row.noted] } : {}) }));
         copyInto(this.closedRows, copy.closedRows, (row) => ({ ...row }));
         copyInto(this.alarms, copy.alarms, (track) => ({ ...track, ...(track.noted ? { noted: [...track.noted] } : {}) }));

package/build/services/machines/gateway/wire-window.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The last wire events of a line, kept by its leader so a client reads the
+ * tape over HTTP instead of the event stream. A ring of a fixed size; reads
+ * are newest first and may narrow by machine, direction, kind and time.
+ */
+import type { WireDirection, WireEvent, WireKind, WireWindowQuery } from '../../../types/machines-view';
+export declare const DEFAULT_WIRE_WINDOW = 500;
+export declare const MAX_WIRE_PAGE = 500;
+export declare class WireWindow {
+    readonly size: number;
+    private readonly events;
+    private head;
+    private count;
+    constructor(size?: number);
+    push(event: WireEvent): void;
+    /** Newest first, narrowed by the query, at most `limit` (the window's size when absent). */
+    read(query?: WireWindowQuery): WireEvent[];
+    get length(): number;
+}
+export declare function isWireDirection(v: unknown): v is WireDirection;
+export declare function isWireKind(v: unknown): v is WireKind;

package/build/services/machines/gateway/wire-window.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * The last wire events of a line, kept by its leader so a client reads the
+ * tape over HTTP instead of the event stream. A ring of a fixed size; reads
+ * are newest first and may narrow by machine, direction, kind and time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireWindow = exports.MAX_WIRE_PAGE = exports.DEFAULT_WIRE_WINDOW = void 0;
+exports.isWireDirection = isWireDirection;
+exports.isWireKind = isWireKind;
+exports.DEFAULT_WIRE_WINDOW = 500;
+exports.MAX_WIRE_PAGE = 500;
+class WireWindow {
+    constructor(size = exports.DEFAULT_WIRE_WINDOW) {
+        this.size = size;
+        this.events = [];
+        this.head = 0;
+        this.count = 0;
+        if (!Number.isInteger(size) || size < 1)
+            throw new Error(`a wire window keeps at least one event (got ${size})`);
+    }
+    push(event) {
+        this.events[this.head] = event;
+        this.head = (this.head + 1) % this.size;
+        if (this.count < this.size)
+            this.count += 1;
+    }
+    /** Newest first, narrowed by the query, at most `limit` (the window's size when absent). */
+    read(query = {}) {
+        const limit = Math.min(Math.max(1, query.limit ?? this.size), exports.MAX_WIRE_PAGE);
+        const out = [];
+        for (let i = 1; i <= this.count && out.length < limit; i++) {
+            const event = this.events[(this.head - i + this.size) % this.size];
+            if (matches(event, query))
+                out.push(event);
+        }
+        return out;
+    }
+    get length() {
+        return this.count;
+    }
+}
+exports.WireWindow = WireWindow;
+function matches(event, q) {
+    if (q.machine && event.machineId !== q.machine)
+        return false;
+    if (q.direction && event.direction !== q.direction)
+        return false;
+    if (q.kind && event.kind !== q.kind)
+        return false;
+    if (q.since && event.at <= q.since)
+        return false;
+    return true;
+}
+function isWireDirection(v) {
+    return v === 'in' || v === 'out';
+}
+const KINDS = ['presence', 'snapshot', 'job', 'alarm', 'telemetry', 'report', 'cmd', 'reply', 'receipt', 'unknown'];
+function isWireKind(v) {
+    return typeof v === 'string' && KINDS.includes(v);
+}

package/build/services/machines/gateway/wire.js

@@ -165,6 +165,7 @@ function plannedAction(a) {
         case 'watchOffline': return { verb: 'none', detail: `watching ${a.machineId} for an offline row` };
         case 'settleReply': return { verb: 'ack', detail: `${a.status} ${a.cmdId}` };
         case 'settleSnapshot': return { verb: 'ack', detail: `${a.machineId} holds ${count(a.jobIds.length, 'job')}` };
+        case 'unrecoverable': return { verb: 'none', detail: `${a.machineId} lost ${a.jobs.join(', ')}; nothing remembered to send again` };
         case 'bindAddress': return { verb: 'ack', detail: `bind ${a.machineId} to ${a.address}` };
         case 'refuseBinding': return { verb: 'refuse', detail: a.reason };
     }

package/build/services/machines/leadership.d.ts

@@ -30,6 +30,8 @@ export declare class LineLeadership {
     private leadOnce;
     /** Lead while the lock is held; the error that ended it. */
     private holdLock;
+    /** The leader gives its turn up without stopping: `lost` runs, the lock goes, and the line contends again after the pause. */
+    relinquish(reason: string): void;
     /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
     stop(): Promise<void>;
 }

package/build/services/machines/leadership.js

@@ -62,7 +62,7 @@ class LineLeadership {
     async holdLock(client, lead) {
         const ended = new Promise((resolve) => {
             client.once('error', resolve);
-            this.endTurn = () => resolve(new Error('leadership stopped'));
+            this.endTurn = (err) => resolve(err ?? new Error('leadership stopped'));
         });
         try {
             await client.query(LOCK_SQL, [this.key]);
@@ -76,6 +76,12 @@ class LineLeadership {
             return err;
         }
     }
+    /** The leader gives its turn up without stopping: `lost` runs, the lock goes, and the line contends again after the pause. */
+    relinquish(reason) {
+        if (!this.leading)
+            return;
+        this.endTurn?.(new Error(reason));
+    }
     /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
     async stop() {
         this.stopped = true;

package/build/services/machines/roles.d.ts

@@ -1,10 +1,11 @@
 /**
  * The roles a line needs, as code-owned role declarations: one station role
  * per process (a machine resolves the handoffs into it), the exit role (a
- * person receives finished units) and the operator role (a person decides
- * failed handoffs and closes alarm and machine rows). Each role owns its
- * form; only the operator role enforces it on the server, because handoff
- * rows also collect machine records the gateway already validates.
+ * person receives finished units), the operator role (a person decides
+ * failed handoffs and closes alarm and machine rows) and the quality role
+ * (a person decides units finished on hold). Each role owns its form; the
+ * operator and quality roles enforce it on the server, since handoff rows
+ * also collect machine records the gateway already validates.
  */
 import type { LTRoleConfig } from '../../types/startup';
 import { type LineDef } from '../../lib/machines/line';

package/build/services/machines/roles.js

@@ -2,10 +2,11 @@
 /**
  * The roles a line needs, as code-owned role declarations: one station role
  * per process (a machine resolves the handoffs into it), the exit role (a
- * person receives finished units) and the operator role (a person decides
- * failed handoffs and closes alarm and machine rows). Each role owns its
- * form; only the operator role enforces it on the server, because handoff
- * rows also collect machine records the gateway already validates.
+ * person receives finished units), the operator role (a person decides
+ * failed handoffs and closes alarm and machine rows) and the quality role
+ * (a person decides units finished on hold). Each role owns its form; the
+ * operator and quality roles enforce it on the server, since handoff rows
+ * also collect machine records the gateway already validates.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.machineRoleConfigs = machineRoleConfigs;
@@ -44,6 +45,14 @@ function machineRoleConfigs(line) {
             enforce_schema: true,
             ...BOARD,
         },
+        {
+            role: (0, line_1.qualityRole)(line),
+            title: 'Line quality',
+            description: 'Units a machine finished on hold: release, rework or scrap.',
+            form_schema: forms_1.QUALITY_FORM_SCHEMA,
+            enforce_schema: true,
+            ...BOARD,
+        },
     ];
 }
 /** The host's declarations first; line roles only where the host declared none. */

package/build/services/machines/select.d.ts

@@ -16,9 +16,10 @@ export type LineMessaging = Pick<typeof messagingRegistry, 'streams' | 'pubsub'>
 /**
  * The gateway's view of every machine on the line. With `nats`, events are read
  * from Long Tail's messaging streams; MACHINE_SITE_NATS_URL instead names a NATS
- * server of the site's own, which the bus connects to itself.
+ * server of the site's own, which the bus connects to itself. `siteCodecs` are
+ * the codecs of every line on the site, so the streams keep all their subjects.
  */
-export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging): MachineBus;
+export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging, siteCodecs?: LineCodec[], onLost?: (reason: string) => void): MachineBus;
 /** Long Tail's escalation events for the gateway; `in-process` needs the running instance's callback adapter. */
 export declare function createEscalationFeed(config: MachineLineConfig, line: LineDef, callbacks?: CallbackEventAdapter): EscalationFeed;
 /** One MQTT link per simulated machine; machines speak MQTT in every networked mode. */

package/build/services/machines/select.js

@@ -33,12 +33,13 @@ function defaultCodec(config, line) {
 /**
  * The gateway's view of every machine on the line. With `nats`, events are read
  * from Long Tail's messaging streams; MACHINE_SITE_NATS_URL instead names a NATS
- * server of the site's own, which the bus connects to itself.
+ * server of the site's own, which the bus connects to itself. `siteCodecs` are
+ * the codecs of every line on the site, so the streams keep all their subjects.
  */
-function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry) {
+function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry, siteCodecs = [], onLost) {
     switch (config.transport) {
         case config_1.MACHINE_TRANSPORT.NATS: {
-            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec };
+            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec, siteCodecs, onLost };
             if (config.siteNatsUrl) {
                 return new nats_bus_1.NatsMachineBus({ natsUrl: config.siteNatsUrl, user: config.siteNatsUser, password: config.siteNatsPassword, ...where });
             }

package/build/services/machines/surface.d.ts

@@ -11,7 +11,7 @@ import type { CallbackEventAdapter } from '../../lib/events/callback';
 import { type LineDef } from '../../lib/machines/line';
 import { type LineCodec } from '../../lib/machines/protocol';
 import type { InboundMessage } from '../../lib/machines/transport';
-import type { InspectResult, LineSummary, LineView } from '../../types/machines-view';
+import type { InspectResult, LineSummary, LineView, WireEvent, WireWindowQuery } from '../../types/machines-view';
 import { type MachineLineConfig } from './config';
 import { type GatewayLog } from './gateway/log';
 import type { HandoffRowAdapter } from './rows';
@@ -23,8 +23,12 @@ export interface MachineSurfaceOptions {
     callbacks?: CallbackEventAdapter;
     log?: GatewayLog;
     codec?: LineCodec;
+    /** A codec for one line, keyed `<siteId>/<lineId>`; every other line uses `codec`. */
+    codecs?: Record<string, LineCodec>;
     rows?: HandoffRowAdapter;
 }
+/** The codec a line runs on: its own, the surface's, or the generic line protocol. */
+export declare function codecFor(opts: Pick<MachineSurfaceOptions, 'codec' | 'codecs'>, config: MachineLineConfig, line: LineDef): LineCodec;
 /** A message to dry-run against a line. */
 export type WireProbe = Pick<InboundMessage, 'topic' | 'payload' | 'retained'>;
 /** What settings and the API read of the surface. */
@@ -35,6 +39,8 @@ export interface LineSurface {
     describeLine(siteId: string, lineId: string): LineView | null;
     /** A dry run of one message; null when this replica is not leading the line. */
     inspect(siteId: string, lineId: string, probe: WireProbe): InspectResult | null;
+    /** The leader's last wire events, newest first; null when this replica is not leading the line. */
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
     /** The declared line, or undefined. */
     findLine(siteId: string, lineId: string): LineDef | undefined;
     /** The ops a machine-command row on this line may ask for. */
@@ -65,8 +71,11 @@ export declare class MachineSurface implements LineSurface {
     describeLines(): LineSummary[];
     describeLine(siteId: string, lineId: string): LineView | null;
     inspect(siteId: string, lineId: string, probe: WireProbe): InspectResult | null;
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
     findLine(siteId: string, lineId: string): LineDef | undefined;
     commandOps(siteId: string, lineId: string): string[];
+    /** The codecs every line on a site runs, so one site's streams keep all their subjects. */
+    codecsOnSite(siteId: string): LineCodec[];
     private begin;
     private run;
 }