@davesheffer/hunch 1.22.2 → 1.23.1

package/README.md

@@ -80,6 +80,7 @@ validation layer behind the tools that write the code.
 | **Project DNA** | Revision-specific, evidence-backed observations about how a repository communicates and works: vocabulary, contribution habits, review expectations, engineering conventions, and culture. |
 | **Engineering Landscape** | Human-reviewed links from product and capability to system, repository, service, interface, data, delivery resources, runbooks, ownership, dashboards, and SLOs. |
 | **Validated Delivery** | The smallest relevant evidence for the current builder, reviewer, or architect, with provenance, currentness, omissions, authority, and a content-addressed receipt. |
+| **Native Change Proof** | A sealed exact-change artifact binding revisions, DNA, base/result graphs, memory, blast radius, conformance, guard verdict, and explicit gaps without granting workflow authority. |
 | **Change Gate + Constitution** | Deterministic checks for trusted constraints and architectural intent. Policies are compiled, proved, inspected, and explicitly activated by a human—never promoted by an agent in the background. |
 
 Readable JSON in `.hunch/` is the source of truth. SQLite is a fast, rebuildable projection. Git
@@ -126,6 +127,7 @@ manual paths:
 | `hunch conform` | Prove the code still satisfies recorded architectural intent |
 | `hunch impact origin/main` | See the dependency and memory surface of a branch |
 | `hunch compare branch-a branch-b` | Rank candidate changes by the fewest invariant and decision conflicts |
+| `hunch prove origin/main --public-only` | Produce a publication-safe `hunch.change-proof/1` artifact for an exact committed change |
 | `hunch landscape review` | Inspect a hash-bound repository landscape without writing authority |
 | `hunch now` | See recent memory and the live decision-backed roadmap |
 | `hunch escalations` | See the rare questions that genuinely require a human answer |
@@ -179,7 +181,7 @@ does not host that repository. Give teammates and CI normal Git access, keep cre
 the Git credential helper, and have one maintainer connect it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.22.2
+npm i -g @davesheffer/hunch@1.23.1
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -189,7 +191,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.22.2
+npm i -g @davesheffer/hunch@1.23.1
 git pull
 hunch init
 hunch doctor
@@ -224,6 +226,7 @@ Use `hunch firmness off` to pause hook enforcement without deleting history. Use
 - [Full documentation](https://hunch-pi.vercel.app/docs)
 - [Copy-paste cookbook](https://hunch-pi.vercel.app/cookbook)
 - [Project DNA](docs/project-dna.md)
+- [Native change proof](docs/change-proof.md)
 - [Engineering Landscape Graph](docs/engineering-landscape.md)
 - [Hunch roadmap](ROADMAP.md)
 - [VS Code extension](vscode-extension/README.md)

package/contracts/change-proof/hunch.change-proof.v1.example.json

@@ -0,0 +1,96 @@
+{
+  "schema": "hunch.change-proof/1",
+  "algorithm": "hunch-change-proof-sha256/1",
+  "engine": {
+    "package": "@davesheffer/hunch",
+    "version": "1.22.3"
+  },
+  "repository": {
+    "repository_id": "pdnar_aaaaaaaaaaaaaaaaaaaaaaaa",
+    "base_revision": "1111111111111111111111111111111111111111",
+    "result_revision": "2222222222222222222222222222222222222222"
+  },
+  "change": {
+    "schema": "hunch.change-identity/1",
+    "algorithm": "git-raw-tree-delta-sha256/1",
+    "change_id": "hchg_889f51592bcb2e773394f42c",
+    "base_revision": "1111111111111111111111111111111111111111",
+    "head_revision": "2222222222222222222222222222222222222222",
+    "base_tree": "4444444444444444444444444444444444444444",
+    "head_tree": "5555555555555555555555555555555555555555",
+    "delta_hash": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+    "patch_id": "6666666666666666666666666666666666666666",
+    "file_count": 1,
+    "paths_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+    "content_hash": "sha256:4149654f541cca52d2f69c208772f9d3063ec4daf230d88cf5f27855a94293a6"
+  },
+  "project_dna": {
+    "schema": "hunch.project-dna/1",
+    "profile_id": "pdna_bbbbbbbbbbbbbbbbbbbbbbbb",
+    "repository_id": "pdnar_aaaaaaaaaaaaaaaaaaaaaaaa",
+    "repository_revision": "2222222222222222222222222222222222222222",
+    "content_hash": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+    "trait_ids": []
+  },
+  "graph": {
+    "base": {
+      "source": "commit",
+      "revision": "1111111111111111111111111111111111111111",
+      "source_hash": "sha1:9999999999999999999999999999999999999999",
+      "topology_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "files": 1,
+      "symbols": 1,
+      "edges": 0,
+      "components": 1,
+      "issue_count": 0
+    },
+    "result": {
+      "source": "commit",
+      "revision": "2222222222222222222222222222222222222222",
+      "source_hash": "sha1:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "topology_hash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+      "files": 1,
+      "symbols": 1,
+      "edges": 0,
+      "components": 1,
+      "issue_count": 0
+    }
+  },
+  "changed_files": [
+    "src/example.ts"
+  ],
+  "changed_file_count": 1,
+  "blast_radius": [],
+  "blast_radius_count": 0,
+  "decisions": [],
+  "decision_count": 0,
+  "constraints": [],
+  "constraint_count": 0,
+  "conformance": [],
+  "conformance_count": 0,
+  "guard": {
+    "verdict": "pass",
+    "strict_blocker_ids": [],
+    "regression_decision_ids": [],
+    "veto_decision_ids": [],
+    "report_hash": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+  },
+  "memory": {
+    "scope": "public",
+    "records_hash": "sha256:d181842823fd171f29a2de31820136d5b5ea58341c07626fa0b1c574e74f0b16"
+  },
+  "omissions": [],
+  "unknowns": [],
+  "verdict": "pass",
+  "authority": {
+    "execution": false,
+    "ci": false,
+    "deployment": false,
+    "merge": false,
+    "ranking": false,
+    "promotion": false,
+    "policy": false
+  },
+  "proof_id": "hproof_813af1d712c7e16334c573e3",
+  "content_hash": "sha256:481d03e0dd598a1b1811541e978b92d40e607c104c3c9b5403d2b4fea604068d"
+}

package/contracts/change-proof/hunch.change-proof.v1.schema.json

@@ -0,0 +1,215 @@
+{
+  "$id": "https://raw.githubusercontent.com/davesheffer/hunch/main/contracts/change-proof/hunch.change-proof.v1.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "schema": { "type": "string", "const": "hunch.change-proof/1" },
+    "algorithm": { "type": "string", "const": "hunch-change-proof-sha256/1" },
+    "proof_id": { "type": "string", "pattern": "^hproof_[a-f0-9]{24}$" },
+    "engine": {
+      "type": "object",
+      "properties": {
+        "package": { "type": "string", "const": "@davesheffer/hunch" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 64 }
+      },
+      "required": ["package", "version"],
+      "additionalProperties": false
+    },
+    "repository": {
+      "type": "object",
+      "properties": {
+        "repository_id": { "type": "string", "pattern": "^pdnar_[a-f0-9]{24}$" },
+        "base_revision": { "$ref": "#/$defs/gitObject" },
+        "result_revision": { "$ref": "#/$defs/gitObject" }
+      },
+      "required": ["repository_id", "base_revision", "result_revision"],
+      "additionalProperties": false
+    },
+    "change": {
+      "type": "object",
+      "properties": {
+        "schema": { "type": "string", "const": "hunch.change-identity/1" },
+        "algorithm": { "type": "string", "const": "git-raw-tree-delta-sha256/1" },
+        "change_id": { "type": "string", "pattern": "^hchg_[a-f0-9]{24}$" },
+        "base_revision": { "$ref": "#/$defs/gitObject" },
+        "head_revision": { "$ref": "#/$defs/gitObject" },
+        "base_tree": { "$ref": "#/$defs/gitObject" },
+        "head_tree": { "$ref": "#/$defs/gitObject" },
+        "delta_hash": { "$ref": "#/$defs/sha256" },
+        "patch_id": { "anyOf": [{ "$ref": "#/$defs/gitObject" }, { "type": "null" }] },
+        "file_count": { "type": "integer", "minimum": 1, "maximum": 16384 },
+        "paths_hash": { "$ref": "#/$defs/sha256" },
+        "content_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["schema", "algorithm", "change_id", "base_revision", "head_revision", "base_tree", "head_tree", "delta_hash", "patch_id", "file_count", "paths_hash", "content_hash"],
+      "additionalProperties": false
+    },
+    "project_dna": {
+      "type": "object",
+      "properties": {
+        "schema": { "type": "string", "const": "hunch.project-dna/1" },
+        "profile_id": { "type": "string", "pattern": "^pdna_[a-f0-9]{24}$" },
+        "repository_id": { "type": "string", "pattern": "^pdnar_[a-f0-9]{24}$" },
+        "repository_revision": { "$ref": "#/$defs/gitObject" },
+        "content_hash": { "$ref": "#/$defs/sha256" },
+        "trait_ids": {
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^pdnat_[a-f0-9]{20}$" }
+        }
+      },
+      "required": ["schema", "profile_id", "repository_id", "repository_revision", "content_hash", "trait_ids"],
+      "additionalProperties": false
+    },
+    "graph": {
+      "type": "object",
+      "properties": {
+        "base": { "$ref": "#/$defs/graphSeal" },
+        "result": { "$ref": "#/$defs/graphSeal" }
+      },
+      "required": ["base", "result"],
+      "additionalProperties": false
+    },
+    "changed_files": { "type": "array", "maxItems": 2048, "uniqueItems": true, "items": { "$ref": "#/$defs/repoPath" } },
+    "changed_file_count": { "type": "integer", "minimum": 1, "maximum": 16384 },
+    "blast_radius": { "type": "array", "maxItems": 4096, "uniqueItems": true, "items": { "$ref": "#/$defs/blastEntry" } },
+    "blast_radius_count": { "type": "integer", "minimum": 0, "maximum": 10000000 },
+    "decisions": { "type": "array", "maxItems": 1024, "uniqueItems": true, "items": { "$ref": "#/$defs/decisionRef" } },
+    "decision_count": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+    "constraints": { "type": "array", "maxItems": 1024, "uniqueItems": true, "items": { "$ref": "#/$defs/constraintRef" } },
+    "constraint_count": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+    "conformance": { "type": "array", "maxItems": 1024, "uniqueItems": true, "items": { "$ref": "#/$defs/conformanceReceipt" } },
+    "conformance_count": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+    "guard": {
+      "type": "object",
+      "properties": {
+        "verdict": { "type": "string", "enum": ["pass", "fail"] },
+        "strict_blocker_ids": { "type": "array", "maxItems": 2048, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 } },
+        "regression_decision_ids": { "type": "array", "maxItems": 1024, "uniqueItems": true, "items": { "$ref": "#/$defs/decisionId" } },
+        "veto_decision_ids": { "type": "array", "maxItems": 1024, "uniqueItems": true, "items": { "$ref": "#/$defs/decisionId" } },
+        "report_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["verdict", "strict_blocker_ids", "regression_decision_ids", "veto_decision_ids", "report_hash"],
+      "additionalProperties": false
+    },
+    "memory": {
+      "type": "object",
+      "properties": {
+        "scope": { "type": "string", "enum": ["public", "union"] },
+        "records_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["scope", "records_hash"],
+      "additionalProperties": false
+    },
+    "omissions": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/hashGap" } },
+    "unknowns": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/hashGap" } },
+    "verdict": { "type": "string", "enum": ["fail", "pass", "unknown"] },
+    "authority": {
+      "type": "object",
+      "properties": {
+        "execution": { "type": "boolean", "const": false },
+        "ci": { "type": "boolean", "const": false },
+        "deployment": { "type": "boolean", "const": false },
+        "merge": { "type": "boolean", "const": false },
+        "ranking": { "type": "boolean", "const": false },
+        "promotion": { "type": "boolean", "const": false },
+        "policy": { "type": "boolean", "const": false }
+      },
+      "required": ["execution", "ci", "deployment", "merge", "ranking", "promotion", "policy"],
+      "additionalProperties": false
+    },
+    "content_hash": { "$ref": "#/$defs/sha256" }
+  },
+  "required": ["schema", "algorithm", "proof_id", "engine", "repository", "change", "project_dna", "graph", "changed_files", "changed_file_count", "blast_radius", "blast_radius_count", "decisions", "decision_count", "constraints", "constraint_count", "conformance", "conformance_count", "guard", "memory", "omissions", "unknowns", "verdict", "authority", "content_hash"],
+  "additionalProperties": false,
+  "$defs": {
+    "gitObject": { "type": "string", "pattern": "^[a-f0-9]{40,64}$" },
+    "sha1": { "type": "string", "pattern": "^sha1:[a-f0-9]{40}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "repoPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[^\\u0000]+$"
+    },
+    "decisionId": { "type": "string", "pattern": "^dec_[A-Za-z0-9_.-]{3,}$" },
+    "constraintId": { "type": "string", "pattern": "^con_[A-Za-z0-9_.-]{3,}$" },
+    "graphSeal": {
+      "type": "object",
+      "properties": {
+        "source": { "type": "string", "const": "commit" },
+        "revision": { "$ref": "#/$defs/gitObject" },
+        "source_hash": { "$ref": "#/$defs/sha1" },
+        "topology_hash": { "$ref": "#/$defs/sha256" },
+        "files": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+        "symbols": { "type": "integer", "minimum": 0, "maximum": 10000000 },
+        "edges": { "type": "integer", "minimum": 0, "maximum": 50000000 },
+        "components": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+        "issue_count": { "type": "integer", "minimum": 0, "maximum": 1000000 }
+      },
+      "required": ["source", "revision", "source_hash", "topology_hash", "files", "symbols", "edges", "components", "issue_count"],
+      "additionalProperties": false
+    },
+    "blastEntry": {
+      "type": "object",
+      "properties": {
+        "source_path": { "$ref": "#/$defs/repoPath" },
+        "dependent_path": { "$ref": "#/$defs/repoPath" },
+        "depth": { "type": "integer", "minimum": 1, "maximum": 4 },
+        "graphs": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": ["base", "result"] } }
+      },
+      "required": ["source_path", "dependent_path", "depth", "graphs"],
+      "additionalProperties": false
+    },
+    "decisionRef": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/decisionId" },
+        "record_hash": { "$ref": "#/$defs/sha256" },
+        "relevance": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "enum": ["blast_radius", "changed_path", "conformance", "guard"] } },
+        "paths": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "$ref": "#/$defs/repoPath" } },
+        "path_count": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+        "paths_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["id", "record_hash", "relevance", "paths", "path_count", "paths_hash"],
+      "additionalProperties": false
+    },
+    "constraintRef": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/constraintId" },
+        "record_hash": { "$ref": "#/$defs/sha256" },
+        "severity": { "type": "string", "enum": ["advisory", "warning", "blocking"] },
+        "relevance": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": ["blast_radius", "changed_path"] } },
+        "paths": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "$ref": "#/$defs/repoPath" } },
+        "path_count": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+        "paths_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["id", "record_hash", "severity", "relevance", "paths", "path_count", "paths_hash"],
+      "additionalProperties": false
+    },
+    "conformanceReceipt": {
+      "type": "object",
+      "properties": {
+        "decision_id": { "$ref": "#/$defs/decisionId" },
+        "predicate_index": { "type": "integer", "minimum": 0, "maximum": 1000000 },
+        "predicate_hash": { "$ref": "#/$defs/sha256" },
+        "satisfied": { "type": "boolean" },
+        "detail_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["decision_id", "predicate_index", "predicate_hash", "satisfied", "detail_hash"],
+      "additionalProperties": false
+    },
+    "hashGap": {
+      "type": "object",
+      "properties": {
+        "code": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{2,127}$" },
+        "count": { "type": "integer", "minimum": 1, "maximum": 1000000 },
+        "evidence_hash": { "$ref": "#/$defs/sha256" }
+      },
+      "required": ["code", "count", "evidence_hash"],
+      "additionalProperties": false
+    }
+  }
+}

package/dist/changeProof.d.ts

@@ -0,0 +1 @@
+export { CHANGE_PROOF_ALGORITHM, CHANGE_PROOF_RELEVANCE, CHANGE_PROOF_SCHEMA_VERSION, CHANGE_PROOF_VERDICTS, ChangeProofSchema, assertChangeProof, canonicalChangeProofJson, changeProofHash, type ChangeProof, } from "./core/changeProofContract.js";

package/dist/changeProof.js

@@ -0,0 +1,2 @@
+export { CHANGE_PROOF_ALGORITHM, CHANGE_PROOF_RELEVANCE, CHANGE_PROOF_SCHEMA_VERSION, CHANGE_PROOF_VERDICTS, ChangeProofSchema, assertChangeProof, canonicalChangeProofJson, changeProofHash, } from "./core/changeProofContract.js";
+//# sourceMappingURL=changeProof.js.map

package/dist/cli/index.js

@@ -57,6 +57,7 @@ import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/e
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
 import { deriveChangeIdentity } from "../core/changeIdentity.js";
+import { deriveChangeProof } from "../core/changeProof.js";
 import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
 import { diffProjectDna } from "../core/projectDnaDelta.js";
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
@@ -3985,6 +3986,42 @@ program
         fail(error.message);
     }
 });
+// ---- prove (standalone semantic proof for an exact committed change) ------
+program
+    .command("prove")
+    .description("Derive Hunch's sealed semantic proof for one exact committed tree transition.")
+    .argument("<base>", "base commit or ref")
+    .argument("[result]", "result commit or ref", "HEAD")
+    .option("--public-only", "exclude the configured private-memory overlay from the proof")
+    .option("--json", "emit the complete hunch.change-proof/1 artifact as JSON")
+    .action((base, result, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const proof = deriveChangeProof(root, store, base, result, { publicOnly: opts.publicOnly });
+        if (opts.json) {
+            console.log(JSON.stringify(proof, null, 2));
+        }
+        else {
+            const gaps = proof.omissions.length + proof.unknowns.length;
+            console.log([
+                `${proof.proof_id} — ${proof.verdict.toUpperCase()} (${proof.schema})`,
+                `  exact revisions: ${proof.repository.base_revision}..${proof.repository.result_revision}`,
+                `  exact change: ${proof.change.change_id} (${proof.changed_file_count} file${proof.changed_file_count === 1 ? "" : "s"})`,
+                `  semantic graph: ${proof.graph.result.symbols} symbols, ${proof.graph.result.edges} edges; ${proof.blast_radius_count} dependent path${proof.blast_radius_count === 1 ? "" : "s"}`,
+                `  memory: ${proof.decision_count} decision${proof.decision_count === 1 ? "" : "s"}, ${proof.constraint_count} constraint${proof.constraint_count === 1 ? "" : "s"}, ${proof.conformance_count} conformance receipt${proof.conformance_count === 1 ? "" : "s"} (${proof.memory.scope})`,
+                `  guard: ${proof.guard.verdict.toUpperCase()}; explicit gaps: ${gaps}`,
+                `  sealed artifact: ${proof.content_hash}`,
+                "  authority: evidence only — no execution, CI, deployment, merge, ranking, promotion, or policy authority",
+            ].join("\n"));
+        }
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- context (surgical retrieval) -----------------------------------------
 program
     .command("context")