@hotmeshio/long-tail 0.25.4 → 0.26.0

package/build/services/machines/identities.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Identities inside Long Tail: each machine is a bot account holding its
+ * station roles, so rows it claims and resolves name the machine. Bots are
+ * found by name and given any role they are missing; nothing is removed. A
+ * person's account under a bot's name stops the line from starting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotAddressBook = exports.ADDRESS_PROPERTY = void 0;
+exports.ensureLineBots = ensureLineBots;
+const iam_1 = require("../iam");
+const user_1 = require("../user");
+const actions_1 = require("./gateway/actions");
+const provision_1 = require("./gateway/provision");
+/** The user property on a station's bot account that holds the address its machine registered. */
+exports.ADDRESS_PROPERTY = 'machineAddress';
+const MEMBER = 'member';
+const BOT = 'bot';
+/** Make sure every bot the line needs exists with its roles; returns actor → user id. */
+async function ensureLineBots(line) {
+    const ids = new Map();
+    for (const identity of (0, provision_1.lineIdentities)(line)) {
+        const existing = await (0, user_1.getUserByExternalId)(identity.botName);
+        if (existing && existing.account_type !== BOT) {
+            throw new Error(`"${identity.botName}" belongs to a person's account; the gateway acts only as bot accounts`);
+        }
+        if (!existing) {
+            const bot = await (0, iam_1.createBot)({
+                name: identity.botName,
+                description: `Machine line ${line.siteId}/${line.lineId}: ${identity.actor}`,
+                roles: identity.roles.map((role) => ({ role, type: MEMBER })),
+            });
+            ids.set(identity.actor, bot.id);
+            continue;
+        }
+        const held = new Set((await (0, iam_1.getBotRoles)(existing.id)).map((r) => r.role));
+        for (const role of identity.roles.filter((r) => !held.has(r)))
+            await (0, iam_1.addBotRole)(existing.id, role, MEMBER);
+        ids.set(identity.actor, existing.id);
+    }
+    return ids;
+}
+/**
+ * Learned addresses kept on each station's bot account, so a replica that
+ * takes the line over sends to the machines the line already knows. An address
+ * belongs to one station: binding it to a station clears it from any other.
+ */
+class BotAddressBook {
+    constructor(bots) {
+        this.bots = bots;
+    }
+    async load() {
+        const bound = new Map();
+        for (const [machineId, address] of await this.read())
+            if (address)
+                bound.set(machineId, address);
+        return bound;
+    }
+    async bind(machineId, address) {
+        const id = this.bots.get(machineId);
+        if (!id)
+            throw new Error(`no bot for station "${machineId}"`);
+        for (const [other, held] of await this.read()) {
+            if (other !== machineId && held === address)
+                await (0, user_1.patchUserProperties)(this.bots.get(other), { remove: [exports.ADDRESS_PROPERTY] });
+        }
+        await (0, user_1.patchUserProperties)(id, { set: { [exports.ADDRESS_PROPERTY]: address } });
+    }
+    async read() {
+        const stations = [...this.bots.entries()].filter(([actor]) => actor !== actions_1.CONTROLLER);
+        return Promise.all(stations.map(async ([machineId, id]) => {
+            const address = (await (0, user_1.getUser)(id))?.metadata?.[exports.ADDRESS_PROPERTY];
+            return [machineId, typeof address === 'string' ? address : undefined];
+        }));
+    }
+}
+exports.BotAddressBook = BotAddressBook;

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

@@ -0,0 +1,11 @@
+export * from './config';
+export * from './contracts';
+export * from './commands';
+export * from './forms';
+export * from './select';
+export * from './gateway';
+export * from './roles';
+export * from './identities';
+export * from './surface';
+export * from './rows';
+export * from '../../lib/machines';

package/build/services/machines/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config"), exports);
+__exportStar(require("./contracts"), exports);
+__exportStar(require("./commands"), exports);
+__exportStar(require("./forms"), exports);
+__exportStar(require("./select"), exports);
+__exportStar(require("./gateway"), exports);
+__exportStar(require("./roles"), exports);
+__exportStar(require("./identities"), exports);
+__exportStar(require("./surface"), exports);
+__exportStar(require("./rows"), exports);
+__exportStar(require("../../lib/machines"), exports);

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

@@ -0,0 +1,22 @@
+/**
+ * One gateway per line across every replica. Each line contends for a
+ * Postgres advisory lock on a dedicated connection; `pg_advisory_lock`
+ * waits on the server, so standby replicas hold no timers and the next one
+ * takes over the moment the leader's session ends.
+ */
+export declare class LineLeadership {
+    readonly key: string;
+    private client?;
+    private stopped;
+    private leading;
+    constructor(key: string);
+    /**
+     * Wait for the lock, then call `lead`. When leading fails or the
+     * connection drops, the lock is released, `lost` runs, and the line
+     * contends again after a pause.
+     */
+    run(lead: () => Promise<void>, lost: (err: Error) => Promise<void>): Promise<void>;
+    private leadOnce;
+    /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
+    stop(): Promise<void>;
+}

package/build/services/machines/leadership.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * One gateway per line across every replica. Each line contends for a
+ * Postgres advisory lock on a dedicated connection; `pg_advisory_lock`
+ * waits on the server, so standby replicas hold no timers and the next one
+ * takes over the moment the leader's session ends.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LineLeadership = void 0;
+const db_1 = require("../../lib/db");
+const LOCK_SQL = 'SELECT pg_advisory_lock(hashtext($1))';
+const RETRY_MS = 5_000;
+const UNLOCK_SQL = 'SELECT pg_advisory_unlock(hashtext($1))';
+class LineLeadership {
+    constructor(key) {
+        this.key = key;
+        this.stopped = false;
+        this.leading = false;
+    }
+    /**
+     * Wait for the lock, then call `lead`. When leading fails or the
+     * connection drops, the lock is released, `lost` runs, and the line
+     * contends again after a pause.
+     */
+    async run(lead, lost) {
+        while (!this.stopped) {
+            const err = await this.leadOnce(lead);
+            if (this.stopped)
+                return;
+            await lost(err);
+            await new Promise((r) => setTimeout(r, RETRY_MS));
+        }
+    }
+    async leadOnce(lead) {
+        const client = await (0, db_1.getPool)().connect();
+        this.client = client;
+        const dropped = new Promise((resolve) => client.once('error', resolve));
+        try {
+            await client.query(LOCK_SQL, [this.key]);
+            this.leading = true;
+            await lead();
+            return await dropped;
+        }
+        catch (err) {
+            return err;
+        }
+        finally {
+            this.leading = false;
+            if (!this.stopped) {
+                this.client = undefined;
+                client.release(true);
+            }
+        }
+    }
+    /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
+    async stop() {
+        this.stopped = true;
+        const client = this.client;
+        this.client = undefined;
+        if (!client)
+            return;
+        if (!this.leading) {
+            client.release(true);
+            return;
+        }
+        try {
+            await client.query(UNLOCK_SQL, [this.key]);
+            client.release();
+        }
+        catch {
+            client.release(true);
+        }
+    }
+}
+exports.LineLeadership = LineLeadership;

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

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+import type { LTRoleConfig } from '../../types/startup';
+import { type LineDef } from '../../lib/machines/line';
+export declare function machineRoleConfigs(line: LineDef): LTRoleConfig[];
+/** The host's declarations first; line roles only where the host declared none. */
+export declare function withMachineRoles(declared: LTRoleConfig[] | undefined, lines: LineDef[]): LTRoleConfig[];

package/build/services/machines/roles.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.machineRoleConfigs = machineRoleConfigs;
+exports.withMachineRoles = withMachineRoles;
+const line_1 = require("../../lib/machines/line");
+const forms_1 = require("./forms");
+const BOARD = { sla_minutes: 10, target_per_hour: 60, priority_threshold_minutes: 10, ops_visible: true };
+function machineRoleConfigs(line) {
+    const stations = [...new Map(line.machines.map((m) => [(0, line_1.machineRole)(m), m])).values()];
+    const chain = stations.map((m, i) => ({
+        role: (0, line_1.machineRole)(m),
+        title: `Line: ${m.process}`,
+        description: `Units handed to ${m.process}; the machine claims and resolves each handoff.`,
+        ...(i > 0 ? { parent_role: (0, line_1.machineRole)(stations[i - 1]) } : {}),
+        form_schema: forms_1.HANDOFF_FORM_SCHEMA,
+        enforce_schema: false,
+        ...BOARD,
+    }));
+    return [
+        ...chain,
+        {
+            role: (0, line_1.exitRole)(line),
+            title: 'Line exit',
+            description: 'Finished units leaving the line; a person confirms they are in hand.',
+            ...(chain.length ? { parent_role: chain[chain.length - 1].role } : {}),
+            upstream_roles: [(0, line_1.operatorRole)(line)],
+            form_schema: forms_1.HANDOFF_FORM_SCHEMA,
+            enforce_schema: false,
+            ...BOARD,
+        },
+        {
+            role: (0, line_1.operatorRole)(line),
+            title: 'Line operator',
+            description: 'Failed handoffs, stopping alarms, and machines that went dark or quiet.',
+            form_schema: forms_1.OPERATOR_FORM_SCHEMA,
+            enforce_schema: true,
+            ...BOARD,
+        },
+    ];
+}
+/** The host's declarations first; line roles only where the host declared none. */
+function withMachineRoles(declared = [], lines) {
+    const out = [...declared];
+    const seen = new Set(out.map((r) => r.role));
+    for (const line of lines) {
+        for (const role of machineRoleConfigs(line)) {
+            if (seen.has(role.role))
+                continue;
+            seen.add(role.role);
+            out.push(role);
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Which escalation rows are machine handoffs, and what each one asks for.
+ * The workflow parks an ordinary row; this adapter reads it into the task
+ * the gateway dispatches. The standard adapter reads the handoff facets
+ * (contracts.ts); a host whose rows carry its own facets supplies its own,
+ * so neither the workflow nor its rows change to be resolved by a machine.
+ */
+import type { LineDef } from '../../lib/machines/line';
+import { type HandoffFacets } from './contracts';
+/** The parts of an escalation row the adapter reads. */
+export interface EscalationRowView {
+    id: string;
+    role: string;
+    type?: string;
+    subtype?: string;
+    metadata?: Record<string, any>;
+}
+/** Open rows to read when the gateway starts leading a line. */
+export interface OpenRowQuery {
+    type?: string;
+    role?: string;
+}
+export interface HandoffRowAdapter {
+    openRows(line: LineDef): OpenRowQuery[];
+    /** The handoff a row asks for, or null when it is not a machine handoff. */
+    toHandoff(row: EscalationRowView): HandoffFacets | null;
+}
+/** Read standard handoff facets; null when the line, job or units are missing. */
+export declare function readHandoffFacets(md?: Record<string, any>): HandoffFacets | null;
+export declare const standardRows: HandoffRowAdapter;

package/build/services/machines/rows.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Which escalation rows are machine handoffs, and what each one asks for.
+ * The workflow parks an ordinary row; this adapter reads it into the task
+ * the gateway dispatches. The standard adapter reads the handoff facets
+ * (contracts.ts); a host whose rows carry its own facets supplies its own,
+ * so neither the workflow nor its rows change to be resolved by a machine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardRows = void 0;
+exports.readHandoffFacets = readHandoffFacets;
+const contracts_1 = require("./contracts");
+const str = (v) => (v === undefined || v === null || v === '' ? null : String(v));
+/** A plain object of parameters; anything else is not parameters. */
+function paramsOf(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+function artifactOf(v) {
+    return v && typeof v.url === 'string' && v.url && typeof v.sha256 === 'string' && v.sha256 ? { url: v.url, sha256: v.sha256 } : undefined;
+}
+function unitsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((u) => u && u.unitId).map((u) => {
+        const artifact = artifactOf(u.artifact);
+        const parameters = paramsOf(u.parameters);
+        return { unitId: String(u.unitId), carrierId: str(u.carrierId), ...(artifact ? { artifact } : {}), ...(parameters ? { parameters } : {}) };
+    });
+}
+/** Read standard handoff facets; null when the line, job or units are missing. */
+function readHandoffFacets(md = {}) {
+    const units = unitsOf(md.units);
+    if (!md.siteId || !md.lineId || !md.jobId || !units.length)
+        return null;
+    return {
+        siteId: String(md.siteId),
+        lineId: String(md.lineId),
+        units,
+        jobId: String(md.jobId),
+        senderJobId: str(md.senderJobId),
+        orderRef: String(md.orderRef ?? ''),
+        fromMachine: str(md.fromMachine),
+        toMachine: str(md.toMachine),
+        recipeId: str(md.recipeId),
+        recipeVersion: str(md.recipeVersion),
+        process: str(md.process),
+        artifactUrl: str(md.artifactUrl),
+        artifactSha256: str(md.artifactSha256),
+        attempt: Number(md.attempt ?? 1),
+        ...(paramsOf(md.parameters) ? { parameters: paramsOf(md.parameters) } : {}),
+    };
+}
+exports.standardRows = {
+    openRows: () => [{ type: contracts_1.ROW_TYPE.HANDOFF }],
+    toHandoff: (row) => (row.type === contracts_1.ROW_TYPE.HANDOFF ? readHandoffFacets(row.metadata) : null),
+};

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

@@ -0,0 +1,18 @@
+/**
+ * Transport selection from config. The memory transport only exists inside
+ * one process (tests build it directly), so asking for it here throws, as
+ * does any mode missing what it needs.
+ */
+import { type MachineLineConfig } from './config';
+import { type LineDef } from '../../lib/machines/line';
+import { type LineCodec } from '../../lib/machines/protocol';
+import type { CallbackEventAdapter } from '../../lib/events/callback';
+import type { EscalationFeed, MachineBus, MachineLink } from '../../lib/machines/transport/delivery';
+/** The codec for a line when the host supplies none: the line protocol under MACHINE_TOPIC_ROOT. */
+export declare function defaultCodec(config: MachineLineConfig, line?: LineDef): LineCodec;
+/** The gateway's view of every machine on the line. */
+export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: 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. */
+export declare function createLinkFactory(config: MachineLineConfig): () => MachineLink;

package/build/services/machines/select.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Transport selection from config. The memory transport only exists inside
+ * one process (tests build it directly), so asking for it here throws, as
+ * does any mode missing what it needs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCodec = defaultCodec;
+exports.createMachineBus = createMachineBus;
+exports.createEscalationFeed = createEscalationFeed;
+exports.createLinkFactory = createLinkFactory;
+const config_1 = require("./config");
+const line_1 = require("../../lib/machines/line");
+const protocol_1 = require("../../lib/machines/protocol");
+const mqtt_bus_1 = require("../../lib/machines/transport/mqtt-bus");
+const mqtt_link_1 = require("../../lib/machines/transport/mqtt-link");
+const nats_bus_1 = require("../../lib/machines/transport/nats-bus");
+const callback_feed_1 = require("../../lib/machines/transport/callback-feed");
+const nats_feed_1 = require("../../lib/machines/transport/nats-feed");
+const IN_PROCESS_ONLY = 'lives inside one process; build MemoryMachineBus and MemoryEscalationFeed directly';
+function mqttOf(config) {
+    if (!config.mqtt)
+        throw new Error(`MACHINE_TRANSPORT=${config.transport} has no MQTT endpoint (MACHINE_MQTT_URL)`);
+    return config.mqtt;
+}
+/** The codec for a line when the host supplies none: the line protocol under MACHINE_TOPIC_ROOT. */
+function defaultCodec(config, line) {
+    return (0, protocol_1.genericCodec)({ root: config.topicRoot, line });
+}
+/** The gateway's view of every machine on the line. */
+function createMachineBus(config, line, codec = defaultCodec(config, line)) {
+    switch (config.transport) {
+        case config_1.MACHINE_TRANSPORT.NATS:
+            return new nats_bus_1.NatsMachineBus({
+                natsUrl: config.siteNatsUrl, user: config.siteNatsUser, password: config.siteNatsPassword,
+                mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec,
+            });
+        case config_1.MACHINE_TRANSPORT.MQTT:
+            return new mqtt_bus_1.MqttMachineBus(mqttOf(config), (0, line_1.controllerId)(line), (0, protocol_1.lineFilter)(codec.root, line.siteId, line.lineId));
+        default:
+            throw new Error(`MACHINE_TRANSPORT=${config.transport} ${IN_PROCESS_ONLY}`);
+    }
+}
+/** Long Tail's escalation events for the gateway; `in-process` needs the running instance's callback adapter. */
+function createEscalationFeed(config, line, callbacks) {
+    switch (config.feed) {
+        case config_1.ESCALATION_FEED.IN_PROCESS:
+            if (!callbacks)
+                throw new Error('MACHINE_ESCALATION_FEED=in-process runs inside start({ machines })');
+            return new callback_feed_1.CallbackEscalationFeed(callbacks);
+        case config_1.ESCALATION_FEED.CORE:
+            return new nats_feed_1.CoreEscalationFeed({ natsUrl: config.ltNatsUrl, token: config.ltNatsToken });
+        default:
+            throw new Error(`MACHINE_ESCALATION_FEED=${config.feed} ${IN_PROCESS_ONLY}`);
+    }
+}
+/** One MQTT link per simulated machine; machines speak MQTT in every networked mode. */
+function createLinkFactory(config) {
+    if (config.transport === config_1.MACHINE_TRANSPORT.MEMORY)
+        throw new Error(`MACHINE_TRANSPORT=memory ${IN_PROCESS_ONLY}`);
+    const endpoint = mqttOf(config);
+    return () => new mqtt_link_1.MqttMachineLink(endpoint);
+}

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

@@ -0,0 +1,33 @@
+/**
+ * The machine surface inside Long Tail. For each line this deployment
+ * 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.
+ */
+import type { CallbackEventAdapter } from '../../lib/events/callback';
+import type { LineDef } from '../../lib/machines/line';
+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 {
+    lines: LineDef[];
+    /** Transport settings (MACHINE_*); defaults to process.env. */
+    env?: Env;
+    callbacks?: CallbackEventAdapter;
+    log?: GatewayLog;
+    codec?: LineCodec;
+    rows?: HandoffRowAdapter;
+}
+/** Inside Long Tail the gateway reads escalation events in process. */
+export declare function surfaceConfig(env: Env): MachineLineConfig;
+export declare class MachineSurface {
+    private readonly runs;
+    private constructor();
+    /** Validate the configuration, then contend for every line in the background. */
+    static start(opts: MachineSurfaceOptions): MachineSurface;
+    stop(): Promise<void>;
+}
+export {};

package/build/services/machines/surface.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * The machine surface inside Long Tail. For each line this deployment
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineSurface = void 0;
+exports.surfaceConfig = surfaceConfig;
+const config_1 = require("./config");
+const api_escalations_1 = require("./gateway/api-escalations");
+const gateway_1 = require("./gateway/gateway");
+const log_1 = require("./gateway/log");
+const identities_1 = require("./identities");
+const leadership_1 = require("./leadership");
+const select_1 = require("./select");
+/** Inside Long Tail the gateway reads escalation events in process. */
+function surfaceConfig(env) {
+    const transport = env.MACHINE_TRANSPORT;
+    if (transport !== config_1.MACHINE_TRANSPORT.NATS && transport !== config_1.MACHINE_TRANSPORT.MQTT) {
+        throw new Error(`start({ machines }) needs MACHINE_TRANSPORT=nats or mqtt (got "${transport ?? ''}")`);
+    }
+    return (0, config_1.loadMachineLineConfig)({ ...env, MACHINE_ESCALATION_FEED: env.MACHINE_ESCALATION_FEED ?? config_1.ESCALATION_FEED.IN_PROCESS });
+}
+class LineRun {
+    constructor(line, config, opts, log) {
+        this.line = line;
+        this.config = config;
+        this.opts = opts;
+        this.log = log;
+        this.leadership = new leadership_1.LineLeadership(`lt-machine-line:${line.siteId}/${line.lineId}`);
+    }
+    start() {
+        const where = { site: this.line.siteId, line: this.line.lineId };
+        this.log.info(log_1.GATEWAY_LOG.STANDBY, where);
+        this.leadership.run(() => this.lead(), async (err) => {
+            this.log.warn(log_1.GATEWAY_LOG.LEADERSHIP_LOST, { ...where, error: err.message });
+            await this.gateway?.stop();
+            this.gateway = undefined;
+        }).catch((err) => this.log.error(log_1.GATEWAY_LOG.START_FAILED, { ...where, error: err.message }));
+    }
+    async stop() {
+        await this.gateway?.stop();
+        await this.leadership.stop();
+    }
+    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);
+        const userFor = (as) => {
+            const id = ids.get(as);
+            if (!id)
+                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);
+        this.gateway = new gateway_1.MachineGateway({
+            bus: (0, select_1.createMachineBus)(config, line, codec),
+            codec,
+            rows: this.opts.rows,
+            feed: (0, select_1.createEscalationFeed)(config, line, this.opts.callbacks),
+            lt: new api_escalations_1.ApiLineEscalations(userFor),
+            addresses: new identities_1.BotAddressBook(ids),
+            line,
+            log: this.log,
+            settings: {
+                topicRoot: config.topicRoot, replyTimeoutMs: config.replyTimeoutMs, dispatchAttempts: config.dispatchAttempts,
+                offlineDebounceMs: config.offlineDebounceMs, dispatchTtlMs: config.dispatchTtlMs, quietMs: config.quietMs,
+                receiptDelayMs: config.receiptDelayMs,
+            },
+        });
+        await this.gateway.start();
+        this.log.info(log_1.GATEWAY_LOG.LEADING, { site: line.siteId, line: line.lineId });
+    }
+}
+class MachineSurface {
+    constructor(runs) {
+        this.runs = runs;
+    }
+    /** Validate the configuration, then contend for every line in the background. */
+    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);
+    }
+    async stop() {
+        for (const run of this.runs)
+            await run.stop();
+    }
+}
+exports.MachineSurface = MachineSurface;