@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/dist/components/deploymentOperations.js

@@ -0,0 +1,185 @@
+'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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleListDeployments = handleListDeployments;
+exports.handleGetDeployment = handleGetDeployment;
+// Read-side operations against system.hdb_deployment.
+// Write-side lives in deploymentRecorder.ts; this module only reads.
+const databases_ts_1 = require("../resources/databases.js");
+const terms = __importStar(require("../utility/hdbTerms.js"));
+const hdbError_ts_1 = require("../utility/errors/hdbError.js");
+const deploymentRecorder_ts_1 = require("./deploymentRecorder.js");
+const DEPLOYMENT_TABLE = terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME;
+const TERMINAL_STATUSES = new Set(['success', 'failed', 'rolled_back']);
+function deploymentTable() {
+    const table = databases_ts_1.databases.system?.[DEPLOYMENT_TABLE];
+    if (!table) {
+        throw new hdbError_ts_1.ClientError(`Deployment tracking is not initialized on this node (system.${DEPLOYMENT_TABLE} missing). ` +
+            `Run upgrade or restart the server to provision the table.`);
+    }
+    return table;
+}
+// Strip the blob attribute from a row; the bytes never travel over the operations API.
+// A separate get_deployment_payload operation streams the raw bytes when callers need them.
+function stripBlob(row) {
+    if (!row || typeof row !== 'object')
+        return row;
+    const { payload_blob, ...rest } = row;
+    rest.payload_blob_present = payload_blob != null;
+    return rest;
+}
+async function handleListDeployments(req = {}) {
+    const table = deploymentTable();
+    const conditions = [];
+    if (req.project)
+        conditions.push({ attribute: 'project', value: req.project });
+    if (req.status)
+        conditions.push({ attribute: 'status', value: req.status });
+    if (req.since != null)
+        conditions.push({ attribute: 'started_at', value: req.since, comparator: 'greater_than_equal' });
+    if (req.until != null)
+        conditions.push({ attribute: 'started_at', value: req.until, comparator: 'less_than_equal' });
+    const collected = [];
+    for await (const row of table.search(conditions)) {
+        collected.push(stripBlob(row));
+    }
+    // Newest first by started_at; ties broken by deployment_id for stability.
+    collected.sort((a, b) => (b.started_at ?? 0) - (a.started_at ?? 0) || String(a.deployment_id).localeCompare(b.deployment_id));
+    const total = collected.length;
+    const offset = Math.max(0, req.offset ?? 0);
+    const limit = req.limit != null ? Math.max(0, req.limit) : collected.length;
+    return { deployments: collected.slice(offset, offset + limit), total };
+}
+async function handleGetDeployment(req) {
+    if (!req || !req.deployment_id) {
+        throw new hdbError_ts_1.ClientError(`'deployment_id' is required`);
+    }
+    const table = deploymentTable();
+    const row = await table.get(req.deployment_id);
+    if (!row) {
+        throw new hdbError_ts_1.ClientError(`No deployment found with id '${req.deployment_id}'`);
+    }
+    // SSE content-negotiated branch — when serverHandlers.js detects
+    // `Accept: text/event-stream` it attaches a ProgressEmitter as req.progress and wraps
+    // our return as the operation's final SSE event. We replay event_log on connect, then
+    // tail the deployment's live emitter (if it's still running on this node) until it
+    // reaches a terminal status. The final return value becomes the SSE `done` event.
+    if (req.progress && typeof req.progress.emit === 'function') {
+        const sse = req.progress;
+        const liveEmitter = (0, deploymentRecorder_ts_1.getActiveEmitter)(req.deployment_id);
+        // Subscribe FIRST, before reading the row, so any event the recorder emits between
+        // "now" and the moment we finish reading the historical log still lands. Buffer
+        // those live events; dedupe by recording the timestamp of the last replayed entry
+        // and skipping any live event whose timestamp is <= that. Forward everything else.
+        let lastReplayedTs = 0;
+        let resolveLive = null;
+        let liveDone = false;
+        const liveBuffer = [];
+        const forwardLive = (e) => {
+            sse.emit(e.event, e.data);
+            // A terminal signal — either explicit success/error event from the lifecycle, or
+            // the recorder's `_recorder_finished` sentinel emitted before it unsubscribes.
+            const isTerminalEvent = e.event === '_recorder_finished' ||
+                e.event === 'error' ||
+                (e.event === 'phase' &&
+                    e.data &&
+                    typeof e.data === 'object' &&
+                    e.data.phase === 'success');
+            if (isTerminalEvent && !liveDone) {
+                liveDone = true;
+                resolveLive?.();
+            }
+        };
+        const unsubscribe = liveEmitter
+            ? liveEmitter.subscribe((event) => {
+                const t = Date.now();
+                if (resolveLive) {
+                    // Replay phase finished; we own the live forward path now.
+                    if (t > lastReplayedTs)
+                        forwardLive(event);
+                }
+                else {
+                    // Still replaying; stash for dedup-and-forward once replay completes.
+                    liveBuffer.push({ t, event });
+                }
+            })
+            : null;
+        try {
+            for (const entry of row.event_log ?? []) {
+                sse.emit(entry.event, entry.data);
+                if (typeof entry.t === 'number')
+                    lastReplayedTs = Math.max(lastReplayedTs, entry.t);
+            }
+            if (liveEmitter && !TERMINAL_STATUSES.has(row.status)) {
+                await new Promise((resolve) => {
+                    resolveLive = resolve;
+                    // Flush anything that arrived during replay, filtering to events the replay missed.
+                    for (const buffered of liveBuffer) {
+                        if (buffered.t > lastReplayedTs)
+                            forwardLive(buffered.event);
+                    }
+                    if (liveDone)
+                        resolve();
+                    // Safety net — if the in-memory emitter is dropped (recorder finished or
+                    // the process recycled) before signaling, poll the row's status as a
+                    // fallback so the client never hangs indefinitely.
+                    const pollTimer = setInterval(async () => {
+                        if (liveDone) {
+                            clearInterval(pollTimer);
+                            return;
+                        }
+                        const live = (0, deploymentRecorder_ts_1.getActiveEmitter)(req.deployment_id);
+                        if (!live || live !== liveEmitter) {
+                            clearInterval(pollTimer);
+                            const latest = await table.get(req.deployment_id);
+                            if (latest && TERMINAL_STATUSES.has(latest.status) && !liveDone) {
+                                liveDone = true;
+                                resolve();
+                            }
+                        }
+                    }, 500);
+                });
+            }
+            // Re-read the row so the final SSE payload reflects the post-deploy state.
+            const finalRow = await table.get(req.deployment_id);
+            return stripBlob(finalRow ?? row);
+        }
+        finally {
+            unsubscribe?.();
+        }
+    }
+    return stripBlob(row);
+}
+//# sourceMappingURL=deploymentOperations.js.map

package/dist/components/deploymentOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploymentOperations.js","sourceRoot":"","sources":["../../components/deploymentOperations.ts"],"names":[],"mappings":"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"}

package/dist/components/deploymentRecorder.d.ts

@@ -0,0 +1,81 @@
+import type { Readable } from 'node:stream';
+import { ProgressEmitter } from '../server/serverHelpers/progressEmitter.ts';
+export declare function getActiveEmitter(deploymentId: string): ProgressEmitter | undefined;
+type DeploymentStatus = 'pending' | 'extracting' | 'installing' | 'loading' | 'replicating' | 'restarting' | 'success' | 'failed' | 'rolled_back';
+interface CreateOptions {
+    project?: string;
+    package_identifier?: string;
+    user?: string;
+    restart_mode?: 'immediate' | 'rolling' | null;
+    rollback_of?: string | null;
+    emitter?: ProgressEmitter;
+}
+export declare class DeploymentRecorder {
+    readonly deploymentId: string;
+    private readonly record;
+    private hash;
+    private byteCount;
+    private finished;
+    private unsubscribe;
+    private pendingPut;
+    private dirty;
+    private constructor();
+    static create(options: CreateOptions): Promise<DeploymentRecorder>;
+    /**
+     * Subscribe to a ProgressEmitter. Each event is appended (bounded) to event_log; phase
+     * events also update the row's `status` and `phase` fields. Writes coalesce: a put is
+     * always pending after the first event in a burst, so chatty install output collapses
+     * to one row update per ~100ms instead of one per line.
+     */
+    private subscribeTo;
+    private appendEvent;
+    private scheduleFlush;
+    /**
+     * Drain a payload source (Buffer or Readable) into the row's payload_blob attribute,
+     * computing sha256 and byte count alongside. After this resolves the row has been
+     * committed once with the final hash and size, and `this.row.payload_blob.stream()`
+     * yields a fresh Readable that callers can pass to extraction.
+     *
+     * Buffers the payload in memory (subject to PAYLOAD_BUFFER_CAP_BYTES) so the
+     * hash/size are known synchronously before we commit and so the blob's `saveBlob`
+     * lifecycle doesn't race with our digest() call. A streaming variant is a planned
+     * follow-up that uses the unused `hash`/`byteCount` instance fields below.
+     */
+    ingestPayload(source: Readable | Buffer | string): Promise<void>;
+    transitionPhase(phase: string, status?: DeploymentStatus): Promise<void>;
+    /**
+     * Upsert a single peer outcome by node name. Called per-peer as each replication
+     * target settles, so the row reflects in-flight progress rather than only the
+     * final aggregate. Routes through `scheduleFlush()` so the write coalesces with
+     * the emitter-driven puts and the latest in-memory state always wins.
+     *
+     * Tolerates unknown shapes — anything we can't interpret becomes a plain
+     * stringified entry so the audit trail at least records that a peer was contacted.
+     */
+    recordPeer(result: unknown): void;
+    /**
+     * Bulk-record a final aggregate of peer outcomes. Equivalent to calling recordPeer()
+     * for each entry. Useful for replication layers that surface results all-at-once
+     * via Promise.allSettled rather than via a per-peer callback.
+     */
+    recordPeers(results: unknown): void;
+    finish(status: 'success' | 'failed' | 'rolled_back', error?: unknown): Promise<void>;
+    get row(): Record<string, any>;
+    private put;
+}
+/**
+ * Peer-side helper — wait for the hdb_deployment row to arrive via table replication,
+ * then return it. The row is committed on origin before `replicateOperation` is
+ * called, so peers normally find it immediately; this polling loop is for the rare
+ * case where the operation arrives faster than the table-replication channel.
+ *
+ * The payload_blob's chunks may still be in flight after the row arrives — that's
+ * fine, the Blob's `stream()` / `bytes()` API blocks on incomplete writes
+ * (resources/blob.ts).
+ */
+export declare function awaitDeploymentRow(deploymentId: string, options?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    initialPollIntervalMs?: number;
+}): Promise<Record<string, any>>;
+export {};

package/dist/components/deploymentRecorder.js

@@ -0,0 +1,401 @@
+'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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeploymentRecorder = void 0;
+exports.getActiveEmitter = getActiveEmitter;
+exports.awaitDeploymentRow = awaitDeploymentRow;
+// DeploymentRecorder — lifecycle owner for one row in system.hdb_deployment.
+//
+// Creates the pending row at deploy start, persists the upload payload into the row's
+// payload_blob (with sha256 + size), and writes the terminal status at the end.
+// Subscribes to a ProgressEmitter so phase transitions and install lines land in
+// event_log as they happen — making the deploy observable by Studio polling
+// get_deployment without an attached CLI. The persisted payload_blob will also serve
+// as the rollback source when that operation lands.
+const node_crypto_1 = require("node:crypto");
+const node_crypto_2 = require("node:crypto");
+const databases_ts_1 = require("../resources/databases.js");
+const blob_ts_1 = require("../resources/blob.js");
+const terms = __importStar(require("../utility/hdbTerms.js"));
+const hdbError_ts_1 = require("../utility/errors/hdbError.js");
+const node_os_1 = require("node:os");
+// Bound the event_log so a pathologically chatty install can't grow a row without limit.
+// 200 entries comfortably covers a real deploy with headroom (phase events plus install
+// line summaries). When we exceed the cap, drop the middle rather than the front — the
+// lifecycle spine (prepare → load → replicate → success) is the most valuable context
+// for debugging, and naive front-truncation loses it under a chatty `npm install`.
+const EVENT_LOG_MAX = 200;
+const EVENT_LOG_HEAD_KEEP = 20;
+// In-memory registry of live emitters, keyed by deployment_id. Populated for the lifetime
+// of an in-progress deploy on the origin node; get_deployment SSE looks here to tail live
+// events after replaying event_log. Per-node, not replicated — peers don't see another
+// node's in-progress emitters. Cross-node tailing is a later concern.
+const activeEmitters = new Map();
+function getActiveEmitter(deploymentId) {
+    return activeEmitters.get(deploymentId);
+}
+// Interim cap: ingestPayload currently buffers the entire payload in memory before
+// computing the hash and persisting. This cap prevents an OOM on accidentally-huge
+// uploads. A follow-up will swap this for a true streaming-hash + blob-source pattern
+// that lifts the limit back to whatever the replication path supports.
+const PAYLOAD_BUFFER_CAP_BYTES = 200 * 1024 * 1024;
+class DeploymentRecorder {
+    deploymentId;
+    record;
+    hash = null;
+    byteCount = 0;
+    finished = false;
+    unsubscribe = null;
+    pendingPut = null;
+    dirty = false;
+    constructor(deploymentId, initial) {
+        this.deploymentId = deploymentId;
+        this.record = initial;
+    }
+    static async create(options) {
+        const deploymentId = (0, node_crypto_1.randomUUID)();
+        const startedAt = Date.now();
+        const record = {
+            deployment_id: deploymentId,
+            project: options.project ?? null,
+            package_identifier: options.package_identifier ?? null,
+            payload_hash: null,
+            payload_size: null,
+            payload_blob: null,
+            status: 'pending',
+            phase: 'pending',
+            event_log: [],
+            peer_results: [],
+            origin_node: (0, node_os_1.hostname)(),
+            restart_mode: options.restart_mode ?? null,
+            started_at: startedAt,
+            completed_at: null,
+            user: options.user ?? null,
+            rollback_of: options.rollback_of ?? null,
+            error: null,
+        };
+        const recorder = new DeploymentRecorder(deploymentId, record);
+        await recorder.put();
+        if (options.emitter) {
+            recorder.subscribeTo(options.emitter);
+            activeEmitters.set(deploymentId, options.emitter);
+        }
+        return recorder;
+    }
+    /**
+     * Subscribe to a ProgressEmitter. Each event is appended (bounded) to event_log; phase
+     * events also update the row's `status` and `phase` fields. Writes coalesce: a put is
+     * always pending after the first event in a burst, so chatty install output collapses
+     * to one row update per ~100ms instead of one per line.
+     */
+    subscribeTo(emitter) {
+        this.unsubscribe = emitter.subscribe((event) => {
+            this.appendEvent(event.event, event.data);
+        });
+    }
+    appendEvent(event, data) {
+        if (this.finished)
+            return;
+        const log = this.record.event_log;
+        log.push({ t: Date.now(), event, data });
+        // Keep the head (lifecycle spine) and tail (most-recent activity); drop the middle.
+        if (log.length > EVENT_LOG_MAX) {
+            const tailKeep = EVENT_LOG_MAX - EVENT_LOG_HEAD_KEEP - 1; // -1 for the truncation marker
+            const removedCount = log.length - EVENT_LOG_HEAD_KEEP - tailKeep;
+            log.splice(EVENT_LOG_HEAD_KEEP, log.length - EVENT_LOG_HEAD_KEEP - tailKeep, {
+                t: Date.now(),
+                event: 'truncated',
+                data: { dropped_events: removedCount },
+            });
+        }
+        // Phase events drive the canonical status/phase fields used by list_deployments.
+        if (event === 'phase' && data && typeof data === 'object') {
+            const p = data;
+            if (p.phase)
+                this.record.phase = p.phase;
+            if (p.status === 'start') {
+                const mapped = startStatusFor(p.phase);
+                if (mapped)
+                    this.record.status = mapped;
+            }
+        }
+        this.scheduleFlush();
+    }
+    // Coalesce writes: at most one in-flight put at a time. While a put is running, mark
+    // the record dirty; the chained continuation issues a follow-up put once the prior one
+    // settles. This keeps event_log writes O(1) puts per burst rather than O(N) per event.
+    scheduleFlush() {
+        if (this.pendingPut) {
+            this.dirty = true;
+            return;
+        }
+        this.pendingPut = this.put().finally(() => {
+            this.pendingPut = null;
+            if (this.dirty) {
+                this.dirty = false;
+                this.scheduleFlush();
+            }
+        });
+    }
+    /**
+     * Drain a payload source (Buffer or Readable) into the row's payload_blob attribute,
+     * computing sha256 and byte count alongside. After this resolves the row has been
+     * committed once with the final hash and size, and `this.row.payload_blob.stream()`
+     * yields a fresh Readable that callers can pass to extraction.
+     *
+     * Buffers the payload in memory (subject to PAYLOAD_BUFFER_CAP_BYTES) so the
+     * hash/size are known synchronously before we commit and so the blob's `saveBlob`
+     * lifecycle doesn't race with our digest() call. A streaming variant is a planned
+     * follow-up that uses the unused `hash`/`byteCount` instance fields below.
+     */
+    async ingestPayload(source) {
+        const hash = (0, node_crypto_2.createHash)('sha256');
+        let byteCount = 0;
+        let buffer;
+        if (Buffer.isBuffer(source)) {
+            buffer = source;
+        }
+        else if (typeof source === 'string') {
+            // Legacy CBOR/JSON path: payload arrives as a base64-encoded string.
+            buffer = Buffer.from(source, 'base64');
+        }
+        else {
+            const chunks = [];
+            let collected = 0;
+            for await (const chunk of source) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                collected += buf.length;
+                if (collected > PAYLOAD_BUFFER_CAP_BYTES) {
+                    source.destroy?.();
+                    throw new hdbError_ts_1.ClientError(`Deploy payload exceeds the ${PAYLOAD_BUFFER_CAP_BYTES} byte buffer cap. ` +
+                        `Use a package identifier (npm:/file:/git:) for larger components.`);
+                }
+                chunks.push(buf);
+            }
+            buffer = Buffer.concat(chunks);
+        }
+        if (buffer.length > PAYLOAD_BUFFER_CAP_BYTES) {
+            throw new hdbError_ts_1.ClientError(`Deploy payload (${buffer.length} bytes) exceeds the ${PAYLOAD_BUFFER_CAP_BYTES} byte buffer cap. ` +
+                `Use a package identifier (npm:/file:/git:) for larger components.`);
+        }
+        hash.update(buffer);
+        byteCount = buffer.length;
+        this.record.payload_blob = (0, blob_ts_1.createBlob)(buffer, { type: 'application/gzip' });
+        this.record.payload_hash = hash.digest('hex');
+        this.record.payload_size = byteCount;
+        // Touch the unused private fields so the type system stays happy when a streaming
+        // variant lands that uses them.
+        this.hash = hash;
+        this.byteCount = byteCount;
+        await this.put();
+    }
+    async transitionPhase(phase, status) {
+        this.record.phase = phase;
+        if (status)
+            this.record.status = status;
+        await this.put();
+    }
+    /**
+     * Upsert a single peer outcome by node name. Called per-peer as each replication
+     * target settles, so the row reflects in-flight progress rather than only the
+     * final aggregate. Routes through `scheduleFlush()` so the write coalesces with
+     * the emitter-driven puts and the latest in-memory state always wins.
+     *
+     * Tolerates unknown shapes — anything we can't interpret becomes a plain
+     * stringified entry so the audit trail at least records that a peer was contacted.
+     */
+    recordPeer(result) {
+        if (this.finished)
+            return;
+        const normalized = normalizePeerResult(result);
+        // Defensive: rows freshly created via create() always have peer_results=[], but if
+        // a replicated row was loaded back where the attribute is absent or null we want
+        // to initialize lazily rather than throw on `.findIndex`.
+        if (!Array.isArray(this.record.peer_results))
+            this.record.peer_results = [];
+        const list = this.record.peer_results;
+        // Upsert by node name when present; otherwise append (we can't dedupe without an id).
+        const nodeName = normalized.node;
+        const idx = nodeName ? list.findIndex((entry) => entry.node === nodeName) : -1;
+        if (idx >= 0) {
+            list[idx] = normalized;
+        }
+        else {
+            list.push(normalized);
+        }
+        this.scheduleFlush();
+    }
+    /**
+     * Bulk-record a final aggregate of peer outcomes. Equivalent to calling recordPeer()
+     * for each entry. Useful for replication layers that surface results all-at-once
+     * via Promise.allSettled rather than via a per-peer callback.
+     */
+    recordPeers(results) {
+        if (this.finished)
+            return;
+        if (!Array.isArray(results))
+            return;
+        for (const result of results)
+            this.recordPeer(result);
+    }
+    async finish(status, error) {
+        if (this.finished)
+            return;
+        // Send a terminal sentinel through the emitter (if any) BEFORE we unsubscribe and
+        // remove it from the registry, so any SSE tail subscribers can resolve their wait
+        // even on a code path that doesn't emit an explicit `error` event.
+        const emitter = activeEmitters.get(this.deploymentId);
+        emitter?.emit('_recorder_finished', { status });
+        this.finished = true;
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        activeEmitters.delete(this.deploymentId);
+        // Drain the ENTIRE coalesced-flush chain before mutating + persisting the terminal
+        // state. Just awaiting `this.pendingPut` once isn't enough: its `.finally` may
+        // re-schedule another put (when `dirty` was set during the in-flight put), and
+        // that re-scheduled put captures a pre-mutation snapshot of the record. Without
+        // this loop, the re-scheduled put can complete AFTER our terminal put and
+        // overwrite status=success with stale state.
+        while (this.pendingPut) {
+            try {
+                await this.pendingPut;
+            }
+            catch {
+                /* the next put surfaces the error */
+            }
+        }
+        this.record.status = status;
+        this.record.completed_at = Date.now();
+        if (error) {
+            const e = error;
+            this.record.error = {
+                message: e?.message ?? String(error),
+                code: e?.code,
+                phase: this.record.phase,
+            };
+        }
+        await this.put();
+    }
+    get row() {
+        return this.record;
+    }
+    async put() {
+        const table = databases_ts_1.databases.system?.[terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME];
+        if (!table) {
+            // Table missing means the upgrade directive hasn't run yet (or the table got dropped).
+            // We tolerate this — tracking is observability; the deploy itself must still succeed.
+            return;
+        }
+        await table.put(this.record);
+    }
+}
+exports.DeploymentRecorder = DeploymentRecorder;
+/**
+ * Peer-side helper — wait for the hdb_deployment row to arrive via table replication,
+ * then return it. The row is committed on origin before `replicateOperation` is
+ * called, so peers normally find it immediately; this polling loop is for the rare
+ * case where the operation arrives faster than the table-replication channel.
+ *
+ * The payload_blob's chunks may still be in flight after the row arrives — that's
+ * fine, the Blob's `stream()` / `bytes()` API blocks on incomplete writes
+ * (resources/blob.ts).
+ */
+async function awaitDeploymentRow(deploymentId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const maxIntervalMs = options.pollIntervalMs ?? 100;
+    // Start fast (5ms) so the common case — replication has already caught up — sees no
+    // human-noticeable latency, then back off exponentially up to maxIntervalMs for the
+    // rare case where the row is genuinely still replicating.
+    let intervalMs = options.initialPollIntervalMs ?? 5;
+    const table = databases_ts_1.databases.system?.[terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME];
+    if (!table) {
+        throw new Error(`Deployment tracking is not initialized on this node (system.${terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME} missing).`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const row = await table.get(deploymentId);
+            if (row && row.payload_blob != null)
+                return row;
+        }
+        catch (err) {
+            lastError = err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        intervalMs = Math.min(intervalMs * 2, maxIntervalMs);
+    }
+    throw new Error(`Timed out after ${timeoutMs}ms waiting for hdb_deployment row '${deploymentId}' to replicate` +
+        (lastError ? ` (last error: ${lastError.message ?? lastError})` : ''));
+}
+function normalizePeerResult(raw) {
+    if (!raw || typeof raw !== 'object') {
+        // Replication layer returned a primitive — preserve as a stringified marker so the
+        // audit row at least records that something came back from a peer.
+        return { node: null, status: 'unknown', raw: String(raw) };
+    }
+    const r = raw;
+    const err = r.error;
+    const hasError = err != null && (typeof err === 'string' ? err.length > 0 : typeof err === 'object' || typeof err === 'number');
+    return {
+        node: r.node ?? r.name ?? r.hostname ?? null,
+        status: hasError ? 'failed' : (r.status ?? 'success'),
+        error: hasError
+            ? {
+                message: typeof err === 'object' ? (err.message ?? String(err)) : String(err),
+                code: typeof err === 'object' ? err.code : undefined,
+            }
+            : null,
+        started_at: r.started_at ?? null,
+        completed_at: r.completed_at ?? null,
+    };
+}
+function startStatusFor(phase) {
+    switch (phase) {
+        case 'extract':
+            return 'extracting';
+        case 'install':
+            return 'installing';
+        case 'load':
+            return 'loading';
+        case 'replicate':
+            return 'replicating';
+        case 'restart':
+            return 'restarting';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=deploymentRecorder.js.map