@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/store/jsonStore.d.ts

@@ -0,0 +1,125 @@
+import type { HunchPaths } from "../core/paths.js";
+import { type EntityKind, type EntityFor } from "../core/types.js";
+/** Curated entities are intentionally small, human-reviewable records. Symbols
+ * and edges are dense indexes, so they get a much larger but still finite cap. */
+export declare const MAX_JSON_RECORD_BYTES: number;
+export declare const MAX_JSON_INDEX_BYTES: number;
+export declare const MAX_JSON_MANIFEST_BYTES: number;
+export declare const MAX_JSON_DIRECTORY_ENTRIES_PER_KIND = 100000;
+export declare class JsonStore {
+    private readonly paths;
+    private _warnedForward;
+    /** Memoized validated records per kind. loadAll() is on every read-path method
+     *  (why/checkConstraints/fragility/assembleContext…), each of which previously
+     *  re-read the directory and re-ran Zod over every record. Cache keyed by the
+     *  kind dir's mtime: every write goes through writeFileAtomic (temp + rename) or
+     *  rmSync, both of which bump the dir mtime — so an OUT-OF-BAND write by another
+     *  process self-invalidates on the next read. In-process writes also invalidate
+     *  explicitly (exact, independent of mtime granularity). */
+    private cache;
+    private readonly lexicalRoot;
+    private readonly canonicalRoot;
+    private readonly lexicalHunch;
+    constructor(paths: HunchPaths);
+    private lstatOrMissing;
+    private expectedCanonical;
+    /** Require an ordinary, canonically-contained directory. Creation is one
+     * component at a time after its parent has been validated; recursive mkdir
+     * would otherwise traverse a malicious pre-existing symlink. */
+    private safeDirectory;
+    private safeHunchDirectory;
+    private assertKind;
+    private safeKindDirectory;
+    private maxBytes;
+    private assertSafeRecordId;
+    private assertFileBelongsTo;
+    private validateExistingFile;
+    /** Read through the exact descriptor whose type, identity, containment, and
+     * finite size were checked. Returning null means the file is absent. */
+    private readContainedFile;
+    private writeContainedFile;
+    private removeContainedFile;
+    private jsonFileNames;
+    /** Drop memoized loadAll results. Writes through this store invalidate the
+     *  affected kind automatically; call this for OUT-OF-BAND changes to .hunch/
+     *  JSON (e.g. the long-lived MCP server reacting to a file-watch, or after an
+     *  external `hunch migrate`). */
+    clearCache(): void;
+    /** Cheap revision marker for the JSON source tree. Hunch writes records with
+     *  temp-file + rename, so every supported add/update/delete bumps the containing
+     *  kind directory's metadata. Include the manifest separately because a schema
+     *  migration can change how otherwise-identical record bytes are interpreted.
+     *  This lets long-lived readers notice another process without hashing or
+     *  reparsing the complete graph on every request. */
+    changeStamp(): string;
+    private invalidate;
+    /** Create .hunch/<kind>/ directories. Stamp the manifest at the CURRENT version
+     *  only when scaffolding a FRESH .hunch/ (so `hunch index`/`sync` on a brand-new
+     *  repo records the version too, not just `init`). A pre-existing .hunch/ without
+     *  a manifest is LEGACY — left unstamped so it defaults to the baseline and
+     *  `hunch migrate` upgrades it. */
+    ensureDirs(): void;
+    /** The on-disk schema version (from the manifest), read FRESH each call so a
+     *  long-lived process (the MCP server) reflects an out-of-band `hunch migrate`. */
+    schemaVersion(): number;
+    /** Migrate one raw record UP to the current schema before validation, so a
+     *  schema bump never makes the loader silently skip (drop) old records. The
+     *  on-disk `version` is read ONCE per load (not per record) by the caller. */
+    private migrate;
+    private fileFor;
+    /** Load every record of a kind, validated against its schema. Memoized — the
+     *  returned array is shared and MUST be treated read-only (every caller already
+     *  derives via filter/map/sort, which copy). Invalidated on write. */
+    loadAll<K extends EntityKind>(kind: K): EntityFor[K][];
+    /** Uncached disk read + validate. Invalid records are skipped with a warning
+     *  rather than crashing the whole load. */
+    private readAllFromDisk;
+    /** Cross-process mutex for single-file index read-modify-write (issue #35).
+     *  The long-lived MCP server and CLI hooks write the same `.hunch/` concurrently;
+     *  two unsynchronized RMWs over index.json each read the same base array and the
+     *  second rename silently erases the first's record. `mkdirSync` is the atomic
+     *  acquire (EEXIST = held). A stale lock (killed process) is taken over by age;
+     *  against a live contender we wait briefly and then proceed WITH a warning —
+     *  never worse than the historical lockless behavior, and capture paths must not
+     *  start throwing on lock contention. */
+    private withSingleFileLock;
+    /** Write a single record (validated) to its JSON file / into the index array. */
+    put<K extends EntityKind>(kind: K, record: EntityFor[K]): EntityFor[K];
+    /** Bulk replace all records of a kind (used by the extractor for symbols/edges). */
+    replaceAll<K extends EntityKind>(kind: K, records: EntityFor[K][]): void;
+    /** Read a single-file index as a raw array (no validation). Missing/empty → [].
+     *  A non-empty file that fails to parse THROWS — we must never silently treat a
+     *  corrupt index as empty and then rewrite it, which would flatten every existing
+     *  record. (`hunch index` rebuilds from scratch via replaceAll to recover.) */
+    private readRawArray;
+    get<K extends EntityKind>(kind: K, id: string): EntityFor[K] | undefined;
+    /** Direct authoritative state lookup. No directory enumeration or stale cache;
+     * migration precedes validation and corrupt files fail closed. */
+    getDirect<K extends "derived" | "receipts" | "commitments">(kind: K, id: string): EntityFor[K] | undefined;
+    /** On-disk record count, independent of validation: per-record kinds count
+     *  every non-tombstone .json file (a 0-byte merge tombstone is an intentional
+     *  absence), single-file kinds count raw array entries (a corrupt index file
+     *  throws readRawArray's own actionable refusal). Lets a caller about to
+     *  DELETE the kind — `hunch private --migrate` — prove the validating loader
+     *  dropped nothing first, instead of silently destroying the records loadAll
+     *  skipped (issue #29, the same never-silently-drop contract as
+     *  con_947c578b2c). */
+    rawRecordCount(kind: EntityKind): number;
+    /** Remove a record (used by the curate/reject flow). Returns true if removed.
+     *  For single-file kinds we operate on the RAW JSON array (not the validating
+     *  loader) so deleting one record can't silently drop schema-invalid siblings. */
+    delete<K extends EntityKind>(kind: K, id: string): boolean;
+    /** Remove EVERY record of a kind from disk (the kind dir's JSON files), keeping
+     *  the dir itself so the layout/manifest survive. Used by `hunch private --migrate`
+     *  to empty the PUBLIC store after its records have been moved into the private
+     *  overlay. Returns the number of files removed. Invalidates the memoized load. */
+    dropAll(kind: EntityKind): number;
+    /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
+     *  A record that still fails validation after migration is kept untouched (never
+     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
+     *  bumps the manifest afterward. */
+    persistMigration(): {
+        migrated: number;
+        skipped: number;
+    };
+}

package/dist/store/merge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Structured three-way merge of `.hunch/` JSON for TEAM workflows.
+ *
+ * Concurrent branches both writing the Hunch conflict on `git merge`: the
+ * single-file symbols/edges index is rewritten wholesale by `hunch index`, and two
+ * people can touch the same decision/bug/constraint. A registered git merge driver
+ * (`hunch merge-driver`, wired up by `hunch init`) calls mergeHunchJson per
+ * conflicted file so records merge BY ID instead of leaving conflict markers.
+ *
+ * Scope: git only invokes a content merge driver when the SAME path differs on both
+ * sides — so this resolves (a) the symbols/edges index ARRAY and (b) edits to the
+ * same id in the same per-record file. Per-record ADD/DELETE across branches are
+ * distinct files and git handles them at the tree level (the driver isn't called).
+ *
+ * Resolution for a record changed on BOTH sides: human-confirmed beats auto, then
+ * higher provenance.confidence, then the more recently verified, then a deterministic
+ * content tiebreak (so both developers' merges converge on the same result). Records
+ * are pure data here — no filesystem access; the CLI reads/writes the files.
+ */
+type Rec = Record<string, unknown>;
+export interface MergeResult {
+    text: string;
+    /** true → could not structurally merge (corrupt JSON / id-less records); the
+     *  caller should fall back to git's normal conflict handling. */
+    conflict: boolean;
+}
+/** Merge three versions of one `.hunch` JSON file (an index array OR a single
+ *  record object). Returns the merged text, or conflict=true to fall back. */
+export declare function mergeHunchJson(baseText: string, oursText: string, theirsText: string): MergeResult;
+/** Three-way merge of record arrays keyed by `id`. Additions on either side are
+ *  kept; a record changed on one side only takes that side; a delete is honored
+ *  only if the other side left the record unchanged (a modification beats a delete);
+ *  a both-sides change is resolved by `pickWinner`. */
+export declare function mergeRecordsById(base: Rec[], ours: Rec[], theirs: Rec[]): Rec[];
+/** Both sides changed the same record: pick the one to keep. */
+export declare function pickWinner(ours: Rec, theirs: Rec): Rec;
+/** Stable JSON with recursively SORTED keys, so equality/compare ignore key order. */
+export declare function canon(v: unknown): string;
+export {};

package/dist/store/privateMigrate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Move a repo's PUBLIC engineering memory into its PRIVATE overlay, for
+ * `hunch private --migrate` (turn a public-by-default repo into a code-only public
+ * repo whose memory lives in a separate private store).
+ *
+ * The merge is a UNION BY ID: every public record is absorbed into the private
+ * store, and a record that already exists on both sides (e.g. a decision present
+ * in both) is resolved by the same precedence the merge driver uses (human-confirmed
+ * › higher confidence › more recent › deterministic tiebreak). Private-only records
+ * are preserved untouched. This NEVER deletes from the public store — the CLI empties
+ * it separately (JsonStore.dropAll) only after this returns, so an interrupted move
+ * can't lose records.
+ */
+import { type EntityKind } from "../core/types.js";
+import type { JsonStore } from "./jsonStore.js";
+export interface MoveResult {
+    /** Per-kind count of public records absorbed into the overlay. */
+    moved: Partial<Record<EntityKind, number>>;
+    /** Total public records absorbed. */
+    total: number;
+}
+/** Union every public record into `priv` (by id). Returns what was absorbed.
+ *  Idempotent: re-running with the same input rewrites identical content. */
+export declare function movePublicMemoryToPrivate(pub: JsonStore, priv: JsonStore): MoveResult;

package/dist/store/replay.d.ts

@@ -0,0 +1,56 @@
+import { type Scope, type StateFacet, type ChangeEvent } from "../core/stateContract.js";
+import { type Ledger } from "./changeLedger.js";
+import type { HunchStore } from "./hunchStore.js";
+export declare const REPLAY_SCHEMA_VERSION: "nuryel.replay/1";
+/** The facets the contract is the ONLY writer of; a record here without a ledger event is an orphan. */
+export declare const STATE_ONLY_FACETS: readonly ["receipts", "commitments", "derived", "entities", "relationships"];
+export type ReplayDivergenceKind = "missing-record" | "hash-drift" | "orphan-record" | "idempotency-drift" | "legacy-drift";
+export interface ReplayDivergence {
+    kind: ReplayDivergenceKind;
+    facet: StateFacet;
+    record_id: string;
+    /** The seq of the ledger event the record was checked against (0 when none). */
+    seq: number;
+    expected_hash: string | null;
+    actual_hash: string | null;
+    detail: string;
+}
+/** One line per record the fold produced: the state the ledger implies. Sorted by id, so the
+ *  snapshot hash is order-independent and two clones of one ledger agree on it. */
+export interface ReplaySnapshotEntry {
+    facet: StateFacet;
+    record_id: string;
+    record_hash: string;
+    /** The last change the ledger recorded for it. */
+    change: ChangeEvent["change"];
+    seq: number;
+}
+export interface ReplayReport {
+    schema: typeof REPLAY_SCHEMA_VERSION;
+    scope: Scope;
+    ledger: {
+        head_seq: number;
+        floor_seq: number;
+        events: number;
+        idempotency_entries: number;
+    };
+    /** Hash of the state the ledger implies (the fold) and of the records on file for the same ids —
+     *  over the facets the contract owns (legacy facets are advisory and excluded). */
+    replay_hash: string;
+    stored_hash: string;
+    records: {
+        named_by_ledger: number;
+        verified: number;
+        verified_by_idempotency: number;
+        unverifiable: number;
+        legacy_checked: number;
+    };
+    divergences: ReplayDivergence[];
+    /** True when the ledger and the files agree on every record the check can decide. */
+    ok: boolean;
+}
+/** Fold a ledger into the state it implies: the last event per record, in seq order. */
+export declare function foldLedger(ledger: Ledger): Map<string, ReplaySnapshotEntry>;
+/** Verify that a partition's stored records are exactly what its ledger implies. Read-only. */
+export declare function verifyReplay(store: HunchStore, scope: Scope): ReplayReport;
+export declare function formatReplayReport(r: ReplayReport): string;

package/dist/store/schema.d.ts

@@ -0,0 +1,17 @@
+/** Canonical content hash of the exact title+body that fed both FTS and the
+ *  embedding for a doc. Stored in `embeddings.doc_hash` so reindex can tell, with
+ *  NO model loaded, whether a stored vector is stale (its source text changed).
+ *  The NUL separator keeps the title/body boundary unambiguous. Reuses the shared
+ *  sha1-truncate idiom from core/ids so the hashing scheme lives in one place. */
+export declare function embedHash(title: string, body: string): string;
+export declare const SCHEMA_SQL = "\nPRAGMA journal_mode = WAL;\nPRAGMA foreign_keys = OFF;\n\nCREATE TABLE IF NOT EXISTS components (\n  id TEXT PRIMARY KEY,\n  kind TEXT, name TEXT, responsibility TEXT,\n  paths TEXT, status TEXT, owners TEXT,\n  fragility REAL,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,\n  created_at TEXT, updated_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS resources (\n  id TEXT PRIMARY KEY,\n  schema TEXT, kind TEXT, name TEXT, scope TEXT, locator TEXT,\n  lifecycle TEXT, criticality TEXT, contract_version TEXT,\n  currentness TEXT, metadata TEXT,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,\n  created_at TEXT, updated_at TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_resources_kind ON resources(kind);\nCREATE INDEX IF NOT EXISTS idx_resources_lifecycle ON resources(lifecycle);\n\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  \"from\" TEXT, \"to\" TEXT, type TEXT, reason TEXT, strength REAL,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_edges_from ON edges(\"from\");\nCREATE INDEX IF NOT EXISTS idx_edges_to ON edges(\"to\");\nCREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);\n\n-- A rebuildable projection over the subset of the existing edge graph carrying\n-- the resource-relationship contract. JSON edges remain the one authority.\nCREATE TABLE IF NOT EXISTS resource_relationships (\n  id TEXT PRIMARY KEY,\n  schema TEXT, \"from\" TEXT, \"to\" TEXT, type TEXT, reason TEXT, strength REAL,\n  currentness TEXT, environment TEXT, criticality TEXT, contract_version TEXT,\n  metadata TEXT, prov_source TEXT, prov_confidence REAL, prov_evidence TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_resource_relationships_from ON resource_relationships(\"from\");\nCREATE INDEX IF NOT EXISTS idx_resource_relationships_to ON resource_relationships(\"to\");\nCREATE INDEX IF NOT EXISTS idx_resource_relationships_type ON resource_relationships(type);\n\nCREATE TABLE IF NOT EXISTS symbols (\n  id TEXT PRIMARY KEY,\n  file TEXT, name TEXT, kind TEXT, signature_hash TEXT,\n  calls TEXT, called_by TEXT,\n  loc INTEGER, churn_90d INTEGER, bug_count INTEGER, fan_in INTEGER, fan_out INTEGER,\n  last_changed TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);\nCREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);\n\nCREATE TABLE IF NOT EXISTS decisions (\n  id TEXT PRIMARY KEY,\n  title TEXT, status TEXT, context TEXT, decision TEXT,\n  consequences TEXT, alternatives_rejected TEXT,\n  related_components TEXT, related_files TEXT,\n  supersedes TEXT, caused_by_bug TEXT, \"commit\" TEXT,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,\n  date TEXT\n);\n\nCREATE TABLE IF NOT EXISTS bugs (\n  id TEXT PRIMARY KEY,\n  title TEXT, symptom TEXT, root_cause TEXT, severity TEXT, status TEXT,\n  affected_files TEXT, affected_symbols TEXT, lineage TEXT,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT\n);\n\nCREATE TABLE IF NOT EXISTS constraints (\n  id TEXT PRIMARY KEY,\n  type TEXT, statement TEXT, scope TEXT, severity TEXT, enforcement TEXT,\n  rationale TEXT, source_decision TEXT, violations TEXT,\n  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT\n);\n\n-- Local semantic-search vectors (opt-in; written by `hunch embed`). One row per\n-- (ref, model); vec is a Float32 BLOB. DELIBERATELY NOT in RESET_SQL: reindex()\n-- runs RESET on nearly every path (MCP startup, every query/context), so resetting\n-- embeddings here would wipe them constantly and make the feature a no-op. Staleness\n-- is tracked by doc_hash and reconciled by pruneStaleEmbeddings() instead. Recall is\n-- exact brute-force cosine in JS (graphs are small); sqlite-vec only past ~100k rows.\nCREATE TABLE IF NOT EXISTS embeddings (\n  ref TEXT, kind TEXT, model TEXT, dim INTEGER, doc_hash TEXT, vec BLOB,\n  PRIMARY KEY (ref, model)\n);\n";
+/** Preferred search table when the host SQLite build includes FTS5. Kept
+ * separate from SCHEMA_SQL so a missing optional SQLite module cannot prevent
+ * deterministic graph/constraint operations from opening the derived index. */
+export declare const FTS_SEARCH_SCHEMA_SQL = "\nCREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(\n  ref UNINDEXED,   -- entity id\n  kind UNINDEXED,  -- components | resources | edges | symbols | decisions | bugs | constraints | runbooks | findings\n                   -- | receipts | commitments | derived | entities | relationships (nuryel.state/1; title = subject key)\n  title,\n  body,\n  tokenize = 'porter unicode61'\n);\n";
+/** Portable keyword-search fallback. HunchStore detects that MATCH/bm25 are
+ * unavailable and performs a bounded LIKE scan over the same four columns. */
+export declare const PLAIN_SEARCH_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS search (\n  ref TEXT,\n  kind TEXT,\n  title TEXT,\n  body TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_search_ref ON search(ref);\nCREATE INDEX IF NOT EXISTS idx_search_kind ON search(kind);\n";
+/** Drop derived data (used before a full reindex). NOTE: embeddings is omitted on
+ *  purpose — see the embeddings table comment above. */
+export declare const RESET_SQL = "\nDELETE FROM components; DELETE FROM resources; DELETE FROM edges; DELETE FROM resource_relationships; DELETE FROM symbols;\nDELETE FROM decisions; DELETE FROM bugs; DELETE FROM constraints;\nDELETE FROM search;\n";

package/dist/store/stateBinding.d.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import type { HunchStore } from "./hunchStore.js";
+import { readLedger } from "./changeLedger.js";
+import { type DeliveryEnvelope } from "../core/delivery.js";
+import { STATE_CONTRACT_VERSION, type Scope, type ReadResponse, type WriteResult, type RecordsResponse } from "../core/stateContract.js";
+/** A typed refusal. `code` is stable for bindings; `conflict` names the incumbent when one exists. */
+export declare class StateRefusal extends Error {
+    readonly code: "outside-grants" | "unsupported" | "malformed" | "identity" | "conflict" | "no-partition-home" | "idempotency";
+    readonly conflict: {
+        incumbent_id: string;
+        reason: string;
+    } | null;
+    constructor(code: "outside-grants" | "unsupported" | "malformed" | "identity" | "conflict" | "no-partition-home" | "idempotency", message: string, conflict?: {
+        incumbent_id: string;
+        reason: string;
+    } | null);
+}
+/** The partition this store IS. A served partition declares itself in `.hunch/partition.json`
+ *  (`{ kind, id }`, committed with the store); a plain checkout is the repository partition
+ *  named after its directory, sanitized to the contract's token grammar — stable per clone,
+ *  discoverable through `capabilities`, and the scope every legacy record defaults to. */
+export declare function partitionOf(store: HunchStore): Scope;
+/** @deprecated name kept for callers written before served partitions; same value as partitionOf. */
+export declare const repositoryScope: typeof partitionOf;
+export declare const SubscribeResponseSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.state.subscribe/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;
+    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>>;
+    filtered: z.ZodBoolean;
+    floor_seq: z.ZodDefault<z.ZodNumber>;
+    resync: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type SubscribeResponse = z.infer<typeof SubscribeResponseSchema>;
+export declare function capabilities(store: HunchStore): {
+    protocol: typeof STATE_CONTRACT_VERSION;
+    capabilities: string[];
+    repository: Scope;
+    partitions: Scope["kind"][];
+};
+/** Where a scope's records and ledger live in this store (exported for the replay check, which
+ *  must read the SAME home the write verb wrote — never a second routing rule). */
+export declare function stateHomeFor(store: HunchStore, scope: Scope): {
+    home: "public" | "private";
+    hunchDir: string;
+    isPrivate: boolean;
+};
+/** read — the system-of-record answer for a subject, under the delivery envelope's receipt.
+ *  Grants are the first predicate on every candidate; a matching record in a scope the
+ *  principal lacks is NAMED in denied_scopes and never described. */
+export declare function readState(store: HunchStore, input: unknown): {
+    response: ReadResponse;
+    envelope: DeliveryEnvelope;
+};
+/** Union read — one state_of_record across several partitions, each read by `readState` against
+ *  its own store. Pure: no store, no grants decided here (every input already passed its own
+ *  grant check). The primary's receipt, scope and envelope lead; refs concatenate (each already
+ *  carries its partition), `depends_on` concatenates, `invalidated_by` is a sorted union, `records`
+ *  merge by id (first writer wins — ids are identity, two copies are the same record),
+ *  `denied_scopes` is the union of every partition's denied plus `extraDenied` (requested-but-
+ *  ungranted scopes the host refused to open), `scopes` names the partitions read and `receipts`
+ *  carries one delivery receipt per partition. Reusable by any host (HTTP today; MCP or CLI
+ *  fronting several roots later). */
+export declare function mergeReadResponses(primary: ReadResponse, others: readonly ReadResponse[], extraDenied?: readonly Scope[]): ReadResponse;
+export interface WriteOptions {
+    /** Internal batch owner rebuilds once in finally while holding the write lock. */
+    deferReindex?: boolean;
+    /** Internal cache scoped to one uninterrupted partition write lock. Never retained. */
+    ledgerCache?: {
+        ledger?: ReturnType<typeof readLedger>;
+    };
+    /** Durability step after the record is on disk (auto-commit / push). Absent = "local". */
+    flush?: (isPrivate: boolean, message: string) => "pushed" | "committed" | null;
+    now?: () => Date;
+}
+/** write — provenance + idempotency in, durability out. A replay returns the original;
+ *  a conflict names the incumbent; nothing is ever silently overwritten or duplicated. */
+export declare function writeState(store: HunchStore, input: unknown, opts?: WriteOptions): WriteResult;
+/** subscribe — the scope's ordered change stream after a cursor. Unfiltered, the events are
+ *  contiguous and assertChangeSequence holds; filtered, `head_seq` is still the cursor. */
+export declare function subscribeState(store: HunchStore, input: unknown): SubscribeResponse;
+/** records — fetch by id, grants first. Every id is accounted for: found, denied (its scope is
+ *  outside the grants — named, never described) or missing. */
+export declare function recordsState(store: HunchStore, input: unknown): RecordsResponse;

package/dist/store/stateCapture.d.ts

@@ -0,0 +1,15 @@
+import type { HunchStore } from "./hunchStore.js";
+import { type CaptureBatchResult, type WriteResult } from "../core/stateContract.js";
+import { type WriteOptions } from "./stateBinding.js";
+interface CaptureOptions extends WriteOptions {
+    sourceHashes?: Map<string, string>;
+}
+/** The caller selects relevant atomic claims; this deterministic boundary checks evidence
+ * fidelity and deduplication. It does not pretend to prove semantic entailment or relevance.
+ * Both bindings hold the partition write lock over lookup AND write. */
+export declare function captureState(store: HunchStore, input: unknown, opts?: CaptureOptions): WriteResult;
+/** Bounded partial-success batch. The caller holds the same partition lock as writeState.
+ * Every result has its input index; a refused claim never hides a later valid new detail.
+ * A duplicate-only batch performs no record, ledger, index or Git writes. */
+export declare function captureBatchState(store: HunchStore, input: unknown, opts?: WriteOptions): CaptureBatchResult;
+export {};

package/dist/synthesis/cliAdapter.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+declare const adapterSchema: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    protocol: z.ZodEnum<{
+        stdin: "stdin";
+        acp: "acp";
+    }>;
+    probe_args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentCliAdapter = z.infer<typeof adapterSchema>;
+export interface AgentCliWorker {
+    name: string;
+    draftProse?(prompt: string): Promise<string>;
+}
+export declare function readAgentCliConfig(file: string): AgentCliAdapter[];
+/** ACP (Kimi and other agents) or plain stdin → JSON stdout for any user-configured CLI. */
+export declare function runAgentCli(adapterInput: AgentCliAdapter, prompt: string): Promise<string>;
+export declare function discoverAgentClis(configured?: AgentCliAdapter[], initiator?: string): AgentCliWorker[];
+export {};

package/dist/synthesis/initiator.d.ts

@@ -0,0 +1,13 @@
+export interface AgentInitiator {
+    provider: string | null;
+    source: "explicit" | "environment" | "client" | "unknown" | "ambiguous";
+}
+export declare function normalizeInitiator(name: string): string;
+export declare function detectInitiator(env?: NodeJS.ProcessEnv): AgentInitiator;
+export declare function currentInitiator(env?: NodeJS.ProcessEnv): AgentInitiator;
+export declare function withInitiator<T>(initiator: AgentInitiator, work: () => T): T;
+/** Bind the MCP client, not the process that happened to start the server. Unknown clients stay unknown. */
+export declare function initiatorFromClient(name: string | undefined): AgentInitiator;
+/** Freeze the operation's origin before spawning Git hooks or other deferred children. */
+export declare function initiatorChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function assertInitiatorProvider(provider: string): void;