@untangle-code/jobs 0.0.0-stage → 0.1.1

package/dist/bounded-queue.js

@@ -0,0 +1,338 @@
+import { indexIncompleteError } from "@untangle-code/observability";
+import { abortedPromise, throwIfAborted } from "./abort.js";
+/**
+ * Vorgabe fuer `maxOverBudgetAdmissions`: genau EIN Element, das das Budget
+ * allein sprengt, darf passieren (sonst haengt die Queue an ihm fest). Jedes
+ * weitere ist ein Konfigurationsfehler und wird als solcher gemeldet.
+ */
+const DEFAULT_OVER_BUDGET_ALLOWANCE = 1;
+export class BoundedQueue {
+    slots = [];
+    capacity;
+    maxBytes;
+    sizeOf;
+    overBudgetAllowance;
+    onOverBudgetAdmission;
+    overBudgetAdmissions = 0;
+    maxItemBytesObserved = 0;
+    bytes = 0;
+    closed = false;
+    failure = null;
+    wakers = [];
+    maxDepthObserved = 0;
+    maxBytesObserved = 0;
+    constructor(options) {
+        // WP-116: `capacity` ist ueber `IndexJobRunnerOptions.queueCapacities`
+        // frei konfigurierbar und entscheidet mit darueber, ob die Byte-Grenze
+        // ueberhaupt greifen kann — deshalb wird sie hier so hart geprueft wie
+        // `maxBytes`. `Number.isInteger(1e21)` ist true, `isSafeInteger` nicht:
+        // eine Kapazitaet jenseits der sicheren Ganzzahlen ist als Grenze
+        // wertlos, weil Vergleiche und Zaehler darauf nicht mehr exakt sind.
+        if (!Number.isSafeInteger(options.capacity) || options.capacity < 1) {
+            throw new Error(`BoundedQueue capacity must be a safe integer >= 1, got ${String(options.capacity)}`);
+        }
+        if (options.maxBytes !== undefined) {
+            if (options.sizeOf === undefined) {
+                throw new Error("BoundedQueue maxBytes requires a sizeOf cost function");
+            }
+            // Same defect class as an invalid per-item size (see `validateSize`
+            // below): a non-finite/negative budget disables the byte check just
+            // as surely as a poisoned item does, only permanently instead of
+            // transiently — e.g. `Math.floor(memoryBudgetBytes / 2)` silently
+            // produces `NaN`/`Infinity` when a caller's `memoryBudgetBytes` is
+            // itself malformed (runner.ts). Reject at construction, before any
+            // item is ever admitted.
+            BoundedQueue.validateSize(options.maxBytes, "maxBytes");
+        }
+        const allowance = options.maxOverBudgetAdmissions ?? DEFAULT_OVER_BUDGET_ALLOWANCE;
+        if (!Number.isSafeInteger(allowance) || allowance < 0) {
+            throw new Error(`BoundedQueue maxOverBudgetAdmissions must be a safe integer >= 0, got ${String(options.maxOverBudgetAdmissions)}`);
+        }
+        this.capacity = options.capacity;
+        this.maxBytes = options.maxBytes ?? null;
+        this.sizeOf = options.sizeOf ?? null;
+        this.overBudgetAllowance = allowance;
+        this.onOverBudgetAdmission = options.onOverBudgetAdmission ?? null;
+    }
+    /**
+     * Rejects a caller-supplied byte size (a per-item `sizeOf(item)` result or
+     * the constructor's `maxBytes`) that is not finite and >= 0.
+     *
+     * This is deliberately a hard rejection, never a clamp to some
+     * conservative substitute: the whole point of `maxBytes`/`sizeOf` is that
+     * the QUEUE trusts the caller's cost estimate to keep the pipeline's
+     * memory bound truthful (architecture.md §13.2, "a hard limit, not a
+     * hope"). A `NaN`/`Infinity`/negative size means that trust is already
+     * broken — the caller's cost model produced a value with no relationship
+     * to real memory use — so any number the queue might invent instead
+     * (0, the budget itself, the last good size, …) would just re-establish
+     * that same false trust one layer down and let corrupted accounting
+     * accumulate exactly as the adversarial repro showed (`Infinity` on an
+     * empty queue turns `bytes` into `NaN` on the very next `pull()`, which
+     * then compares `false` against every future budget check forever). A
+     * caller that cannot produce a valid size has a bug that must surface as
+     * a failed job (spec.md §25.2: write-side operations fail closed when
+     * consistency cannot be guaranteed), not as a silently-disabled budget.
+     */
+    static validateSize(size, field) {
+        if (Number.isFinite(size) && size >= 0) {
+            return;
+        }
+        throw indexIncompleteError(`BoundedQueue received an invalid byte size from ${field} (${String(size)}); ` +
+            "sizes must be finite numbers >= 0 — a NaN/Infinity/negative size would " +
+            "silently disable the byte budget (architecture.md §13.2)", { retryable: false, operation: "bounded_queue_size", context: { field, size } });
+    }
+    /**
+     * Defense-in-depth invariant on the running `bytes` counter itself, on
+     * top of `validateSize()` at every entry point: `bytes` is a sum of
+     * values that already passed `validateSize()`, so it should never go
+     * non-finite or negative — but "should never" is not a guarantee, and a
+     * counter that silently drifts into `NaN`/negative is exactly as
+     * dangerous as an unchecked input (it disables the same budget check the
+     * same way). Called after every mutation of `bytes`; poisons the queue
+     * and throws rather than letting `push()`/`pull()` keep computing on a
+     * counter that can no longer prove the budget (spec.md §25.2, fail
+     * closed).
+     */
+    assertByteCounterIntact(operation) {
+        if (Number.isFinite(this.bytes) && this.bytes >= 0) {
+            return;
+        }
+        const corrupted = indexIncompleteError(`BoundedQueue's internal byte counter became invalid (${String(this.bytes)}) during ` +
+            `${operation}() despite validated inputs — refusing to continue accounting on a ` +
+            "counter that can no longer prove the byte budget (architecture.md §13.2)", { retryable: false, operation: `bounded_queue_${operation}`, context: { bytes: this.bytes } });
+        // Poison rather than merely throw: a corrupted counter is a queue-wide
+        // invariant violation, not a one-off bad call — every other pending and
+        // future push()/pull() must see the same failure.
+        this.fail(corrupted);
+        throw corrupted;
+    }
+    notify() {
+        const wakers = this.wakers;
+        this.wakers = [];
+        for (const wake of wakers) {
+            wake();
+        }
+    }
+    async waitForChange(signal) {
+        const wake = new Promise((resolve) => this.wakers.push(resolve));
+        if (signal === undefined) {
+            await wake;
+            return;
+        }
+        const cleanup = new AbortController();
+        try {
+            await Promise.race([wake, abortedPromise(signal, cleanup.signal)]);
+        }
+        finally {
+            cleanup.abort();
+        }
+    }
+    /**
+     * Entscheidet ueber eine Aufnahme, ohne etwas zu veraendern.
+     *
+     * - `"admit"`  — Element passt in beide Grenzen.
+     * - `"wait"`   — kein Platz; Warten kann Platz schaffen (Rueckstau).
+     * - `"over-budget"` — Element ist ALLEIN groesser als das ganze Budget:
+     *   Warten kann fuer dieses Element nie Platz schaffen, die Ausnahme greift.
+     *
+     * WP-116: Frueher haengte der Byte-Zweig an `slots.length > 0`. Auf einer
+     * leeren Queue ist `bytes === 0`, also fiel „Element passt nicht ins
+     * Budget" mit „Element ist allein zu gross" nur zufaellig zusammen — und
+     * bei `capacity: 1` ist die Queue vor JEDEM Push leer, womit die Ausnahme
+     * zum Dauerzustand wurde und die Byte-Grenze mit voellig gueltigen Werten
+     * abgeschaltet war (belegt: 20 x 50 MB durch ein 100-Byte-Budget). Die
+     * Bedingung steht jetzt dort, wo sie hingehoert: am ELEMENT
+     * (`size > maxBytes`), nicht am Fuellstand.
+     */
+    admissionVerdict(size) {
+        if (this.slots.length >= this.capacity) {
+            return "wait";
+        }
+        if (this.maxBytes === null) {
+            return "admit";
+        }
+        this.assertEmptyStateCounter();
+        if (this.bytes + size <= this.maxBytes) {
+            return "admit";
+        }
+        if (size > this.maxBytes) {
+            // Das Element sprengt das Budget aus eigener Kraft. Es wird nur in die
+            // LEERE Queue aufgenommen, damit die Verletzung nie mit anderen
+            // Elementen kumuliert; ist noch etwas gepuffert, schafft Warten sehr
+            // wohl Platz (naemlich die leere Queue).
+            return this.slots.length === 0 ? "over-budget" : "wait";
+        }
+        // Passt grundsaetzlich ins Budget, gerade nur nicht: klassischer
+        // Rueckstau — genau der Mechanismus, den §13.2 will.
+        return "wait";
+    }
+    /**
+     * Invariante der leeren Queue: ohne gepufferte Elemente MUSS `bytes` 0
+     * sein. Frueher hat der Byte-Zweig diese Annahme stillschweigend benutzt
+     * (`slots.length > 0` als Ersatz fuer `bytes === 0`); jetzt wird sie
+     * geprueft, damit eine kuenftige Abweichung als Fehler auffaellt und nicht
+     * als lautlos abgeschaltete Grenze.
+     */
+    assertEmptyStateCounter() {
+        if (this.slots.length !== 0 || this.bytes === 0) {
+            return;
+        }
+        const corrupted = indexIncompleteError(`BoundedQueue holds no items but its byte counter reads ${String(this.bytes)} — the byte ` +
+            "budget can no longer be proven, refusing to admit further items (architecture.md §13.2)", {
+            retryable: false,
+            operation: "bounded_queue_empty_state",
+            context: { bytes: this.bytes, depth: this.slots.length },
+        });
+        this.fail(corrupted);
+        throw corrupted;
+    }
+    /**
+     * Bucht eine Ausnahme. Ist das Kontingent erschoepft, scheitert der Push
+     * mit benanntem, nicht wiederholbarem Fehler — fail closed (spec.md
+     * §25.2) statt einer Budgetverletzung, die niemand sieht. Absichtlich
+     * KEIN Warten: fuer ein Element groesser als das Budget kann Warten nie
+     * Platz schaffen, ein Warten waere ein Haenger statt eines Rueckstaus.
+     */
+    admitOverBudget(size) {
+        const maxBytes = this.maxBytes ?? 0;
+        if (this.overBudgetAdmissions >= this.overBudgetAllowance) {
+            throw indexIncompleteError(`BoundedQueue refuses a ${String(size)}-byte item: it exceeds the queue's entire ` +
+                `${String(maxBytes)}-byte budget on its own, and this queue already admitted ` +
+                `${String(this.overBudgetAdmissions)} such item(s) (allowance ` +
+                `${String(this.overBudgetAllowance)}). The exception exists for a SINGLE oversized ` +
+                "item that would otherwise block the queue forever, not as a permanent state that " +
+                "turns the byte budget off (architecture.md §13.2). Raise the byte budget, reduce the " +
+                "item size, or skip this item and record the skip with a reason.", {
+                retryable: false,
+                operation: "bounded_queue_push",
+                context: {
+                    itemBytes: size,
+                    maxBytes,
+                    overBudgetAdmissions: this.overBudgetAdmissions,
+                    allowance: this.overBudgetAllowance,
+                },
+            });
+        }
+        this.overBudgetAdmissions += 1;
+        this.onOverBudgetAdmission?.({
+            itemBytes: size,
+            maxBytes,
+            ordinal: this.overBudgetAdmissions,
+            allowance: this.overBudgetAllowance,
+        });
+    }
+    /**
+     * Enqueues `item`, waiting while the queue is full (count or byte bound) —
+     * this wait IS the backpressure that pauses the previous stage. Rejects
+     * with `JOB_CANCELLED` when `options.signal` aborts, and with the failure
+     * error after `fail()`.
+     */
+    async push(item, options) {
+        const size = this.sizeOf === null ? 0 : this.sizeOf(item);
+        // Validate BEFORE the item ever reaches `hasRoomFor()`/`bytes` — an
+        // invalid size must never be accepted "for now" and dealt with later;
+        // by the time it is in `bytes` it has already corrupted the budget.
+        BoundedQueue.validateSize(size, "sizeOf(item)");
+        while (true) {
+            if (this.failure !== null) {
+                throw this.failure.error;
+            }
+            if (this.closed) {
+                throw new Error("BoundedQueue.push() called after close()");
+            }
+            throwIfAborted(options?.signal, "bounded_queue_push");
+            const verdict = this.admissionVerdict(size);
+            if (verdict === "admit") {
+                break;
+            }
+            if (verdict === "over-budget") {
+                // Bucht die Ausnahme oder wirft, wenn das Kontingent aufgebraucht
+                // ist. Erst NACH dieser Buchung wird das Element aufgenommen.
+                this.admitOverBudget(size);
+                break;
+            }
+            await this.waitForChange(options?.signal);
+        }
+        this.slots.push({ item, size });
+        this.bytes += size;
+        this.assertByteCounterIntact("push");
+        this.maxDepthObserved = Math.max(this.maxDepthObserved, this.slots.length);
+        this.maxBytesObserved = Math.max(this.maxBytesObserved, this.bytes);
+        this.maxItemBytesObserved = Math.max(this.maxItemBytesObserved, size);
+        this.notify();
+    }
+    /**
+     * Dequeues the oldest item, waiting while the queue is empty. Returns
+     * `{ done: true }` once the queue is closed AND drained. Rejects with
+     * `JOB_CANCELLED` when `options.signal` aborts, and with the failure
+     * error after `fail()` (buffered items are NOT delivered after a failure —
+     * the pipeline is broken and must not continue on stale work).
+     */
+    async pull(options) {
+        while (true) {
+            if (this.failure !== null) {
+                throw this.failure.error;
+            }
+            throwIfAborted(options?.signal, "bounded_queue_pull");
+            const slot = this.slots.shift();
+            if (slot !== undefined) {
+                this.bytes -= slot.size;
+                this.assertByteCounterIntact("pull");
+                this.notify();
+                return { done: false, value: slot.item };
+            }
+            if (this.closed) {
+                return { done: true };
+            }
+            await this.waitForChange(options?.signal);
+        }
+    }
+    /** Non-blocking pull: `null` when nothing is buffered right now. */
+    tryPull() {
+        if (this.failure !== null) {
+            throw this.failure.error;
+        }
+        const slot = this.slots.shift();
+        if (slot !== undefined) {
+            this.bytes -= slot.size;
+            this.assertByteCounterIntact("tryPull");
+            this.notify();
+            return { done: false, value: slot.item };
+        }
+        if (this.closed) {
+            return { done: true };
+        }
+        return null;
+    }
+    /** No more pushes; pulls drain the remaining items, then report done. */
+    close() {
+        this.closed = true;
+        this.notify();
+    }
+    /**
+     * Poisons the queue: every pending and future `push`/`pull` rejects with
+     * `error`. Used to unblock sibling pipeline workers when one stage fails.
+     */
+    fail(error) {
+        if (this.failure === null) {
+            this.failure = { error };
+        }
+        this.closed = true;
+        this.notify();
+    }
+    stats() {
+        return {
+            depth: this.slots.length,
+            capacity: this.capacity,
+            bytes: this.bytes,
+            maxBytes: this.maxBytes,
+            maxDepthObserved: this.maxDepthObserved,
+            maxBytesObserved: this.maxBytesObserved,
+            overBudgetAdmissions: this.overBudgetAdmissions,
+            overBudgetAllowance: this.overBudgetAllowance,
+            maxItemBytesObserved: this.maxItemBytesObserved,
+        };
+    }
+}
+//# sourceMappingURL=bounded-queue.js.map

package/dist/bounded-queue.js.map

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

package/dist/checkpoint-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File-backed `CheckpointStorePort` (architecture.md §6.14, §13.3) on top of
+ * the injected `FileSystemPort` — atomic via the temp+rename pattern the
+ * port guarantees for `rename`.
+ *
+ * Error semantics (spec.md §25.2): a MISSING checkpoint is `null` — never an
+ * error; a CORRUPT checkpoint file is an `UntangleError` with code
+ * `INDEX_INCOMPLETE` — never silently treated as "not found", because that
+ * would silently discard confirmed work and restart from scratch.
+ */
+import type { FileSystemPort, IndexCheckpointV1, PortCallOptions, CheckpointStorePort } from "@untangle-code/domain";
+/** Structural guard for the exact `IndexCheckpointV1` shape (§13.3). */
+export declare function isIndexCheckpointV1(value: unknown): value is IndexCheckpointV1;
+export interface FileCheckpointStoreOptions {
+    /** Directory the checkpoint JSON files live in; created on first save. */
+    directory: string;
+}
+export declare class FileCheckpointStore implements CheckpointStorePort {
+    private readonly fs;
+    private readonly directory;
+    private tmpCounter;
+    constructor(fs: FileSystemPort, options: FileCheckpointStoreOptions);
+    private pathFor;
+    save(checkpoint: IndexCheckpointV1, options?: PortCallOptions): Promise<void>;
+    load(jobId: string, options?: PortCallOptions): Promise<IndexCheckpointV1 | null>;
+    loadLatest(repoId: string, refId: string, options?: PortCallOptions): Promise<IndexCheckpointV1 | null>;
+    delete(jobId: string, options?: PortCallOptions): Promise<void>;
+    private parseCheckpoint;
+}
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/checkpoint-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../src/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAwB/B,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAkB9E;AAED,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,mBAAoB,YAAW,mBAAmB;IAC7D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,UAAU,CAAK;gBAEJ,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,0BAA0B;IAK1E,OAAO,CAAC,OAAO;IAOF,IAAI,CAAC,UAAU,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB7E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAWjF,UAAU,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA4BvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5E,OAAO,CAAC,eAAe;CAqBxB"}

package/dist/checkpoint-store.js

@@ -0,0 +1,131 @@
+import { sha256Hex } from "@untangle-code/domain";
+import { indexIncompleteError } from "@untangle-code/observability";
+import { throwIfAborted } from "./abort.js";
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isStringRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every((entry) => typeof entry === "string");
+}
+function isStringArrayRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every((entry) => isStringArray(entry));
+}
+/** Structural guard for the exact `IndexCheckpointV1` shape (§13.3). */
+export function isIndexCheckpointV1(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record["jobId"] === "string" &&
+        typeof record["generationId"] === "string" &&
+        typeof record["workspaceId"] === "string" &&
+        typeof record["repoId"] === "string" &&
+        typeof record["refId"] === "string" &&
+        typeof record["effectiveProfileId"] === "string" &&
+        isStringArray(record["completedFiles"]) &&
+        isStringArrayRecord(record["storedPointIdsByFile"]) &&
+        isStringRecord(record["manifestHashes"]) &&
+        typeof record["stage"] === "string" &&
+        typeof record["savedAt"] === "string");
+}
+export class FileCheckpointStore {
+    fs;
+    directory;
+    tmpCounter = 0;
+    constructor(fs, options) {
+        this.fs = fs;
+        this.directory = options.directory.replace(/\/+$/u, "");
+    }
+    pathFor(jobId) {
+        // jobIds are usually UUIDs, but the file name must stay collision-free
+        // and path-safe for ANY id: sanitize, then disambiguate with a hash.
+        const safe = jobId.replace(/[^A-Za-z0-9._-]/gu, "_");
+        return `${this.directory}/${safe}-${sha256Hex(jobId).slice(0, 8)}.json`;
+    }
+    async save(checkpoint, options) {
+        throwIfAborted(options?.signal, "checkpoint_save");
+        if (!isIndexCheckpointV1(checkpoint)) {
+            throw indexIncompleteError("refusing to persist a malformed checkpoint", {
+                retryable: false,
+                operation: "checkpoint_save",
+            });
+        }
+        await this.fs.mkdir(this.directory, { recursive: true, ...(options ?? {}) });
+        const path = this.pathFor(checkpoint.jobId);
+        this.tmpCounter += 1;
+        const tmpPath = `${path}.tmp-${this.tmpCounter}`;
+        const bytes = new TextEncoder().encode(`${JSON.stringify(checkpoint, null, 2)}\n`);
+        await this.fs.writeFile(tmpPath, bytes, options);
+        await this.fs.rename(tmpPath, path, options);
+    }
+    async load(jobId, options) {
+        throwIfAborted(options?.signal, "checkpoint_load");
+        const path = this.pathFor(jobId);
+        const stat = await this.fs.stat(path, options);
+        if (stat === null) {
+            return null;
+        }
+        const text = await this.fs.readTextFile(path, options);
+        return this.parseCheckpoint(text, path);
+    }
+    async loadLatest(repoId, refId, options) {
+        throwIfAborted(options?.signal, "checkpoint_load_latest");
+        const dirStat = await this.fs.stat(this.directory, options);
+        if (dirStat === null) {
+            return null;
+        }
+        const entries = await this.fs.readDir(this.directory, options);
+        let latest = null;
+        for (const entry of entries) {
+            if (entry.kind !== "file" || !entry.name.endsWith(".json")) {
+                continue;
+            }
+            const text = await this.fs.readTextFile(entry.path, options);
+            const checkpoint = this.parseCheckpoint(text, entry.path);
+            if (checkpoint.repoId !== repoId || checkpoint.refId !== refId) {
+                continue;
+            }
+            if (latest === null ||
+                checkpoint.savedAt > latest.savedAt ||
+                (checkpoint.savedAt === latest.savedAt && checkpoint.jobId > latest.jobId)) {
+                latest = checkpoint;
+            }
+        }
+        return latest;
+    }
+    async delete(jobId, options) {
+        throwIfAborted(options?.signal, "checkpoint_delete");
+        // `FileSystemPort.remove` is force-style: a missing file is not an error,
+        // which makes delete idempotent by design.
+        await this.fs.remove(this.pathFor(jobId), options);
+    }
+    parseCheckpoint(text, path) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (cause) {
+            throw indexIncompleteError(`checkpoint file is not valid JSON: ${path}`, {
+                retryable: false,
+                operation: "checkpoint_load",
+                context: { path },
+                cause,
+            });
+        }
+        if (!isIndexCheckpointV1(parsed)) {
+            throw indexIncompleteError(`checkpoint file has an invalid shape: ${path}`, {
+                retryable: false,
+                operation: "checkpoint_load",
+                context: { path },
+            });
+        }
+        return parsed;
+    }
+}
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/checkpoint-store.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Single-consumer async event channel — the transport that makes the typed
+ * job events of architecture.md §2.2 consumable as an `AsyncIterable`
+ * (spec.md §22: `index()` returns `AsyncIterable<JobEvent>`).
+ *
+ * The producer side (`emit`) never blocks: job events are small, bounded in
+ * number per batch, and the pipeline's memory pressure is controlled by the
+ * bounded work queues, not by the event stream. `fail()` exists for
+ * catastrophic driver bugs only — regular job failures are emitted as
+ * `job_failed` events and end the stream via `close()`.
+ */
+export declare class AsyncEventChannel<T> implements AsyncIterable<T> {
+    private readonly buffer;
+    private closed;
+    private failure;
+    private wakers;
+    /** Enqueues one event. Throws when the channel is already closed/failed. */
+    emit(event: T): void;
+    /** Ends the stream after all buffered events were consumed. Idempotent. */
+    close(): void;
+    /**
+     * Ends the stream with a rejection after all buffered events were
+     * consumed. Idempotent; a later `fail()` does not override an earlier one.
+     */
+    fail(error: unknown): void;
+    private notify;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qBAAa,iBAAiB,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,MAAM,CAAyB;IAEvC,4EAA4E;IACrE,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAQ3B,2EAA2E;IACpE,KAAK,IAAI,IAAI;IAKpB;;;OAGG;IACI,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAQjC,OAAO,CAAC,MAAM;IAQA,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAiBzD"}

package/dist/events.js

@@ -0,0 +1,66 @@
+/**
+ * Single-consumer async event channel — the transport that makes the typed
+ * job events of architecture.md §2.2 consumable as an `AsyncIterable`
+ * (spec.md §22: `index()` returns `AsyncIterable<JobEvent>`).
+ *
+ * The producer side (`emit`) never blocks: job events are small, bounded in
+ * number per batch, and the pipeline's memory pressure is controlled by the
+ * bounded work queues, not by the event stream. `fail()` exists for
+ * catastrophic driver bugs only — regular job failures are emitted as
+ * `job_failed` events and end the stream via `close()`.
+ */
+export class AsyncEventChannel {
+    buffer = [];
+    closed = false;
+    failure = null;
+    wakers = [];
+    /** Enqueues one event. Throws when the channel is already closed/failed. */
+    emit(event) {
+        if (this.closed) {
+            throw new Error("AsyncEventChannel.emit() called after close()/fail()");
+        }
+        this.buffer.push(event);
+        this.notify();
+    }
+    /** Ends the stream after all buffered events were consumed. Idempotent. */
+    close() {
+        this.closed = true;
+        this.notify();
+    }
+    /**
+     * Ends the stream with a rejection after all buffered events were
+     * consumed. Idempotent; a later `fail()` does not override an earlier one.
+     */
+    fail(error) {
+        if (this.failure === null) {
+            this.failure = { error };
+        }
+        this.closed = true;
+        this.notify();
+    }
+    notify() {
+        const wakers = this.wakers;
+        this.wakers = [];
+        for (const wake of wakers) {
+            wake();
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.buffer.length > 0) {
+                // `length > 0` guarantees the shift result is a T, even for a T that
+                // could itself include `undefined`.
+                yield this.buffer.shift();
+                continue;
+            }
+            if (this.failure !== null) {
+                throw this.failure.error;
+            }
+            if (this.closed) {
+                return;
+            }
+            await new Promise((resolve) => this.wakers.push(resolve));
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,OAAO,iBAAiB;IACX,MAAM,GAAQ,EAAE,CAAC;IAC1B,MAAM,GAAG,KAAK,CAAC;IACf,OAAO,GAA8B,IAAI,CAAC;IAC1C,MAAM,GAAsB,EAAE,CAAC;IAEvC,4EAA4E;IACrE,IAAI,CAAC,KAAQ;QAClB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,2EAA2E;IACpE,KAAK;QACV,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,IAAI,CAAC,KAAc;QACxB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAEO,MAAM;QACZ,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAClC,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,qEAAqE;gBACrE,oCAAoC;gBACpC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAO,CAAC;gBAC/B,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC1B,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;YAC3B,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,OAAO;YACT,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @untangle-code/jobs — the job core of the Untangle indexer
+ * (spec.md §11, §12.2; architecture.md §2.2, §6.14, §13, §21.3–§21.4).
+ *
+ * Pipeline MECHANICS only: the exact spec.md §11.1 state machine, typed job
+ * events as `AsyncIterable`, a checkpoint store (`IndexCheckpointV1`,
+ * checkpoints only after confirmed upserts), resume planning, generation
+ * commit per §13.4, bounded queues with backpressure and a visible memory
+ * budget, and `AbortSignal` cancellation at safe batch boundaries. The
+ * domain-specific stages (scanner, parser, chunker, embedder, stores) are
+ * injected behind narrow interfaces. This module is the ONLY public export
+ * of the package.
+ */
+export * from "./abort.js";
+export * from "./state-machine.js";
+export * from "./events.js";
+export * from "./bounded-queue.js";
+export * from "./stages.js";
+export * from "./checkpoint-store.js";
+export * from "./resume.js";
+export * from "./runner.js";
+//# sourceMappingURL=index.d.ts.map