instar 1.3.1144 → 1.3.1145

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1144",
+  "packageVersion": "1.3.1145",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "a01cf44f29d7c2c5e2bc284dbcd18e27b5c4d6035f3fee7b8e8254e8a993cf2d",
+  "sha256": "4a5b88caa62ae256f4868735dc66735c52ae30604a8272c977ca1f4564086e43",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1144"
+  "packageVersion": "1.3.1145"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1144"
+  "packageVersion": "1.3.1145"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1144",
+  "version": "1.3.1145",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/lint-journal-actuation-ban.js

@@ -12,8 +12,37 @@
  * separate module from the writer so this ban has a precise import target —
  * actuators MAY hold the writer (they emit), they may never read.
  *
- * Guardrail, not proof (a consumer could re-read the JSONL by hand); the
- * declared §3.9 duty is the authority, this catches the direct pattern.
+ * ── 2026-08-14: the header used to declare TWO limitations. One is now closed,
+ * one is NOT, and pretending otherwise would be the worse outcome.
+ *
+ * CLOSED — "this catches the direct pattern". The match required the `from`
+ * keyword, so `await import(...)` and `require(...)` walked straight past it.
+ * Reproduced against the shipped lint on a REAL listed actuator: it reported
+ * "clean". Now every module-loading form is matched, comments are stripped
+ * first (so a §3.9 reference in prose can never be a violation), and a
+ * runtime-erased `import type` is correctly NOT a violation.
+ *
+ * NOT CLOSED — "grow this list when a new actuator class lands". The population
+ * is still curated by hand. Automatic discovery was BUILT, MEASURED AGAINST THIS
+ * TREE, AND REJECTED on the evidence: inferring "is this an actuator?" from
+ * declared names flagged nine sites in three files, and every one was a
+ * granularity or part-of-speech error rather than a §3.9 breach —
+ *   · `src/server/routes.ts` matched on `readReaperPeerText`, `isReaperSnapshot`,
+ *     `reaperPoolHealth`: "reaper" as a NOUN in code that REPORTS ON the reaper,
+ *     which is exactly the correct-code case (a reporting surface may read).
+ *   · `src/commands/server.ts` is the 22k-line composition root — every module's
+ *     authority is wired through it, so any file-level verdict on it is wrong in
+ *     one direction or the other.
+ *   · `src/core/WorkingSetPull.ts` matched a runtime-erased `import type`.
+ * A guard that blocks commits must not rest on a heuristic with that error rate;
+ * over-blocking correct code is the more expensive failure here. What IS closed
+ * mechanically is the STALENESS half: a curated entry that no longer exists on
+ * disk means an actuator was renamed or moved and silently fell off the ban —
+ * that is now a hard failure instead of a skipped line.
+ *
+ * Still a guardrail, not a proof: a determined consumer can re-read the JSONL by
+ * hand or reach the reader through a re-export. The declared §3.9 duty is the
+ * authority; this catches the mechanical patterns.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -27,7 +56,8 @@ const ROOT = process.argv.includes('--root')
 /**
  * Actuator modules: anything holding kill/spawn/place/transfer/reap authority.
  * Grow this list when a new actuator class lands — adding here is cheap;
- * debugging a journal-driven double-kill is not.
+ * debugging a journal-driven double-kill is not. See the header for why this
+ * stays curated rather than inferred.
  */
 const ACTUATOR_FILES = [
   'src/core/SessionManager.ts',
@@ -40,17 +70,93 @@ const ACTUATOR_FILES = [
   'src/lifeline/ServerSupervisor.ts',
 ];
 
-const READER_IMPORT = /from\s+['"][^'"]*CoherenceJournalReader(\.js)?['"]/;
+/**
+ * Every way a module can LOAD the reader at runtime. The old pattern required
+ * `from`, which is precisely the token a dynamic import does not have.
+ */
+const LOADS_READER =
+  /(?:\bfrom\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)['"][^'"]*CoherenceJournalReader(?:\.js)?['"]/;
+
+/**
+ * `import type { X } from '…Reader.js'` is erased at compile time — it creates
+ * no runtime coupling and therefore cannot act on stale data. Borrowing a TYPE
+ * from the reader is legal; holding the reader is not. A MIXED import such as
+ * `import { type A, CoherenceJournalReader }` does not match this and is still
+ * caught, which is correct — it pulls in the runtime binding.
+ */
+const TYPE_ONLY_IMPORT = /^\s*import\s+type\s/;
+
+/**
+ * Blank out comments, preserving length and line count so reported line numbers
+ * stay true. Quote-aware, so a `//` inside a string literal is not mistaken for
+ * a comment. This is what keeps "the reader named in a comment" legal no matter
+ * how wide the load-matching gets.
+ */
+function stripComments(src) {
+  const out = src.split('');
+  let i = 0;
+  let state = 'code'; // code | line | block | single | double | tick
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (state === 'code') {
+      if (c === '/' && d === '/') { state = 'line'; out[i] = ' '; out[i + 1] = ' '; i += 2; continue; }
+      if (c === '/' && d === '*') { state = 'block'; out[i] = ' '; out[i + 1] = ' '; i += 2; continue; }
+      if (c === "'") state = 'single';
+      else if (c === '"') state = 'double';
+      else if (c === '`') state = 'tick';
+      i++; continue;
+    }
+    if (state === 'line') {
+      if (c === '\n') { state = 'code'; i++; continue; }
+      out[i] = ' '; i++; continue;
+    }
+    if (state === 'block') {
+      if (c === '*' && d === '/') { state = 'code'; out[i] = ' '; out[i + 1] = ' '; i += 2; continue; }
+      if (c !== '\n') out[i] = ' ';
+      i++; continue;
+    }
+    // inside a string literal: honour escapes, then look for the closing quote
+    if (c === '\\') { i += 2; continue; }
+    if ((state === 'single' && c === "'") || (state === 'double' && c === '"') || (state === 'tick' && c === '`')) {
+      state = 'code';
+    }
+    i++;
+  }
+  return out.join('');
+}
+
+/**
+ * A lint that reports "clean" because it scanned NOTHING is worse than no lint:
+ * absence is the cheapest result to obtain, and it is indistinguishable from a
+ * genuinely clean tree. Refuse to render a verdict on a root with no src/.
+ */
+if (!fs.existsSync(path.join(ROOT, 'src'))) {
+  console.error(`lint-journal-actuation-ban: no src/ under ${ROOT} — scanned nothing, so no verdict.`);
+  process.exit(2);
+}
 
 const violations = [];
+
 for (const rel of ACTUATOR_FILES) {
   const file = path.join(ROOT, rel);
-  if (!fs.existsSync(file)) continue;
-  const lines = fs.readFileSync(file, 'utf-8').split('\n');
+
+  // The staleness half of the declared-population gap: a curated actuator that
+  // is no longer here was renamed or moved, and silently left the ban behind.
+  if (!fs.existsSync(file)) {
+    violations.push(
+      `${rel}: listed actuator is missing from the tree — renamed or moved? It has silently left the §3.9 ban. Update ACTUATOR_FILES.`,
+    );
+    continue;
+  }
+
+  const lines = stripComments(fs.readFileSync(file, 'utf-8')).split('\n');
   for (let i = 0; i < lines.length; i++) {
-    if (READER_IMPORT.test(lines[i])) {
-      violations.push(`${rel}:${i + 1}: actuator imports the journal READER (forbidden by §3.9 — the journal answers questions, live systems decide)`);
-    }
+    if (!LOADS_READER.test(lines[i])) continue;
+    if (TYPE_ONLY_IMPORT.test(lines[i])) continue;
+    violations.push(
+      `${rel}:${i + 1}: actuator loads the journal READER (forbidden by §3.9 — the journal answers questions, live systems decide)`,
+    );
   }
 }
 
@@ -60,4 +166,4 @@ if (violations.length > 0) {
   console.error('\nReplicated journal data is stale by construction. Read the live store instead.');
   process.exit(1);
 }
-console.log(`lint-journal-actuation-ban: clean (${ACTUATOR_FILES.length} actuator modules, none import the reader)`);
+console.log(`lint-journal-actuation-ban: clean (${ACTUATOR_FILES.length} actuator modules, none load the reader)`);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-14T21:37:12.442Z",
-  "instarVersion": "1.3.1144",
+  "generatedAt": "2026-08-14T22:33:19.830Z",
+  "instarVersion": "1.3.1145",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1144",
+  "packageVersion": "1.3.1145",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "a01cf44f29d7c2c5e2bc284dbcd18e27b5c4d6035f3fee7b8e8254e8a993cf2d",
+  "sha256": "4a5b88caa62ae256f4868735dc66735c52ae30604a8272c977ca1f4564086e43",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1144"
+  "packageVersion": "1.3.1145"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1144"
+  "packageVersion": "1.3.1145"
 }

package/upgrades/1.3.1145.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-journal-actuation-ban.js` enforces COHERENCE-JOURNAL-SPEC §3.9: no actuator (kill / spawn / place /
+transfer / reap) may import the journal READER, because replicated journal data is stale by construction and an
+actuator trusting it can kill live work or double-place a conversation.
+
+The check matched `/from\s+['"]…CoherenceJournalReader…['"]/`, which requires the `from` keyword. `await
+import(…)` and `require(…)` do not have it, so both loaded the reader straight past the ban. Reproduced against
+the shipped lint on a real listed actuator (`src/core/SessionManager.ts`): it printed `clean`. instar-codey
+reproduced the same evasion independently and ranked this lint first of ~20 by consequence-of-defeat.
+
+- All three load forms now match.
+- Comments are stripped (quote-aware, line-preserving) before matching, so prose describing the ban can never
+  itself be a violation.
+- `import type` is now exempt — it is erased at compile time, so it cannot act on stale data. The old pattern
+  flagged it, and a live file in the tree has that shape legitimately.
+- A curated actuator that has vanished from the tree is now a violation instead of a silently skipped line: a
+  renamed module used to leave the ban without a word.
+- A root with no `src/` exits 2 instead of printing `clean` over zero files.
+
+Deliberately NOT changed: the curated actuator list. Automatic discovery by declared-name shape was built and
+measured against this tree — nine flags across three files, every one a part-of-speech or granularity error
+("reaper" as a noun in reporting code; the 22k-line composition root; an `import type`). This lint blocks
+commits, so over-blocking correct code is the more expensive failure, and the enumerated list is the original
+converged design decision. The limit is now stated plainly in the header and pinned by a test that fails if
+anyone closes it properly.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/journal-actuation-ban-lint.test.ts` — 13/13 green.
+- Negative control: with the shipped lint restored, exactly 5 of 13 fail (dynamic import, `require`,
+  `import type`, vanished-curated-file, rootless-tree) and all 8 controls still pass — controls should pass both
+  ways, which is what makes them controls.
+- Real-tree verdict: `node scripts/lint-journal-actuation-ban.js` → `clean (8 actuator modules, none load the
+  reader)`, exit 0. All eight curated actuators verified present, none referencing the reader.
+- Full `npm run lint` chain green; `tests/unit/lint-chain-completeness.test.ts` 3/3.
+- Side-effects review: `upgrades/side-effects/journal-actuation-ban-load-forms.md`.
+- ELI16: `docs/specs/journal-actuation-ban-load-forms.eli16.md`.
+
+**Raised separately, not actioned here:** `src/commands/server.ts:20853` wires `OwnershipApplier`, which
+materializes durable topic ownership from the REPLICATED placement journal (it does validate `transferTo`
+against the live known-machine set first, and is specified in
+`docs/specs/ownership-applier-meshself-ordering-fix.md`). Whether §3.9 permits a validated read like that is a
+spec question, not a lint decision; it is on the operator's attention queue. The shipped lint does not flag it.

package/upgrades/side-effects/journal-actuation-ban-load-forms.md

@@ -0,0 +1,127 @@
+# Side-Effects Review — journal-actuation-ban: every load form, and the staleness half of the population
+
+**Version / slug:** `journal-actuation-ban-load-forms`
+**Date:** `2026-08-14`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (classifyTier: suggestedTier 1, riskFloor 1, no reasons). No spec change: COHERENCE-JOURNAL-SPEC §3.9 is unmodified; this makes the existing ban see load forms it already forbade.`
+
+## Summary of the change
+
+`scripts/lint-journal-actuation-ban.js` enforced §3.9 with `/from\s+['"]…CoherenceJournalReader…['"]/`. That
+requires the `from` keyword, which `await import(…)` and `require(…)` do not have, so both walked past the ban.
+Reproduced against the shipped lint on a REAL listed actuator (`src/core/SessionManager.ts`): it reported
+`clean`. Independently reproduced by instar-codey, who ranked this lint #1 of ~20 by consequence-of-defeat.
+
+Now: all three load forms are matched; comments are stripped (quote-aware, length- and line-preserving) before
+matching, so prose describing the ban is never a violation; a runtime-erased `import type` is correctly NOT a
+violation; a curated actuator that has vanished from the tree is a violation instead of a skipped line; and a
+root with no `src/` exits 2 rather than printing `clean`.
+
+The declared-population gap ("grow this list when a new actuator class lands") is **left open deliberately** —
+see §2.
+
+## Decision-point inventory
+
+- `LOADS_READER` — WIDEN — now matches `from` / `import(` / `require(`. CI-time only; never runtime.
+- `TYPE_ONLY_IMPORT` — ADD — narrows: `import type` is exempt (erased at compile time).
+- comment stripping — ADD — narrows: commented text cannot be a violation.
+- missing curated file — CHANGE — was `continue` (silent), now a violation.
+- root without `src/` — ADD — exit 2, no verdict.
+- No runtime block/allow decisions added or modified. This script runs in `npm run lint` and CI only.
+
+## 1. Over-block
+
+The widened matcher can only fire on the eight curated actuator files, so the blast radius is those eight.
+Verified against the real tree: none of the eight so much as mentions `CoherenceJournalReader`, and the lint
+exits 0. Two narrowings actively REDUCE over-block versus the shipped version: `import type` (which the old
+regex flagged — `src/core/WorkingSetPull.ts` is a live example of that shape) and comment stripping.
+
+The one new way to fail a build that is not a §3.9 breach: renaming a curated actuator without updating
+`ACTUATOR_FILES`. That is intended — a renamed actuator silently leaving the ban is the failure this closes —
+and the message names the file and the fix.
+
+## 2. Under-block
+
+**Automatic discovery of actuators was built, measured against this tree, and REJECTED.** Inferring "is this an
+actuator?" from declared names (functions, classes, filename) flagged nine sites across three files, and every
+one was a part-of-speech or granularity error rather than a §3.9 breach:
+
+- `src/server/routes.ts` — matched `readReaperPeerText`, `isReaperSnapshot`, `reaperPoolHealth`: "reaper" as a
+  NOUN in code that REPORTS ON the reaper. A reporting surface reading the journal is correct code.
+- `src/commands/server.ts` — the 22k-line composition root. Every module's authority is wired through it, so any
+  file-level verdict on it is wrong in one direction or the other.
+- `src/core/WorkingSetPull.ts` — a runtime-erased `import type`.
+
+This lint blocks commits, so over-blocking correct code is the more expensive failure. The enumerated-list shape
+is also the ORIGINAL converged design decision, stated in `upgrades/side-effects/coherence-journal-p1-2.md`:
+"The enumerated-list shape is deliberate: growable, reviewable." Closing it needs an authoritative actuator
+population, not a heuristic; `src/testing/selfActionRegistry.ts` (`modelsPath`, kept complete by
+`lint-no-unregistered-self-action.js`) is the closest candidate but is a superset in KIND — spend-alert
+emitters and sweeps are self-actions, not §3.9 session actuators. Left open, named in the header, and pinned by
+a test that will fail if someone closes it.
+
+Still evadable, unchanged from before: a hand-rolled JSONL read, or reaching the reader through a re-export.
+The §3.9 duty remains the authority.
+
+## 3. Level-of-abstraction fit
+
+Line-level regex over comment-stripped source, on an enumerated file list. Same layer as the shipped check —
+no AST, no type information, no new dependency. The comment stripper is the only added machinery, and it exists
+so the matcher can widen without making §3.9 prose illegal.
+
+## 4. Signal vs authority compliance
+
+Unchanged and reinforced. The lint is a CI guard, not a runtime authority; it forbids actuators from HOLDING the
+reader, which is what keeps replicated journal data signal rather than authority. Nothing here reads the journal
+at runtime.
+
+## 5. Interactions
+
+- `npm run lint` chain (`package.json:31`) — position unchanged; `tests/unit/lint-chain-completeness.test.ts`
+  passes (3/3).
+- Husky pre-commit / CI run the same chain. Exit 2 on a rootless tree is new; the repo root always has `src/`,
+  and the only caller passing `--root` is this test.
+- No source module, route, config key, or state file is touched.
+
+## 6. External surfaces
+
+None. No HTTP route, no config key, no user-visible message, no CLAUDE.md template change (the lint is
+developer-facing tooling, not an agent capability). Agent Awareness Standard does not apply.
+
+## 7. Rollback cost
+
+`git revert` of one script plus one test file. No migration, no state, no deployed artifact. The lint is
+stateless and runs from source.
+
+## Conclusion
+
+Ship. One real evasion closed with a negative control proving each assertion fails without the fix; two
+narrowings that reduce false positives below the shipped baseline; one silent-failure mode of my own making
+(clean verdict over zero files) caught and closed before it shipped.
+
+## Second-pass review (if required)
+
+Not required at Tier 1. Independent corroboration of DEFECT 1 exists regardless: instar-codey reproduced the
+dynamic-import evasion separately and ranked this lint first of ~20 by consequence-of-defeat, and recommended
+exactly the scope taken here — "low FP risk if limited to actuator files and comment-stripped `import()`,
+`require()`… Do not ban writer imports."
+
+## Evidence pointers
+
+- `tests/unit/journal-actuation-ban-lint.test.ts` — 13/13 green with the fix.
+- Negative control: with the shipped lint restored, exactly 5 of the 13 fail (dynamic import, `require`,
+  `import type`, vanished-curated-file, rootless-tree) and all 8 controls still pass — controls should pass
+  both ways, which is what makes them controls.
+- Real-tree verdict: `node scripts/lint-journal-actuation-ban.js` → `clean (8 actuator modules, none load the
+  reader)`, exit 0.
+- `upgrades/side-effects/coherence-journal-p1-2.md` — the original converged decision to enumerate.
+
+## Finding raised separately (NOT fixed here)
+
+Discovery, before it was rejected, surfaced five `await import('../core/CoherenceJournalReader.js')` sites in
+`src/commands/server.ts`. One (`:20853`) wires `OwnershipApplier`, which materializes durable topic ownership
+FROM the replicated placement journal — replicated data feeding an ownership decision that placement and
+session routing then act on. It is deliberate and specified (`docs/specs/ownership-applier-meshself-ordering-fix.md`)
+and validates `transferTo` against the live known-machine set before materializing. Whether §3.9 permits it is a
+spec question with real consequence, and it is not mine to settle inside a lint change. Raised to the operator;
+deliberately NOT actioned here, and the lint does not flag it.