@hotmeshio/long-tail 0.25.4 → 0.26.0

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

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Learned addresses. On a line that learns them, a station is bound to the
+ * address that first claims it. A claim that disagrees with a binding (a
+ * station already bound to another address, or an address bound to another
+ * station) is a person's decision: one registration row per claim, and the
+ * claimant's messages have no effect until it is approved. Lines that declare
+ * their addresses pass through unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENDER = void 0;
+exports.resolveSender = resolveSender;
+exports.identFor = identFor;
+exports.reachable = reachable;
+exports.registrationRow = registrationRow;
+exports.planRegistrationRow = planRegistrationRow;
+const contracts_1 = require("../contracts");
+const line_1 = require("../../../lib/machines/line");
+const protocol_1 = require("../../../lib/machines/protocol");
+exports.SENDER = { KNOWN: 'known', BOUND: 'bound', CONTESTED: 'contested', UNKNOWN: 'unknown' };
+const onLine = (line, machineId) => !!machineId && line.machines.some((m) => m.machineId === machineId);
+function declaredAt(line, machineId, address) {
+    return onLine(line, machineId) && !(0, line_1.learnsAddress)(line, machineId) && (0, protocol_1.addressOf)((0, line_1.identOf)(line, machineId)) === address;
+}
+function asStation(seen, machineId, address) {
+    return { ...seen, parsed: { ...seen.parsed, ident: { ...seen.parsed.ident, machineId, address } } };
+}
+/** Who sent a message: a known station, one bound just now, a contested claim, or no station at all. */
+function resolveSender(state, line, seen) {
+    const ident = seen.parsed.ident;
+    const address = ident.address ?? ident.machineId;
+    if (line.addressing !== line_1.ADDRESSING.LEARNED)
+        return { status: exports.SENDER.KNOWN, address, machineId: ident.machineId, seen };
+    // A station whose address the line declares is known only on that address.
+    if (declaredAt(line, ident.machineId, address))
+        return { status: exports.SENDER.KNOWN, address, machineId: ident.machineId, seen };
+    const claim = seen.claim ?? (ident.address ? ident.machineId : undefined);
+    const bound = state.stationAt(address);
+    if (bound) {
+        if (claim && claim !== bound)
+            return { status: exports.SENDER.CONTESTED, address, machineId: claim };
+        return { status: exports.SENDER.KNOWN, address, machineId: bound, seen: asStation(seen, bound, address) };
+    }
+    if (!onLine(line, claim) || !(0, line_1.learnsAddress)(line, claim))
+        return { status: exports.SENDER.UNKNOWN, address };
+    if (state.learnedAddress(claim))
+        return { status: exports.SENDER.CONTESTED, address, machineId: claim };
+    return { status: exports.SENDER.BOUND, address, machineId: claim, seen: asStation(seen, claim, address) };
+}
+/** A station's identity on the wire, with the address the line learned for it. */
+function identFor(state, line, machineId) {
+    const learned = (0, line_1.learnsAddress)(line, machineId) ? state.learnedAddress(machineId) : undefined;
+    return { ...(0, line_1.identOf)(line, machineId), ...(learned ? { address: learned } : {}) };
+}
+/** Whether the gateway knows where to send to a station: a declared address, or one it learned. */
+function reachable(state, line, machineId) {
+    return !(0, line_1.learnsAddress)(line, machineId) || !!state.learnedAddress(machineId);
+}
+/** The row asking a person whether `address` is `machineId`. */
+function registrationRow(state, line, address, machineId) {
+    const boundAddress = state.learnedAddress(machineId) ?? null;
+    const boundStation = state.stationAt(address) ?? null;
+    const now = [
+        boundAddress ? `${machineId} is bound to ${boundAddress}` : null,
+        boundStation ? `${address} is bound to ${boundStation}` : null,
+    ].filter(Boolean).join('; ');
+    return {
+        type: contracts_1.ROW_TYPE.MACHINE_REGISTRATION, role: (0, line_1.operatorRole)(line), priority: 2,
+        description: `${address} says it is ${machineId}. ${now}. Approve to bind ${machineId} to ${address}.`,
+        metadata: { siteId: line.siteId, lineId: line.lineId, machineId, address, boundAddress, boundStation },
+    };
+}
+/** A row's resolver payload, which Long Tail stores serialized. */
+function resolutionOf(raw) {
+    if (raw && typeof raw === 'object')
+        return raw;
+    if (typeof raw !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why an approved registration may not bind; null when it may. The row is only a request:
+ * the station must learn its address, the address must be one a machine could send from,
+ * and a machine at that address must have claimed the station on the wire.
+ */
+function bindingRefusal(state, line, machineId, address) {
+    if (!onLine(line, machineId) || !(0, line_1.learnsAddress)(line, machineId))
+        return `${machineId} is not a station on this line that learns its address`;
+    if (!(0, protocol_1.isTopicLevel)(address))
+        return `"${address}" is not an address a machine can send from`;
+    if (line.machines.some((m) => declaredAt(line, m.machineId, address)))
+        return `${address} is the declared address of another station`;
+    if (!state.claimHeard(address, machineId))
+        return `no machine at ${address} has claimed ${machineId} since this gateway took the line`;
+    return null;
+}
+/** A person decided a registration row: approval binds the station to the claimant; anything else leaves the binding. */
+function planRegistrationRow(state, line, event) {
+    const md = event.data?.metadata ?? {};
+    if (typeof md.machineId !== 'string' || typeof md.address !== 'string')
+        return [];
+    if (event.verb === 'created') {
+        state.raiseClaim(md.address, md.machineId);
+        return [];
+    }
+    state.settleClaim(md.address, md.machineId);
+    const approved = event.verb === 'resolved' && resolutionOf(event.data?.resolver_payload)?.decision === contracts_1.DECISION.APPROVE;
+    const by = event.data?.resolved_by ?? event.data?.metadata?.resolved_by ?? undefined;
+    if (!approved)
+        return [];
+    const reason = bindingRefusal(state, line, md.machineId, md.address);
+    return reason
+        ? [{ kind: 'refuseBinding', machineId: md.machineId, address: md.address, reason }]
+        : [{ kind: 'bindAddress', machineId: md.machineId, address: md.address, by }];
+}

package/build/services/machines/gateway/reply-waiter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Command replies by cmdId, and machine snapshots by machine. A wait registers
+ * before the command is published and resolves with the reply, or null at the
+ * deadline.
+ */
+export interface CommandReply {
+    cmdId: string;
+    status: string;
+    reason: string;
+}
+/** The jobs a machine reports holding, queued or in work. */
+export type HeldJobs = Set<string>;
+export declare class ReplyWaiter {
+    private replies;
+    private snapshots;
+    wait(cmdId: string, timeoutMs: number): Promise<CommandReply | null>;
+    /** True when a waiter took the reply. */
+    settle(reply: CommandReply): boolean;
+    /** The next snapshot from `machineId`, or null at the deadline. */
+    waitSnapshot(machineId: string, timeoutMs: number): Promise<HeldJobs | null>;
+    /** Answer a status query in flight; null when there is nothing to wait for. */
+    settleSnapshot(machineId: string, jobs: HeldJobs | null): void;
+    cancelAll(): void;
+}

package/build/services/machines/gateway/reply-waiter.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Command replies by cmdId, and machine snapshots by machine. A wait registers
+ * before the command is published and resolves with the reply, or null at the
+ * deadline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplyWaiter = void 0;
+class Waits {
+    constructor() {
+        this.waiting = new Map();
+    }
+    wait(key, timeoutMs) {
+        this.waiting.get(key)?.resolve(null);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.waiting.delete(key);
+                resolve(null);
+            }, timeoutMs);
+            this.waiting.set(key, { resolve, timer });
+        });
+    }
+    settle(key, value) {
+        const w = this.waiting.get(key);
+        if (!w)
+            return false;
+        clearTimeout(w.timer);
+        this.waiting.delete(key);
+        w.resolve(value);
+        return true;
+    }
+    cancelAll() {
+        for (const [, w] of this.waiting) {
+            clearTimeout(w.timer);
+            w.resolve(null);
+        }
+        this.waiting.clear();
+    }
+}
+class ReplyWaiter {
+    constructor() {
+        this.replies = new Waits();
+        this.snapshots = new Waits();
+    }
+    wait(cmdId, timeoutMs) {
+        return this.replies.wait(cmdId, timeoutMs);
+    }
+    /** True when a waiter took the reply. */
+    settle(reply) {
+        return this.replies.settle(reply.cmdId, reply);
+    }
+    /** The next snapshot from `machineId`, or null at the deadline. */
+    waitSnapshot(machineId, timeoutMs) {
+        return this.snapshots.wait(machineId, timeoutMs);
+    }
+    /** Answer a status query in flight; null when there is nothing to wait for. */
+    settleSnapshot(machineId, jobs) {
+        this.snapshots.settle(machineId, jobs);
+    }
+    cancelAll() {
+        this.replies.cancelAll();
+        this.snapshots.cancelAll();
+    }
+}
+exports.ReplyWaiter = ReplyWaiter;

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

@@ -0,0 +1,125 @@
+/**
+ * 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>>;
+}
+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;
+}
+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;
+    /** 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 open row an accepted dispatch command belongs to. */
+    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,228 @@
+"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;
+        /** 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 }
+            : 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 open row an accepted dispatch command belongs to. */
+    rowForDispatch(cmdId) {
+        const rowId = this.dispatches.get(cmdId);
+        return rowId ? this.openRows.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;
+}