@davesheffer/hunch 1.32.8 → 1.33.0

package/dist/store/stateBinding.js

@@ -1,3 +1,9 @@
+import { conventionDelivery, conventionSupplements } from '../core/conventionDelivery.js';
+import { StateRefusal } from "./stateError.js";
+import { partitionOf, recordScope } from "./statePartition.js";
+import { createStateAccess } from "./stateAccess.js";
+import { visibilityAllows } from "../core/recordVisibility.js";
+import { writeFileAtomic } from "../core/io.js";
 /**
  * nuryel.state/1 bound to the store — the ONE implementation of read / write / subscribe
  * that every transport (MCP today; HTTP, CLI, typed client next) calls. Transport-free:
@@ -17,8 +23,7 @@
  * dependencies, external-truth-stays-external (schema refinements), never-in-request-path
  * (there is no proxy verb — this module never fetches anything).
  */
-import { basename, join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { z } from "zod";
 import { appendChanges, latestSeqFor, readLedger } from "./changeLedger.js";
 import { hunchPaths } from "../core/paths.js";
@@ -26,18 +31,9 @@ import { decisionId } from "../core/ids.js";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { captureConflicts, isLive } from "../core/topics.js";
 import { buildDeliveryEnvelope } from "../core/delivery.js";
-import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_RECORDS_VERSION, ScopeSchema, scopePath, stateHash, actionReceiptId, commitmentId, derivedId, relationshipId, externalKey, subjectOfRef, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, isHumanConfirmed, } from "../core/stateContract.js";
+import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_RECORD_VISIBILITY_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_RECORDS_VERSION, ScopeSchema, scopePath, stateHash, conventionId, actionReceiptId, commitmentId, derivedId, relationshipId, externalKey, subjectOfRef, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, isHumanConfirmed, } from "../core/stateContract.js";
 /** A typed refusal. `code` is stable for bindings; `conflict` names the incumbent when one exists. */
-export class StateRefusal extends Error {
-    code;
-    conflict;
-    constructor(code, message, conflict = null) {
-        super(message);
-        this.code = code;
-        this.conflict = conflict;
-        this.name = "StateRefusal";
-    }
-}
+export { StateRefusal } from "./stateError.js";
 const LEGACY_FACETS = new Set(["decisions", "constraints", "bugs", "findings"]);
 // Explicit classes, no `i` flag: the pattern must survive zod → JSON schema for MCP output validation.
 const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
@@ -45,20 +41,7 @@ const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
  *  (`{ 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 function partitionOf(store) {
-    const declared = join(hunchPaths(store.publicRoot).hunch, "partition.json");
-    if (existsSync(declared)) {
-        const parsed = ScopeSchema.safeParse(JSON.parse(readFileSync(declared, "utf8")));
-        if (!parsed.success)
-            throw new StateRefusal("unsupported", `${declared} does not declare a valid partition scope`);
-        return parsed.data;
-    }
-    const raw = basename(store.publicRoot).replace(/[^A-Za-z0-9._:@+-]/g, "-").replace(/^[^A-Za-z0-9]+/, "");
-    const id = TOKEN.test(raw) ? raw : "repository";
-    return { kind: "repository", id };
-}
-/** @deprecated name kept for callers written before served partitions; same value as partitionOf. */
-export const repositoryScope = partitionOf;
+export { partitionOf, repositoryScope } from "./statePartition.js";
 export const SubscribeResponseSchema = z.object({
     schema: z.literal(STATE_SUBSCRIBE_VERSION),
     scope: ScopeSchema,
@@ -97,11 +80,6 @@ export function stateHomeFor(store, scope) {
     }
     return { home: "private", hunchDir: store.privateDir, isPrivate: true };
 }
-const recordScope = (record, repo) => {
-    const s = record.scope;
-    const parsed = ScopeSchema.safeParse(s);
-    return parsed.success ? parsed.data : repo;
-};
 // ---- read ----------------------------------------------------------------------------------
 function refOf(facet, record, scope) {
     return { facet, id: record.id, record_hash: stateHash(record), scope };
@@ -121,10 +99,10 @@ function survivorOf(byId, entity) {
 }
 /** The entities in the principal's grants that stand for an external key or an entity id — active
  *  ones directly, retired-and-merged ones through the survivor they name. */
-function entityIndex(store, principal, repo) {
+function entityIndex(store, principal, repo, canRead = () => true) {
     const byId = new Map();
     for (const e of store.recs("entities"))
-        if (granted(principal, recordScope(e, repo)))
+        if (granted(principal, recordScope(e, repo)) && canRead(e))
             byId.set(e.id, e);
     const survivor = (e) => survivorOf(byId, e);
     const byKey = new Map();
@@ -144,9 +122,9 @@ function entityIndex(store, principal, repo) {
 }
 /** The names one subject is filed under: itself, the entity that stands for it (through merges),
  *  every entity merged into that one, and every key any of them carries. Explicit refs only. */
-function subjectAliases(store, principal, repo, subject) {
+function subjectAliases(store, principal, repo, subject, canRead) {
     const aliases = new Set([subject]);
-    const { bySubject, byId, survivor } = entityIndex(store, principal, repo);
+    const { bySubject, byId, survivor } = entityIndex(store, principal, repo, canRead);
     const named = bySubject.get(subject) ?? byId.get(subject);
     if (!named)
         return aliases;
@@ -165,7 +143,7 @@ function subjectAliases(store, principal, repo, subject) {
 /** 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 function readState(store, input) {
+export function readState(store, input, options = {}) {
     const request = ReadRequestSchema.parse(input);
     if (!granted(request.principal, request.scope))
         throw new StateRefusal("outside-grants", `scope ${scopePath(request.scope)} is outside the principal's grants`);
@@ -175,16 +153,30 @@ export function readState(store, input) {
     const repo = partitionOf(store);
     const facets = new Set(request.facets ?? STATE_FACETS);
     const target = request.task ?? request.subject ?? scopePath(request.scope);
-    const ctx = store.assembleContext(target, request.budget_tokens ?? 1500);
+    const access = createStateAccess(store, request.principal, options);
+    const conventions = facets.has('conventions') ? store.recs('conventions').filter(r => access.canRead(r) && scopePath(r.scope) === scopePath(request.scope)) : [];
+    const resolveConventionSource = (id, scope) => {
+        for (const source of [store, ...(options.additionalStores ?? [])]) {
+            const record = findRecord(source, id)?.record;
+            if (record && scopePath(recordScope(record, partitionOf(source))) === scopePath(scope) && access.canRead(record))
+                return record;
+        }
+        return undefined;
+    };
+    const conventionView = conventionDelivery(conventions, resolveConventionSource);
+    const ctx = store.assembleContext(target, request.budget_tokens ?? 1500, { canRead: access.canRead });
     const envelope = buildDeliveryEnvelope(ctx, {
         root: store.publicRoot,
-        symbols: store.recs("symbols"),
-        components: store.recs("components"),
-        decisionCorpus: store.recs("decisions"),
+        symbols: store.recs("symbols").filter(access.canRead),
+        components: store.recs("components").filter(access.canRead),
+        decisionCorpus: store.recs("decisions").filter(access.canRead),
         profile: request.profile ?? "builder",
+        supplements: conventionSupplements(conventions, resolveConventionSource),
     });
     let stateOfRecord = null;
     const records = {};
+    for (const item of conventionView?.items ?? [])
+        records[item.ref.id] = conventions.find(r => r.id === item.ref.id);
     const denied = new Map();
     // Union read against ONE store: every requested scope the principal lacks is named up front;
     // the partitions actually read are declared so a caller never mistakes this for the union
@@ -197,13 +189,13 @@ export function readState(store, input) {
         // Subject identity by external reference: a read for an external record's key (`event:26904`,
         // `customer:Site:7`) also finds what is filed under the entity that carries that ref, and a
         // read for the entity id finds what was filed under its keys — one explicit hop, grants first.
-        const aliases = subjectAliases(store, request.principal, repo, subject);
+        const aliases = subjectAliases(store, request.principal, repo, subject, access.canRead);
         const isSubject = (s) => s !== undefined && aliases.has(s);
         // One hop only. Do not broaden aliases: a linked observation does not merge subjects,
         // bring unrelated facts, receipts or commitments, or traverse another relationship.
         const linkedObservations = new Map();
         for (const r of store.recs("relationships")) {
-            if (!granted(request.principal, r.scope) || scopePath(r.scope) !== scopePath(request.scope))
+            if (!access.canRead(r) || !granted(request.principal, r.scope) || scopePath(r.scope) !== scopePath(request.scope))
                 continue;
             if (r.type !== "observation_about" || r.lifecycle === "retired" || !isSubject(r.to) || !r.observation_hash)
                 continue;
@@ -225,7 +217,7 @@ export function readState(store, input) {
                 denied.set(scopePath(scope), scope);
                 return null;
             }
-            return scope;
+            return access.canRead(record) ? scope : null;
         };
         const keep = (facet, record, scope) => {
             records[record.id] = record;
@@ -355,7 +347,8 @@ export function readState(store, input) {
         scope: request.scope,
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
-        ...(stateOfRecord ? { records } : {}),
+        ...(conventionView ? { conventions: conventionView } : {}),
+        ...(stateOfRecord || conventionView ? { records } : {}),
         ...(request.scopes ? { scopes: [request.scope], receipts: [{ scope: request.scope, receipt_id: envelope.receipt_id }] } : {}),
     });
     assertReadWithinGrants(request.principal, response);
@@ -428,13 +421,31 @@ export function mergeReadResponses(primary, others, extraDenied = []) {
                 if (!(id in records))
                     records[id] = record;
     }
+    // Recompute cross-scope conflicts without inventing an organization/team/user winner.
+    const conventionRecords = all.flatMap(r => (r.conventions?.items ?? []).map(item => r.records?.[item.ref.id])).filter((r) => !!r);
+    const deliveredConventions = all.flatMap(r => r.conventions?.items ?? []);
+    const conventionView = conventionDelivery(conventionRecords, undefined, new Map(deliveredConventions.map(item => [item.ref.id, item.currentness])));
+    if (conventionView) {
+        conventionView.truncated ||= all.some(r => r.conventions?.truncated);
+        for (const item of conventionView.items) {
+            const prior = deliveredConventions.find(x => x.ref.id === item.ref.id);
+            item.currentness = prior.currentness;
+            item.conflict ||= prior.conflict;
+            records[item.ref.id] = conventionRecords.find(r => r.id === item.ref.id);
+        }
+        const selected = new Set(conventionView.items.map(item => item.ref.id));
+        for (const record of conventionRecords)
+            if (!selected.has(String(record.id)))
+                delete records[String(record.id)];
+    }
     return ReadResponseSchema.parse({
         schema: STATE_READ_VERSION,
         receipt_id: primary.receipt_id,
         scope: primary.scope,
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
-        ...(stateOfRecord ? { records } : {}),
+        ...(conventionView ? { conventions: conventionView } : {}),
+        ...(stateOfRecord || conventionView ? { records } : {}),
         scopes: [...scopes.values()],
         receipts: [...receipts.values()],
     });
@@ -443,6 +454,7 @@ export function mergeReadResponses(primary, others, extraDenied = []) {
 function subjectOf(facet, record) {
     const r = record;
     switch (facet) {
+        case "conventions": return typeof r.key === "string" ? r.key : undefined;
         case "commitments":
         case "derived": return typeof r.subject === "string" ? r.subject : undefined;
         case "entities": return typeof r.id === "string" ? r.id : undefined;
@@ -464,6 +476,7 @@ function facetOfId(id) {
         case "con": return "constraints";
         case "bug": return "bugs";
         case "fnd": return "findings";
+        case "ncv": return "conventions";
         case "nrc": return "receipts";
         case "ncm": return "commitments";
         case "nds": return "derived";
@@ -615,7 +628,9 @@ function normalizeRecord(facet, scope, raw, principal) {
     }
     let expectedId = null;
     try {
-        if (facet === "receipts")
+        if (facet === "conventions")
+            expectedId = conventionId(record);
+        else if (facet === "receipts")
             expectedId = actionReceiptId(record);
         else if (facet === "commitments")
             expectedId = commitmentId(record);
@@ -650,6 +665,25 @@ function normalizeRecord(facet, scope, raw, principal) {
 /** write — provenance + idempotency in, durability out. A replay returns the original;
  *  a conflict names the incumbent; nothing is ever silently overwritten or duplicated. */
 export function writeState(store, input, opts = {}) {
+    const request = WriteRequestSchema.parse(input);
+    if (!granted(request.principal, request.scope))
+        throw new StateRefusal("outside-grants", "scope is outside the principal grants");
+    const access = createStateAccess(store, request.principal, { ...opts, requireVisibility: request.record.visibility !== undefined });
+    try {
+        return writeStateAuthorized(store, request, opts, access);
+    }
+    catch (error) {
+        // Collision detection remains global, but inaccessible incumbents never become
+        // refusal details. Do not filter the collision corpus and permit duplicates.
+        if (error instanceof StateRefusal && error.conflict) {
+            const incumbent = findRecord(store, error.conflict.incumbent_id)?.record;
+            if (incumbent && !access.canRead(incumbent))
+                throw new StateRefusal('outside-grants', 'record unavailable or operation not permitted');
+        }
+        throw error;
+    }
+}
+function writeStateAuthorized(store, input, opts, access) {
     const request = WriteRequestSchema.parse(input);
     try {
         assertWriteWellFormed(request);
@@ -666,10 +700,50 @@ export function writeState(store, input, opts = {}) {
     if (!ENTITY_KINDS.includes(facet))
         throw new StateRefusal("unsupported", `facet ${facet} is not a store kind`);
     const record = normalizeRecord(facet, request.scope, request.record, request.principal);
+    const deny = () => { throw new StateRefusal('outside-grants', 'record unavailable or operation not permitted'); };
+    const incumbent = getHere(String(record.id));
+    if (incumbent && !access.canWrite(incumbent))
+        deny();
+    const previousVisibility = incumbent?.visibility;
+    const nextVisibility = record.visibility;
+    if (nextVisibility && home === 'private')
+        throw new StateRefusal('unsupported', 'record visibility requires a dedicated partition home; shared/private overlays cannot safely gate every older reader');
+    const supersededRecord = request.supersedes ? findRecord(store, request.supersedes)?.record : undefined;
+    const supersededVisibility = supersededRecord?.visibility;
+    if (supersededRecord) {
+        if (!access.canWrite(supersededRecord))
+            deny();
+        if (stateHash(supersededVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
+            if (supersededVisibility ? supersededVisibility.owner !== request.principal.id : request.principal.kind !== 'human')
+                deny();
+            const matches = typeof request.expected_version === 'number'
+                ? latestSeqFor(readLedger(hunchDir, request.scope), String(supersededRecord.id)) === request.expected_version
+                : request.expected_version === stateHash(supersededRecord);
+            if (!matches)
+                throw new StateRefusal('malformed', 'changing visibility during supersession requires the predecessor expected_version');
+        }
+    }
+    if (!incumbent && !supersededRecord && nextVisibility?.owner !== undefined && nextVisibility.owner !== request.principal.id)
+        deny();
+    if (incumbent && stateHash(previousVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
+        if (previousVisibility ? previousVisibility.owner !== request.principal.id : request.principal.kind !== 'human' || nextVisibility?.owner !== request.principal.id)
+            deny();
+        if (request.expected_version === null)
+            throw new StateRefusal('malformed', 'changing visibility requires an explicit expected_version');
+    }
+    if (!visibilityAllows(record, request.principal.id) || !access.referencesVisible(record) || (request.cause && !access.referencesVisible(request.cause)))
+        deny();
+    if (request.supersedes) {
+        const prior = findRecord(store, request.supersedes)?.record;
+        if (prior && !access.canWrite(prior))
+            deny();
+    }
     let replayLink;
     if (facet === "relationships" && record.type === "observation_about") {
         const link = record;
         const observation = store.getStateDirect("derived", link.from, home);
+        if (observation && !access.canRead(observation))
+            deny();
         if (!observation || scopePath(observation.scope) !== scopePath(request.scope) || !granted(request.principal, observation.scope))
             throw new StateRefusal("conflict", "observation is absent from the granted partition");
         if (!observation.transform_version.startsWith("agent-capture/1:"))
@@ -706,6 +780,9 @@ export function writeState(store, input, opts = {}) {
     // is a refusal, never a second record.
     const seen = ledger.idempotency[request.idempotency_key];
     if (seen) {
+        const prior = findRecord(store, seen.record_id)?.record;
+        if (prior && !access.canRead(prior))
+            deny();
         if (seen.record_id === id && (seen.record_hash === hash || seen.payload_hash === hash))
             return result("replayed");
         // Say WHAT differs and what to do: a stable key with a varying payload (a timestamp, new
@@ -772,6 +849,24 @@ export function writeState(store, input, opts = {}) {
         if (supersedes && supersedes !== id)
             guard(store.getRec(facet, supersedes), "supersede");
     }
+    if (facet === 'conventions') {
+        const convention = record;
+        if (existing && request.expected_version === null)
+            throw new StateRefusal('conflict', 'changing a convention requires expected_version');
+        if (supersedes) {
+            const prior = store.getRec('conventions', supersedes);
+            if (!prior || prior.key !== convention.key || scopePath(prior.scope) !== scopePath(convention.scope))
+                throw new StateRefusal('conflict', 'convention supersession must preserve scope and key');
+            if (request.expected_version !== stateHash(prior))
+                throw new StateRefusal('conflict', 'convention supersession requires the predecessor expected_version hash');
+        }
+        if (convention.status === 'accepted' && convention.valid_to === null) {
+            const incumbent = store.recsInHome('conventions', home).find(r => r.key === convention.key && scopePath(r.scope) === scopePath(convention.scope) && r.status === 'accepted' && r.valid_to === null && r.id !== id && r.id !== supersedes);
+            if (incumbent)
+                throw new StateRefusal('conflict', `${convention.key} already has an accepted convention; pass supersedes`, { incumbent_id: incumbent.id, reason: 'one accepted convention per scope and key' });
+        }
+        assertRestsOn(store, request.principal, request.scope, convention.sources);
+    }
     // one-live-decision-per-topic — refuse with the incumbent named; supersession is explicit.
     if (facet === "decisions") {
         const d = record;
@@ -827,6 +922,12 @@ export function writeState(store, input, opts = {}) {
     if (facet === "receipts")
         assertRestsOn(store, request.principal, request.scope, record.rests_on ?? []);
     const closedBy = facet === "commitments" ? assertClosedBy(store, request.principal, record) : null;
+    if (nextVisibility) {
+        // Publish the fail-closed old-reader gate BEFORE protected bytes. An interrupted
+        // write can leave a gate without a record, never a record without the gate.
+        const declaration = join(hunchPaths(store.publicRoot).hunch, 'partition.json');
+        writeFileAtomic(declaration, JSON.stringify({ ...partitionOf(store), required_capabilities: [STATE_RECORD_VISIBILITY_VERSION] }, null, 2) + '\n');
+    }
     store.putCapture(facet, record, isPrivate);
     /** What is on file now — the hash every event, ref and result carries. */
     const onFileHash = stateHash(getHere(id) ?? record);
@@ -843,10 +944,10 @@ export function writeState(store, input, opts = {}) {
         const closed = closeWindow(store, facet, supersedes, id, now, isPrivate);
         if (closed) {
             const old = store.getRec(facet, supersedes);
-            changes.push({ facet, record_id: supersedes, record_hash: stateHash(old), change: "superseded", subject: subjectOf(facet, old), invalidates: [], cause });
+            changes.push({ ...("visibility" in old && old.visibility ? { visibility: old.visibility } : {}), facet, record_id: supersedes, record_hash: stateHash(old), change: "superseded", subject: subjectOf(facet, old), invalidates: [], cause });
         }
     }
-    changes.push({ facet, record_id: id, record_hash: onFileHash, change: invalidated ? "invalidated" : retired ? "retired" : existing ? "updated" : "created", subject, invalidates: invalidated && subject ? [subject] : invalidates, cause });
+    changes.push({ ...(nextVisibility ? { visibility: nextVisibility } : {}), facet, record_id: id, record_hash: onFileHash, change: invalidated ? "invalidated" : retired ? "retired" : existing ? "updated" : "created", subject, invalidates: invalidated && subject ? [subject] : invalidates, cause });
     appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: onFileHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
     if (!opts.deferReindex)
         store.reindex();
@@ -855,7 +956,7 @@ export function writeState(store, input, opts = {}) {
 // ---- subscribe -----------------------------------------------------------------------------
 /** 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 function subscribeState(store, input) {
+export function subscribeState(store, input, options = {}) {
     const request = SubscribeRequestSchema.parse(input);
     if (!granted(request.principal, request.scope))
         throw new StateRefusal("outside-grants", `scope ${scopePath(request.scope)} is outside the principal's grants`);
@@ -863,10 +964,13 @@ export function subscribeState(store, input) {
     const ledger = readLedger(hunchDir, request.scope);
     const facets = request.facets ? new Set(request.facets) : null;
     const subjects = request.subjects ? new Set(request.subjects) : null;
-    const filtered = !!(facets || subjects);
+    const access = createStateAccess(store, request.principal, options);
+    const visibilityFiltered = ledger.events.some(e => e.visibility !== undefined) || access.restricted;
+    const filtered = !!(facets || subjects || visibilityFiltered);
     const resync = request.after_seq < ledger.floor_seq;
     const after = resync ? ledger.floor_seq : request.after_seq;
     const events = ledger.events.filter((e) => e.seq > after
+        && (!visibilityFiltered || (visibilityAllows(e, request.principal.id) && access.canRead(findRecord(store, e.record_id)?.record) && access.referencesVisible(e)))
         && (!facets || facets.has(e.facet))
         && (!subjects || subjects.has(e.record_id) || (e.subject !== undefined && subjects.has(e.subject)) || e.invalidates.some((s) => subjects.has(s))));
     return SubscribeResponseSchema.parse({ schema: STATE_SUBSCRIBE_VERSION, scope: request.scope, head_seq: ledger.head_seq, events, filtered, floor_seq: ledger.floor_seq, resync });
@@ -874,11 +978,12 @@ export function subscribeState(store, input) {
 // ---- records ------------------------------------------------------------------------------
 /** 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 function recordsState(store, input) {
+export function recordsState(store, input, options = {}) {
     const request = RecordsRequestSchema.parse(input);
     if (!granted(request.principal, request.scope))
         throw new StateRefusal("outside-grants", `scope ${scopePath(request.scope)} is outside the principal's grants`);
     const repo = partitionOf(store);
+    const access = createStateAccess(store, request.principal, options);
     const records = {};
     const facets = {};
     const denied = [];
@@ -901,6 +1006,10 @@ export function recordsState(store, input) {
             denied.push(id);
             continue;
         }
+        if (!access.canRead(found.record)) {
+            missing.push(id);
+            continue;
+        }
         records[id] = found.record;
         facets[id] = found.facet;
     }

package/dist/store/stateCapture.js

@@ -1,3 +1,4 @@
+import { createStateAccess } from "./stateAccess.js";
 import { CaptureRequestSchema, CaptureBatchRequestSchema, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION, STATE_WRITE_VERSION, assertDerivedState, captureTransform, derivedId, normalizeAssertion, canonicalObjectKey, externalKey, scopePath, stateHash } from "../core/stateContract.js";
 import { isCredentialFreeValue } from "../core/provenance.js";
 import { StateRefusal, stateHomeFor, writeState } from "./stateBinding.js";
@@ -27,6 +28,10 @@ export function captureState(store, input, opts = {}) {
     const id = derivedId({ scope: request.scope, subject: request.subject, transform_version: transform, dependencies: [] });
     const incumbent = store.getStateDirect("derived", id, home);
     if (incumbent) {
+        if (!createStateAccess(store, request.principal, opts).canRead(incumbent))
+            throw new StateRefusal("outside-grants", "record unavailable or operation not permitted");
+        if (request.visibility && stateHash(request.visibility) !== stateHash(incumbent.visibility ?? null))
+            throw new StateRefusal("conflict", "capture already exists with different visibility; use write with expected_version to change its audience");
         assertDerivedState(incumbent);
         if (incumbent.transform_version !== transform || scopePath(incumbent.scope) !== scopePath(request.scope) || incumbent.subject !== request.subject)
             throw new StateRefusal("conflict", "capture identity collision; incumbent preserved");
@@ -38,6 +43,7 @@ export function captureState(store, input, opts = {}) {
     const content = JSON.stringify({ schema: "nuryel.observation-content/1", statement, relevance: request.relevance,
         evidence: evidence.map(e => ({ source: externalKey(e.ref), excerpt: e.excerpt })), captured_by: request.principal.id });
     const record = {
+        ...(request.visibility ? { visibility: request.visibility } : {}),
         schema: "nuryel.derived/1", scope: request.scope, subject: request.subject, content, content_hash: stateHash(content),
         dependencies: refs.map(ref => ({ kind: "external", ref })), transform_version: transform,
         computed_at: (opts.now ?? (() => new Date()))().toISOString(), valid_to: null, state: "unknown",
@@ -65,6 +71,8 @@ export function captureBatchState(store, input, opts = {}) {
         for (const [index, review] of (request.reviews ?? []).entries()) {
             try {
                 const record = store.getStateDirect("derived", review.record_id, home);
+                if (record && !createStateAccess(store, request.principal, opts).canWrite(record))
+                    throw new StateRefusal("outside-grants", "record unavailable or operation not permitted");
                 if (!record || scopePath(record.scope) !== scopePath(request.scope) || !record.transform_version.startsWith('agent-capture/1:'))
                     throw new StateRefusal('conflict', 'captured observation is absent from this partition');
                 if (!isCredentialFreeValue(review.reason))
@@ -95,7 +103,7 @@ export function captureBatchState(store, input, opts = {}) {
                 const at = (opts.now ?? (() => new Date()))().toISOString();
                 const result = writeState(store, { schema: STATE_WRITE_VERSION, principal: request.principal, scope: request.scope, facet: 'derived',
                     record: { ...record, state: 'stale', review: { by: request.principal.id, at, previous_hash: review.expected_hash, reason: review.reason, evidence } },
-                    expected_version: review.expected_hash, idempotency_key: `observation-review:${identity}`, cause: { kind: 'external', ref: evidence[0].ref } }, { now: opts.now, ledgerCache, deferReindex: true });
+                    expected_version: review.expected_hash, idempotency_key: `observation-review:${identity}`, cause: { kind: 'external', ref: evidence[0].ref } }, { now: opts.now, additionalStores: opts.additionalStores, ledgerCache, deferReindex: true });
                 changed ||= result.outcome !== 'replayed';
                 reviews.push({ index, status: 'saved', result });
             }
@@ -113,7 +121,7 @@ export function captureBatchState(store, input, opts = {}) {
                         throw new StateRefusal("malformed", `evidence source index ${e.source} is absent`);
                     return { ...source, excerpt: e.excerpt };
                 });
-                const result = captureState(store, { schema: STATE_CAPTURE_VERSION, principal: request.principal, scope: request.scope, ...observation, evidence }, { now: opts.now, sourceHashes, ledgerCache, deferReindex: true });
+                const result = captureState(store, { schema: STATE_CAPTURE_VERSION, principal: request.principal, scope: request.scope, ...observation, evidence }, { now: opts.now, additionalStores: opts.additionalStores, sourceHashes, ledgerCache, deferReindex: true });
                 changed ||= result.outcome !== "replayed";
                 results.push({ index, status: "saved", result });
             }

package/dist/store/stateError.d.ts

@@ -0,0 +1,12 @@
+/** Stable typed refusals shared by bindings and partition validation. */
+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);
+}

package/dist/store/stateError.js

@@ -0,0 +1,12 @@
+/** Stable typed refusals shared by bindings and partition validation. */
+export class StateRefusal extends Error {
+    code;
+    conflict;
+    constructor(code, message, conflict = null) {
+        super(message);
+        this.code = code;
+        this.conflict = conflict;
+        this.name = "StateRefusal";
+    }
+}
+//# sourceMappingURL=stateError.js.map

package/dist/store/statePartition.d.ts

@@ -0,0 +1,9 @@
+import type { HunchStore } from './hunchStore.js';
+import { type Scope } from '../core/stateContract.js';
+export declare function partitionDeclarationOf(store: HunchStore): Scope & {
+    required_capabilities?: string[];
+};
+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 recordScope: (record: unknown, repo: Scope) => Scope;

package/dist/store/statePartition.js

@@ -0,0 +1,30 @@
+import { StateRefusal } from "./stateError.js";
+/** Partition identity and upgrade gate, re-read for every state operation. */
+import { basename, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { hunchPaths } from '../core/paths.js';
+import { ScopeSchema, PartitionDeclarationSchema } from '../core/stateContract.js';
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
+export function partitionDeclarationOf(store) {
+    const declared = join(hunchPaths(store.publicRoot).hunch, "partition.json");
+    if (existsSync(declared)) {
+        const parsed = PartitionDeclarationSchema.safeParse(JSON.parse(readFileSync(declared, "utf8")));
+        if (!parsed.success)
+            throw new StateRefusal("unsupported", `${declared} does not declare a supported partition scope or capabilities`);
+        return parsed.data;
+    }
+    const raw = basename(store.publicRoot).replace(/[^A-Za-z0-9._:@+-]/g, "-").replace(/^[^A-Za-z0-9]+/, "");
+    const id = TOKEN.test(raw) ? raw : "repository";
+    return { kind: "repository", id };
+}
+export function partitionOf(store) {
+    const declaration = partitionDeclarationOf(store);
+    return { kind: declaration.kind, id: declaration.id };
+}
+/** @deprecated name kept for callers written before served partitions; same value as partitionOf. */
+export const repositoryScope = partitionOf;
+export const recordScope = (record, repo) => {
+    const parsed = ScopeSchema.safeParse(record.scope);
+    return parsed.success ? parsed.data : repo;
+};
+//# sourceMappingURL=statePartition.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.32.8",
+  "version": "1.33.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -27,6 +27,10 @@
       "default": "./dist/projectDna.js"
     },
     "./state": "./dist/client/state.js",
+    "./state-proof": {
+      "types": "./dist/client/stateProof.d.ts",
+      "default": "./dist/client/stateProof.js"
+    },
     "./reports": {
       "types": "./dist/taskReports.d.ts",
       "default": "./dist/taskReports.js"

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.32.8",
+  "version": "1.33.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.32.8",
+      "version": "1.33.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {