@hotmeshio/long-tail 0.27.0 → 0.28.1

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.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,172 @@
+"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 '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/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;

package/build/services/machines/registry-sql.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SITES = exports.LINE_ORDER = exports.HEALTH_ROW_TYPES = exports.LIST_CODE_LINES = exports.LIST_ENABLED_LINES = exports.DELETE_LINE = exports.GET_LINE = exports.APPLY_CODE_LINE = exports.SEED_CODE_LINE = exports.UPSERT_API_LINE = exports.LINE_SOURCE = void 0;
+exports.listLinesSql = listLinesSql;
+const contracts_1 = require("./contracts");
+exports.LINE_SOURCE = { CODE: 'code', API: 'api' };
+const COLUMNS = 'site_id, line_id, definition, source, version, enabled, search_text, created_at, updated_at';
+/** An API write: insert, or replace and advance the version; $5 non-null requires that version. */
+exports.UPSERT_API_LINE = `
+  INSERT INTO lt_machine_lines (site_id, line_id, definition, source, search_text)
+  VALUES ($1, $2, $3::jsonb, '${exports.LINE_SOURCE.API}', $4)
+  ON CONFLICT (site_id, line_id) DO UPDATE
+    SET definition = EXCLUDED.definition,
+        source = '${exports.LINE_SOURCE.API}',
+        search_text = EXCLUDED.search_text,
+        enabled = true,
+        version = lt_machine_lines.version + 1,
+        updated_at = NOW()
+    WHERE $5::int IS NULL OR lt_machine_lines.version = $5::int
+  RETURNING ${COLUMNS}`;
+/** A db-owned code line: first writer wins, an existing row is left as it is. */
+exports.SEED_CODE_LINE = `
+  INSERT INTO lt_machine_lines (site_id, line_id, definition, source, search_text)
+  VALUES ($1, $2, $3::jsonb, '${exports.LINE_SOURCE.CODE}', $4)
+  ON CONFLICT (site_id, line_id) DO NOTHING
+  RETURNING ${COLUMNS}`;
+/** A code-owned code line: written only when the definition or the owner differs, one version per change. */
+exports.APPLY_CODE_LINE = `
+  INSERT INTO lt_machine_lines (site_id, line_id, definition, source, search_text)
+  VALUES ($1, $2, $3::jsonb, '${exports.LINE_SOURCE.CODE}', $4)
+  ON CONFLICT (site_id, line_id) DO UPDATE
+    SET definition = EXCLUDED.definition,
+        source = '${exports.LINE_SOURCE.CODE}',
+        search_text = EXCLUDED.search_text,
+        enabled = true,
+        version = lt_machine_lines.version + 1,
+        updated_at = NOW()
+    WHERE lt_machine_lines.definition IS DISTINCT FROM EXCLUDED.definition
+       OR lt_machine_lines.source <> '${exports.LINE_SOURCE.CODE}'
+       OR NOT lt_machine_lines.enabled
+  RETURNING ${COLUMNS}`;
+exports.GET_LINE = `SELECT ${COLUMNS} FROM lt_machine_lines WHERE site_id = $1 AND line_id = $2`;
+exports.DELETE_LINE = `DELETE FROM lt_machine_lines WHERE site_id = $1 AND line_id = $2 RETURNING ${COLUMNS}`;
+exports.LIST_ENABLED_LINES = `SELECT ${COLUMNS} FROM lt_machine_lines WHERE enabled ORDER BY site_id, line_id`;
+exports.LIST_CODE_LINES = `SELECT site_id, line_id FROM lt_machine_lines WHERE source = '${exports.LINE_SOURCE.CODE}'`;
+/** The kinds of pending rows the index counts, in the order the health CTE projects them. */
+exports.HEALTH_ROW_TYPES = [
+    contracts_1.ROW_TYPE.MACHINE_OFFLINE, contracts_1.ROW_TYPE.MACHINE_QUIET, contracts_1.ROW_TYPE.ALARM,
+    contracts_1.ROW_TYPE.HANDOFF_ERROR, contracts_1.ROW_TYPE.CONTRACT_VIOLATION, contracts_1.ROW_TYPE.MACHINE_REGISTRATION,
+    contracts_1.ROW_TYPE.HANDOFF, contracts_1.ROW_TYPE.MACHINE_COMMAND,
+];
+const PENDING = 'pending';
+/** Pending rows per line, counted by kind: $1 is the list of row types. */
+const HEALTH_CTE = `
+  health AS (
+    SELECT metadata->>'siteId' AS site_id, metadata->>'lineId' AS line_id,
+      COUNT(*) FILTER (WHERE type = '${contracts_1.ROW_TYPE.MACHINE_OFFLINE}')::int AS offline,
+      COUNT(*) FILTER (WHERE type = '${contracts_1.ROW_TYPE.MACHINE_QUIET}')::int AS quiet,
+      COUNT(*) FILTER (WHERE type = '${contracts_1.ROW_TYPE.ALARM}')::int AS alarms,
+      COUNT(*) FILTER (WHERE type IN ('${contracts_1.ROW_TYPE.HANDOFF_ERROR}', '${contracts_1.ROW_TYPE.CONTRACT_VIOLATION}', '${contracts_1.ROW_TYPE.MACHINE_REGISTRATION}'))::int AS people,
+      COUNT(*) FILTER (WHERE type = '${contracts_1.ROW_TYPE.HANDOFF}')::int AS handoff,
+      COUNT(*) FILTER (WHERE type = '${contracts_1.ROW_TYPE.MACHINE_COMMAND}')::int AS command
+    FROM public.lt_escalations
+    WHERE status = '${PENDING}' AND type = ANY($1::text[]) AND metadata ? 'siteId' AND metadata ? 'lineId'
+    GROUP BY 1, 2
+  ),
+  lines AS (
+    SELECT l.${COLUMNS.split(', ').join(', l.')},
+      COALESCE(h.offline, 0) AS offline, COALESCE(h.quiet, 0) AS quiet, COALESCE(h.alarms, 0) AS alarms,
+      COALESCE(h.people, 0) AS people, COALESCE(h.handoff, 0) AS handoff, COALESCE(h.command, 0) AS command,
+      (COALESCE(h.offline, 0) + COALESCE(h.alarms, 0) + COALESCE(h.people, 0)) > 0 AS attention
+    FROM lt_machine_lines l
+    LEFT JOIN health h ON h.site_id = l.site_id AND h.line_id = l.line_id
+    WHERE l.enabled
+  )`;
+/** The index's order, by name; attention first within each. */
+exports.LINE_ORDER = {
+    attention: 'attention DESC, (offline + alarms + people) DESC, site_id, line_id',
+    site: 'site_id, line_id',
+    updated: 'updated_at DESC, site_id, line_id',
+};
+/**
+ * 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.
+ */
+function listLinesSql(order) {
+    return `
+  WITH ${HEALTH_CTE}
+  SELECT *, COUNT(*) OVER() AS total
+  FROM lines
+  WHERE ($2::text IS NULL OR search_text ILIKE $2 ESCAPE '\\')
+    AND ($3::text IS NULL OR site_id = $3)
+    AND ($4::boolean IS NULL OR attention = $4)
+    AND ($7::text IS NULL OR line_id = $7)
+  ORDER BY ${order}
+  LIMIT $5 OFFSET $6`;
+}
+/** Every site, with its lines and how many need attention: $1 row types. */
+exports.LIST_SITES = `
+  WITH ${HEALTH_CTE}
+  SELECT site_id, COUNT(*)::int AS lines, COUNT(*) FILTER (WHERE attention)::int AS attention
+  FROM lines
+  GROUP BY site_id
+  ORDER BY site_id`;

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

@@ -0,0 +1,31 @@
+/**
+ * Keeps the running surface in step with the line registry. A declaration
+ * through the API writes the registry, applies the line's roles, runs the
+ * line on this replica and tells every other replica, which reads the row
+ * again and follows. Boot applies the code lines the same way, then starts
+ * the surface with everything the registry holds.
+ */
+import type { CallbackEventAdapter } from '../../lib/events/callback';
+import type { LineDef } from '../../lib/machines/line';
+import { type LineApplyReport, type LineRecord } from './registry';
+import type { LineSurface } from './surface';
+export declare const LINE_ACTION: {
+    readonly DECLARED: "declared";
+    readonly RETIRED: "retired";
+};
+/** Declare a line through the API on this replica, then tell the others. */
+export declare function declareLine(surface: LineSurface, def: LineDef, expectedVersion?: number): Promise<LineRecord>;
+/** Retire a line on this replica and in the registry, then tell the others. Roles and bot accounts stay. */
+export declare function retireLine(surface: LineSurface, siteId: string, lineId: string): Promise<LineRecord | null>;
+/** Boot: apply code lines under the configSource rules, then every enabled line the registry holds. */
+export declare function syncDeclaredLines(lines: LineDef[], codeOwned: boolean): Promise<{
+    report: LineApplyReport;
+    lines: LineDef[];
+}>;
+/**
+ * Follow registry changes other replicas publish. The event only names the
+ * line: the registry row is read again and decides, so a stray or stale
+ * event cannot stop a line the registry still holds. The surface ignores a
+ * line it already runs unchanged.
+ */
+export declare function watchLineRegistry(surface: LineSurface, callbacks: CallbackEventAdapter): () => void;

package/build/services/machines/registry-sync.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Keeps the running surface in step with the line registry. A declaration
+ * through the API writes the registry, applies the line's roles, runs the
+ * line on this replica and tells every other replica, which reads the row
+ * again and follows. Boot applies the code lines the same way, then starts
+ * the surface with everything the registry holds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINE_ACTION = void 0;
+exports.declareLine = declareLine;
+exports.retireLine = retireLine;
+exports.syncDeclaredLines = syncDeclaredLines;
+exports.watchLineRegistry = watchLineRegistry;
+const publish_1 = require("../../lib/events/publish");
+const config_lock_1 = require("../../lib/db/config-lock");
+const logger_1 = require("../../lib/logger");
+const topics_1 = require("../../lib/machines/protocol/topics");
+const seed_1 = require("../role/seed");
+const registry_1 = require("./registry");
+const roles_1 = require("./roles");
+const LINE_EVENTS = 'machine.line.>';
+const LOG = '[lt-machines]';
+exports.LINE_ACTION = { DECLARED: 'declared', RETIRED: 'retired' };
+/** The line's station, exit and operator roles, where the host declared none. */
+async function applyLineRoles(line) {
+    await (0, config_lock_1.withConfigLock)(async () => {
+        for (const cfg of (0, roles_1.machineRoleConfigs)(line))
+            await (0, seed_1.applyRoleConfig)(cfg, false);
+    });
+}
+/** Declare a line through the API on this replica, then tell the others. */
+async function declareLine(surface, def, expectedVersion) {
+    const record = await (0, registry_1.declareApiLine)(def, expectedVersion);
+    await applyLineRoles(record.definition);
+    await surface.declare(record.definition);
+    await (0, publish_1.publishMachineLineEvent)({ siteId: record.siteId, lineId: record.lineId, source: record.source, version: record.version, action: exports.LINE_ACTION.DECLARED });
+    return record;
+}
+/** Retire a line on this replica and in the registry, then tell the others. Roles and bot accounts stay. */
+async function retireLine(surface, siteId, lineId) {
+    const record = await (0, registry_1.deleteLine)(siteId, lineId);
+    if (!record)
+        return null;
+    await surface.retire(siteId, lineId);
+    await (0, publish_1.publishMachineLineEvent)({ siteId, lineId, source: record.source, version: record.version, action: exports.LINE_ACTION.RETIRED });
+    return record;
+}
+/** Boot: apply code lines under the configSource rules, then every enabled line the registry holds. */
+async function syncDeclaredLines(lines, codeOwned) {
+    const report = await (0, config_lock_1.withConfigLock)(() => (0, registry_1.applyDeclaredLines)(lines, codeOwned));
+    const enabled = await (0, registry_1.listEnabledLines)();
+    return { report, lines: enabled.map((r) => r.definition) };
+}
+/**
+ * Follow registry changes other replicas publish. The event only names the
+ * line: the registry row is read again and decides, so a stray or stale
+ * event cannot stop a line the registry still holds. The surface ignores a
+ * line it already runs unchanged.
+ */
+function watchLineRegistry(surface, callbacks) {
+    return callbacks.on(LINE_EVENTS, (event) => {
+        const data = (event.data ?? {});
+        if (!(0, topics_1.isTopicLevel)(data.siteId) || !(0, topics_1.isTopicLevel)(data.lineId))
+            return;
+        const { siteId, lineId } = data;
+        void follow(surface, siteId, lineId).catch((err) => {
+            logger_1.loggerRegistry.warn(`${LOG} following ${siteId}/${lineId} failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    });
+}
+async function follow(surface, siteId, lineId) {
+    const record = await (0, registry_1.getLine)(siteId, lineId);
+    if (!record || !record.enabled) {
+        await surface.retire(siteId, lineId);
+        return;
+    }
+    const outcome = await surface.declare(record.definition);
+    if (outcome !== 'unchanged')
+        logger_1.loggerRegistry.info(`${LOG} line ${siteId}/${lineId} ${outcome} from the registry (v${record.version})`);
+}