@davesheffer/hunch 1.31.1 → 1.32.1

package/dist/serve/config.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { type Principal, type Scope } from "../core/stateContract.js";
+export declare const SERVE_CONFIG_VERSION: "nuryel.serve-config/1";
+export declare const PartitionConfigSchema: z.ZodObject<{
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    root: z.ZodString;
+}, z.core.$strict>;
+export type PartitionConfig = z.infer<typeof PartitionConfigSchema>;
+export declare const PrincipalConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        service: "service";
+        human: "human";
+        agent: "agent";
+    }>;
+    display: z.ZodOptional<z.ZodString>;
+    token_sha256: z.ZodString;
+    grants: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PrincipalConfig = z.infer<typeof PrincipalConfigSchema>;
+export declare const ServeConfigSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.serve-config/1">;
+    port: z.ZodDefault<z.ZodNumber>;
+    partitions: z.ZodArray<z.ZodObject<{
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        root: z.ZodString;
+    }, z.core.$strict>>;
+    principals: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            service: "service";
+            human: "human";
+            agent: "agent";
+        }>;
+        display: z.ZodOptional<z.ZodString>;
+        token_sha256: z.ZodString;
+        grants: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ServeConfig = z.infer<typeof ServeConfigSchema>;
+export declare const PARTITION_GITIGNORE: string;
+export declare function hashToken(token: string): string;
+export declare function mintToken(): string;
+export declare function readServeConfig(file: string): ServeConfig & {
+    file: string;
+};
+export declare function writeServeConfig(file: string, config: ServeConfig): void;
+/** Constant-time token → principal. Undefined for a missing or unknown token. */
+export declare function resolvePrincipal(config: ServeConfig, token: string | undefined): Principal | undefined;
+export declare function partitionFor(config: ServeConfig, scope: Scope): PartitionConfig | undefined;
+/** `serve init`: ensure a partition directory declares its scope, and add a principal
+ *  with a freshly minted token. Idempotent for the partition; a principal id that
+ *  already exists gets a NEW token (rotation), the old one stops working. */
+export declare function initServeConfig(opts: {
+    file: string;
+    scope: Scope;
+    root: string;
+    principal?: {
+        id: string;
+        kind: "human" | "agent" | "service";
+        grants?: Scope[];
+    };
+    port?: number;
+}): {
+    config: ServeConfig;
+    token: string | null;
+    partition: PartitionConfig;
+};

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/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>;