@hotmeshio/long-tail 0.27.0 → 0.28.0

package/build/services/machines/gateway/reply-waiter.js

@@ -2,7 +2,8 @@
 /**
  * Command replies by cmdId, and machine snapshots by machine. A wait registers
  * before the command is published and resolves with the reply, or null at the
- * deadline.
+ * deadline. Several waits on one key are all settled by the next answer, so
+ * two dispatches asking one machine what it holds share its next snapshot.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReplyWaiter = void 0;
@@ -11,31 +12,51 @@ class Waits {
         this.waiting = new Map();
     }
     wait(key, timeoutMs) {
-        this.waiting.get(key)?.resolve(null);
         return new Promise((resolve) => {
-            const timer = setTimeout(() => {
-                this.waiting.delete(key);
-                resolve(null);
-            }, timeoutMs);
-            this.waiting.set(key, { resolve, timer });
+            const waiter = {
+                resolve,
+                timer: setTimeout(() => {
+                    this.drop(key, waiter);
+                    resolve(null);
+                }, timeoutMs),
+            };
+            let waiters = this.waiting.get(key);
+            if (!waiters) {
+                waiters = new Set();
+                this.waiting.set(key, waiters);
+            }
+            waiters.add(waiter);
         });
     }
+    /** True when at least one waiter took the value. */
     settle(key, value) {
-        const w = this.waiting.get(key);
-        if (!w)
+        const waiters = this.waiting.get(key);
+        if (!waiters)
             return false;
-        clearTimeout(w.timer);
         this.waiting.delete(key);
-        w.resolve(value);
+        for (const w of waiters) {
+            clearTimeout(w.timer);
+            w.resolve(value);
+        }
         return true;
     }
     cancelAll() {
-        for (const [, w] of this.waiting) {
-            clearTimeout(w.timer);
-            w.resolve(null);
+        for (const waiters of this.waiting.values()) {
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve(null);
+            }
         }
         this.waiting.clear();
     }
+    drop(key, waiter) {
+        const waiters = this.waiting.get(key);
+        if (!waiters)
+            return;
+        waiters.delete(waiter);
+        if (!waiters.size)
+            this.waiting.delete(key);
+    }
 }
 class ReplyWaiter {
     constructor() {
@@ -49,11 +70,11 @@ class ReplyWaiter {
     settle(reply) {
         return this.replies.settle(reply.cmdId, reply);
     }
-    /** The next snapshot from `machineId`, or null at the deadline. */
+    /** The next snapshot from `machineId`, or null at the deadline; every wait in flight for the machine gets it. */
     waitSnapshot(machineId, timeoutMs) {
         return this.snapshots.wait(machineId, timeoutMs);
     }
-    /** Answer a status query in flight; null when there is nothing to wait for. */
+    /** Answer the status queries in flight; null when there is nothing to wait for. */
     settleSnapshot(machineId, jobs) {
         this.snapshots.settle(machineId, jobs);
     }

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

@@ -5,6 +5,8 @@
  * machine's link: presence, last message, software and boot id.
  */
 import type { HandoffFacets, TraceEntry } from '../contracts';
+import type { LineDef } from '../../../lib/machines/line';
+import type { ContestedClaimView, LineView } from '../../../types/machines-view';
 /**
  * WAITING: the machine has no room yet (pacing.ts); the row waits in its role queue.
  * ARRIVING: the job goes out once its units arrive at the receiver (codec `dispatchOn: arrival`).
@@ -47,6 +49,7 @@ export interface AlarmTrack {
     alarmId: string;
     /** When the machine raised it; a reused alarm id with a new time is a new alarm. */
     raisedAt?: string;
+    level?: string;
     rowId?: string;
     /** Created and not yet resolved by anyone. */
     open: boolean;
@@ -62,12 +65,25 @@ export interface LinkTrack {
     watching?: boolean;
     software?: string;
     bootId?: string;
+    /** The machine's connection, when its presence names one; a new one while online is a reconnect to resync. */
+    sessionId?: string;
+    /** Why the machine went offline, when its presence said. */
+    reason?: string;
+    /** The jobs its last snapshot listed, as the codec reported them. */
+    jobs?: unknown[];
+}
+/** One unit a machine holds: the job it arrived under. */
+export interface HeldUnit {
+    unitId: string;
+    jobId: string;
 }
 export declare class GatewayState {
     /** Units one dispatch may carry, from the codec; null when any number may. */
     unitsPerDispatch: number | null;
     /** Jobs go to a receiver once its units arrive there, from the codec. */
     dispatchOnArrival: boolean;
+    /** Commands of the machines' own that a machine-command row may ask for, from the codec. */
+    rowOps: readonly string[];
     /** Note each job's start, progress steps and pauses on the row that holds it (lifecycle.ts). */
     lifecycle: boolean;
     /** Active alarms are retained on the broker; otherwise snapshots list them (codec.ts retainedAlarms). */
@@ -87,6 +103,7 @@ export declare class GatewayState {
     readonly alarms: Map<string, AlarmTrack>;
     /** Finished records that came before their row: machine/unit → job body. */
     private earlyFinishes;
+    /** Open machine-command rows → the machine each commands. */
     private openCommands;
     /** Accepted dispatch command ids → their row, so a later failure finds the row. */
     private dispatches;
@@ -97,7 +114,7 @@ export declare class GatewayState {
     /** Learned addresses, both ways: station → address and address → station. */
     private addressOfStation;
     private stationOfAddress;
-    /** Contested claims already raised as registration rows, `${address}>${station}`. */
+    /** Contested claims already raised as registration rows, `${address}>${station}` → the row. */
     private claims;
     /** Contested claims heard from the machines themselves, `${address}>${station}`. */
     private heard;
@@ -116,6 +133,7 @@ export declare class GatewayState {
     /** 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). */
     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. */
@@ -125,14 +143,18 @@ export declare class GatewayState {
     /** The row a dispatch command belongs to, open or recently closed. */
     rowForDispatch(cmdId: string): HandoffRow | undefined;
     /** Track a machine-command row; false when it is already tracked or has ended. */
-    trackCommand(id: string): boolean;
+    trackCommand(id: string, machineId?: string): boolean;
+    /** Open machine-command rows for one machine. */
+    openCommandsFor(machineId: string): number;
     endCommand(id: string): void;
     /** Bind a station to an address, replacing whatever either was bound to before. */
     bindAddress(machineId: string, address: string): void;
     learnedAddress(machineId: string): string | undefined;
     stationAt(address: string): string | undefined;
     claimRaised(address: string, machineId: string): boolean;
-    raiseClaim(address: string, machineId: string): void;
+    raiseClaim(address: string, machineId: string, rowId?: string): void;
+    /** The contested claims waiting for a person, with the rows that ask. */
+    contested(): ContestedClaimView[];
     settleClaim(address: string, machineId: string): void;
     hearClaim(address: string, machineId: string): void;
     claimHeard(address: string, machineId: string): boolean;
@@ -142,4 +164,8 @@ export declare class GatewayState {
     raiseViolation(key: string): void;
     link(machineId: string, now?: number): LinkTrack;
     alarmKey(machineId: string, alarmId: string): string;
+    /** The line as this gateway sees it (project.ts). */
+    project(line: LineDef): LineView;
+    /** A copy a dry run may change without touching the line. */
+    clone(): GatewayState;
 }

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 project_1 = require("./project");
 const trace_1 = require("./trace");
 /**
  * WAITING: the machine has no room yet (pacing.ts); the row waits in its role queue.
@@ -16,6 +17,10 @@ exports.DISPATCH_STATE = {
     NONE: 'none', WAITING: 'waiting', ARRIVING: 'arriving', PENDING: 'pending', ACCEPTED: 'accepted', REFUSED: 'refused',
 };
 exports.ROW_END = { RESOLVED: 'resolved', CANCELLED: 'cancelled', EXPIRED: 'expired' };
+function copyInto(from, into, clone = (v) => v) {
+    for (const [k, v] of from)
+        into.set(k, clone(v));
+}
 const CLOSED_LIMIT = 2_000;
 class GatewayState {
     constructor() {
@@ -23,6 +28,8 @@ class GatewayState {
         this.unitsPerDispatch = null;
         /** Jobs go to a receiver once its units arrive there, from the codec. */
         this.dispatchOnArrival = false;
+        /** Commands of the machines' own that a machine-command row may ask for, from the codec. */
+        this.rowOps = [];
         /** Note each job's start, progress steps and pauses on the row that holds it (lifecycle.ts). */
         this.lifecycle = false;
         /** Active alarms are retained on the broker; otherwise snapshots list them (codec.ts retainedAlarms). */
@@ -42,7 +49,8 @@ class GatewayState {
         this.alarms = new Map();
         /** Finished records that came before their row: machine/unit → job body. */
         this.earlyFinishes = new Map();
-        this.openCommands = new Set();
+        /** Open machine-command rows → the machine each commands. */
+        this.openCommands = new Map();
         /** Accepted dispatch command ids → their row, so a later failure finds the row. */
         this.dispatches = new Map();
         this.endedCommands = new Set();
@@ -52,8 +60,8 @@ class GatewayState {
         /** Learned addresses, both ways: station → address and address → station. */
         this.addressOfStation = new Map();
         this.stationOfAddress = new Map();
-        /** Contested claims already raised as registration rows, `${address}>${station}`. */
-        this.claims = new Set();
+        /** Contested claims already raised as registration rows, `${address}>${station}` → the row. */
+        this.claims = new Map();
         /** Contested claims heard from the machines themselves, `${address}>${station}`. */
         this.heard = new Set();
         /** Addresses heard that claim no station, logged once each. */
@@ -116,6 +124,9 @@ class GatewayState {
     heldAt(machineId) {
         return [...(this.held.get(machineId)?.values() ?? [])];
     }
+    heldUnitsAt(machineId) {
+        return [...(this.held.get(machineId)?.entries() ?? [])].map(([unitId, jobId]) => ({ unitId, jobId }));
+    }
     /** Keep only units whose job the machine still lists (its snapshot). */
     keepHeld(machineId, jobIds) {
         const units = this.held.get(machineId);
@@ -154,12 +165,16 @@ class GatewayState {
         return rowId ? this.openRows.get(rowId) ?? this.closedRows.get(rowId) : undefined;
     }
     /** Track a machine-command row; false when it is already tracked or has ended. */
-    trackCommand(id) {
+    trackCommand(id, machineId = '') {
         if (this.openCommands.has(id) || this.endedCommands.has(id))
             return false;
-        this.openCommands.add(id);
+        this.openCommands.set(id, machineId);
         return true;
     }
+    /** Open machine-command rows for one machine. */
+    openCommandsFor(machineId) {
+        return [...this.openCommands.values()].filter((m) => m === machineId).length;
+    }
     endCommand(id) {
         this.openCommands.delete(id);
         this.endedCommands.add(id);
@@ -189,8 +204,15 @@ class GatewayState {
     claimRaised(address, machineId) {
         return this.claims.has(`${address}>${machineId}`);
     }
-    raiseClaim(address, machineId) {
-        this.claims.add(`${address}>${machineId}`);
+    raiseClaim(address, machineId, rowId) {
+        this.claims.set(`${address}>${machineId}`, rowId ?? this.claims.get(`${address}>${machineId}`) ?? null);
+    }
+    /** The contested claims waiting for a person, with the rows that ask. */
+    contested() {
+        return [...this.claims.entries()].map(([key, rowId]) => {
+            const [address, station] = key.split('>');
+            return { address, station, rowId: rowId ?? '' };
+        });
     }
     settleClaim(address, machineId) {
         this.claims.delete(`${address}>${machineId}`);
@@ -234,6 +256,38 @@ class GatewayState {
     alarmKey(machineId, alarmId) {
         return `${machineId}/${alarmId}`;
     }
+    /** The line as this gateway sees it (project.ts). */
+    project(line) {
+        return (0, project_1.projectLine)(this, line);
+    }
+    /** A copy a dry run may change without touching the line. */
+    clone() {
+        const copy = new GatewayState();
+        Object.assign(copy, {
+            unitsPerDispatch: this.unitsPerDispatch, dispatchOnArrival: this.dispatchOnArrival, rowOps: this.rowOps, lifecycle: this.lifecycle,
+            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.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] } : {}) }));
+        copyInto(this.earlyFinishes, copy.earlyFinishes);
+        copyInto(this.openCommands, copy.openCommands);
+        copyInto(this.dispatches, copy.dispatches);
+        copyInto(this.links, copy.links, (link) => ({ ...link }));
+        copyInto(this.addressOfStation, copy.addressOfStation);
+        copyInto(this.stationOfAddress, copy.stationOfAddress);
+        copyInto(this.claims, copy.claims);
+        for (const id of this.endedCommands)
+            copy.endedCommands.add(id);
+        for (const key of this.violations)
+            copy.violations.add(key);
+        for (const key of this.heard)
+            copy.heard.add(key);
+        for (const key of this.strangers)
+            copy.strangers.add(key);
+        return copy;
+    }
 }
 exports.GatewayState = GatewayState;
 function carries(row, unitId) {

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

@@ -0,0 +1,58 @@
+/**
+ * The wire record. Every message a gateway reads, and every command,
+ * snapshot request and receipt it sends, becomes one WireEvent for the
+ * line's view: what was on the wire, how the codec read it, and what the
+ * gateway did about it. Telemetry is left out unless the line asks for it.
+ */
+import { type Inspection, type MachineCommand, type MachineIdent, type WireMessage } from '../../../lib/machines/protocol';
+import { type InboundMessage } from '../../../lib/machines/transport';
+import type { WireAction, WireEvent } from '../../../types/machines-view';
+import type { Action } from './actions';
+import type { Applied } from './admission';
+export type WireSink = (event: WireEvent) => void;
+export declare const WIRE_EVENT_TYPE = "machine.wire";
+export declare const WIRE_DIRECTION: {
+    readonly IN: "in";
+    readonly OUT: "out";
+};
+export interface WireOptions {
+    /** Publish telemetry messages too. */
+    telemetry?: boolean;
+}
+interface WireLine {
+    siteId: string;
+    lineId: string;
+}
+/** The sender a message was read as, when it differs from the topic's. */
+export interface WireSender {
+    machineId: string | null;
+    address: string | null;
+}
+export declare class WireRecorder {
+    private readonly line;
+    private readonly sink;
+    private readonly opts;
+    constructor(line: WireLine, sink: WireSink, opts?: WireOptions);
+    /** A decoded inbound message and what the gateway did with it. */
+    inbound(msg: InboundMessage, seen: Inspection, applied: Applied, deliveries: number, sender?: WireSender): void;
+    /** A message the codec could not read, or one that is not a machine's. */
+    unreadable(msg: InboundMessage, detail: string, verb?: WireAction['verb']): void;
+    /** A command the gateway sent, as the codec put it on the wire. */
+    command(ident: MachineIdent, command: MachineCommand, wire: WireMessage): void;
+    /** A receipt confirming the messages the gateway is done with. */
+    receipt(ident: MachineIdent, ids: string[], wire: WireMessage): void;
+    private outbound;
+}
+/** The event name within the kind: job event, alarm action, command op, reply status. */
+export declare function eventOf(seen: Inspection): string | null;
+/** One line from the kind, the event and the ids the body names. */
+export declare function summarize(seen: Inspection): string;
+/** The record of an inbound message before the gateway's actions are known. */
+export declare function describeInbound(line: WireLine, msg: InboundMessage, seen: Inspection, sender?: WireSender): Omit<WireEvent, 'actions'>;
+/** What handling a message came to, as actions; a message with none is acknowledged, or waits for its row. */
+export declare function appliedActions(applied: Applied, deliveries: number, maxDeliveries?: number): WireAction[];
+/** A message no row has claimed after this many deliveries is not racing its row. */
+export declare const MAX_DELIVERIES = 30;
+/** A planner action as the wire would record it, before it runs; a dry run shows these. */
+export declare function plannedAction(a: Action): WireAction;
+export {};

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

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * The wire record. Every message a gateway reads, and every command,
+ * snapshot request and receipt it sends, becomes one WireEvent for the
+ * line's view: what was on the wire, how the codec read it, and what the
+ * gateway did about it. Telemetry is left out unless the line asks for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DELIVERIES = exports.WireRecorder = exports.WIRE_DIRECTION = exports.WIRE_EVENT_TYPE = void 0;
+exports.eventOf = eventOf;
+exports.summarize = summarize;
+exports.describeInbound = describeInbound;
+exports.appliedActions = appliedActions;
+exports.plannedAction = plannedAction;
+const protocol_1 = require("../../../lib/machines/protocol");
+const transport_1 = require("../../../lib/machines/transport");
+exports.WIRE_EVENT_TYPE = 'machine.wire';
+exports.WIRE_DIRECTION = { IN: 'in', OUT: 'out' };
+const RECEIPT_CHANNEL = 'receipt';
+const ALARM_EVENT = { RAISED: 'raised', ACKED: 'acked', CLEARED: 'cleared' };
+const PRESENCE_EVENT = { ONLINE: 'online', OFFLINE: 'offline' };
+class WireRecorder {
+    constructor(line, sink, opts = {}) {
+        this.line = line;
+        this.sink = sink;
+        this.opts = opts;
+    }
+    /** A decoded inbound message and what the gateway did with it. */
+    inbound(msg, seen, applied, deliveries, sender) {
+        if (seen.parsed?.kind === protocol_1.MESSAGE_KIND.TELEMETRY && !this.opts.telemetry)
+            return;
+        this.sink({ ...describeInbound(this.line, msg, seen, sender), actions: appliedActions(applied, deliveries) });
+    }
+    /** A message the codec could not read, or one that is not a machine's. */
+    unreadable(msg, detail, verb = 'unreadable') {
+        this.sink({
+            ...describeInbound(this.line, msg, { parsed: null, body: null, violations: [] }),
+            summary: detail, actions: [{ verb, detail }],
+        });
+    }
+    /** A command the gateway sent, as the codec put it on the wire. */
+    command(ident, command, wire) {
+        const jobId = typeof command.args.jobId === 'string' ? ` ${command.args.jobId}` : '';
+        this.sink(this.outbound(ident, wire, protocol_1.MESSAGE_KIND.CMD, protocol_1.CHANNEL.CMD, command.op, `cmd ${command.op}${jobId} ${command.cmdId}`));
+    }
+    /** A receipt confirming the messages the gateway is done with. */
+    receipt(ident, ids, wire) {
+        this.sink(this.outbound(ident, wire, 'receipt', RECEIPT_CHANNEL, null, `receipt for ${ids.length} message${ids.length === 1 ? '' : 's'}`));
+    }
+    outbound(ident, wire, kind, channel, event, summary) {
+        const body = parseJson(wire.payload);
+        return {
+            type: exports.WIRE_EVENT_TYPE, siteId: this.line.siteId, lineId: this.line.lineId, machineId: ident.machineId, address: (0, protocol_1.addressOf)(ident),
+            direction: exports.WIRE_DIRECTION.OUT, channel, topic: wire.topic, id: typeof body?.id === 'string' ? body.id : null,
+            at: typeof body?.at === 'string' ? body.at : (0, protocol_1.isoTs)(), retained: false, kind, event, summary, violations: [], actions: [], payload: body ?? wire.payload,
+        };
+    }
+}
+exports.WireRecorder = WireRecorder;
+function parseJson(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The line-protocol channel a decoded message belongs to. */
+function channelOf(seen) {
+    const parsed = seen.parsed;
+    if (!parsed)
+        return '';
+    switch (parsed.kind) {
+        case protocol_1.MESSAGE_KIND.ALARM: return `${protocol_1.CHANNEL.ALARM}/${parsed.key ?? ''}`;
+        case protocol_1.MESSAGE_KIND.REPORT: return `${protocol_1.CHANNEL.REPORT}/${parsed.key ?? ''}`;
+        case protocol_1.MESSAGE_KIND.REPLY: return protocol_1.CHANNEL.REPLY;
+        default: return parsed.kind;
+    }
+}
+/** The event name within the kind: job event, alarm action, command op, reply status. */
+function eventOf(seen) {
+    const parsed = seen.parsed;
+    const b = seen.body?.body ?? {};
+    if (!parsed)
+        return null;
+    switch (parsed.kind) {
+        case protocol_1.MESSAGE_KIND.JOB: return typeof b.event === 'string' ? b.event : null;
+        case protocol_1.MESSAGE_KIND.ALARM: return !seen.body || b.active === false ? ALARM_EVENT.CLEARED : b.ackedBy ? ALARM_EVENT.ACKED : ALARM_EVENT.RAISED;
+        case protocol_1.MESSAGE_KIND.CMD: return typeof b.op === 'string' ? b.op : null;
+        case protocol_1.MESSAGE_KIND.REPLY: return typeof b.status === 'string' ? b.status : null;
+        case protocol_1.MESSAGE_KIND.PRESENCE: return b.online === true ? PRESENCE_EVENT.ONLINE : PRESENCE_EVENT.OFFLINE;
+        case protocol_1.MESSAGE_KIND.SNAPSHOT: return typeof b.mode === 'string' ? b.mode : null;
+        case protocol_1.MESSAGE_KIND.REPORT: return parsed.key ?? null;
+        default: return null;
+    }
+}
+const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** One line from the kind, the event and the ids the body names. */
+function summarize(seen) {
+    const parsed = seen.parsed;
+    if (!parsed)
+        return 'not a machine message';
+    const b = seen.body?.body ?? {};
+    const event = eventOf(seen);
+    switch (parsed.kind) {
+        case protocol_1.MESSAGE_KIND.PRESENCE:
+            return ['presence', event, b.software, b.reason ? `(${b.reason})` : null].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.SNAPSHOT:
+            return ['snapshot', event, count(Array.isArray(b.jobs) ? b.jobs.length : 0, 'job'), Array.isArray(b.alarms) && b.alarms.length ? count(b.alarms.length, 'alarm') : null].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.JOB:
+            return ['job', event, b.unitId ?? (b.carrierId ? `carrier ${b.carrierId}` : null), b.jobId ? `(${b.jobId})` : null, b.result, b.failure].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.ALARM:
+            return ['alarm', event, parsed.key ?? b.alarmId, b.level, b.text ? `: ${b.text}` : null].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.TELEMETRY:
+            return `telemetry ${count(Object.keys(b.readings ?? {}).length, 'reading')}`;
+        case protocol_1.MESSAGE_KIND.CMD:
+            return ['cmd', event, b.args?.jobId, b.cmdId].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.REPLY:
+            return ['reply', event, b.cmdId, b.reason ? `: ${b.reason}` : null].filter(Boolean).join(' ');
+        case protocol_1.MESSAGE_KIND.REPORT:
+            return `report ${parsed.key ?? ''}`.trim();
+        default:
+            return parsed.kind;
+    }
+}
+/** The record of an inbound message before the gateway's actions are known. */
+function describeInbound(line, msg, seen, sender) {
+    const ident = seen.parsed?.ident;
+    return {
+        type: exports.WIRE_EVENT_TYPE, siteId: line.siteId, lineId: line.lineId,
+        machineId: sender ? sender.machineId : ident?.machineId ?? null,
+        address: sender ? sender.address : ident ? (0, protocol_1.addressOf)(ident) : null,
+        direction: exports.WIRE_DIRECTION.IN, channel: channelOf(seen), topic: msg.topic,
+        id: seen.body?.id ?? null, at: seen.body?.at ?? (0, protocol_1.isoTs)(), retained: msg.retained === true,
+        kind: seen.parsed?.kind ?? 'unknown', event: eventOf(seen), summary: summarize(seen),
+        violations: seen.violations, payload: seen.body ?? msg.payload,
+    };
+}
+/** What handling a message came to, as actions; a message with none is acknowledged, or waits for its row. */
+function appliedActions(applied, deliveries, maxDeliveries = exports.MAX_DELIVERIES) {
+    if (applied.actions.length)
+        return applied.actions;
+    if (applied.disposition !== transport_1.DISPOSITION.NAK)
+        return [{ verb: 'ack' }];
+    if (applied.failed)
+        return [{ verb: 'none', detail: 'a verb failed; the message is delivered again' }];
+    if (deliveries >= maxDeliveries)
+        return [{ verb: 'unmatched', detail: `no row after ${deliveries} deliveries` }];
+    return [{ verb: 'none', detail: `waiting for its row (delivery ${deliveries})` }];
+}
+/** A message no row has claimed after this many deliveries is not racing its row. */
+exports.MAX_DELIVERIES = 30;
+/** A planner action as the wire would record it, before it runs; a dry run shows these. */
+function plannedAction(a) {
+    switch (a.kind) {
+        case 'dispatch': return { verb: 'none', detail: `dispatch ${a.args.jobId ?? a.cmdId} to ${a.machineId}` };
+        case 'command': return { verb: 'none', detail: `${a.op} to ${a.machineId}` };
+        case 'control': return { verb: 'none', rowId: a.rowId, detail: `${a.op} to ${a.machineId}` };
+        case 'claim': return { verb: 'claim', rowId: a.rowId };
+        case 'accumulate': return { verb: 'accumulate', rowId: a.rowId, itemKey: a.itemKey };
+        case 'resolve': return { verb: 'resolve', rowId: a.rowId };
+        case 'createAlarmRow': return { verb: 'create-row', detail: `${a.row.type} for ${a.machineId}` };
+        case 'createRow': return { verb: 'create-row', detail: a.row.type };
+        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 'bindAddress': return { verb: 'ack', detail: `bind ${a.machineId} to ${a.address}` };
+        case 'refuseBinding': return { verb: 'refuse', detail: a.reason };
+    }
+}

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

@@ -7,5 +7,8 @@ export * from './gateway';
 export * from './roles';
 export * from './identities';
 export * from './surface';
+export * from './registry';
+export * from './registry-sync';
 export * from './rows';
 export * from '../../lib/machines';
+export type * from '../../types/machines-view';

package/build/services/machines/index.js

@@ -23,5 +23,7 @@ __exportStar(require("./gateway"), exports);
 __exportStar(require("./roles"), exports);
 __exportStar(require("./identities"), exports);
 __exportStar(require("./surface"), exports);
+__exportStar(require("./registry"), exports);
+__exportStar(require("./registry-sync"), exports);
 __exportStar(require("./rows"), exports);
 __exportStar(require("../../lib/machines"), exports);

package/build/services/machines/line-index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The lines index as the API and the MCP server present it: a registry row
+ * joined with what the running surface knows about the line.
+ */
+import type { LineDef } from '../../lib/machines/line';
+import type { LineHealth, LineIndexRow, LineSummary } from '../../types/machines-view';
+import type { LineRecordWithHealth } from './registry';
+import { type LineSurface } from './surface';
+/** The line as every replica describes it: the surface's own summary when it runs the line, else the stored definition. */
+export declare function lineSummaryOf(surface: LineSurface, siteId: string, lineId: string, stored: LineDef): LineSummary;
+/** A registry row as the index shows it. */
+export declare function toLineIndexRow(surface: LineSurface, record: LineRecordWithHealth): LineIndexRow;
+/** Health for a line no pending row names yet. */
+export declare function emptyLineHealth(machines: number): LineHealth;
+/** The raw wire payload as a string: an object is serialized, text passes through. */
+export declare function wirePayloadOf(body: unknown): string;

package/build/services/machines/line-index.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * The lines index as the API and the MCP server present it: a registry row
+ * joined with what the running surface knows about the line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineSummaryOf = lineSummaryOf;
+exports.toLineIndexRow = toLineIndexRow;
+exports.emptyLineHealth = emptyLineHealth;
+exports.wirePayloadOf = wirePayloadOf;
+const surface_1 = require("./surface");
+/** The line as every replica describes it: the surface's own summary when it runs the line, else the stored definition. */
+function lineSummaryOf(surface, siteId, lineId, stored) {
+    const running = surface.findLine(siteId, lineId)
+        ? surface.describeLines().find((l) => l.siteId === siteId && l.lineId === lineId)
+        : undefined;
+    return running ?? (0, surface_1.summarizeLine)(stored, {});
+}
+/** A registry row as the index shows it. */
+function toLineIndexRow(surface, record) {
+    return {
+        ...lineSummaryOf(surface, record.siteId, record.lineId, record.definition),
+        source: record.source, version: record.version, enabled: record.enabled, updatedAt: record.updatedAt,
+        leading: surface.describeLine(record.siteId, record.lineId) !== null,
+        health: record.health,
+    };
+}
+/** Health for a line no pending row names yet. */
+function emptyLineHealth(machines) {
+    return { machines, offline: 0, quiet: 0, alarms: 0, people: 0, handoff: 0, command: 0, attention: false };
+}
+/** The raw wire payload as a string: an object is serialized, text passes through. */
+function wirePayloadOf(body) {
+    if (typeof body === 'string')
+        return body;
+    if (body === undefined || body === null)
+        return '';
+    return JSON.stringify(body);
+}

package/build/services/machines/registry-sql.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The line registry's statements. Every write is one statement: the
+ * version advances in the same UPDATE that changes the row, and a version
+ * check rides the WHERE so a stale writer gets zero rows back.
+ */
+export declare const LINE_SOURCE: {
+    readonly CODE: "code";
+    readonly API: "api";
+};
+/** An API write: insert, or replace and advance the version; $5 non-null requires that version. */
+export declare const UPSERT_API_LINE: string;
+/** A db-owned code line: first writer wins, an existing row is left as it is. */
+export declare const SEED_CODE_LINE: string;
+/** A code-owned code line: written only when the definition or the owner differs, one version per change. */
+export declare const APPLY_CODE_LINE: string;
+export declare const GET_LINE = "SELECT site_id, line_id, definition, source, version, enabled, search_text, created_at, updated_at FROM lt_machine_lines WHERE site_id = $1 AND line_id = $2";
+export declare const DELETE_LINE = "DELETE FROM lt_machine_lines WHERE site_id = $1 AND line_id = $2 RETURNING site_id, line_id, definition, source, version, enabled, search_text, created_at, updated_at";
+export declare const LIST_ENABLED_LINES = "SELECT site_id, line_id, definition, source, version, enabled, search_text, created_at, updated_at FROM lt_machine_lines WHERE enabled ORDER BY site_id, line_id";
+export declare const LIST_CODE_LINES: string;
+/** The kinds of pending rows the index counts, in the order the health CTE projects them. */
+export declare const HEALTH_ROW_TYPES: readonly ["machine-offline", "machine-quiet", "line-alarm", "handoff-error", "contract-violation", "machine-registration", "handoff", "machine-command"];
+/** The index's order, by name; attention first within each. */
+export declare const LINE_ORDER: Record<string, string>;
+/**
+ * One page of the index: $1 row types, $2 search pattern or null, $3 site
+ * or null, $4 attention or null, $5 limit, $6 offset, $7 line or null. The
+ * total rides every row as a window count.
+ */
+export declare function listLinesSql(order: string): string;
+/** Every site, with its lines and how many need attention: $1 row types. */
+export declare const LIST_SITES: string;