@chrisdudek/yg 5.4.1 → 5.5.0

package/dist/det-worker.js

@@ -0,0 +1,1715 @@
+// src/structure/det-worker.ts
+import { parentPort, workerData } from "worker_threads";
+
+// src/structure/ctx-fs.ts
+import * as fs from "fs";
+import * as path from "path";
+
+// src/utils/mapping-path.ts
+import { minimatch } from "minimatch";
+function normalizeMappingPath(p) {
+  return p.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function isGlobPattern(entry) {
+  return entry.includes("*");
+}
+function globMatch(file, pattern) {
+  return minimatch(file, pattern, { dot: true });
+}
+function mappingEntryMatchesFile(entry, file) {
+  const e = normalizeMappingPath(entry);
+  const f = normalizeMappingPath(file);
+  if (e === "") return false;
+  if (isGlobPattern(e)) return globMatch(f, e);
+  return f === e || f.startsWith(e + "/");
+}
+
+// src/utils/posix.ts
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function toPosixPath(p) {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+
+// src/structure/ctx-fs.ts
+var UndeclaredFsReadError = class extends Error {
+  constructor(path9) {
+    super(`structure-aspect-undeclared-fs-read: ${path9}`);
+    this.path = path9;
+    this.name = "UndeclaredFsReadError";
+  }
+  path;
+};
+function isAllowed(p, set) {
+  if (p === "") return false;
+  if (set.has(p)) return true;
+  for (const a of set) {
+    if (a.startsWith(p + "/")) return true;
+    if (mappingEntryMatchesFile(a, p)) return true;
+  }
+  return false;
+}
+function assertRealpathContained(abs, projectRoot, rel) {
+  let realRoot;
+  try {
+    realRoot = fs.realpathSync(projectRoot);
+  } catch {
+    realRoot = projectRoot;
+  }
+  let probe = abs;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) return;
+    probe = parent;
+  }
+  let realProbe;
+  try {
+    realProbe = fs.realpathSync(probe);
+  } catch {
+    return;
+  }
+  const relReal = toPosix(path.relative(realRoot, realProbe));
+  if (relReal === ".." || relReal.startsWith("../") || path.isAbsolute(relReal)) {
+    throw new UndeclaredFsReadError(rel);
+  }
+}
+function resolveAllowedReadPath(raw, allowedSet, projectRoot) {
+  const abs = path.resolve(projectRoot, normalizeMappingPath(raw));
+  const rel = toPosix(path.relative(projectRoot, abs));
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new UndeclaredFsReadError(normalizeMappingPath(raw));
+  }
+  if (!isAllowed(rel, allowedSet)) throw new UndeclaredFsReadError(rel);
+  assertRealpathContained(abs, projectRoot, rel);
+  return rel;
+}
+function createCtxFs(params) {
+  const { allowedSet, projectRoot, touchedFiles, recorder, subjectFiles } = params;
+  function assertAllowed(raw) {
+    const p = resolveAllowedReadPath(raw, allowedSet, projectRoot);
+    touchedFiles.push(p);
+    return p;
+  }
+  function isSubjectFile(p) {
+    return subjectFiles !== void 0 && subjectFiles.has(p);
+  }
+  return {
+    exists(raw) {
+      const p = assertAllowed(raw);
+      const abs = path.resolve(projectRoot, p);
+      let result;
+      try {
+        const stat2 = fs.statSync(abs);
+        result = stat2.isDirectory() ? "dir" : stat2.isFile() ? "file" : false;
+      } catch {
+        result = false;
+      }
+      if (recorder && !isSubjectFile(p)) {
+        recorder.recordExists(p, result);
+      }
+      return result;
+    },
+    read(raw) {
+      const p = assertAllowed(raw);
+      const abs = path.resolve(projectRoot, p);
+      let bytes;
+      try {
+        bytes = fs.readFileSync(abs);
+      } catch (err) {
+        if (recorder && !isSubjectFile(p)) recorder.recordReadAbsent(p);
+        throw err;
+      }
+      if (recorder && !isSubjectFile(p)) {
+        recorder.recordRead(p, bytes);
+      }
+      return bytes.toString("utf8");
+    },
+    list(raw) {
+      const p = assertAllowed(raw);
+      const abs = path.resolve(projectRoot, p);
+      let dirents;
+      try {
+        dirents = fs.readdirSync(abs, { withFileTypes: true });
+      } catch (err) {
+        if (recorder && !isSubjectFile(p)) recorder.recordListAbsent(p);
+        throw err;
+      }
+      const entries = dirents.map((e) => ({
+        name: e.name,
+        kind: e.isDirectory() ? "dir" : "file"
+      }));
+      if (recorder && !isSubjectFile(p)) {
+        recorder.recordList(p, entries);
+      }
+      return entries;
+    }
+  };
+}
+
+// src/structure/ctx-graph.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+
+// src/structure/expand-mapping-sync.ts
+function isPathInMapping(candidate, mapping) {
+  const c = normalizeMappingPath(candidate);
+  if (c === "") return false;
+  return mapping.some((raw) => mappingEntryMatchesFile(raw, c));
+}
+
+// src/structure/ctx-graph.ts
+var UndeclaredGraphReadError = class extends Error {
+  constructor(nodePath) {
+    super(`structure-aspect-undeclared-graph-read: ${nodePath}`);
+    this.nodePath = nodePath;
+    this.name = "UndeclaredGraphReadError";
+  }
+  nodePath;
+};
+function makeGraphFile(repoRelPosixPath, content, bytes, recorder, subjectFiles) {
+  if (!recorder || subjectFiles?.has(repoRelPosixPath)) {
+    return { path: repoRelPosixPath, content };
+  }
+  const rec = recorder;
+  let recorded = false;
+  const file = { path: repoRelPosixPath };
+  Object.defineProperty(file, "content", {
+    enumerable: true,
+    configurable: true,
+    get() {
+      if (!recorded) {
+        rec.recordRead(repoRelPosixPath, bytes);
+        recorded = true;
+      }
+      return content;
+    }
+  });
+  return file;
+}
+function computeAllowedNodePaths(currentPath, graph) {
+  const allowed = /* @__PURE__ */ new Set([currentPath]);
+  const current = graph.nodes.get(currentPath);
+  if (!current) return allowed;
+  for (const rel of current.meta.relations ?? []) {
+    allowed.add(rel.target);
+    const target = graph.nodes.get(rel.target);
+    if (!target) continue;
+    const relStack = [...target.children];
+    while (relStack.length > 0) {
+      const n = relStack.pop();
+      allowed.add(n.path);
+      relStack.push(...n.children);
+    }
+  }
+  let cursor = current.parent;
+  while (cursor) {
+    allowed.add(cursor.path);
+    cursor = cursor.parent;
+  }
+  const stack = [...current.children];
+  while (stack.length) {
+    const n = stack.pop();
+    allowed.add(n.path);
+    stack.push(...n.children);
+  }
+  return allowed;
+}
+function createCtxGraph(params) {
+  const { currentNodePath, graph, projectRoot, touchedFiles, expandedFilesByNode, recorder, subjectFiles } = params;
+  const allowed = computeAllowedNodePaths(currentNodePath, graph);
+  function assertAllowed(id) {
+    if (!allowed.has(id)) throw new UndeclaredGraphReadError(id);
+  }
+  function recordGraphNode(m) {
+    if (!recorder) return;
+    const ygNodePath = path2.join(projectRoot, ".yggdrasil", "model", m.path, "yg-node.yaml");
+    let yamlBytes;
+    try {
+      yamlBytes = fs2.readFileSync(ygNodePath);
+    } catch {
+      yamlBytes = m.nodeYamlRaw !== void 0 ? Buffer.from(m.nodeYamlRaw, "utf8") : void 0;
+    }
+    if (yamlBytes === void 0) {
+      recorder.recordGraphNodeAbsent(m.path);
+    } else {
+      recorder.recordGraphNode(m.path, yamlBytes);
+    }
+  }
+  function toPublicNode(m) {
+    const files = [];
+    const preExpanded = expandedFilesByNode?.get(m.path);
+    const candidatePaths = preExpanded ?? (m.meta.mapping ?? []).map(normalizeMappingPath);
+    for (const p of candidatePaths) {
+      if (!p) continue;
+      const abs = path2.resolve(projectRoot, p);
+      try {
+        const stat2 = fs2.statSync(abs);
+        if (stat2.isFile()) {
+          const bytes = fs2.readFileSync(abs);
+          const content = bytes.toString("utf8");
+          touchedFiles.push(p);
+          files.push(makeGraphFile(p, content, bytes, recorder, subjectFiles));
+        }
+      } catch {
+      }
+    }
+    recordGraphNode(m);
+    return {
+      id: m.path,
+      type: m.meta.type,
+      mapping: m.meta.mapping ?? [],
+      files,
+      ports: m.meta.ports ?? {}
+    };
+  }
+  return {
+    node(id) {
+      const self = graph.nodes.get(currentNodePath);
+      if (self) recordGraphNode(self);
+      if (!allowed.has(id)) {
+        assertAllowed(id);
+      }
+      const m = graph.nodes.get(id);
+      if (!m) {
+        if (recorder) recorder.recordGraphNodeAbsent(id);
+        return void 0;
+      }
+      return toPublicNode(m);
+    },
+    nodesByType(type) {
+      const out = [];
+      const matchedIds = [];
+      for (const id of allowed) {
+        const m = graph.nodes.get(id);
+        if (m && m.meta.type === type) {
+          matchedIds.push(m.path);
+          out.push(toPublicNode(m));
+        }
+      }
+      if (recorder) recorder.recordGraphNodesByType(type, matchedIds);
+      return out;
+    },
+    relationsFrom(node) {
+      assertAllowed(node.id);
+      const m = graph.nodes.get(node.id);
+      if (m) recordGraphNode(m);
+      return m?.meta.relations ?? [];
+    },
+    relationsTo(node) {
+      const out = [];
+      for (const id of allowed) {
+        const m = graph.nodes.get(id);
+        if (!m) continue;
+        recordGraphNode(m);
+        for (const rel of m.meta.relations ?? []) {
+          if (rel.target === node.id) out.push(rel);
+        }
+      }
+      return out;
+    },
+    children(node) {
+      assertAllowed(node.id);
+      const m = graph.nodes.get(node.id);
+      const childIds = m ? m.children.map((c) => c.path) : [];
+      if (recorder) recorder.recordGraphChildren(node.id, childIds);
+      return m ? m.children.map(toPublicNode) : [];
+    },
+    flowParticipants(flowName) {
+      const flow = graph.flows.find((f) => f.name === flowName || f.path === flowName);
+      if (!flow) return [];
+      const participates = flow.nodes.some((n) => {
+        if (n === currentNodePath) return true;
+        let cursor = graph.nodes.get(currentNodePath)?.parent;
+        while (cursor) {
+          if (cursor.path === n) return true;
+          cursor = cursor.parent;
+        }
+        return false;
+      });
+      if (!participates) throw new UndeclaredGraphReadError(`flow:${flowName}`);
+      if (recorder) recorder.recordFlowParticipants(flow.name, [...flow.nodes]);
+      const out = [];
+      for (const nodeId of flow.nodes) {
+        const m = graph.nodes.get(nodeId);
+        if (m) out.push(toPublicNode(m));
+      }
+      return out;
+    }
+  };
+}
+
+// src/structure/ctx-parsers.ts
+import * as fs3 from "fs";
+import * as path4 from "path";
+import { extname } from "path";
+import { parse as parseYaml } from "yaml";
+import { parse as parseTomlSmol } from "smol-toml";
+
+// src/ast/parser.ts
+import { Parser, Language } from "web-tree-sitter";
+import path3 from "path";
+import { fileURLToPath } from "url";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { createRequire } from "module";
+import { createHash } from "crypto";
+
+// src/core/graph/language-registry.ts
+var LANGUAGES = {
+  typescript: {
+    id: "typescript",
+    extensions: [".ts"],
+    wasmFile: "tree-sitter-typescript.wasm",
+    wasmPackage: "tree-sitter-typescript",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-typescript",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  tsx: {
+    id: "tsx",
+    extensions: [".tsx"],
+    wasmFile: "tree-sitter-tsx.wasm",
+    wasmPackage: "tree-sitter-typescript",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-typescript",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  javascript: {
+    id: "javascript",
+    extensions: [".js", ".mjs", ".cjs", ".jsx"],
+    wasmFile: "tree-sitter-javascript.wasm",
+    wasmPackage: "tree-sitter-javascript",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-javascript",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  python: {
+    id: "python",
+    extensions: [".py"],
+    wasmFile: "tree-sitter-python.wasm",
+    wasmPackage: "tree-sitter-python",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-python",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["#"]
+  },
+  go: {
+    id: "go",
+    extensions: [".go"],
+    wasmFile: "tree-sitter-go.wasm",
+    wasmPackage: "tree-sitter-go",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-go",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  rust: {
+    id: "rust",
+    extensions: [".rs"],
+    wasmFile: "tree-sitter-rust.wasm",
+    wasmPackage: "tree-sitter-rust",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-rust",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["line_comment", "block_comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  java: {
+    id: "java",
+    extensions: [".java"],
+    wasmFile: "tree-sitter-java.wasm",
+    wasmPackage: "tree-sitter-java",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-java",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["line_comment", "block_comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  csharp: {
+    id: "csharp",
+    extensions: [".cs"],
+    wasmFile: "tree-sitter-c_sharp.wasm",
+    wasmPackage: "tree-sitter-c-sharp",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-c-sharp",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  c: {
+    id: "c",
+    extensions: [".c", ".h"],
+    wasmFile: "tree-sitter-c.wasm",
+    wasmPackage: "tree-sitter-c",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-c",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  cpp: {
+    id: "cpp",
+    extensions: [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx"],
+    wasmFile: "tree-sitter-cpp.wasm",
+    wasmPackage: "tree-sitter-cpp",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-cpp",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  php: {
+    id: "php",
+    extensions: [".php"],
+    wasmFile: "tree-sitter-php_only.wasm",
+    wasmPackage: "tree-sitter-php",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-php",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["//", "#", "/*"]
+  },
+  ruby: {
+    id: "ruby",
+    extensions: [".rb"],
+    wasmFile: "tree-sitter-ruby.wasm",
+    wasmPackage: "tree-sitter-ruby",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-ruby",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["#"]
+  },
+  json: {
+    id: "json",
+    extensions: [".json"],
+    wasmFile: "tree-sitter-json.wasm",
+    wasmPackage: "tree-sitter-json",
+    grammarRepo: "https://github.com/tree-sitter/tree-sitter-json",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: [],
+    commentDelimiters: []
+  },
+  kotlin: {
+    id: "kotlin",
+    extensions: [".kt", ".kts"],
+    wasmFile: "tree-sitter-kotlin.wasm",
+    wasmPackage: "@tree-sitter-grammars/tree-sitter-kotlin",
+    grammarRepo: "https://github.com/tree-sitter-grammars/tree-sitter-kotlin",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["line_comment", "block_comment"],
+    commentDelimiters: ["//", "/*"]
+  },
+  yaml: {
+    id: "yaml",
+    extensions: [".yaml", ".yml"],
+    wasmFile: "tree-sitter-yaml.wasm",
+    wasmPackage: "@tree-sitter-grammars/tree-sitter-yaml",
+    grammarRepo: "https://github.com/tree-sitter-grammars/tree-sitter-yaml",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["#"]
+  },
+  toml: {
+    id: "toml",
+    extensions: [".toml"],
+    wasmFile: "tree-sitter-toml.wasm",
+    wasmPackage: "@tree-sitter-grammars/tree-sitter-toml",
+    grammarRepo: "https://github.com/tree-sitter-grammars/tree-sitter-toml",
+    grammarCommit: "",
+    treeSitterCliVersion: "",
+    externalScanner: false,
+    commentTypes: ["comment"],
+    commentDelimiters: ["#"]
+  }
+};
+var EXTENSION_TO_LANGUAGE = Object.fromEntries(
+  Object.values(LANGUAGES).flatMap((def) => def.extensions.map((ext) => [ext, def.id]))
+);
+function getLanguageForExtension(ext, overrides) {
+  if (overrides && ext in overrides) return overrides[ext];
+  return EXTENSION_TO_LANGUAGE[ext] ?? null;
+}
+function getGrammarForExtension(ext) {
+  const lang = getLanguageForExtension(ext.toLowerCase());
+  if (lang === null) return null;
+  const def = LANGUAGES[lang];
+  if (!def) return null;
+  return { wasmFile: def.wasmFile, wasmPackage: def.wasmPackage };
+}
+
+// src/ast/parser.ts
+var _require = createRequire(import.meta.url);
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path3.dirname(__filename);
+var GRAMMAR_DIRS = [
+  path3.resolve(__dirname, "grammars"),
+  path3.resolve(__dirname, "..", "grammars")
+];
+var initPromise = null;
+var langCache = /* @__PURE__ */ new Map();
+var parserCache = /* @__PURE__ */ new Map();
+function init() {
+  if (initPromise === null) {
+    initPromise = Parser.init();
+    initPromise.catch(() => {
+      initPromise = null;
+    });
+  }
+  return initPromise;
+}
+function resolveWasm(filename, pkg) {
+  for (const dir of GRAMMAR_DIRS) {
+    const p = path3.join(dir, filename);
+    if (existsSync2(p)) return p;
+  }
+  try {
+    const pkgDir = path3.dirname(_require.resolve(`${pkg}/package.json`));
+    for (const candidate of [path3.join(pkgDir, filename), path3.join(pkgDir, "bindings/node", filename)]) {
+      if (existsSync2(candidate)) return candidate;
+    }
+  } catch {
+  }
+  throw new Error(`Could not find WASM grammar ${filename} in dist/grammars/ or in the ${pkg} package.`);
+}
+async function getParser(extension) {
+  await init();
+  const info = getGrammarForExtension(extension);
+  if (!info) {
+    throw new Error(`no parser for extension '${extension}'`);
+  }
+  const cacheKey = info.wasmFile;
+  let langP = langCache.get(cacheKey);
+  if (langP === void 0) {
+    const wasmPath = resolveWasm(info.wasmFile, info.wasmPackage);
+    langP = Language.load(wasmPath);
+    langCache.set(cacheKey, langP);
+    langP.catch(() => {
+      if (langCache.get(cacheKey) === langP) langCache.delete(cacheKey);
+    });
+  }
+  const lang = await langP;
+  const existing = parserCache.get(cacheKey);
+  if (existing) return existing;
+  const parser = new Parser();
+  parser.setLanguage(lang);
+  parserCache.set(cacheKey, parser);
+  return parser;
+}
+async function parseFile(filePath, content) {
+  const ext = path3.extname(filePath);
+  const parser = await getParser(ext);
+  const tree = parser.parse(content);
+  if (tree === null) {
+    throw new Error(`tree-sitter failed to parse file: ${filePath}`);
+  }
+  return tree;
+}
+
+// src/structure/ctx-parsers.ts
+var ParseAstNotPrewarmedError = class extends Error {
+  constructor(filePath) {
+    super(
+      `structure-aspect-parseast-not-prewarmed: ${filePath}. The dispatcher did not prewarm this file. Either (i) add a declared relation to the node owning this file, or (ii) use ctx.parseYaml/Json/Toml if AST is not required.`
+    );
+    this.filePath = filePath;
+    this.name = "ParseAstNotPrewarmedError";
+  }
+  filePath;
+};
+function createCtxParsers(params) {
+  const { allowedSet, projectRoot, touchedFiles, astCache, recorder, subjectFiles } = params;
+  function asFile(input) {
+    if (typeof input !== "string") {
+      touchedFiles.push(input.path);
+      return input;
+    }
+    const p = resolveAllowedReadPath(input, allowedSet, projectRoot);
+    const abs = path4.resolve(projectRoot, p);
+    let bytes;
+    try {
+      bytes = fs3.readFileSync(abs);
+    } catch (err) {
+      if (recorder && !subjectFiles?.has(p)) recorder.recordReadAbsent(p);
+      throw err;
+    }
+    const content = bytes.toString("utf8");
+    touchedFiles.push(p);
+    if (recorder && !subjectFiles?.has(p)) {
+      recorder.recordRead(p, bytes);
+    }
+    return { path: p, content };
+  }
+  return {
+    parseAst(file, language) {
+      void language;
+      const f = asFile(file);
+      const cached = astCache.get(f.path);
+      if (cached && cached.content === f.content) return cached.ast;
+      throw new ParseAstNotPrewarmedError(f.path);
+    },
+    parseYaml(file) {
+      return parseYaml(asFile(file).content);
+    },
+    parseJson(file) {
+      return JSON.parse(asFile(file).content);
+    },
+    parseToml(file) {
+      return parseTomlSmol(asFile(file).content);
+    }
+  };
+}
+async function prewarmupAstCache(params) {
+  const { astCache, files } = params;
+  for (const f of files) {
+    if (!isAstLanguageExtension(f.path)) continue;
+    const existing = astCache.get(f.path);
+    if (existing && existing.content === f.content) continue;
+    const tree = await parseFile(f.path, f.content);
+    astCache.set(f.path, { content: f.content, ast: tree });
+  }
+}
+function isAstLanguageExtension(p) {
+  return getLanguageForExtension(extname(p).toLowerCase()) !== null;
+}
+function enrichFilesWithAst(files, astCache) {
+  return files.map((f) => {
+    const language = getLanguageForExtension(extname(f.path)) ?? void 0;
+    const cached = astCache.get(f.path);
+    const ast = cached && cached.content === f.content ? cached.ast : void 0;
+    return { ...f, ast, language };
+  });
+}
+
+// src/ast/suppress.ts
+import { extname as extname3 } from "path";
+
+// src/ast/find-comments.ts
+import { extname as extname2 } from "path";
+function findComments(target) {
+  const hasAst = "ast" in target;
+  const hasRootNode = "rootNode" in target;
+  if (hasAst && hasRootNode) {
+    throw new Error("AST_FINDCOMMENTS_AMBIGUOUS_TARGET: pass either ast or rootNode, not both");
+  }
+  let language = "language" in target ? target.language : void 0;
+  if (language === void 0 && "path" in target) {
+    language = getLanguageForExtension(extname2(target.path)) ?? void 0;
+  }
+  if (language === void 0) {
+    throw new Error(
+      "AST_FINDCOMMENTS_NO_LANGUAGE: pass a SourceFile whose path has a known extension, or an explicit { language }"
+    );
+  }
+  const def = LANGUAGES[language];
+  if (def === void 0) {
+    throw new Error(`AST_FINDCOMMENTS_UNKNOWN_LANGUAGE: '${language}' not in registry`);
+  }
+  const root = hasAst ? target.ast.rootNode : target.rootNode;
+  const out = [];
+  for (const type of def.commentTypes) {
+    out.push(...root.descendantsOfType(type));
+  }
+  return out;
+}
+
+// src/ast/suppress.ts
+var SuppressMarkerError = class extends Error {
+  constructor(message, file, line) {
+    super(message);
+    this.file = file;
+    this.line = line;
+    this.name = "SuppressMarkerError";
+    const loc = `${toPosixPath(file)}:${line}`;
+    this.messageData = {
+      what: `Malformed yg-suppress marker at ${loc} \u2014 it is missing the required reason after the aspect id.`,
+      why: `A single-line or disable marker must carry a reason after its closing parenthesis; a reasonless marker cannot be honored. This is a fault in the source file's marker, not in the aspect's check.`,
+      next: `Add a reason to the marker at ${loc}, or remove it.`
+    };
+  }
+  file;
+  line;
+  code = "SUPPRESS_MARKER_MISSING_REASON";
+  /**
+   * Self-describing what/why/next for the malformed marker. A reasonless marker
+   * is a fault in the SOURCE file's marker — NOT in the aspect's check.mjs — so
+   * the deterministic runners re-surface this as its own diagnostic instead of an
+   * `aspect-check-runtime-error`. (The LLM-sizing paths build their own message
+   * from `file`/`line`; only the deterministic consumers read `messageData`.)
+   */
+  messageData;
+};
+var LEADER_DELIM = String.raw`\/\/[/!]*|\/\*+|\*+|#+|--+|;+|<!--|\{-|\(\*|[!%'"]`;
+var RE_LEADER_OPTIONAL = new RegExp(String.raw`^\s*(${LEADER_DELIM})?\s*`);
+var RE_LEADER_REQUIRED = new RegExp(String.raw`^\s*(${LEADER_DELIM})\s*`);
+var RE_MARKER = /^yg-suppress(-disable|-enable)?\(\s*([^)]*?)\s*\)\s*(.*)$/;
+var RE_ASPECT_ID = /^(?:\*|[A-Za-z0-9_][A-Za-z0-9_./-]*)$/;
+var RE_ANY_CLOSER = /\s*(?:\*+\/|-->|-\}|\*\))\s*$/;
+var RE_CLOSER_CSTYLE = /\s*\*+\/\s*$/;
+var RE_CLOSER_HTML = /\s*-->\s*$/;
+var RE_CLOSER_HASKELL = /\s*-\}\s*$/;
+var RE_CLOSER_OCAML = /\s*\*\)\s*$/;
+function stripCloser(reason, leader) {
+  if (leader === void 0) return reason.replace(RE_ANY_CLOSER, "");
+  if (leader.startsWith("//")) return reason;
+  if (leader.startsWith("/*") || /^\*+$/.test(leader)) return reason.replace(RE_CLOSER_CSTYLE, "");
+  if (leader === "<!--") return reason.replace(RE_CLOSER_HTML, "");
+  if (leader === "{-") return reason.replace(RE_CLOSER_HASKELL, "");
+  if (leader === "(*") return reason.replace(RE_CLOSER_OCAML, "");
+  return reason;
+}
+function splitAspectList(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function matchMarkerLine(line, requireDelimiter) {
+  if (line.endsWith("\r")) line = line.slice(0, -1);
+  const leader = (requireDelimiter ? RE_LEADER_REQUIRED : RE_LEADER_OPTIONAL).exec(line);
+  if (leader === null) return null;
+  const m = RE_MARKER.exec(line.slice(leader[0].length));
+  if (m === null) return null;
+  const aspectIds = splitAspectList(m[2]);
+  if (aspectIds.length === 0) return null;
+  if (!aspectIds.every((id) => RE_ASPECT_ID.test(id))) return null;
+  const kind = m[1] === "-disable" ? "disable" : m[1] === "-enable" ? "enable" : "single";
+  const reason = kind === "enable" ? "" : stripCloser(m[3], leader[1]).trim();
+  return { kind, aspectIds, reason };
+}
+function parseMarker(lineText, line, file, requireDelimiter) {
+  const m = matchMarkerLine(lineText, requireDelimiter);
+  if (m === null) return null;
+  if (m.kind !== "enable" && m.reason === "") {
+    throw new SuppressMarkerError(
+      `yg-suppress${m.kind === "disable" ? "-disable" : ""}(${m.aspectIds.join(", ")}) missing reason at ${file}:${line}`,
+      file,
+      line
+    );
+  }
+  return { kind: m.kind, aspectIds: m.aspectIds, reason: m.reason, line };
+}
+var RE_FENCE = /^ {0,3}((?:`{3,})|(?:~{3,}))[ \t]*(.*)$/;
+var MARKDOWN_EXTS = /* @__PURE__ */ new Set([".md", ".markdown"]);
+function isMarkdownExt(file) {
+  return MARKDOWN_EXTS.has(extname3(file).toLowerCase());
+}
+function markdownFencedLines(text) {
+  const fenced = /* @__PURE__ */ new Set();
+  const lines = text.split("\n");
+  let open = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = RE_FENCE.exec(lines[i]);
+    if (open === null) {
+      if (m) {
+        open = { char: m[1][0], len: m[1].length };
+        fenced.add(i + 1);
+      }
+      continue;
+    }
+    fenced.add(i + 1);
+    if (m && m[1][0] === open.char && m[1].length >= open.len && m[2].trim() === "") {
+      open = null;
+    }
+  }
+  return fenced;
+}
+function collectSuppressions(tree, file, totalLines, content) {
+  const hasGrammar = getLanguageForExtension(extname3(file)) !== null;
+  const markers = [];
+  if (hasGrammar && tree) {
+    const comments = findComments({ path: file, ast: tree });
+    for (const c of comments) {
+      const commentLines = c.text.split("\n");
+      for (let i = 0; i < commentLines.length; i++) {
+        const m = parseMarker(commentLines[i], c.startPosition.row + i + 1, file, false);
+        if (m) markers.push(m);
+      }
+    }
+  } else if (content !== void 0) {
+    const lines = content.split("\n");
+    const fenced = isMarkdownExt(file) ? markdownFencedLines(content) : null;
+    for (let i = 0; i < lines.length; i++) {
+      if (fenced && fenced.has(i + 1)) continue;
+      const m = parseMarker(lines[i], i + 1, file, true);
+      if (m) markers.push(m);
+    }
+  } else {
+    return [];
+  }
+  markers.sort((a, b) => a.line - b.line);
+  const ranges = [];
+  const openSpecific = /* @__PURE__ */ new Map();
+  let openWildcard = null;
+  for (const m of markers) {
+    if (m.kind === "single") {
+      const isWildcard = m.aspectIds.includes("*");
+      ranges.push({ aspectIds: new Set(m.aspectIds), startLine: m.line + 1, endLine: m.line + 1, isWildcard });
+    } else if (m.kind === "disable") {
+      for (const id of m.aspectIds) {
+        if (id === "*") {
+          if (openWildcard === null) openWildcard = m.line + 1;
+        } else {
+          if (!openSpecific.has(id)) openSpecific.set(id, m.line + 1);
+        }
+      }
+    } else {
+      for (const id of m.aspectIds) {
+        if (id === "*") {
+          if (openWildcard !== null) {
+            if (m.line - 1 >= openWildcard) {
+              ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: m.line - 1, isWildcard: true });
+            }
+            openWildcard = null;
+          }
+        } else {
+          const start = openSpecific.get(id);
+          if (start !== void 0) {
+            if (m.line - 1 >= start) {
+              ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: m.line - 1, isWildcard: false });
+            }
+            openSpecific.delete(id);
+          }
+        }
+      }
+    }
+  }
+  if (openWildcard !== null && openWildcard <= totalLines) ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: totalLines, isWildcard: true });
+  for (const [id, start] of openSpecific) {
+    if (start <= totalLines) ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: totalLines, isWildcard: false });
+  }
+  return ranges;
+}
+function isLineSuppressed(ranges, aspectId, line) {
+  return ranges.some((r) => {
+    if (line < r.startLine || line > r.endLine) return false;
+    return r.isWildcard || r.aspectIds.has(aspectId);
+  });
+}
+
+// src/utils/validate-check-module.ts
+function validateCheckModuleExport(mod, opts) {
+  const { codePrefix, runnerLabel } = opts;
+  if (mod.check === void 0) {
+    const defaultExport = mod.default;
+    if (typeof defaultExport === "function" && defaultExport.name === "check") {
+      return {
+        ok: false,
+        code: `${codePrefix}_CHECK_DEFAULT_EXPORT`,
+        message: {
+          what: `check.mjs exports 'check' as default, but a NAMED export is required (${runnerLabel}).`,
+          why: `The runner imports the named export. A default export is invisible to it.`,
+          next: `Change 'export default function check(...)' to 'export function check(...)'.`
+        }
+      };
+    }
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_NOT_EXPORTED`,
+      message: {
+        what: `check.mjs does not export a function named 'check' (${runnerLabel}).`,
+        why: `The runner expects 'export function check(ctx) { ... }'.`,
+        next: `Add a named export 'check' in check.mjs.`
+      }
+    };
+  }
+  if (typeof mod.check !== "function") {
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_NOT_FUNCTION`,
+      message: {
+        what: `'check' is exported but is not a function (got ${typeof mod.check}).`,
+        why: `The runner calls check(ctx).`,
+        next: `Re-export check as a function.`
+      }
+    };
+  }
+  const checkFn = mod.check;
+  if (checkFn.length !== 1) {
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_WRONG_ARITY`,
+      message: {
+        what: `'check' must accept exactly 1 parameter (ctx); declared arity is ${checkFn.length}.`,
+        why: `The runner invokes check(ctx).`,
+        next: `Change the signature to function check(ctx).`
+      }
+    };
+  }
+  return { ok: true };
+}
+
+// src/ast/parse-cache.ts
+function destroyParseCache(cache) {
+  for (const { ast } of cache.values()) {
+    ast.delete();
+  }
+  cache.clear();
+}
+
+// src/structure/hook-loader.ts
+import * as fs4 from "fs";
+import * as path8 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+
+// src/ast/loader-hook.ts
+import { register } from "module";
+import { pathToFileURL } from "url";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { existsSync as existsSync3 } from "fs";
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = path5.dirname(__filename2);
+var registered = false;
+function ensureLoaderRegistered() {
+  if (registered) return;
+  let implPath = path5.resolve(__dirname2, "./loader-hook-impl.js");
+  if (!existsSync3(implPath)) {
+    const pkgRoot = path5.resolve(__dirname2, "../../");
+    implPath = path5.resolve(pkgRoot, "dist/loader-hook-impl.js");
+  }
+  register(pathToFileURL(implPath));
+  registered = true;
+}
+
+// src/structure/allowed-reads.ts
+function collectAllowedReadsForAspect(nodePath, graph) {
+  const allowed = /* @__PURE__ */ new Set();
+  const node = graph.nodes.get(nodePath);
+  if (!node) return allowed;
+  const addMapping = (n) => {
+    const mapping = n.meta.mapping ?? [];
+    for (const raw of mapping) {
+      const p = normalizeMappingPath(raw);
+      if (p) allowed.add(p);
+    }
+  };
+  const childPaths = /* @__PURE__ */ new Set();
+  for (const child of node.children) {
+    for (const raw of child.meta.mapping ?? []) {
+      const p = normalizeMappingPath(raw);
+      if (p) childPaths.add(p);
+    }
+  }
+  for (const raw of node.meta.mapping ?? []) {
+    const p = normalizeMappingPath(raw);
+    if (p && !childPaths.has(p)) allowed.add(p);
+  }
+  for (const rel of node.meta.relations ?? []) {
+    const target = graph.nodes.get(rel.target);
+    if (!target) continue;
+    addMapping(target);
+    const relStack = [...target.children];
+    while (relStack.length > 0) {
+      const n = relStack.pop();
+      addMapping(n);
+      relStack.push(...n.children);
+    }
+  }
+  let cursor = node.parent;
+  while (cursor) {
+    addMapping(cursor);
+    cursor = cursor.parent;
+  }
+  const parentDirs = /* @__PURE__ */ new Set();
+  for (const raw of node.meta.mapping ?? []) {
+    const p = normalizeMappingPath(raw);
+    if (p) {
+      const lastSlash = p.lastIndexOf("/");
+      if (lastSlash > 0) {
+        parentDirs.add(p.substring(0, lastSlash));
+      }
+    }
+  }
+  const siblingCarveOut = /* @__PURE__ */ new Set();
+  for (const cp of childPaths) {
+    const lastSlash = cp.lastIndexOf("/");
+    if (lastSlash > 0) {
+      const cpDir = cp.substring(0, lastSlash);
+      if (parentDirs.has(cpDir)) {
+        siblingCarveOut.add(cp);
+      }
+    }
+  }
+  const stack = [...node.children];
+  while (stack.length > 0) {
+    const n = stack.pop();
+    for (const raw of n.meta.mapping ?? []) {
+      const p = normalizeMappingPath(raw);
+      if (p && !siblingCarveOut.has(p)) allowed.add(p);
+    }
+    stack.push(...n.children);
+  }
+  return allowed;
+}
+
+// src/io/hash.ts
+import { readFile as readFile2, readdir as readdir2, stat } from "fs/promises";
+import path7 from "path";
+import { createHash as createHash2 } from "crypto";
+import { createRequire as createRequire3 } from "module";
+
+// src/io/repo-scanner.ts
+import { readFile, readdir } from "fs/promises";
+import { join as join2, relative as relative2, sep } from "path";
+import { createRequire as createRequire2 } from "module";
+
+// src/utils/debug-log.ts
+import path6 from "path";
+
+// src/io/repo-scanner.ts
+var require2 = createRequire2(import.meta.url);
+var ignoreFactory = require2("ignore");
+
+// src/io/hash.ts
+var require3 = createRequire3(import.meta.url);
+var ignoreFactory2 = require3("ignore");
+var CR = 13;
+var LF = 10;
+function normalizeLineEndings(bytes) {
+  if (!bytes.includes(CR)) return bytes;
+  const out = Buffer.allocUnsafe(bytes.length);
+  let w = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] === CR) {
+      out[w++] = LF;
+      if (bytes[i + 1] === LF) i++;
+    } else {
+      out[w++] = bytes[i];
+    }
+  }
+  return out.subarray(0, w);
+}
+async function loadRootGitignoreStack2(projectRoot) {
+  if (!projectRoot) return [];
+  try {
+    const content = await readFile2(path7.join(projectRoot, ".gitignore"), "utf-8");
+    const matcher = ignoreFactory2();
+    matcher.add(content);
+    return [{ basePath: projectRoot, matcher }];
+  } catch {
+    return [];
+  }
+}
+function isIgnoredByStack2(candidatePath, stack) {
+  for (const { basePath, matcher } of stack) {
+    const relativePath = toPosix(path7.relative(basePath, candidatePath));
+    if (relativePath === "" || relativePath.startsWith("..")) continue;
+    if (matcher.ignores(relativePath) || matcher.ignores(relativePath + "/")) return true;
+  }
+  return false;
+}
+function hashString(content) {
+  return createHash2("sha256").update(content).digest("hex");
+}
+function hashBytes(bytes) {
+  return createHash2("sha256").update(normalizeLineEndings(bytes)).digest("hex");
+}
+async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
+  let stack = options.gitignoreStack ?? [];
+  try {
+    const localContent = await readFile2(path7.join(directoryPath, ".gitignore"), "utf-8");
+    const localMatcher = ignoreFactory2();
+    localMatcher.add(localContent);
+    stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
+  } catch {
+  }
+  const entries = await readdir2(directoryPath, { withFileTypes: true });
+  const dirs = [];
+  const files = [];
+  for (const entry of entries) {
+    const absoluteChildPath = path7.join(directoryPath, entry.name);
+    if (isIgnoredByStack2(absoluteChildPath, stack)) continue;
+    if (entry.isDirectory()) dirs.push(absoluteChildPath);
+    else if (entry.isFile()) files.push(absoluteChildPath);
+  }
+  const [dirResults, fileStats] = await Promise.all([
+    Promise.all(dirs.map((d) => collectDirectoryFilePaths(d, rootDirectoryPath, {
+      projectRoot: options.projectRoot,
+      gitignoreStack: stack
+    }))),
+    Promise.all(files.map(async (f) => {
+      const fileStat = await stat(f);
+      return {
+        relPath: toPosixPath(path7.relative(rootDirectoryPath, f)),
+        absPath: f,
+        mtimeMs: fileStat.mtimeMs
+      };
+    }))
+  ]);
+  const result = [];
+  for (const nested of dirResults) result.push(...nested);
+  result.push(...fileStats);
+  return result;
+}
+async function expandGlobEntry(projectRoot, glob, gitignoreStack) {
+  const segments = glob.split("/");
+  const firstGlobIdx = segments.findIndex((s) => isGlobPattern(s));
+  const baseSegments = firstGlobIdx > 0 ? segments.slice(0, firstGlobIdx) : [];
+  const baseDir = baseSegments.length > 0 ? path7.join(projectRoot, ...baseSegments) : projectRoot;
+  try {
+    const dirEntries = await collectDirectoryFilePaths(baseDir, projectRoot, {
+      projectRoot,
+      gitignoreStack
+    });
+    return dirEntries.filter((entry) => globMatch(entry.relPath, glob)).map((entry) => ({
+      relPath: toPosixPath(entry.relPath),
+      absPath: entry.absPath,
+      mtimeMs: entry.mtimeMs
+    }));
+  } catch {
+    return [];
+  }
+}
+async function expandMappingPaths(projectRoot, mappingPaths) {
+  const gitignoreStack = await loadRootGitignoreStack2(projectRoot);
+  const result = [];
+  for (const mp of mappingPaths) {
+    if (isGlobPattern(mp)) {
+      const entries = await expandGlobEntry(projectRoot, mp, gitignoreStack);
+      for (const entry of entries) result.push(entry.relPath);
+    } else {
+      const absPath = path7.join(projectRoot, mp);
+      try {
+        const st = await stat(absPath);
+        if (st.isDirectory()) {
+          const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
+            projectRoot,
+            gitignoreStack
+          });
+          for (const entry of dirEntries) {
+            result.push(toPosixPath(path7.join(mp, entry.relPath)));
+          }
+        } else {
+          result.push(toPosixPath(mp));
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return result;
+}
+
+// src/utils/binary-extensions.ts
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".gif",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".webp",
+  ".bmp",
+  ".ico",
+  ".svgz",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".zip",
+  ".gz",
+  ".tgz",
+  ".tar",
+  ".bz2",
+  ".7z",
+  ".pdf",
+  ".mp4",
+  ".mov",
+  ".webm",
+  ".mp3",
+  ".wav",
+  ".wasm",
+  ".bin"
+]);
+
+// src/core/pair-hash.ts
+function observationKey(kind, target) {
+  return `${kind}:${target}`;
+}
+var MISSING_OBSERVATION = "missing";
+function hashNodeSetObservation(nodeIds) {
+  const lines = [...nodeIds].sort((a, b) => a < b ? -1 : a > b ? 1 : 0).join("\n");
+  return hashString(lines);
+}
+function hashReadObservation(bytes) {
+  return hashBytes(bytes);
+}
+function hashListObservation(entries) {
+  const lines = [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map((e) => `${e.name}:${e.kind}`).join("\n");
+  return hashString(lines);
+}
+function hashExistsObservation(result) {
+  return hashString(result === false ? "false" : result);
+}
+
+// src/structure/observations.ts
+var ObservationRecorder = class {
+  _entries = /* @__PURE__ */ new Map();
+  // key → hash (first-wins)
+  _tainted = false;
+  /** Record a file-read observation. `bytes` is the raw content read. */
+  recordRead(repoRelPosixPath, bytes) {
+    this._record(observationKey("read", repoRelPosixPath), hashReadObservation(bytes));
+  }
+  /** Record a directory-listing observation. */
+  recordList(repoRelPosixDir, entries) {
+    this._record(observationKey("list", repoRelPosixDir), hashListObservation(entries));
+  }
+  /** Record an existence-probe observation (including negative probes where result === false). */
+  recordExists(repoRelPosixPath, result) {
+    this._record(observationKey("exists", repoRelPosixPath), hashExistsObservation(result));
+  }
+  /** Record a graph-node observation by hashing its yg-node.yaml bytes. */
+  recordGraphNode(nodePath, ygNodeYamlBytes) {
+    this._record(observationKey("graph", nodePath), hashReadObservation(ygNodeYamlBytes));
+  }
+  /**
+   * Record an ABSENT file-read observation: the check attempted a read that threw
+   * (the path passed the allow-check but the file was missing/unreadable at read
+   * time). Folds MISSING_OBSERVATION under the same read:<path> key the verifier
+   * re-observes — so if the check swallowed the throw and treated the file as
+   * absent, a later successful read of that path changes the value ⇒ unverified
+   * (spec §3.1, over-record: a throwing access is still an observation).
+   */
+  recordReadAbsent(repoRelPosixPath) {
+    this._record(observationKey("read", repoRelPosixPath), MISSING_OBSERVATION);
+  }
+  /**
+   * Record an ABSENT directory-listing observation: the check attempted a list
+   * that threw (path allow-checked but the dir was missing/unreadable at list
+   * time). Folds MISSING_OBSERVATION under the list:<path> key — a later
+   * successful listing changes the value ⇒ unverified (spec §3.1, over-record).
+   */
+  recordListAbsent(repoRelPosixDir) {
+    this._record(observationKey("list", repoRelPosixDir), MISSING_OBSERVATION);
+  }
+  /**
+   * Record a NEGATIVE graph-node observation: the check looked up a node that
+   * does not exist. Folds the MISSING_OBSERVATION token so the verifier's
+   * re-observation (which reads that node's yg-node.yaml and also yields
+   * MISSING_OBSERVATION when absent) reproduces it byte-for-byte — and creating
+   * the node later changes the value ⇒ unverified (spec §3.1, over-record).
+   */
+  recordGraphNodeAbsent(nodePath) {
+    this._record(observationKey("graph", nodePath), MISSING_OBSERVATION);
+  }
+  /**
+   * Record a child-set observation for `nodePath`: the SET of node ids returned
+   * by ctx.graph.children(node). Folds membership only — adding/removing a child
+   * invalidates; a content edit to an unchanged child rides its own graph:
+   * observation (spec §3.1).
+   */
+  recordGraphChildren(nodePath, childIds) {
+    this._record(observationKey("graph-children", nodePath), hashNodeSetObservation(childIds));
+  }
+  /**
+   * Record a by-type-set observation for `type`: the SET of node ids returned by
+   * ctx.graph.nodesByType(type). Folds membership only — adding/removing a node
+   * of that type invalidates (spec §3.1).
+   */
+  recordGraphNodesByType(type, nodeIds) {
+    this._record(observationKey("graph-bytype", type), hashNodeSetObservation(nodeIds));
+  }
+  /**
+   * Record a flow-participant-set observation for `flowName`: the SET of declared
+   * participant ids of the flow. Folds the flow's participant list (the flow
+   * DEFINITION's membership) so adding/removing a participant in the flow file
+   * invalidates the verdict, even when every still-present participant node is
+   * unchanged (spec §3.1, flowParticipants minor).
+   */
+  recordFlowParticipants(flowName, participantIds) {
+    this._record(observationKey("graph-flow", flowName), hashNodeSetObservation(participantIds));
+  }
+  /**
+   * Returns a sorted, deduplicated array of [observationKey, observationHash] pairs.
+   * Re-observing the same key with a different hash sets `tainted = true` and keeps
+   * the first hash (first-observation-wins).
+   */
+  snapshot() {
+    const result = [...this._entries.entries()];
+    result.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return result;
+  }
+  /** True if the same path was observed with different content during this run. */
+  get tainted() {
+    return this._tainted;
+  }
+  _record(key, hash) {
+    const existing = this._entries.get(key);
+    if (existing === void 0) {
+      this._entries.set(key, hash);
+    } else if (existing !== hash) {
+      this._tainted = true;
+    }
+  }
+};
+
+// src/structure/hook-loader.ts
+var StructureRunnerError = class extends Error {
+  constructor(code, data) {
+    super(`${code}: ${data.what}
+${data.why}
+${data.next}`);
+    this.code = code;
+    this.messageData = data;
+    this.name = "StructureRunnerError";
+  }
+  code;
+  messageData;
+};
+async function buildOwnFiles(node, projectRoot, touchedFiles) {
+  const childMappingEntries = [];
+  for (const child of node.children) {
+    for (const raw of child.meta.mapping ?? []) {
+      const p = normalizeMappingPath(raw);
+      if (p) childMappingEntries.push(p);
+    }
+  }
+  const rawMapping = (node.meta.mapping ?? []).map(normalizeMappingPath).filter((p) => p !== "");
+  const expanded = await expandMappingPaths(projectRoot, rawMapping);
+  const result = [];
+  for (const p of expanded) {
+    if (childMappingEntries.length > 0 && isPathInMapping(p, childMappingEntries)) continue;
+    if (BINARY_EXTENSIONS.has(path8.extname(p).toLowerCase())) continue;
+    const abs = path8.resolve(projectRoot, p);
+    let bytes;
+    try {
+      bytes = fs4.readFileSync(abs);
+    } catch {
+      continue;
+    }
+    const content = bytes.toString("utf8");
+    result.push({ file: { path: p, content }, bytes });
+    touchedFiles.push(p);
+  }
+  return result;
+}
+function wrapNonSubjectFile(f, repoRelPosixPath, bytes, recorder) {
+  if (bytes === void 0) return f;
+  const { content, ...rest } = f;
+  let recorded = false;
+  const wrapped = { ...rest };
+  Object.defineProperty(wrapped, "content", {
+    enumerable: true,
+    configurable: true,
+    get() {
+      if (!recorded) {
+        recorder.recordRead(repoRelPosixPath, bytes);
+        recorded = true;
+      }
+      return content;
+    }
+  });
+  return wrapped;
+}
+async function enumerateMappedFilesAsync(mappingPaths, projectRoot) {
+  const normalized = mappingPaths.map(normalizeMappingPath).filter((p) => p !== "");
+  return expandMappingPaths(projectRoot, normalized);
+}
+async function loadHookModule(params) {
+  ensureLoaderRegistered();
+  const { aspectDir, projectRoot, filename } = params;
+  const resolveFailedCode = params.resolveFailedCode ?? "STRUCTURE_LOADER_RESOLVE_FAILED";
+  const aspectDirAbs = path8.isAbsolute(aspectDir) ? aspectDir : path8.resolve(projectRoot, aspectDir);
+  const modulePath = path8.join(aspectDirAbs, filename);
+  try {
+    return await import(pathToFileURL2(modulePath).href);
+  } catch (err) {
+    throw new StructureRunnerError(resolveFailedCode, {
+      what: `Failed to load ${filename} at ${modulePath}: ${err.message}`,
+      why: `The runner dynamically imports the aspect's ${filename} before invoking it.`,
+      next: `Ensure ${filename} exists at the aspect directory and has no unresolved imports.`
+    });
+  }
+}
+async function buildUnitCtx(params) {
+  const { aspectId, nodePath, graph, projectRoot, astCache, touchedFiles, subjectScope } = params;
+  const node = graph.nodes.get(nodePath);
+  if (!node) {
+    throw new StructureRunnerError("STRUCTURE_NODE_MISSING", {
+      what: `Node '${nodePath}' not in graph.`,
+      why: `The runner resolves the node by path to load its mapped files and aspects.`,
+      next: `Pass an existing node path, or add the node to the graph.`
+    });
+  }
+  void aspectId;
+  const allowedSet = collectAllowedReadsForAspect(nodePath, graph);
+  const recorder = new ObservationRecorder();
+  const ownFilesRaw = (node.meta.mapping ?? []).map(normalizeMappingPath).filter((p) => p !== "");
+  const ownFilesExpanded = await expandMappingPaths(projectRoot, ownFilesRaw);
+  const subjectFiles = subjectScope !== void 0 ? new Set(subjectScope.map(normalizeMappingPath)) : new Set(ownFilesExpanded);
+  const ctxFs = createCtxFs({ allowedSet, projectRoot, touchedFiles, recorder, subjectFiles });
+  const expandedFilesByNode = /* @__PURE__ */ new Map();
+  for (const id of computeAllowedNodePaths(nodePath, graph)) {
+    const m = graph.nodes.get(id);
+    if (m) expandedFilesByNode.set(id, await enumerateMappedFilesAsync(m.meta.mapping ?? [], projectRoot));
+  }
+  const ctxGraph = createCtxGraph({ currentNodePath: nodePath, graph, projectRoot, touchedFiles, expandedFilesByNode, recorder, subjectFiles });
+  const parsers = createCtxParsers({ allowedSet, projectRoot, touchedFiles, astCache, recorder, subjectFiles });
+  const ownFilesWithBytes = await buildOwnFiles(node, projectRoot, touchedFiles);
+  const ownFiles = ownFilesWithBytes.map((x) => x.file);
+  const bytesByPath = /* @__PURE__ */ new Map();
+  for (const x of ownFilesWithBytes) bytesByPath.set(normalizeMappingPath(x.file.path), x.bytes);
+  await prewarmupAstCache({ astCache, projectRoot, files: ownFiles });
+  const ownFilesEnriched = enrichFilesWithAst(ownFiles, astCache);
+  let nodeFilesEnriched;
+  let ctxFilesEnriched;
+  if (subjectScope !== void 0) {
+    nodeFilesEnriched = recorder !== void 0 ? ownFilesEnriched.map((f) => {
+      const p = normalizeMappingPath(f.path);
+      if (subjectFiles.has(p)) return f;
+      return wrapNonSubjectFile(f, p, bytesByPath.get(p), recorder);
+    }) : ownFilesEnriched;
+    ctxFilesEnriched = ownFilesEnriched.filter((f) => subjectFiles.has(normalizeMappingPath(f.path)));
+  } else {
+    nodeFilesEnriched = ownFilesEnriched;
+    ctxFilesEnriched = ownFilesEnriched;
+  }
+  const ctx = {
+    node: {
+      id: node.path,
+      type: node.meta.type,
+      mapping: node.meta.mapping ?? [],
+      files: nodeFilesEnriched,
+      ports: node.meta.ports ?? {}
+    },
+    files: ctxFilesEnriched,
+    // ctx.subject is the unit's subject file(s): for the deterministic whole-node
+    // case it is the SAME array reference as ctx.files; for a per:file unit it is
+    // exactly the narrowed subject view (also ctx.files here). Identical reference
+    // in both branches keeps the alias contract.
+    subject: ctxFilesEnriched,
+    fs: ctxFs,
+    graph: ctxGraph,
+    parseAst: parsers.parseAst,
+    parseYaml: parsers.parseYaml,
+    parseJson: parsers.parseJson,
+    parseToml: parsers.parseToml
+  };
+  const astInputSet = [...ownFiles];
+  for (const rel of node.meta.relations ?? []) {
+    const target = graph.nodes.get(rel.target);
+    if (!target) continue;
+    for (const p of await enumerateMappedFilesAsync(target.meta.mapping ?? [], projectRoot)) {
+      const abs = path8.resolve(projectRoot, p);
+      try {
+        const content = fs4.readFileSync(abs, "utf8");
+        astInputSet.push({ path: p, content });
+      } catch {
+      }
+    }
+  }
+  await prewarmupAstCache({ astCache, projectRoot, files: astInputSet });
+  return { ctx, recorder, node, subjectFiles, ownFiles, astInputSet };
+}
+
+// src/structure/runner.ts
+var SUPPRESS_MARKER_MALFORMED_CODE = "STRUCTURE_SUPPRESS_MARKER_MALFORMED";
+async function runStructureAspect(params) {
+  const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
+  const ownCache = !params.parseCache;
+  const astCache = params.parseCache ?? /* @__PURE__ */ new Map();
+  const touchedFiles = [];
+  try {
+    let rangesFor2 = function(filePath) {
+      const existing = rangesByFile.get(filePath);
+      if (existing !== void 0) return existing;
+      const cached = astCache.get(filePath);
+      let ranges;
+      try {
+        if (cached) {
+          ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
+        } else {
+          const content = contentByPath.get(filePath);
+          ranges = content !== void 0 ? collectSuppressions(void 0, filePath, content.split("\n").length, content) : null;
+        }
+      } catch (err) {
+        if (err instanceof SuppressMarkerError) {
+          throw new StructureRunnerError(SUPPRESS_MARKER_MALFORMED_CODE, err.messageData);
+        }
+        throw err;
+      }
+      rangesByFile.set(filePath, ranges);
+      return ranges;
+    };
+    var rangesFor = rangesFor2;
+    const mod = await loadHookModule({ aspectDir, projectRoot, filename: "check.mjs" });
+    const exportCheck = validateCheckModuleExport(mod, {
+      codePrefix: "STRUCTURE",
+      runnerLabel: `aspect '${aspectId}'`
+    });
+    if (!exportCheck.ok) {
+      throw new StructureRunnerError(exportCheck.code, exportCheck.message);
+    }
+    const checkFn = mod.check;
+    const { ctx, recorder, ownFiles, astInputSet } = await buildUnitCtx({
+      aspectId,
+      nodePath,
+      graph,
+      projectRoot,
+      astCache,
+      touchedFiles,
+      subjectScope
+    });
+    let raw;
+    try {
+      raw = checkFn(ctx);
+    } catch (err) {
+      if (err instanceof UndeclaredFsReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared path '${err.path}'. Add a relation in yg-node.yaml to the node owning this path.`,
+            kind: "structure-aspect-undeclared-fs-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof UndeclaredGraphReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared graph node '${err.nodePath}'. Add a relation in yg-node.yaml.`,
+            kind: "structure-aspect-undeclared-graph-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof ParseAstNotPrewarmedError) {
+        return {
+          violations: [{
+            message: `Aspect called ctx.parseAst on '${err.filePath}', which was not pre-warmed by the dispatcher. Add a declared relation to the node owning this file, or use ctx.parseYaml/Json/Toml if AST is not required.`,
+            kind: "structure-aspect-parseast-not-prewarmed",
+            file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      throw new StructureRunnerError("STRUCTURE_CHECK_THROWN", {
+        what: `check.mjs threw an exception while running (aspect '${aspectId}').`,
+        why: `${err.message}
+${err.stack ?? ""}`,
+        next: `Fix the bug in check.mjs, then re-run: yg check --approve`
+      });
+    }
+    if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
+      throw new StructureRunnerError("STRUCTURE_CHECK_ASYNC", {
+        what: `check.mjs returned a Promise; only synchronous returns are supported.`,
+        why: `The runner does not await check's return value.`,
+        next: `Refactor check to be synchronous.`
+      });
+    }
+    if (!Array.isArray(raw)) {
+      throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
+        what: `check.mjs returned ${typeof raw}, expected Violation[].`,
+        why: `The runner reports violations from the array returned by check.`,
+        next: `Return [] or Violation[] from check.`
+      });
+    }
+    const contextFiles = new Set(ownFiles.map((f) => f.path));
+    for (const t of touchedFiles) contextFiles.add(t);
+    const violations = [];
+    for (const v of raw) {
+      if (typeof v !== "object" || v === null || typeof v.message !== "string") {
+        throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
+          what: `Violation entry must be an object with a string 'message' field.`,
+          why: `The runner renders each violation from its message and optional file/line.`,
+          next: `Return objects shaped { message: string, file?: string, line?: number } from check.`
+        });
+      }
+      const vv = v;
+      if (typeof vv.file === "string" && !contextFiles.has(normalizeMappingPath(vv.file))) {
+        throw new StructureRunnerError("STRUCTURE_CHECK_FILE_NOT_IN_CONTEXT", {
+          what: `Violation references file '${vv.file}' not in ctx (own mapping or touched via ctx.fs/ctx.graph).`,
+          why: `Author cannot synthesize violations against files they were not given.`,
+          next: `Return only violations for files in ctx, or declare a relation to the node owning '${vv.file}'.`
+        });
+      }
+      violations.push(vv);
+    }
+    const contentByPath = /* @__PURE__ */ new Map();
+    for (const f of [...ownFiles, ...astInputSet]) {
+      contentByPath.set(normalizeMappingPath(f.path), f.content);
+    }
+    const rangesByFile = /* @__PURE__ */ new Map();
+    const visible = violations.filter((v) => {
+      if (typeof v.file !== "string" || typeof v.line !== "number") return true;
+      const ranges = rangesFor2(normalizeMappingPath(v.file));
+      if (!ranges) return true;
+      return !isLineSuppressed(ranges, aspectId, v.line);
+    });
+    return {
+      violations: visible,
+      touchedFiles,
+      succeeded: true,
+      observations: recorder.snapshot(),
+      observationsTainted: recorder.tainted
+    };
+  } finally {
+    if (ownCache) destroyParseCache(astCache);
+  }
+}
+
+// src/structure/det-worker-core.ts
+async function runDetTask(req, graph, projectRoot) {
+  try {
+    const result = await runStructureAspect({
+      aspectDir: req.aspectDir,
+      aspectId: req.aspectId,
+      nodePath: req.nodePath,
+      graph,
+      projectRoot,
+      subjectScope: req.subjectScope
+    });
+    return { id: req.id, ok: true, result };
+  } catch (e) {
+    if (e instanceof StructureRunnerError) {
+      return { id: req.id, ok: false, error: { code: e.code, messageData: e.messageData, message: e.message } };
+    }
+    return { id: req.id, ok: false, error: { message: e instanceof Error ? e.message : String(e) } };
+  }
+}
+
+// src/structure/det-worker.ts
+if (parentPort) {
+  const { graph, projectRoot } = workerData;
+  const port = parentPort;
+  port.on("message", (req) => {
+    void runDetTask(req, graph, projectRoot).then((reply) => {
+      port.postMessage(reply);
+    });
+  });
+}
+//# sourceMappingURL=det-worker.js.map