@hotmeshio/long-tail 0.27.0 → 0.28.1

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/roles.d.ts

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

package/build/services/machines/roles.js

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

package/build/services/machines/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/select.d.ts

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

package/build/services/machines/select.js

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

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

@@ -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, WireEvent, WireWindowQuery } 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 {
@@ -19,15 +23,60 @@ export interface MachineSurfaceOptions {
     callbacks?: CallbackEventAdapter;
     log?: GatewayLog;
     codec?: LineCodec;
+    /** A codec for one line, keyed `<siteId>/<lineId>`; every other line uses `codec`. */
+    codecs?: Record<string, LineCodec>;
     rows?: HandoffRowAdapter;
 }
+/** The codec a line runs on: its own, the surface's, or the generic line protocol. */
+export declare function codecFor(opts: Pick<MachineSurfaceOptions, 'codec' | 'codecs'>, config: MachineLineConfig, line: LineDef): LineCodec;
+/** A message to dry-run against a line. */
+export type WireProbe = Pick<InboundMessage, 'topic' | 'payload' | 'retained'>;
+/** What settings and the API read of the surface. */
+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 leader's last wire events, newest first; null when this replica is not leading the line. */
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
+    /** The declared line, or undefined. */
+    findLine(siteId: string, lineId: string): LineDef | undefined;
+    /** The ops a machine-command row on this line may ask for. */
+    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;
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
+    findLine(siteId: string, lineId: string): LineDef | undefined;
+    commandOps(siteId: string, lineId: string): string[];
+    /** The codecs every line on a site runs, so one site's streams keep all their subjects. */
+    codecsOnSite(siteId: string): LineCodec[];
+    private begin;
+    private run;
 }
 export {};

package/build/services/machines/surface.js

@@ -4,11 +4,19 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineSurface = void 0;
+exports.codecFor = codecFor;
 exports.surfaceConfig = surfaceConfig;
+exports.summarizeLine = summarizeLine;
+exports.commandOpsOf = commandOpsOf;
+const node_util_1 = require("node:util");
+const line_1 = require("../../lib/machines/line");
+const protocol_1 = require("../../lib/machines/protocol");
 const config_1 = require("./config");
 const api_escalations_1 = require("./gateway/api-escalations");
 const gateway_1 = require("./gateway/gateway");
@@ -16,6 +24,10 @@ const log_1 = require("./gateway/log");
 const identities_1 = require("./identities");
 const leadership_1 = require("./leadership");
 const select_1 = require("./select");
+/** The codec a line runs on: its own, the surface's, or the generic line protocol. */
+function codecFor(opts, config, line) {
+    return opts.codecs?.[keyOf(line.siteId, line.lineId)] ?? opts.codec ?? (0, select_1.defaultCodec)(config, line);
+}
 /** Inside Long Tail the gateway reads escalation events in process. */
 function surfaceConfig(env) {
     const transport = env.MACHINE_TRANSPORT;
@@ -24,20 +36,45 @@ function surfaceConfig(env) {
     }
     return (0, config_1.loadMachineLineConfig)({ ...env, MACHINE_ESCALATION_FEED: env.MACHINE_ESCALATION_FEED ?? config_1.ESCALATION_FEED.IN_PROCESS });
 }
+/** The line as every replica can describe it: its machines, roles, declared addresses and the codec's own ops. */
+function summarizeLine(line, codec) {
+    const rowOps = (0, protocol_1.declaredRowOps)(codec);
+    return {
+        siteId: line.siteId, lineId: line.lineId,
+        machines: line.machines.map((m) => {
+            const learned = (0, line_1.learnsAddress)(line, m.machineId);
+            return {
+                machineId: m.machineId, process: m.process, role: (0, line_1.machineRole)(m),
+                address: learned ? null : m.address ?? m.machineId, addressing: learned ? 'learned' : 'declared',
+                ...(rowOps.length ? { rowOps } : {}),
+            };
+        }),
+    };
+}
+/** The ops a machine-command row may ask for: the control ops, a snapshot, and the codec's own. */
+function commandOpsOf(codec) {
+    return [...new Set([...protocol_1.CONTROL_OPS, protocol_1.OP.SNAPSHOT, ...(0, protocol_1.declaredRowOps)(codec)])];
+}
 class LineRun {
-    constructor(line, config, opts, log) {
+    constructor(line, config, opts, log, 
+    /** The codecs of every line on this line's site, read when the gateway starts. */
+    siteCodecs = () => []) {
         this.line = line;
         this.config = config;
         this.opts = opts;
         this.log = log;
+        this.siteCodecs = siteCodecs;
+        this.ready = false;
         this.stopped = false;
         this.leadership = new leadership_1.LineLeadership(`lt-machine-line:${line.siteId}/${line.lineId}`);
+        this.codec = codecFor(opts, config, line);
     }
     start() {
         const where = { site: this.line.siteId, line: this.line.lineId };
         this.log.info(log_1.GATEWAY_LOG.STANDBY, where);
         this.leadership.run(() => (this.leading = this.lead()), async (err) => {
             this.log.warn(log_1.GATEWAY_LOG.LEADERSHIP_LOST, { ...where, error: err.message });
+            this.ready = false;
             await this.gateway?.stop();
             this.gateway = undefined;
         }).catch((err) => this.log.error(log_1.GATEWAY_LOG.START_FAILED, { ...where, error: err.message }));
@@ -45,10 +82,15 @@ class LineRun {
     /** A gateway still starting finishes first, so none is left running after stop. */
     async stop() {
         this.stopped = true;
+        this.ready = false;
         await this.leading?.catch(() => undefined);
         await this.gateway?.stop();
         await this.leadership.stop();
     }
+    /** The gateway, once it leads the line. */
+    leader() {
+        return this.ready ? this.gateway : undefined;
+    }
     async lead() {
         // 1. Identities, 2. gateway on the line's bus and feed, 3. reconcile and consume (gateway.start)
         const ids = await (0, identities_1.ensureLineBots)(this.line);
@@ -60,10 +102,9 @@ class LineRun {
                 throw new Error(`no bot for "${as}" on ${this.line.siteId}/${this.line.lineId}`);
             return id;
         };
-        const { config, line } = this;
-        const codec = this.opts.codec ?? (0, select_1.defaultCodec)(config, line);
+        const { config, line, codec } = this;
         this.gateway = new gateway_1.MachineGateway({
-            bus: (0, select_1.createMachineBus)(config, line, codec),
+            bus: (0, select_1.createMachineBus)(config, line, codec, undefined, this.siteCodecs()),
             codec,
             rows: this.opts.rows,
             feed: (0, select_1.createEscalationFeed)(config, line, this.opts.callbacks),
@@ -74,31 +115,86 @@ class LineRun {
             settings: {
                 topicRoot: config.topicRoot, replyTimeoutMs: config.replyTimeoutMs, dispatchAttempts: config.dispatchAttempts,
                 offlineDebounceMs: config.offlineDebounceMs, dispatchTtlMs: config.dispatchTtlMs, quietMs: config.quietMs,
-                receiptDelayMs: config.receiptDelayMs, lifecycle: config.lifecycle, progressStep: config.progressStep,
+                receiptDelayMs: config.receiptDelayMs, lifecycle: config.lifecycle, progressStep: config.progressStep, wireTelemetry: config.wireTelemetry,
+                wireWindow: config.wireWindow,
             },
         });
         await this.gateway.start();
+        this.ready = true;
         this.log.info(log_1.GATEWAY_LOG.LEADING, { site: line.siteId, line: line.lineId });
     }
 }
 class MachineSurface {
-    constructor(runs) {
-        this.runs = runs;
+    constructor(config, opts, log) {
+        this.config = config;
+        this.opts = opts;
+        this.log = log;
+        this.runs = new Map();
     }
-    /** 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) {
-        if (!opts.lines.length)
-            throw new Error('start({ machines }) needs at least one line');
         const config = surfaceConfig(opts.env ?? process.env);
-        const log = opts.log ?? log_1.consoleLog;
-        const runs = opts.lines.map((line) => new LineRun(line, config, opts, log));
-        for (const run of runs)
-            run.start();
-        return new MachineSurface(runs);
+        const surface = new MachineSurface(config, opts, opts.log ?? log_1.consoleLog);
+        for (const line of opts.lines)
+            surface.begin(line);
+        return surface;
     }
     async stop() {
-        for (const run of this.runs)
+        for (const run of this.runs.values())
             await run.stop();
+        this.runs.clear();
+    }
+    async declare(line) {
+        const current = this.run(line.siteId, line.lineId);
+        if (current && (0, node_util_1.isDeepStrictEqual)(current.line, line))
+            return 'unchanged';
+        if (current)
+            await current.stop();
+        this.begin(line);
+        return current ? 'replaced' : 'started';
+    }
+    async retire(siteId, lineId) {
+        const current = this.run(siteId, lineId);
+        if (!current)
+            return false;
+        this.runs.delete(keyOf(siteId, lineId));
+        await current.stop();
+        return true;
+    }
+    describeLines() {
+        return [...this.runs.values()].map((run) => summarizeLine(run.line, run.codec));
+    }
+    describeLine(siteId, lineId) {
+        const gateway = this.run(siteId, lineId)?.leader();
+        return gateway ? gateway.state.project(this.findLine(siteId, lineId)) : null;
+    }
+    inspect(siteId, lineId, probe) {
+        return this.run(siteId, lineId)?.leader()?.inspect(probe) ?? null;
+    }
+    wire(siteId, lineId, query = {}) {
+        return this.run(siteId, lineId)?.leader()?.window.read(query) ?? null;
+    }
+    findLine(siteId, lineId) {
+        return this.run(siteId, lineId)?.line;
+    }
+    commandOps(siteId, lineId) {
+        const run = this.run(siteId, lineId);
+        return run ? commandOpsOf(run.codec) : [];
+    }
+    /** The codecs every line on a site runs, so one site's streams keep all their subjects. */
+    codecsOnSite(siteId) {
+        return [...new Set([...this.runs.values()].filter((run) => run.line.siteId === siteId).map((run) => run.codec))];
+    }
+    begin(line) {
+        const run = new LineRun(line, this.config, this.opts, (0, log_1.composeLogs)(this.log, (0, log_1.eventsLog)(line)), () => this.codecsOnSite(line.siteId));
+        this.runs.set(keyOf(line.siteId, line.lineId), run);
+        run.start();
+    }
+    run(siteId, lineId) {
+        return this.runs.get(keyOf(siteId, lineId));
     }
 }
 exports.MachineSurface = MachineSurface;
+function keyOf(siteId, lineId) {
+    return `${siteId}/${lineId}`;
+}

package/build/start/apply-report.d.ts

@@ -18,7 +18,7 @@ export interface SurfaceReport {
 export declare function newSurfaceReport(): SurfaceReport;
 /** Record one entry's outcome on the surface report. */
 export declare function recordOutcome(report: SurfaceReport, name: string, outcome: ApplyOutcome): void;
-export declare function withConfigLock<T>(fn: () => Promise<T>): Promise<T>;
+export { withConfigLock } from '../lib/db/config-lock';
 /**
  * One boot line per surface. Warn level when orphans exist so operators see
  * "declared set no longer matches the DB" without grepping.