@hegemonart/get-design-done 1.30.0 → 1.30.6

package/scripts/lib/graph/atomic-write.mjs

@@ -0,0 +1,68 @@
+// scripts/lib/graph/atomic-write.mjs — Plan 30.6-02 Task 1
+//
+// Atomic JSON write seam per D-05: writeFile(tmp) + rename(tmp, target) in
+// the SAME directory (Windows atomicity guarantee — fs.rename is only
+// atomic across same-volume same-device renames). No proper-lockfile.
+// Single-writer assumption for the design pipeline; revisit in Phase 41
+// if multi-writer becomes a real need.
+
+import {
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  mkdirSync,
+  existsSync,
+} from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+
+/**
+ * Atomically write a JSON payload to `target` using the tmp+rename pattern.
+ *
+ * Guarantees:
+ *   - Readers either see the previous file or the new file, never a
+ *     partial write.
+ *   - If rename fails, the tmp file is unlinked (no orphan tmp files).
+ *   - Tmp file lives in the SAME directory as target (Windows-safe).
+ *
+ * @param {string} target  - Absolute or repo-relative path to final file
+ * @param {unknown} payload - JSON-serializable value (stringified pretty 2-space)
+ */
+export function atomicWriteJson(target, payload) {
+  const parent = dirname(target);
+  const base = basename(target);
+  const tmp = join(
+    parent,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+
+  // Defense per D-05: assert tmp is in same dir as target (cross-device
+  // rename is NOT atomic on Windows). Resolve both to normalize forward-
+  // vs back-slash separators on Windows so the comparison is path-shape-
+  // agnostic — string equality on dirname() outputs is fragile when the
+  // caller passes a POSIX-style path on Windows (`/tmp/foo`) and Node
+  // resolves it to a native-style temp dir (`C:\...\Temp\foo`).
+  if (resolve(dirname(tmp)) !== resolve(parent)) {
+    throw new Error(
+      `atomicWriteJson invariant: tmp not in same dir as target (tmp=${tmp}, target=${target})`,
+    );
+  }
+
+  mkdirSync(parent, { recursive: true });
+
+  const body = JSON.stringify(payload, null, 2) + '\n';
+
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, target);
+  } catch (err) {
+    // Clean up orphan tmp file on failure (best-effort).
+    if (existsSync(tmp)) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Swallow cleanup errors — original throw takes precedence.
+      }
+    }
+    throw err;
+  }
+}

package/scripts/lib/graph/build.mjs

@@ -0,0 +1,124 @@
+// scripts/lib/graph/build.mjs — Plan 30.6-02 Task 2
+//
+// buildGraph: read .design/intel/graph.json, transform per RESEARCH.md
+// intel→graph mapping, validate against schema 1.0, atomic-write to
+// .design/graph/graph.json. Deterministic when `now` is passed (test seam).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator, SCHEMA_VERSION } from './schema.mjs';
+import { atomicWriteJson } from './atomic-write.mjs';
+
+const DEFAULT_INTEL = '.design/intel/graph.json';
+const DEFAULT_OUT = '.design/graph/graph.json';
+const DEFAULT_BUILDER_VERSION = '1.30.6';
+const DEFAULT_SOURCE_MARKER = 'gdd-intel-store';
+
+/**
+ * Build .design/graph/graph.json from a .design/intel/graph.json slice.
+ *
+ * @param {object} opts
+ * @param {string} [opts.intelPath]      - default '.design/intel/graph.json'
+ * @param {string} [opts.outPath]        - default '.design/graph/graph.json'
+ * @param {string} [opts.builderVersion] - default '1.30.6'
+ * @param {string} [opts.now]            - ISO timestamp override (deterministic tests)
+ * @returns {{ok: true, nodeCount: number, edgeCount: number, outPath: string}}
+ * @throws on missing intel, parse failure, schema-invalid output
+ */
+export function buildGraph({
+  intelPath = DEFAULT_INTEL,
+  outPath = DEFAULT_OUT,
+  builderVersion = DEFAULT_BUILDER_VERSION,
+  now = undefined,
+} = {}) {
+  if (!existsSync(intelPath)) {
+    const err = new Error(`buildGraph: intel file not found at ${intelPath}`);
+    err.code = 'INTEL_MISSING';
+    throw err;
+  }
+
+  let intel;
+  try {
+    intel = JSON.parse(readFileSync(intelPath, 'utf8'));
+  } catch (e) {
+    const err = new Error(
+      `buildGraph: failed to parse intel JSON at ${intelPath}: ${e.message}`,
+    );
+    err.code = 'INTEL_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+
+  const nodes = (Array.isArray(intel.nodes) ? intel.nodes : []).map(
+    (n) => transformNode(n),
+  );
+  const edges = (Array.isArray(intel.edges) ? intel.edges : []).map(
+    (e) => transformEdge(e),
+  );
+
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    metadata: {
+      generatedAt: now ?? new Date().toISOString(),
+      intelSource: intelPath,
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      builderVersion,
+    },
+    nodes,
+    edges,
+  };
+
+  const validate = compileValidator();
+  if (!validate(payload)) {
+    const err = new Error('buildGraph: payload failed schema validation');
+    err.code = 'SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+
+  atomicWriteJson(outPath, payload);
+  return {
+    ok: true,
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    outPath,
+  };
+}
+
+/**
+ * Intel → graph node transform per RESEARCH.md §Intel → graph transformation.
+ * intel.name → graph.label; any extra fields land in attrs blob.
+ */
+function transformNode(n) {
+  if (!n || typeof n !== 'object') return n;
+  // Pull off named intel fields; spread rest into attrs (lenient passthrough).
+  const { id, type, name, label, attrs, source, ...rest } = n;
+  const out = { id, type };
+  // Honor explicit label first; fall back to intel.name; otherwise omit.
+  const labelOut = label ?? name;
+  if (labelOut !== undefined) out.label = labelOut;
+  // Merge intel-extra fields into attrs (existing attrs win).
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}
+
+/**
+ * Intel → graph edge transform. Edges already use {from,to,kind} verbatim
+ * per D-03.b — pure passthrough plus attrs absorption.
+ */
+function transformEdge(e) {
+  if (!e || typeof e !== 'object') return e;
+  const { from, to, kind, weight, attrs, source, ...rest } = e;
+  const out = { from, to, kind };
+  if (typeof weight === 'number') out.weight = weight;
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}

package/scripts/lib/graph/diff.mjs

@@ -0,0 +1,90 @@
+// scripts/lib/graph/diff.mjs — Plan 30.6-02 Task 2
+//
+// diffGraph: compare two graph.json files, emit {addedNodes, removedNodes,
+// changedNodes, addedEdges, removedEdges}. Node identity = .id; edge
+// identity = `${from}::${to}::${kind}` per upstream-key formula.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { compileValidator } from './schema.mjs';
+
+/**
+ * Diff two graphs by file path.
+ *
+ * @param {object} opts
+ * @param {string} opts.fromPath - baseline graph path
+ * @param {string} opts.toPath   - current graph path
+ * @returns {{addedNodes: any[], removedNodes: any[], changedNodes: Array<{id:string, before:any, after:any}>, addedEdges: any[], removedEdges: any[]}}
+ */
+export function diffGraph({ fromPath, toPath } = {}) {
+  if (!fromPath || !toPath) {
+    const err = new Error('diffGraph: fromPath and toPath are required');
+    err.code = 'DIFF_ARGS_MISSING';
+    throw err;
+  }
+  const from = readAndValidate(fromPath, 'fromPath');
+  const to = readAndValidate(toPath, 'toPath');
+
+  const fromNodeMap = new Map(from.nodes.map((n) => [n.id, n]));
+  const toNodeMap = new Map(to.nodes.map((n) => [n.id, n]));
+
+  const addedNodes = [];
+  const removedNodes = [];
+  const changedNodes = [];
+
+  for (const [id, after] of toNodeMap) {
+    if (!fromNodeMap.has(id)) {
+      addedNodes.push(after);
+    } else {
+      const before = fromNodeMap.get(id);
+      if (!isDeepStrictEqual(before, after)) {
+        changedNodes.push({ id, before, after });
+      }
+    }
+  }
+  for (const [id, before] of fromNodeMap) {
+    if (!toNodeMap.has(id)) removedNodes.push(before);
+  }
+
+  const edgeKey = (e) => `${e.from}::${e.to}::${e.kind}`;
+  const fromEdgeMap = new Map(from.edges.map((e) => [edgeKey(e), e]));
+  const toEdgeMap = new Map(to.edges.map((e) => [edgeKey(e), e]));
+
+  const addedEdges = [];
+  const removedEdges = [];
+  for (const [k, e] of toEdgeMap) if (!fromEdgeMap.has(k)) addedEdges.push(e);
+  for (const [k, e] of fromEdgeMap) if (!toEdgeMap.has(k)) removedEdges.push(e);
+
+  return {
+    addedNodes,
+    removedNodes,
+    changedNodes,
+    addedEdges,
+    removedEdges,
+  };
+}
+
+function readAndValidate(path, label) {
+  if (!existsSync(path)) {
+    const err = new Error(`diffGraph: ${label} not found at ${path}`);
+    err.code = 'DIFF_FILE_MISSING';
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    const err = new Error(`diffGraph: ${label} parse failed: ${e.message}`);
+    err.code = 'DIFF_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+  const validate = compileValidator();
+  if (!validate(parsed)) {
+    const err = new Error(`diffGraph: ${label} failed schema validation`);
+    err.code = 'DIFF_SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+  return parsed;
+}

package/scripts/lib/graph/index.mjs

@@ -0,0 +1,14 @@
+// scripts/lib/graph/index.mjs — Plan 30.6-02 Task 2
+//
+// Barrel re-export for graph subcommand handlers. 30.6-03 layers query,
+// upsertNode, upsertEdge on top of these exports + the schema/atomic-write
+// foundation; 30.6-04 verifies the union decouples from upstream GSD.
+
+export { buildGraph } from './build.mjs';
+export { statusGraph } from './status.mjs';
+export { diffGraph } from './diff.mjs';
+export { compileValidator, SCHEMA_VERSION, SCHEMA } from './schema.mjs';
+export { atomicWriteJson } from './atomic-write.mjs';
+export { queryGraph } from './query.mjs';                  // 30.6-03 Task 1
+export { estimateTokens } from './token-estimate.mjs';     // 30.6-03 Task 1
+export { upsertNode, upsertEdge } from './upsert.mjs';     // 30.6-03 Task 2

package/scripts/lib/graph/query.mjs

@@ -0,0 +1,155 @@
+// scripts/lib/graph/query.mjs — Plan 30.6-03 Task 1
+//
+// queryGraph: read .design/graph/graph.json, tokenize the query, score
+// nodes per D-04.a (+100 exact-id / +50 exact-label / +20 seed / +10
+// token-in-label / +5 token-in-type / +1 token-in-attrs), walk 1-hop
+// outbound edges to attach neighbors, then enforce a token budget
+// (D-04 chars/4 heuristic via token-estimate.mjs) by dropping
+// lowest-scored matches until the payload fits.
+//
+// Deterministic: identical (graph, query, budget) inputs produce
+// byte-identical JSON output. Ties broken by lexicographic id.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator } from './schema.mjs';
+import { estimateTokens } from './token-estimate.mjs';
+
+const DEFAULT_GRAPH = '.design/graph/graph.json';
+const DEFAULT_BUDGET = 8000;
+const DEFAULT_TOP_K = 10;
+
+/**
+ * Query the native graph.
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath] - default '.design/graph/graph.json'
+ * @param {string} opts.query       - search term (lowercased, tokenized)
+ * @param {number} [opts.budget]    - max estimated tokens for return payload
+ * @returns {{query:string, matches:Array<{node:object, score:number, neighbors:object[]}>, truncated:boolean}}
+ * @throws GRAPH_MISSING when graphPath does not exist
+ * @throws GRAPH_PARSE_FAILED when graph JSON cannot be parsed
+ * @throws GRAPH_SCHEMA_INVALID when graph fails schema validation
+ */
+export function queryGraph({
+  graphPath = DEFAULT_GRAPH,
+  query = '',
+  budget = DEFAULT_BUDGET,
+} = {}) {
+  if (!existsSync(graphPath)) {
+    const err = new Error(`queryGraph: graph file not found at ${graphPath}`);
+    err.code = 'GRAPH_MISSING';
+    throw err;
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  } catch (e) {
+    const err = new Error(
+      `queryGraph: failed to parse graph JSON at ${graphPath}: ${e.message}`,
+    );
+    err.code = 'GRAPH_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+
+  const validate = compileValidator();
+  if (!validate(graph)) {
+    const err = new Error('queryGraph: graph failed schema validation');
+    err.code = 'GRAPH_SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+
+  // ── Tokenize ────────────────────────────────────────────────────────
+  const lowerQuery = String(query).toLowerCase().trim();
+  const tokens = lowerQuery
+    .split(/[^a-z0-9:_\-/.]+/)
+    .filter((t) => t.length > 0);
+
+  // ── Empty / no-token query short-circuit ────────────────────────────
+  if (tokens.length === 0) {
+    return { query, matches: [], truncated: false };
+  }
+
+  // ── Score each node ─────────────────────────────────────────────────
+  // Identify seed nodes (label or id contains the full lowercase query) for the
+  // +20 seed bonus before per-token scoring.
+  const seedIds = new Set();
+  for (const n of graph.nodes) {
+    const idLower = String(n.id || '').toLowerCase();
+    const labelLower = String(n.label || '').toLowerCase();
+    if (
+      lowerQuery.length > 0 &&
+      (idLower.includes(lowerQuery) || labelLower.includes(lowerQuery))
+    ) {
+      seedIds.add(n.id);
+    }
+  }
+
+  const scored = graph.nodes
+    .map((node) => ({ node, score: scoreNode(node, tokens, lowerQuery, seedIds) }))
+    .filter((m) => m.score > 0)
+    .sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id));
+
+  // ── Build adjacency for 1-hop outbound walk ─────────────────────────
+  const outbound = new Map();
+  for (const e of graph.edges) {
+    if (!outbound.has(e.from)) outbound.set(e.from, []);
+    outbound.get(e.from).push(e);
+  }
+  const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+
+  // ── Assemble matches with neighbors ─────────────────────────────────
+  const candidates = scored.slice(0, DEFAULT_TOP_K).map(({ node, score }) => {
+    const outs = outbound.get(node.id) || [];
+    const neighbors = outs
+      .map((e) => nodeById.get(e.to))
+      .filter((n) => n !== undefined);
+    return { node, score, neighbors };
+  });
+
+  // ── Budget-truncation loop ──────────────────────────────────────────
+  let payload = { query, matches: candidates.slice(), truncated: false };
+  while (
+    estimateTokens(payload) > budget &&
+    payload.matches.length > 0
+  ) {
+    payload.matches.pop(); // drop lowest-score (sorted desc → tail = lowest)
+  }
+  if (estimateTokens(payload) > budget) {
+    payload = { query, matches: [], truncated: true };
+  } else if (payload.matches.length < candidates.length) {
+    payload.truncated = true;
+  }
+
+  return payload;
+}
+
+/**
+ * Score a node per D-04.a:
+ *   +100 exact-id match (case-insensitive)
+ *   +50  exact-label match
+ *   +20  seed bonus (node contained the full query as substring)
+ *   +10  per token substring-match in label
+ *   +5   per token substring-match in type
+ *   +1   per token substring-match in attrs (JSON-stringified, lowercased)
+ */
+function scoreNode(node, tokens, lowerQuery, seedIds) {
+  let score = 0;
+  const idLower = String(node.id || '').toLowerCase();
+  const labelLower = String(node.label || '').toLowerCase();
+  const typeLower = String(node.type || '').toLowerCase();
+  const attrsLower = JSON.stringify(node.attrs || {}).toLowerCase();
+
+  if (lowerQuery && idLower === lowerQuery) score += 100;
+  if (lowerQuery && labelLower === lowerQuery) score += 50;
+  if (seedIds.has(node.id)) score += 20;
+
+  for (const t of tokens) {
+    if (labelLower.includes(t)) score += 10;
+    if (typeLower.includes(t)) score += 5;
+    if (attrsLower.includes(t)) score += 1;
+  }
+  return score;
+}

package/scripts/lib/graph/schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/graph.schema.json",
+  "title": ".design/graph/graph.json",
+  "description": "Native gdd-graph store. Schema version 1.0 — frozen at Phase 30.6 per D-03.",
+  "type": "object",
+  "required": ["schemaVersion", "metadata", "nodes", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Pinned to 1.0 at ship; future migrations bump explicitly (D-03)."
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["generatedAt", "nodeCount", "edgeCount"],
+      "additionalProperties": true,
+      "properties": {
+        "generatedAt": { "type": "string", "description": "ISO 8601 timestamp" },
+        "intelSource": { "type": "string", "description": "Path to source intel file, e.g. .design/intel/graph.json" },
+        "nodeCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "builderVersion": { "type": "string", "description": "gdd-graph version that wrote this file" }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type"],
+        "additionalProperties": true,
+        "properties": {
+          "id":     { "type": "string", "minLength": 1, "description": "Stable globally-unique node ID" },
+          "type":   { "type": "string", "description": "Node category (component, token, decision, etc.) — lenient enum per D-03" },
+          "label":  { "type": "string", "description": "Human-readable display name" },
+          "attrs":  { "type": "object", "additionalProperties": true, "description": "Free-form node attributes" },
+          "source": {
+            "oneOf": [
+              { "type": "string", "description": "Source file path or origin marker" },
+              { "type": "object", "additionalProperties": true, "description": "Structured source descriptor per D-03.a" }
+            ]
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind"],
+        "additionalProperties": true,
+        "properties": {
+          "from":   { "type": "string", "minLength": 1, "description": "Source node id (matches a nodes[].id)" },
+          "to":     { "type": "string", "minLength": 1, "description": "Target node id" },
+          "kind":   { "type": "string", "description": "Edge type per D-03.b" },
+          "weight": { "type": "number", "description": "Optional edge weight per D-03.c; used by query ranking + budget eviction" },
+          "attrs":  { "type": "object", "additionalProperties": true },
+          "source": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "object", "additionalProperties": true }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/lib/graph/schema.mjs

@@ -0,0 +1,47 @@
+// scripts/lib/graph/schema.mjs — Plan 30.6-02 Task 1
+//
+// Ajv-compiled validator factory for .design/graph/graph.json (schema 1.0,
+// frozen at Phase 30.6 per D-03). Compile-once + memoized so callers can
+// invoke compileValidator() liberally without paying per-call cost.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import Ajv from 'ajv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read schema via fs.readFileSync rather than `import ... with { type:'json' }`
+// to keep this working on Node 22+ without flag tweaks across runtimes.
+const schemaJson = JSON.parse(
+  readFileSync(join(__dirname, 'schema.json'), 'utf8'),
+);
+
+export const SCHEMA_VERSION = '1.0';
+export const SCHEMA = schemaJson;
+
+let _validator = null;
+
+/**
+ * Returns a compiled Ajv validator function for the native graph schema.
+ * Memoized: subsequent calls return the same instance (no recompile).
+ *
+ * Strict mode is disabled so additionalProperties:true on nodes/edges is
+ * honored (forward-compat lenience per 30.6-01 RESEARCH.md).
+ *
+ * @returns {(payload: unknown) => boolean} validator with .errors after a failed call
+ */
+export function compileValidator() {
+  if (_validator) return _validator;
+  // Ajv ESM: the default export is the constructor.
+  const AjvCtor = Ajv.default || Ajv;
+  const ajv = new AjvCtor({ strict: false, allErrors: true });
+  _validator = ajv.compile(schemaJson);
+  return _validator;
+}
+
+// Test-only hook: reset the memo so test runs can verify compile-once semantics
+// without polluting other suites. Not part of the public CLI surface.
+export function _resetValidatorMemoForTests() {
+  _validator = null;
+}

package/scripts/lib/graph/status.mjs

@@ -0,0 +1,88 @@
+// scripts/lib/graph/status.mjs — Plan 30.6-02 Task 2
+//
+// statusGraph: read .design/graph/graph.json, return structured status JSON.
+// Gracefully degrades when graph file is missing — returns
+// {configured:false, exists:false} without throwing (the 6 status callsites
+// probe before issuing other commands).
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { compileValidator } from './schema.mjs';
+
+const DEFAULT_GRAPH = '.design/graph/graph.json';
+const DEFAULT_INTEL = '.design/intel/graph.json';
+
+/**
+ * Report status of the native graph store.
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath] - default '.design/graph/graph.json'
+ * @param {string} [opts.intelPath] - default '.design/intel/graph.json' (used for staleness)
+ * @returns {object} structured status — see RESEARCH.md §Subcommand inventory
+ */
+export function statusGraph({
+  graphPath = DEFAULT_GRAPH,
+  intelPath = DEFAULT_INTEL,
+} = {}) {
+  if (!existsSync(graphPath)) {
+    return { configured: false, exists: false };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(graphPath, 'utf8');
+  } catch (e) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: [{ message: `read failed: ${e.message}` }],
+    };
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(raw);
+  } catch (e) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: [{ message: `parse failed: ${e.message}` }],
+    };
+  }
+
+  const validate = compileValidator();
+  if (!validate(graph)) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: validate.errors,
+    };
+  }
+
+  const lastBuiltAt = graph.metadata?.generatedAt ?? null;
+
+  let stale = false;
+  if (existsSync(intelPath) && lastBuiltAt) {
+    try {
+      const intelMtime = statSync(intelPath).mtimeMs;
+      const builtMs = Date.parse(lastBuiltAt);
+      if (Number.isFinite(builtMs) && intelMtime > builtMs) {
+        stale = true;
+      }
+    } catch {
+      // Stat failed — leave stale=false; not a hard error.
+    }
+  }
+
+  return {
+    configured: true,
+    exists: true,
+    nodeCount: graph.nodes.length,
+    edgeCount: graph.edges.length,
+    schemaVersion: graph.schemaVersion,
+    lastBuiltAt,
+    stale,
+  };
+}

package/scripts/lib/graph/token-estimate.mjs

@@ -0,0 +1,27 @@
+// scripts/lib/graph/token-estimate.mjs — Plan 30.6-03 Task 1
+//
+// Token-budget heuristic per D-04: ceil(JSON.stringify(payload).length / 4).
+// Crude approximation of the Anthropic tokenizer's chars-per-token ratio;
+// overridable via GDD_GRAPH_TOKEN_FACTOR env var for test seams (D-04 +
+// RESEARCH.md §Query algorithm).
+//
+// This module is the single place to swap heuristic for a real tokenizer
+// (tiktoken, anthropic-tokenizer, etc.) if/when we want a more faithful
+// budget calculation. All callers funnel through estimateTokens().
+
+/**
+ * Estimate the token count of a payload.
+ *
+ * @param {unknown} payload - string OR JSON-serializable value
+ * @returns {number} ceiling of chars/divisor; divisor = GDD_GRAPH_TOKEN_FACTOR
+ *                   (when finite, positive number) or 4 (default)
+ */
+export function estimateTokens(payload) {
+  const str = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  // JSON.stringify can return undefined for symbol/function inputs — guard.
+  const safe = typeof str === 'string' ? str : '';
+  const envFactor = Number(process.env.GDD_GRAPH_TOKEN_FACTOR);
+  const divisor =
+    Number.isFinite(envFactor) && envFactor > 0 ? envFactor : 4;
+  return Math.ceil(safe.length / divisor);
+}