@davesheffer/hunch 1.8.3 → 1.9.2

package/dist/constitution/plan.js

@@ -1,10 +1,12 @@
-import { basename } from "node:path";
 import { shortHash } from "../core/ids.js";
-import { firstCommitForFile, headSha, revExists, revParse } from "../extractors/git.js";
+import { stableRepositoryName } from "../extractors/git.js";
 import { canonicalHash, policySemanticHash } from "./canonical.js";
 import { policyCompositionBinding, policyProofHash } from "./composition.js";
 import { graphSnapshot, mutationOperatorForPolicy, selectedPolicyForComposition } from "./evaluator.js";
 import { createExecutableBehaviorProofPlan } from "./behaviorProof.js";
+import { canonicalStaticGraphBaseline, isAncestorOrSame } from "./staticGraphBaseline.js";
+import { replacementFreeExactCommit, replacementFreeFirstCommitForFile } from "./replacementFreeGit.js";
+export { canonicalStaticGraphBaseline } from "./staticGraphBaseline.js";
 import { POLICY_EVALUATOR, MUTATION_ENGINE, ProofPlanSchema, } from "./schema.js";
 function clamp(value, fallback, min, max) {
     if (value == null || !Number.isFinite(value))
@@ -46,19 +48,26 @@ export function createProofPlan(store, root, repository, policy, opts = {}) {
             throw new Error("executable-behavior policies cannot have exception composition");
         return createExecutableBehaviorProofPlan(root, repository, policy, { now: opts.now, privateOnly: true });
     }
-    const head = headSha(root);
-    if (!head)
+    const repositoryHead = replacementFreeExactCommit(root, "HEAD");
+    if (!repositoryHead)
         throw new Error("proof planning needs a Git repository with a current HEAD");
+    const head = canonicalStaticGraphBaseline(root, repositoryHead);
     const composition = opts.composition ?? [];
     const parentHash = policySemanticHash(policy);
     const policyHash = policyProofHash(policy, composition);
     const compositionBinding = policyCompositionBinding(policy, composition);
     const corpus = repository.getCorpus(policy.id, opts);
+    // Proof plans are shared memory. A clone-local directory basename would mint
+    // different plan IDs for Architect, Developer, CI, and linked worktrees even
+    // when every one of them is looking at the same repository and policy. An
+    // existing immutable corpus remains the compatibility authority for artifacts
+    // created before stable repository identities were introduced.
+    const repositoryName = opts.repositoryName ?? corpus?.repository ?? stableRepositoryName(root);
     if (corpus) {
         if (corpus.policy_hash !== parentHash) {
             throw new Error(`proof corpus ${corpus.id} is stale for policy ${policy.id}; re-import it after the policy semantic change`);
         }
-        if (corpus.repository !== basename(root) || corpus.data_class !== policy.data_class) {
+        if (corpus.repository !== repositoryName || corpus.data_class !== policy.data_class) {
             throw new Error(`proof corpus ${corpus.id} does not match repository/data class for policy ${policy.id}`);
         }
     }
@@ -73,11 +82,19 @@ export function createProofPlan(store, root, repository, policy, opts = {}) {
         .filter((ref) => ref.startsWith("dec_"))
         .map(readDecision)
         .find((record) => !!record);
-    const policyCommit = firstCommitForFile(`.hunch/policies/${policy.id}.json`, root);
+    const policyCommit = replacementFreeFirstCommitForFile(root, `.hunch/policies/${policy.id}.json`);
     const sourceRef = sourceEvent?.commit ?? decision?.commit ?? (policyCommit || head);
-    if (!revExists(sourceRef, root))
+    const rawSource = replacementFreeExactCommit(root, sourceRef);
+    if (!rawSource)
         throw new Error(`proof-plan source commit ${sourceRef} does not resolve in this repository`);
-    const sourceCommit = revParse(sourceRef, root);
+    // Canonicalize the source independently of current HEAD. A policy introduced
+    // by a Hunch-only publication commit remains anchored to the indexed-code (or
+    // merge) boundary immediately before that publication, even after later code
+    // commits advance the current baseline.
+    const sourceCommit = canonicalStaticGraphBaseline(root, rawSource);
+    if (!isAncestorOrSame(root, sourceCommit, head)) {
+        throw new Error(`proof-plan source commit ${sourceCommit} is not an ancestor of canonical graph baseline ${head}`);
+    }
     const structural = events.find((event) => event.structural_delta && (event.kind === "bug_fix" || event.kind === "revert" || event.kind === "decision"));
     const structuralKnownBad = structural?.structural_delta
         ? [{
@@ -112,7 +129,7 @@ export function createProofPlan(store, root, repository, policy, opts = {}) {
     const body = {
         policy_id: policy.id,
         policy_candidate_hash: policyHash,
-        repository: basename(root),
+        repository: repositoryName,
         data_class: policy.data_class,
         source_commit: sourceCommit,
         valid_from_commit: sourceCommit,

package/dist/constitution/replacementFreeGit.js

@@ -0,0 +1,67 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { foreignRepoEnv } from "../extractors/git.js";
+/** Constitution proof identity is the repository's real object graph, never a
+ * clone-local `refs/replace/*` or legacy graft view. Keep this environment
+ * private to proof planning so every traversal and ancestry check agrees with
+ * replay, which uses the same Git invariant. */
+export function replacementFreeGitEnvironment(source = process.env) {
+    return {
+        ...foreignRepoEnv(source),
+        GIT_NO_REPLACE_OBJECTS: "1",
+    };
+}
+function gitText(root, args, maxBuffer = 64 * 1024 * 1024) {
+    return execFileSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        env: replacementFreeGitEnvironment(),
+        maxBuffer,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function gitTextSafe(root, args, maxBuffer) {
+    try {
+        return gitText(root, args, maxBuffer);
+    }
+    catch {
+        return "";
+    }
+}
+/** Resolve one commit-ish through the real object graph. */
+export function replacementFreeExactCommit(root, ref) {
+    const oid = gitTextSafe(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).toLowerCase();
+    return /^[0-9a-f]{40,64}$/.test(oid) ? oid : null;
+}
+/** Files changed by an exact commit, ignoring local replacement objects. */
+export function replacementFreeCommitFiles(root, commit) {
+    const out = gitTextSafe(root, ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", commit]);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+export function replacementFreeCommitMeta(root, commit) {
+    const raw = gitTextSafe(root, ["show", "-s", "--format=%H%x1f%h%x1f%s%x1f%b%x1f%an%x1f%aI", commit]);
+    if (!raw)
+        return null;
+    const [sha = "", shortSha = "", subject = "", body = "", author = "", date = ""] = raw.split("\x1f");
+    if (!/^[0-9a-f]{40,64}$/i.test(sha))
+        return null;
+    return { sha, shortSha, subject, body, author, date, files: replacementFreeCommitFiles(root, sha) };
+}
+/** Exact introducing commit for a Git-native policy record. */
+export function replacementFreeFirstCommitForFile(root, file) {
+    const added = gitTextSafe(root, ["log", "--diff-filter=A", "--format=%H", "--", file])
+        .split("\n")
+        .find(Boolean);
+    if (added)
+        return added;
+    return gitTextSafe(root, ["log", "--reverse", "--format=%H", "--", file])
+        .split("\n")
+        .find(Boolean) ?? "";
+}
+export function replacementFreeIsAncestorOrSame(root, ancestor, descendant) {
+    if (ancestor === descendant)
+        return true;
+    return spawnSync("git", ["-C", root, "merge-base", "--is-ancestor", ancestor, descendant], {
+        env: replacementFreeGitEnvironment(),
+        stdio: "ignore",
+    }).status === 0;
+}
+//# sourceMappingURL=replacementFreeGit.js.map

package/dist/constitution/replay.js

@@ -7,6 +7,7 @@ import { canonicalHash, proofEvaluationHash, proofPlanContentHash } from "./cano
 import { assertCompositionBinding, policyProofHash } from "./composition.js";
 import { evaluateCompositePolicyOnSnapshot, evaluatePolicyOnSnapshot } from "./evaluator.js";
 import { loadReplaySnapshot, putReplaySnapshot } from "./replayCache.js";
+import { hasUnsafeCheckoutAttributes } from "./safeCheckout.js";
 import { POLICY_EVALUATOR, ProofPlanSchema, ReplayReceiptSchema, } from "./schema.js";
 const ZERO_SHA = "0".repeat(40);
 export const DEFAULT_REPLAY_WORKERS = 4;
@@ -26,6 +27,7 @@ export function replaySafeEnvironment(home, gitConfig) {
         HOME: home,
         GIT_CONFIG_GLOBAL: gitConfig,
         GIT_CONFIG_NOSYSTEM: "1",
+        GIT_NO_REPLACE_OBJECTS: "1",
         GIT_TERMINAL_PROMPT: "0",
         GIT_LFS_SKIP_SMUDGE: "1",
         HUNCH_PRIVATE_DIR: "",
@@ -204,6 +206,10 @@ export function replayProofPlan(root, policy, inputPlan, opts = {}) {
                 outcomes.set(commit, { commit, error_code: "timeout" });
                 continue;
             }
+            if (hasUnsafeCheckoutAttributes(root, commit, env, { allowDisabledLfs: true })) {
+                outcomes.set(commit, { commit, error_code: "unsafe-checkout-attributes" });
+                continue;
+            }
             const cached = loadReplaySnapshot(root, commit, plan.data_class);
             if (cached.status === "hit" && cached.snapshot) {
                 cacheStats.hits++;

package/dist/constitution/replayCache.js

@@ -6,7 +6,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { canonicalHash } from "./canonical.js";
 import { graphSnapshotFromRecords } from "./evaluator.js";
 import { DataClassSchema, POLICY_EVALUATOR } from "./schema.js";
-export const REPLAY_CACHE_ENGINE = { name: "hunch-tsjs-static-index", version: "3" };
+export const REPLAY_CACHE_ENGINE = { name: "hunch-tsjs-static-index", version: "4" };
 const ReplayGraphCacheSchema = z.object({
     version: z.literal(1),
     engine: z.object({ name: z.string().min(1), version: z.string().min(1) }),

package/dist/constitution/replayWorker.js

@@ -13,7 +13,7 @@ let message;
 try {
     store = new HunchStore(hunchPathsForDir(input.graph));
     store.json.ensureDirs();
-    indexRepo(store, input.checkout, { churn: false });
+    indexRepo(store, input.checkout, { churn: false, requireComplete: true });
     message = {
         commit: input.commit,
         snapshot: graphSnapshot(store, input.root, { publicOnly: true, head: input.commit }),

package/dist/constitution/repository.js

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { writeFileAtomic } from "../core/io.js";
+import { writeFileAtomic, writeFileAtomicIfAbsent } from "../core/io.js";
 import { shortHash } from "../core/ids.js";
-import { policySemanticHash, proofPlanContentHash } from "./canonical.js";
+import { canonicalHash, policySemanticHash, proofPlanContentHash } from "./canonical.js";
 import { proofCorpusContentHash } from "./corpus.js";
 import { currentHistoryDispositions, historyDispositionContentHash, historyDispositionJudgmentHash } from "./disposition.js";
 import { assertCompositionBinding, compositionDescendants, policyProofHash } from "./composition.js";
@@ -218,9 +218,51 @@ export class PolicyRepository {
         writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
         return parsed;
     }
-    putProof(proof, policyId) {
+    /** Publish a new policy lifecycle record without overwriting a concurrent
+     * writer. Used by automated proposal materializers so human authority always
+     * wins a race. */
+    putPolicyIfAbsent(policy, opts = {}) {
+        const parsed = PolicySpecSchema.parse(policy);
+        if (opts.private && opts.public)
+            throw new Error("choose only one policy home");
+        const home = opts.private ? "private" : opts.public ? "public" : parsed.data_class !== "public" || this.store.unified ? "private" : "public";
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} policy ${parsed.id} into the public home`);
+        }
+        const homeOpts = home === "public" ? { publicOnly: true } : { privateOnly: true };
+        const existing = this.getPolicy(parsed.id, homeOpts);
+        const otherHome = this.getPolicy(parsed.id, home === "public" ? { privateOnly: true } : { publicOnly: true });
+        if (existing && otherHome)
+            throw new Error(`policy ${parsed.id} exists in both public and private homes`);
+        if (existing)
+            return { policy: existing, created: false };
+        if (otherHome)
+            throw new Error(`policy ${parsed.id} already exists in the ${home === "public" ? "private" : "public"} home`);
+        const dir = this.dir(home, "policies");
+        mkdirSync(dir, { recursive: true });
+        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed))) {
+            const racedOtherHome = this.getPolicy(parsed.id, home === "public" ? { privateOnly: true } : { publicOnly: true });
+            if (racedOtherHome)
+                throw new Error(`policy ${parsed.id} was published concurrently in both public and private homes`);
+            return { policy: parsed, created: true };
+        }
+        const winner = this.getPolicy(parsed.id, homeOpts);
+        if (!winner)
+            throw new Error(`policy ${parsed.id} appeared concurrently but could not be read`);
+        return { policy: winner, created: false };
+    }
+    putProof(proof, policyId, opts = {}) {
         const parsed = PolicyProofSchema.parse(proof);
-        const home = this.homeOfPolicy(policyId) ?? (parsed.data_class === "public" && !this.store.unified ? "public" : "private");
+        if (opts.private && opts.public)
+            throw new Error("choose only one proof home");
+        const home = opts.private
+            ? "private"
+            : opts.public
+                ? "public"
+                : this.homeOfPolicy(policyId) ?? (parsed.data_class === "public" && !this.store.unified ? "public" : "private");
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} proof ${parsed.id} into the public home`);
+        }
         const homeOpts = home === "public" ? { publicOnly: true } : { privateOnly: true };
         const policy = this.getPolicy(policyId, homeOpts);
         if (policy) {
@@ -240,6 +282,50 @@ export class PolicyRepository {
         writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
         return parsed;
     }
+    /** Publish an immutable proof without replacing a concurrent writer. */
+    putProofIfAbsent(proof, policyId, opts = {}) {
+        const parsed = PolicyProofSchema.parse(proof);
+        if (opts.private && opts.public)
+            throw new Error("choose only one proof home");
+        const home = opts.private
+            ? "private"
+            : opts.public
+                ? "public"
+                : this.homeOfPolicy(policyId) ?? (parsed.data_class === "public" && !this.store.unified ? "public" : "private");
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} proof ${parsed.id} into the public home`);
+        }
+        const homeOpts = home === "public" ? { publicOnly: true } : { privateOnly: true };
+        const policy = this.getPolicy(policyId, homeOpts);
+        if (policy) {
+            const composition = compositionDescendants(policy, this.listPolicies(homeOpts));
+            assertCompositionBinding(policy, composition, parsed.composition);
+            if (parsed.policy_hash !== policyProofHash(policy, composition))
+                throw new Error(`composite proof ${parsed.id} policy hash mismatch`);
+            if (composition.length) {
+                const plan = this.listPlans(homeOpts).find((candidate) => candidate.content_hash === parsed.plan_hash);
+                if (!plan || plan.policy_candidate_hash !== parsed.policy_hash)
+                    throw new Error(`composite proof ${parsed.id} has no exact bound proof plan`);
+                assertCompositionBinding(policy, composition, plan.composition);
+            }
+        }
+        const existing = this.getProof(parsed.id, homeOpts);
+        if (existing) {
+            if (immutableProofHash(existing) !== immutableProofHash(parsed))
+                throw new Error(`proof ${parsed.id} already exists with different immutable content`);
+            return { proof: existing, created: false };
+        }
+        const dir = this.dir(home, "proofs");
+        mkdirSync(dir, { recursive: true });
+        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed)))
+            return { proof: parsed, created: true };
+        const winner = this.getProof(parsed.id, homeOpts);
+        if (!winner)
+            throw new Error(`proof ${parsed.id} appeared concurrently but could not be read`);
+        if (immutableProofHash(winner) !== immutableProofHash(parsed))
+            throw new Error(`proof ${parsed.id} appeared concurrently with different immutable content`);
+        return { proof: winner, created: false };
+    }
     putPlan(plan, policyId, opts = {}) {
         const parsed = validatePlan(plan);
         if (opts.private && opts.public)
@@ -249,6 +335,9 @@ export class PolicyRepository {
             : opts.public
                 ? "public"
                 : this.homeOfPolicy(policyId) ?? (parsed.data_class === "public" && !this.store.unified ? "public" : "private");
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} proof plan ${parsed.id} into the public home`);
+        }
         const homeOpts = home === "public" ? { publicOnly: true } : { privateOnly: true };
         const policy = this.getPolicy(policyId, homeOpts);
         if (policy) {
@@ -262,6 +351,44 @@ export class PolicyRepository {
         writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
         return parsed;
     }
+    /** Publish an immutable proof plan without replacing a concurrent writer. */
+    putPlanIfAbsent(plan, policyId, opts = {}) {
+        const parsed = validatePlan(plan);
+        if (opts.private && opts.public)
+            throw new Error("choose only one proof-plan home");
+        const home = opts.private
+            ? "private"
+            : opts.public
+                ? "public"
+                : this.homeOfPolicy(policyId) ?? (parsed.data_class === "public" && !this.store.unified ? "public" : "private");
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} proof plan ${parsed.id} into the public home`);
+        }
+        const homeOpts = home === "public" ? { publicOnly: true } : { privateOnly: true };
+        const policy = this.getPolicy(policyId, homeOpts);
+        if (policy) {
+            const composition = compositionDescendants(policy, this.listPolicies(homeOpts));
+            assertCompositionBinding(policy, composition, parsed.composition);
+            if (parsed.policy_candidate_hash !== policyProofHash(policy, composition))
+                throw new Error(`composite plan ${parsed.id} policy hash mismatch`);
+        }
+        const existing = this.getPlan(parsed.id, homeOpts);
+        if (existing) {
+            if (existing.content_hash !== parsed.content_hash)
+                throw new Error(`proof plan ${parsed.id} already exists with different immutable content`);
+            return { plan: existing, created: false };
+        }
+        const dir = this.dir(home, "plans");
+        mkdirSync(dir, { recursive: true });
+        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed)))
+            return { plan: parsed, created: true };
+        const winner = this.getPlan(parsed.id, homeOpts);
+        if (!winner)
+            throw new Error(`proof plan ${parsed.id} appeared concurrently but could not be read`);
+        if (winner.content_hash !== parsed.content_hash)
+            throw new Error(`proof plan ${parsed.id} appeared concurrently with different immutable content`);
+        return { plan: winner, created: false };
+    }
     putCorpus(corpus, policyId) {
         const parsed = validateCorpus(corpus);
         if (parsed.policy_id !== policyId)
@@ -280,7 +407,12 @@ export class PolicyRepository {
     }
     putEvidence(event, opts = {}) {
         const parsed = EvidenceEventSchema.parse(event);
-        const home = opts.private || parsed.data_class !== "public" || this.store.unified ? "private" : "public";
+        if (opts.private && opts.public)
+            throw new Error("choose only one evidence home");
+        const home = opts.private ? "private" : opts.public ? "public" : parsed.data_class !== "public" || this.store.unified ? "private" : "public";
+        if (home === "public" && parsed.data_class !== "public") {
+            throw new Error(`refusing to write ${parsed.data_class} evidence ${parsed.id} into the public home`);
+        }
         const dir = this.dir(home, "evidence");
         mkdirSync(dir, { recursive: true });
         writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
@@ -395,6 +527,10 @@ export class PolicyRepository {
         return parsed;
     }
 }
+function immutableProofHash(proof) {
+    const { generated_at: _generatedAt, ...payload } = proof;
+    return canonicalHash(payload);
+}
 function validatePlan(raw) {
     const plan = ProofPlanSchema.parse(raw);
     const hash = proofPlanContentHash(plan);

package/dist/constitution/safeCheckout.js

@@ -0,0 +1,75 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const CHECKOUT_TRANSFORM_ATTRIBUTES = ["filter", "working-tree-encoding", "ident", "eol", "text", "crlf"];
+const MAX_ATTRIBUTE_BYTES = 64 * 1024 * 1024;
+function nulFields(bytes) {
+    const fields = [];
+    let start = 0;
+    for (let end = bytes.indexOf(0, start); end !== -1; end = bytes.indexOf(0, start)) {
+        fields.push(bytes.subarray(start, end));
+        start = end + 1;
+    }
+    if (start < bytes.length)
+        fields.push(bytes.subarray(start));
+    return fields;
+}
+/** Inspect the exact target tree plus repository-local info attributes without
+ * checking it out. Any checkout transform could execute code or make the worktree
+ * bytes diverge from the raw blobs bound by receipts, so fail closed. Merge
+ * attributes are intentionally excluded: worktree materialization never invokes a
+ * merge driver. LFS is allowed only when callers explicitly disable its
+ * smudge/process hooks. */
+export function hasUnsafeCheckoutAttributes(root, commit, env, opts = {}) {
+    const session = mkdtempSync(join(tmpdir(), "hunch-attr-index-"));
+    const index = join(session, "index");
+    const exactEnv = { ...env, GIT_INDEX_FILE: index, GIT_NO_REPLACE_OBJECTS: "1", GIT_ATTR_NOSYSTEM: "1" };
+    try {
+        execFileSync("git", ["-C", root, "read-tree", commit], {
+            env: exactEnv,
+            timeout: 10_000,
+            maxBuffer: MAX_ATTRIBUTE_BYTES,
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        const paths = execFileSync("git", ["-C", root, "ls-files", "-z"], {
+            env: exactEnv,
+            timeout: 10_000,
+            maxBuffer: MAX_ATTRIBUTE_BYTES,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (!paths.length)
+            return false;
+        const raw = execFileSync("git", ["-C", root, "check-attr", "--cached", "-z", "--stdin", ...CHECKOUT_TRANSFORM_ATTRIBUTES], {
+            env: exactEnv,
+            input: paths,
+            timeout: 10_000,
+            maxBuffer: MAX_ATTRIBUTE_BYTES,
+            encoding: "buffer",
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        const fields = nulFields(raw);
+        if (fields.length % 3 !== 0)
+            return true;
+        for (let index = 0; index < fields.length; index += 3) {
+            const attribute = fields[index + 1].toString("utf8");
+            const value = fields[index + 2].toString("utf8");
+            if (!CHECKOUT_TRANSFORM_ATTRIBUTES.includes(attribute))
+                return true;
+            if (value === "unspecified" || value === "unset")
+                continue;
+            if (opts.allowDisabledLfs && attribute === "filter" && value === "lfs")
+                continue;
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+    finally {
+        rmSync(session, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=safeCheckout.js.map

package/dist/constitution/schema.js

@@ -4,6 +4,10 @@ export const POLICY_IR_VERSION = 1;
 export const POLICY_EVALUATOR = { name: "hunch-graph-policy", version: "1.3.0" };
 export const MUTATION_ENGINE = { name: "hunch-static-graph-controls", version: "5" };
 export const EXECUTABLE_BEHAVIOR_IR_VERSION = 2;
+/** Source-gated correction policies deliberately use an IR unknown to pre-Matrix
+ * clients. Those clients then reject the artifact instead of loading it without
+ * understanding (and potentially bypassing) its activation gate. */
+export const CORRECTION_POLICY_IR_VERSION = 3;
 export const BEHAVIOR_POLICY_EVALUATOR = { name: "hunch-executable-behavior", version: "1.0.0" };
 export const BEHAVIOR_MUTATION_ENGINE = { name: "hunch-behavior-controls", version: "1" };
 export const DataClassSchema = z.enum(["public", "private", "secret"]);
@@ -195,10 +199,20 @@ export const PolicyAuthoritySchema = z.object({
     event: z.string().min(1),
     at: z.string().datetime({ offset: true }),
 });
+export const PolicyActivationGateSchema = z.object({
+    kind: z.literal("source_currentness"),
+    status: z.literal("blocked"),
+    reason: z.string().min(1),
+}).strict();
 export const PolicySpecSchema = z.object({
     id: z.string().regex(/^pol_[a-f0-9]{10}$/),
     topic: z.string().min(1),
-    ir_version: z.union([z.literal(POLICY_IR_VERSION), z.literal(EXECUTABLE_BEHAVIOR_IR_VERSION)]),
+    origin: z.enum(["generic", "correction_md1a"]).default("generic"),
+    ir_version: z.union([
+        z.literal(POLICY_IR_VERSION),
+        z.literal(EXECUTABLE_BEHAVIOR_IR_VERSION),
+        z.literal(CORRECTION_POLICY_IR_VERSION),
+    ]),
     revision: z.number().int().min(1),
     state: PolicyStateSchema,
     statement: z.string().min(1),
@@ -208,6 +222,7 @@ export const PolicySpecSchema = z.object({
     severity: z.enum(["advisory", "warning", "blocking"]).default("warning"),
     surfaces: z.array(z.enum(["pre_edit", "pre_commit", "ci", "mcp", "cli"])).default(["cli", "mcp"]),
     authority: PolicyAuthoritySchema.nullable().default(null),
+    activation_gate: PolicyActivationGateSchema.nullable().default(null),
     evidence: z.array(z.string()).default([]),
     proof: z.string().nullable().default(null),
     reversal_conditions: z.array(z.string()).default([]),
@@ -225,11 +240,21 @@ export const PolicySpecSchema = z.object({
     updated_at: z.string().datetime({ offset: true }),
     provenance: ProvenanceSchema,
 }).passthrough().superRefine((policy, context) => {
-    if (policy.assertion.kind === "executable-behavior" && policy.ir_version !== EXECUTABLE_BEHAVIOR_IR_VERSION) {
-        context.addIssue({ code: "custom", path: ["ir_version"], message: `executable-behavior requires Policy IR v${EXECUTABLE_BEHAVIOR_IR_VERSION}` });
+    if (policy.origin === "correction_md1a") {
+        if (policy.assertion.kind === "executable-behavior") {
+            context.addIssue({ code: "custom", path: ["assertion", "kind"], message: "source-gated correction policies require a graph assertion" });
+        }
+        if (policy.ir_version !== CORRECTION_POLICY_IR_VERSION) {
+            context.addIssue({ code: "custom", path: ["ir_version"], message: `source-gated correction policies require Policy IR v${CORRECTION_POLICY_IR_VERSION}` });
+        }
     }
-    if (policy.assertion.kind !== "executable-behavior" && policy.ir_version !== POLICY_IR_VERSION) {
-        context.addIssue({ code: "custom", path: ["ir_version"], message: `graph assertions require Policy IR v${POLICY_IR_VERSION}` });
+    else {
+        if (policy.assertion.kind === "executable-behavior" && policy.ir_version !== EXECUTABLE_BEHAVIOR_IR_VERSION) {
+            context.addIssue({ code: "custom", path: ["ir_version"], message: `executable-behavior requires Policy IR v${EXECUTABLE_BEHAVIOR_IR_VERSION}` });
+        }
+        if (policy.assertion.kind !== "executable-behavior" && policy.ir_version !== POLICY_IR_VERSION) {
+            context.addIssue({ code: "custom", path: ["ir_version"], message: `graph assertions require Policy IR v${POLICY_IR_VERSION}` });
+        }
     }
 });
 export const PolicyCompositionMemberSchema = z.object({