@plurnk/plurnk-service 1.3.12 → 1.4.0

package/dist/core/turn-scheduler.d.ts

@@ -1,3 +1,3 @@
-import type { PlurnkStatement } from "@plurnk/plurnk-grammar";
+import type { PlurnkStatement } from "@plurnk/plurnk-contracts";
 export declare const scheduleTurnOps: (statements: readonly PlurnkStatement[]) => PlurnkStatement[];
 //# sourceMappingURL=turn-scheduler.d.ts.map

package/dist/core/turn-scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-scheduler.d.ts","sourceRoot":"","sources":["../../src/core/turn-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAe9D,eAAO,MAAM,eAAe,eAAgB,SAAS,eAAe,EAAE,KAAG,eAAe,EAI9C,CAAC"}
+{"version":3,"file":"turn-scheduler.d.ts","sourceRoot":"","sources":["../../src/core/turn-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAehE,eAAO,MAAM,eAAe,eAAgB,SAAS,eAAe,EAAE,KAAG,eAAe,EAI9C,CAAC"}

package/dist/core/turn-scheduler.js

@@ -11,7 +11,7 @@ const phaseOf = (statement) => {
         return 4;
     return 3;
 };
-// §op-mode-phases — Array#sort is stable, so authored order survives inside
+// {§op-mode-phases} — Array#sort is stable, so authored order survives inside
 // each phase while observations move behind the turn's settled mutations.
 export const scheduleTurnOps = (statements) => statements
     .map((statement, authoredIndex) => ({ statement, authoredIndex, phase: phaseOf(statement) }))

package/dist/core/turn-scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"turn-scheduler.js","sourceRoot":"","sources":["../../src/core/turn-scheduler.ts"],"names":[],"mappings":"AAEA,MAAM,SAAS,GAAG,IAAI,GAAG,CAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3F,MAAM,YAAY,GAAG,IAAI,GAAG,CAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9E,MAAM,OAAO,GAAG,CAAC,SAA0B,EAAU,EAAE;IACnD,IAAI,SAAS,CAAC,EAAE,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IACtC,IAAI,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1C,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,SAAS,CAAC,EAAE,KAAK,MAAM,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IACzG,OAAO,CAAC,CAAC;AACb,CAAC,CAAC;AAEF,4EAA4E;AAC5E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAsC,EAAqB,EAAE,CACzF,UAAU;KACL,GAAG,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;KAC5F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;KACtE,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"turn-scheduler.js","sourceRoot":"","sources":["../../src/core/turn-scheduler.ts"],"names":[],"mappings":"AAEA,MAAM,SAAS,GAAG,IAAI,GAAG,CAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3F,MAAM,YAAY,GAAG,IAAI,GAAG,CAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9E,MAAM,OAAO,GAAG,CAAC,SAA0B,EAAU,EAAE;IACnD,IAAI,SAAS,CAAC,EAAE,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IACtC,IAAI,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1C,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,SAAS,CAAC,EAAE,KAAK,MAAM,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IACzG,OAAO,CAAC,CAAC;AACb,CAAC,CAAC;AAEF,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAsC,EAAqB,EAAE,CACzF,UAAU;KACL,GAAG,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;KAC5F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;KACtE,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC"}

package/dist/core/worker-cap.d.ts

@@ -1,8 +1,6 @@
 import type { Db } from "./Db.ts";
+import type { SchemeResult } from "@plurnk/plurnk-schemes";
 export default class WorkerCap {
-    static deny(db: Db, workspaceId: number): Promise<{
-        status: number;
-        error: string;
-    } | null>;
+    static deny(db: Db, workspaceId: number): Promise<SchemeResult | null>;
 }
 //# sourceMappingURL=worker-cap.d.ts.map

package/dist/core/worker-cap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-cap.d.ts","sourceRoot":"","sources":["../../src/core/worker-cap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AASlC,MAAM,CAAC,OAAO,OAAO,SAAS;IAC1B,OAAa,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAOhG;CACJ"}
+{"version":3,"file":"worker-cap.d.ts","sourceRoot":"","sources":["../../src/core/worker-cap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAU3D,MAAM,CAAC,OAAO,OAAO,SAAS;IAC1B,OAAa,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAuB3E;CACJ"}

package/dist/core/worker-cap.js

@@ -1,10 +1,11 @@
+import Results from "./results.js";
 // Workspace-tier ceiling on CONCURRENT active workers (a worker with a non-terminal loop)
 // — the fork-bomb / destabilization brake. `PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE` is the
 // knob; -1 / unset / invalid = no cap. Only concurrency is bounded, never lifetime:
 // workspaces persist for months, so a total-created cap would punish longevity. A
 // spawn/fork past the ceiling fails hard (508) — no queue, no retry. Checked at the
-// single run-creation site (Dispatcher.#handleWorkerCopy, which both spawns and forks); irc is
-// exempt — it targets an existing run and creates nothing.
+// single worker-creation site (Dispatcher.#handleWorkerControl, which both spawns and forks); IRC is
+// exempt — it targets an existing worker and creates nothing.
 export default class WorkerCap {
     static async deny(db, workspaceId) {
         const raw = process.env.PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE;
@@ -12,8 +13,16 @@ export default class WorkerCap {
         if (!Number.isFinite(cap) || cap < 0)
             return null; // no cap
         const row = await db.worker_count_active.get({ workspace_id: workspaceId });
-        if ((row?.n ?? 0) >= cap)
-            return { status: 508, error: `workspace active-run ceiling reached (PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=${cap})` };
+        const activeWorkers = row?.n ?? 0;
+        if (activeWorkers >= cap) {
+            return Results.failure("engine:worker", "active-worker-limit-reached", 508, `The workspace has ${activeWorkers} active workers, reaching its limit of ${cap}.`, {}, {
+                activeWorkers,
+                maximumActiveWorkers: cap,
+                stage: "worker-admission",
+                recovery: "Wait for an active worker to finish or KILL one before creating another.",
+                retryable: false,
+            });
+        }
         return null;
     }
 }

package/dist/core/worker-cap.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker-cap.js","sourceRoot":"","sources":["../../src/core/worker-cap.ts"],"names":[],"mappings":"AAEA,0FAA0F;AAC1F,gGAAgG;AAChG,oFAAoF;AACpF,kFAAkF;AAClF,oFAAoF;AACpF,+FAA+F;AAC/F,2DAA2D;AAC3D,MAAM,CAAC,OAAO,OAAO,SAAS;IAC1B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAM,EAAE,WAAmB;QACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC;QACpE,MAAM,GAAG,GAAG,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,SAAS;QAC5D,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,qFAAqF,GAAG,GAAG,EAAE,CAAC;QACrJ,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}
+{"version":3,"file":"worker-cap.js","sourceRoot":"","sources":["../../src/core/worker-cap.ts"],"names":[],"mappings":"AAEA,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC,0FAA0F;AAC1F,gGAAgG;AAChG,oFAAoF;AACpF,kFAAkF;AAClF,oFAAoF;AACpF,qGAAqG;AACrG,8DAA8D;AAC9D,MAAM,CAAC,OAAO,OAAO,SAAS;IAC1B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAM,EAAE,WAAmB;QACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC;QACpE,MAAM,GAAG,GAAG,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,SAAS;QAC5D,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC;QAC3F,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,aAAa,IAAI,GAAG,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,OAAO,CAClB,eAAe,EACf,6BAA6B,EAC7B,GAAG,EACH,qBAAqB,aAAa,0CAA0C,GAAG,GAAG,EAClF,EAAE,EACF;gBACI,aAAa;gBACb,oBAAoB,EAAE,GAAG;gBACzB,KAAK,EAAE,kBAAkB;gBACzB,QAAQ,EAAE,0EAA0E;gBACpF,SAAS,EAAE,KAAK;aACnB,CACJ,CAAC;QACN,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}

package/dist/core/{run-ops.sql → worker-ops.sql}

@@ -1,7 +1,7 @@
--- worker:// op family — the run-table primitive spawn/irc need beyond fork.sql.
+-- worker:// op family — the worker-table primitive spawn/irc need beyond fork.sql.
 -- Resolve a sister worker by name, WITHIN a workspace only (the actor boundary — a
--- model never reaches another workspace's workers, SPEC §machine-processes). Newest
--- wins if a name was reused. spawn reuses fork.sql's run-insert (fork_insert_worker,
+-- model never reaches another workspace's workers, SPEC {§machine-processes}). Newest
+-- wins if a name was reused. spawn reuses fork.sql's worker insert (fork_insert_worker,
 -- the identical INSERT); fork reuses Fork.fork; only by-name resolution is new.
 
 -- PREP: worker_resolve_by_name
@@ -9,13 +9,13 @@ SELECT id FROM workers WHERE workspace_id = $workspace_id AND name = $name
 ORDER BY id DESC LIMIT 1;
 
 -- PREP: worker_name_by_id
--- A worker's name from its id (§worker-scheme) — the worker:/// self-fold resolves the
--- acting run (ctx.workerId) to its name to key its worker-scope entries by authority.
+-- A worker's name from its id ({§worker-scheme}) — the worker:/// self-fold resolves the
+-- acting worker (ctx.workerId) to the owner named by the URI authority.
 SELECT name FROM workers WHERE id = $worker_id;
 
 -- PREP: worker_deliverable_by_name
--- The newest run holding this name, with its latest loop's status + terminal message — the
--- deliverable a sister COLLECTS by READing worker://<name> (§worker-scheme-collect, the pull side of
+-- The newest worker holding this name, with its latest loop's status + terminal message — the
+-- deliverable a sister COLLECTS by READing worker://<name> ({§worker-scheme-collect}, the pull side of
 -- the same deliverable the push delta carries). Terminal status → the message is the result (200)
 -- or the abandonment reason; non-terminal → the worker hasn't delivered yet (READ steers to 202).
 -- terminated_by names an external cancellation so COLLECT renders its marker.
@@ -27,17 +27,17 @@ ORDER BY r.id DESC, l.sequence DESC
 LIMIT 1;
 
 -- PREP: worker_live_by_name
--- The newest run holding this name that is still LIVE (a non-terminal loop, 100/102) —
+-- The newest worker holding this name that is still LIVE (a non-terminal loop, 100/102) —
 -- the spawn gate's collision check. A hit means the name is in use by a running sister
--- (refuse: 409); no hit means the name is free or held only by a terminated run (reclaim).
+-- (refuse: 409); no hit means the name is free or held only by a terminated worker (reclaim).
 SELECT r.id FROM workers r
 JOIN loops l ON l.worker_id = r.id
 WHERE r.workspace_id = $workspace_id AND r.name = $name AND l.status IN (100, 102)
 ORDER BY r.id DESC LIMIT 1;
 
 -- PREP: worker_count_active
--- Runs in a workspace with a non-terminal loop (status 100 pending / 102 in-progress)
--- — "active" for the PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE ceiling (run-cap.ts).
+-- Workers in a workspace with a non-terminal loop (status 100 pending / 102 in-progress)
+-- — "active" for the PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE ceiling (worker-cap.ts).
 SELECT COUNT(DISTINCT r.id) AS n FROM workers r
 JOIN loops l ON l.worker_id = r.id
 WHERE r.workspace_id = $workspace_id AND l.status IN (100, 102);

package/dist/core/workspace-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-settings.d.ts","sourceRoot":"","sources":["../../src/core/workspace-settings.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,OAAO,OAAO,iBAAiB;IAGlC,OAAa,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAa5E;IAKD,OAAa,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3E;IAOD,OAAa,WAAW,CAAC,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAOvH;CACJ"}
+{"version":3,"file":"workspace-settings.d.ts","sourceRoot":"","sources":["../../src/core/workspace-settings.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,OAAO,OAAO,iBAAiB;IAGlC,OAAa,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAa5E;IAKD,OAAa,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3E;IAOD,OAAa,WAAW,CAAC,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAiBvH;CACJ"}

package/dist/core/workspace-settings.js

@@ -1,8 +1,8 @@
-// #231 — a workspace's client-chosen open-context: the per-workspace overrides a client
+// {§operator-config} — a workspace's client-chosen open context: the per-workspace overrides a client
 // user legitimately sets at workspace.create, read at turn-0 with precedence over env.
 // Two knobs with deliberately different compose semantics:
 //   - filesItems: REPLACE — a single scalar; the client value wins outright over
-//     PLURNK_SERVICE_FILES_ITEMS (normalization — 0=off / -1=full / N=first-N — stays in Engine).
+//     PLURNK_SERVICE_FILES_ITEMS (0=off / -1=complete shallow map / N=file-map first-N).
 //   - mdDocs: UNION — the server env docs (PLURNK_SERVICE_MD_*) and the client's docs ride
 //     together; the systemwide policy doc survives unless the client shadows its alias.
 // Storage is a JSON bag on workspaces.settings (the env mdDocs live in process.env, never
@@ -26,7 +26,7 @@ export default class WorkspaceSettings {
             : [];
         return { filesItems, mdDocs, maxCommands, git, client, execs, questions };
     }
-    // §send-300-choices — the three-state cascade resolved: ALLOWED servicewide (PLURNK_QUESTIONS
+    // {§send-300-choices} — the three-state cascade resolved: ALLOWED servicewide (PLURNK_QUESTIONS
     // != "0") AND affirmatively REQUESTED by the client for this workspace. One predicate, shared by
     // the dispatch gate and the teaching injection so capability and teaching can never desync.
     static async questionsEnabled(db, workspaceId) {
@@ -36,19 +36,27 @@ export default class WorkspaceSettings {
     }
     // The turn-0 reference-doc set: server env docs (PLURNK_SERVICE_MD_*, read from disk) UNION the
     // workspace's client docs (content), keyed by `<alias>.md`. On alias collision the client
-    // wins — it may deliberately shadow a server doc, but by default the policy doc rides
-    // along. Missing env files are skipped (same as the env-only path before #231). The set
-    // is the single source for BOTH the loop_run materialize and the Engine turn-0 READ foist.
+    // wins before I/O — a shadowed operator path is not selected. An unshadowed configured
+    // path is required and fails causally if unreadable ({§operator-config-workspace-md-docs}).
+    // The set is the single source for BOTH materialization and the Engine turn-0 READ foist.
     static async resolveDocs(clientDocs) {
+        const clientByEntry = new Map(clientDocs.map(({ alias, content }) => [`${alias}.md`, content]));
         const byEntry = new Map();
         for (const { entryName, path } of Paths.docs()) {
+            const clientContent = clientByEntry.get(entryName);
+            if (clientContent !== undefined) {
+                byEntry.set(entryName, clientContent);
+                continue;
+            }
             try {
                 byEntry.set(entryName, await readFile(path, "utf8"));
             }
-            catch { /* missing → skip */ }
+            catch (cause) {
+                throw new Error(`configured operator reference doc '${entryName}' could not be read`, { cause });
+            }
         }
-        for (const { alias, content } of clientDocs)
-            byEntry.set(`${alias}.md`, content); // client wins
+        for (const [entryName, content] of clientByEntry)
+            byEntry.set(entryName, content);
         return [...byEntry].map(([entryName, content]) => ({ entryName, content }));
     }
 }

package/dist/core/workspace-settings.js.map

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

package/dist/digest/Digest.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import type { Provider } from "@plurnk/plurnk-providers";
+import { type Provider } from "@plurnk/plurnk-providers";
 interface DigestOptions {
     dbPath: string;
     digestDir?: string;
@@ -14,6 +14,7 @@ export default class Digest {
         provider?: Provider;
     }): Promise<{
         path: string;
+        reportPath: string;
         workers: number;
     }>;
     static run(opts: DigestOptions): void;

package/dist/digest/Digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Digest.d.ts","sourceRoot":"","sources":["../../src/digest/Digest.ts"],"names":[],"mappings":";AAwCA,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAuEtE,UAAU,aAAa;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,CAAC,OAAO,OAAO,MAAM;;IA6RvB,MAAM,CAAC,aAAa,IAAI,MAAM,CAO7B;IAQD,OAAa,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAuEpI;IAED,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA8GpC;CACJ"}
+{"version":3,"file":"Digest.d.ts","sourceRoot":"","sources":["../../src/digest/Digest.ts"],"names":[],"mappings":";AAiDA,OAAO,EAA4E,KAAK,QAAQ,EAA6C,MAAM,0BAA0B,CAAC;AA6G9K,UAAU,aAAa;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,CAAC,OAAO,OAAO,MAAM;;IA2YvB,MAAM,CAAC,aAAa,IAAI,MAAM,CAO7B;IAID,OAAa,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAiKxJ;IAED,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAIpC;CA4HJ"}