@untangle-code/jobs 0.0.0-stage → 0.1.0

package/NOTICE

@@ -0,0 +1,90 @@
+# NOTICE
+
+Copyright (C) 2026 Luke Bölling and contributors.
+
+This attribution covers original Untangle work. Contributors retain copyright in
+their contributions. Third-party packages, grammars and other materials retain
+their own copyright holders, licenses and notices; this line does not replace them.
+
+## License — binding decision
+
+Untangle is licensed under the **GNU Affero General Public License, Version 3
+(AGPL-3.0-only)**. See [`LICENSE`](./LICENSE).
+
+This decision is **final, not provisional**, and was explicitly instructed by
+the project owner. No contributor, agent or tool may change it without a new
+explicit instruction.
+
+The repository-wide license covers Untangle's first-party source code, scripts,
+tests, fixtures, configuration, documentation, website and brand artwork, including
+the logo and 3D yarn illustrations. Every workspace `package.json` declares
+`"license": "AGPL-3.0-only"`. There is no separately licensed enterprise component
+or separate permissive license for documentation or brand assets.
+
+Third-party code, embedded grammars, dependency assets and their notices retain
+their original licenses. Their inclusion does not relicense those works. The
+repository license does not grant trademark rights or change the license of a
+repository analyzed with Untangle. See the repository's `docs/LICENSING.md` for
+scope and verification details.
+
+This resolves the license question left open in `vision.md` §14 and completes
+`product.md` §16, item 2.
+
+## Rationale
+
+- **Network copyleft fits the intended product model.** AGPL §13 sets source
+  availability requirements for modified versions used through a computer network.
+  The current local CLI/stdio-MCP entry and future shared-server modes share the
+  same license.
+- **Local-first analysis has a clear boundary.** Running Untangle against a codebase
+  does not replace that codebase's own license with Untangle's license.
+- **First-party components share one license.** Implemented components and future
+  official plugins use this repository's licensing policy. Planned integrations do
+  not establish implemented or published products.
+
+## Deliberately accepted consequence
+
+The project deliberately chooses AGPL rather than a permissive embedding license.
+Redistribution, modifications and combined works must be assessed against the
+actual terms in `LICENSE`, including applicable Corresponding Source requirements.
+No permissive exception, commercial dual license or special contract-only package
+license is granted or promised by this notice.
+
+## Dependencies
+
+Third-party runtime dependencies are checked against the allowlist in
+`scripts/check-licenses.mjs`. Their licenses and copyright notices remain unchanged
+and traceable through package `THIRD_PARTY_LICENSES.md` files, grammar provenance,
+the lockfile and release SBOM. The allowlist includes MIT / Apache-2.0 / BSD / ISC
+and other explicitly listed licenses; it is not a license grant for dependencies.
+
+The allowlist in `scripts/check-licenses.mjs` applies to **dependencies**, not
+workspace packages. Untangle's own packages carry AGPL-3.0-only and are excluded
+from that check.
+
+## Clean room
+
+Untangle is an independent implementation with its own data models, APIs, tool
+names, tests and sources. Feature ideas may be derived from publicly observable
+behavior and generally known techniques. Third-party source code is not copied,
+including from AGPL projects even where the license would permit it.
+
+## Contribution terms
+
+Pull requests are welcome under the repository's existing AGPL-3.0-only license.
+No separate CLA, copyright assignment or DCO sign-off is required. Contributors
+must have the right to submit their work under those terms. See CONTRIBUTING.md.
+
+## Release decisions
+
+- [x] Copyright attribution: Luke Bölling, with contributors retaining their rights.
+- [x] Contributions use AGPL-3.0-only without an additional CLA or DCO gate.
+
+## Open legal items before public beta
+
+- [ ] Trademark search for the product name `Untangle`.
+- [ ] Registration and legal review of the npm scope `@untangle-code`.
+- [ ] Verify source availability and notices for each released network daemon/server
+  mode (WP-59). The current stdio MCP `untangle_about` already reports the license,
+  source repository and build commit when supplied; metadata alone does not prove
+  that a concrete deployed version's source is available.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @untangle-code/jobs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Untangle indexer's job core (WP-13): state machine, typed job events, checkpoints, resume
+planning, generation commit, bounded queues with backpressure and cancellation through `AbortSignal`.
+
+Normative sources: `spec.md` §10.5, §11, §12.2, §22; `architecture.md` §2.2, §6.14, §13.1–§13.4,
+§21.3–§21.4, §27.5.
+
+<a id="inhalt"></a>
+
+## Contents
+
+- **`JobStateMachine`** (`state-machine.ts`): exactly the state machine from spec.md §11.1,
+  including `failed`, `cancel_requested`, `cancelled`. Illegal transitions are rejected with typed
+  errors, never silently ignored.
+- **`AsyncEventChannel`** (`events.ts`): exposes the typed job events from architecture.md §2.2
+  (types in `@untangle-code/domain`) as `AsyncIterable<JobEvent>` (spec.md §22).
+- **`BoundedQueue`** (`bounded-queue.ts`): bounded queues from architecture.md §13.2. A full queue
+  blocks `push()`, pausing the previous stage. Limits apply to count AND bytes; high-water marks
+  are visible through `stats()`.
+- **`FileCheckpointStore`** (`checkpoint-store.ts`): `CheckpointStorePort` using `FileSystemPort`,
+  atomic through temp+rename, with the exact `IndexCheckpointV1` shape (§13.3).
+- **`planResume`** (`resume.ts`): reconstructs remaining work from the last acknowledged checkpoint
+  (spec.md §11.2).
+- **Stage interfaces** (`stages.ts`): narrow injectable contracts for discovery, analysis,
+  embedding, storage, graphs, context and generation commit. This package builds pipeline
+  MECHANICS, not domain stages.
+- **`IndexJobRunner`** (`runner.ts`): orchestrates events, queues, checkpoints only after
+  acknowledged upserts (spec.md §10.5), cancellation only at safe batch boundaries
+  (architecture.md §21.3), and `completed` only after complete generation commit (§13.4, enforced
+  by domain's `assertGenerationComplete`). On success its terminal observer also publishes the
+  immutable `corpusRevisionFingerprint` of the fully scanned corpus manifest.
+
+<a id="entscheidungen"></a>
+
+## Decisions
+
+Deliberate choices left open by source documents:
+
+1. **State-machine transition relation.** spec.md §11.1 lists the pipeline chain and error states,
+   but not every edge. Only the immediately next stage is reachable along the chain; `failed` and
+   `cancel_requested` are reachable from every nonterminal pipeline stage; `cancel_requested`
+   leads only to `cancelled` (or `failed` if cancellation cleanup itself fails); `completed`,
+   `failed`, `cancelled` are terminal; self-transitions are not transitions.
+2. **Stage as a high-water mark.** The pipeline overlaps work, using backpressure rather than
+   phase barriers. The state machine therefore advances as a high-water mark (`advanceTo`) when
+   the first work unit reaches a phase. Every individual movement is a legal chain transition;
+   it never moves backward. A run without remaining work also crosses intermediate stages legally
+   with no work.
+3. **Error code for illegal transitions and untyped stage errors.** The closed catalog
+   (spec.md §25.1) has no "internal state error" code. Illegal transitions or untyped stage errors
+   leave the index incomplete, so they use `INDEX_INCOMPLETE` (`retryable: false`), never a guessed
+   infrastructure code (spec.md §25.2). A dedicated code would be clearer and is recorded as an
+   additive proposal for the domain owner.
+4. **Corrupt checkpoint is not missing checkpoint.** `load`/`loadLatest` return `null` only for
+   absence. A corrupt checkpoint throws `INDEX_INCOMPLETE`; silently ignoring it would discard
+   acknowledged work and silently restart, prohibited by spec.md §25.2 and E4.
+5. **Resume validity.** A checkpoint is accepted only when workspace, repository, ref AND
+   `effectiveProfileId` agree (incompatible profiles require a new generation, spec.md §11.2).
+   An acknowledged file is skipped only when its content hash also remains unchanged (hash is
+   the source of truth, spec.md §12.1). Changed or no-longer-planned files leave the adopted state
+   and require fresh acknowledgement; they are never counted twice.
+6. **Event-stream cancellation semantics.** `run()` does NOT throw for job failure or
+   cancellation; it ends the stream with exactly one terminal event
+   (`job_completed` | `job_failed` | `job_cancelled`), the consumable form of returning `cancelled`
+   (architecture.md §21.3). Inside the package, long-running methods abort with
+   `UntangleError("JOB_CANCELLED")` (spec.md §22). A consumer stopping iteration stops the job
+   through internal abort; without external abort, this counts as failure rather than user cancellation.
+7. **Memory budget.** One budget (`memoryBudgetBytes`, default 64 MiB) is split equally between
+   analysis and upsert queues and appears alongside queue depths in `status()`
+   (architecture.md §13.2). `queueCapacities`, `embedBatchSize` and `memoryBudgetBytes` are validated
+   when constructing the runner (`CONFIG_INVALID`), not halfway through a run.
+
+   The **only** exception is an item that **alone** exceeds the entire byte budget. Rejecting it
+   would silently drop data; waiting would hang rather than apply backpressure because no pull
+   could ever create enough room. The exception is narrow:
+   - It applies to the ITEM (`size > maxBytes`), not queue occupancy;
+   - It applies only to an empty queue so the violation never accumulates with other items;
+   - It has a quota (`maxOverBudgetAdmissions`, default 1); once exhausted, `push()` fails with
+     `INDEX_INCOMPLETE` rather than permanently exceeding the budget;
+   - Every admission is counted (`stats().overBudgetAdmissions`), reported
+     (`onOverBudgetAdmission`, logged by the runner as `queue_over_budget_admission`) and reflected
+     in high-water marks. Budget violations are never silent (E4).
+
+   Before WP-116, the byte branch depended on `slots.length > 0`. With `capacity: 1`, the queue is
+   empty before every push, so the exception applied to EVERY push: 20 × 50 MB crossed a 100-byte
+   budget without a single blocked push, despite fully valid configuration.
+8. **Checkpoint batch equals embedding batch.** `embedBatchSize` defines the configured file
+   batch in spec.md §11.2: exactly one checkpoint is written after each acknowledged batch
+   upsert, never before (spec.md §10.5).
+9. **Commit order.** Before generation commit, the runner prechecks through
+   `validateGenerationCompleteness` with assumed metadata status; AFTER commit,
+   `assertGenerationComplete` also enforces the actually reached final metadata state. An
+   incomplete generation is never submitted for commit.
+10. **Optional injected locks.** When optional `lockProvider` is set, the job holds
+    `repo:<repoId>:<refId>:index` (architecture.md §21.1). Validated `lockLeaseMs` defaults to
+    30 seconds; the runner renews without overlap no later than one third of its duration.
+    Renewal failure aborts the internal pipeline as `LOCK_HELD`. A final renewal proves ownership
+    again before the terminal observer; a runner detecting ownership loss does not invoke it.
+    Adapter-owned current pointers additionally need serialization per repository/ref, ownership
+    checks immediately before publication and generation-CAS replacement. Stale detection and the
+    owner-checked renewal operation itself belong to the provider.
+11. **Unbounded event channel.** Job events are small and finite per batch; bounded WORK queues,
+    rather than the event stream, limit pipeline memory pressure. Slow event consumption therefore
+    does not delay the job.
+12. **Corpus revision from the complete scan, not the changed subset.** Discovery returns the
+    complete mapping of file IDs to content hashes. Only after successful generation commit does
+    the runner hash this canonical manifest and pass its immutable `corpusRevisionFingerprint`
+    to `onGenerationFinished`. This also applies to incremental runs with zero changed files.
+    Failed or cancelled runs publish no corpus revision; reused generations therefore cannot merge
+    different corpus snapshots in downstream Search Journeys.
+
+## Tests
+
+Co-located `src/**/*.test.ts`, using only `@untangle-code/testkit` (FakeClock, DeterministicRandom,
+MemoryFileSystem, InMemoryLockProvider), with no network or Docker. Coverage includes the complete
+transition relation (all 15×15 pairs), demonstrated backpressure (a blocked storage stage limits
+analysis to queue capacity plus in-flight work), cancellation producing valid checkpoints and
+`cancelled`, exact checkpoint resume without repeating acknowledged work, incomplete generations
+never reaching `completed`, successful zero-change runs producing corpus revisions from complete
+manifests, and fault injection from architecture.md §27.5 at points 1 (after embedding/before
+upsert), 3 (after upsert/before checkpoint) and 5 (after checkpoint/before generation commit), with
+post-restart consistency evidence.
+
+<a id="lizenz"></a>
+
+## License
+
+**AGPL-3.0-only.** This package includes the complete license in [`LICENSE`](./LICENSE), the
+license-choice rationale in [`NOTICE`](./NOTICE), and licenses for all third-party production
+dependencies in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md). All three ship in the npm
+tarball: AGPL-3.0-only §4 and §5 require recipients to receive the license; a README alone is not
+a copy of the license.
+
+Local use alone does not trigger an obligation. Copyleft obligations apply to redistribution and
+providing a network service (AGPL §13).
+
+Corresponding TypeScript source ships under `src/` in the same tarball; the complete repository
+is available at <https://github.com/lboel/untangle>.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,24 @@
+# Third-party licenses — @untangle-code/jobs
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Result: no third-party dependencies
+
+This package has no production dependencies outside the workspace.
+The list is empty because none exist, not because they were not checked.

package/dist/abort.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Throws `UntangleError("JOB_CANCELLED", …)` when `signal` is already
+ * aborted. Called at every safe batch boundary (architecture.md §21.3).
+ */
+export declare function throwIfAborted(signal: AbortSignal | undefined, operation: string): void;
+/** True when `error` is an `UntangleError` with code `JOB_CANCELLED`. */
+export declare function isJobCancelledError(error: unknown): boolean;
+/**
+ * Resolves when `signal` aborts. The listener is removed as soon as
+ * `cleanup` aborts, so racing this against another promise does not leak
+ * one listener per wait.
+ */
+export declare function abortedPromise(signal: AbortSignal, cleanup: AbortSignal): Promise<void>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAIvF;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}

package/dist/abort.js

@@ -0,0 +1,35 @@
+/**
+ * AbortSignal helpers shared by every long-running method in this package
+ * (spec.md §22: public APIs MUST support abort signals; cancellation
+ * surfaces as `UntangleError` with code `JOB_CANCELLED`).
+ */
+import { isUntangleError } from "@untangle-code/domain";
+import { jobCancelledError } from "@untangle-code/observability";
+/**
+ * Throws `UntangleError("JOB_CANCELLED", …)` when `signal` is already
+ * aborted. Called at every safe batch boundary (architecture.md §21.3).
+ */
+export function throwIfAborted(signal, operation) {
+    if (signal?.aborted) {
+        throw jobCancelledError(`"${operation}" was aborted`, { operation });
+    }
+}
+/** True when `error` is an `UntangleError` with code `JOB_CANCELLED`. */
+export function isJobCancelledError(error) {
+    return isUntangleError(error) && error.code === "JOB_CANCELLED";
+}
+/**
+ * Resolves when `signal` aborts. The listener is removed as soon as
+ * `cleanup` aborts, so racing this against another promise does not leak
+ * one listener per wait.
+ */
+export function abortedPromise(signal, cleanup) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        signal.addEventListener("abort", () => resolve(), { once: true, signal: cleanup });
+    });
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAA+B,EAAE,SAAiB;IAC/E,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,iBAAiB,CAAC,IAAI,SAAS,eAAe,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,OAAoB;IACtE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bounded-queue.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Bounded FIFO queue with backpressure (architecture.md §13.1–§13.2).
+ *
+ * A full queue makes `push()` WAIT — that is the mechanism by which a slow
+ * downstream stage pauses the previous stage instead of letting it
+ * accumulate unbounded ASTs/vectors in memory. Bounds are enforced on both
+ * item count (`capacity`) and, optionally, estimated bytes (`maxBytes` with
+ * a `sizeOf` cost function), so the pipeline's memory budget is a hard
+ * limit, not a hope. All observed values are exposed via `stats()` for the
+ * job status output (spec-driven visibility, architecture.md §13.2).
+ *
+ * Die EINZIGE Ausnahme vom Byte-Budget ist ein Element, das das ganze Budget
+ * allein uebersteigt: fuer so ein Element kann Warten nie Platz schaffen, es
+ * wuerde die Queue also nicht bremsen, sondern haengen lassen. Diese Ausnahme
+ * ist eng gefasst (leere Queue, kontingentiert, gezaehlt, gemeldet) — sie war
+ * frueher an den Fuellstand geknuepft und damit bei `capacity: 1` ein
+ * Dauerzustand, der die Byte-Grenze mit gueltigen Werten abschaltete (WP-116).
+ */
+import type { PortCallOptions } from "@untangle-code/domain";
+/**
+ * Eine Aufnahme, die das Byte-Budget verletzt hat, weil das Element ALLEIN
+ * groesser als das gesamte Budget ist. Wird gezaehlt und gemeldet — eine
+ * Budgetverletzung darf nie stillschweigend passieren (E4).
+ */
+export interface OverBudgetAdmissionV1 {
+    /** Groesse des aufgenommenen Elements in Bytes (> `maxBytes`). */
+    itemBytes: number;
+    /** Das Budget, das dieses Element allein ueberschreitet. */
+    maxBytes: number;
+    /** Die wievielte Ausnahme dieser Queue (1-basiert). */
+    ordinal: number;
+    /** Wie viele solcher Ausnahmen diese Queue insgesamt zulaesst. */
+    allowance: number;
+}
+export interface BoundedQueueOptions<T> {
+    /** Maximum number of buffered items; must be a safe integer >= 1. */
+    capacity: number;
+    /** Optional byte budget across all buffered items. Requires `sizeOf`. */
+    maxBytes?: number;
+    /** Estimated size of one item in bytes; required when `maxBytes` is set. */
+    sizeOf?: (item: T) => number;
+    /**
+     * Wie viele Elemente, die das Byte-Budget ALLEIN uebersteigen, darf diese
+     * Queue insgesamt aufnehmen? Vorgabe: 1.
+     *
+     * Die Ausnahme existiert nur, damit EIN einzelnes uebergrosses Element die
+     * Queue nicht dauerhaft blockiert (warten kann fuer so ein Element nie
+     * Platz schaffen). Sie ist ausdruecklich kein Dauerzustand: ist das
+     * Kontingent erschoepft, scheitert `push()` mit einem benannten Fehler,
+     * statt das Budget weiter stillschweigend zu ueberschreiten. `0` lehnt
+     * schon das erste uebergrosse Element ab.
+     */
+    maxOverBudgetAdmissions?: number;
+    /**
+     * Wird bei JEDER Ausnahme gerufen — der vorgesehene Weg, die
+     * Budgetverletzung in Log, Diagnostics oder Skip-Ledger sichtbar zu
+     * machen. Wirft der Rueckruf, scheitert der `push()`.
+     */
+    onOverBudgetAdmission?: (admission: OverBudgetAdmissionV1) => void;
+}
+/** Snapshot of one queue for status output and tests. */
+export interface QueueStatsV1 {
+    depth: number;
+    capacity: number;
+    bytes: number;
+    maxBytes: number | null;
+    /** High-water marks since construction — prove boundedness in tests. */
+    maxDepthObserved: number;
+    maxBytesObserved: number;
+    /**
+     * Anzahl der Elemente, die trotz Budgetueberschreitung aufgenommen wurden,
+     * weil sie allein groesser als das gesamte Budget sind. `> 0` ist die
+     * Erklaerung dafuer, dass `maxBytesObserved > maxBytes` sein kann — ohne
+     * diesen Zaehler waere die Budgetverletzung unsichtbar (E4).
+     */
+    overBudgetAdmissions: number;
+    /** Wie viele solcher Ausnahmen diese Queue insgesamt zulaesst. */
+    overBudgetAllowance: number;
+    /** Groesstes je aufgenommenes Einzelelement in Bytes. */
+    maxItemBytesObserved: number;
+}
+export type QueuePullResult<T> = {
+    done: true;
+} | {
+    done: false;
+    value: T;
+};
+export declare class BoundedQueue<T> {
+    private readonly slots;
+    private readonly capacity;
+    private readonly maxBytes;
+    private readonly sizeOf;
+    private readonly overBudgetAllowance;
+    private readonly onOverBudgetAdmission;
+    private overBudgetAdmissions;
+    private maxItemBytesObserved;
+    private bytes;
+    private closed;
+    private failure;
+    private wakers;
+    private maxDepthObserved;
+    private maxBytesObserved;
+    constructor(options: BoundedQueueOptions<T>);
+    /**
+     * 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.
+     */
+    private static validateSize;
+    /**
+     * 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).
+     */
+    private assertByteCounterIntact;
+    private notify;
+    private waitForChange;
+    /**
+     * 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.
+     */
+    private admissionVerdict;
+    /**
+     * 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.
+     */
+    private assertEmptyStateCounter;
+    /**
+     * 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.
+     */
+    private admitOverBudget;
+    /**
+     * 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()`.
+     */
+    push(item: T, options?: PortCallOptions): Promise<void>;
+    /**
+     * 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).
+     */
+    pull(options?: PortCallOptions): Promise<QueuePullResult<T>>;
+    /** Non-blocking pull: `null` when nothing is buffered right now. */
+    tryPull(): QueuePullResult<T> | null;
+    /** No more pushes; pulls drain the remaining items, then report done. */
+    close(): void;
+    /**
+     * Poisons the queue: every pending and future `push`/`pull` rejects with
+     * `error`. Used to unblock sibling pipeline workers when one stage fails.
+     */
+    fail(error: unknown): void;
+    stats(): QueueStatsV1;
+}
+//# sourceMappingURL=bounded-queue.d.ts.map

package/dist/bounded-queue.d.ts.map

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