instar 1.3.635 → 1.3.637

package/scripts/lint-no-wholefile-sync-read.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * lint-no-wholefile-sync-read.js — Bounded Accumulation §3c (Lint 2).
+ *
+ * Forbids a whole-file SYNCHRONOUS read of a store the registry marks
+ * `access: 'streamed'` (a store that can exceed 8MB): `JSON.parse(fs.readFileSync(p))`
+ * or `fs.readFileSync(p, ...).split(...)`. Reading a multi-MB file whole on the event
+ * loop is the stall this standard exists to kill (#1239; the cartographer index,
+ * instar#1069). Such stores must be read by streaming / segment / SQLite.
+ *
+ * COVERAGE HONESTY (No Silent Degradation): this is a static guardrail, NOT complete.
+ * It resolves a `streamed` store by its path BASENAME appearing as a literal near the
+ * read. A read via a variable path (`fs.readFileSync(this.logPath)`) is NOT statically
+ * resolvable and is NOT caught here — that gap is closed by the accessor funnel (route
+ * all reads through src/core/storage/, Bounded Accumulation Increment 2). The complete
+ * runtime check is the growth-burst test; this lint is the cheap forward ratchet that
+ * stops a NEW literal whole-file read of a bounded store.
+ *
+ * Ships WARN-then-ratchet: a FROZEN baseline grandfathers today's literal hits; a NEW
+ * hit fails. Exit codes: 0 pass · 1 new violation · 2 cannot-read.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+// --registry / --baseline / --root override the defaults (for tests + alternate checkouts).
+function argVal(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : null;
+}
+const REGISTRY = path.resolve(argVal('--registry') || path.join(ROOT, 'src', 'data', 'state-coherence-registry.json'));
+const BASELINE = path.resolve(argVal('--baseline') || path.join(ROOT, 'scripts', 'bounded-accumulation-wholefile-read-baseline.json'));
+const SRC = path.resolve(argVal('--root') || path.join(ROOT, 'src'));
+
+// Files exempt: the accessor + rotation definitions, and the standard's own machinery.
+const EXEMPT = [/\/core\/storage\//, /\/utils\/jsonl-rotation\.ts$/];
+
+function streamedBasenames() {
+  const reg = JSON.parse(fs.readFileSync(REGISTRY, 'utf8'));
+  const names = new Set();
+  for (const e of reg.entries || []) {
+    if (e.retention && (e.retention.access === 'streamed')) {
+      for (const p of e.paths || []) {
+        const b = path.basename(p).replace(/\*/g, '');
+        if (b && b.endsWith('.jsonl')) names.add(b);
+      }
+    }
+  }
+  return names;
+}
+
+function walk(dir, out) {
+  for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fp = path.join(dir, f.name);
+    if (f.isDirectory()) walk(fp, out);
+    else if (f.name.endsWith('.ts') && !f.name.endsWith('.test.ts')) out.push(fp);
+  }
+  return out;
+}
+
+// A whole-file sync read: JSON.parse(...readFileSync...) OR readFileSync(...).split
+const WHOLE_READ = /(JSON\.parse\([^)]*readFileSync|readFileSync\s*\([^)]*\)\s*\.\s*split)/;
+
+let registryBasenames;
+try {
+  registryBasenames = streamedBasenames();
+} catch (e) {
+  console.error('lint-no-wholefile-sync-read: cannot read registry: ' + e.message);
+  process.exit(2);
+}
+
+let baseline = { violations: [] };
+try {
+  baseline = JSON.parse(fs.readFileSync(BASELINE, 'utf8'));
+} catch {
+  // No baseline yet → treat as empty (first run records nothing as grandfathered).
+}
+const baselineSet = new Set((baseline.violations || []).map((v) => v.file + '::' + v.basename));
+
+const found = [];
+for (const file of walk(SRC, [])) {
+  if (EXEMPT.some((re) => re.test(file))) continue;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!WHOLE_READ.test(line)) continue;
+    // Resolve to a streamed store by a basename literal on this or the 2 lines above.
+    const ctx = (lines[i - 2] || '') + '\n' + (lines[i - 1] || '') + '\n' + line;
+    for (const b of registryBasenames) {
+      if (ctx.includes(b)) {
+        found.push({ file: path.relative(ROOT, file), basename: b, line: i + 1 });
+      }
+    }
+  }
+}
+
+// Generate-baseline mode: record current hits as grandfathered.
+if (process.argv.includes('--write-baseline')) {
+  fs.writeFileSync(
+    BASELINE,
+    JSON.stringify(
+      {
+        note: 'FROZEN baseline of literal whole-file-sync reads of streamed stores at Bounded Accumulation Increment 1. May only shrink. New hits fail the lint.',
+        frozenAt: '2026-06-21',
+        violations: found.map((f) => ({ file: f.file, basename: f.basename })),
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+  console.log(`lint-no-wholefile-sync-read: wrote baseline with ${found.length} grandfathered hit(s).`);
+  process.exit(0);
+}
+
+const newViolations = found.filter((f) => !baselineSet.has(f.file + '::' + f.basename));
+if (newViolations.length) {
+  console.error('lint-no-wholefile-sync-read: FAIL — new whole-file sync read(s) of a streamed store:');
+  for (const v of newViolations) {
+    console.error(`  • ${v.file}:${v.line} reads ${v.basename} whole. Use streaming / segment / SQLite, or route through src/core/storage/.`);
+  }
+  process.exit(1);
+}
+console.log(
+  `lint-no-wholefile-sync-read: OK — ${found.length} literal hit(s), all grandfathered (${baselineSet.size} baselined).`,
+);
+process.exit(0);

package/scripts/lint-store-retention-declared.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * lint-store-retention-declared.js — Bounded Accumulation §3b (Lint 1).
+ *
+ * Every persistent store (a category in state-coherence-registry.json) MUST declare a
+ * retention policy. This lint is the RATCHET: it FAILS on a NEW category that has no
+ * `retention`, while grandfathering the frozen legacy backlog (the §4 retrofit counts
+ * that backlog down). It also enforces D6 set-monotonicity — the frozen baseline may
+ * only SHRINK: growing it (gaming the ratchet by adding a new store to the allowlist
+ * instead of giving it retention) fails.
+ *
+ * Pairs with lint-state-registry.js (which forces a write-site to be REGISTERED at all);
+ * this lint forces a registered store to also be BOUNDED.
+ *
+ * Exit codes: 0 pass · 1 violation · 2 cannot-read (fail-loud, never silently skip).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+// --registry / --baseline override the defaults (for tests + alternate checkouts).
+function argVal(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : null;
+}
+const REGISTRY = path.resolve(argVal('--registry') || path.join(ROOT, 'src', 'data', 'state-coherence-registry.json'));
+const BASELINE = path.resolve(argVal('--baseline') || path.join(ROOT, 'scripts', 'bounded-accumulation-retention-baseline.json'));
+
+// The category count of the frozen baseline at Increment 1. The baseline may only
+// shrink; a larger set means the allowlist was grown to dodge the ratchet (D6).
+const FROZEN_BASELINE_COUNT = 75;
+
+function hasRetention(e) {
+  return !!(e && e.retention && typeof e.retention === 'object' && Object.keys(e.retention).length > 0);
+}
+
+let registry, baseline;
+try {
+  registry = JSON.parse(fs.readFileSync(REGISTRY, 'utf8'));
+} catch (e) {
+  console.error('lint-store-retention-declared: cannot read registry: ' + e.message);
+  process.exit(2);
+}
+try {
+  baseline = JSON.parse(fs.readFileSync(BASELINE, 'utf8'));
+} catch (e) {
+  console.error('lint-store-retention-declared: cannot read frozen baseline: ' + e.message);
+  process.exit(2);
+}
+
+const baselineSet = new Set(baseline.categories || []);
+const errors = [];
+
+// D6: the frozen baseline may only shrink.
+if ((baseline.categories || []).length > FROZEN_BASELINE_COUNT) {
+  errors.push(
+    `Retention baseline GREW (${baseline.categories.length} > frozen ${FROZEN_BASELINE_COUNT}). ` +
+      `The baseline may only shrink (D6 set-monotonicity) — declare a retention policy on the new ` +
+      `store instead of adding it to the grandfathered allowlist.`,
+  );
+}
+
+// Every no-retention category must be in the frozen baseline (grandfathered legacy).
+for (const e of registry.entries || []) {
+  if (hasRetention(e)) continue;
+  if (!baselineSet.has(e.category)) {
+    errors.push(
+      `Store category "${e.category}" has NO retention policy and is not in the frozen baseline. ` +
+        `Every persistent store must declare a retention policy (Bounded Accumulation §2). Add a ` +
+        `"retention" field to its state-coherence-registry.json entry — one of: ` +
+        `{class:'A',access:'streamed',maxBytes,keepSegments} (rotating log), ` +
+        `{class:'C',access:'streamed',complianceHold:true} (audit/forensic — archive, never drop), ` +
+        `{class:'sqlite',access:'sqlite',maxAgeMs} (indexed store), ` +
+        `{class:'R',access:'protocol-reader',boundedBy:'replication-protocol'} (replication substrate), or ` +
+        `{class:'resolution',boundedByResolution:true,maxOpenItems} (actionable queue).`,
+    );
+  }
+}
+
+if (errors.length) {
+  console.error('lint-store-retention-declared: FAIL');
+  for (const e of errors) console.error('  • ' + e);
+  process.exit(1);
+}
+
+const retentioned = (registry.entries || []).filter(hasRetention).length;
+console.log(
+  `lint-store-retention-declared: OK — ${retentioned} stores retentioned, ` +
+    `${baselineSet.size} grandfathered (retrofit backlog, may only shrink).`,
+);
+process.exit(0);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-21T10:22:16.189Z",
-  "instarVersion": "1.3.635",
+  "generatedAt": "2026-06-22T00:10:26.994Z",
+  "instarVersion": "1.3.637",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/state-coherence-registry.json

@@ -14,7 +14,13 @@
       "paths": [
         "state/coherence-journal/"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "R",
+        "access": "protocol-reader",
+        "boundedBy": "replication-protocol",
+        "note": "CARVED OUT — bounded inside CoherenceJournal via KindRetention + the new seq-floor prune guard; never externally rotated"
+      }
     },
     {
       "category": "pending-pulls",
@@ -171,7 +177,13 @@
       "paths": [
         "state/coherence-journal/*.topic-placement.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "R",
+        "access": "protocol-reader",
+        "boundedBy": "replication-protocol",
+        "note": "CARVED OUT — replication substrate"
+      }
     },
     {
       "category": "autonomous-working-artifacts",
@@ -432,7 +444,12 @@
         "state/resource-ledger.db",
         "state/resources.db"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "sqlite",
+        "access": "sqlite",
+        "maxAgeMs": 2592000000
+      }
     },
     {
       "category": "lease-coordination-state",
@@ -608,7 +625,14 @@
         "state/destructive-ops.jsonl",
         "logs/destructive-ops.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "C",
+        "access": "streamed",
+        "complianceHold": true,
+        "keepSegments": 0,
+        "note": "forensic trail — archive, never drop-delete (replaces SafeGitExecutor.maybeRotateAuditLog drop-rotate)"
+      }
     },
     {
       "category": "audit-job-runs",
@@ -621,7 +645,13 @@
         "state/job-runs.jsonl",
         "logs/job-runs.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "A",
+        "access": "streamed",
+        "maxBytes": 33554432,
+        "keepSegments": 4
+      }
     },
     {
       "category": "audit-reaper",
@@ -671,7 +701,14 @@
         "state/security.jsonl",
         "logs/security.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "C",
+        "access": "streamed",
+        "complianceHold": true,
+        "keepSegments": 0,
+        "note": "forensic trail — archive, never drop-delete (replaces SecurityLog maybeRotateJsonl keep-ratio trim)"
+      }
     },
     {
       "category": "audit-decision-journal",
@@ -749,7 +786,13 @@
         "state/telegram-messages.jsonl",
         "logs/telegram-messages.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "A",
+        "access": "streamed",
+        "maxBytes": 33554432,
+        "keepSegments": 4
+      }
     },
     {
       "category": "audit-a2a-messages",
@@ -814,7 +857,13 @@
         "state/feedback.jsonl",
         "logs/feedback.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "A",
+        "access": "streamed",
+        "maxBytes": 33554432,
+        "keepSegments": 4
+      }
     },
     {
       "category": "audit-apprenticeship-decisions",
@@ -840,7 +889,13 @@
         "state/token-ledger.db",
         "state/tokens.db"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "sqlite",
+        "access": "sqlite",
+        "maxAgeMs": 2592000000,
+        "note": "incremental-vacuum + batched delete off-thread (Increment 2)"
+      }
     },
     {
       "category": "derived-semantic-memory",
@@ -856,7 +911,13 @@
         "state/episodes/",
         "memory/semantic.jsonl"
       ],
-      "grandfathered": false
+      "grandfathered": false,
+      "retention": {
+        "class": "sqlite",
+        "access": "sqlite",
+        "maxAgeMs": 7776000000,
+        "note": "mixed .db + memory/semantic.jsonl; jsonl arm is A-class streamed in retrofit"
+      }
     },
     {
       "category": "derived-topic-memory",

package/upgrades/1.3.636.md

@@ -0,0 +1,59 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The sleep/wake watcher (`SleepWakeDetector`) used to decide "did the machine sleep?"
+purely from a timer-drift jump plus **system load**. On a multi-core machine, one
+internal thread can freeze for 10–60 seconds without moving the system load average — so
+the watcher would announce a "wake after ~Ns sleep" when the machine never slept at all
+(it was plugged in, lid open, with `caffeinate` running — sleep was impossible). Those
+false "sleep" reports hid the real cause: short event-loop freezes.
+
+Now the watcher also measures how much CPU **its own process** burned during the gap. A
+truly sleeping process burns almost no CPU; a frozen-but-busy one burns CPU the whole
+time. So a busy gap is correctly reported as a `stall` (a freeze the wedge watchers can
+act on) instead of a phantom "sleep." The new check runs first, applies even to
+multi-minute gaps, defaults on with no configuration, and fails safe (if the CPU reading
+can't be taken it quietly falls back to the old behavior).
+
+## What to Tell Your User
+
+If you ever saw your agent claim it "woke from sleep" on a machine that was plugged in
+and awake — that was a misread. The watcher now tells the difference between a real sleep
+and an internal freeze by checking its own CPU use, so those phantom "sleep" messages stop
+and genuine freezes get flagged honestly. Nothing to configure.
+
+## Summary of New Capabilities
+
+No new user-facing capability — a correctness fix. `SleepWakeDetector` gains a per-process
+CPU-burn discriminator that separates an event-loop block from real sleep: it emits a
+signal-only `stall` event (and suppresses the false `wake`) when this process burned CPU
+through the drift gap. Tunable via the optional `cpuBlockBusyRatio` (default 0.5; set 0 to
+disable). `getStats().suppressedByReason` gains an `event-loop-block` count. Existing
+agents get it via the normal update; on-disk formats and API shapes are unchanged.
+
+## Evidence
+
+**Reproduction (live, 2026-06-21):** Echo's server was flapping (watchdog SIGKILL+respawn
+on a cadence) from event-loop wedges. Throughout, `logs/server.log` carried
+`[SleepWakeDetector] Wake detected after ~Ns sleep` lines — on a host that was plugged in,
+lid open, with `caffeinate` running, where OS sleep is physically impossible. `pmset -g`
+confirmed no sleep occurred. The drifts were single-process event-loop blocks (one Node
+thread pinned), and the 16-core `loadavg` stayed well under `maxLoadRatio` (1.5), so the
+existing load guard never tripped and each block printed a phantom "sleep."
+
+**Before:** a 14s CPU-bound event-loop block under normal system load → `wake` emitted
+(`sleepDurationSeconds ≈ 14`), credited as real sleep in `wakeHistory`; the wedge was
+invisible (laundered into "sleep").
+
+**After:** the same 14s CPU-bound drift → the per-process CPU check measures ~100% busy
+across the gap → a `stall` event is emitted and the `wake` is suppressed (recorded under
+`suppressedByReason['event-loop-block']`), so it is never credited as sleep. A genuine
+idle/suspend gap (~0% CPU) still emits `wake` unchanged.
+
+**Automated:** `tests/unit/SleepWakeDetector-cpu-block.test.ts` reproduces both directions
+with injected clock + CPU providers (CPU-busy short drift → stall; idle drift → wake; long
+CPU-busy drift → stall; throwing provider → no crash). 15/15 unit tests green; `tsc` clean.

package/upgrades/1.3.637.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Instar gains a new constitutional standard — **Bounded Accumulation: every persistent store must
+declare a ceiling and stay under it** — and the first slice of its enforcement. This is the
+storage-dimension twin of the existing "No Unbounded Loops" and "Bounded Notification Surface"
+standards: it exists because an agent that runs for months accumulates data in append-only logs and
+databases that only ever grow, and reading one of those multi-MB files all at once freezes the
+single-threaded event loop (the cause of recurring health-check failures and restarts).
+
+This increment is non-behavioral — it adds the substrate without changing how any current store
+behaves: a registry that records each store's retention policy, an event-loop-safe segment-rotation
+primitive (rename, never read-and-rewrite), a `JsonlStore` accessor that all JSONL persistence will
+route through, a growth-burst test that proves retention actually bounds a store on disk, and two
+build-time lints that ratchet new violations (a new store must declare a ceiling; a new whole-file
+synchronous read of a large store is rejected) while grandfathering the existing tree.
+
+## What to Tell Your User
+
+Nothing changes today in how your agent behaves. This lays the foundation that stops your agent's
+on-disk data from growing without bound and stops the kind of large-file reads that briefly freeze
+it. The actual trimming of existing oversized files, and the one-time cleanup of data that has
+already accumulated, come in the next increments (the cleanup is operator-gated — it asks before
+deleting any history).
+
+## Summary of New Capabilities
+
+- A retention policy field on every store in the state-coherence registry (10 stores declared,
+  75 legacy categories tracked as a shrink-only backlog).
+- `maybeRotateJsonlSegment` (event-loop-safe rename rotation) + `JsonlStore` (the accessor funnel
+  with an amortized size-check) in `src/core/storage/`.
+- Two CI lints — `lint-store-retention-declared` (a new store must declare a retention policy) and
+  `lint-no-wholefile-sync-read` (no new literal whole-file synchronous read of a streamed store) —
+  both wired into `npm run lint` over a frozen baseline (only NEW violations fail).
+- A growth-burst invariant test that floods a registered store and asserts the on-disk footprint
+  stays bounded by the declared policy (and that compliance-hold audit stores never drop their
+  oldest segment).

package/upgrades/side-effects/bounded-accumulation-increment-1.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — Bounded Accumulation Increment 1 (registry + accessor + 2 lints + rotation fix)
+
+**Slug:** `bounded-accumulation-increment-1` · **Tier:** 2 (spec-driven; converged + operator-approved)
+**Spec:** `docs/specs/bounded-accumulation-standard.md` (review-convergence 2026-06-21, approved)
+
+## Summary of the change
+
+The non-behavioral first increment of the Bounded Accumulation standard. It adds the ENFORCEMENT
+substrate without changing any existing store's runtime behavior:
+- `src/utils/jsonl-rotation.ts`: adds `maybeRotateJsonlSegment` — event-loop-safe segment rotation
+  (rename active → numbered segment, fresh active, unlink-oldest; O(1), NO whole-file read). The
+  existing `maybeRotateJsonl` (read-filter-rewrite) is left intact but marked non-conformant.
+- `src/core/storage/JsonlStore.ts`: the registered accessor funnel — append + a cached-byte-counter
+  throttle so even the O(1) statSync isn't paid per append.
+- `src/data/state-coherence-registry.json`: extends 10 in-scope entries with a `retention` policy
+  (A/C/sqlite/R classes). 75 legacy categories are frozen as the retrofit backlog.
+- `scripts/lint-store-retention-declared.js` (Lint 1) + `scripts/lint-no-wholefile-sync-read.js`
+  (Lint 2), wired into `npm run lint`, each with a frozen baseline.
+
+## Decision-point inventory
+
+All decisions are frozen in the spec §6 (D1–D9): 32MB/4-segment A-class default, 30-day token-ledger,
+compliance-hold (archive-never-delete) for audit logs, R-class carve-out for replication journals,
+set-monotonic ratchet, 8MB streamed threshold. No new decision is introduced at the callsite.
+
+## 1. Over-block (false positive)
+
+- Lint 1 fails a registry entry with no `retention` that is not in the frozen baseline. False positive
+  only if a genuinely-new store is legitimately unbounded — which the standard forbids by definition;
+  the author declares a policy (incl. `boundedByResolution`). Cannot mis-fire on a legacy store (all
+  75 are baselined).
+- Lint 2 fails a NEW literal whole-file read of a streamed store. Honest coverage limit: only literal
+  paths; dynamic paths are not flagged (no false positives, some false negatives — closed by the
+  accessor funnel in Increment 2).
+
+## 2. Under-block (false negative)
+
+Lint 2's dynamic-path gap (e.g. `readFileSync(this.logPath)`) is the known limit — documented in the
+lint header and in spec §3c. The runtime growth-burst test is the complete check for stores it
+exercises; the accessor funnel (Increment 2) closes the read-side gap. Not silently hidden.
+
+## 4. Signal vs authority
+
+The lints are deterministic STRUCTURAL checks (a path/registry match), permitted to block like the
+existing funnel lints (lint-state-registry, lint-no-blocking-process-scans). The SEMANTIC judgment
+("is this store actually actionable / which class?") stays with the author + reviewer, never the
+regex. Ships ratchet-over-frozen-baseline (warn-then-ratchet per Maturation Path): the current tree
+is grandfathered; only NEW violations fail.
+
+## 5. Interactions
+
+The new `maybeRotateJsonlSegment` is additive — no existing caller of `maybeRotateJsonl` is changed,
+so no store's rotation behavior changes in Increment 1 (verified: the existing
+`tests/unit/jsonl-rotation.test.ts` 11 tests still pass). The registry gains fields read only by the
+two new lints. No existing reader of the registry breaks (additive JSON fields).
+
+## 6. External surfaces
+
+None. No new HTTP route, no config-contract change, no messaging, no persistence-schema change. The
+two `scripts/*.js` lints run only at lint/CI time.
+
+## 6b. Operator-surface quality
+
+N/A — no operator/dashboard/approval surface is touched.
+
+## Framework generality
+
+N/A — `JsonlStore`/the lints are framework-agnostic infrastructure; not part of the session
+launch/inject abstraction. Works identically regardless of the agent's framework.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+The registry's `retention.access` and the new `coherenceScope` usage declare per-store posture.
+Retention is MACHINE-LOCAL by design (each machine's `.instar/` stores differ in size; the rotator
+runs per-machine). The replication substrate (`state/coherence-journal/**`) is explicitly R-class
+(carved OUT of generic rotation — naive truncation would resurrect deleted PII); it is bounded inside
+its own protocol (the seq-floor prune guard is Increment 2). No replicated state is introduced.
+
+## 8. Rollback cost
+
+Trivial. The lints ship over a frozen baseline (no current-tree failures); removing them from
+`package.json` reverts the enforcement. `maybeRotateJsonlSegment` + `JsonlStore` are new, unused by
+any runtime store yet (Increment 2 wires them), so reverting is a clean delete. The registry fields
+are additive data. Nothing to migrate back.
+
+## Evidence pointers
+
+- `tests/unit/jsonl-segment-rotation.test.ts` (7): rename-not-rewrite, prune-beyond-keep, archive
+  never-prunes, JsonlStore amortized check + bounded-under-flood.
+- `tests/integration/store-growth-burst-invariant.test.ts` (3): A-class on-disk bounded under a
+  20k-entry flood; C-class never drops its oldest segment; every registry A-class entry has an
+  enforceable maxBytes.
+- `tests/unit/bounded-accumulation-lints.test.ts` (7): both lints, both sides of each boundary
+  (pass current / fail new-unretentioned / pass new-with-retention / fail grown-baseline; Lint 2
+  pass-clean / fail-new-literal-read / pass-grandfathered).
+- Existing `tests/unit/jsonl-rotation.test.ts` (11) still green → no regression to the old path.
+- `npm run lint` green (the two new lints in the chain).
+
+## Conclusion
+
+A non-behavioral enforcement substrate: the registry declares ceilings, two lints ratchet new
+violations, and the event-loop-safe rotation primitive + accessor are ready for Increment 2 to wire
+to real stores. Grandfathers the current tree, fails only NEW violations, trivially reversible. Ship.