@davesheffer/hunch 1.39.0 → 1.39.2

package/dist/serve/app.js

@@ -93,6 +93,7 @@ function parseScopeParam(value) {
 }
 export function createServeApp(config, opts = {}) {
     const version = opts.version ?? HUNCH_VERSION;
+    const writeLockTimeoutMs = opts.writeLockTimeoutMs;
     const configFile = config.file;
     const authStateDir = opts.authStateDir ?? (configFile ? resolve(configFile + ".auth") : undefined);
     const stores = new Map();
@@ -125,19 +126,26 @@ export function createServeApp(config, opts = {}) {
     };
     const problemBody = (p) => ({ type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra });
     const sendProblem = (res, p) => { send(res, p.status, problemBody(p), "application/problem+json"); };
-    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results). */
+    const log = opts.log ?? ((line) => { process.stderr.write(`${line}\n`); });
+    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results).
+     *  A contract refusal (4xx) explains itself to the caller. A server-side failure (5xx) does
+     *  not: its message can name lock paths, PIDs, host names or store paths, so the caller gets
+     *  a generic detail and the specifics go to the server log only. */
     const problemOf = (error) => {
         if (error instanceof HttpProblem)
             return error;
         if (error instanceof StateRefusal)
             return problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {});
-        if (error instanceof WriteLockTimeout)
-            return problem(503, "write-lock-timeout", error.message, { "retry-after": 1 });
+        if (error instanceof WriteLockTimeout) {
+            log(`hunch serve: 503 write-lock-timeout: ${error.message}`);
+            return problem(503, "write-lock-timeout", "the partition is busy with another write; retry shortly", { "retry-after": 1 });
+        }
         if (error && typeof error === "object" && error.name === "ZodError") {
             const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
             return problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues });
         }
-        return problem(500, "internal", error.message);
+        log(`hunch serve: 500 internal: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+        return problem(500, "internal", "internal server error");
     };
     /** One authenticated state verb. The REST routes and the MCP tools both call this, so every
      *  rule — grants, the write lock, flushes, refusals — is the same whichever transport carried it. */
@@ -191,20 +199,53 @@ export function createServeApp(config, opts = {}) {
         if (route === "write" || route === "capture" || route === "capture-batch") {
             const { hunchDir } = stateHomeFor(store, scope);
             const opts = { ...accessOptions, flush };
+            const lockOptions = { timeoutMs: writeLockTimeoutMs };
             if (route === "write") {
-                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts));
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts), lockOptions);
                 return { status: result.outcome === "created" ? 201 : 200, payload: result };
             }
             if (route === "capture") {
-                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts));
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts), lockOptions);
                 return { status: result.outcome === "created" ? 201 : 200, payload: result };
             }
-            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts)) };
+            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts), lockOptions) };
         }
         if (route === "subscribe")
             return { status: 200, payload: subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions) };
         return { status: 200, payload: recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions) };
     };
+    /** The bearer/DPoP credential → the principal. Every authenticated route, and health when a
+     *  credential is presented, goes through this one check. */
+    const authenticate = async (req, res, url, activeConfig) => {
+        const authorization = /^(Bearer|DPoP) ([^\s]+)$/i.exec(req.headers.authorization ?? '');
+        const credential = resolveCredential(activeConfig, authorization?.[2]);
+        if (!credential)
+            throw problem(401, 'unauthorized', 'valid credentials are required');
+        const countHeader = (name) => req.rawHeaders.filter((header, index) => index % 2 === 0 && header.toLowerCase() === name).length;
+        if (countHeader('authorization') !== 1 || countHeader('dpop') > 1)
+            throw problem(401, 'invalid_dpop_proof', 'ambiguous authentication headers');
+        if (credential.proof_key) {
+            if (authorization[1].toLowerCase() !== 'dpop')
+                throw problem(401, 'invalid_dpop_proof', 'this credential requires DPoP proof; bearer fallback is disabled');
+            if (!activeConfig.public_origin || !authStateDir)
+                throw problem(503, 'proof-state-unavailable', 'key-bound authentication requires a public origin and persistent proof state');
+            try {
+                await verifyStateProof({ proof: typeof req.headers.dpop === 'string' ? req.headers.dpop : undefined, key: credential.proof_key, method: req.method ?? '', url: activeConfig.public_origin + url.pathname, token: authorization[2], stateDir: authStateDir });
+            }
+            catch (error) {
+                if (error instanceof StateProofError) {
+                    res.setHeader('WWW-Authenticate', `DPoP error="${error.code}", algs="EdDSA"`);
+                    if (error.nonce)
+                        res.setHeader('DPoP-Nonce', error.nonce);
+                    throw problem(401, error.code, error.message);
+                }
+                throw problem(503, 'proof-state-unavailable', 'proof replay state is unavailable; authentication is refused');
+            }
+        }
+        else if (authorization[1].toLowerCase() !== 'bearer' || req.headers.dpop !== undefined)
+            throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
+        return { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
+    };
     const server = createServer(async (req, res) => {
         try {
             let activeConfig;
@@ -222,36 +263,15 @@ export function createServeApp(config, opts = {}) {
                 return res.end(asset[0]);
             }
             if (url.pathname === "/nuryel/v1/health" && req.method === "GET") {
-                return send(res, 200, { ok: true, version, protocol: "nuryel.state/1", partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
-            }
-            const authorization = /^(Bearer|DPoP) ([^\s]+)$/i.exec(req.headers.authorization ?? '');
-            const credential = resolveCredential(activeConfig, authorization?.[2]);
-            if (!credential)
-                throw problem(401, 'unauthorized', 'valid credentials are required');
-            const countHeader = (name) => req.rawHeaders.filter((header, index) => index % 2 === 0 && header.toLowerCase() === name).length;
-            if (countHeader('authorization') !== 1 || countHeader('dpop') > 1)
-                throw problem(401, 'invalid_dpop_proof', 'ambiguous authentication headers');
-            if (credential.proof_key) {
-                if (authorization[1].toLowerCase() !== 'dpop')
-                    throw problem(401, 'invalid_dpop_proof', 'this credential requires DPoP proof; bearer fallback is disabled');
-                if (!activeConfig.public_origin || !authStateDir)
-                    throw problem(503, 'proof-state-unavailable', 'key-bound authentication requires a public origin and persistent proof state');
-                try {
-                    await verifyStateProof({ proof: typeof req.headers.dpop === 'string' ? req.headers.dpop : undefined, key: credential.proof_key, method: req.method ?? '', url: activeConfig.public_origin + url.pathname, token: authorization[2], stateDir: authStateDir });
-                }
-                catch (error) {
-                    if (error instanceof StateProofError) {
-                        res.setHeader('WWW-Authenticate', `DPoP error="${error.code}", algs="EdDSA"`);
-                        if (error.nonce)
-                            res.setHeader('DPoP-Nonce', error.nonce);
-                        throw problem(401, error.code, error.message);
-                    }
-                    throw problem(503, 'proof-state-unavailable', 'proof replay state is unavailable; authentication is refused');
-                }
+                // Liveness is public (a load balancer or proxy probe holds no token). Which
+                // partitions this server hosts is not: their ids name people and organizations.
+                const liveness = { ok: true, version, protocol: "nuryel.state/1" };
+                if (req.headers.authorization === undefined && req.headers.dpop === undefined)
+                    return send(res, 200, liveness);
+                await authenticate(req, res, url, activeConfig);
+                return send(res, 200, { ...liveness, partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
             }
-            else if (authorization[1].toLowerCase() !== 'bearer' || req.headers.dpop !== undefined)
-                throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
-            const principal = { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
+            const principal = await authenticate(req, res, url, activeConfig);
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
                 const scope = parseScopeParam(url.searchParams.get("scope"));
                 const { status, payload } = await dispatch("capabilities", principal, scope ? { scope } : {}, activeConfig);

package/dist/store/hunchStore.d.ts

@@ -5,7 +5,7 @@ import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { type RankingContext, type RankingQuery, type RankingWeights, type SlotOptions, type TaskSelection } from "../core/taskRanking.js";
 import { type VetoTier } from "../core/strictgate.js";
-import { type DiffAnalysis } from "../extractors/diff.js";
+import { type DiffAnalysis, type DiffStatus } from "../extractors/diff.js";
 import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
 import { type ReviewedLandscapeSelection } from "../core/landscapeDelivery.js";
 import { type StateSlice } from "../core/stateDelivery.js";
@@ -384,7 +384,7 @@ export declare class HunchStore {
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
      *  scope-matched constraints, why) so impact and gating can never disagree. */
-    prImpact(files: string[], diff: string): ImpactReport;
+    prImpact(files: string[], diff: string, diffStatus?: DiffStatus): ImpactReport;
     /** Structure view (hunch_structure / hunch structure): serve the indexed shape of
      *  the repo so an agent ORIENTS from the graph instead of running grep/glob rounds.
      *  Resolution: no target -> repo map; a directory -> its files+symbols; a file ->
@@ -446,6 +446,8 @@ export declare class HunchStore {
         strict: boolean;
         lastChange?: (f: string) => string;
         publicOnly?: boolean;
+        /** Completeness of `diff` as produced for a gate (a GateDiff fits). */
+        diffStatus?: DiffStatus;
     }): CheckReport;
     /** Sprawl/"this already exists" guard (ADVISORY, never blocks). A symbol the diff
      *  ADDS whose name already exists in the indexed graph in a file NOT touched by the

package/dist/store/hunchStore.js

@@ -28,7 +28,7 @@ import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
-import { analyzeDiff } from "../extractors/diff.js";
+import { analyzeDiff, diffContentGaps } from "../extractors/diff.js";
 import { selectReviewedLandscape, } from "../core/landscapeDelivery.js";
 import { STATE_KINDS, STATE_SLICE_CAPS, compareStateHits, isStateKind, stateLiveness, stateObservedAt, stateSearchDoc, stateSubject, } from "../core/stateDelivery.js";
 /** Git cannot resolve repository identity from a cwd that does not exist yet.
@@ -1332,7 +1332,7 @@ export class HunchStore {
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
      *  scope-matched constraints, why) so impact and gating can never disagree. */
-    prImpact(files, diff) {
+    prImpact(files, diff, diffStatus) {
         const changed = new Set(files.map(toPosixTarget));
         const blast = new Map();
         for (const f of changed) {
@@ -1344,7 +1344,7 @@ export class HunchStore {
                     blast.set(b.file, b);
             }
         }
-        const report = this.buildCheckReport([...changed], diff, { strict: false });
+        const report = this.buildCheckReport([...changed], diff, { strict: false, diffStatus });
         const decisions = new Map();
         for (const f of changed) {
             for (const d of this.why(f).decisions)
@@ -1639,6 +1639,7 @@ export class HunchStore {
             });
             const directReport = [];
             const addedDepSet = new Set(an.addedDeps);
+            const missingContent = diffContentGaps(diff, opts.diffStatus);
             for (const { c, files: fs } of direct.values()) {
                 const forbids = effectiveForbids(c);
                 if (forbids) {
@@ -1646,11 +1647,27 @@ export class HunchStore {
                     // dep imported / symbol added / pattern matched in scoped code) — not by bare
                     // scope-touch. A commit that touches the scope but doesn't trip it COMPLIES → drop it
                     // (no noise). A real hit blocks WITHOUT the staleness gate: content is verified per
-                    // commit, so file churn can't retract the teeth (dec_e0a36efbf5). Empty diff ⇒ can't
-                    // prove a violation ⇒ treat as clean.
+                    // commit, so file churn can't retract the teeth (dec_e0a36efbf5). A COMPLETE diff with
+                    // no added lines for a file proves nothing was added there ⇒ clean.
                     const scopedAdded = fs.flatMap((f) => an.addedLinesByFile.get(f) ?? []);
-                    if (!matchForbids(forbids, addedDepSet, scopedAdded))
+                    if (!matchForbids(forbids, addedDepSet, scopedAdded)) {
+                        // …but when the diff is truncated, git could not produce it, or a file's content
+                        // could not be read, "no added lines" is not evidence of compliance. A blocking
+                        // rule over such a file is UNEVALUABLE and fails closed under the same strict gate
+                        // a proven hit would face (dec_20db57c576). Advisory/warning rules stay quiet.
+                        const unseen = missingContent ? fs.filter((f) => missingContent.missing(f)) : [];
+                        if (c.severity !== "blocking" || !unseen.length)
+                            continue;
+                        const strictBlocks = isStrictBlocker(c, false);
+                        directReport.push({
+                            id: c.id, severity: c.severity, statement: c.statement, rationale: c.rationale ?? "",
+                            files: fs, strictBlocks,
+                            downgrade: strictBlocks ? undefined : "low-confidence",
+                            unevaluable: { reason: missingContent.reason(unseen), files: unseen },
+                            why: this.causalChain(c.id),
+                        });
                         continue;
+                    }
                     const strictBlocks = isStrictBlocker(c, false);
                     directReport.push({
                         id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",

package/dist/store/stateBinding.js

@@ -26,6 +26,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { join } from "node:path";
 import { z } from "zod";
 import { appendChanges, latestSeqFor, readLedger } from "./changeLedger.js";
+import { STATE_ONLY_FACETS } from "./replay.js";
 import { hunchPaths } from "../core/paths.js";
 import { decisionId } from "../core/ids.js";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
@@ -274,15 +275,18 @@ export function readState(store, input, options = {}) {
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
+                // Match the subject BEFORE admit, as every other facet does: admit names an ungranted
+                // partition in denied_scopes, and only a record that matches may name its partition.
+                // A linked observation must sit in the request's (granted) partition, so it never names one.
+                const direct = isSubject(d.subject) || d.id === subject;
+                const linked = scopePath(recordScope(d, repo)) === scopePath(request.scope) && linkedObservations.get(d.id)?.has(stateHash(d));
+                if (!direct && !linked)
+                    continue;
                 const scope = admit("derived", d);
                 if (!scope)
                     continue;
                 if (request.observed_page && scopePath(scope) !== scopePath(request.scope))
                     continue;
-                const direct = isSubject(d.subject) || d.id === subject;
-                const linked = scopePath(scope) === scopePath(request.scope) && linkedObservations.get(d.id)?.has(stateHash(d));
-                if (!direct && !linked)
-                    continue;
                 if (!direct) {
                     if (d.state === "unknown" && d.valid_to == null)
                         observations.push(d);
@@ -467,6 +471,16 @@ function subjectOf(facet, record) {
         default: return undefined;
     }
 }
+/** The published `ChangeEvent.subject` bound. Record subjects can be longer (a receipt's
+ *  `object_type:object_key`, an entity id, a relationship endpoint, a decision topic); the record
+ *  limits are never lowered and the event limit is never raised (dec_a9bfb5dd8d). */
+const EVENT_SUBJECT_MAX = 512;
+/** The subject an EVENT carries: the record's subject when it fits the event limit, otherwise
+ *  omitted (`subject` is optional). A subscriber still matches the event by `record_id`. */
+function eventSubjectOf(facet, record) {
+    const subject = subjectOf(facet, record);
+    return subject !== undefined && subject.length <= EVENT_SUBJECT_MAX ? subject : undefined;
+}
 /** Which facet a record id belongs to, from its prefix; `null` for a kind-qualified entity id
  *  or an unknown shape (those are looked up across every facet). */
 function facetOfId(id) {
@@ -607,6 +621,29 @@ function closeWindow(store, facet, incumbentId, byId, at, isPrivate) {
     store.putCapture(facet, closed, isPrivate);
     return true;
 }
+/** Validate pending change events against the published event schema without writing anything,
+ *  so a write whose event could not be appended is refused before its record lands (#283). */
+function assertEventsValid(ledger, scope, at, changes) {
+    changes.forEach((change, i) => {
+        const parsed = ChangeEventSchema.safeParse({ schema: STATE_SUBSCRIBE_VERSION, seq: ledger.head_seq + i + 1, at, scope, ...change });
+        if (!parsed.success)
+            throw new StateRefusal("malformed", `change event for ${change.record_id} is malformed: ${parsed.error.issues.map((x) => `${x.path.join(".") || "event"}: ${x.message}`).join("; ")}`);
+    });
+}
+/** The event a replayed write owes the ledger (#282): a state-only record on file that the ledger
+ *  has never seen — no event names it and no idempotency entry references it (compaction drops
+ *  events but keeps the table, so an entry means "known") — was written without its event, by a
+ *  crash between put and append or a refusal after the put. The retry appends it with the hash on
+ *  file. A record the ledger already knows gets no new event. */
+function missingEventFor(ledger, facet, onFile, principal) {
+    if (!STATE_ONLY_FACETS.includes(facet))
+        return [];
+    const id = String(onFile.id);
+    if (latestSeqFor(ledger, id) > 0 || Object.values(ledger.idempotency).some((e) => e.record_id === id))
+        return [];
+    const invalidates = facet === "receipts" && Array.isArray(onFile.invalidates) ? onFile.invalidates : [];
+    return [{ ...(onFile.visibility ? { visibility: onFile.visibility } : {}), facet, record_id: id, record_hash: stateHash(onFile), change: "created", subject: eventSubjectOf(facet, onFile), invalidates, cause: { kind: "write", principal } }];
+}
 /** Normalize + validate the record for its facet; enforce the identity rule (an id, when
  *  given, must be the one the record's facts derive). Returns the canonical record. */
 function normalizeRecord(facet, scope, raw, principal) {
@@ -691,7 +728,17 @@ function writeStateAuthorized(store, input, opts, access) {
     catch (e) {
         throw new StateRefusal(/grants/.test(e.message) ? "outside-grants" : "malformed", e.message);
     }
+    const repo = partitionOf(store);
+    // Legacy kinds carry no partition scope: whatever home they land in, every reader (and the
+    // repository's edit gate) treats them as the store's OWN partition. Written under any other
+    // scope they would silently become that partition's records, so they are refused instead.
+    if (LEGACY_FACETS.has(request.facet) && scopePath(request.scope) !== scopePath(repo)) {
+        throw new StateRefusal("unsupported", `${request.facet} records belong to this store's own partition ${scopePath(repo)}; they cannot be written under ${scopePath(request.scope)} — use a partition-scoped facet (conventions, receipts, commitments, derived, entities, relationships) there`);
+    }
     const { home, hunchDir, isPrivate } = stateHomeFor(store, request.scope);
+    /** Several partitions share one overlay home: a record counts for this write only when it is
+     *  in the write's own partition. */
+    const inScope = (r) => scopePath(recordScope(r, repo)) === scopePath(request.scope);
     const now = (opts.now ?? (() => new Date()))().toISOString();
     const facet = request.facet;
     const getHere = (id) => facet === "derived" || facet === "receipts" || facet === "commitments"
@@ -701,9 +748,40 @@ function writeStateAuthorized(store, input, opts, access) {
         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 id = record.id;
+    /** The normalized PAYLOAD hash: what idempotency recognizes on a re-send. */
+    const hash = stateHash(record);
+    const ledger = opts.ledgerCache?.ledger ?? readLedger(hunchDir, request.scope);
+    if (opts.ledgerCache)
+        opts.ledgerCache.ledger = ledger;
+    const durability = () => opts.flush?.(isPrivate, `nuryel: write ${id}`) ?? "local";
+    /** The result reports the record ON FILE and its hash — the store may enrich a record on put
+     *  (a private-mode decision gains `valid_from`), and a writer that goes on to rest a receipt
+     *  on this record must hold the hash a reader will verify, never a pre-store one. */
+    const result = (outcome, conflict = null, rid = id) => {
+        const onFile = getHere(rid) ?? record;
+        return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: stateHash(onFile), durability: durability(), outcome, conflict, record: onFile });
+    };
+    // Idempotency, exact replay FIRST: the same key with the same payload for the same record is
+    // the retry of a request that already succeeded, and returns what it wrote — before any check
+    // that depends on state changed since (an entity now claiming the subject, a visibility or link
+    // change). Otherwise a writer whose response was lost is refused, re-derives, and duplicates
+    // the record it already holds (#284). A differing payload under the key falls through to every
+    // check and the idempotency refusal below.
+    const seen = ledger.idempotency[request.idempotency_key];
+    if (seen && seen.record_id === id && (seen.record_hash === hash || seen.payload_hash === hash)) {
+        const prior = findRecord(store, seen.record_id)?.record;
+        if (prior && !access.canRead(prior))
+            deny();
+        return result("replayed");
+    }
     const incumbent = getHere(String(record.id));
     if (incumbent && !access.canWrite(incumbent))
         deny();
+    // An id not derived from its scope (an entity, a relationship) can collide with another
+    // partition's record in a shared home: that record is never rewritten from this partition.
+    if (incumbent && !inScope(incumbent))
+        throw new StateRefusal("conflict", `${id} is on record in ${scopePath(recordScope(incumbent, repo))}, not ${scopePath(request.scope)}: a write never moves or rewrites another partition's record`, { incumbent_id: id, reason: "record id held by another partition" });
     const previousVisibility = incumbent?.visibility;
     const nextVisibility = record.visibility;
     if (nextVisibility && home === 'private')
@@ -713,6 +791,10 @@ function writeStateAuthorized(store, input, opts, access) {
     if (supersededRecord) {
         if (!access.canWrite(supersededRecord))
             deny();
+        // Supersession stays inside one partition: closing another partition's record from here would
+        // land its `superseded` event in THIS ledger, invisible to that partition's subscribers.
+        if (!inScope(supersededRecord))
+            throw new StateRefusal("conflict", `supersedes ${request.supersedes} is on record in ${scopePath(recordScope(supersededRecord, repo))}, not ${scopePath(request.scope)}: a write supersedes only a record in its own partition`, { incumbent_id: String(supersededRecord.id), reason: "supersede target in another partition" });
         if (stateHash(supersededVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
             if (supersededVisibility ? supersededVisibility.owner !== request.principal.id : request.principal.kind !== 'human')
                 deny();
@@ -761,30 +843,12 @@ function writeStateAuthorized(store, input, opts, access) {
             replayLink = prior;
         }
     }
-    const id = record.id;
     assertExternalIdentity(store, request.principal, request.scope, facet, record);
-    /** The normalized PAYLOAD hash: what idempotency recognizes on a re-send. */
-    const hash = stateHash(record);
-    const ledger = opts.ledgerCache?.ledger ?? readLedger(hunchDir, request.scope);
-    if (opts.ledgerCache)
-        opts.ledgerCache.ledger = ledger;
-    const durability = () => opts.flush?.(isPrivate, `nuryel: write ${id}`) ?? "local";
-    /** The result reports the record ON FILE and its hash — the store may enrich a record on put
-     *  (a private-mode decision gains `valid_from`), and a writer that goes on to rest a receipt
-     *  on this record must hold the hash a reader will verify, never a pre-store one. */
-    const result = (outcome, conflict = null, rid = id) => {
-        const onFile = getHere(rid) ?? record;
-        return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: stateHash(onFile), durability: durability(), outcome, conflict, record: onFile });
-    };
-    // Idempotency: the same key replays the original; the same key with a different payload
-    // is a refusal, never a second record.
-    const seen = ledger.idempotency[request.idempotency_key];
+    // Idempotency: the same key with a different payload is a refusal, never a second record.
     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
         // wording) is the trap every writer falls into once; the refusal must teach the way out.
         const stored = store.getRec(facet, seen.record_id);
@@ -799,7 +863,7 @@ function writeStateAuthorized(store, input, opts, access) {
             throw new StateRefusal('malformed', 'reviewer must be the initiating principal');
     }
     if (existing && stateHash(existing) === hash) {
-        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
+        appendChanges(hunchDir, request.scope, missingEventFor(ledger, facet, existing, request.principal.id), { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
         return result("replayed");
     }
     if (existing && request.expected_version !== null) {
@@ -811,7 +875,7 @@ function writeStateAuthorized(store, input, opts, access) {
     }
     if (replayLink) {
         const recordHash = stateHash(replayLink);
-        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: replayLink.id, record_hash: recordHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
+        appendChanges(hunchDir, request.scope, missingEventFor(ledger, facet, replayLink, request.principal.id), { key: request.idempotency_key, entry: { record_id: replayLink.id, record_hash: recordHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
         return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: replayLink.id, record_hash: recordHash, record: replayLink, outcome: "replayed", conflict: null, durability: "local" });
     }
     // human-correction-outranks-agent-writes: what a human confirmed, an agent does not rewrite.
@@ -841,7 +905,7 @@ function writeStateAuthorized(store, input, opts, access) {
         };
         const verdict = guard(existing, "overwrite");
         if (verdict === "replay") {
-            appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: stateHash(existing), payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
+            appendChanges(hunchDir, request.scope, missingEventFor(ledger, facet, existing, request.principal.id), { key: request.idempotency_key, entry: { record_id: id, record_hash: stateHash(existing), payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
             return result("replayed");
         }
         if (verdict === "keep-provenance")
@@ -878,7 +942,7 @@ function writeStateAuthorized(store, input, opts, access) {
             }
         }
     }
-    if (supersedes && !store.recsInHome(facet, home).some((r) => r.id === supersedes)) {
+    if (supersedes && !store.recsInHome(facet, home).some((r) => r.id === supersedes && inScope(r))) {
         throw new StateRefusal("conflict", `supersedes ${supersedes} is not a ${facet} record in this partition`, { incumbent_id: supersedes, reason: "supersede target absent" });
     }
     if (supersedes === id)
@@ -892,7 +956,7 @@ function writeStateAuthorized(store, input, opts, access) {
         if (incumbent && "valid_to" in incumbent && incumbent.valid_to !== null) {
             const subject = subjectOf(facet, incumbent);
             const open = store.recsInHome(facet, home)
-                .filter((r) => subjectOf(facet, r) === subject && r.valid_to === null)
+                .filter((r) => inScope(r) && subjectOf(facet, r) === subject && r.valid_to === null)
                 .map((r) => r.id).sort();
             if (!open.includes(id)) {
                 const current = open.length ? `the current ${facet} record for ${subject ?? "that subject"} is ${open.join(", ")}` : `no ${facet} record for ${subject ?? "that subject"} is open now`;
@@ -911,7 +975,7 @@ function writeStateAuthorized(store, input, opts, access) {
         const d = record;
         const incumbent = store.recsInHome("derived", home).find((r) => {
             const x = r;
-            return x.id !== id && x.id !== supersedes && x.subject === d.subject && x.transform_version === d.transform_version && x.state === "current" && x.valid_to === null;
+            return x.id !== id && x.id !== supersedes && inScope(x) && x.subject === d.subject && x.transform_version === d.transform_version && x.state === "current" && x.valid_to === null;
         });
         if (incumbent) {
             throw new StateRefusal("conflict", `${d.subject} already has a current ${d.transform_version} statement ${incumbent.id}; pass supersedes: "${incumbent.id}" to replace it, or write that identity to update it`, { incumbent_id: incumbent.id, reason: "one-current-derived-per-subject-transform" });
@@ -922,6 +986,21 @@ function writeStateAuthorized(store, input, opts, access) {
     if (facet === "receipts")
         assertRestsOn(store, request.principal, request.scope, record.rests_on ?? []);
     const closedBy = facet === "commitments" ? assertClosedBy(store, request.principal, record) : null;
+    // Build and validate every change event BEFORE anything is written (#283): a refusal must never
+    // leave a record on file without its event. Only the hashes are filled in after the write (the
+    // store may enrich a record on put), and a sha256 always satisfies the event schema.
+    const cause = closedBy ? { kind: "receipt", receipt_id: closedBy } : request.cause ?? { kind: "write", principal: request.principal.id };
+    // A current derived statement written back as stale is an INVALIDATION, not an update: the
+    // ledger says so, and names the external pointer that moved when the writer gives one.
+    const invalidated = facet === "derived" && !!existing && (existing.state === "current" || existing.state === "unknown") && record.state === "stale";
+    const invalidates = facet === "receipts" ? record.invalidates : [];
+    // An entity leaving service is a `retired` change (a merge names the survivor in the record).
+    const retired = (facet === "entities" || facet === "relationships") && record.lifecycle === "retired" && (!existing || existing.lifecycle !== "retired");
+    const subject = eventSubjectOf(facet, record);
+    const supersededPrior = supersedes ? store.getRec(facet, supersedes) : undefined;
+    const supersededChange = (old) => ({ ...(old.visibility ? { visibility: old.visibility } : {}), facet, record_id: String(old.id), record_hash: stateHash(old), change: "superseded", subject: eventSubjectOf(facet, old), invalidates: [], cause });
+    const ownChange = (recordHash) => ({ ...(nextVisibility ? { visibility: nextVisibility } : {}), facet, record_id: id, record_hash: recordHash, change: invalidated ? "invalidated" : retired ? "retired" : existing ? "updated" : "created", subject, invalidates: invalidated && subject ? [subject] : invalidates, cause });
+    assertEventsValid(ledger, request.scope, now, [...(supersededPrior ? [supersededChange(supersededPrior)] : []), ownChange(hash)]);
     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.
@@ -932,22 +1011,12 @@ function writeStateAuthorized(store, input, opts, access) {
     /** What is on file now — the hash every event, ref and result carries. */
     const onFileHash = stateHash(getHere(id) ?? record);
     const changes = [];
-    const cause = closedBy ? { kind: "receipt", receipt_id: closedBy } : request.cause ?? { kind: "write", principal: request.principal.id };
-    // A current derived statement written back as stale is an INVALIDATION, not an update: the
-    // ledger says so, and names the external pointer that moved when the writer gives one.
-    const invalidated = facet === "derived" && !!existing && (existing.state === "current" || existing.state === "unknown") && record.state === "stale";
-    const invalidates = facet === "receipts" ? record.invalidates : [];
-    // An entity leaving service is a `retired` change (a merge names the survivor in the record).
-    const retired = (facet === "entities" || facet === "relationships") && record.lifecycle === "retired" && (!existing || existing.lifecycle !== "retired");
-    const subject = subjectOf(facet, record);
     if (supersedes) {
         const closed = closeWindow(store, facet, supersedes, id, now, isPrivate);
-        if (closed) {
-            const old = store.getRec(facet, supersedes);
-            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 });
-        }
+        if (closed)
+            changes.push(supersededChange(store.getRec(facet, supersedes)));
     }
-    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 });
+    changes.push(ownChange(onFileHash));
     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();

package/dist/wiki/wiki.d.ts

@@ -146,7 +146,14 @@ export interface NowItem {
     date: string;
     /** decision text for recent items; CONTEXT (the why-it's-planned) for roadmap items. */
     note: string;
+    /** Roadmap only: true when the item is agent testimony no human has confirmed yet.
+     *  Omitted (never false) otherwise, so pages rendered before this field stay fresh. */
+    unconfirmed?: true;
 }
+/** Marker for an unconfirmed roadmap item, naming the human countersign command. */
+export declare function unconfirmedRoadmapMarker(item: Pick<NowItem, "id" | "unconfirmed">, opts?: {
+    private?: boolean;
+}): string;
 /** The hot view's inputs: last `recentLimit` decisions by date (any status — a
  *  supersession IS activity), and every live PROPOSED decision (the roadmap:
  *  record intent as a proposed decision; accepting or superseding it removes it

package/dist/wiki/wiki.js

@@ -33,6 +33,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { compareCodeUnits } from "../core/canonicalOrder.js";
 import { hunchPaths, toPosixTarget } from "../core/paths.js";
 import { isLive } from "../core/topics.js";
+import { confirmCommand, isAgentTestimony } from "../core/countersign.js";
 import { scanRepoDocs } from "../core/docscan.js";
 import { adoptedSlug, adoptionHash, renderAdoptedDoc } from "./adopt.js";
 import { assembleGraphData, renderGraphPage } from "./graph.js";
@@ -396,6 +397,10 @@ const NOW_ID = "_now";
 const GRAPH_ID = "_graph";
 /** Manifest component-id prefix for adopted (wiki-managed) doc copies. */
 const ADOPTED_PREFIX = "doc:";
+/** Marker for an unconfirmed roadmap item, naming the human countersign command. */
+export function unconfirmedRoadmapMarker(item, opts = {}) {
+    return item.unconfirmed ? `⚠ unconfirmed agent testimony — confirm: ${confirmCommand(item.id, opts)}` : "";
+}
 /** The hot view's inputs: last `recentLimit` decisions by date (any status — a
  *  supersession IS activity), and every live PROPOSED decision (the roadmap:
  *  record intent as a proposed decision; accepting or superseding it removes it
@@ -405,15 +410,21 @@ export function nowData(decisions, recentLimit = 10) {
     const byDateDesc = (a, b) => compareCodeUnits(b.valid_from ?? b.date, a.valid_from ?? a.date) || compareCodeUnits(a.id, b.id);
     const recent = [...decisions].sort(byDateDesc).slice(0, recentLimit)
         .map((d) => ({ id: d.id, topic: d.topic, title: d.title, status: d.status, date: (d.valid_from ?? d.date).slice(0, 10), note: clip1(d.decision) }));
-    // Roadmap = INTENT the human vouched for. Auto-synthesized drafts are also
-    // status "proposed", but they describe work already done and belong to the
-    // review queue (`hunch review`) — surfacing them here would bury real plans.
+    // Roadmap = deliberately recorded INTENT: human-vouched, or recorded by an agent
+    // (hunch_record_decision, e.g. at the end of /capture) and not yet confirmed. The latter
+    // is shown MARKED with the human confirm command — never hidden, and never routed to
+    // `adopt-drafts` (which would accept it). Auto-synthesized drafts are also status
+    // "proposed", but they describe work already done and belong to the review queue
+    // (`hunch review`) — surfacing them here would bury real plans.
     const live = decisions.filter((d) => d.status === "proposed" && !d.superseded_by && !d.valid_to);
-    const vouched = live.filter((d) => d.provenance.source.includes("human_confirmed"));
-    const roadmap = vouched
+    const intent = live.filter((d) => d.provenance.source.includes("human_confirmed") || isAgentTestimony(d.provenance.source));
+    const roadmap = intent
         .sort(byDateDesc)
-        .map((d) => ({ id: d.id, topic: d.topic, title: d.title, status: d.status, date: (d.valid_from ?? d.date).slice(0, 10), note: clip1(d.context || d.decision) }));
-    return { recent, roadmap, pendingReview: live.length - vouched.length };
+        .map((d) => ({
+        id: d.id, topic: d.topic, title: d.title, status: d.status, date: (d.valid_from ?? d.date).slice(0, 10), note: clip1(d.context || d.decision),
+        ...(isAgentTestimony(d.provenance.source) ? { unconfirmed: true } : {}),
+    }));
+    return { recent, roadmap, pendingReview: live.length - intent.length };
 }
 /** The hot file — a DERIVED view like every other page: what just happened
  *  (last N decisions) and what's next (live proposed decisions). No topic pins
@@ -436,7 +447,7 @@ export function renderNowPage(recent, roadmap, home, pendingReview = 0) {
     if (!roadmap.length)
         L.push("_Empty. Record what's next as a PROPOSED decision (`/capture`, status: proposed) and it appears here._", "");
     for (const r of roadmap)
-        L.push(`- **${r.title}** — ${r.note || "(no context)"} _(${r.id}${r.topic ? `, topic \`${r.topic}\`` : ""}, since ${r.date})_`);
+        L.push(`- **${r.title}** — ${r.note || "(no context)"} _(${r.id}${r.topic ? `, topic \`${r.topic}\`` : ""}, since ${r.date})_${r.unconfirmed ? ` — ${unconfirmedRoadmapMarker(r, { private: home.kind === "private" })}` : ""}`);
     if (roadmap.length)
         L.push("");
     if (pendingReview > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.39.0",
+  "version": "1.39.2",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

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