@davesheffer/hunch 1.17.0 → 1.18.0

package/README.md

@@ -6,10 +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 a guarantee: **your agents never re-make a decided decision, and never re-introduce a
-fixed bug.** The mechanism behind it 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.
+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.
@@ -17,10 +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.17.0:** an exported ADR corpus now tracks the graph automatically and reports its
-> own drift (`madr-stale` / `madr-edited` / `madr-orphan`), and retrieval ranks recorded intent
-> above code symbols that merely share the query's vocabulary — Recall@10 70% → 90% on the
-> curated benchmark.
+> **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.
 
@@ -50,8 +51,8 @@ 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, Python, and Go 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.
@@ -88,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"
@@ -103,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
@@ -121,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:
@@ -148,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.
 
@@ -201,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

@@ -114,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)
@@ -5431,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/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)

package/dist/extractors/helm.js

@@ -0,0 +1,77 @@
+/**
+ * Deterministic text scan for Helm's `define`/`include`/`template` Go-template
+ * actions — NOT a Go-template parser, and NOT a tree-sitter query. tree-sitter-yaml
+ * has no notion of `{{ }}` content: parsing `{{ include "x" . }}` inside a real
+ * YAML mapping value produces only stray `{` flow-mapping-open tokens, with the
+ * enclosed text lost to ERROR recovery (verified directly against this repo's
+ * tree-sitter-yaml bundle). There is nothing for a tree-sitter query to capture,
+ * so this runs as a sidecar text scan over the raw source — invoked only for
+ * files under a Helm chart (indexer.ts's chart-root detection), never for
+ * arbitrary YAML.
+ *
+ * Known bounded limitation: this is a token scan, not a full parser. A literal
+ * `}}` inside a quoted argument, or an include/define-shaped string inside a
+ * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
+ * Both are bounded failure modes (a stray reference to a real symbol name, or a
+ * slightly-long symbol range) — the same class of accepted limitation
+ * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
+ * The chart-wide `importedFiles` widening this module's output flows through
+ * (indexer.ts) also lets a YAML alias resolve to an anchor in a sibling chart
+ * file, even though YAML anchors are properly document-scoped; this only fires
+ * when the alias has no matching anchor in its own file (i.e. only on input
+ * that's already invalid YAML on its own terms), so it's bounded, but it's a
+ * real, disclosed side effect of the chart-scoping mechanism, not something to
+ * silently rely on.
+ */
+import { MAX_BODY_TEXT_CHARS } from "./parse.js";
+// Matches one `{{ ... }}` action, including the `{{-`/`-}}` whitespace-trim
+// markers. Non-greedy so a multi-action line matches each action separately.
+const ACTION = /\{\{-?([\s\S]*?)-?\}\}/g;
+const BLOCK_OPEN = new Set(["if", "range", "with", "define", "block"]);
+const NAME_ARG = /^"([^"]*)"/;
+// Matched against an action's RAW inner text (not just a leading keyword) so
+// `{{ $labels := include "x" . }}` and `{{ if include "x" . }}` are caught,
+// not only the standalone `{{ include "x" . }}` form.
+const CALL_SITE = /\b(?:include|template)\s+"([^"]+)"/g;
+export function extractHelmDirectives(source) {
+    const symbols = [];
+    const calls = [];
+    const stack = [];
+    for (const m of source.matchAll(ACTION)) {
+        const raw = m[1];
+        // "{{" is 2 chars; a trim-marker "{{-" is 3 — this is the byte offset of
+        // `raw`'s first character within `source`, needed for call-site atByte math.
+        const innerStart = m.index + (source[m.index + 2] === "-" ? 3 : 2);
+        const endByte = m.index + m[0].length;
+        const body = raw.trim();
+        const spaceIdx = body.search(/\s/);
+        const keyword = spaceIdx === -1 ? body : body.slice(0, spaceIdx);
+        if (keyword === "define") {
+            const name = NAME_ARG.exec(body.slice(spaceIdx + 1).trim())?.[1];
+            stack.push({ name, startByte: m.index });
+        }
+        else if (BLOCK_OPEN.has(keyword)) {
+            // if/range/with/block: depth marker only, no symbol on its own.
+            stack.push({ startByte: m.index });
+        }
+        else if (keyword === "end") {
+            const open = stack.pop();
+            if (open?.name) {
+                symbols.push({
+                    name: open.name,
+                    kind: "variable",
+                    startByte: open.startByte,
+                    endByte,
+                    loc: source.slice(open.startByte, endByte).split("\n").length,
+                    bodyText: source.slice(open.startByte, endByte).slice(0, MAX_BODY_TEXT_CHARS),
+                });
+            }
+        }
+        for (const call of raw.matchAll(CALL_SITE)) {
+            const atByte = innerStart + call.index;
+            calls.push({ callee: call[1], atByte, endByte: atByte + call[0].length, member: false });
+        }
+    }
+    return { symbols, calls };
+}
+//# sourceMappingURL=helm.js.map