@hotmeshio/long-tail 0.25.4 → 0.27.0

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

@@ -0,0 +1,145 @@
+/**
+ * What the gateway knows: the open handoff rows (from escalation events, so a
+ * replay rebuilds it), recently closed ones and how they ended (so replayed
+ * machine events are recognized as done), open alarm rows, and each
+ * machine's link: presence, last message, software and boot id.
+ */
+import type { HandoffFacets, TraceEntry } from '../contracts';
+/**
+ * WAITING: the machine has no room yet (pacing.ts); the row waits in its role queue.
+ * ARRIVING: the job goes out once its units arrive at the receiver (codec `dispatchOn: arrival`).
+ */
+export declare const DISPATCH_STATE: {
+    readonly NONE: "none";
+    readonly WAITING: "waiting";
+    readonly ARRIVING: "arriving";
+    readonly PENDING: "pending";
+    readonly ACCEPTED: "accepted";
+    readonly REFUSED: "refused";
+};
+export type DispatchState = typeof DISPATCH_STATE[keyof typeof DISPATCH_STATE];
+export declare const ROW_END: {
+    readonly RESOLVED: "resolved";
+    readonly CANCELLED: "cancelled";
+    readonly EXPIRED: "expired";
+};
+export type RowEnd = typeof ROW_END[keyof typeof ROW_END];
+export interface HandoffRow extends HandoffFacets {
+    id: string;
+    role: string;
+    dispatch: DispatchState;
+    ended?: RowEnd;
+    /** Finished-unit records already on the row's metadata (trace.ts). */
+    trace?: TraceEntry[];
+    /** Each unit's arrival event, as its receiver reported it (dispatch on arrival). */
+    arrivals?: Record<string, Record<string, any>>;
+    /** Lifecycle item keys already on the row (lifecycle.ts). */
+    noted?: string[];
+    /** Parked with a limit on its items, which lifecycle notes must never use up. */
+    capped?: boolean;
+    /** When the row was created (epoch ms). */
+    createdAt?: number;
+    /** When its last unit arrived (epoch ms, dispatch on arrival); its dispatch windows count from here, else from createdAt. */
+    dueAt?: number;
+}
+export interface AlarmTrack {
+    machineId: string;
+    alarmId: string;
+    /** When the machine raised it; a reused alarm id with a new time is a new alarm. */
+    raisedAt?: string;
+    rowId?: string;
+    /** Created and not yet resolved by anyone. */
+    open: boolean;
+    /** Rows the alarm paused, noted again when it clears. */
+    noted?: string[];
+}
+export interface LinkTrack {
+    online: boolean;
+    since: number;
+    lastSeen: number;
+    rowId?: string;
+    quietRowId?: string;
+    watching?: boolean;
+    software?: string;
+    bootId?: string;
+}
+export declare class GatewayState {
+    /** Units one dispatch may carry, from the codec; null when any number may. */
+    unitsPerDispatch: number | null;
+    /** Jobs go to a receiver once its units arrive there, from the codec. */
+    dispatchOnArrival: boolean;
+    /** Note each job's start, progress steps and pauses on the row that holds it (lifecycle.ts). */
+    lifecycle: boolean;
+    /** Active alarms are retained on the broker; otherwise snapshots list them (codec.ts retainedAlarms). */
+    retainedAlarms: boolean;
+    /** Reading the broker's retained messages on taking the line; a snapshot read back may be older than its alarms. */
+    readingRetained: boolean;
+    /** When this gateway took the line (epoch ms); a command for an older row may have been sent by an earlier one. */
+    takenAt: number;
+    /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
+    progressStep: number;
+    /** While reconciling, new handoffs wait so pacing sees the whole line before anything is sent. */
+    holdDispatch: boolean;
+    /** Units at each machine that arrived and have not left: machine → unit → job. */
+    private held;
+    private openRows;
+    private closedRows;
+    readonly alarms: Map<string, AlarmTrack>;
+    /** Finished records that came before their row: machine/unit → job body. */
+    private earlyFinishes;
+    private openCommands;
+    /** Accepted dispatch command ids → their row, so a later failure finds the row. */
+    private dispatches;
+    private endedCommands;
+    readonly links: Map<string, LinkTrack>;
+    /** Messages already shown to a person as contract violations. */
+    private violations;
+    /** Learned addresses, both ways: station → address and address → station. */
+    private addressOfStation;
+    private stationOfAddress;
+    /** Contested claims already raised as registration rows, `${address}>${station}`. */
+    private claims;
+    /** Contested claims heard from the machines themselves, `${address}>${station}`. */
+    private heard;
+    /** Addresses heard that claim no station, logged once each. */
+    private strangers;
+    index(row: HandoffRow): void;
+    get(id: string): HandoffRow | undefined;
+    close(id: string, ended?: RowEnd): HandoffRow | undefined;
+    isClosed(id: string): boolean;
+    open(): HandoffRow[];
+    /** The open handoff carrying this unit that `pred` picks (latest attempt first). */
+    openFor(unitId: string, pred: (r: HandoffRow) => boolean): HandoffRow | undefined;
+    closedFor(unitId: string, pred: (r: HandoffRow) => boolean): HandoffRow | undefined;
+    hold(machineId: string, unitId: string, jobId: string): void;
+    letGo(machineId: string, unitId: string): void;
+    /** The job a unit arrived under at `machineId`, while it is still there. */
+    heldJob(machineId: string, unitId: string): string | undefined;
+    heldAt(machineId: string): string[];
+    /** Keep only units whose job the machine still lists (its snapshot). */
+    keepHeld(machineId: string, jobIds: Set<string>): void;
+    /** Keep a sender's finished record until its row is known, so an arrival cannot close the row without it. */
+    rememberFinish(machineId: string, unitId: string, body: Record<string, any>): void;
+    takeFinish(machineId: string, unitId: string): Record<string, any> | undefined;
+    rememberDispatch(cmdId: string, rowId: string): void;
+    /** The row a dispatch command belongs to, open or recently closed. */
+    rowForDispatch(cmdId: string): HandoffRow | undefined;
+    /** Track a machine-command row; false when it is already tracked or has ended. */
+    trackCommand(id: string): boolean;
+    endCommand(id: string): void;
+    /** Bind a station to an address, replacing whatever either was bound to before. */
+    bindAddress(machineId: string, address: string): void;
+    learnedAddress(machineId: string): string | undefined;
+    stationAt(address: string): string | undefined;
+    claimRaised(address: string, machineId: string): boolean;
+    raiseClaim(address: string, machineId: string): void;
+    settleClaim(address: string, machineId: string): void;
+    hearClaim(address: string, machineId: string): void;
+    claimHeard(address: string, machineId: string): boolean;
+    /** True the first time an address that claims no station is heard. */
+    firstHeardStranger(address: string): boolean;
+    violationRaised(key: string): boolean;
+    raiseViolation(key: string): void;
+    link(machineId: string, now?: number): LinkTrack;
+    alarmKey(machineId: string, alarmId: string): string;
+}

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

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * What the gateway knows: the open handoff rows (from escalation events, so a
+ * replay rebuilds it), recently closed ones and how they ended (so replayed
+ * machine events are recognized as done), open alarm rows, and each
+ * machine's link: presence, last message, software and boot id.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayState = exports.ROW_END = exports.DISPATCH_STATE = void 0;
+const trace_1 = require("./trace");
+/**
+ * WAITING: the machine has no room yet (pacing.ts); the row waits in its role queue.
+ * ARRIVING: the job goes out once its units arrive at the receiver (codec `dispatchOn: arrival`).
+ */
+exports.DISPATCH_STATE = {
+    NONE: 'none', WAITING: 'waiting', ARRIVING: 'arriving', PENDING: 'pending', ACCEPTED: 'accepted', REFUSED: 'refused',
+};
+exports.ROW_END = { RESOLVED: 'resolved', CANCELLED: 'cancelled', EXPIRED: 'expired' };
+const CLOSED_LIMIT = 2_000;
+class GatewayState {
+    constructor() {
+        /** Units one dispatch may carry, from the codec; null when any number may. */
+        this.unitsPerDispatch = null;
+        /** Jobs go to a receiver once its units arrive there, from the codec. */
+        this.dispatchOnArrival = false;
+        /** Note each job's start, progress steps and pauses on the row that holds it (lifecycle.ts). */
+        this.lifecycle = false;
+        /** Active alarms are retained on the broker; otherwise snapshots list them (codec.ts retainedAlarms). */
+        this.retainedAlarms = false;
+        /** Reading the broker's retained messages on taking the line; a snapshot read back may be older than its alarms. */
+        this.readingRetained = false;
+        /** When this gateway took the line (epoch ms); a command for an older row may have been sent by an earlier one. */
+        this.takenAt = 0;
+        /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
+        this.progressStep = 25;
+        /** While reconciling, new handoffs wait so pacing sees the whole line before anything is sent. */
+        this.holdDispatch = false;
+        /** Units at each machine that arrived and have not left: machine → unit → job. */
+        this.held = new Map();
+        this.openRows = new Map();
+        this.closedRows = new Map();
+        this.alarms = new Map();
+        /** Finished records that came before their row: machine/unit → job body. */
+        this.earlyFinishes = new Map();
+        this.openCommands = new Set();
+        /** Accepted dispatch command ids → their row, so a later failure finds the row. */
+        this.dispatches = new Map();
+        this.endedCommands = new Set();
+        this.links = new Map();
+        /** Messages already shown to a person as contract violations. */
+        this.violations = new Set();
+        /** Learned addresses, both ways: station → address and address → station. */
+        this.addressOfStation = new Map();
+        this.stationOfAddress = new Map();
+        /** Contested claims already raised as registration rows, `${address}>${station}`. */
+        this.claims = new Set();
+        /** Contested claims heard from the machines themselves, `${address}>${station}`. */
+        this.heard = new Set();
+        /** Addresses heard that claim no station, logged once each. */
+        this.strangers = new Set();
+    }
+    index(row) {
+        if (this.closedRows.has(row.id))
+            return;
+        const existing = this.openRows.get(row.id);
+        // An event may carry metadata older than what the gateway already wrote: keep both traces.
+        this.openRows.set(row.id, existing
+            ? {
+                ...row, dispatch: existing.dispatch, trace: (0, trace_1.mergeTrace)(row.trace, existing.trace), arrivals: existing.arrivals,
+                dueAt: existing.dueAt, noted: existing.noted ?? row.noted,
+            }
+            : row);
+    }
+    get(id) {
+        return this.openRows.get(id);
+    }
+    close(id, ended = exports.ROW_END.RESOLVED) {
+        const row = this.openRows.get(id);
+        if (!row)
+            return undefined;
+        this.openRows.delete(id);
+        row.ended = ended;
+        this.closedRows.set(id, row);
+        if (this.closedRows.size > CLOSED_LIMIT) {
+            const oldest = this.closedRows.keys().next().value;
+            if (oldest)
+                this.closedRows.delete(oldest);
+        }
+        return row;
+    }
+    isClosed(id) {
+        return this.closedRows.has(id);
+    }
+    open() {
+        return [...this.openRows.values()];
+    }
+    /** The open handoff carrying this unit that `pred` picks (latest attempt first). */
+    openFor(unitId, pred) {
+        return this.open().filter((r) => carries(r, unitId) && pred(r)).sort((a, b) => b.attempt - a.attempt)[0];
+    }
+    closedFor(unitId, pred) {
+        return [...this.closedRows.values()].find((r) => carries(r, unitId) && pred(r));
+    }
+    hold(machineId, unitId, jobId) {
+        if (!this.held.has(machineId))
+            this.held.set(machineId, new Map());
+        this.held.get(machineId).set(unitId, jobId);
+    }
+    letGo(machineId, unitId) {
+        this.held.get(machineId)?.delete(unitId);
+    }
+    /** The job a unit arrived under at `machineId`, while it is still there. */
+    heldJob(machineId, unitId) {
+        return this.held.get(machineId)?.get(unitId);
+    }
+    heldAt(machineId) {
+        return [...(this.held.get(machineId)?.values() ?? [])];
+    }
+    /** Keep only units whose job the machine still lists (its snapshot). */
+    keepHeld(machineId, jobIds) {
+        const units = this.held.get(machineId);
+        if (!units)
+            return;
+        for (const [unitId, jobId] of units)
+            if (!jobIds.has(jobId))
+                units.delete(unitId);
+    }
+    /** Keep a sender's finished record until its row is known, so an arrival cannot close the row without it. */
+    rememberFinish(machineId, unitId, body) {
+        this.earlyFinishes.delete(`${machineId}/${unitId}`);
+        this.earlyFinishes.set(`${machineId}/${unitId}`, body);
+        if (this.earlyFinishes.size > CLOSED_LIMIT) {
+            const oldest = this.earlyFinishes.keys().next().value;
+            if (oldest)
+                this.earlyFinishes.delete(oldest);
+        }
+    }
+    takeFinish(machineId, unitId) {
+        const body = this.earlyFinishes.get(`${machineId}/${unitId}`);
+        this.earlyFinishes.delete(`${machineId}/${unitId}`);
+        return body;
+    }
+    rememberDispatch(cmdId, rowId) {
+        this.dispatches.set(cmdId, rowId);
+        if (this.dispatches.size > CLOSED_LIMIT) {
+            const oldest = this.dispatches.keys().next().value;
+            if (oldest)
+                this.dispatches.delete(oldest);
+        }
+    }
+    /** The row a dispatch command belongs to, open or recently closed. */
+    rowForDispatch(cmdId) {
+        const rowId = this.dispatches.get(cmdId);
+        return rowId ? this.openRows.get(rowId) ?? this.closedRows.get(rowId) : undefined;
+    }
+    /** Track a machine-command row; false when it is already tracked or has ended. */
+    trackCommand(id) {
+        if (this.openCommands.has(id) || this.endedCommands.has(id))
+            return false;
+        this.openCommands.add(id);
+        return true;
+    }
+    endCommand(id) {
+        this.openCommands.delete(id);
+        this.endedCommands.add(id);
+        if (this.endedCommands.size > CLOSED_LIMIT) {
+            const oldest = this.endedCommands.values().next().value;
+            if (oldest)
+                this.endedCommands.delete(oldest);
+        }
+    }
+    /** Bind a station to an address, replacing whatever either was bound to before. */
+    bindAddress(machineId, address) {
+        const before = this.addressOfStation.get(machineId);
+        if (before)
+            this.stationOfAddress.delete(before);
+        const other = this.stationOfAddress.get(address);
+        if (other)
+            this.addressOfStation.delete(other);
+        this.addressOfStation.set(machineId, address);
+        this.stationOfAddress.set(address, machineId);
+    }
+    learnedAddress(machineId) {
+        return this.addressOfStation.get(machineId);
+    }
+    stationAt(address) {
+        return this.stationOfAddress.get(address);
+    }
+    claimRaised(address, machineId) {
+        return this.claims.has(`${address}>${machineId}`);
+    }
+    raiseClaim(address, machineId) {
+        this.claims.add(`${address}>${machineId}`);
+    }
+    settleClaim(address, machineId) {
+        this.claims.delete(`${address}>${machineId}`);
+    }
+    hearClaim(address, machineId) {
+        this.heard.add(`${address}>${machineId}`);
+        if (this.heard.size > CLOSED_LIMIT)
+            this.heard.delete(this.heard.values().next().value);
+    }
+    claimHeard(address, machineId) {
+        return this.heard.has(`${address}>${machineId}`);
+    }
+    /** True the first time an address that claims no station is heard. */
+    firstHeardStranger(address) {
+        if (this.strangers.has(address))
+            return false;
+        this.strangers.add(address);
+        if (this.strangers.size > CLOSED_LIMIT)
+            this.strangers.delete(this.strangers.values().next().value);
+        return true;
+    }
+    violationRaised(key) {
+        return this.violations.has(key);
+    }
+    raiseViolation(key) {
+        this.violations.add(key);
+        if (this.violations.size > CLOSED_LIMIT) {
+            const oldest = this.violations.values().next().value;
+            if (oldest)
+                this.violations.delete(oldest);
+        }
+    }
+    link(machineId, now = Date.now()) {
+        let link = this.links.get(machineId);
+        if (!link) {
+            link = { online: true, since: now, lastSeen: now };
+            this.links.set(machineId, link);
+        }
+        return link;
+    }
+    alarmKey(machineId, alarmId) {
+        return `${machineId}/${alarmId}`;
+    }
+}
+exports.GatewayState = GatewayState;
+function carries(row, unitId) {
+    return row.units.some((u) => u.unitId === unitId);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Traceability on the row. When a sender finishes a unit, its record (result
+ * and the material lots it consumed) is added to the handoff row's metadata
+ * in the same statement that records the release, so a search by lot finds
+ * every handoff, and so every unit, that used it. The full record stays on
+ * the row as the release item.
+ */
+import { type TraceEntry } from '../contracts';
+/** The trace entry for a finished job event from `machineId`. */
+export declare function traceEntry(machineId: string, body: Record<string, any>): TraceEntry;
+/** A row's trace as read back from its metadata; entries without a unit or machine are dropped. */
+export declare function readTrace(md?: Record<string, any>): TraceEntry[];
+/** Entries from both lists, one per unit and machine; a later entry replaces an earlier one. */
+export declare function mergeTrace(a?: TraceEntry[], b?: TraceEntry[]): TraceEntry[];
+/** The metadata patch for a trace: the entries, and every lot once. */
+export declare function traceFacets(trace: TraceEntry[]): Record<string, unknown>;

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

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Traceability on the row. When a sender finishes a unit, its record (result
+ * and the material lots it consumed) is added to the handoff row's metadata
+ * in the same statement that records the release, so a search by lot finds
+ * every handoff, and so every unit, that used it. The full record stays on
+ * the row as the release item.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceEntry = traceEntry;
+exports.readTrace = readTrace;
+exports.mergeTrace = mergeTrace;
+exports.traceFacets = traceFacets;
+const contracts_1 = require("../contracts");
+const str = (v) => (typeof v === 'string' && v ? v : null);
+function materialsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((m) => str(m?.material) && str(m?.lot)).map((m) => ({ material: m.material, lot: m.lot }));
+}
+/** The trace entry for a finished job event from `machineId`. */
+function traceEntry(machineId, body) {
+    return { unitId: String(body.unitId), machineId, jobId: str(body.jobId), result: str(body.result), materials: materialsOf(body.materials) };
+}
+/** A row's trace as read back from its metadata; entries without a unit or machine are dropped. */
+function readTrace(md = {}) {
+    const raw = md[contracts_1.TRACE_FACET.TRACE];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((e) => str(e?.unitId) && str(e?.machineId)).map((e) => ({ ...e, materials: materialsOf(e.materials) }));
+}
+/** Entries from both lists, one per unit and machine; a later entry replaces an earlier one. */
+function mergeTrace(a = [], b = []) {
+    const byKey = new Map();
+    for (const e of [...a, ...b])
+        byKey.set(`${e.unitId}@${e.machineId}`, e);
+    return [...byKey.values()];
+}
+/** The metadata patch for a trace: the entries, and every lot once. */
+function traceFacets(trace) {
+    const lots = [...new Set(trace.flatMap((e) => e.materials.map((m) => m.lot)))];
+    return { [contracts_1.TRACE_FACET.TRACE]: trace, [contracts_1.TRACE_FACET.LOTS]: lots };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+import type { LineDef } from '../../lib/machines/line';
+import { type Actor } from './gateway/actions';
+import type { AddressBook } from './gateway/address-book';
+/** The user property on a station's bot account that holds the address its machine registered. */
+export declare const ADDRESS_PROPERTY = "machineAddress";
+/** Make sure every bot the line needs exists with its roles; returns actor → user id. */
+export declare function ensureLineBots(line: LineDef): Promise<Map<Actor, string>>;
+/**
+ * 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.
+ */
+export declare class BotAddressBook implements AddressBook {
+    private readonly bots;
+    constructor(bots: Map<Actor, string>);
+    load(): Promise<Map<string, string>>;
+    bind(machineId: string, address: string): Promise<void>;
+    private read;
+}

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,35 @@
+/**
+ * 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.
+ */
+import type { PoolClient } from 'pg';
+export interface LeadershipOptions {
+    /** A dedicated connection for the lock; the shared pool's by default. */
+    connect?: () => Promise<PoolClient>;
+    /** The pause before contending again. */
+    retryMs?: number;
+}
+export declare class LineLeadership {
+    readonly key: string;
+    private client?;
+    private stopped;
+    private leading;
+    private endTurn?;
+    private readonly connect;
+    private readonly retryMs;
+    constructor(key: string, opts?: LeadershipOptions);
+    /**
+     * Wait for the lock, then call `lead`. When the connection is refused,
+     * leading fails or the connection drops, `lost` runs before this replica lets
+     * the lock go, so no other replica leads alongside a gateway that is
+     * stopping; then the line contends again after a pause.
+     */
+    run(lead: () => Promise<void>, lost: (err: Error) => Promise<void>): Promise<void>;
+    private leadOnce;
+    /** Lead while the lock is held; the error that ended it. */
+    private holdLock;
+    /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
+    stop(): Promise<void>;
+}