@davesheffer/hunch 1.29.0 → 1.31.0

package/dist/core/reviewMemory.js

@@ -0,0 +1,100 @@
+/** Review text is evidence, never executable instructions or policy authority. */
+import { z } from "zod";
+import { canonicalHash } from "../constitution/canonical.js";
+import { buildCorrectionConstraint } from "./correction.js";
+const repositorySchema = z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/);
+const pathSchema = z.string().min(1).max(500).refine(p => !p.startsWith("/") && !/[\\:*?\[\]{}\x00-\x1f]/.test(p)
+    && p.split("/").every(part => part !== ".." && part !== "." && part !== ""), "expected a literal repository-relative file");
+const commentSchema = z.object({
+    id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    body: z.string().trim().min(1).max(32000),
+    path: pathSchema,
+    html_url: z.string().url(),
+    commit_id: z.string().regex(/^[a-f0-9]{40,64}$/),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    in_reply_to_id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    user: z.object({ login: z.string().min(1).max(100), type: z.enum(["User", "Bot"]) }),
+});
+/** Accept GitHub REST review-comment exports, including gh --paginate --slurp pages. */
+export function prepareReviewMemory(repository, input) {
+    repositorySchema.parse(repository);
+    if (!Array.isArray(input))
+        throw new Error("expected a GitHub review-comment array");
+    const comments = z.array(commentSchema).max(10000).parse(input.flat());
+    const unique = new Map();
+    for (const comment of comments) {
+        const url = new URL(comment.html_url);
+        if (url.origin !== "https://github.com" || url.username || url.password || url.search
+            || !new RegExp(`^/${repository.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/pull/[1-9][0-9]*$`, "i").test(url.pathname)
+            || url.hash !== `#discussion_r${comment.id}`)
+            throw new Error(`comment ${comment.id} does not belong to ${repository}`);
+        const previous = unique.get(comment.id);
+        if (previous && canonicalHash(previous) !== canonicalHash(comment))
+            throw new Error(`conflicting versions of comment ${comment.id}`);
+        unique.set(comment.id, comment);
+    }
+    const groups = new Map();
+    let excluded = 0;
+    for (const comment of unique.values()) {
+        if (comment.user.type === "Bot") {
+            excluded++;
+            continue;
+        }
+        const rootId = comment.in_reply_to_id ?? comment.id;
+        const group = groups.get(rootId) ?? [];
+        group.push(comment);
+        groups.set(rootId, group);
+    }
+    const candidates = [];
+    for (const [rootId, group] of groups) {
+        // Do not misrepresent a reply as the original request when an export is partial.
+        const root = group.find(comment => comment.id === rootId && !comment.in_reply_to_id);
+        if (!root)
+            throw new Error(`missing human root comment ${rootId}; export the complete thread`);
+        if (group.some(comment => comment.path !== root.path || new URL(comment.html_url).pathname !== new URL(root.html_url).pathname)) {
+            throw new Error(`inconsistent thread ${rootId}`);
+        }
+        group.sort((a, b) => a.id - b.id);
+        const evidenceHash = canonicalHash({ repository: repository.toLowerCase(), comments: group });
+        candidates.push({ id: `review_${rootId}`, evidence_hash: evidenceHash, file: root.path, comments: group });
+    }
+    candidates.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return { schema: "hunch.review-memory/1", repository: repository.toLowerCase(), authority: "none", candidates, excluded_bots: excluded };
+}
+export function validateReviewPacket(input) {
+    const packet = z.object({
+        schema: z.literal("hunch.review-memory/1"), repository: repositorySchema,
+        authority: z.literal("none"), excluded_bots: z.number().int().nonnegative(),
+        candidates: z.array(z.object({ id: z.string(), evidence_hash: z.string(), file: pathSchema, comments: z.array(commentSchema).min(1) }).strict()).max(10000),
+    }).strict().parse(input);
+    const rebuilt = prepareReviewMemory(packet.repository, packet.candidates.flatMap(c => c.comments));
+    if (canonicalHash(rebuilt.candidates) !== canonicalHash(packet.candidates))
+        throw new Error("review packet evidence hash or membership changed; prepare it again");
+    return packet;
+}
+/** A separate, explicit selection supplies the actual rule and how to check it. */
+export function compileReviewRules(packetInput, selections, now) {
+    const packet = validateReviewPacket(packetInput);
+    const rules = z.array(z.object({
+        candidate_id: z.string(), evidence_hash: z.string(),
+        rule: z.string().trim().min(10).max(2000),
+        check: z.string().trim().min(10).max(4000),
+    }).strict()).min(1).max(100).parse(selections);
+    const results = rules.map(selection => {
+        const candidate = packet.candidates.find(c => c.id === selection.candidate_id);
+        if (!candidate || candidate.evidence_hash !== selection.evidence_hash)
+            throw new Error(`stale or missing review selection ${selection.candidate_id}`);
+        const record = buildCorrectionConstraint({ rule: selection.rule, scope_hint_file: candidate.file,
+            severity: "warning", vouched: false, rationale: `Review check: ${selection.check}` }, now);
+        // Prose cannot silently create a regex/import matcher or earn a human signature.
+        record.forbids = null;
+        record.provenance.evidence = [packet.repository, candidate.id, candidate.evidence_hash,
+            ...candidate.comments.flatMap(c => [c.html_url, `git:${c.commit_id}`])];
+        return record;
+    });
+    if (new Set(results.map(r => r.id)).size !== results.length)
+        throw new Error("duplicate rule statements; select one thread per rule");
+    return results;
+}
+//# sourceMappingURL=reviewMemory.js.map

package/dist/core/stateContract.js

@@ -28,6 +28,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { compareCodeUnits } from "./canonicalOrder.js";
 import { DELIVERY_PROFILES } from "./delivery.js";
+import { isHumanConfirmed as sourceIsHumanConfirmed } from "./strictgate.js";
 import { ScopeSchema, scopePath, DependencyRefSchema, ExternalRefSchema, RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION, } from "./stateRecords.js";
 export * from "./stateRecords.js";
 export const STATE_CONTRACT_VERSION = "nuryel.state/1";
@@ -234,9 +235,17 @@ 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: "one-entity-per-external-ref", statement: "One external record is one entity in a partition: a second active entity carrying an external key an incumbent already carries is refused with the incumbent named, and a subject written as that record's external key is refused with the entity's id named. Identity is explicit refs, never similarity; merge is explicit — a retired entity names the survivor in `merged_into`, the ledger holds the `retired` event, nothing under the old id is rewritten and reads resolve to the survivor — and split is the explicit reverse; never a silent rewrite." },
+    { id: "human-correction-outranks-agent-writes", statement: "A record a human confirmed is never overwritten or superseded by an agent or service principal: the agent may replay it, write derived state back stale with the external cause that moved, or close a commitment with a receipt on record. Changing what the human said takes a human." },
     { 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);
+/** The memory supply chain's top tier: a record whose provenance a human signed. Same tier rule
+ *  as the strict gate's (strictgate.isHumanConfirmed), applied to a record instead of a source. */
+export function isHumanConfirmed(record) {
+    const source = record?.provenance?.source;
+    return typeof source === "string" && sourceIsHumanConfirmed(source);
+}
 /** authorization-before-retrieval, checked on the way OUT as well: nothing in a read response
  *  may sit outside the principal's grants. Bindings must also filter on the way in. */
 export function assertReadWithinGrants(principal, response) {

package/dist/core/stateRecords.js

@@ -44,6 +44,24 @@ export const ExternalRefSchema = z.object({
     observed_at: z.string().regex(ISO),
     locator: credentialFree("external locator").optional(),
 }).strict();
+/** The external system's own key, canonicalized so two writers that copied it from the same
+ *  system agree byte for byte: Unicode NFC, trimmed, internal whitespace collapsed. Case is
+ *  preserved — the key belongs to the external system, and folding it could merge two of its
+ *  records. No other guessing: identity here is explicit refs, never similarity. */
+export function canonicalObjectKey(key) {
+    return key.normalize("NFC").trim().replace(/\s+/g, " ");
+}
+/** The identity of an external record across writers: system, type and canonical key. Two
+ *  entities in one partition that carry the same external key are the same thing. */
+export function externalKey(ref) {
+    return `${ref.system}/${ref.object_type}/${canonicalObjectKey(ref.object_key)}`;
+}
+/** The subject an external record is known by, the convention the read verb already uses for
+ *  receipts (`event:26904`): the object type and the canonical key. When an entity in the
+ *  partition carries the ref, that entity's id is the subject and this form resolves to it. */
+export function subjectOfRef(ref) {
+    return `${ref.object_type}:${canonicalObjectKey(ref.object_key)}`;
+}
 /** What a derived statement rests on. Exactly what a currentness check re-validates. */
 export const DependencyRefSchema = z.discriminatedUnion("kind", [
     /** `scope` (additive) points into ANOTHER partition — the repository decision an
@@ -124,10 +142,22 @@ export const ExternalEntitySchema = z.object({
     refs: z.array(ExternalRefSchema).min(1).max(64),
     attributes: z.record(z.string().max(128), AttributeValue).default({}),
     lifecycle: z.enum(["active", "deprecated", "retired"]).default("active"),
+    /** Audited merge (additive): this entity was folded into another. Set only on a retired
+     *  entity; the survivor must be an active entity on record. Nothing under the retired id is
+     *  rewritten — reads resolve the old id and its keys to the survivor, and the ledger holds
+     *  the `retired` event with its provenance. A split is the explicit reverse: retire or
+     *  re-key the survivor, then write the entity active again without `merged_into`. */
+    merged_into: z.string().min(3).max(2048).optional(),
     provenance: ProvenanceSchema,
     created_at: z.string().regex(ISO),
     updated_at: z.string().regex(ISO),
 }).strict().superRefine((entity, ctx) => {
+    if (entity.merged_into !== undefined) {
+        if (entity.lifecycle !== "retired")
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["merged_into"], message: "a merged entity is retired; the survivor stays active" });
+        if (entity.merged_into === entity.id)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["merged_into"], message: "an entity cannot merge into itself" });
+    }
     const prefix = `${entity.kind}:`;
     const key = entity.id.startsWith(prefix) ? entity.id.slice(prefix.length) : "";
     if (!key.trim() || entity.id !== resourceId(entity.kind, key)) {

package/dist/extractors/diff.js

@@ -26,7 +26,7 @@ const DECL_PATTERNS = [
     // `class Foo(Bar):` header too, and — since declOf() returns on the first match —
     // always wins for Python class lines before any Python-specific pattern would run.
 ];
-import { languageFor } from "./languages.js";
+import { languageFor, isSubstantive } from "./languages.js";
 const IMPORT_RE = /^\s*import\s+(?:[^'"]*from\s+)?['"]([^'"]+)['"]/;
 const CONT_IMPORT_RE = /^\s*\}?\s*from\s+['"]([^'"]+)['"]/; // multi-line: "} from 'x'"
 const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/;
@@ -114,7 +114,7 @@ export function analyzeDiff(diff) {
             else if (raw.startsWith("rename to ") || raw.startsWith("copy to ")) {
                 const to = raw.slice(raw.indexOf(" to ") + 4).trim();
                 curFile = to;
-                if (isCode(to))
+                if (isSubstantive(to))
                     filesRenamed.push({ from: renameFrom, to });
             }
             else if (raw.startsWith("--- ")) {
@@ -126,7 +126,7 @@ export function analyzeDiff(diff) {
                 const p = raw.slice(4).trim();
                 if (p !== "/dev/null")
                     curFile = stripAB(p); // new path preferred
-                if (isCode(curFile)) {
+                if (isSubstantive(curFile)) {
                     if (curAdded)
                         filesAdded.add(curFile);
                     else if (curDeleted)
@@ -138,45 +138,50 @@ export function analyzeDiff(diff) {
         // ---- inside a hunk: content lines ----
         if (raw.startsWith("+")) {
             const body = raw.slice(1);
-            // Raw added lines are captured for EVERY file, before the code-only gate:
+            // Raw added lines are captured for EVERY file, before the substantive gate:
             // content-matched constraints and Veto tripwires are not code-only rules
             // (a blocking invariant legitimately scopes .github/workflows/**, *.sql,
             // Dockerfile). Skipping them here left `scopedAdded` empty, which
             // buildCheckReport reads as "cannot prove a violation ⇒ complies" — so the
             // pre-edit hook denied the edit while `hunch check --strict` passed the
-            // very commit that landed it. Symbol/import extraction and the churn
-            // counters below stay code-only, unchanged.
+            // very commit that landed it. The churn counters below now also include
+            // prose (isSubstantive, issue #12); symbol/import extraction stays
+            // code-only (isCode/languageFor) since declarations are a code concept.
             let lines = addedLinesBy.get(curFile);
             if (!lines) {
                 lines = [];
                 addedLinesBy.set(curFile, lines);
             }
             lines.push(body);
-            if (!isCode(curFile))
+            if (!isSubstantive(curFile))
                 continue;
             addedLines++;
             if (!curAdded && !curDeleted)
                 filesModified.add(curFile);
-            const d = declOf(body);
-            if (d)
-                declsFor(curFile)?.added.set(d.name, d);
-            const imp = importOf(body);
-            if (imp && !imp.startsWith("."))
-                addedImports.add(imp);
+            if (isCode(curFile)) {
+                const d = declOf(body);
+                if (d)
+                    declsFor(curFile)?.added.set(d.name, d);
+                const imp = importOf(body);
+                if (imp && !imp.startsWith("."))
+                    addedImports.add(imp);
+            }
         }
         else if (raw.startsWith("-")) {
-            if (!isCode(curFile))
+            if (!isSubstantive(curFile))
                 continue;
             removedLines++;
             if (!curAdded && !curDeleted)
                 filesModified.add(curFile);
-            const body = raw.slice(1);
-            const d = declOf(body);
-            if (d)
-                declsFor(curFile)?.removed.set(d.name, d);
-            const imp = importOf(body);
-            if (imp && !imp.startsWith("."))
-                removedImports.add(imp);
+            if (isCode(curFile)) {
+                const body = raw.slice(1);
+                const d = declOf(body);
+                if (d)
+                    declsFor(curFile)?.removed.set(d.name, d);
+                const imp = importOf(body);
+                if (imp && !imp.startsWith("."))
+                    removedImports.add(imp);
+            }
         }
     }
     // per-file symbol classification (added/removed/changed within the same file)

package/dist/extractors/git.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
 import { createRepoFileReader } from "../core/safeRepoFile.js";
+import { initiatorChildEnv } from "../synthesis/initiator.js";
 // `git` exports these repository-local variables to hooks. They outrank cwd/-C,
 // so carrying them from the code repository into a command for the memory
 // overlay can target the wrong index/object store. This is the documented set
@@ -21,7 +22,7 @@ const LOCAL_GIT_ENV_VARS = [
     "GIT_INTERNAL_SUPER_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
 ];
 export function foreignRepoEnv(source) {
-    const env = { ...source };
+    const env = initiatorChildEnv(source);
     for (const key of LOCAL_GIT_ENV_VARS)
         delete env[key];
     for (const key of Object.keys(env)) {
@@ -58,6 +59,7 @@ function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
         cwd, encoding: "utf8", maxBuffer,
+        env: initiatorChildEnv(),
         stdio: ["ignore", "pipe", "ignore"],
     }).trim();
 }
@@ -748,6 +750,10 @@ export function headFileContent(root, rel) {
             encoding: "utf8",
             env: foreignRepoEnv(process.env),
             maxBuffer: 16 * 1024 * 1024,
+            // An untracked/absent-at-HEAD path is an expected, silently-handled case
+            // (falls through to the catch below) — don't let git's "fatal: path ...
+            // does not exist in 'HEAD'" leak onto the caller's stderr for it.
+            stdio: ["ignore", "pipe", "ignore"],
         });
     }
     catch {

package/dist/extractors/languages.js

@@ -281,4 +281,12 @@ export function languageFor(file) {
     }
     return null;
 }
+/** Prose formats worth drafting a decision from even though no LanguageSpec parses
+ *  them — no grammar, no symbols/edges, just eligible input to synthesis (issue #12). */
+export const PROSE_EXTENSIONS = [".md"];
+/** Broader than languageFor: "is this worth reasoning about" (synthesis input)
+ *  rather than "can tree-sitter parse this" (symbol/dependency extraction). */
+export function isSubstantive(file) {
+    return languageFor(file) !== null || PROSE_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
 //# sourceMappingURL=languages.js.map