@hotmeshio/long-tail 0.25.4 → 0.27.0

package/build/services/machines/leadership.js

@@ -0,0 +1,100 @@
+"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, opts = {}) {
+        this.key = key;
+        this.stopped = false;
+        this.leading = false;
+        this.connect = opts.connect ?? (() => (0, db_1.getPool)().connect());
+        this.retryMs = opts.retryMs ?? RETRY_MS;
+    }
+    /**
+     * 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.
+     */
+    async run(lead, lost) {
+        while (!this.stopped) {
+            await this.leadOnce(lead, lost);
+            if (this.stopped)
+                return;
+            await new Promise((r) => setTimeout(r, this.retryMs));
+        }
+    }
+    async leadOnce(lead, lost) {
+        let client;
+        try {
+            client = await this.connect();
+        }
+        catch (err) {
+            if (!this.stopped)
+                await lost(err);
+            return;
+        }
+        if (this.stopped) {
+            client.release(true);
+            return;
+        }
+        this.client = client;
+        const err = await this.holdLock(client, lead);
+        this.leading = false;
+        this.endTurn = undefined;
+        // stop() has let the connection go.
+        if (this.stopped)
+            return;
+        await lost(err);
+        this.client = undefined;
+        client.release(true);
+    }
+    /** Lead while the lock is held; the error that ended it. */
+    async holdLock(client, lead) {
+        const ended = new Promise((resolve) => {
+            client.once('error', resolve);
+            this.endTurn = () => resolve(new Error('leadership stopped'));
+        });
+        try {
+            await client.query(LOCK_SQL, [this.key]);
+            if (this.stopped)
+                return new Error('leadership stopped');
+            this.leading = true;
+            await lead();
+            return await ended;
+        }
+        catch (err) {
+            return err;
+        }
+    }
+    /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
+    async stop() {
+        this.stopped = true;
+        this.endTurn?.();
+        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,71 @@
+"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) {
+    if (!v || typeof v.url !== 'string' || !v.url || typeof v.sha256 !== 'string' || !v.sha256)
+        return undefined;
+    return {
+        url: v.url, sha256: v.sha256,
+        ...(typeof v.id === 'string' && v.id ? { id: v.id } : {}),
+        ...(typeof v.contentType === 'string' && v.contentType ? { contentType: v.contentType } : {}),
+        ...(Number.isInteger(v.sizeBytes) && v.sizeBytes >= 0 ? { sizeBytes: v.sizeBytes } : {}),
+    };
+}
+function artifactsOf(v) {
+    const list = Array.isArray(v) ? v.map(artifactOf).filter((a) => !!a) : [];
+    return list.length ? list : undefined;
+}
+function unitsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((u) => u && u.unitId).map((u) => {
+        const artifact = artifactOf(u.artifact);
+        const artifacts = artifactsOf(u.artifacts);
+        const parameters = paramsOf(u.parameters);
+        return {
+            unitId: String(u.unitId), carrierId: str(u.carrierId),
+            ...(artifact ? { artifact } : {}), ...(artifacts ? { artifacts } : {}), ...(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,25 @@
+/**
+ * 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 { messagingRegistry } from '../../lib/messaging';
+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;
+/** What the stream bus needs from Long Tail's messaging; the registry by default. */
+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.
+ */
+export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging): 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,76 @@
+"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 stream_bus_1 = require("../../lib/machines/transport/stream-bus");
+const callback_feed_1 = require("../../lib/machines/transport/callback-feed");
+const nats_feed_1 = require("../../lib/machines/transport/nats-feed");
+const pubsub_feed_1 = require("../../lib/machines/transport/pubsub-feed");
+const messaging_1 = require("../../lib/messaging");
+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. 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.
+ */
+function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry) {
+    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 };
+            if (config.siteNatsUrl) {
+                return new nats_bus_1.NatsMachineBus({ natsUrl: config.siteNatsUrl, user: config.siteNatsUser, password: config.siteNatsPassword, ...where });
+            }
+            return new stream_bus_1.StreamMachineBus({ streams: messaging.streams, pubsub: messaging.pubsub, ...where });
+        }
+        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:
+            if (messaging_1.messagingRegistry.hasProvider)
+                return new pubsub_feed_1.PubSubEscalationFeed(messaging_1.messagingRegistry.pubsub);
+            if (!config.ltNatsUrl)
+                throw new Error('MACHINE_ESCALATION_FEED=core needs Long Tail messaging (LT_MESSAGING=nats) or NATS_URL');
+            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,104 @@
+"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.stopped = false;
+        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.leading = 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 }));
+    }
+    /** A gateway still starting finishes first, so none is left running after stop. */
+    async stop() {
+        this.stopped = true;
+        await this.leading?.catch(() => undefined);
+        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);
+        if (this.stopped)
+            return;
+        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, lifecycle: config.lifecycle, progressStep: config.progressStep,
+            },
+        });
+        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;

package/build/services/machines/testing/fake-long-tail.d.ts

@@ -0,0 +1,79 @@
+/**
+ * An in-memory Long Tail for the machine gateway: escalation rows with the
+ * claim / accumulate / resolve / create verbs, each publishing the lifecycle
+ * event Long Tail publishes, plus helpers that play the unit workflow and the
+ * people (exit, operator).
+ */
+import { type Actor, type CreateRowInput } from '../gateway/actions';
+import { type LineEscalations, type RowItem, type VerbResult } from '../gateway/escalations';
+import { type HandoffFacets } from '../contracts';
+import type { MemoryEscalationFeed } from '../../../lib/machines/transport';
+import type { OpenRowQuery } from '../rows';
+export interface FakeRow {
+    id: string;
+    type: string;
+    subtype?: string;
+    role: string;
+    status: 'pending' | 'resolved' | 'cancelled' | 'expired';
+    assigned_to?: string;
+    metadata: Record<string, any>;
+    items: {
+        itemKey: string;
+        payload: any;
+        actor: Actor;
+    }[];
+    resolver_payload?: Record<string, any>;
+    resolved_by?: string;
+    envelope?: string;
+    escalation_payload?: string;
+    created_at?: string;
+}
+export interface Call {
+    verb: string;
+    as: Actor;
+    id: string;
+    payload?: any;
+}
+export declare class FakeLongTail implements LineEscalations {
+    private readonly feed;
+    readonly rows: Map<string, FakeRow>;
+    readonly calls: Call[];
+    private seq;
+    private failing;
+    /** The next `times` calls of `verb` fail as a Long Tail outage would (5xx). */
+    failNext(verb: 'claim' | 'accumulate' | 'resolve' | 'create', times?: number): void;
+    /** Roles each actor holds; an actor outside a row's role gets not found, as Long Tail's RBAC answers. */
+    readonly holds: Map<string, Set<string>>;
+    private hidden;
+    private outage;
+    constructor(feed: MemoryEscalationFeed);
+    private emit;
+    private add;
+    /** What the unit workflow's conditionalAccumulator does: park a handoff row. */
+    park(role: string, facets: HandoffFacets): FakeRow;
+    /** Park any row, as a host workflow parks its own. */
+    parkRow(input: {
+        type: string;
+        role: string;
+        subtype?: string;
+        metadata: Record<string, any>;
+    }): FakeRow;
+    /** A person resolving a row on the dashboard. */
+    personResolves(id: string, payload: Record<string, any>, person?: string): void;
+    /** A person or the workflow cancelling the row. */
+    cancel(id: string): void;
+    /** The row's timeout firing (conditional `timeout`). */
+    expire(id: string): void;
+    claim(as: Actor, id: string): Promise<VerbResult>;
+    accumulate(as: Actor, id: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>): Promise<VerbResult>;
+    resolve(as: Actor, id: string, payload: Record<string, any>): Promise<VerbResult>;
+    create(_as: Actor, input: CreateRowInput): Promise<{
+        id: string;
+    }>;
+    itemKeys(id: string): Promise<string[]>;
+    items(id: string): Promise<RowItem[]>;
+    get(id: string): Promise<Record<string, any> | null>;
+    listOpen(query: OpenRowQuery): Promise<Record<string, any>[]>;
+    ofType(type: string): FakeRow[];
+    ended(id: string, ms?: number): Promise<FakeRow>;
+}