@sigloch/graph-api-core 3.0.0 → 3.2.0

package/dist/audit.d.ts

@@ -40,14 +40,64 @@ export interface AuditEntry {
      * at exactly the records it affected.
      */
     rulesetVersion?: string;
+    /**
+     * PROVENANCE (CR-GC-354) — the four fields that make a record answer the base question
+     * of an audit trail: WHO, with WHICH PROMPT, reached WHICH RESULT. The result half was
+     * always there; these are the other two.
+     *
+     * All four are DERIVED at the recording site, never self-declared by the consumer.
+     * `consumerId` is the counter-example that motivated this: it IS a self-declared field
+     * and 40% of the records carry its anonymous default. A prompt a model writes about
+     * itself is a paraphrase — it already contains the interpretation a later consumer
+     * would want to predict — so it is worthless as provenance.
+     *
+     * Session this record was written in — groups the records of ONE conversation.
+     * Assigned by the recording host, not accepted from the caller.
+     */
+    sessionId?: string;
+    /**
+     * The LLM that emitted the commands (e.g. the executor's configured model). The
+     * dimension rule calibration breaks down by ("R-01 dominated rejections: Haiku 26/29,
+     * Opus 17/18, devstral 10/23") and the one a client-side transcript cannot supply for
+     * a local or third-party model, because no transcript exists there.
+     */
+    model?: string;
+    /**
+     * The triggering prompt VERBATIM, truncated by the recording host's policy (the
+     * contract states that it is truncated, the host states where).
+     *
+     * Same absence asymmetry as `rulesPassed`: a missing field means NOT RECORDED, never
+     * "empty prompt". A consumer must not read absence as "no prompt was given".
+     */
+    intent?: string;
+    /**
+     * `true` when `intent` was truncated. Present only in that case — no silent cut, and
+     * no `false` noise on the overwhelming majority of records that fit.
+     */
+    intentTruncated?: boolean;
+}
+/** The read horizon of a query (CR-GC-349). */
+export interface AuditQueryFilter {
+    consumerId?: string;
+    since?: string;
+    limit?: number;
+    /**
+     * Read ARCHIVED segments too, not just the active log (CR-GC-349).
+     *
+     * Compaction archives by rename and deletes nothing, but a plain `query()` reads only the
+     * active file — so the day after the first compaction an aggregation over the trail reports
+     * a near-empty window while the full evidence sits untouched beside it. That is worse than a
+     * missing measurement: it is a WRONG one shaped like a result.
+     *
+     * Off by default on purpose. OCC calls `query({})` on the WRITE path and only needs the
+     * batches since a fork point, so pulling archives in there would be a slowdown with no
+     * consumer. Analysis surfaces (audit_trail / audit_stats) turn it on.
+     */
+    includeArchived?: boolean;
 }
 export interface AuditLog {
     record(entry: AuditEntry): Promise<void>;
-    query(filter: {
-        consumerId?: string;
-        since?: string;
-        limit?: number;
-    }): Promise<AuditEntry[]>;
+    query(filter: AuditQueryFilter): Promise<AuditEntry[]>;
 }
 /**
  * The durable operations-log surface: append/query (AuditLog) plus the event-
@@ -68,15 +118,18 @@ export interface OperationsLog extends AuditLog {
         archivedTo: string | null;
         checkpointVersion: number;
     };
+    /**
+     * The archived segments beside the active log, oldest first (CR-GC-349).
+     *
+     * So an answer can SAY what it did not read instead of silently omitting it — the same rule
+     * as "no silent cap" on the projection side.
+     */
+    archives(): string[];
 }
 export declare class InMemoryAuditLog implements AuditLog {
     private entries;
     record(entry: AuditEntry): Promise<void>;
-    query(filter: {
-        consumerId?: string;
-        since?: string;
-        limit?: number;
-    }): Promise<AuditEntry[]>;
+    query(filter: AuditQueryFilter): Promise<AuditEntry[]>;
 }
 /** Auto-compaction size threshold (bytes). */
 export declare const DEFAULT_COMPACT_BYTES: number;
@@ -96,11 +149,7 @@ export declare class FileOperationsLog implements OperationsLog {
     });
     record(entry: AuditEntry): Promise<void>;
     /** Mirrors InMemoryAuditLog semantics: `since` inclusive, `limit` = last N. */
-    query(filter: {
-        consumerId?: string;
-        since?: string;
-        limit?: number;
-    }): Promise<AuditEntry[]>;
+    query(filter: AuditQueryFilter): Promise<AuditEntry[]>;
     /** The compaction anchor: checkpoint version, or 0 on a never-compacted log. */
     baseVersion(): number;
     /**
@@ -122,4 +171,22 @@ export declare class FileOperationsLog implements OperationsLog {
     /** Read all parseable lines; skip a torn tail (crash mid-append) with a warning. */
     private readLines;
     private readEntries;
+    /**
+     * Archived segments beside the active log, OLDEST FIRST (CR-GC-349).
+     *
+     * Sorted by (stamp, collision counter) and NOT lexically. Lexical order looks right and is
+     * wrong exactly where it matters: `-` (0x2D) sorts before `.` (0x2E), so a collision-suffixed
+     * `…-329Z-1.jsonl` would come out BEFORE the `…-329Z.jsonl` it followed, silently inverting
+     * the replay order of two adjacent segments. The unsuffixed name is counter 0 because it was
+     * written first.
+     */
+    archives(): string[];
+    /**
+     * Every entry across the archives AND the active log, in log order (CR-GC-349).
+     *
+     * An unreadable archive is SKIPPED, not fatal: the same torn-tail tolerance the active log
+     * already has. An analysis must not die on a years-old segment — losing part of the horizon
+     * is a gap, losing the answer is a defect.
+     */
+    private readAllEntries;
 }

package/dist/audit.js

@@ -16,7 +16,7 @@
  * survives every compaction, and torn-tail tolerant so a crash mid-append is a
  * skipped line, never a read failure.
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 export class InMemoryAuditLog {
     entries = [];
@@ -63,7 +63,7 @@ export class FileOperationsLog {
     }
     /** Mirrors InMemoryAuditLog semantics: `since` inclusive, `limit` = last N. */
     async query(filter) {
-        let result = this.readEntries();
+        let result = filter.includeArchived ? this.readAllEntries() : this.readEntries();
         if (filter.consumerId)
             result = result.filter(e => e.consumerId === filter.consumerId);
         if (filter.since)
@@ -102,7 +102,16 @@ export class FileOperationsLog {
             return { archivedTo: null, checkpointVersion: 0 };
         const version = this.latestVersion();
         const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-        const archive = this.path.replace(/\.jsonl$/, `-${stamp}.jsonl`);
+        // COLLISION GUARD (CR-GC-349). The stamp resolves to milliseconds, and `renameSync`
+        // overwrites its target silently — so two compactions inside the same millisecond used to
+        // destroy the earlier archive. Measured before the guard: 30 records written, 14 left on
+        // disk. That is data loss inside the one function whose contract is "deletes nothing";
+        // unreachable at the 10 MB default, reachable with a small `maxBytes` or concurrent binds,
+        // and exactly the shape of bug that stays invisible because the promise reads as kept.
+        let archive = this.path.replace(/\.jsonl$/, `-${stamp}.jsonl`);
+        for (let n = 1; existsSync(archive); n++) {
+            archive = this.path.replace(/\.jsonl$/, `-${stamp}-${n}.jsonl`);
+        }
         renameSync(this.path, archive);
         const cp = { checkpoint: true, version, timestamp: new Date().toISOString(), reason };
         writeFileSync(this.path, JSON.stringify(cp) + '\n', 'utf8');
@@ -142,4 +151,61 @@ export class FileOperationsLog {
     readEntries() {
         return this.readLines().filter((l) => !isCheckpoint(l));
     }
+    /**
+     * Archived segments beside the active log, OLDEST FIRST (CR-GC-349).
+     *
+     * Sorted by (stamp, collision counter) and NOT lexically. Lexical order looks right and is
+     * wrong exactly where it matters: `-` (0x2D) sorts before `.` (0x2E), so a collision-suffixed
+     * `…-329Z-1.jsonl` would come out BEFORE the `…-329Z.jsonl` it followed, silently inverting
+     * the replay order of two adjacent segments. The unsuffixed name is counter 0 because it was
+     * written first.
+     */
+    archives() {
+        const dir = dirname(this.path);
+        const base = AUDIT_BASENAME.replace(/\.jsonl$/, '');
+        const pattern = new RegExp(`^${base}-(.+?)(?:-(\\d+))?\\.jsonl$`);
+        try {
+            return readdirSync(dir)
+                .flatMap(f => {
+                const m = pattern.exec(f);
+                return m ? [{ file: f, stamp: m[1], n: m[2] ? Number(m[2]) : 0 }] : [];
+            })
+                .sort((a, b) => (a.stamp < b.stamp ? -1 : a.stamp > b.stamp ? 1 : a.n - b.n))
+                .map(a => join(dir, a.file));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Every entry across the archives AND the active log, in log order (CR-GC-349).
+     *
+     * An unreadable archive is SKIPPED, not fatal: the same torn-tail tolerance the active log
+     * already has. An analysis must not die on a years-old segment — losing part of the horizon
+     * is a gap, losing the answer is a defect.
+     */
+    readAllEntries() {
+        const out = [];
+        for (const archive of this.archives()) {
+            try {
+                for (const line of readFileSync(archive, 'utf8').split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (!isCheckpoint(parsed))
+                            out.push(parsed);
+                    }
+                    catch {
+                        // torn line in an archive — skip, same as the active log
+                    }
+                }
+            }
+            catch {
+                // unreadable archive — skip the segment, keep the answer
+            }
+        }
+        out.push(...this.readEntries());
+        return out;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,11 +21,11 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "@sigloch/contracts": "^4.0.0",
+    "@sigloch/contracts": "^4.1.0",
     "zod": "^4.3.6"
   },
   "license": "MIT",
-  "description": "Framework-agnostic graph engine core \u2014 ontology-typed nodes/traces, rule evaluation, views",
+  "description": "Framework-agnostic graph engine core — ontology-typed nodes/traces, rule evaluation, views",
   "author": "sigloch-consulting",
   "repository": {
     "type": "git",