@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/serve/writelock.d.ts

@@ -0,0 +1,22 @@
+/** Longest a write may hold the lock before another process may steal it: a put plus a
+ *  git commit and push — seconds, not minutes. */
+export declare const STALE_AFTER_MS = 60000;
+/** Longest a writer waits before giving up and telling the caller. */
+export declare const ACQUIRE_TIMEOUT_MS = 10000;
+export interface LockOwner {
+    pid: number;
+    host: string;
+    nonce: string;
+    at: string;
+}
+export declare class WriteLockTimeout extends Error {
+    readonly path: string;
+    readonly heldBy: LockOwner | undefined;
+    readonly waitedMs: number;
+    constructor(path: string, heldBy: LockOwner | undefined, waitedMs: number);
+}
+export declare function writeLockPath(hunchDir: string): string;
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+export declare function withWriteLock<T>(hunchDir: string, fn: () => T | Promise<T>, opts?: {
+    timeoutMs?: number;
+}): Promise<T>;

package/dist/store/changeLedger.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { type ChangeEvent, type Scope } from "../core/stateContract.js";
+export declare const LEDGER_SCHEMA_VERSION: "nuryel.ledger/1";
+export declare const CHANGES_DIR = "changes";
+declare const IdempotencyEntrySchema: z.ZodObject<{
+    record_id: z.ZodString;
+    record_hash: z.ZodString;
+    payload_hash: z.ZodOptional<z.ZodString>;
+    facet: z.ZodString;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+}, z.core.$strict>;
+export type IdempotencyEntry = z.infer<typeof IdempotencyEntrySchema>;
+export declare const LedgerSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.ledger/1">;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    head_seq: z.ZodNumber;
+    floor_seq: z.ZodDefault<z.ZodNumber>;
+    events: z.ZodArray<z.ZodObject<{
+        schema: z.ZodLiteral<"nuryel.state.subscribe/1">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        facet: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+            bugs: "bugs";
+            findings: "findings";
+            receipts: "receipts";
+            commitments: "commitments";
+            derived: "derived";
+            entities: "entities";
+            relationships: "relationships";
+        }>;
+        record_id: z.ZodString;
+        record_hash: z.ZodString;
+        change: z.ZodEnum<{
+            updated: "updated";
+            retired: "retired";
+            superseded: "superseded";
+            created: "created";
+            invalidated: "invalidated";
+        }>;
+        subject: z.ZodOptional<z.ZodString>;
+        invalidates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        cause: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"receipt">;
+            receipt_id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"external">;
+            ref: z.ZodObject<{
+                system: z.ZodString;
+                object_type: z.ZodString;
+                object_key: z.ZodString;
+                version: z.ZodOptional<z.ZodString>;
+                content_hash: z.ZodOptional<z.ZodString>;
+                observed_at: z.ZodString;
+                locator: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"write">;
+            principal: z.ZodString;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>;
+    idempotency: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        record_id: z.ZodString;
+        record_hash: z.ZodString;
+        payload_hash: z.ZodOptional<z.ZodString>;
+        facet: z.ZodString;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Ledger = z.infer<typeof LedgerSchema>;
+/** Scope ids may carry `:` `@` `+` (safe in the contract, not in every file system), so
+ *  the file name is the sanitized id plus a short hash of the exact id — readable AND
+ *  collision-free. The scope inside the file is authoritative, the name is a locator. */
+export declare function ledgerFile(hunchDir: string, scope: Scope): string;
+export declare function emptyLedger(scope: Scope): Ledger;
+/** Read the ledger for a scope; a missing file is an empty ledger, a corrupt one is an
+ *  error (never silently treated as empty — that would restart the sequence). */
+export declare function readLedger(hunchDir: string, scope: Scope): Ledger;
+export declare function writeLedger(hunchDir: string, ledger: Ledger): void;
+export type PendingChange = Omit<ChangeEvent, "schema" | "seq" | "at" | "scope">;
+/** Append events (in order) and remember an idempotency key in ONE atomic write, so a
+ *  crash between "record written" and "event appended" can be detected by the next
+ *  writer (record present, ledger silent) rather than producing a half-applied write. */
+export declare function appendChanges(hunchDir: string, scope: Scope, changes: readonly PendingChange[], idempotency: {
+    key: string;
+    entry: Omit<IdempotencyEntry, "seq" | "at">;
+} | null, at?: string, 
+/** Already validated under the same uninterrupted partition lock; batch-local only. */
+current?: Ledger): ChangeEvent[];
+/** The latest seq that touched a record in this scope, or 0 when the ledger never saw it. */
+export declare function latestSeqFor(ledger: Ledger, recordId: string): number;
+/** Keep the newest `keep` events; everything older is dropped and the floor moves up. The
+ *  idempotency table is kept whole (it is what makes replays exact); the records themselves are
+ *  untouched. Returns how many events were dropped. */
+export declare function compactLedger(hunchDir: string, scope: Scope, opts?: {
+    keep?: number;
+}): {
+    dropped: number;
+    floor_seq: number;
+    head_seq: number;
+};
+/** Three-way merge of one scope's ledger, for the git merge driver: two clones that both
+ *  appended to the same partition. The union of events is kept (identity = what changed, to
+ *  which hash, when, by whom), ordered by time then ours-before-theirs, and RE-SEQUENCED from
+ *  the higher floor; every subscriber's cursor is therefore invalid after a merge and the gap
+ *  rule makes it resynchronize. Idempotency entries are unioned; a key both sides used for
+ *  different records is a conflict the caller must surface (ours is kept). */
+export declare function mergeLedgers(base: Ledger | null, ours: Ledger, theirs: Ledger): {
+    ledger: Ledger;
+    conflicts: string[];
+};
+export {};

package/dist/store/changeLedger.js

@@ -10,7 +10,7 @@
  * here (see docs/nuryel-state-contract.md, "Not decided here").
  */
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { writeFileAtomic } from "../core/io.js";
@@ -39,6 +39,12 @@ export const LedgerSchema = z.object({
     events: z.array(ChangeEventSchema),
     idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
 }).strict();
+// Process-local acceleration only: compare the actual bytes on EVERY read, never
+// timestamps or a TTL. Separate processes and same-size replacements stay visible.
+// Keep only four small snapshots; oversized ledgers follow the uncached path.
+const validatedSnapshots = new Map();
+const MAX_CACHED_LEDGERS = 4;
+const MAX_CACHED_CHARACTERS = 1024 * 1024;
 /** Scope ids may carry `:` `@` `+` (safe in the contract, not in every file system), so
  *  the file name is the sanitized id plus a short hash of the exact id — readable AND
  *  collision-free. The scope inside the file is authoritative, the name is a locator. */
@@ -53,10 +59,21 @@ export function emptyLedger(scope) {
 /** Read the ledger for a scope; a missing file is an empty ledger, a corrupt one is an
  *  error (never silently treated as empty — that would restart the sequence). */
 export function readLedger(hunchDir, scope) {
-    const file = ledgerFile(hunchDir, scope);
-    if (!existsSync(file))
+    const file = resolve(ledgerFile(hunchDir, scope));
+    if (!existsSync(file)) {
+        validatedSnapshots.delete(file);
         return emptyLedger(scope);
-    const raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    const text = readFileSync(file, "utf8");
+    const cached = validatedSnapshots.get(file);
+    if (cached?.text === text && cached.scope === scopePath(scope)) {
+        validatedSnapshots.delete(file);
+        validatedSnapshots.set(file, cached);
+        // append/compaction callers mutate their copy. Never expose the cached object.
+        return JSON.parse(cached.normalized);
+    }
+    validatedSnapshots.delete(file);
+    const raw = JSON.parse(text);
     const ledger = LedgerSchema.parse(raw);
     if (scopePath(ledger.scope) !== scopePath(scope))
         throw new Error(`ledger ${file} belongs to scope ${scopePath(ledger.scope)}, not ${scopePath(scope)}`);
@@ -68,18 +85,30 @@ export function readLedger(hunchDir, scope) {
     }
     if (ledger.head_seq !== ledger.floor_seq + ledger.events.length)
         throw new Error(`ledger ${file} head_seq ${ledger.head_seq} disagrees with floor ${ledger.floor_seq} + ${ledger.events.length} events`);
+    if (text.length <= MAX_CACHED_CHARACTERS) {
+        while (validatedSnapshots.size >= MAX_CACHED_LEDGERS)
+            validatedSnapshots.delete(validatedSnapshots.keys().next().value);
+        validatedSnapshots.set(file, { text, normalized: JSON.stringify(ledger), scope: scopePath(scope) });
+    }
     return ledger;
 }
 export function writeLedger(hunchDir, ledger) {
+    writeValidatedLedger(hunchDir, LedgerSchema.parse(ledger));
+}
+function writeValidatedLedger(hunchDir, ledger) {
     const file = ledgerFile(hunchDir, ledger.scope);
     mkdirSync(join(hunchDir, CHANGES_DIR), { recursive: true });
-    writeFileAtomic(file, JSON.stringify(LedgerSchema.parse(ledger), null, 2) + "\n");
+    writeFileAtomic(file, JSON.stringify(ledger, null, 2) + "\n");
 }
 /** Append events (in order) and remember an idempotency key in ONE atomic write, so a
  *  crash between "record written" and "event appended" can be detected by the next
  *  writer (record present, ledger silent) rather than producing a half-applied write. */
-export function appendChanges(hunchDir, scope, changes, idempotency, at = new Date().toISOString()) {
-    const ledger = readLedger(hunchDir, scope);
+export function appendChanges(hunchDir, scope, changes, idempotency, at = new Date().toISOString(), 
+/** Already validated under the same uninterrupted partition lock; batch-local only. */
+current) {
+    const ledger = current ?? readLedger(hunchDir, scope);
+    if (scopePath(ledger.scope) !== scopePath(scope))
+        throw new Error("cached ledger belongs to another scope");
     const appended = [];
     for (const change of changes) {
         const event = ChangeEventSchema.parse({ schema: "nuryel.state.subscribe/1", seq: ledger.head_seq + 1, at, scope, ...change });
@@ -88,9 +117,11 @@ export function appendChanges(hunchDir, scope, changes, idempotency, at = new Da
         appended.push(event);
     }
     if (idempotency) {
-        ledger.idempotency[idempotency.key] = { ...idempotency.entry, seq: ledger.head_seq, at };
+        ledger.idempotency[idempotency.key] = IdempotencyEntrySchema.parse({ ...idempotency.entry, seq: ledger.head_seq, at });
     }
-    writeLedger(hunchDir, ledger);
+    // The initial ledger and each new event/entry are validated; don't re-validate the
+    // full history per assertion. Each append still reaches disk atomically before return.
+    writeValidatedLedger(hunchDir, ledger);
     return appended;
 }
 /** The latest seq that touched a record in this scope, or 0 when the ledger never saw it. */

package/dist/store/compact.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Record compaction (bounds unbounded Hunch growth). Auto-captured drafts
+ * accumulate forever; `hunch compact` prunes the LOW-VALUE ones — never an
+ * accepted/human-confirmed decision, never an open bug, never a constraint
+ * (invariants are sacred), and never a record another record still points to.
+ *
+ * planCompaction is PURE (takes `now`) so it is fully testable; the CLI supplies
+ * Date.now(). Reference safety uses a greatest-fixpoint so records being pruned in
+ * the same pass don't keep each other (or a cycle of dead drafts) alive.
+ */
+import type { Bug, Constraint, Decision, EntityKind } from "../core/types.js";
+export interface CompactionCandidate {
+    kind: EntityKind;
+    id: string;
+    title: string;
+    reason: string;
+}
+export interface CompactionPlan {
+    remove: CompactionCandidate[];
+    /** how many records were considered (decisions + bugs). */
+    considered: number;
+}
+export interface CompactionInput {
+    decisions: Decision[];
+    bugs: Bug[];
+    constraints: Constraint[];
+}
+export interface CompactionOpts {
+    now: number;
+    maxAgeDays?: number;
+    minConfidence?: number;
+}
+export declare function planCompaction(input: CompactionInput, opts: CompactionOpts): CompactionPlan;

package/dist/store/db.d.ts

@@ -0,0 +1,9 @@
+export type DB = import("node:sqlite").DatabaseSync;
+export declare function openDb(sqlitePath: string): DB;
+/** In-memory db (tests / ephemeral queries). */
+export declare function openMemoryDb(options?: {
+    forcePlainSearch?: boolean;
+}): DB;
+/** Run `fn` inside one transaction: BEGIN → fn → COMMIT, ROLLBACK on throw.
+ *  (node:sqlite has no better-sqlite3-style transaction() helper.) */
+export declare function withTx<T>(db: DB, fn: () => T): T;

package/dist/store/embedder.d.ts

@@ -0,0 +1,32 @@
+export interface Embedder {
+    /** Embed each text → an L2-normalized Float32Array of length `dim`. */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    readonly dim: number;
+    /** Stable id; also the `embeddings.model` key, so vectors from different models
+     *  never get compared. */
+    readonly id: string;
+}
+export declare class TransformersEmbedder implements Embedder {
+    readonly dim = 384;
+    readonly id = "all-MiniLM-L6-v2";
+    private extractor;
+    private load;
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+/** Deterministic, dependency-free embedder for tests (no model download).
+ *  Bag-of-token-hashes → L2-normalized vector: shared tokens ⇒ similar vectors,
+ *  enough to exercise hybrid ranking without semantics. Intentionally returns
+ *  SUBARRAY VIEWS into one backing buffer, so any caller that fails to copy
+ *  tightly before persisting will corrupt data — that keeps the BLOB round-trip
+ *  honest. */
+export declare class StubEmbedder implements Embedder {
+    readonly dim: number;
+    readonly id = "stub-v1";
+    constructor(dim?: number);
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+/** Choose an embedder, or null to signal "no semantic search → use pure FTS".
+ *  Never throws. `HUNCH_EMBEDDER=stub` forces the test stub; `=none` forces the
+ *  null (FTS-only) path; otherwise use the local model iff its optional dep is
+ *  installed. */
+export declare function selectEmbedder(): Promise<Embedder | null>;