knitting 0.1.70 → 0.1.73

package/knitting.d.ts

@@ -1,7 +1,9 @@
 import { workerMainLoop } from "./src/worker/loop.js";
 import { checkCompiledWorker, createPool, importTask, isMain, setModuleUrl, task } from "./src/api.js";
 import { Envelope } from "./src/common/envelope.js";
+import { KnittingError } from "./src/error.js";
 import { isNumericArray, NumericArray } from "./src/connections/numeric-array.js";
-export { checkCompiledWorker as checkCompiledWorker, createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, isNumericArray as isNumericArray, NumericArray as NumericArray, setModuleUrl as setModuleUrl, task as task, workerMainLoop as workerMainLoop, };
+export { checkCompiledWorker as checkCompiledWorker, createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, isNumericArray as isNumericArray, KnittingError as KnittingError, NumericArray as NumericArray, setModuleUrl as setModuleUrl, task as task, workerMainLoop as workerMainLoop, };
 export type { EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, } from "./src/common/envelope.js";
+export type { KnittingErrorCode } from "./src/error.js";
 export type { CompiledWorkerCheck, CompiledWorkerOptions, CompiledWorkerSource, } from "./src/types.js";

package/knitting.js

@@ -2,5 +2,6 @@
 import { workerMainLoop } from "./src/worker/loop.js";
 import { checkCompiledWorker, createPool, importTask, isMain, setModuleUrl, task, } from "./src/api.js";
 import { Envelope } from "./src/common/envelope.js";
+import { KnittingError } from "./src/error.js";
 import { isNumericArray, NumericArray, } from "./src/connections/numeric-array.js";
-export { checkCompiledWorker as checkCompiledWorker, createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, isNumericArray as isNumericArray, NumericArray as NumericArray, setModuleUrl as setModuleUrl, task as task, workerMainLoop as workerMainLoop, };
+export { checkCompiledWorker as checkCompiledWorker, createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, isNumericArray as isNumericArray, KnittingError as KnittingError, NumericArray as NumericArray, setModuleUrl as setModuleUrl, task as task, workerMainLoop as workerMainLoop, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.70",
+  "version": "0.1.73",
   "description": "Shared-memory IPC runtime for Node.js, Deno, and Bun.",
   "license": "Apache-2.0",
   "repository": {
@@ -83,7 +83,7 @@
     "release:npm": "npm run test:all && npm publish",
     "release:npm:dry-run": "npm publish --dry-run",
     "test": "npm run test:deno",
-    "test:deno": "deno test -A --ignore=test/runtime.node.test.ts --ignore=test/runtime.process.test.ts",
+    "test:deno": "deno test -A --ignore=test/runtime.node.test.ts --ignore=test/runtime.process.test.ts test",
     "test:node": "node --no-warnings --experimental-transform-types --test \"./test/*.test.ts\"",
     "test:node:26": "node --no-warnings --experimental-ffi test/node26-ffi.integration.mjs",
     "test:bun": "bun test",
@@ -102,7 +102,12 @@
     "bun": ">=1.0.0"
   },
   "peerDependencies": {
-    "typescript": "^5.2.0"
+    "typescript": ">=5.2.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.js

@@ -4,6 +4,7 @@ import { genTaskID, stableTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
 import { endpointSymbol } from "./common/task-symbol.js";
 import { createStealPoolBuffers, MAX_STEAL_CONSUMERS, spawnWorkerContext, } from "./runtime/pool.js";
+import { isNodePermissionExecFlag } from "./runtime/worker-common.js";
 import { ChannelHandler, hostDispatcherLoop } from "./runtime/dispatcher.js";
 import { createDenoCompletionDoorbell } from "./runtime/deno-doorbell.js";
 import { createSharedArrayBuffer, RUNTIME } from "./common/runtime.js";
@@ -11,17 +12,20 @@ import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from
 import { classifyProcessPermissionCompatibility, enforceProcessPermissionCompatibility, resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
 import { readProcessSharedMemorySettings, readProcessWorkerNodeMajor, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { assertStealClaim, DEFAULT_STEAL_CLAIM, } from "./memory/lock.js";
 import { TRANSPORT_SIGNAL_BYTES } from "./ipc/transport/shared-memory.js";
 import { inspectCompiledWorkerArtifact } from "./runtime/compiled-artifact.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
 import { createHostArgAllocator } from "./runtime/host-arg-arena.js";
 const hasDebugNamespace = (namespaces, namespace) => namespaces.has("*") || namespaces.has(namespace);
-const createHostDebug = (namespaces) => {
+const createHostDebug = (namespaces, epoch) => {
     const enabled = (namespace) => hasDebugNamespace(namespaces, namespace);
     if (!enabled("host"))
         return undefined;
-    const base = performance.now();
+    // Same rebase the workers do (see debug/handle.ts), so host and worker lines
+    // share one zero.
+    const base = epoch - performance.timeOrigin;
     const tag = `host·${RUNTIME}`;
     const log = (message) => {
         const elapsed = (performance.now() - base).toFixed(1);
@@ -250,8 +254,14 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         (debug !== undefined && debug !== false);
     let debugNamespaces;
     const getDebugNamespaces = () => debugNamespaces ??= resolveDebugNamespaces(debug);
-    const hostDebug = debugRequested
-        ? createHostDebug(getDebugNamespaces())
+    // Absolute (Unix-epoch ms) zero for every debug clock in this pool. Raw
+    // `performance.now()` is relative to each thread/process's own time origin;
+    // `timeOrigin + now()` is not, so workers can rebase onto this value.
+    const debugEpoch = debugRequested
+        ? performance.timeOrigin + performance.now()
+        : undefined;
+    const hostDebug = debugEpoch !== undefined
+        ? createHostDebug(getDebugNamespaces(), debugEpoch)
         : undefined;
     const debugEnabled = (namespace) => debugRequested && hasDebugNamespace(getDebugNamespaces(), namespace);
     /**
@@ -278,6 +288,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         return {
             shutdown: mainThreadOnlyProxy,
             [Symbol.dispose]: () => { },
+            [Symbol.asyncDispose]: async () => { },
             call: mainThreadOnlyProxy,
         };
     }
@@ -306,20 +317,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     const permissionExecArgv = toRuntimePermissionFlags(permissionProtocol);
     const nodeProcess = getNodeProcess();
     const allowedFlags = nodeProcess?.allowedNodeEnvironmentFlags ?? null;
-    const isNodePermissionFlag = (flag) => {
-        const key = flag.split("=", 1)[0];
-        return key === "--permission" ||
-            key === "--experimental-permission" ||
-            key === "--allow-fs-read" ||
-            key === "--allow-fs-write" ||
-            key === "--allow-worker" ||
-            key === "--allow-child-process" ||
-            key === "--allow-net" ||
-            key === "--allow-addons" ||
-            key === "--allow-ffi" ||
-            key === "--allow-wasi";
-    };
-    const stripNodePermissionFlags = (flags) => flags?.filter((flag) => !isNodePermissionFlag(flag));
+    const stripNodePermissionFlags = (flags) => flags?.filter((flag) => !isNodePermissionExecFlag(flag));
     const dedupeFlags = (flags) => {
         const out = [];
         const seen = new Set();
@@ -346,16 +344,11 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         ? nodeProcess.execArgv
         : undefined;
     const defaultExecArgvCandidate = workerExecArgv ??
-        (inheritedExecArgv
-            ? (allowedFlags?.has("--expose-gc") === true
-                ? (inheritedExecArgv.includes("--expose-gc")
-                    ? inheritedExecArgv
-                    : [...inheritedExecArgv, "--expose-gc"])
-                : inheritedExecArgv)
-            : undefined);
-    const defaultExecArgv = permissionProtocol?.unsafe === true
-        ? stripNodePermissionFlags(defaultExecArgvCandidate)
-        : defaultExecArgvCandidate;
+        inheritedExecArgv;
+    // Knitting resolves the worker's permission policy itself. Do not inherit
+    // the host's Node grants (or caller-supplied permission flags), which could
+    // broaden that policy when Node combines repeated --allow-* options.
+    const defaultExecArgv = stripNodePermissionFlags(defaultExecArgvCandidate);
     const combinedExecArgv = dedupeFlags([
         ...permissionExecArgv,
         ...(defaultExecArgv ?? []),
@@ -367,6 +360,16 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     hostDebug?.log(`permission=${permissionProtocol?.mode ?? "off"} execArgv=${formatDebugList(execArgv)}`);
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
     const resolvedWorker = resolveWorkerSettings(worker, callerHref);
+    if (RUNTIME === "node" &&
+        resolvedWorker?.runtime !== "process" &&
+        resolvedWorker?.runtime !== "compiled") {
+        const missingPermissionFlags = permissionExecArgv.filter((flag) => isNodePermissionExecFlag(flag) && !execArgv?.includes(flag));
+        if (missingPermissionFlags.length > 0) {
+            throw new Error("Node cannot apply the resolved permission policy to this thread " +
+                `worker (unsupported flags: ${missingPermissionFlags.join(", ")}). ` +
+                "Refusing to start the worker without those permissions.");
+        }
+    }
     const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
     const stealEnvRaw = nodeProcess?.env?.KNITTING_STEAL?.trim().toLowerCase();
     const stealEnv = stealEnvRaw === "1" || stealEnvRaw === "true"
@@ -383,12 +386,15 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     const stealRequested = host?.steal ?? stealEnv ?? stealDefaultCompatible;
     const stealClaimEnvRaw = nodeProcess?.env?.KNITTING_STEAL_CLAIM?.trim()
         .toLowerCase();
-    const stealClaimEnv = stealClaimEnvRaw === "cas-mask" ||
-        stealClaimEnvRaw === "dekker"
-        ? stealClaimEnvRaw
-        : undefined;
+    // An unrecognised discipline is an error, not a fallback: `cas-mask` and
+    // typos used to select Dekker silently and run under the wrong name.
+    const stealClaimEnv = stealClaimEnvRaw === undefined || stealClaimEnvRaw === ""
+        ? undefined
+        : assertStealClaim(stealClaimEnvRaw, "KNITTING_STEAL_CLAIM");
     // Select the stealing claim discipline, preferring the explicit option.
-    const stealClaim = host?.stealClaim ?? stealClaimEnv ?? "dekker";
+    const stealClaim = host?.stealClaim === undefined
+        ? stealClaimEnv ?? DEFAULT_STEAL_CLAIM
+        : assertStealClaim(host.stealClaim, "host.stealClaim");
     const usingCompiledWorker = resolvedWorker?.runtime === "compiled";
     if (resolvedWorker?.compiled !== undefined && !usingCompiledWorker) {
         throw new Error("worker.compiled requires worker.runtime to be compiled");
@@ -526,6 +532,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         at,
         thread,
         debug,
+        debugEpoch,
         hostDebug: hostDebug?.log,
         totalNumberOfThread,
         // Worker count without the inline lane. The inliner runs on the host
@@ -534,6 +541,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         source,
         workerOptions: resolvedWorker,
         workerExecArgv: execArgv,
+        requestedExecArgv: workerExecArgv,
         host,
         payload,
         sharedBytesEnabled,
@@ -564,14 +572,27 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         // Round-robin wake keeps stealing at one notify per publish; any idle worker
         // can claim the region.
         let wakeCursor = 0;
+        let lastWoken = 0;
         const wakeOne = () => {
             const lanes = workers.length;
             if (lanes === 0)
                 return;
-            const lane = wakeCursor;
+            const lane = lastWoken = wakeCursor;
             wakeCursor = wakeCursor + 1 < lanes ? wakeCursor + 1 : 0;
             workers[lane].laneWake?.();
         };
+        // Any awake worker will claim what was just published, so a lost wake
+        // only strands work when every worker is parked. Ring the lane this pass
+        // already rang: one still waking up absorbs it, and a second lane would
+        // be one more thread woken per call.
+        const wakeIfAllParked = () => {
+            for (let lane = 0; lane < workers.length; lane++) {
+                const context = workers[lane];
+                if (context.laneAwake?.() !== false)
+                    return;
+            }
+            workers[lastWoken]?.laneWake?.();
+        };
         // The shared dispatcher drives one queue, so it needs signal words of its
         // own rather than any single lane's; waking is delegated to `wakeOne`.
         const signalWords = new Int32Array(createSharedArrayBuffer(3 * Int32Array.BYTES_PER_ELEMENT));
@@ -585,6 +606,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             channelHandler: channel,
             dispatcherOptions: host,
             notifySignal: wakeOne,
+            wakeAfterPass: wakeIfAllParked,
             crossProcess: resolvedWorker?.runtime === "process",
             nativeCompletionDoorbell: denoCompletionDoorbell !== undefined ||
                 workers.some((context) => context
@@ -896,6 +918,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     return {
         shutdown: shutdownWithDelay,
         [Symbol.dispose]: disposePool,
+        [Symbol.asyncDispose]: () => shutdownWithDelay(),
         call: Object.fromEntries(callEntries),
         // Only the shared submit queue has a single arena to build arguments in.
         sharedArgBytes: createHostArgAllocator(sharedArgsEnabled ? stealBuffers?.submitBuffers.payload : undefined),
@@ -910,6 +933,7 @@ const createSingleTaskPool = (single, options) => {
         call: pool.call[SINGLE_TASK_KEY],
         shutdown: pool.shutdown,
         [Symbol.dispose]: pool[Symbol.dispose],
+        [Symbol.asyncDispose]: pool[Symbol.asyncDispose],
     };
 };
 const buildTaskDefinitionFromCaller = (input, callerHref, at, imported = false) => {

package/src/connections/node-addons.js

@@ -34,6 +34,14 @@ export const formatNodeNativeAddonLoadError = (name, platformInfo, errors) => {
         ? "an unknown version"
         : `v${platformInfo.version}`;
     const target = `${platformInfo.platform}-${platformInfo.arch}`;
+    if (errors.some((error) => error.includes("ERR_DLOPEN_DISABLED"))) {
+        return (`knitting: Node.js ${version} blocked loading native addon ${name} ` +
+            `because --allow-addons is not enabled. For a thread worker pool, ` +
+            `set permission.node.allowAddons to true; if the host itself runs ` +
+            `with --permission, start it with --allow-addons too. This permits ` +
+            `task code to load Node native addons; only enable it for trusted ` +
+            `tasks.${attempts}`);
+    }
     if (abi === NODE_26_MODULE_ABI) {
         return (`knitting: Node.js 26 uses node:ffi instead of ABI-specific addons. ` +
             `Restart Node with the --experimental-ffi flag` +
@@ -85,7 +93,9 @@ export const loadNodeNativeAddon = (require, name, specifier) => {
             return require(candidate);
         }
         catch (error) {
-            errors.push(`${candidate}: ${String(error)}`);
+            const code = error?.code;
+            errors.push(`${candidate}: ${typeof code === "string" ? `${code}: ` : ""}` +
+                String(error));
         }
     }
     throw new Error(formatNodeNativeAddonLoadError(name, readNodePlatformInfo(), errors));

package/src/debug/gate.js

@@ -4,7 +4,7 @@
  * Read once at module load from `KNITTING_DEBUG`. This module is deliberately
  * tiny and dependency-light: importing it must never pull in the logger or the
  * environment-diff machinery. Callers branch on {@link DEBUG_ENABLED} and only
- * then `await import("./handle.ts")`, so when debug is off nothing else under
+ * then `await import("./handle.js")`, so when debug is off nothing else under
  * `src/debug` is ever loaded — literally zero cost, not merely cheap.
  *
  * `KNITTING_DEBUG` is a comma-separated list of namespaces:

package/src/debug/handle.d.ts

@@ -3,6 +3,11 @@ export type DebugInit = {
     readonly name: string;
     readonly runtime: string;
     readonly namespaces: ReadonlySet<string>;
+    /**
+     * Host debug epoch as `timeOrigin + now()`. When absent (debug enabled only
+     * inside the worker), the clock starts when this handle initialises.
+     */
+    readonly epoch?: number;
 };
 export type Debug = {
     /**
@@ -20,4 +25,4 @@ export type Debug = {
      */
     envPhase: (label: string) => void;
 };
-export declare const initDebug: ({ name, runtime, namespaces }: DebugInit) => Debug;
+export declare const initDebug: ({ name, runtime, namespaces, epoch }: DebugInit) => Debug;

package/src/debug/handle.js

@@ -4,16 +4,24 @@
  * baseline snapshot it takes exists when debug is off.
  *
  * Diagnostics go to stderr so they never corrupt a worker's stdout, and every
- * line is tagged with the worker id, runtime, and a clock relative to when this
- * worker's debug initialised. The clock is worker-local on purpose: a main-thread
- * timestamp can't be compared against `performance.now()` here because the time
- * origins differ across the thread/process boundary (it would read negative).
+ * line is tagged with the worker id, runtime, and a clock in milliseconds since
+ * the host's debug epoch, so host and worker lines interleave on one timeline.
+ *
+ * Raw `performance.now()` can't be compared across the thread/process boundary:
+ * bun and deno give each worker its own time origin, and a process worker's
+ * origin is its own process start. `performance.timeOrigin + performance.now()`
+ * is comparable (measured within a few µs on bun, node and deno, for both
+ * threads and processes), so the host sends that absolute value and each worker
+ * rebases onto it once. Staying in the local `now()` frame afterwards keeps
+ * full precision; the absolute sum alone only resolves ~0.24µs.
  */
 import { describeGlobalKey, diffGlobals, snapshotGlobals, } from "./env-diff.js";
-export const initDebug = ({ name, runtime, namespaces }) => {
+export const initDebug = ({ name, runtime, namespaces, epoch }) => {
     const all = namespaces.has("*");
     const enabled = (namespace) => all || namespaces.has(namespace);
-    const base = performance.now();
+    const base = epoch === undefined
+        ? performance.now()
+        : epoch - performance.timeOrigin;
     const tag = `${name}·${runtime}`;
     const log = (namespace, message) => {
         if (!enabled(namespace))

package/src/error.d.ts

@@ -6,6 +6,15 @@ export declare const ErrorKnitting: {
     readonly Serializable: 3;
 };
 export type ErrorKnitting = typeof ErrorKnitting[keyof typeof ErrorKnitting];
+export type KnittingErrorCode = "KNT_ERROR_0" | "KNT_ERROR_1" | "KNT_ERROR_2" | "KNT_ERROR_3" | "THREAD_CLOSED" | "WORKER_CRASHED" | "WORKER_EXITED" | "WORKER_STARTUP_FAILED";
+/**
+ * Rejection raised by Knitting itself rather than by task code. Branch on
+ * `code`; `message` keeps the human-readable text.
+ */
+export declare class KnittingError extends Error {
+    readonly code: KnittingErrorCode;
+    constructor(code: KnittingErrorCode, message: string, cause?: unknown);
+}
 export declare const encoderError: ({ task, type, onPromise, detail, }: {
     task: Task;
     type: ErrorKnitting;

package/src/error.js

@@ -8,6 +8,18 @@ export const ErrorKnitting = {
     Json: 2,
     Serializable: 3,
 };
+/**
+ * Rejection raised by Knitting itself rather than by task code. Branch on
+ * `code`; `message` keeps the human-readable text.
+ */
+export class KnittingError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "KnittingError";
+        this.code = code;
+    }
+}
 const reasonFrom = (task, type, detail) => {
     switch (type) {
         case ErrorKnitting.Function: {
@@ -41,10 +53,12 @@ export const encoderError = ({ task, type, onPromise, detail, }) => {
     }
     if (!beginPromisePayload(task))
         return false;
+    // Built here, not in the microtask, so the stack still names the caller.
+    const error = new KnittingError(`KNT_ERROR_${type}`, reason);
     queueMicrotask(() => {
         finishPromisePayload(task);
-        task.value = reason;
-        onPromise(task, true, reason);
+        task.value = error;
+        onPromise(task, true, error);
     });
     return false;
 };

package/src/memory/lock.d.ts

@@ -181,8 +181,26 @@ export declare const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32: number;
 export declare const STEAL_LIVE_SLOT_OFFSET_U32: number;
 /** Host-owned arm word for the return-lock completion doorbell. */
 export declare const DOORBELL_ARMED_SLOT_OFFSET_U32: number;
-/** Shared region-owner mask for the `cas-mask` claim discipline. */
-export declare const STEAL_CLAIM_MASK_SLOT_OFFSET_U32: number;
+/**
+ * Non-wrapping 64-bit claim head for the `ticket` discipline. The producer
+ * publishes only the low 32 bits of the tail. A successful head CAS validates
+ * the snapshot: with that head unchanged, at most 32 tickets can be pending,
+ * so unsigned subtraction recovers the exact distance even across tail wrap.
+ * Head and tail occupy different slots' header lines (slots 0 and 1).
+ */
+export declare const STEAL_TICKET_HEAD_SLOT_OFFSET_U32: number;
+/** Negative head permanently closes a failed ticket queue. */
+export declare const STEAL_TICKET_FAILED = -1n;
+/**
+ * Publication-order ring. `order[t & 31]` is the slot the producer filled for
+ * ticket `t`, so a ticket names a lane without the ticket having to *be* the
+ * lane: the producer keeps its free-bit allocation and claims follow publication
+ * order. Cell `i` uses the former ACK word; words 14..15
+ * are reserved for the head in slot 0 and the tail in slot 1.
+ */
+export declare const STEAL_TICKET_ORDER_SLOT_OFFSET_U32: number;
+/** Ring cells, and therefore the wrap mask, follow the slot count. */
+export declare const STEAL_TICKET_RING_MASK: number;
 export declare const HEADER_U32_LENGTH: number;
 export declare const HEADER_BYTE_LENGTH: number;
 export declare const makeTask: () => Task;
@@ -194,18 +212,37 @@ type ResolveHostOptions = {
 };
 export type Lock2 = ReturnType<typeof lock2>;
 /**
- * Region mutual-exclusion discipline for stealing consumers.
+ * Claim discipline for stealing consumers.
  *
  * - `dekker`: per-consumer intent words and an O(N) peer survey.
- * - `cas-mask`: one shared owner mask for all regions.
+ * - `ticket`: one monotonic counter; a CAS on the head claims lanes in
+ *   publication order, with no regions and no per-consumer state.
  */
-export type StealClaimDiscipline = "dekker" | "cas-mask";
+export declare const STEAL_CLAIM_DISCIPLINES: readonly ["dekker", "ticket"];
+export type StealClaimDiscipline = typeof STEAL_CLAIM_DISCIPLINES[number];
+/**
+ * Validate a claim discipline coming from an untrusted source — an env var, or
+ * a JS caller the type system never saw.
+ *
+ * This throws rather than falling back, because a silent fallback is worse than
+ * a crash here: a stale `cas-mask` setting or a typo would quietly run Dekker,
+ * and every benchmark and test built on it would report Dekker's numbers under
+ * another name. Both sides of a lock must also agree, so an unrecognised value
+ * that resolved differently on host and worker would corrupt the protocol.
+ */
+export declare const assertStealClaim: (value: unknown, source: string) => StealClaimDiscipline;
+/**
+ * The discipline chosen when nothing selects one. Host and worker default
+ * independently, so this must be a single shared constant: two sides landing on
+ * different disciplines would read the same buffer under different protocols.
+ */
+export declare const DEFAULT_STEAL_CLAIM: StealClaimDiscipline;
 export type WaitAsyncState = "not-equal" | "ok" | "timed-out";
 export type WaitAsyncResult = {
     async: boolean;
     value: WaitAsyncState | PromiseLike<WaitAsyncState>;
 };
-export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, sharedReturn, moveReturn, consumers, consumerId, regionLanes, stealClaim, notifyOnHostPublish, notifyHostPublish, }: {
+export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, sharedReturn, moveReturn, consumers, consumerId, regionLanes, stealClaim, notifyOnHostPublish, notifyHostPublish, traceClaim, }: {
     headers?: SharedBufferSource;
     headerSlotStrideU32?: number;
     LockBoundSector?: SharedBufferSource;
@@ -244,6 +281,11 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     notifyOnHostPublish?: boolean;
     /** Runtime-native host wake used when Atomics.waitAsync cannot wake it. */
     notifyHostPublish?: () => void;
+    /**
+     * Debug sink for steal claims. Only consulted when `decode` is chosen, so an
+     * untraced lock returns the bare claim function; see {@link traceStealClaims}.
+     */
+    traceClaim?: (message: string) => void;
 }) => {
     enlist: (task: Task) => true;
     encode: (task: Task, state?: number) => boolean;