@davesheffer/hunch 1.32.8 → 1.33.0

package/dist/store/hunchStore.js

@@ -518,20 +518,20 @@ export class HunchStore {
      *  relevance ordering (liveness/provenance/recency + topic-chain promotion)
      *  go through hybridSearch/searchScoped, where rerankByPriors applies.
      *  Falls back to LIKE if the query has no FTS-tokenizable terms. */
-    search(query, limit = 12) {
+    search(query, limit = 12, allowedIds) {
         const match = toFtsQuery(query);
         // No FTS-tokenizable terms (e.g. a CJK-only query) — degrade to LIKE rather
         // than silently returning nothing (the documented fallback).
         if (!match)
-            return this.likeSearch(query, limit);
+            return this.likeSearch(query, limit, undefined, allowedIds);
         try {
             const rows = this.db.prepare(`SELECT ref, kind, title, snippet(search, 3, '[', ']', '…', 12) AS snip, bm25(search) AS score
-         FROM search WHERE search MATCH ? ORDER BY score LIMIT ?`).all(match, limit);
+         FROM search WHERE search MATCH ? ${allowedIds ? 'AND ref IN (SELECT value FROM json_each(?))' : ''} ORDER BY score LIMIT ?`).all(...(allowedIds ? [match, JSON.stringify(allowedIds), limit] : [match, limit]));
             return this.demoteHistoricalState(rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score })));
         }
         catch {
             // Malformed FTS expression — degrade to a LIKE scan over titles/bodies.
-            return this.likeSearch(query, limit);
+            return this.likeSearch(query, limit, undefined, allowedIds);
         }
     }
     /** State-of-record ordering for nuryel.state/1 hits (superseded derived, done/cancelled
@@ -635,7 +635,7 @@ export class HunchStore {
      * `hunchrecorddecision` and matched nothing — on precisely the runtimes with no FTS5,
      * where this fallback is the only search there is. Escaping keeps the term literal;
      * leaving `_` unescaped would silently over-match instead. */
-    likeSearch(query, limit, kind) {
+    likeSearch(query, limit, kind, allowedIds) {
         const terms = (query.toLowerCase().match(/[\p{L}\p{N}_]+/gu)
             ?? [query.toLowerCase().trim()].filter(Boolean)).slice(0, 32);
         if (!terms.length)
@@ -645,8 +645,7 @@ export class HunchStore {
             const like = `%${term.replace(/[\\%_]/g, "\\$&")}%`;
             return [like, like];
         });
-        const where = kind ? `kind = ? AND (${predicates})` : `(${predicates})`;
-        const params = kind ? [kind, ...likes, limit] : [...likes, limit];
+        const where = (kind ? `kind = ? AND (${predicates})` : `(${predicates})`) + (allowedIds ? " AND ref IN (SELECT value FROM json_each(?))" : "");
         // Ordered so a TRUNCATING limit drops the least relevant row rather than an
         // arbitrary one: a title hit outranks a body-only hit, then shortest title
         // (a constraint's one-line statement beats a long decision body that merely
@@ -657,7 +656,7 @@ export class HunchStore {
         const rows = this.db.prepare(`SELECT ref, kind, title, substr(body,1,120) AS snip FROM search
        WHERE ${where}
        ORDER BY CASE WHEN ${titleLikes} THEN 0 ELSE 1 END, length(title), ref
-       LIMIT ?`).all(...(kind ? [kind, ...likes, ...titleParams, limit] : [...likes, ...titleParams, limit]));
+       LIMIT ?`).all(...[...(kind ? [kind] : []), ...likes, ...(allowedIds ? [JSON.stringify(allowedIds)] : []), ...titleParams, limit]);
         return this.demoteHistoricalState(rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: 0 })));
     }
     // ---- semantic search (opt-in embeddings) --------------------------------
@@ -1174,11 +1173,11 @@ export class HunchStore {
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
         target = toPosixTarget(target);
-        const decisions = this.recs("decisions");
-        const bugs = this.recs("bugs");
-        const constraints = this.recs("constraints");
-        const symbols = this.recs("symbols");
-        const components = this.recs("components");
+        const decisions = this.recs("decisions").filter(opts.canRead ?? (() => true));
+        const bugs = this.recs("bugs").filter(opts.canRead ?? (() => true));
+        const constraints = this.recs("constraints").filter(opts.canRead ?? (() => true));
+        const symbols = this.recs("symbols").filter(opts.canRead ?? (() => true));
+        const components = this.recs("components").filter(opts.canRead ?? (() => true));
         const asOf = opts.asOf;
         // pathsRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
         // so an unanchored suffix pulled unrelated files' records into why()/the
@@ -1801,13 +1800,13 @@ export class HunchStore {
         return out;
     }
     /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
-    bugLineage(symptomOrSymbol) {
-        const bugs = this.recs("bugs");
+    bugLineage(symptomOrSymbol, canRead) {
+        const bugs = this.recs("bugs").filter(canRead ?? (() => true));
         const direct = bugs.filter((b) => b.affected_symbols.includes(symptomOrSymbol) || b.affected_files.includes(symptomOrSymbol));
         if (direct.length)
             return direct;
         // fall back to fts over bug titles/symptoms
-        const hits = this.search(symptomOrSymbol).filter((h) => h.kind === "bugs").map((h) => h.ref);
+        const hits = this.search(symptomOrSymbol, 12, canRead ? bugs.map(b => b.id) : undefined).filter((h) => h.kind === "bugs").map((h) => h.ref);
         const byHit = bugs.filter((b) => hits.includes(b.id));
         if (byHit.length)
             return byHit;
@@ -1905,7 +1904,7 @@ export class HunchStore {
                     blast.set(d.id, d); // keep the MIN depth across start symbols
             }
         }
-        const bugs = w.bugs.length ? w.bugs : this.bugLineage(target);
+        const bugs = w.bugs.length ? w.bugs : this.bugLineage(target, opts.canRead);
         const ctx = {
             target,
             constraints: w.constraints.sort((a, b) => sev(b.severity) - sev(a.severity)),
@@ -1913,13 +1912,13 @@ export class HunchStore {
             bugs,
             blast_radius: [...blast.values()].sort((a, b) => a.depth - b.depth).slice(0, 12),
             components: w.components,
-            findings: this.liveFindingsFor(target).slice(0, 8),
+            findings: this.liveFindingsFor(target).filter(opts.canRead ?? (() => true)).slice(0, 8),
             // Landscape records do not yet carry a valid-time window. A historical
             // query therefore withholds them instead of mixing current graph state
             // into an as-of memory envelope.
             landscape: opts.asOf
                 ? undefined
-                : selectReviewedLandscape(this.recs("resources"), this.recs("edges"), target),
+                : selectReviewedLandscape(this.recs("resources").filter(opts.canRead ?? (() => true)), this.recs("edges").filter(opts.canRead ?? (() => true)), target),
             budget_tokens: budget,
         };
         return ctx;

package/dist/store/stateAccess.d.ts

@@ -0,0 +1,13 @@
+/** A request-local access view. Never installs mutable filters on shared stores. */
+import type { HunchStore } from './hunchStore.js';
+import { type Principal } from '../core/stateContract.js';
+export interface StateAccessOptions {
+    additionalStores?: readonly HunchStore[];
+    requireVisibility?: boolean;
+}
+export declare function createStateAccess(store: HunchStore, principal: Principal, opts?: StateAccessOptions): {
+    restricted: boolean;
+    canRead: (record: unknown) => boolean;
+    referencesVisible: (root: unknown) => boolean;
+    canWrite: (record: unknown) => boolean;
+};

package/dist/store/stateAccess.js

@@ -0,0 +1,85 @@
+import { STATE_FACETS, scopePath } from '../core/stateContract.js';
+import { visibilityAllows } from '../core/recordVisibility.js';
+import { recordScope, partitionOf, partitionDeclarationOf } from './statePartition.js';
+export function createStateAccess(store, principal, opts = {}) {
+    const repo = partitionOf(store), grants = new Set(principal.grants.map(scopePath));
+    const sources = [...new Set([store, ...(opts.additionalStores ?? [])])].map(source => ({ source, scope: partitionDeclarationOf(source) }));
+    // Protected writers persist this gate before the first restricted record and never remove it.
+    const restricted = !!opts.requireVisibility || sources.some(source => !!source.scope.required_capabilities?.length);
+    const recordScopes = new WeakMap();
+    const scoped = (record) => recordScopes.get(record) ?? recordScope(record, repo);
+    const baseAllows = (record, mode = 'read') => grants.has(scopePath(scoped(record))) && visibilityAllows(record, principal.id, mode);
+    const lookup = new Map();
+    function find(id) {
+        const cached = lookup.get(id);
+        if (cached)
+            return cached;
+        const found = [];
+        for (const { source, scope } of sources)
+            for (const facet of STATE_FACETS) {
+                let record;
+                // Exact capture/replay must not enumerate a high-cardinality collection. Its
+                // schemas require these prefixes; other strings cannot identify these records.
+                if (facet === 'derived' || facet === 'receipts' || facet === 'commitments') {
+                    const prefix = { derived: 'nds', receipts: 'nrc', commitments: 'ncm' }[facet];
+                    if (!new RegExp(`^${prefix}_[a-f0-9]{24}$`).test(id))
+                        continue;
+                    record = source.getStateDirect(facet, id, 'private') ?? source.getStateDirect(facet, id, 'public');
+                }
+                else
+                    record = source.getRec(facet, id);
+                if (record) {
+                    const value = record;
+                    recordScopes.set(value, recordScope(value, scope));
+                    found.push(value);
+                }
+            }
+        lookup.set(id, found);
+        return found;
+    }
+    // Walk only the reachable dependency graph, iteratively so cycles and deep chains
+    // cannot overflow the stack. Complete records are withheld, never hash-preserving redactions.
+    function referencesVisible(root) {
+        const queue = [root], visited = new Set();
+        for (let i = 0; i < queue.length; i++) {
+            const record = queue[i];
+            if (!record || typeof record !== 'object' || visited.has(record))
+                continue;
+            visited.add(record);
+            if (i > 0 && (!visibilityAllows(record, principal.id) || (restricted && !baseAllows(record))))
+                return false;
+            const own = scoped(record);
+            const values = [{ value: record }];
+            while (values.length) {
+                const { value, field } = values.pop();
+                if (field === 'visibility' || field === 'id')
+                    continue;
+                if (typeof value === 'string') {
+                    queue.push(...find(value));
+                    continue;
+                }
+                if (Array.isArray(value)) {
+                    for (const child of value)
+                        values.push({ value: child });
+                    continue;
+                }
+                if (!value || typeof value !== 'object')
+                    continue;
+                const ref = value;
+                if (ref.kind === 'record' && typeof ref.id === 'string') {
+                    const scope = recordScope(ref, own), matches = find(ref.id).filter(candidate => scopePath(scoped(candidate)) === scopePath(scope));
+                    if (restricted && (!grants.has(scopePath(scope)) || !matches.length))
+                        return false;
+                    queue.push(...matches);
+                    continue;
+                }
+                for (const [name, child] of Object.entries(ref))
+                    values.push({ value: child, field: name });
+            }
+        }
+        return true;
+    }
+    const canRead = (record) => !!record && baseAllows(record) && referencesVisible(record);
+    return { restricted, canRead, referencesVisible, canWrite: (record) => canRead(record) && baseAllows(record, 'write') };
+}
+//# sourceMappingURL=stateAccess.js.map

package/dist/store/stateBinding.d.ts

@@ -1,27 +1,16 @@
+import { type StateAccessOptions } from "./stateAccess.js";
 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);
-}
+export { StateRefusal } from "./stateError.js";
 /** 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 { partitionOf, repositoryScope } from "./statePartition.js";
 export declare const SubscribeResponseSchema: z.ZodObject<{
     schema: z.ZodLiteral<"nuryel.state.subscribe/1">;
     scope: z.ZodObject<{
@@ -35,6 +24,11 @@ export declare const SubscribeResponseSchema: z.ZodObject<{
     }, z.core.$strict>;
     head_seq: z.ZodNumber;
     events: z.ZodArray<z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.state.subscribe/1">;
         seq: z.ZodNumber;
         at: z.ZodString;
@@ -57,6 +51,7 @@ export declare const SubscribeResponseSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         record_id: z.ZodString;
         record_hash: z.ZodString;
@@ -109,7 +104,7 @@ export declare function stateHomeFor(store: HunchStore, scope: Scope): {
 /** 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): {
+export declare function readState(store: HunchStore, input: unknown, options?: StateAccessOptions): {
     response: ReadResponse;
     envelope: DeliveryEnvelope;
 };
@@ -123,7 +118,7 @@ export declare function readState(store: HunchStore, input: unknown): {
  *  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 {
+export interface WriteOptions extends StateAccessOptions {
     /** 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. */
@@ -139,7 +134,7 @@ export interface WriteOptions {
 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;
+export declare function subscribeState(store: HunchStore, input: unknown, options?: StateAccessOptions): 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;
+export declare function recordsState(store: HunchStore, input: unknown, options?: StateAccessOptions): RecordsResponse;