@hotmeshio/long-tail 0.27.0 → 0.28.0

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})`);
+}

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

@@ -0,0 +1,77 @@
+/**
+ * The line registry: every line this deployment controls, in Postgres, so
+ * every replica contends for the same lines and the Lines index reads one
+ * list. Lines come from code (start({ machines })) and from the API; the
+ * configSource rules decide who wins at boot, the version says what changed.
+ */
+import { type LineDef } from '../../lib/machines/line';
+import type { LineHealth, LineSource, SiteSummary } from '../../types/machines-view';
+import { LINE_ORDER, LINE_SOURCE } from './registry-sql';
+export { LINE_SOURCE };
+/** A registry row. */
+export interface LineRecord {
+    siteId: string;
+    lineId: string;
+    definition: LineDef;
+    source: LineSource;
+    version: number;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A registry row with its pending rows counted. */
+export interface LineRecordWithHealth extends LineRecord {
+    health: LineHealth;
+}
+export interface LineListQuery {
+    q?: string;
+    site?: string;
+    /** One line by id, with `site`. */
+    line?: string;
+    attention?: boolean;
+    sort?: keyof typeof LINE_ORDER;
+    limit?: number;
+    offset?: number;
+}
+export interface LineListPage {
+    lines: LineRecordWithHealth[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** What boot did with each code line, and the code lines it no longer declares. */
+export interface LineApplyReport {
+    applied: string[];
+    unchanged: string[];
+    dbOwned: string[];
+    orphans: string[];
+}
+/** A write that named a version the row no longer has. */
+export declare class LineVersionConflict extends Error {
+    readonly siteId: string;
+    readonly lineId: string;
+    readonly expected: number;
+    constructor(siteId: string, lineId: string, expected: number);
+}
+export declare const DEFAULT_LINE_PAGE = 50;
+export declare const MAX_LINE_PAGE = 200;
+/** The index's search text: everything a person might type to find the line. */
+export declare function searchTextOf(line: LineDef): string;
+/** Declare a line through the API: insert, or replace and advance its version. */
+export declare function declareApiLine(def: LineDef, expectedVersion?: number): Promise<LineRecord>;
+/**
+ * Apply one code line. Db-owned: insert if absent, otherwise leave the row
+ * and log drift. Code-owned: write when the definition differs, once.
+ */
+export declare function applyCodeLine(def: LineDef, codeOwned: boolean): Promise<'applied' | 'unchanged' | 'db-owned'>;
+/** Boot: apply every code line and report, naming code lines the registry still holds that code no longer declares. */
+export declare function applyDeclaredLines(lines: LineDef[], codeOwned: boolean): Promise<LineApplyReport>;
+export declare function getLine(siteId: string, lineId: string): Promise<LineRecord | null>;
+export declare function deleteLine(siteId: string, lineId: string): Promise<LineRecord | null>;
+/** Every enabled line, code and API alike: what a replica contends for. */
+export declare function listEnabledLines(): Promise<LineRecord[]>;
+/** One page of the index, searched and filtered in SQL, with each line's pending rows counted. */
+export declare function listLines(query?: LineListQuery): Promise<LineListPage>;
+/** One line with its pending rows counted, or null. */
+export declare function getLineWithHealth(siteId: string, lineId: string): Promise<LineRecordWithHealth | null>;
+export declare function listSites(): Promise<SiteSummary[]>;

package/build/services/machines/registry.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * The line registry: every line this deployment controls, in Postgres, so
+ * every replica contends for the same lines and the Lines index reads one
+ * list. Lines come from code (start({ machines })) and from the API; the
+ * configSource rules decide who wins at boot, the version says what changed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LINE_PAGE = exports.DEFAULT_LINE_PAGE = exports.LineVersionConflict = exports.LINE_SOURCE = void 0;
+exports.searchTextOf = searchTextOf;
+exports.declareApiLine = declareApiLine;
+exports.applyCodeLine = applyCodeLine;
+exports.applyDeclaredLines = applyDeclaredLines;
+exports.getLine = getLine;
+exports.deleteLine = deleteLine;
+exports.listEnabledLines = listEnabledLines;
+exports.listLines = listLines;
+exports.getLineWithHealth = getLineWithHealth;
+exports.listSites = listSites;
+const node_util_1 = require("node:util");
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+const line_1 = require("../../lib/machines/line");
+const registry_sql_1 = require("./registry-sql");
+Object.defineProperty(exports, "LINE_SOURCE", { enumerable: true, get: function () { return registry_sql_1.LINE_SOURCE; } });
+/** A write that named a version the row no longer has. */
+class LineVersionConflict extends Error {
+    constructor(siteId, lineId, expected) {
+        super(`line ${siteId}/${lineId} is not at version ${expected}`);
+        this.siteId = siteId;
+        this.lineId = lineId;
+        this.expected = expected;
+        this.name = 'LineVersionConflict';
+    }
+}
+exports.LineVersionConflict = LineVersionConflict;
+exports.DEFAULT_LINE_PAGE = 50;
+exports.MAX_LINE_PAGE = 200;
+const LOG = '[lt-machines]';
+/** The index's search text: everything a person might type to find the line. */
+function searchTextOf(line) {
+    const words = [line.siteId, line.lineId];
+    for (const m of line.machines)
+        words.push(m.machineId, m.process, (0, line_1.machineRole)(m), m.address ?? '');
+    return [...new Set(words.filter(Boolean).map((w) => w.toLowerCase()))].join(' ');
+}
+function toRecord(row) {
+    return {
+        siteId: row.site_id, lineId: row.line_id, definition: row.definition, source: row.source,
+        version: row.version, enabled: row.enabled,
+        createdAt: new Date(row.created_at).toISOString(), updatedAt: new Date(row.updated_at).toISOString(),
+    };
+}
+function toHealth(row) {
+    const machines = Array.isArray(row.definition?.machines) ? row.definition.machines.length : 0;
+    return {
+        machines, offline: row.offline, quiet: row.quiet, alarms: row.alarms, people: row.people,
+        handoff: row.handoff, command: row.command, attention: row.attention === true,
+    };
+}
+function keyOf(siteId, lineId) {
+    return `${siteId}/${lineId}`;
+}
+/** A LIKE pattern that matches the text anywhere, with the person's wildcards taken literally. */
+function likePattern(q) {
+    return `%${q.trim().toLowerCase().replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+}
+/** Declare a line through the API: insert, or replace and advance its version. */
+async function declareApiLine(def, expectedVersion) {
+    const line = (0, line_1.validateLine)(def);
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.UPSERT_API_LINE, [
+        line.siteId, line.lineId, JSON.stringify(line), searchTextOf(line), expectedVersion ?? null,
+    ]);
+    if (!rows.length)
+        throw new LineVersionConflict(line.siteId, line.lineId, expectedVersion);
+    return toRecord(rows[0]);
+}
+/**
+ * Apply one code line. Db-owned: insert if absent, otherwise leave the row
+ * and log drift. Code-owned: write when the definition differs, once.
+ */
+async function applyCodeLine(def, codeOwned) {
+    const line = (0, line_1.validateLine)(def);
+    const params = [line.siteId, line.lineId, JSON.stringify(line), searchTextOf(line)];
+    const { rows } = await (0, db_1.getPool)().query(codeOwned ? registry_sql_1.APPLY_CODE_LINE : registry_sql_1.SEED_CODE_LINE, params);
+    if (rows.length)
+        return 'applied';
+    if (codeOwned)
+        return 'unchanged';
+    const existing = await getLine(line.siteId, line.lineId);
+    if (existing && !(0, node_util_1.isDeepStrictEqual)(existing.definition, line)) {
+        logger_1.loggerRegistry.warn(`${LOG} line ${keyOf(line.siteId, line.lineId)} differs from its declaration; the registry row stands (db-owned)`);
+    }
+    return 'db-owned';
+}
+/** Boot: apply every code line and report, naming code lines the registry still holds that code no longer declares. */
+async function applyDeclaredLines(lines, codeOwned) {
+    const report = { applied: [], unchanged: [], dbOwned: [], orphans: [] };
+    const declared = new Set();
+    for (const line of lines) {
+        const key = keyOf(line.siteId, line.lineId);
+        declared.add(key);
+        const outcome = await applyCodeLine(line, codeOwned);
+        if (outcome === 'applied')
+            report.applied.push(key);
+        else if (outcome === 'unchanged')
+            report.unchanged.push(key);
+        else
+            report.dbOwned.push(key);
+    }
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.LIST_CODE_LINES);
+    report.orphans = rows.map((r) => keyOf(r.site_id, r.line_id)).filter((k) => !declared.has(k));
+    const counts = `applied ${report.applied.length}, unchanged ${report.unchanged.length}, db-owned ${report.dbOwned.length}`;
+    if (report.orphans.length)
+        logger_1.loggerRegistry.warn(`${LOG} lines: ${counts}, declared in code before and not now: [${report.orphans.join(', ')}]`);
+    else
+        logger_1.loggerRegistry.info(`${LOG} lines: ${counts}`);
+    return report;
+}
+async function getLine(siteId, lineId) {
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.GET_LINE, [siteId, lineId]);
+    return rows.length ? toRecord(rows[0]) : null;
+}
+async function deleteLine(siteId, lineId) {
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.DELETE_LINE, [siteId, lineId]);
+    return rows.length ? toRecord(rows[0]) : null;
+}
+/** Every enabled line, code and API alike: what a replica contends for. */
+async function listEnabledLines() {
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.LIST_ENABLED_LINES);
+    return rows.map(toRecord);
+}
+/** One page of the index, searched and filtered in SQL, with each line's pending rows counted. */
+async function listLines(query = {}) {
+    const limit = Math.min(Math.max(1, Math.floor(query.limit ?? exports.DEFAULT_LINE_PAGE)), exports.MAX_LINE_PAGE);
+    const offset = Math.max(0, Math.floor(query.offset ?? 0));
+    const order = registry_sql_1.LINE_ORDER[query.sort ?? 'attention'];
+    if (!order)
+        throw new Error(`sort must be one of ${Object.keys(registry_sql_1.LINE_ORDER).join(', ')}`);
+    const { rows } = await (0, db_1.getPool)().query((0, registry_sql_1.listLinesSql)(order), [
+        [...registry_sql_1.HEALTH_ROW_TYPES], query.q?.trim() ? likePattern(query.q) : null, query.site || null,
+        query.attention ?? null, limit, offset, query.line || null,
+    ]);
+    return {
+        lines: rows.map((r) => ({ ...toRecord(r), health: toHealth(r) })),
+        total: rows.length ? Number(rows[0].total) : 0,
+        limit, offset,
+    };
+}
+/** One line with its pending rows counted, or null. */
+async function getLineWithHealth(siteId, lineId) {
+    const page = await listLines({ site: siteId, line: lineId, limit: 1 });
+    return page.lines[0] ?? null;
+}
+async function listSites() {
+    const { rows } = await (0, db_1.getPool)().query(registry_sql_1.LIST_SITES, [[...registry_sql_1.HEALTH_ROW_TYPES]]);
+    return rows.map((r) => ({ siteId: r.site_id, lines: r.lines, attention: r.attention }));
+}

package/build/services/machines/rows.js

@@ -15,6 +15,13 @@ const str = (v) => (v === undefined || v === null || v === '' ? null : String(v)
 function paramsOf(v) {
     return v && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
 }
+/** Named references with string values; other values are dropped, and an empty set is no refs. */
+function refsOf(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return undefined;
+    const refs = Object.fromEntries(Object.entries(v).filter((e) => typeof e[1] === 'string'));
+    return Object.keys(refs).length ? refs : undefined;
+}
 function artifactOf(v) {
     if (!v || typeof v.url !== 'string' || !v.url || typeof v.sha256 !== 'string' || !v.sha256)
         return undefined;
@@ -36,9 +43,10 @@ function unitsOf(v) {
         const artifact = artifactOf(u.artifact);
         const artifacts = artifactsOf(u.artifacts);
         const parameters = paramsOf(u.parameters);
+        const refs = refsOf(u.refs);
         return {
             unitId: String(u.unitId), carrierId: str(u.carrierId),
-            ...(artifact ? { artifact } : {}), ...(artifacts ? { artifacts } : {}), ...(parameters ? { parameters } : {}),
+            ...(artifact ? { artifact } : {}), ...(artifacts ? { artifacts } : {}), ...(parameters ? { parameters } : {}), ...(refs ? { refs } : {}),
         };
     });
 }
@@ -63,6 +71,7 @@ function readHandoffFacets(md = {}) {
         artifactSha256: str(md.artifactSha256),
         attempt: Number(md.attempt ?? 1),
         ...(paramsOf(md.parameters) ? { parameters: paramsOf(md.parameters) } : {}),
+        ...(refsOf(md.refs) ? { refs: refsOf(md.refs) } : {}),
     };
 }
 exports.standardRows = {

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

@@ -3,13 +3,17 @@
  * controls, one replica leads (an advisory lock), makes sure the line's bot
  * accounts exist, and runs the gateway: escalation events in, machine
  * messages in, verbs performed in process as each machine. Workflows never
- * see any of it; their rows are resolved the way a form resolves them.
+ * see any of it; their rows are resolved the way a form resolves them. The
+ * surface also describes its lines for the dashboard: every replica lists
+ * them, and the leader of a line projects it.
  */
 import type { CallbackEventAdapter } from '../../lib/events/callback';
-import type { LineDef } from '../../lib/machines/line';
+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 MachineLineConfig } from './config';
 import { type GatewayLog } from './gateway/log';
-import type { LineCodec } from '../../lib/machines/protocol';
 import type { HandoffRowAdapter } from './rows';
 type Env = Record<string, string | undefined>;
 export interface MachineSurfaceOptions {
@@ -21,13 +25,49 @@ export interface MachineSurfaceOptions {
     codec?: LineCodec;
     rows?: HandoffRowAdapter;
 }
+/** 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. */
+export interface LineSurface {
+    /** Every declared line, on every replica. */
+    describeLines(): LineSummary[];
+    /** The line as its leader sees it; null when this replica is not leading it, or the line is not declared. */
+    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 declared line, or undefined. */
+    findLine(siteId: string, lineId: string): LineDef | undefined;
+    /** The ops a machine-command row on this line may ask for. */
+    commandOps(siteId: string, lineId: string): string[];
+    /** Run a line on this replica: started, replaced when its definition changed, or unchanged. */
+    declare(line: LineDef): Promise<DeclareOutcome>;
+    /** Stop running a line on this replica; false when it was not running. */
+    retire(siteId: string, lineId: string): Promise<boolean>;
+}
+export type DeclareOutcome = 'started' | 'replaced' | 'unchanged';
 /** Inside Long Tail the gateway reads escalation events in process. */
 export declare function surfaceConfig(env: Env): MachineLineConfig;
-export declare class MachineSurface {
+/** The line as every replica can describe it: its machines, roles, declared addresses and the codec's own ops. */
+export declare function summarizeLine(line: LineDef, codec: Pick<LineCodec, 'rowOps'>): LineSummary;
+/** The ops a machine-command row may ask for: the control ops, a snapshot, and the codec's own. */
+export declare function commandOpsOf(codec: Pick<LineCodec, 'rowOps'>): string[];
+export declare class MachineSurface implements LineSurface {
+    private readonly config;
+    private readonly opts;
+    private readonly log;
     private readonly runs;
     private constructor();
-    /** Validate the configuration, then contend for every line in the background. */
+    /** Validate the configuration, then contend for every line in the background. The registry may add lines later. */
     static start(opts: MachineSurfaceOptions): MachineSurface;
     stop(): Promise<void>;
+    declare(line: LineDef): Promise<DeclareOutcome>;
+    retire(siteId: string, lineId: string): Promise<boolean>;
+    describeLines(): LineSummary[];
+    describeLine(siteId: string, lineId: string): LineView | null;
+    inspect(siteId: string, lineId: string, probe: WireProbe): InspectResult | null;
+    findLine(siteId: string, lineId: string): LineDef | undefined;
+    commandOps(siteId: string, lineId: string): string[];
+    private begin;
+    private run;
 }
 export {};