instar 1.3.636 → 1.3.637

package/dist/core/storage/JsonlStore.d.ts

@@ -0,0 +1,54 @@
+/**
+ * JsonlStore — the registered accessor for append-only JSONL persistence
+ * (Bounded Accumulation standard §3a/§3b).
+ *
+ * Every persistent JSONL store routes through this class so that:
+ *   1. The retention policy (maxBytes / keepSegments / archive) is declared and
+ *      ENFORCED at the one place data is written — not hoped for at each callsite.
+ *   2. The lint surface is a single funnel: raw `fs.appendFileSync` to a `.instar/`
+ *      path in `src/` is itself a Lint-1 failure; an author must use this accessor,
+ *      which makes the retention declaration unskippable.
+ *   3. Rotation is the event-loop-SAFE segment cut (rename, not read-filter-rewrite),
+ *      gated behind a cached byte-counter so the size check is amortized — even the
+ *      O(1) `statSync` is not paid on every append.
+ *
+ * This is the storage twin of the funnels SafeFsExecutor / SafeGitExecutor already
+ * establish for destructive fs/git ops: one chokepoint that a lint can enforce.
+ */
+export interface JsonlStoreOptions {
+    /** Maximum active-file size in bytes before a segment is cut. Default: 32MB. */
+    maxBytes?: number;
+    /** Rotated segments to retain (oldest beyond this are unlinked, unless archive). Default: 4. */
+    keepSegments?: number;
+    /**
+     * Compliance-hold: rotated segments are NEVER unlinked. For audit/forensic trails
+     * that must never lose their oldest entries. Default: false.
+     */
+    archive?: boolean;
+    /**
+     * Amortize the rotation size-check: only check (and possibly rotate) after this many
+     * bytes have been appended since the last check. Keeps the hot append path a pure
+     * `appendFileSync` + counter bump. Default: 64KB.
+     */
+    checkEveryBytes?: number;
+}
+export declare class JsonlStore {
+    private readonly filePath;
+    private readonly maxBytes;
+    private readonly keepSegments;
+    private readonly archive;
+    private readonly checkEveryBytes;
+    /** Bytes appended since the last rotation size-check (the cached counter). */
+    private bytesSinceCheck;
+    constructor(filePath: string, options?: JsonlStoreOptions);
+    /** Append one raw line (a trailing newline is added if absent). */
+    append(line: string): void;
+    /** Append one JSON-serialized object as a line. */
+    appendObject(obj: unknown): void;
+    /** Force a rotation size-check now (e.g. on a periodic sweep), bypassing the counter. */
+    checkRotationNow(): boolean;
+    /** The active file path this store writes to. */
+    get path(): string;
+    private ensureDir;
+}
+//# sourceMappingURL=JsonlStore.d.ts.map

package/dist/core/storage/JsonlStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonlStore.d.ts","sourceRoot":"","sources":["../../../src/core/storage/JsonlStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,8EAA8E;IAC9E,OAAO,CAAC,eAAe,CAAK;gBAEhB,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB;IAQ7D,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAgB1B,mDAAmD;IACnD,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAIhC,yFAAyF;IACzF,gBAAgB,IAAI,OAAO;IAS3B,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,SAAS;CAOlB"}

package/dist/core/storage/JsonlStore.js

@@ -0,0 +1,81 @@
+/**
+ * JsonlStore — the registered accessor for append-only JSONL persistence
+ * (Bounded Accumulation standard §3a/§3b).
+ *
+ * Every persistent JSONL store routes through this class so that:
+ *   1. The retention policy (maxBytes / keepSegments / archive) is declared and
+ *      ENFORCED at the one place data is written — not hoped for at each callsite.
+ *   2. The lint surface is a single funnel: raw `fs.appendFileSync` to a `.instar/`
+ *      path in `src/` is itself a Lint-1 failure; an author must use this accessor,
+ *      which makes the retention declaration unskippable.
+ *   3. Rotation is the event-loop-SAFE segment cut (rename, not read-filter-rewrite),
+ *      gated behind a cached byte-counter so the size check is amortized — even the
+ *      O(1) `statSync` is not paid on every append.
+ *
+ * This is the storage twin of the funnels SafeFsExecutor / SafeGitExecutor already
+ * establish for destructive fs/git ops: one chokepoint that a lint can enforce.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { maybeRotateJsonlSegment } from '../../utils/jsonl-rotation.js';
+const DEFAULT_MAX_BYTES = 32 * 1024 * 1024; // 32MB
+const DEFAULT_KEEP_SEGMENTS = 4;
+const DEFAULT_CHECK_EVERY_BYTES = 64 * 1024; // 64KB
+export class JsonlStore {
+    filePath;
+    maxBytes;
+    keepSegments;
+    archive;
+    checkEveryBytes;
+    /** Bytes appended since the last rotation size-check (the cached counter). */
+    bytesSinceCheck = 0;
+    constructor(filePath, options = {}) {
+        this.filePath = filePath;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.keepSegments = Math.max(1, options.keepSegments ?? DEFAULT_KEEP_SEGMENTS);
+        this.archive = options.archive ?? false;
+        this.checkEveryBytes = Math.max(1, options.checkEveryBytes ?? DEFAULT_CHECK_EVERY_BYTES);
+    }
+    /** Append one raw line (a trailing newline is added if absent). */
+    append(line) {
+        const data = line.endsWith('\n') ? line : line + '\n';
+        this.ensureDir();
+        fs.appendFileSync(this.filePath, data);
+        this.bytesSinceCheck += Buffer.byteLength(data);
+        if (this.bytesSinceCheck >= this.checkEveryBytes) {
+            this.bytesSinceCheck = 0;
+            // O(1) segment cut when over maxBytes; never throws.
+            maybeRotateJsonlSegment(this.filePath, {
+                maxBytes: this.maxBytes,
+                keepSegments: this.keepSegments,
+                archive: this.archive,
+            });
+        }
+    }
+    /** Append one JSON-serialized object as a line. */
+    appendObject(obj) {
+        this.append(JSON.stringify(obj));
+    }
+    /** Force a rotation size-check now (e.g. on a periodic sweep), bypassing the counter. */
+    checkRotationNow() {
+        this.bytesSinceCheck = 0;
+        return maybeRotateJsonlSegment(this.filePath, {
+            maxBytes: this.maxBytes,
+            keepSegments: this.keepSegments,
+            archive: this.archive,
+        });
+    }
+    /** The active file path this store writes to. */
+    get path() {
+        return this.filePath;
+    }
+    ensureDir() {
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        }
+        catch {
+            // directory likely exists; append will surface a real error if not
+        }
+    }
+}
+//# sourceMappingURL=JsonlStore.js.map

package/dist/core/storage/JsonlStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonlStore.js","sourceRoot":"","sources":["../../../src/core/storage/JsonlStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAoBxE,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;AACnD,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAChC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO;AAEpD,MAAM,OAAO,UAAU;IACJ,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,YAAY,CAAS;IACrB,OAAO,CAAU;IACjB,eAAe,CAAS;IACzC,8EAA8E;IACtE,eAAe,GAAG,CAAC,CAAC;IAE5B,YAAY,QAAgB,EAAE,UAA6B,EAAE;QAC3D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;QACtD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,IAAI,qBAAqB,CAAC,CAAC;QAC/E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,eAAe,IAAI,yBAAyB,CAAC,CAAC;IAC3F,CAAC;IAED,mEAAmE;IACnE,MAAM,CAAC,IAAY;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;QACtD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACjD,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;YACzB,qDAAqD;YACrD,uBAAuB,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACrC,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,YAAY,CAAC,GAAY;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,yFAAyF;IACzF,gBAAgB;QACd,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,OAAO,uBAAuB,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;IACL,CAAC;IAED,iDAAiD;IACjD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,SAAS;QACf,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;CACF"}

package/dist/utils/jsonl-rotation.d.ts

@@ -21,7 +21,44 @@ export interface RotationOptions {
  * Check if a JSONL file exceeds its size limit, and if so, rotate it
  * by keeping only the most recent lines.
  *
+ * NON-CONFORMANT to the Bounded Accumulation standard (§3.5): this rotates by
+ * `readFileSync` (whole file) + `split` + `writeFileSync`, which blocks the event
+ * loop for hundreds of ms on a multi-MB file — the exact stall the standard exists
+ * to kill. Prefer {@link maybeRotateJsonlSegment} (constant-time rename) for any
+ * store registered `access: 'streamed'`. Retained for back-compat callers pending
+ * their migration (Bounded Accumulation Increment 2).
+ *
  * @returns true if rotation occurred, false otherwise
  */
 export declare function maybeRotateJsonl(filePath: string, options?: RotationOptions): boolean;
+export interface SegmentRotationOptions {
+    /** Maximum active-file size in bytes before a segment is cut. Default: 10MB */
+    maxBytes?: number;
+    /** Number of rotated segments to retain (oldest beyond this are unlinked). Default: 4 */
+    keepSegments?: number;
+    /**
+     * Compliance-hold mode: rotated segments are NEVER unlinked. An audit/forensic
+     * trail (security.jsonl, destructive-ops.jsonl) must not lose its oldest entries —
+     * it is bounded by archive policy, never by drop. Default: false.
+     */
+    archive?: boolean;
+}
+/**
+ * Segment-based JSONL rotation — the event-loop-SAFE alternative to
+ * {@link maybeRotateJsonl}'s read-filter-rewrite (Bounded Accumulation standard §3.5).
+ *
+ * When the active file exceeds `maxBytes`, the active file is RENAMED to a numbered
+ * segment `<name>.<seq>` (a constant-time metadata op — NO file read, NO whole-file
+ * rewrite) and a fresh empty active file is opened. Oldest segments beyond
+ * `keepSegments` are unlinked — UNLESS `archive: true`, which retains every segment
+ * (compliance/audit trails that must never drop their oldest entries).
+ *
+ * Why it exists: rotating a 14MB hot log via the old read+split+rewrite path froze the
+ * event loop for hundreds of ms on the append path; renaming a segment is O(1). Callers
+ * SHOULD gate the size-check behind a cached byte-counter (see `JsonlStore`) so even the
+ * O(1) `statSync` is not paid on every append.
+ *
+ * @returns true if a segment was cut, false otherwise. Never throws.
+ */
+export declare function maybeRotateJsonlSegment(filePath: string, options?: SegmentRotationOptions): boolean;
 //# sourceMappingURL=jsonl-rotation.d.ts.map

package/dist/utils/jsonl-rotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl-rotation.d.ts","sourceRoot":"","sources":["../../src/utils/jsonl-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAyCrF"}
+{"version":3,"file":"jsonl-rotation.d.ts","sourceRoot":"","sources":["../../src/utils/jsonl-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAyCrF;AAID,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAqDnG"}

package/dist/utils/jsonl-rotation.js

@@ -12,15 +12,27 @@
  *   - Lazy rotation — called before/after append, no background timers
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
 // ── Constants ────────────────────────────────────────────────────────
 const DEFAULT_MAX_BYTES = 10 * 1024 * 1024; // 10MB
 const DEFAULT_KEEP_RATIO = 0.75;
+const DEFAULT_KEEP_SEGMENTS = 4;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 // ── Public API ───────────────────────────────────────────────────────
 /**
  * Check if a JSONL file exceeds its size limit, and if so, rotate it
  * by keeping only the most recent lines.
  *
+ * NON-CONFORMANT to the Bounded Accumulation standard (§3.5): this rotates by
+ * `readFileSync` (whole file) + `split` + `writeFileSync`, which blocks the event
+ * loop for hundreds of ms on a multi-MB file — the exact stall the standard exists
+ * to kill. Prefer {@link maybeRotateJsonlSegment} (constant-time rename) for any
+ * store registered `access: 'streamed'`. Retained for back-compat callers pending
+ * their migration (Bounded Accumulation Increment 2).
+ *
  * @returns true if rotation occurred, false otherwise
  */
 export function maybeRotateJsonl(filePath, options) {
@@ -61,4 +73,78 @@ export function maybeRotateJsonl(filePath, options) {
         return false;
     }
 }
+/**
+ * Segment-based JSONL rotation — the event-loop-SAFE alternative to
+ * {@link maybeRotateJsonl}'s read-filter-rewrite (Bounded Accumulation standard §3.5).
+ *
+ * When the active file exceeds `maxBytes`, the active file is RENAMED to a numbered
+ * segment `<name>.<seq>` (a constant-time metadata op — NO file read, NO whole-file
+ * rewrite) and a fresh empty active file is opened. Oldest segments beyond
+ * `keepSegments` are unlinked — UNLESS `archive: true`, which retains every segment
+ * (compliance/audit trails that must never drop their oldest entries).
+ *
+ * Why it exists: rotating a 14MB hot log via the old read+split+rewrite path froze the
+ * event loop for hundreds of ms on the append path; renaming a segment is O(1). Callers
+ * SHOULD gate the size-check behind a cached byte-counter (see `JsonlStore`) so even the
+ * O(1) `statSync` is not paid on every append.
+ *
+ * @returns true if a segment was cut, false otherwise. Never throws.
+ */
+export function maybeRotateJsonlSegment(filePath, options) {
+    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const keepSegments = Math.max(1, options?.keepSegments ?? DEFAULT_KEEP_SEGMENTS);
+    const archive = options?.archive ?? false;
+    try {
+        let size;
+        try {
+            size = fs.statSync(filePath).size; // O(1) — no file read
+        }
+        catch {
+            return false; // no active file yet → nothing to rotate
+        }
+        if (size <= maxBytes)
+            return false;
+        const dir = path.dirname(filePath);
+        const base = path.basename(filePath);
+        // Rotated segments are "<base>.<seq>" (optionally ".gz"); seq is monotonic.
+        const segRe = new RegExp('^' + escapeRegExp(base) + '\\.(\\d+)(?:\\.gz)?$');
+        const segments = [];
+        let maxSeq = 0;
+        for (const f of fs.readdirSync(dir)) {
+            const m = f.match(segRe);
+            if (!m)
+                continue;
+            const seq = parseInt(m[1], 10);
+            if (!Number.isFinite(seq))
+                continue;
+            segments.push({ seq, name: f });
+            if (seq > maxSeq)
+                maxSeq = seq;
+        }
+        const nextSeq = maxSeq + 1;
+        // Cut the segment: rename active → segment (constant-time), open a fresh active.
+        fs.renameSync(filePath, path.join(dir, base + '.' + nextSeq));
+        fs.writeFileSync(filePath, '');
+        // Prune oldest segments beyond keepSegments — NEVER in archive (compliance) mode.
+        if (!archive) {
+            const cutoff = nextSeq - keepSegments; // segments with seq <= cutoff are dropped
+            for (const s of segments) {
+                if (s.seq <= cutoff) {
+                    try {
+                        SafeFsExecutor.safeUnlinkSync(path.join(dir, s.name), {
+                            operation: 'src/utils/jsonl-rotation.ts:maybeRotateJsonlSegment',
+                        });
+                    }
+                    catch {
+                        // best effort — a failed unlink just leaves an extra old segment
+                    }
+                }
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=jsonl-rotation.js.map

package/dist/utils/jsonl-rotation.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl-rotation.js","sourceRoot":"","sources":["../../src/utils/jsonl-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAW3D,wEAAwE;AAExE,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;AACnD,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,OAAyB;IAC1E,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,iBAAiB,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,IAAI,kBAAkB,CAAC,CAAC,CAAC;IAErF,IAAI,CAAC;QACH,iCAAiC;QACjC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,4DAA4D;QAC5D,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAElD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;QACnE,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;QAE1C,kCAAkC;QAClC,MAAM,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;QAC3C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACvD,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,mEAAmE;QACnE,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;YAC3C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,cAAc,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,gCAAgC,EAAE,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"jsonl-rotation.js","sourceRoot":"","sources":["../../src/utils/jsonl-rotation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.636",
+  "version": "1.3.637",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "test:contract": "node scripts/run-contract-tests.js",
     "test:contract:raw": "vitest run --config vitest.contract.config.ts",
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts",
-    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js",
+    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js",
     "lint:destructive": "node scripts/lint-no-direct-destructive.js",
     "lint:dev-agent-dark-gate": "node scripts/lint-dev-agent-dark-gate.js",
     "lint:guard-manifest": "node scripts/lint-guard-manifest.js",

package/scripts/bounded-accumulation-retention-baseline.json

@@ -0,0 +1,81 @@
+{
+  "note": "FROZEN baseline of registry categories without a retention policy at Bounded Accumulation Increment 1. The lint forbids NEW categories without retention; this set may only SHRINK (D6 set-monotonicity). Giving a baselined category retention counts the backlog down.",
+  "frozenAt": "2026-06-21",
+  "categories": [
+    "attention-queue",
+    "audit-a2a-messages",
+    "audit-activity",
+    "audit-apprenticeship-decisions",
+    "audit-decision-journal",
+    "audit-operation-log",
+    "audit-prompt-gate",
+    "audit-reap-log",
+    "audit-reaper",
+    "audit-recovery-events",
+    "audit-sentinel-events",
+    "audit-skill-telemetry",
+    "audit-trust-chain",
+    "audit-watchdog-interventions",
+    "autonomous-working-artifacts",
+    "commitment-opkeys",
+    "commitment-pending-mutations",
+    "commitment-replicas",
+    "commitments",
+    "conversation-live-tail",
+    "derived-discovery",
+    "derived-docs-code-sync",
+    "derived-framework-model-preferences",
+    "derived-memory-index",
+    "derived-project-map",
+    "derived-projects-digest",
+    "derived-topic-memory",
+    "ephemeral-caches",
+    "fleet-config",
+    "guard-posture-episodes",
+    "guard-posture-peers",
+    "guard-posture-snapshot",
+    "job-definitions",
+    "job-run-state",
+    "learned-preferences",
+    "lease-coordination-state",
+    "legacy-singletons",
+    "listener-daemon-internals",
+    "machine-identity-keys",
+    "message-store-and-threads",
+    "messaging-adapter-state",
+    "nonce-sequence-watermarks",
+    "pending-pulls",
+    "per-session-state",
+    "platform-attachment-caches",
+    "process-restart-coordination",
+    "projects-registry",
+    "pull-opkeys",
+    "quota-state",
+    "relationships",
+    "relay-delivery-queues",
+    "remote-ack-queue",
+    "remote-close-audit",
+    "resume-queue",
+    "secret-vault",
+    "session-monitor-ctx-notified",
+    "slack-pending-registrations",
+    "slack-permission-decisions",
+    "slack-relationship-baselines",
+    "soul-identity-documents",
+    "stream-tickets",
+    "threadline-conversation-state",
+    "threadline-pairing-result",
+    "threadline-transport-internals",
+    "threadline-trust-profiles",
+    "topic-ownership-current",
+    "topic-project-bindings",
+    "trust-elevation-incidents",
+    "uncertain-correction-capture-backlog",
+    "uncertain-instructions-tracking",
+    "uncertain-project-round-worktrees",
+    "uncertain-shared-state-ledger",
+    "uncertain-topic-intent-store",
+    "users-registry",
+    "visibility-guard"
+  ]
+}

package/scripts/bounded-accumulation-wholefile-read-baseline.json

@@ -0,0 +1,5 @@
+{
+  "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": []
+}

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-21T21:13:59.179Z",
-  "instarVersion": "1.3.636",
+  "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.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.