@davesheffer/hunch 1.16.0 → 1.18.0

package/README.md

@@ -6,9 +6,11 @@
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-Hunch is the engineering-memory and architectural-conformance layer for AI-assisted codebases. It
-records the decisions, constraints, rejected approaches, and bug history behind your code, delivers
-the relevant evidence before an assistant changes anything, then checks the result deterministically.
+For the precise rules your team explicitly trusts and proves, Hunch gives a concrete guarantee:
+**your agents do not re-make a decided decision or re-introduce a fixed bug without a deterministic
+violation being surfaced.** The mechanism is an engineering-memory and architectural-conformance
+layer — the decisions, constraints, rejected approaches, and bug history behind your code, delivered
+as evidence before an assistant changes anything, with the result checked deterministically after.
 
 Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
 strict enforcement.
@@ -16,8 +18,10 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.13.1:** `hunch_context` exposes that provenance-checked, hard-budgeted delivery
-> envelope as MCP structured output and records exactly which returned items reached the client.
+> **New in v1.18.0:** YAML and Helm now enter the same dependency graph as application code.
+> Anchors and aliases become reference edges; chart-scoped `define`, `include`, and `template`
+> relationships survive pre-render syntax without weakening fail-closed handling for ordinary
+> invalid YAML.
 
 See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
 
@@ -47,8 +51,11 @@ to the same graph. It merges into existing configuration instead of replacing it
 - **Change receipts** — review a working tree, commit, or branch against recorded intent and get a
   cited PASS / WARN / BLOCK result.
 - **Bug lineage** — understand which old incident a line fixed before accidentally undoing it.
-- **Code awareness** — TypeScript, JavaScript, and Python structure feed dependency, blast-radius,
-  and redundancy checks. The reasoning layer works with any language.
+- **Code awareness** — TypeScript, JavaScript, Python, Go, YAML, and chart-scoped Helm templates
+  feed dependency, blast-radius, and redundancy checks. The reasoning layer works with any language.
+- **ADR interop** — `hunch import-adr` populates the graph from an existing MADR/Nygard corpus;
+  `hunch export-adr` projects it back as standard MADR any ADR reader understands, and the
+  projection then tracks the graph automatically and reports its own drift.
 
 The source of truth is readable JSON in `.hunch/`. A local SQLite index makes retrieval fast but
 is always rebuildable.
@@ -82,7 +89,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.1
+npm i -g @davesheffer/hunch@1.18.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -97,7 +104,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.1
+npm i -g @davesheffer/hunch@1.18.0
 git pull
 hunch init
 hunch doctor
@@ -115,6 +122,9 @@ authentication stays in SSH or the normal Git credential helper. Shared memory r
 `.hunch/local.json`, and `.hunch-private/` stay out of code history. Use
 `hunch check --base origin/main --strict --public-only --format markdown` for output that may be
 posted publicly; omit `--public-only` for an internal check that should enforce team memory.
+`HUNCH_PRIVATE_DIR` remains an explicit process-level override for CI and portability. When it
+redirects a repo away from `.hunch/local.json` or bypasses an advertised team store, CLI and MCP
+startup warn on stderr and `hunch doctor` labels the effective source.
 
 For a correction that Hunch can express as a deterministic policy, create and inspect its
 proof-backed proposal:
@@ -142,7 +152,7 @@ but stops automatic memory commits and pushes. As a team-coordinated rollback, r
 commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
 local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
 rollback. For this rollout, reinstall the previous published package with
-`npm i -g @davesheffer/hunch@1.12.1`; the release receipt resolves and records the verified rollback
+`npm i -g @davesheffer/hunch@1.16.0`; the release receipt resolves and records the verified rollback
 target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
 and keep every team client on the same release before resuming Matrix policy workflows.
 
@@ -195,6 +205,8 @@ downloaded public VSIX has the same digest as the credential-free release candid
 - [VS Code extension guide](vscode-extension/README.md)
 - [Contributing](CONTRIBUTING.md)
 - [Architecture benchmark](bench/architectural-conformance.md)
+- [Engineering Landscape Graph and ORC boundary](docs/engineering-landscape.md)
+- [ORC outcome/experience protocol](docs/outcome-experience-protocol.md)
 - [Competitive landscape (dated; re-verify before quoting)](docs/competitive-landscape.md)
 
 Apache-2.0

package/dist/cli/index.js

@@ -73,6 +73,7 @@ import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, isInForce, liveForTopic } from "../core/topics.js";
 import { ADR_DIR_CANDIDATES, ADR_FILE_RE, mapAdrCorpus } from "../extractors/adrImport.js";
 import { exportMadrCorpus, isRegenerableMadr } from "../integrations/madrExport.js";
+import { buildMadrManifest, writeMadrManifest, refreshMadrCorpus } from "../integrations/madrManifest.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
@@ -113,6 +114,9 @@ function openTeamStore(root, opts = {}) {
     const teamWired = ensureTeamOverlay(root);
     const store = new HunchStore(hunchPaths(root));
     openStore = store;
+    const overlayWarning = store.overlayResolutionWarning(explicitOverlay && existsSync(teamFile));
+    if (overlayWarning)
+        console.error(`[hunch] ⚠ ${overlayWarning}`);
     if (teamAdvertised && (store.mode !== "shared"
         || !store.privateDir
         || !existsSync(store.privateDir)
@@ -500,6 +504,21 @@ program
     else if (!opts.quiet) {
         console.log(`· skipped: ${r.reason}`);
     }
+    // The MADR projection tracks the graph automatically once adopted, the way the
+    // SQLite index does — a user who ran `hunch export-adr` once never runs it again.
+    // Best-effort and last-write-wins-free: a hand-edited file is skipped, not
+    // clobbered, and any failure here must never affect the capture that preceded it.
+    try {
+        const refreshed = refreshMadrCorpus(store.json.loadAll("decisions"), root, new Date().toISOString());
+        if (refreshed && !opts.quiet && (refreshed.written || refreshed.removed || refreshed.skippedEdited.length)) {
+            const skipped = refreshed.skippedEdited.length ? `, ${refreshed.skippedEdited.length} hand-edited file(s) left alone` : "";
+            console.log(`  ↳ ADR corpus refreshed: ${refreshed.written} written, ${refreshed.removed} removed${skipped} (${refreshed.dir}/)`);
+        }
+    }
+    catch (e) {
+        if (!opts.quiet)
+            console.log(`  ↳ ADR corpus refresh skipped safely: ${e.message}`);
+    }
     let graphRefreshed = false;
     let publicCorrectionQueued = false;
     let privateCorrectionQueued = false;
@@ -3097,6 +3116,10 @@ program
         // are OURS (marker-verified) and stale — remove so the corpus stays coherent.
         for (const f of stale)
             rmSync(join(outDir, f));
+        // Adopt the corpus: the manifest is what makes `hunch drift` able to notice
+        // this projection going stale, being hand-edited, or outliving its decision.
+        // Written after the files land, so a failed write never claims freshness.
+        writeMadrManifest(root, buildMadrManifest(dir, files, new Date().toISOString()));
         console.log(`✓ exported ${files.length} ADR(s) to ${dir}${stale.length ? `; removed ${stale.length} stale generated file(s)` : ""}`);
         console.log(`  ↳ Backstage: add to catalog-info.yaml metadata.annotations →  ${backstageAnnotation}`);
     }
@@ -5223,6 +5246,30 @@ program
                 console.log(`· ${f.id} — ${f.detail}`);
             console.log(`\nHeal: run \`hunch wiki --heal\` — regenerates only the stale pages (the wiki is a derived view; never edit it by hand).\n`);
         }
+        // The MADR projection: three kinds, three different human actions — which is
+        // why they are separate sections rather than one "run export-adr" line.
+        const madrStale = kind("madr-stale");
+        if (madrStale.length) {
+            console.log(`${madrStale.length} exported ADR(s) drifted from the graph:\n`);
+            for (const f of madrStale)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: run \`hunch export-adr\` — the corpus is a disposable projection (the graph stays the source of truth). Normally this never appears: the projection refreshes automatically on every capture.\n`);
+        }
+        const madrEdited = kind("madr-edited");
+        if (madrEdited.length) {
+            console.log(`${madrEdited.length} generated ADR(s) were hand-edited — the next export would overwrite them:\n`);
+            for (const f of madrEdited)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal A (the DECISION is what changed): move the edit into the decision via /capture, then let the projection regenerate — the edit survives because it now lives in the graph.`);
+            console.log(`Heal B (you want to own this file): delete the hunch:generated marker. The export refuses it from then on and it becomes a hand-written ADR.\n`);
+        }
+        const madrOrphan = kind("madr-orphan");
+        if (madrOrphan.length) {
+            console.log(`${madrOrphan.length} generated ADR(s) have no decision behind them any more:\n`);
+            for (const f of madrOrphan)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: delete the file, or run \`hunch export-adr\` to regenerate the corpus without it. If the decision moved to the private overlay, the file is a PUBLIC artifact of a now-private record — delete it.\n`);
+        }
         // Every drift kind heals here — see bug_drift_heal_asymmetry above. premise-stale
         // shipped in the drift report without a section here, so a repo whose ONLY drift
         // was a dead premise got "N findings" from `hunch drift` and a bare closing line
@@ -5387,8 +5434,8 @@ program
     }
     else if (store.privateDir) {
         console.log(store.mode === "shared"
-            ? `shared:     on → ${store.privateDir} (UNIFIED — every capture routes here; one source of truth across branches, worktrees, teammates, agents)`
-            : `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`);
+            ? `shared:     on → ${store.privateDir} (UNIFIED — every capture routes here; one source of truth across branches, worktrees, teammates, agents; source: ${store.overlaySource})`
+            : `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly; source: ${store.overlaySource})`);
     }
     else {
         const team = readTeamConfig(root);

package/dist/constitution/delta.js

@@ -27,10 +27,10 @@ function view(file, source) {
 }
 function viewOfParsed(parsed) {
     const symbols = new Map(parsed.symbols.map((s) => [symbolKey(s), s]));
-    const byStart = new Map(parsed.symbols.map((s) => [s.startByte, s]));
+    const byIndex = new Map(parsed.symbols.map((s, i) => [i, s]));
     const calls = new Map();
-    for (const [start, callees] of attributeCalls(parsed)) {
-        const caller = byStart.get(start);
+    for (const [index, callees] of attributeCalls(parsed)) {
+        const caller = byIndex.get(index);
         if (!caller)
             continue;
         for (const [callee, member] of callees) {

package/dist/constitution/evaluator.js

@@ -436,6 +436,7 @@ export function mutateSnapshotForPolicy(policy, snapshot) {
         }
         else {
             edges.push({
+                schema: "hunch.edge/1",
                 id: `edge_policy_mutation_${policy.id}`,
                 from: subjectId,
                 to: objectId,
@@ -443,6 +444,8 @@ export function mutateSnapshotForPolicy(policy, snapshot) {
                 reason: "deterministic proof mutation",
                 strength: 1,
                 provenance: { source: "derived", confidence: 1, evidence: [policy.id] },
+                environment: null,
+                metadata: {},
             });
             operator = mutationOperatorForPolicy(policy);
         }

package/dist/constitution/schema.js

@@ -14,7 +14,7 @@ export const DataClassSchema = z.enum(["public", "private", "secret"]);
 export const StructuralSymbolRefSchema = z.object({
     file: z.string().min(1),
     name: z.string().min(1),
-    kind: z.enum(["function", "method", "class", "interface", "type"]),
+    kind: z.enum(["function", "method", "class", "interface", "type", "variable", "file"]),
 });
 export const StructuralCallRefSchema = z.object({
     file: z.string().min(1),

package/dist/core/drift.js

@@ -11,6 +11,11 @@
  *                 (hash-compared via .hunch/wiki-manifest.json; only when a wiki
  *                 was adopted — see src/wiki/wiki.ts). Advisory, healed by
  *                 `hunch wiki --heal`, never a gate.
+ *   - madr-*:     the exported MADR corpus drifted from the graph — stale (the
+ *                 decision moved), edited (a human changed a generated file the
+ *                 next export would overwrite), or orphan (the decision left the
+ *                 public graph). Only when a corpus was exported; healed by
+ *                 `hunch export-adr`. See src/integrations/madrManifest.ts.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -20,6 +25,7 @@ import { evaluatePremises } from "./premises.js";
 import { parseDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
+import { computeMadrDrift } from "../integrations/madrManifest.js";
 export function computeDrift(store, root) {
     const findings = [];
     const decisions = store.recs("decisions");
@@ -142,6 +148,12 @@ export function computeDrift(store, root) {
     //    component vanished). Deterministic hash comparison against the manifest;
     //    fires only when a wiki was adopted. Advisory like every other kind here.
     findings.push(...computeWikiDrift(store, root));
+    // 6b. MADR-* — the exported ADR corpus drifted from the graph. PUBLIC decisions
+    //     only: the corpus is a committable artifact, so its freshness must be
+    //     computed from exactly the records allowed to reach it (an overlay record
+    //     leaking into a public drift report is the same class of bug as one
+    //     leaking into the export itself). Fires only where a corpus was exported.
+    findings.push(...computeMadrDrift(store.json.loadAll("decisions"), root));
     // 7. FINDING-STALE — a LIVE finding (observation, no diff) whose anchor evaporated:
     //    an affected file that no longer exists, or a violates_constraint pointing at a
     //    retired/missing rule. Deterministic + advisory (never the exit-code class):

package/dist/core/ids.js

@@ -22,6 +22,22 @@ export function componentId(name) {
 export function edgeId(from, to, type) {
     return "edge_" + shortHash(`${from}->${to}:${type}`);
 }
+/** Stable Engineering Landscape resource identity. The kind remains visible so
+ * fragments stay useful without a lookup table; the natural key is normalized
+ * only where spelling cannot carry meaning (outer whitespace, path separators,
+ * and a trailing slash). Kind-specific discovery may apply stricter canonical
+ * rules before calling this helper. */
+export function resourceId(kind, naturalKey) {
+    const normalizedKind = kind.trim().toLowerCase();
+    const normalizedKey = naturalKey.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    return `${normalizedKind}:${normalizedKey}`;
+}
+/** Resource relationships ride the existing edge graph and therefore share its
+ * endpoint/type identity rule. Keeping one helper prevents a parallel graph from
+ * minting incompatible relationship ids. */
+export function resourceRelationshipId(from, to, type) {
+    return edgeId(from, to, type);
+}
 /** Decision id. Seed with the CANONICAL full commit sha (the auto-sync and MCP
  *  commit paths both do this, so a recorded decision upgrades the auto-draft for
  *  the same commit), or with "manual:<title>" for an ad-hoc MCP decision. */

package/dist/core/migrate.js

@@ -18,7 +18,7 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { writeFileAtomic } from "./io.js";
 /** The schema generation this build writes and reads. Bump on any breaking change. */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 /** A repo whose `.hunch/` predates manifests is treated as v1. Migrations are
  *  numbered from 2 (each `version` is the number it PRODUCES), so a baseline repo
  *  runs every migration with version >= 2 — never author a no-op version:1 one. */
@@ -58,6 +58,25 @@ export const MIGRATIONS = [
             return raw;
         },
     },
+    {
+        // v3: Engineering Landscape resources reuse the existing graph. Existing
+        // edges are explicitly identified as legacy graph edges before the expanded
+        // relationship schema is validated; newly written resource relationships use
+        // hunch.resource-relationship/1 and keep their currentness/metadata.
+        version: 3,
+        description: "Version existing graph edges before adding Engineering Landscape resources and relationships",
+        up(kind, raw) {
+            if (kind === "edges") {
+                if (raw.schema === undefined)
+                    raw.schema = "hunch.edge/1";
+                if (raw.environment === undefined)
+                    raw.environment = null;
+                if (raw.metadata === undefined)
+                    raw.metadata = {};
+            }
+            return raw;
+        },
+    },
 ];
 /** Read `.hunch/manifest.json`. A missing/corrupt manifest is treated as the
  *  BASELINE version (a pre-manifest `.hunch/`), so future builds still migrate it. */

package/dist/core/types.js

@@ -6,6 +6,7 @@
  * tool inputs. Every record carries `provenance` so nothing is a blind assertion.
  */
 import { z } from "zod";
+import { resourceId, resourceRelationshipId } from "./ids.js";
 /** Where a fact came from and how much to trust it. Confidence tiers (DESIGN §4):
  *  inferred < extracted < llm_draft < llm_draft+human_confirmed/derived. */
 export const ProvenanceSchema = z.object({
@@ -29,6 +30,140 @@ export const ComponentSchema = z.object({
     created_at: z.string(),
     updated_at: z.string(),
 });
+export const RESOURCE_SCHEMA_VERSION = "hunch.resource/1";
+export const RESOURCE_RELATIONSHIP_SCHEMA_VERSION = "hunch.resource-relationship/1";
+/** Resource kinds are deliberately extensible: the initial vocabulary is
+ * documented, while repositories may add a stable snake_case kind without a
+ * schema release. */
+export const ResourceKindSchema = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
+export const ResourceCurrentnessSchema = z.object({
+    status: z.enum(["current", "unverified", "stale"]),
+    verified_at: z.string().max(64).optional().describe("ISO timestamp at which the declaration was checked"),
+    source_revision: z.string().min(1).max(512).optional().describe("immutable source/Git revision backing the declaration"),
+    source_content_hash: z.string().min(1).max(512).optional().describe("content hash when revision alone is insufficient"),
+}).strict().superRefine((currentness, ctx) => {
+    if (currentness.verified_at !== undefined && !Number.isFinite(Date.parse(currentness.verified_at))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["verified_at"], message: "resource currentness timestamp must be ISO-compatible" });
+    }
+    if (currentness.status !== "unverified"
+        && (!currentness.verified_at || (!currentness.source_revision && !currentness.source_content_hash))) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "current or stale resource evidence requires a verification timestamp and source revision or content hash",
+        });
+    }
+});
+const MetadataValueSchema = z.union([
+    z.string().max(1024),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(z.union([z.string().max(1024), z.number().finite(), z.boolean(), z.null()])).max(32),
+]);
+const SENSITIVE_METADATA_KEY = /(^|[_-])(authorization|bearer|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)($|[_-])/i;
+const SENSITIVE_ASSIGNMENT = /\b(authorization|password|passwd|private[_-]?key|secret|access[_-]?token|refresh[_-]?token|api[_-]?key)\s*[:=]\s*[^\s,;]{4,}/i;
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/i;
+const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+\/-]{12,}/i;
+/** Reject credential material while allowing ordinary architecture prose such as
+ * "authentication service" or "secrets are managed externally". */
+export function isCredentialFreeText(value) {
+    if (PRIVATE_KEY_BLOCK.test(value) || BEARER_VALUE.test(value) || SENSITIVE_ASSIGNMENT.test(value))
+        return false;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return false;
+        for (const [key] of url.searchParams)
+            if (SENSITIVE_METADATA_KEY.test(key))
+                return false;
+    }
+    catch { /* credential-free canonical locators need not be absolute URLs */ }
+    return true;
+}
+function isCanonicalResourceIdentity(value) {
+    const separator = value.indexOf(":");
+    if (separator <= 0 || separator === value.length - 1)
+        return false;
+    const kind = value.slice(0, separator);
+    const naturalKey = value.slice(separator + 1);
+    return ResourceKindSchema.safeParse(kind).success && value === resourceId(kind, naturalKey);
+}
+export const ResourceMetadataSchema = z.record(z.string().min(1).max(64), MetadataValueSchema)
+    .superRefine((metadata, ctx) => {
+    if (Object.keys(metadata).length > 64) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "resource metadata is limited to 64 fields" });
+    }
+    for (const [key, raw] of Object.entries(metadata)) {
+        if (SENSITIVE_METADATA_KEY.test(key)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: "credential-bearing metadata keys are forbidden" });
+            continue;
+        }
+        const values = Array.isArray(raw) ? raw : [raw];
+        for (const value of values) {
+            if (typeof value === "string" && !isCredentialFreeText(value)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: "credential material is forbidden in resource metadata" });
+                break;
+            }
+        }
+    }
+});
+/** Durable Engineering Landscape node. Runtime health/readiness intentionally has
+ * no field here: those expiring observations belong to ORC. */
+export const ResourceSchema = z.object({
+    schema: z.literal(RESOURCE_SCHEMA_VERSION),
+    id: z.string().min(3).max(2048).describe("stable kind-qualified resource identity"),
+    kind: ResourceKindSchema,
+    name: z.string().min(1).max(256),
+    scope: z.array(z.string().min(1).max(512)).max(16).default([]),
+    locator: z.string().min(1).max(2048).nullable().default(null),
+    lifecycle: z.enum(["planned", "active", "deprecated", "retired"]).default("active"),
+    criticality: z.enum(["low", "medium", "high", "critical"]).optional(),
+    contract_version: z.string().max(256).optional(),
+    provenance: ProvenanceSchema,
+    currentness: ResourceCurrentnessSchema,
+    metadata: ResourceMetadataSchema.default({}),
+    created_at: z.string(),
+    updated_at: z.string(),
+}).strict().superRefine((resource, ctx) => {
+    const prefix = `${resource.kind}:`;
+    const naturalKey = resource.id.startsWith(prefix) ? resource.id.slice(prefix.length) : "";
+    if (!naturalKey.trim() || resource.id !== resourceId(resource.kind, naturalKey)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "resource id must be a canonical kind-qualified identity" });
+    }
+    const credentialFreeFields = [
+        ["id", resource.id],
+        ["name", resource.name],
+        ...resource.scope.map((scope, index) => [`scope.${index}`, scope]),
+        ...(resource.locator === null ? [] : [["locator", resource.locator]]),
+        ...(resource.contract_version === undefined ? [] : [["contract_version", resource.contract_version]]),
+        ["provenance.source", resource.provenance.source],
+        ...resource.provenance.evidence.map((evidence, index) => [`provenance.evidence.${index}`, evidence]),
+        ...(resource.currentness.source_revision === undefined
+            ? []
+            : [["currentness.source_revision", resource.currentness.source_revision]]),
+        ...(resource.currentness.source_content_hash === undefined
+            ? []
+            : [["currentness.source_content_hash", resource.currentness.source_content_hash]]),
+    ];
+    for (const [field, value] of credentialFreeFields) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: String(field).split("."), message: "credential material is forbidden in resource records" });
+        }
+    }
+    if (new Set(resource.scope).size !== resource.scope.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["scope"], message: "resource scope entries must be unique" });
+    }
+    if (resource.provenance.source.length > 256 || resource.provenance.evidence.length > 64
+        || resource.provenance.evidence.some((evidence) => evidence.length > 2048)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance"], message: "resource provenance must remain bounded" });
+    }
+    if (resource.created_at.length > 64 || !Number.isFinite(Date.parse(resource.created_at))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["created_at"], message: "resource created_at must be ISO-compatible" });
+    }
+    if (resource.updated_at.length > 64 || !Number.isFinite(Date.parse(resource.updated_at))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["updated_at"], message: "resource updated_at must be ISO-compatible" });
+    }
+});
 export const EdgeType = z.enum([
     "depends_on",
     "calls",
@@ -37,9 +172,36 @@ export const EdgeType = z.enum([
     "implements",
     "supersedes",
     "related_to",
+    "references",
+    "provides",
+    "belongs_to",
+    "implemented_by",
+    "invokes",
+    "exposes",
+    "publishes",
+    "consumes",
+    "reads_from",
+    "writes_to",
+    "builds",
+    "tests",
+    "deploys",
+    "deployed_on",
+    "owned_by",
+    "monitored_by",
+    "governed_by",
+    "source_of_truth_for",
+    "compatible_with",
+    "replaces",
+]);
+export const ResourceRelationshipType = z.enum([
+    "provides", "belongs_to", "implemented_by", "contains", "depends_on", "invokes",
+    "exposes", "publishes", "consumes", "reads_from", "writes_to", "builds", "tests",
+    "deploys", "deployed_on", "owned_by", "monitored_by", "governed_by",
+    "source_of_truth_for", "compatible_with", "replaces", "implements",
 ]);
 /** Typed relationship between components or symbols. */
 export const EdgeSchema = z.object({
+    schema: z.enum(["hunch.edge/1", RESOURCE_RELATIONSHIP_SCHEMA_VERSION]).default("hunch.edge/1"),
     id: z.string().describe("edge_*"),
     from: z.string(),
     to: z.string(),
@@ -47,6 +209,49 @@ export const EdgeSchema = z.object({
     reason: z.string().default(""),
     strength: z.number().min(0).max(1).default(0.5),
     provenance: ProvenanceSchema,
+    currentness: ResourceCurrentnessSchema.optional(),
+    environment: z.string().max(256).nullable().default(null),
+    criticality: z.enum(["low", "medium", "high", "critical"]).optional(),
+    contract_version: z.string().max(256).optional(),
+    metadata: ResourceMetadataSchema.default({}),
+}).strict().superRefine((edge, ctx) => {
+    if (edge.schema !== RESOURCE_RELATIONSHIP_SCHEMA_VERSION)
+        return;
+    const credentialFreeFields = [
+        ["from", edge.from], ["to", edge.to], ["reason", edge.reason],
+        ["provenance.source", edge.provenance.source],
+        ...edge.provenance.evidence.map((evidence, index) => [`provenance.evidence.${index}`, evidence]),
+        ...(edge.environment === null ? [] : [["environment", edge.environment]]),
+        ...(edge.contract_version === undefined ? [] : [["contract_version", edge.contract_version]]),
+        ...(edge.currentness?.source_revision === undefined
+            ? []
+            : [["currentness.source_revision", edge.currentness.source_revision]]),
+        ...(edge.currentness?.source_content_hash === undefined
+            ? []
+            : [["currentness.source_content_hash", edge.currentness.source_content_hash]]),
+    ];
+    for (const [field, value] of credentialFreeFields) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: field.split("."), message: "credential material is forbidden in graph relationships" });
+        }
+    }
+    if (!ResourceRelationshipType.options.includes(edge.type)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["type"], message: "unsupported resource relationship type" });
+    }
+    if (!isCanonicalResourceIdentity(edge.from) || !isCanonicalResourceIdentity(edge.to)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["from"], message: "resource relationships require kind-qualified endpoints" });
+    }
+    if (edge.id !== resourceRelationshipId(edge.from, edge.to, edge.type)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "resource relationship id must be deterministic from endpoints and type" });
+    }
+    if (!edge.currentness) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["currentness"], message: "resource relationships require currentness evidence" });
+    }
+    if (edge.from.length > 2048 || edge.to.length > 2048 || edge.reason.length > 2048
+        || edge.provenance.source.length > 256 || edge.provenance.evidence.length > 64
+        || edge.provenance.evidence.some((evidence) => evidence.length > 2048)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance"], message: "resource relationship fields must remain bounded" });
+    }
 });
 export const SymbolKind = z.enum(["function", "method", "class", "interface", "type", "variable", "file"]);
 export const SymbolMetricsSchema = z.object({
@@ -281,9 +486,10 @@ export const FindingSchema = z.object({
     provenance: ProvenanceSchema,
 });
 /** The entity collections, keyed by their on-disk directory name. */
-export const ENTITY_KINDS = ["components", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings"];
+export const ENTITY_KINDS = ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings"];
 export const SCHEMAS = {
     components: ComponentSchema,
+    resources: ResourceSchema,
     edges: EdgeSchema,
     symbols: SymbolSchema,
     decisions: DecisionSchema,

package/dist/extractors/git.js

@@ -311,6 +311,13 @@ function remoteIdentity(raw, cwd, purpose = "route") {
         return `literal:${trimRepoSuffix(value)}`;
     }
 }
+/** Canonical repository identity for deterministic, credential-free discovery.
+ * The returned value is an internal identity: callers exposing it must hash
+ * local `file:` identities so host paths never enter graph records. Network
+ * credentials, URL query strings and fragments are deliberately excluded. */
+export function canonicalRemoteRepositoryIdentity(raw, cwd) {
+    return remoteIdentity(raw, cwd, "publication");
+}
 function localRemotePath(raw, cwd) {
     const value = raw.trim();
     if (!value)