@davesheffer/hunch 1.32.8 → 1.35.0

package/dist/serve/stateProof.d.ts

@@ -0,0 +1,15 @@
+import { type ProofPublicKey } from '../core/stateProof.js';
+export declare class StateProofError extends Error {
+    readonly code: 'invalid_dpop_proof' | 'use_dpop_nonce';
+    readonly nonce?: string | undefined;
+    constructor(code: 'invalid_dpop_proof' | 'use_dpop_nonce', nonce?: string | undefined);
+}
+export declare function verifyStateProof(input: {
+    proof?: string;
+    key: ProofPublicKey;
+    method: string;
+    url: string;
+    token: string;
+    stateDir: string;
+    now?: number;
+}): Promise<void>;

package/dist/serve/stateProof.js

@@ -0,0 +1,105 @@
+import { withWriteLock } from './writelock.js';
+/** Shared-disk nonce/replay state survives restarts and serializes independent server processes. */
+import { createHash, createHmac, createPublicKey, randomBytes, timingSafeEqual, verify } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { writeFileAtomicIfAbsent } from '../core/io.js';
+import { ProofPublicKeySchema, proofThumbprint, proofTarget, tokenProofHash } from '../core/stateProof.js';
+const Header = z.object({ typ: z.literal('dpop+jwt'), alg: z.literal('EdDSA'), jwk: ProofPublicKeySchema }).strict();
+const Claims = z.object({ jti: z.string().min(16).max(128), htm: z.string().max(16), htu: z.string().max(2048), iat: z.number().int().nonnegative(), ath: z.string().regex(/^[A-Za-z0-9_-]{43}$/), nonce: z.string().max(128).optional() }).strict();
+export class StateProofError extends Error {
+    code;
+    nonce;
+    constructor(code, nonce) {
+        super(code === 'use_dpop_nonce' ? 'a fresh server nonce is required' : 'request proof is invalid or already used');
+        this.code = code;
+        this.nonce = nonce;
+    }
+}
+function ordinaryDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('proof state must be an ordinary private directory');
+    if ((stat.mode & 0o777) !== 0o700)
+        chmodSync(path, 0o700);
+}
+function equal(a, b) { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); }
+function decode(segment) {
+    if (!/^[A-Za-z0-9_-]+$/.test(segment) || Buffer.from(segment, 'base64url').toString('base64url') !== segment)
+        throw new StateProofError('invalid_dpop_proof');
+    return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+}
+const lastSweep = new Map();
+export async function verifyStateProof(input) {
+    const now = input.now ?? Math.floor(Date.now() / 1000), thumbprint = proofThumbprint(input.key);
+    ordinaryDirectory(input.stateDir);
+    const secretFile = join(input.stateDir, 'nonce-key');
+    if (!existsSync(secretFile))
+        writeFileAtomicIfAbsent(secretFile, randomBytes(32).toString('hex'));
+    const stat = lstatSync(secretFile);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== 64)
+        throw new Error('proof nonce key is invalid');
+    if ((stat.mode & 0o777) !== 0o600)
+        chmodSync(secretFile, 0o600);
+    const secret = readFileSync(secretFile, 'utf8');
+    if (!/^[a-f0-9]{64}$/.test(secret))
+        throw new Error('proof nonce key is invalid');
+    const epoch = Math.floor(now / 60), tokenHash = tokenProofHash(input.token);
+    const nonceAt = (period) => `${period}.${createHmac('sha256', Buffer.from(secret, 'hex')).update(`${period}:${thumbprint}:${tokenHash}`).digest('base64url')}`;
+    const nonce = nonceAt(epoch);
+    if (!input.proof)
+        throw new StateProofError('use_dpop_nonce', nonce);
+    let claims;
+    try {
+        if (input.proof.length > 8192)
+            throw new Error('oversized');
+        const parts = input.proof.split('.');
+        if (parts.length !== 3)
+            throw new Error('JWT');
+        const header = Header.parse(decode(parts[0]));
+        claims = Claims.parse(decode(parts[1]));
+        const signature = Buffer.from(parts[2], 'base64url');
+        if (signature.length !== 64 || signature.toString('base64url') !== parts[2])
+            throw new Error('signature');
+        if (!equal(proofThumbprint(header.jwk), thumbprint))
+            throw new Error('key');
+        if (!verify(null, Buffer.from(parts[0] + '.' + parts[1]), createPublicKey({ key: header.jwk, format: 'jwk' }), signature))
+            throw new Error('signature');
+        if (claims.htm !== input.method || claims.htu !== proofTarget(input.url) || !equal(claims.ath, tokenHash) || claims.iat < now - 60 || claims.iat > now + 5)
+            throw new Error('binding');
+    }
+    catch {
+        throw new StateProofError('invalid_dpop_proof');
+    }
+    if (!claims.nonce || (!equal(claims.nonce, nonce) && !equal(claims.nonce, nonceAt(epoch - 1))))
+        throw new StateProofError('use_dpop_nonce', nonce);
+    await withWriteLock(input.stateDir, () => {
+        const replayRoot = join(input.stateDir, 'used');
+        ordinaryDirectory(replayRoot);
+        // One atomic filename per key/jti, independent of iat: concurrent proofs with
+        // different timestamps cannot each win in a separate bucket.
+        if (lastSweep.get(replayRoot) !== epoch) {
+            for (const entry of readdirSync(replayRoot, { withFileTypes: true })) {
+                if (!/^[a-f0-9]{64}$/.test(entry.name) || !entry.isFile() || entry.isSymbolicLink())
+                    continue;
+                const file = join(replayRoot, entry.name);
+                try {
+                    const expires = Number(readFileSync(file, 'utf8'));
+                    if (Number.isFinite(expires) && expires < now)
+                        rmSync(file);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            lastSweep.set(replayRoot, epoch);
+        }
+        const id = createHash('sha256').update(thumbprint + '\0' + claims.jti).digest('hex');
+        if (!writeFileAtomicIfAbsent(join(replayRoot, id), String(claims.iat + 60)))
+            throw new StateProofError('invalid_dpop_proof');
+    });
+}
+//# sourceMappingURL=stateProof.js.map

package/dist/store/changeLedger.d.ts

@@ -25,6 +25,11 @@ export declare const LedgerSchema: z.ZodObject<{
     head_seq: z.ZodNumber;
     floor_seq: z.ZodDefault<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;
@@ -47,6 +52,7 @@ export declare const LedgerSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         record_id: z.ZodString;
         record_hash: z.ZodString;

package/dist/store/hunchStore.d.ts

@@ -1,5 +1,5 @@
 import { type HunchPaths } from "../core/paths.js";
-import { type Component, type Constraint, type Bug, type Decision, type Symbol, type Edge, type Finding, type EntityKind, type EntityFor } from "../core/types.js";
+import { type Component, type Constraint, type Bug, type Decision, type Symbol, type Edge, type Finding, type EntityKind, type EntityFor, type TaskRecord } from "../core/types.js";
 import { type DB } from "./db.js";
 import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
@@ -191,7 +191,7 @@ export declare 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: string, limit?: number): SearchHit[];
+    search(query: string, limit?: number, allowedIds?: readonly string[]): SearchHit[];
     /** State-of-record ordering for nuryel.state/1 hits (superseded derived, done/cancelled
      *  commitments, failed receipts, retired entities): indexed and findable, but ranked BELOW
      *  the live record of the same subject. bm25 is negative (lower = better), so a history
@@ -341,6 +341,7 @@ export declare class HunchStore {
      *  history-inclusive view (backward-compatible default). */
     why(target: string, opts?: {
         asOf?: string;
+        canRead?: (record: unknown) => boolean;
     }): WhyResult;
     /** Transitive blast radius: every symbol/component that (in)directly depends on
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
@@ -404,6 +405,10 @@ export declare class HunchStore {
      *  glob, and the queried scope may be either too. Advisory only — findings never
      *  enter any block path. Sorted worst-first, then id for stable output. */
     liveFindingsFor(scope: string): Finding[];
+    /** Finished agent tasks that touched a file or glob (rule-checked changes and
+     *  denied edits), newest first. Graph memory, so it spans machines and survives
+     *  the local ledger's retention window. */
+    tasksFor(scope: string, limit?: number): TaskRecord[];
     /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
      *  Deterministic graph join: constraint → source_decision (the decision that
      *  motivated the guard) → the bug whose root cause spawned it (via
@@ -488,7 +493,7 @@ export declare class HunchStore {
      *  available at edit time, so this surfaces the risk as context, not a block. */
     retiredForFile(file: string): RetiredNote[];
     /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
-    bugLineage(symptomOrSymbol: string): Bug[];
+    bugLineage(symptomOrSymbol: string, canRead?: (record: unknown) => boolean): Bug[];
     /** Ranked fragility report (hunch fragile). fragility = weighted churn + bugs + fan-in. */
     fragility(limit?: number): FragileNode[];
     /** Convenience: load a single entity from JSON by id (any kind). */
@@ -507,6 +512,7 @@ export declare class HunchStore {
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
     assembleContext(target: string, budget?: number, opts?: {
         asOf?: string;
+        canRead?: (record: unknown) => boolean;
     }): AssembledContext;
 }
 /** The graph-served repo shape (hunch_structure) — orient without grep rounds. */

package/dist/store/hunchStore.js

@@ -491,6 +491,14 @@ export class HunchStore {
                 fts(f.id, "findings", f.title, `${f.observation} ${f.evidence.join(" ")} ${f.affected_files.join(" ")} ${f.affected_symbols.join(" ")} ${f.triage}`);
             }
             counts.findings = fnds.length;
+            // Tasks (finished agent work as graph memory): same FTS-only ride. Title +
+            // the lesson/save/application record ids and touched files, so "what did
+            // an agent do around X" and a record id both hit.
+            const tasks = this.recs("tasks");
+            for (const t of tasks) {
+                fts(t.id, "tasks", t.title, `${t.lessons.map((l) => `${l.record_id} ${l.title}`).join(" ")} ${t.applied.map((a) => a.record_id).join(" ")} ${t.saved.map((s) => s.record_id).join(" ")} ${t.files.join(" ")} ${t.state} ${t.coverage}`);
+            }
+            counts.tasks = tasks.length;
             // nuryel.state/1 kinds (receipts, commitments, derived, entities, relationships):
             // advisory records on the same FTS-only ride as runbooks/findings — no dedicated
             // SQL table. kind = the store kind; title = the subject key; body = the human words
@@ -518,20 +526,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 +643,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 +653,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 +664,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 +1181,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
@@ -1436,6 +1443,16 @@ export class HunchStore {
             || f.affected_symbols.some((s) => s === scope))
             .sort((a, b) => (SEV_FINDING[b.severity] ?? 0) - (SEV_FINDING[a.severity] ?? 0) || a.id.localeCompare(b.id));
     }
+    /** Finished agent tasks that touched a file or glob (rule-checked changes and
+     *  denied edits), newest first. Graph memory, so it spans machines and survives
+     *  the local ledger's retention window. */
+    tasksFor(scope, limit = 8) {
+        const t = toPosixTarget(scope);
+        return this.recs("tasks")
+            .filter((r) => r.files.some((f) => pathMatchesGlob(t, f) || pathMatchesGlob(f, t) || pathsRelated(toPosixTarget(f), t)))
+            .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
+            .slice(0, Math.max(1, limit));
+    }
     /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
      *  Deterministic graph join: constraint → source_decision (the decision that
      *  motivated the guard) → the bug whose root cause spawned it (via
@@ -1801,13 +1818,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 +1922,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 +1930,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;