@davesheffer/hunch 1.27.0 → 1.29.0

package/README.md

@@ -1,25 +1,27 @@
 # Hunch
 
-## Your repo remembers why — and teaches every coding agent how the project works.
+## Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-Every new AI coding session can read your code. It cannot automatically see why your team chose this design, which alternative already failed, what an odd-looking line protects, or how this repository expects work to be explained and reviewed.
+Every employee is getting an agent. Each one reads the code, the CRM, the mail thread, the chat, and forms its own opinion about what was decided, what was done and what is still owed. Two agents, two slightly different realities. Neither is wrong. Both are guesses, made fresh, from raw material.
 
-That is how settled decisions get reopened, fixed bugs return, and technically plausible changes arrive feeling foreign to the project.
+An organization cannot run on guesses. It runs on state: this was decided, this rule is in force, this action happened and was verified, this promise is due Thursday, this summary is current and rests on these sources. Hunch holds that state in git, refuses it when it contradicts, and delivers it to Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and any other MCP client before the agent answers or edits.
 
-**Hunch is evidence-backed deterministic project intelligence for the AI coding tools you already use.** It gives Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and other MCP clients the same durable understanding of your codebase:
+**Hunch started as engineering memory for coding agents** and still is: why the code is shaped this way, which alternative already failed, what an odd-looking line protects, what depends on the code about to change, and which trusted decisions, fixes and architectural boundaries a change must preserve. The same graph now holds organizational state for operations agents too (see [Deterministic organizational state](#deterministic-organizational-state)).
 
-- why the code is shaped this way;
-- how the repository communicates, reviews and builds;
-- what depends on the code about to change; and
-- which trusted decisions, fixes and architectural boundaries the result must preserve.
+## Why Hunch, not another memory layer
 
-For precise rules your team has explicitly trusted, the promise is **Never Twice**: an agent may propose a different direction, but it cannot quietly re-make a decided decision or re-introduce a fixed failure without Hunch surfacing the conflict and its evidence.
+Memory optimizes recall. State optimizes refusal. Hunch competes for the deterministic state layer from the organizational side, and every point below is a property you can verify in this repository rather than a claim:
 
-Memory starts advisory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
+- **Git is the source of truth.** Every fact is a JSON file under `.hunch/`, every change a commit: diffable, PR-reviewable, revertable, mergeable, never locked in a vendor database. SQLite is only a derived index.
+- **Refusal, not convergence.** One live decision per topic. A second contradicting record is refused at write time with the incumbent named, and a supersede target must still be open. Diverging writes are not merged later.
+- **Organization drawers with a key per agent.** Repository, user, team and organization partitions; the bearer key resolves the principal and decides visibility before anything is looked up.
+- **Receipts and commitments are facts.** What was actually done in an external system, verified or not, and who owes what by when, readable by any agent with the key.
+- **Never Twice.** A human correction becomes an enforced rule, not a one-session memory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
+- **The code spoke.** Decisions, constraints and bug lineage are checked against the code deterministically, with no model in the block path. No state-layer peer has it.
 
 ## Start in five minutes
 
@@ -144,19 +146,19 @@ hunch check --staged --strict
 
 Captured memory cannot silently hard-block on its own.
 
-## Deterministic organizational state — next product direction
+## Deterministic organizational state
 
-Repository memory solves one version of a larger problem.
+Repository memory solves one version of a larger problem, and since 1.25.0 Hunch ships the larger one.
 
 As organizations give every employee an agent that can work across CRM, email, messaging, repositories and other tools, the agents become probabilistic writers/readers of the same organization. If each one independently reconstructs what was decided, what was already done or what is still owed, the organization gets multiple conflicting realities.
 
-The active roadmap asks whether Hunch can become the deterministic state layer between those agents and the organization:
+Hunch is the deterministic state layer between those agents and the organization:
 
 > **Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.**
 
 The target is **one product, one authorized state graph and one versioned state contract** across repository, user, team and organization scopes.
 
-Planned state includes:
+The state it holds:
 
 - decisions currently in force;
 - verified action receipts / what was done;
@@ -203,7 +205,9 @@ user:david --root <dir> --principal sofia@david` declares a partition and mints
 client is `import { createStateClient } from "@davesheffer/hunch/state"`. This folds the separate
 Hunch Memory service into Hunch.
 
-Read [Deterministic organizational state](docs/deterministic-state.md) and the [roadmap](ROADMAP.md).
+As of 1.27.0 a fourth verb, `records`, lists a subject's records for the first writers, and the per-scope ledger compacts and merges across clones. As of 1.28.0 reads are a union across writers, a supersede target must still be open (two racing writers can no longer leave two current records), state records are searchable and delivered by subject, and subjects are keyed by the external record rather than by the agent. Proven on an emulated organization: three agents over ten clinics and a generated year of mail, chat and CRM, one organization drawer, 96 cited summaries, 24 verified receipts, 24 commitments, zero contradictions.
+
+Read [Deterministic organizational state](docs/deterministic-state.md), the [roadmap](ROADMAP.md) and the dated [competitive landscape](docs/competitive-landscape.md).
 
 ### Naming
 
@@ -216,7 +220,7 @@ The current release can keep a team's **repository-scoped** memory in a dedicate
 Today Hunch does not host that shared Git repository; teammates/CI use normal Git access and one maintainer connects it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.3
+npm i -g @davesheffer/hunch@1.28.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -226,7 +230,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.3
+npm i -g @davesheffer/hunch@1.28.0
 git pull
 hunch init
 hunch doctor

package/dist/cli/index.js

@@ -45,17 +45,19 @@ import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
-import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
+import { installPostCommitHook, installPreCommitHook, installPostMergeHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
-import { updateClaudeMd } from "../integrations/claudemd.js";
+import { updateClaudeMd, renderHunchSection } from "../integrations/claudemd.js";
+import { classifyGroundingBlock, describeGroundingFreshness } from "../core/groundingLag.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
-import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
+import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding, GROUNDING_DOC_PATHS } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
-import { formatContext, formatStructure } from "../core/format.js";
+import { formatContext, formatSearchHit, formatStructure } from "../core/format.js";
+import { isStateKind, renderStateLine, stateSupplements } from "../core/stateDelivery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -281,6 +283,8 @@ program
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
+        const pm = installPostMergeHook(root, inv.shell);
+        console.log(`  ✓ post-merge hook ${pm.action} (re-syncs grounding docs after a merge that brought memory in)`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
         // touched directly OR via blast radius, never blocks). Opt out with
         // --no-enforce; --enforce-strict makes blocking near/direct hits fail the commit.
@@ -1320,7 +1324,7 @@ program
     else {
         console.log(`Top matches for "${q}"${how}:\n`);
         for (const h of hits)
-            console.log(`• [${h.kind}] ${h.ref} — ${h.title}\n    ${h.snippet}`);
+            console.log(formatSearchHit(h, isStateKind(h.kind) ? store.resolve(h.ref)?.record : undefined));
     }
     store.close();
 });
@@ -4059,12 +4063,24 @@ program
         !ctx.findings.length &&
         !ctx.landscape?.resources.length &&
         !ctx.landscape?.relationships.length;
+    // The "State" section (nuryel.state/1): current derived, in-force commitments, latest
+    // receipts matching the target — the same slice and render as hunch_context.
+    const slice = asOf ? null : store.stateSlice(target);
+    const stateGrounding = slice ? stateSupplements(slice, target) : [];
     if (empty && !asOf) {
-        const hits = store.rankedSearch(target, 8);
-        if (hits.length) {
+        const hits = store.rankedSearch(target, 8).filter((h) => !isStateKind(h.kind));
+        if (hits.length || stateGrounding.length) {
             console.log(`No file/symbol resolves for "${target}" — closest graph matches instead:\n`);
             for (const h of hits)
                 console.log(`• ${h.ref} — ${h.title}\n    ${h.snippet}`);
+            if (slice) {
+                const stateHits = [...slice.derived, ...slice.commitments, ...slice.receipts];
+                if (stateHits.length) {
+                    console.log(`${hits.length ? "\n" : ""}State (nuryel.state/1):`);
+                    for (const hit of stateHits)
+                        console.log(`• ${renderStateLine(hit.kind, hit.record)}`);
+                }
+            }
             console.log(`\n(For a file/symbol brief use a concrete target; for free-text this is what \`hunch query\` returns.)`);
             store.close();
             return;
@@ -4077,6 +4093,7 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
+        supplements: stateGrounding,
     }));
     store.close();
 });
@@ -5454,6 +5471,79 @@ program
         store.close();
     }
 });
+// ---- grounding (the committed grounding docs vs the PUBLIC graph) -------------
+const GROUNDING_START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
+const GROUNDING_END = "<!-- HUNCH:END -->";
+function groundingBlockContent(text) {
+    const i = text.indexOf(GROUNDING_START);
+    const j = text.indexOf(GROUNDING_END);
+    if (i === -1 || j === -1 || j < i)
+        return null;
+    return text.slice(i + GROUNDING_START.length, j).trim();
+}
+program
+    .command("grounding")
+    .description("Check the committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions, hunch.mdc, hunch.md) against what the PUBLIC graph generates — direction-aware: counts that merely LAG a merge are reported, counts AHEAD of the store (a record never committed) or divergent prose fail. --refresh regenerates every existing doc from the public store (never the overlay union, never a doc the project lacks). Exits 1 on ahead/diverged unless refreshed.")
+    .option("--refresh", "regenerate the existing grounding docs from the public store (what the post-merge hook and the release remedy run)")
+    .option("--json", "machine-readable verdicts")
+    .option("--quiet", "print nothing on success")
+    .action((opts) => {
+    const root = findRoot();
+    // PUBLIC-ONLY by construction, exactly as the release gate and the freshness test
+    // read it: HUNCH_PRIVATE_DIR at an empty overlay beats .hunch/local.json and the
+    // shared pointer, so a dev machine with an overlay attached can never write union
+    // counts into a committed public doc.
+    const emptyPrivate = mkdtempSync(join(tmpdir(), "hunch-grounding-public-"));
+    const prior = process.env.HUNCH_PRIVATE_DIR;
+    process.env.HUNCH_PRIVATE_DIR = emptyPrivate;
+    const store = new HunchStore(hunchPaths(root));
+    try {
+        const rendered = renderHunchSection(store, root);
+        const generated = groundingBlockContent(rendered) ?? rendered.trim();
+        const verdicts = GROUNDING_DOC_PATHS.map((rel) => {
+            const file = join(root, ...rel.split("/"));
+            if (!existsSync(file))
+                return { doc: rel, verdict: { kind: "absent" } };
+            const committed = groundingBlockContent(readFileSync(file, "utf8"));
+            if (committed === null)
+                return { doc: rel, verdict: { kind: "diverged", reason: "no managed HUNCH block" } };
+            return { doc: rel, verdict: classifyGroundingBlock(committed, generated) };
+        });
+        const refreshed = opts.refresh ? refreshExistingGrounding(root, store) : [];
+        const failing = verdicts.filter((v) => v.verdict.kind === "ahead" || v.verdict.kind === "diverged");
+        const lagging = verdicts.filter((v) => v.verdict.kind === "lagging");
+        if (opts.json) {
+            console.log(JSON.stringify({ docs: verdicts, refreshed, ok: opts.refresh ? true : failing.length === 0 }, null, 2));
+        }
+        else if (opts.refresh) {
+            if (!opts.quiet)
+                console.log(refreshed.length ? `grounding refreshed: ${refreshed.join(", ")}` : "grounding already fresh — nothing to regenerate");
+        }
+        else {
+            for (const v of verdicts) {
+                if (v.verdict.kind === "absent")
+                    continue;
+                if (v.verdict.kind === "fresh" && opts.quiet)
+                    continue;
+                console.log(`${v.verdict.kind === "fresh" ? "✓" : v.verdict.kind === "lagging" ? "·" : "✗"} ${describeGroundingFreshness(v.doc, v.verdict)}`);
+            }
+            if (!opts.quiet && !failing.length) {
+                console.log(lagging.length
+                    ? `\n${lagging.length} doc(s) lag a merge — transient; the next capture commit or \`hunch grounding --refresh\` heals it.`
+                    : "✓ grounding docs are fresh.");
+            }
+        }
+        if (!opts.refresh && failing.length)
+            process.exitCode = 1;
+    }
+    finally {
+        store.close();
+        process.env.HUNCH_PRIVATE_DIR = prior;
+        if (prior === undefined)
+            delete process.env.HUNCH_PRIVATE_DIR;
+        rmSync(emptyPrivate, { recursive: true, force: true });
+    }
+});
 // ---- findings (the open-observations ledger) --------------------------------
 program
     .command("findings")

package/dist/cli/serve.js

@@ -57,7 +57,7 @@ export function registerServeCommands(program) {
     });
     serve.command("init")
         .description("Declare a partition directory and mint a principal token (printed once; only its hash is stored)")
-        .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:ylm")
+        .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:acme")
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
         .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")

package/dist/core/format.js

@@ -1,7 +1,18 @@
 import { buildDeliveryEnvelope } from "./delivery.js";
+import { isStateKind, renderStateLine } from "./stateDelivery.js";
 export function formatContext(ctx, options = {}) {
     return buildDeliveryEnvelope(ctx, options).text;
 }
+/** One search hit as `hunch query` / hunch_query print it (headline + indented detail line).
+ *  Graph records keep their `[kind] id — title` shape; a nuryel.state/1 hit renders through
+ *  renderStateLine (`[commitment/in_force] customer:Site:7 — "send report" due … (owner …)`)
+ *  with the record id on the detail line, so both readers say the same thing. */
+export function formatSearchHit(hit, record) {
+    if (isStateKind(hit.kind) && record) {
+        return `• ${renderStateLine(hit.kind, record)}\n    ${hit.ref}`;
+    }
+    return `• [${hit.kind}] ${hit.ref} — ${hit.title}\n    ${hit.snippet}`;
+}
 /** Render a StructureView as a compact orientation brief (hunch_structure). */
 export function formatStructure(v) {
     const NL = "\n";

package/dist/core/groundingLag.js

@@ -0,0 +1,82 @@
+/**
+ * Grounding-block freshness classification (fnd_c402046ac7).
+ *
+ * The committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions,
+ * hunch.mdc, hunch.md) carry a managed block whose first sentence states the
+ * public store's RECORD COUNTS. Those counts are a pure function of .hunch/*.json,
+ * so two branches that each capture one decision both regenerate the very same
+ * "N+1 decisions" line. Git merges identical lines silently, the merged store holds
+ * N+2, and the committed doc is one behind — with no conflict, no hook (the merge
+ * happened on the forge) and no human error. Every release-gate red of that class
+ * (PR #128, #135, v1.26.2's first run) was this lag.
+ *
+ * The lag is transient and self-healing: the next capture commit folds the
+ * regenerated docs in (refreshCommittableGrounding), and the release gate's
+ * repository-index stage regenerates them in the worktree and already treats the
+ * dirt as memory churn. What must STILL fail is a doc that is genuinely wrong:
+ *
+ *   - prose in the block differs (a hand edit, a stale renderer, a template change);
+ *   - an append-only count is AHEAD of the store: the doc counted a record the
+ *     repository does not carry — the never-committed Video component of
+ *     fnd_6391b4242f, the only defect the counts ever caught.
+ *
+ * So the rule is direction-aware and deterministic: decisions, bugs, constraints,
+ * components and policies only accrue, so a doc may lag behind them (merge) but never
+ * run ahead (missing record). Open findings move both ways (a finding resolved on one
+ * branch, a finding recorded on another), so a differing findings count alone is lag.
+ */
+const COUNTS_RE = /\*\*(\d+) decisions?, (\d+) bugs?, (\d+) constraints?, (\d+) components?, (\d+) polic(?:y|ies)(?:, (\d+) open findings?)?\*\*/;
+/** Record kinds whose committed count may only ever lag behind the store. */
+export const APPEND_ONLY_COUNT_KINDS = ["decisions", "bugs", "constraints", "components", "policies"];
+export function parseGroundingCounts(block) {
+    const m = COUNTS_RE.exec(block);
+    if (!m)
+        return null;
+    return {
+        match: m[0],
+        counts: {
+            decisions: Number(m[1]),
+            bugs: Number(m[2]),
+            constraints: Number(m[3]),
+            components: Number(m[4]),
+            policies: Number(m[5]),
+            findings: m[6] === undefined ? 0 : Number(m[6]),
+        },
+    };
+}
+/** Classify a committed managed block against the one the graph generates NOW.
+ *  Both inputs are block CONTENT (markers stripped, trimmed). */
+export function classifyGroundingBlock(committed, generated) {
+    if (committed === generated)
+        return { kind: "fresh" };
+    const c = parseGroundingCounts(committed);
+    const g = parseGroundingCounts(generated);
+    if (!c)
+        return { kind: "diverged", reason: "the committed block carries no record-counts sentence" };
+    if (!g)
+        return { kind: "diverged", reason: "the generated block carries no record-counts sentence" };
+    const withoutCounts = (text, match) => text.replace(match, "<counts>");
+    if (withoutCounts(committed, c.match) !== withoutCounts(generated, g.match)) {
+        return { kind: "diverged", reason: "the block differs outside the record-counts sentence" };
+    }
+    const ahead = APPEND_ONLY_COUNT_KINDS.filter((k) => c.counts[k] > g.counts[k]);
+    if (ahead.length)
+        return { kind: "ahead", committed: c.counts, generated: g.counts, ahead };
+    const behind = Object.keys(g.counts).filter((k) => c.counts[k] !== g.counts[k]);
+    return { kind: "lagging", committed: c.counts, generated: g.counts, behind };
+}
+/** One human line per verdict — shared by the freshness test and `hunch grounding`. */
+export function describeGroundingFreshness(doc, verdict) {
+    const delta = (a, b, kinds) => kinds.map((k) => `${k} ${a[k]} → ${b[k]}`).join(", ");
+    switch (verdict.kind) {
+        case "fresh":
+            return `${doc}: fresh`;
+        case "lagging":
+            return `${doc}: counts lag the store (${delta(verdict.committed, verdict.generated, verdict.behind)}) — records merged in behind the doc; heals on the next capture or \`hunch grounding --refresh\``;
+        case "ahead":
+            return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) — the doc counted a record this repository does not carry; commit the missing .hunch/ record or regenerate`;
+        case "diverged":
+            return `${doc}: stale — ${verdict.reason}; regenerate with \`hunch grounding --refresh\` and commit`;
+    }
+}
+//# sourceMappingURL=groundingLag.js.map

package/dist/core/stateContract.js

@@ -56,10 +56,15 @@ export const PrincipalSchema = z.object({
 }).strict();
 export const STATE_FACETS = ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
 // ---- verbs ------------------------------------------------------------------------------
+/** Union read: the partitions a principal wants in ONE answer. `scope` stays required (it is the
+ *  primary partition; its envelope and receipt lead the response). An entry the principal is not
+ *  granted is NAMED in `denied_scopes` — it never refuses the whole call, and is never described. */
+export const ReadScopesSchema = z.array(ScopeSchema).min(1).max(64);
 export const ReadRequestSchema = z.object({
     schema: z.literal(STATE_READ_VERSION),
     principal: PrincipalSchema,
     scope: ScopeSchema,
+    scopes: ReadScopesSchema.optional(),
     subject: z.string().max(512).optional(),
     task: z.string().max(4096).optional(),
     profile: z.enum(DELIVERY_PROFILES).optional(),
@@ -92,6 +97,12 @@ export const ReadResponseSchema = z.object({
     /** The records behind every ref in `state_of_record`, by id, so a consumer can answer from
      *  the drawer without a second lookup. Additive; absent when there is no subject. */
     records: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    /** Union read (additive): the partitions actually read, primary first. Absent on a
+     *  single-partition read. */
+    scopes: z.array(ScopeSchema).max(64).optional(),
+    /** Union read (additive): one delivery receipt per partition read; `receipt_id` above stays
+     *  the primary's. */
+    receipts: z.array(z.object({ scope: ScopeSchema, receipt_id: z.string().regex(/^hdr_[a-f0-9]{24}$/) }).strict()).max(64).optional(),
 }).strict();
 export const WriteRequestSchema = z.object({
     schema: z.literal(STATE_WRITE_VERSION),
@@ -102,6 +113,10 @@ export const WriteRequestSchema = z.object({
     idempotency_key: z.string().min(8).max(256),
     expected_version: z.union([z.string().max(256), z.number().int().nonnegative()]).nullable().default(null),
     supersedes: z.string().max(2048).optional(),
+    /** Why this write happened, when it is not the writer's own doing (additive): an external
+     *  source moved. A derived record written back as `stale` with this cause emits an
+     *  `invalidated` change naming the pointer — the `changed` facet, finally written by someone. */
+    cause: z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict().optional(),
 }).strict();
 export const DURABILITY = ["pushed", "committed", "local"];
 export const WriteResultSchema = z.object({
@@ -219,6 +234,7 @@ export const STATE_INVARIANTS = [
     { id: "one-live-decision-per-topic", statement: "A second live decision on a topic is refused with the incumbent named; supersession is explicit." },
     { id: "external-truth-stays-external", statement: "External systems remain authoritative for their own content; Nuryel holds credential-free pointers, versions and hashes, never mirrored bodies." },
     { id: "derived-state-carries-dependencies", statement: "A derived statement without dependencies cannot be invalidated and is therefore not state." },
+    { id: "derived-state-writer-owns-currentness", statement: "No source writes the drawer. The writer of a derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. An agent that will not do this must not write derived state." },
 ];
 const grantKey = (scope) => scopePath(scope);
 /** authorization-before-retrieval, checked on the way OUT as well: nothing in a read response
@@ -236,6 +252,14 @@ export function assertReadWithinGrants(principal, response) {
         if (granted.has(grantKey(denied)))
             throw new Error(`denied scope ${grantKey(denied)} is actually granted — the response is inconsistent`);
     }
+    for (const read of response.scopes ?? []) {
+        if (!granted.has(grantKey(read)))
+            throw new Error(`read scope ${grantKey(read)} is outside the principal's grants`);
+    }
+    for (const receipt of response.receipts ?? []) {
+        if (!granted.has(grantKey(receipt.scope)))
+            throw new Error(`receipt for scope ${grantKey(receipt.scope)} is outside the principal's grants`);
+    }
 }
 /** provenance-on-every-write + scope agreement between the envelope and the record. */
 export function assertWriteWellFormed(request) {

package/dist/core/stateDelivery.js

@@ -0,0 +1,179 @@
+export const STATE_KINDS = ["receipts", "commitments", "derived", "entities", "relationships"];
+const STATE_KIND_SET = new Set(STATE_KINDS);
+export function isStateKind(kind) {
+    return STATE_KIND_SET.has(kind);
+}
+/** Singular facet label used in renders: `[commitment/in_force]`, `[derived/current]`. */
+const FACET_LABEL = {
+    receipts: "receipt",
+    commitments: "commitment",
+    derived: "derived",
+    entities: "entity",
+    relationships: "relationship",
+};
+/** Liveness per kind, mirroring readState's state_of_record predicates exactly
+ *  (derived `current` with an open window; commitment open/waiting with an open window;
+ *  receipt succeeded/verified; entity active; a relationship is always current). */
+export function stateLiveness(kind, record) {
+    switch (kind) {
+        case "derived": {
+            const d = record;
+            if (d.valid_to != null)
+                return { label: "superseded", live: false };
+            return { label: d.state, live: d.state === "current" };
+        }
+        case "commitments": {
+            const c = record;
+            if (c.status === "open" || c.status === "waiting") {
+                return c.valid_to == null ? { label: "in_force", live: true } : { label: "superseded", live: false };
+            }
+            return { label: c.status, live: false };
+        }
+        case "receipts": {
+            const r = record;
+            return { label: r.state, live: r.state === "succeeded" || r.state === "verified" };
+        }
+        case "entities": {
+            const e = record;
+            return { label: e.lifecycle, live: e.lifecycle === "active" };
+        }
+        case "relationships":
+            return { label: "current", live: true };
+    }
+}
+/** The subject key a reader would type: the commitment/derived subject, the receipt's target
+ *  object (`event:10042`), the entity id, or the relationship's `from` endpoint. */
+export function stateSubject(kind, record) {
+    switch (kind) {
+        case "derived": return record.subject;
+        case "commitments": return record.subject;
+        case "receipts": {
+            const r = record;
+            return `${r.target.object_type}:${r.target.object_key}`;
+        }
+        case "entities": return record.id;
+        case "relationships": return record.from;
+    }
+}
+/** The instant that orders "latest first": computed_at, valid_from, verified_at ?? occurred_at,
+ *  updated_at. Relationships carry no clock and sort last among equals. */
+export function stateObservedAt(kind, record) {
+    switch (kind) {
+        case "derived": return record.computed_at;
+        case "commitments": return record.valid_from;
+        case "receipts": {
+            const r = record;
+            return r.verified_at ?? r.occurred_at;
+        }
+        case "entities": return record.updated_at;
+        case "relationships": return "";
+    }
+}
+/** The FTS document for a state record: title = the subject key (so an id query hits the
+ *  title column, which the snippet and LIKE fallback both prefer), body = the human words plus
+ *  the actor/owner, the status label and the dates. Every reader's query — a subject id, a
+ *  phrase from a summary, an action kind, a principal — lands on one of these. */
+export function stateSearchDoc(kind, record) {
+    const { label } = stateLiveness(kind, record);
+    const subject = stateSubject(kind, record);
+    switch (kind) {
+        case "derived": {
+            const d = record;
+            return { title: subject, body: `${d.content} ${label} ${d.transform_version} ${d.computed_at.slice(0, 10)}` };
+        }
+        case "commitments": {
+            const c = record;
+            return { title: subject, body: `${c.title} ${c.evidence_excerpt ?? ""} ${label} ${c.status} owner ${c.owner} due ${c.due}` };
+        }
+        case "receipts": {
+            const r = record;
+            return {
+                title: subject,
+                body: `${r.action_kind} ${r.actor} ${label} ${r.target.system} ${r.target.object_type} ${r.target.object_key} ${r.occurred_at.slice(0, 10)} ${r.invalidates.join(" ")}`,
+            };
+        }
+        case "entities": {
+            const e = record;
+            const attrs = Object.entries(e.attributes).map(([k, v]) => `${k} ${v ?? ""}`).join(" ");
+            return { title: subject, body: `${e.name} ${e.kind} ${label} ${attrs}` };
+        }
+        case "relationships": {
+            const r = record;
+            return { title: subject, body: `${r.type} ${r.to} ${r.reason}` };
+        }
+    }
+}
+const DERIVED_HEADLINE_CHARS = 120;
+function oneLine(value, max) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+/** The one-line render shared by hunch_query, `hunch query` and the context "State" section:
+ *    [commitment/in_force] customer:Site:7 — "send report" due 2026-09-11 (owner sofia)
+ *    [derived/current] customer:Site:7 — <first 120 chars of the summary>
+ *    [receipt/verified] event:10042 — events_add_actions by sofia@david 2026-09-08 */
+export function renderStateLine(kind, record) {
+    const { label } = stateLiveness(kind, record);
+    const head = `[${FACET_LABEL[kind]}/${label}] ${stateSubject(kind, record)} — `;
+    switch (kind) {
+        case "derived":
+            return `${head}${oneLine(record.content, DERIVED_HEADLINE_CHARS)}`;
+        case "commitments": {
+            const c = record;
+            return `${head}"${oneLine(c.title, 100)}" due ${c.due} (owner ${c.owner})`;
+        }
+        case "receipts": {
+            const r = record;
+            return `${head}${r.action_kind} by ${r.actor} ${(r.verified_at ?? r.occurred_at).slice(0, 10)}`;
+        }
+        case "entities": {
+            const e = record;
+            return `${head}${oneLine(e.name, 100)} (${e.kind})`;
+        }
+        case "relationships": {
+            const r = record;
+            return `${head}${r.type} → ${r.to}${r.reason ? ` (${oneLine(r.reason, 80)})` : ""}`;
+        }
+    }
+}
+/** Bounded caps for the context "State" section: current derived, in-force commitments,
+ *  latest receipts. Deliberately small — a brief, not a dump; `nuryel_read` is the full view. */
+export const STATE_SLICE_CAPS = { derived: 3, commitments: 5, receipts: 3 };
+/** Deterministic order for a state slice: score (best first), then observed_at DESC (latest
+ *  first), then id ASC. Applied after liveness filtering, before the cap. */
+export function compareStateHits(a, b) {
+    if (a.score !== b.score)
+        return a.score - b.score;
+    const at = stateObservedAt(b.kind, b.record).localeCompare(stateObservedAt(a.kind, a.record));
+    if (at !== 0)
+        return at;
+    return a.record.id.localeCompare(b.record.id);
+}
+/** Supplement priority band for the State section: above Project DNA (425), below
+ *  decision-grounding (1000) and the ranked memory records (which are not supplements). */
+const STATE_SUPPLEMENT_PRIORITY = 500;
+/** Render a state slice as delivery supplements (one header + one line per record) so the
+ *  section shares the context brief's hard budget and receipt like every other grounding.
+ *  Empty slice → no supplements at all: a store with zero state records is byte-identical. */
+export function stateSupplements(slice, target) {
+    const hits = [...slice.derived, ...slice.commitments, ...slice.receipts];
+    if (!hits.length)
+        return [];
+    const out = [{
+            id: "state-of-record",
+            kind: "state",
+            text: `STATE (nuryel.state/1) for "${target}": ${slice.derived.length} current derived, ${slice.commitments.length} in-force commitment(s), ${slice.receipts.length} latest receipt(s). Follow the state of record; nuryel_read(subject) returns the full records.`,
+            priority: STATE_SUPPLEMENT_PRIORITY,
+        }];
+    hits.forEach((hit, index) => {
+        out.push({
+            id: hit.record.id,
+            kind: `state-${FACET_LABEL[hit.kind]}`,
+            text: renderStateLine(hit.kind, hit.record),
+            // Strictly descending so the sort in buildDeliveryEnvelope keeps slice order.
+            priority: STATE_SUPPLEMENT_PRIORITY - 1 - index,
+        });
+    });
+    return out;
+}
+//# sourceMappingURL=stateDelivery.js.map

package/dist/core/stateRecords.js

@@ -46,7 +46,9 @@ export const ExternalRefSchema = z.object({
 }).strict();
 /** What a derived statement rests on. Exactly what a currentness check re-validates. */
 export const DependencyRefSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("record"), id: z.string().regex(TOKEN), record_hash: z.string().regex(SHA256) }).strict(),
+    /** `scope` (additive) points into ANOTHER partition — the repository decision an
+     *  organization-drawer receipt rests on. Absent, the ref is in the record's own partition. */
+    z.object({ kind: z.literal("record"), id: z.string().regex(TOKEN), record_hash: z.string().regex(SHA256), scope: ScopeSchema.optional() }).strict(),
     z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict(),
     z.object({ kind: z.literal("schema"), name: z.string().max(256), fingerprint: z.string().regex(SHA256) }).strict(),
 ]);
@@ -66,6 +68,12 @@ export const ActionReceiptSchema = z.object({
     verified_at: z.string().regex(ISO).optional(),
     result_fingerprint: z.string().regex(SHA256).optional(),
     invalidates: z.array(z.string().max(512)).max(64).default([]),
+    /** What the action rested on (additive): the decision it implements, the change proof for
+     *  the shipped revision, the commitment or incident it answers. Same shape as a derived
+     *  statement's dependencies, so "what does this closure rest on" is one read. A record ref
+     *  in the receipt's own partition is verified by hash on write; a ref into another partition
+     *  is a pointer the reader resolves with `records`, grants first. */
+    rests_on: z.array(DependencyRefSchema).max(64).optional(),
     provenance: ProvenanceSchema,
 }).strict();
 /** committed — an obligation with a due date and an in-force window. */
@@ -80,6 +88,9 @@ export const CommitmentSchema = z.object({
     status: z.enum(["open", "waiting", "done", "cancelled"]),
     source: ExternalRefSchema.optional(),
     evidence_excerpt: z.string().max(900).optional(),
+    /** The receipt that fulfilled this commitment (additive). A closure names what happened:
+     *  the binding refuses a `closed_by` that is not a succeeded/verified receipt on record. */
+    closed_by: z.string().regex(/^nrc_[a-f0-9]{24}$/).optional(),
     valid_from: z.string().regex(ISO),
     valid_to: z.string().regex(ISO).nullable().default(null),
     provenance: ProvenanceSchema,