@chrisdudek/yg 5.0.0-alpha.4 → 5.0.0-alpha.5

package/dist/structure.d.ts

@@ -207,11 +207,6 @@ interface ArchitectureDef {
 }
 interface QualityConfig {
     max_direct_relations: number;
-    /** Per-node character budget. A node whose mapped source files plus the
-     *  reference files of its effective aspects exceed this total is an
-     *  `oversized-node` error. Default 40000. Binary files do not count; a node
-     *  may opt out via `sizeExempt`. */
-    max_node_chars?: number;
 }
 type RelationType = 'uses' | 'calls' | 'extends' | 'implements' | 'emits' | 'listens';
 /** Port on a target node — consumers must satisfy port's aspects */
@@ -234,13 +229,13 @@ interface LlmConfig {
     consensus: number;
     /** CLI providers: subprocess timeout in ms. Default: 120_000. */
     timeout?: number;
-    /** Optional caps on reference files for aspects resolving to this tier. */
-    references?: {
-        /** Max bytes per single reference file. Default 65536 (64 KiB). */
-        max_bytes_per_file?: number;
-        /** Max sum of reference bytes per aspect. Default 262144 (256 KiB). */
-        max_total_bytes_per_aspect?: number;
-    };
+    /**
+     * Optional per-tier cap on assembled reviewer-prompt length in characters.
+     * Absent = unlimited. This is a GATE checked deterministically before the LLM
+     * call — it never participates in verdict identity or hash computation (excluded
+     * from canonicalTierJson like api_key and timeout).
+     */
+    max_prompt_chars?: number;
 }
 interface NodeMeta {
     name: string;
@@ -255,12 +250,6 @@ interface NodeMeta {
     relations?: Relation[];
     /** Flat list of file/directory paths relative to repo root */
     mapping?: string[];
-    /** Documented opt-out from the per-node character budget (`oversized-node`).
-     *  Use ONLY for nodes mapping an unsplittable generated or binary artifact
-     *  (lockfile, append-only changelog, image). Requires a justification. */
-    sizeExempt?: {
-        reason: string;
-    };
 }
 interface Relation {
     target: string;
@@ -305,6 +294,11 @@ interface AspectReviewerSpec {
 type AspectStatus = 'draft' | 'advisory' | 'enforced';
 /** Propagation modifier on implies edges. */
 type StatusInherit = 'strictest' | 'own-default';
+/** Review scope of an aspect: whole-node or per-file, with an optional file filter. */
+interface ScopeDef {
+    per: 'node' | 'file';
+    files?: FileWhenPredicate;
+}
 interface AspectDef {
     name: string;
     id: string;
@@ -327,6 +321,15 @@ interface AspectDef {
     }>;
     /** Aspect-level default status. Absent → 'enforced'. Attach sites may override per the bump rule: bump up OK, downgrade is a validator error. */
     status?: AspectStatus;
+    /**
+     * Review scope: controls review granularity and the subject-file set.
+     *   per: node (default) — one review over all subject files.
+     *   per: file — one review per subject file.
+     *   files: optional FileWhenPredicate filter; subject set = mapped files ∩ filter.
+     * Absent → undefined (semantically equivalent to { per: 'node' }).
+     * Forbidden on aggregate aspects (no rule source to scope).
+     */
+    scope?: ScopeDef;
 }
 interface FlowDef {
     /** Directory name under flows/, e.g. "checkout-flow" */
@@ -406,11 +409,30 @@ interface RunStructureAspectParams {
     graph: Graph;
     projectRoot: string;
     parseCache?: ParseCache;
+    /**
+     * Subject-scope override for a `per: file` deterministic pair (spec §1, B2
+     * contract #8). When present, it overrides BOTH `ctx.files` (the check sees
+     * only these subject files) AND the observation-EXCLUSION set (a read of any
+     * OTHER node file folds as a recorded `read:` observation, since it is no
+     * longer hashed as a subject input). Repo-relative POSIX paths.
+     *
+     * `ctx.node.files` and the allow-set stay NODE-scoped regardless — the check
+     * may still reach the rest of the node, but those reaches become observations.
+     *
+     * Absent → byte-identical legacy behavior (the whole node mapping is both the
+     * subject set and the exclusion set; `per: node` and `yg aspect-test` paths).
+     */
+    subjectScope?: string[];
 }
 interface RunStructureAspectResult {
     violations: Violation[];
     touchedFiles: string[];
     succeeded?: boolean;
+    /** Sorted [observationKey, observationHash] pairs recorded during this run. */
+    observations: Array<[string, string]>;
+    /** True when the same path was observed with different content during the run
+     *  (file changed mid-run) — a tainted result must never be cached. */
+    observationsTainted: boolean;
 }
 declare class StructureRunnerError extends Error {
     readonly code: string;

package/dist/structure.js

@@ -106,36 +106,64 @@ function resolveAllowedReadPath(raw, allowedSet, projectRoot) {
   return rel;
 }
 function createCtxFs(params) {
-  const { allowedSet, projectRoot, touchedFiles } = 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 = path2.resolve(projectRoot, p);
+      let result;
       try {
         const stat2 = fs.statSync(abs);
-        return stat2.isDirectory() ? "dir" : stat2.isFile() ? "file" : false;
+        result = stat2.isDirectory() ? "dir" : stat2.isFile() ? "file" : false;
       } catch {
-        return false;
+        result = false;
+      }
+      if (recorder && !isSubjectFile(p)) {
+        recorder.recordExists(p, result);
       }
+      return result;
     },
     read(raw) {
       const p = assertAllowed(raw);
       const abs = path2.resolve(projectRoot, p);
-      return fs.readFileSync(abs, "utf8");
+      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 = path2.resolve(projectRoot, p);
-      const entries = fs.readdirSync(abs, { withFileTypes: true });
-      return entries.map((e) => ({
+      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;
     }
   };
 }
@@ -188,11 +216,26 @@ function computeAllowedNodePaths(currentPath, graph) {
   return allowed;
 }
 function createCtxGraph(params) {
-  const { currentNodePath, graph, projectRoot, touchedFiles, expandedFilesByNode } = 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 = path3.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);
@@ -203,13 +246,18 @@ function createCtxGraph(params) {
       try {
         const stat2 = fs2.statSync(abs);
         if (stat2.isFile()) {
-          const content = fs2.readFileSync(abs, "utf8");
+          const bytes = fs2.readFileSync(abs);
+          const content = bytes.toString("utf8");
           files.push({ path: p, content });
           touchedFiles.push(p);
+          if (recorder && !subjectFiles?.has(p)) {
+            recorder.recordRead(p, bytes);
+          }
         }
       } catch {
       }
     }
+    recordGraphNode(m);
     return {
       id: m.path,
       type: m.meta.type,
@@ -222,19 +270,29 @@ function createCtxGraph(params) {
     node(id) {
       assertAllowed(id);
       const m = graph.nodes.get(id);
-      return m ? toPublicNode(m) : void 0;
+      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) out.push(toPublicNode(m));
+        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) {
@@ -242,6 +300,7 @@ function createCtxGraph(params) {
       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);
         }
@@ -251,6 +310,8 @@ function createCtxGraph(params) {
     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) {
@@ -266,6 +327,7 @@ function createCtxGraph(params) {
         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);
@@ -575,7 +637,7 @@ var ParseAstNotPrewarmedError = class extends Error {
   }
 };
 function createCtxParsers(params) {
-  const { allowedSet, projectRoot, touchedFiles, astCache } = params;
+  const { allowedSet, projectRoot, touchedFiles, astCache, recorder, subjectFiles } = params;
   function asFile(input) {
     if (typeof input !== "string") {
       touchedFiles.push(input.path);
@@ -583,8 +645,18 @@ function createCtxParsers(params) {
     }
     const p = resolveAllowedReadPath(input, allowedSet, projectRoot);
     const abs = path5.resolve(projectRoot, p);
-    const content = fs3.readFileSync(abs, "utf8");
+    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 {
@@ -707,7 +779,7 @@ import { createRequire as createRequire3 } from "module";
 
 // src/io/repo-scanner.ts
 import { readFile, readdir } from "fs/promises";
-import { join, relative as relative2, sep } from "path";
+import { join as join2, relative as relative2, sep } from "path";
 import { createRequire as createRequire2 } from "module";
 
 // src/utils/debug-log.ts
@@ -742,7 +814,9 @@ function isIgnoredByStack2(candidatePath, stack) {
 function hashString(content) {
   return createHash("sha256").update(content).digest("hex");
 }
-var EMPTY_IDENTITY = { ownSubset: hashString(""), ports: {}, aspects: {} };
+function hashBytes(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
 async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
   let stack = options.gitignoreStack ?? [];
   try {
@@ -1022,18 +1096,7 @@ function validateCheckModuleExport(mod, opts) {
   return { ok: true };
 }
 
-// src/structure/runner.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";
-  }
-  messageData;
-};
+// src/utils/binary-extensions.ts
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".gif",
   ".png",
@@ -1063,6 +1126,141 @@ var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".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/runner.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";
+  }
+  messageData;
+};
 async function buildOwnFiles(node, projectRoot, touchedFiles) {
   const childMappingEntries = [];
   for (const child of node.children) {
@@ -1078,24 +1276,43 @@ async function buildOwnFiles(node, projectRoot, touchedFiles) {
     if (childMappingEntries.length > 0 && isPathInMapping(p, childMappingEntries)) continue;
     if (BINARY_EXTENSIONS.has(path8.extname(p).toLowerCase())) continue;
     const abs = path8.resolve(projectRoot, p);
-    let content;
+    let bytes;
     try {
-      content = fs4.readFileSync(abs, "utf8");
+      bytes = fs4.readFileSync(abs);
     } catch {
       continue;
     }
-    result.push({ path: p, content });
+    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 runStructureAspect(params) {
   ensureLoaderRegistered();
-  const { aspectDir, aspectId, nodePath, graph, projectRoot } = params;
+  const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
   const astCache = params.parseCache ?? /* @__PURE__ */ new Map();
   const touchedFiles = [];
   const node = graph.nodes.get(nodePath);
@@ -1127,26 +1344,46 @@ async function runStructureAspect(params) {
   }
   const checkFn = mod.check;
   const allowedSet = collectAllowedReadsForAspect(nodePath, graph);
-  const ctxFs = createCtxFs({ allowedSet, projectRoot, touchedFiles });
+  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 });
-  const parsers = createCtxParsers({ allowedSet, projectRoot, touchedFiles, astCache });
-  const ownFiles = await buildOwnFiles(node, projectRoot, touchedFiles);
+  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: ownFilesEnriched,
+      files: nodeFilesEnriched,
       ports: node.meta.ports ?? {}
     },
-    files: ownFilesEnriched,
+    files: ctxFilesEnriched,
     fs: ctxFs,
     graph: ctxGraph,
     parseAst: parsers.parseAst,
@@ -1180,7 +1417,9 @@ async function runStructureAspect(params) {
           file: `.yggdrasil/aspects/${aspectId}/check.mjs`
         }],
         touchedFiles: [],
-        succeeded: false
+        succeeded: false,
+        observations: recorder.snapshot(),
+        observationsTainted: recorder.tainted
       };
     }
     if (err instanceof UndeclaredGraphReadError) {
@@ -1191,7 +1430,9 @@ async function runStructureAspect(params) {
           file: `.yggdrasil/aspects/${aspectId}/check.mjs`
         }],
         touchedFiles: [],
-        succeeded: false
+        succeeded: false,
+        observations: recorder.snapshot(),
+        observationsTainted: recorder.tainted
       };
     }
     if (err instanceof ParseAstNotPrewarmedError) {
@@ -1202,14 +1443,16 @@ async function runStructureAspect(params) {
           file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
         }],
         touchedFiles: [],
-        succeeded: false
+        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 and re-run yg approve.`
+      next: `Fix the bug in check.mjs, then re-run: yg check --approve`
     });
   }
   if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
@@ -1272,7 +1515,13 @@ ${err.stack ?? ""}`,
     if (!ranges) return true;
     return !isLineSuppressed(ranges, aspectId, v.line);
   });
-  return { violations: visible, touchedFiles, succeeded: true };
+  return {
+    violations: visible,
+    touchedFiles,
+    succeeded: true,
+    observations: recorder.snapshot(),
+    observationsTainted: recorder.tainted
+  };
 }
 
 // src/ast/walk.ts

package/graph-schemas/yg-architecture.yaml

@@ -38,9 +38,14 @@ node_types:
                                              # Use only for types where missing the type means missing
                                              # a critical aspect (security, audit, regulatory).
 
-    log_required: <boolean>                  # optional — default true. Set false for infrastructure
-                                             # or utility types where an approval log adds no value
-                                             # (e.g. config, types, constants).
+    log_required: <boolean>                  # optional — default false. Enable (true) on types whose
+                                             # changes carry business intent worth capturing — domain
+                                             # logic, command handlers, persistence adapters. When true,
+                                             # a node of this type demands a fresh log entry before
+                                             # `yg check --approve` whenever its mapped source changed
+                                             # since the node's last positive closure. Leave omitted
+                                             # (false) for types whose changes carry no business decision
+                                             # worth forcing an entry for (e.g. config, types, constants).
 
     aspects:                                 # optional — aspects automatically applied to every
                                              # node of this type (channel 3). Two forms per entry: