bareloop 0.13.0 → 0.15.0

package/src/promptregisters.js

@@ -0,0 +1,93 @@
+// THE PROMPT REGISTER INVENTORY — build-list item 5 (PRD TODO #8), Q9 answered
+// (hamr, 2026-08-25): "a check". A commit that changes a prompt register must
+// say, in its message, the failure that caused the change, what it addresses,
+// and what it corrects — doctrine already stated once ("a frozen rule without
+// a wired detector is prose", docs/product/2026-08-23-agreed-build-list.md:187-189)
+// so convention-only was rejected. This module is the ONE place that inventory
+// lives: `scripts/prompt-commit-check.mjs` reads it to decide which commits the
+// rule applies to, and this file's own doc-comment is where a human reads it.
+//
+// The inventory is FILE-scoped, not const-scoped. Several of the files below
+// hold more than one named prompt const, and at least two (authorscout.js,
+// cardauthor.js) also build a model-facing prompt INLINE inside a function
+// (template literals, not a top-level const) rather than assembling one from a
+// named export. A const-scoped check would silently miss those; a file-scoped
+// one does not, because the whole file is in scope once it appears here. The
+// `name` field on each entry is documentation only — grepped to the byte range
+// that motivated it — and carries no weight in `isPromptFile`.
+//
+// Verified against source 2026-08-25 (grepped for exported/module-level string
+// consts that read as model-facing instruction text, and separately for inline
+// template-literal prompts built inside a function). Files checked and found to
+// carry NO prompt content: src/plan.js, src/validate.js, src/kinds.js,
+// src/text.js, src/declaredclose.js, src/calibrate.js, src/index.js (the last
+// is the barrel export only).
+
+/**
+ * One entry in the prompt-register inventory: a file known to carry
+ * model-facing prompt/instruction text, and the name(s) that live there for a
+ * human reading this file. `name` may point at a named const OR at a function
+ * that builds a prompt inline (e.g. `scoutPrompt()`) — the check only ever
+ * keys on `file`.
+ * @typedef {{file: string, name: string}} PromptRegisterEntry
+ */
+
+/** @type {ReadonlyArray<PromptRegisterEntry>} */
+export const PROMPT_REGISTERS = Object.freeze([
+  // src/authorscout.js — the read-only repo-survey scout that opens authoring
+  Object.freeze({ file: 'src/authorscout.js', name: 'SCOUT_SYSTEM' }),
+  Object.freeze({ file: 'src/authorscout.js', name: 'SCOUT_RECOVERY_PROMPT' }),
+  Object.freeze({ file: 'src/authorscout.js', name: 'scoutPrompt() (inline template, not a const)' }),
+
+  // src/authorflow.js — the declaration-authoring turn (system + revise/re-ask)
+  Object.freeze({ file: 'src/authorflow.js', name: 'AUTHOR_SYSTEM' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'REVISE_INSTRUCTION' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'STRUCTURE_INSTRUCTION_TOOL' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'STRUCTURE_INSTRUCTION_TEXT' }),
+
+  // src/judged.js — the softgreen judge's locate prompt (spine + per-rule asks)
+  Object.freeze({ file: 'src/judged.js', name: 'PROMPT_HEAD' }),
+  Object.freeze({ file: 'src/judged.js', name: 'PROMPT_TAIL' }),
+  Object.freeze({ file: 'src/judged.js', name: 'JUDGE_RULES[*].ask (per-rule fragments)' }),
+  Object.freeze({ file: 'src/judged.js', name: 'locatePrompt() (inline template, not a const)' }),
+
+  // src/cardauthor.js — compiles a person's own words into a judged rubric
+  Object.freeze({ file: 'src/cardauthor.js', name: 'COMPILE_SYSTEM' }),
+  Object.freeze({ file: 'src/cardauthor.js', name: 'cardCasesPrompt() (inline template, not a const)' }),
+
+  // src/readshim.js — the capped/deduplicating read shim's worker-facing strategy
+  Object.freeze({ file: 'src/readshim.js', name: 'READ_SHIM_STRATEGY' }),
+  Object.freeze({ file: 'src/readshim.js', name: 'READ_SHIM_DIFF_STRATEGY' }),
+
+  // src/tools.js — the worker tool menu: personas, retrieval/edit/component strategy
+  Object.freeze({ file: 'src/tools.js', name: 'PERSONA_TOOLS' }),
+  Object.freeze({ file: 'src/tools.js', name: 'RETRIEVAL_STRATEGY' }),
+  Object.freeze({ file: 'src/tools.js', name: 'EDIT_STRATEGY' }),
+  Object.freeze({ file: 'src/tools.js', name: 'COMPONENT_STRATEGIES' }),
+  Object.freeze({ file: 'src/tools.js', name: 'strategyFor() (assembles per-grant strategy prose)' }),
+  Object.freeze({ file: 'src/tools.js', name: 'LINE_SPACE (module-private, not exported)' }),
+  Object.freeze({ file: 'src/tools.js', name: 'PERSONA (module-private, not exported, currently unreferenced)' }),
+
+  // src/planrun.js — the native-surface read-truncation strategy line
+  Object.freeze({ file: 'src/planrun.js', name: 'NATIVE_READ_STRATEGY' }),
+]);
+
+/** The distinct file paths carrying prompt registers, repo-root-relative with
+ * forward slashes — derived from `PROMPT_REGISTERS` so the set can never drift
+ * from the entries above. @type {ReadonlySet<string>} */
+const PROMPT_FILES = new Set(PROMPT_REGISTERS.map((e) => e.file));
+
+/**
+ * True when `path` names one of the inventoried prompt-register files. Accepts
+ * either a repo-root-relative path (`src/tools.js`) or an absolute/relative
+ * path ending in one (`/home/x/bareloop/src/tools.js`, `./src/tools.js`) — git
+ * hands the check root-relative paths, but a caller working from an absolute
+ * path should not have to strip the prefix itself.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isPromptFile(path) {
+  if (typeof path !== 'string' || path === '') return false;
+  const normalized = path.replace(/\\/g, '/');
+  return [...PROMPT_FILES].some((f) => normalized === f || normalized.endsWith(`/${f}`));
+}

package/src/readshim.js

@@ -332,13 +332,18 @@ const stalePastEofNotice = (path, startLine, endLine, lines, detail) =>
  * reference to the ledger — see its own note. Both live in one object because
  * they are one worker's shim: the read seam and the retrieval seam the cap
  * steers a capped worker towards.
- * @param {{cap?: number, arm?: ReadShimArm}} [opts] `cap`: delivery bound in bytes (the
- *   shipped value is `READ_SHIM_CAP`; the option exists so the native path can pin the
- *   two bounds to one number rather than two constants drifting apart). `arm`: which
- *   levers are live (`readShimArm`). Defaults to ALL of them, so every caller written
- *   before the arms existed keeps the behaviour it was written against.
+ * @param {{cap?: number, arm?: ReadShimArm, onCount?: ((kind: 'pointered'|'capped', bytesWithheld: number) => void)|null}} [opts]
+ *   `cap`: delivery bound in bytes (the shipped value is `READ_SHIM_CAP`; the option
+ *   exists so the native path can pin the two bounds to one number rather than two
+ *   constants drifting apart). `arm`: which levers are live (`readShimArm`). Defaults to
+ *   ALL of them, so every caller written before the arms existed keeps the behaviour it
+ *   was written against. `onCount`: MEMORY-CACHE — fired once per pointer/capped-slice
+ *   response with exactly the bytes withheld on THAT response, for a caller (e.g.
+ *   `runPlan`) that sums several workers' shims into one run-level readout. Never called
+ *   for a diff response (L2 is its own lever, uncounted here) or a first read under the
+ *   cap (nothing was withheld).
  */
-export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
+export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL, onCount = null } = {}) {
   /** path → what the worker has been handed of the CURRENT content. `full` is
    * the delivered text itself, kept ONLY while the worker holds the whole file
    * (null otherwise) because that is the only state a diff is legal from.
@@ -354,6 +359,22 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
    * @type {Map<string, {hash: string, total: number, delivered: number, full: string|null}>} */
   const ledger = new Map();
 
+  // MEMORY-CACHE counters (this worker's own ledger, summed by a caller across
+  // workers for a run-level readout — see `onCount` above). Counted only where
+  // it is EXACT, never estimated: a pointer withholds exactly `total` bytes (the
+  // whole delivery it replaces) and a capped slice withholds exactly `total - end`
+  // (the tail this call did not send) — both numbers the ledger already computes
+  // for its own bookkeeping below, read here rather than re-derived.
+  let pointered = 0;
+  let capped = 0;
+  let bytesWithheld = 0;
+  /** @param {'pointered'|'capped'} kind @param {number} bytes */
+  const count = (kind, bytes) => {
+    if (kind === 'pointered') pointered++; else capped++;
+    bytesWithheld += bytes;
+    if (onCount) onCount(kind, bytes);
+  };
+
   /**
    * THE STALE-POINTER SERVE. When `ctx_get` throws `StalePointerError` — the file
    * changed on disk after indexing — hand back the REQUESTED LINE RANGE read
@@ -510,6 +531,9 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
       // slice path and is delivered (as nothing) truthfully.
       if (arm.pointer && seen && seen.hash === hash && start >= total) {
         ledger.set(path, { hash, total, delivered: total, full: r });
+        // Withheld = the whole delivery this pointer replaces: `total` bytes the
+        // worker asked to be re-sent and was not, because it already holds them.
+        count('pointered', total);
         return pointer(path, total);
       }
       ledger.set(path, { hash, total, delivered: end, full: end === total ? r : null });
@@ -518,12 +542,20 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
       // no notice, no reframing. That is the overwhelming majority of reads, and
       // it keeps the shim invisible where it buys nothing.
       if (start === 0 && end === total) return slice;
+      // Withheld = the tail beyond this slice (`total - end`), not the slice
+      // itself — the slice IS what was sent; the remainder is what was not.
+      if (end < total) count('capped', total - end);
       return slice + (end < total ? capNotice(start, end, total) : doneNotice(start, total));
     };
     return tool;
   };
 
-  return { arm, cap, wrapRead, serveStale };
+  /** MEMORY-CACHE: this worker's own counts, exact — never re-derived, never
+   * estimated. `bytesWithheld` sums only the `pointered`/`capped` cases above;
+   * the diff lever (L2) is a different response shape and is not counted here. */
+  const summary = () => ({ pointered, capped, bytesWithheld });
+
+  return { arm, cap, wrapRead, serveStale, summary };
 }
 
 /**