feat(admin): the graph read-model, skill enumeration, and record joins (issue #54)

The data layer under the trigger/flow graph. Everything the graph will
draw becomes readable through read-model.mjs, the admin's one I/O
funnel; the view itself is a later slice.

Read-model additions, all never-throw, all degrading per folder to a
discriminated unreachable, all bounded by the frozen literal-pinned
GRAPH_LIMITS: readFolderSkills (object-store enumeration at HEAD via
the worker's own selectEntries/keepOnlyDeclaredSkills over one hardened
ls-tree, one bounded cat-file per top-level SKILL.md, frontmatter
through the gate's own aiTriggerAllows; display-advisory, never a gate
decision), readInjectedSkills (working-tree, advisory, the doctor
precedent), cronRunStats (raw repeat:<id>:<millis> jobId join with the
digits-tail disambiguator), joinRunsToTriggers (persisted triggerIndex
with the OQ-008 range guard: a stale index counts unattributed, never
lands on whatever entry now occupies the row), observedChainEdges
(parentJobId joins folded per flow pair, same-target only per OQ-009,
refusals surfaced), and collectGraphInputs (the one dedupe/caps funnel).

readTriggers display records now carry the RAW triggers-array index,
the identity matched.index counts, so a dropped row leaves a hole
rather than renumbering every attribution below it. resolvePaths
mirrors the chain caps with defaults imported from the worker.

New pure module graph-model.mjs (parseSkillMeta, findSiblingMentions;
purity source-regex-tested). findSiblingMentions boundary-matches
against the skill-name charset itself rather than \b, because \b
calls a hyphen a boundary and fix would fire inside prefix-fix.

Worker enablers: ./materialize exports-map subpath, aiTriggerAllows
exported, CHAIN_DEPTH_MAX_DEFAULT/CHAIN_MAX_PER_JOB_DEFAULT hoisted as
exported consts (loadConfig behaviour unchanged, pinned by test).

Specs: DES-ADMIN-VIA-PI-EXTENSION AMENDED, saying out loud what the
last three dashboard rows certified as unchanged, because this time it
did change: a new read-model surface and new fs/git access. Dashboard
fs ban UNCHANGED, checked. .log placement boundary UNCHANGED, checked.
DES-AI-TRIGGER-FLOW-GATE UNCHANGED, checked (HEAD-at-display-time is
advisory, an unreadable SKILL.md reads as not chainable).

Suite in the CI posture: 2100 pass, 0 skipped; admin bundle builds.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

admin/src/graph-model.mjs

@@ -0,0 +1,78 @@
+/**
+ * The PURE side of the trigger/flow graph (issue #54): text scanners over skill content, and (next
+ * slice) the model assembler every graph consumer renders from. No fs, no child_process, no redis,
+ * no queue, no env -- read-model.mjs supplies bytes and joins, this module supplies meaning. The
+ * purity is enforced by a source-regex test, the render.mjs/panel.mjs/costs.mjs pattern.
+ */
+
+// One frontmatter value line: `key: value`, an optional surrounding double quote, single-line only.
+// The same block-isolation discipline as flow-gate.mjs's aiTriggerAllows, and deliberately NOT a YAML
+// parser for the same recorded reason: two display strings do not justify js-yaml, and a scanner that
+// accepts only what it understands cannot be driven into surprising shapes by hostile frontmatter.
+const FRONTMATTER_BLOCK_RE = /^---\n([\s\S]*?)\n---(?:\n|$)/;
+
+// Display values are CLIPPED, not refused: a viewer degrades. 120 chars covers every honest
+// name/description and bounds what a hostile one can push into a panel row or an HTML tooltip.
+const META_VALUE_MAX_CHARS = 120;
+
+/**
+ * Read a skill's display metadata (`name`, `description`) from its SKILL.md frontmatter.
+ * Total function: any input shape yields `{ name, description }` with nulls, never a throw.
+ */
+export function parseSkillMeta(text) {
+  const empty = { name: null, description: null };
+  if (typeof text !== "string") return empty;
+  const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+  const block = FRONTMATTER_BLOCK_RE.exec(normalized);
+  if (!block) return empty;
+  return {
+    name: frontmatterValue(block[1], "name"),
+    description: frontmatterValue(block[1], "description"),
+  };
+}
+
+function frontmatterValue(block, key) {
+  const m = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(block);
+  if (!m) return null;
+  let value = m[1].trim();
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+  if (value === "") return null;
+  return value.length > META_VALUE_MAX_CHARS ? `${value.slice(0, META_VALUE_MAX_CHARS)}…` : value;
+}
+
+// A mention is "strong" when it sits near chaining vocabulary -- the outbox protocol's own words.
+// Distance, not co-occurrence-anywhere: a README-style skill that lists every sibling once should
+// not promote all of them to likely chain targets.
+const CHAIN_VOCAB_RE = /outbox|request-|"flow"|\bchain\b|follow-up/i;
+const CHAIN_VOCAB_RADIUS = 200;
+
+/**
+ * Find which sibling skill names a skill's text mentions -- the heuristic half of the potential
+ * flow->flow edge (the exact half is the target's own `ai-trigger: allow`). The name space makes
+ * this workable where free-text search would not be: SKILL_NAME_RE names are a closed, enumerable
+ * set the caller supplies, so this scans for a handful of known literals and nothing else.
+ *
+ * Boundary-matched against the SKILL NAME charset itself, not `\b`: a skill name may contain `-`,
+ * and `\b` calls a hyphen a boundary, so `\bfix\b` would fire inside `prefix-fix` -- the lookarounds
+ * refuse any neighbouring name-charset character instead. A name that is also an English word can
+ * still false-positive in prose, which is exactly why these edges render as "potential" and never as
+ * observed. Returns `[{ name, strong }]` in the callers' name order; total function, never throws.
+ */
+export function findSiblingMentions(text, siblingNames) {
+  if (typeof text !== "string" || !Array.isArray(siblingNames)) return [];
+  const mentions = [];
+  for (const name of siblingNames) {
+    if (typeof name !== "string" || name === "") continue;
+    const re = new RegExp(`(?<![a-z0-9_-])${escapeRegExp(name)}(?![a-z0-9_-])`);
+    const at = text.search(re);
+    if (at === -1) continue;
+    const windowStart = Math.max(0, at - CHAIN_VOCAB_RADIUS);
+    const windowEnd = Math.min(text.length, at + name.length + CHAIN_VOCAB_RADIUS);
+    mentions.push({ name, strong: CHAIN_VOCAB_RE.test(text.slice(windowStart, windowEnd)) });
+  }
+  return mentions;
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

admin/src/read-model.mjs

@@ -1,5 +1,15 @@
 // Proves jiti resolves the @edgehero/pi-dispatch workspace symlink and its
 // exports map (the real 3.2 risk), not just bare-relative TypeScript.
 import { settingsFilePath } from "@edgehero/pi-dispatch/runtime-settings";
+// The graph read-model's subpath (issue #54): a missing exports-map entry fails here, in a unit
+// test, rather than at the first /dispatch graph in a bundled install.
+import { selectEntries, keepOnlyDeclaredSkills } from "@edgehero/pi-dispatch/materialize";
+import { aiTriggerAllows } from "@edgehero/pi-dispatch/flow-gate";
+import { CHAIN_DEPTH_MAX_DEFAULT } from "@edgehero/pi-dispatch/config";
 
-export const ok = typeof settingsFilePath === "function";
+export const ok =
+  typeof settingsFilePath === "function" &&
+  typeof selectEntries === "function" &&
+  typeof keepOnlyDeclaredSkills === "function" &&
+  typeof aiTriggerAllows === "function" &&
+  Number.isInteger(CHAIN_DEPTH_MAX_DEFAULT);

admin/test/fixtures/worker-import-probe.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { parseSkillMeta, findSiblingMentions } from "../src/graph-model.mjs";
+
+test("graph-model.mjs is pure: no fs, no child_process, no redis, no queue, no env", () => {
+  // The purity guard comes FIRST (the render.mjs/panel.mjs/costs.mjs pattern): this module receives
+  // bytes and returns meaning, and the day it grows an import is the day the graph stops being
+  // testable offline and the read-model stops being the admin's one I/O funnel.
+  const src = readFileSync(fileURLToPath(new URL("../src/graph-model.mjs", import.meta.url)), "utf8");
+  assert.ok(!/node:fs|node:child_process|ioredis|bullmq|process\.env|readFileSync|execFile/.test(src), "graph-model must stay pure");
+});
+
+// ---- parseSkillMeta ----
+
+test("parseSkillMeta reads name and description from the leading frontmatter", () => {
+  const meta = parseSkillMeta('---\nname: tidy\ndescription: Format and fix lint.\nai-trigger: allow\n---\nBody.\n');
+  assert.deepEqual(meta, { name: "tidy", description: "Format and fix lint." });
+});
+
+test("parseSkillMeta strips a BOM, normalises CRLF, and unwraps double quotes", () => {
+  const meta = parseSkillMeta('\uFEFF---\r\nname: "quoted name"\r\ndescription: d\r\n---\r\n');
+  assert.deepEqual(meta, { name: "quoted name", description: "d" });
+});
+
+test("parseSkillMeta returns nulls for absent frontmatter, absent keys, and non-strings", () => {
+  const empty = { name: null, description: null };
+  assert.deepEqual(parseSkillMeta("no frontmatter here"), empty);
+  assert.deepEqual(parseSkillMeta("---\nother: x\n---\n"), empty);
+  assert.deepEqual(parseSkillMeta(""), empty);
+  assert.deepEqual(parseSkillMeta(null), empty);
+  assert.deepEqual(parseSkillMeta(42), empty);
+});
+
+test("parseSkillMeta clips a hostile oversized value rather than refusing the skill", () => {
+  const meta = parseSkillMeta(`---\nname: ${"x".repeat(500)}\n---\n`);
+  assert.equal(meta.name.length, 121, "120 chars plus the ellipsis");
+  assert.ok(meta.name.endsWith("…"));
+});
+
+test("parseSkillMeta reads only the LEADING block, never a --- fence later in the body", () => {
+  const meta = parseSkillMeta("Body first.\n---\nname: sneaky\n---\n");
+  assert.deepEqual(meta, { name: null, description: null }, "frontmatter is leading-only, like the gate's scanner");
+});
+
+// ---- findSiblingMentions ----
+
+test("findSiblingMentions finds word-boundary sibling names and misses substrings", () => {
+  const text = "After the build finishes, chain the open-pr flow. Nothing here says prefix-fix.";
+  const mentions = findSiblingMentions(text, ["open-pr", "fix", "absent-skill"]);
+  assert.deepEqual(
+    mentions.map((m) => m.name),
+    ["open-pr"],
+    "fix must not fire inside prefix-fix, and absent names must not appear",
+  );
+});
+
+test("findSiblingMentions marks a mention strong only near chaining vocabulary", () => {
+  const strong = findSiblingMentions('Write /outbox/request-1.json with {"flow": "open-pr"}.', ["open-pr"]);
+  assert.deepEqual(strong, [{ name: "open-pr", strong: true }]);
+
+  const weak = findSiblingMentions(`See also the open-pr skill for context.${" filler".repeat(60)} outbox`, ["open-pr"]);
+  assert.deepEqual(weak, [{ name: "open-pr", strong: false }], "vocabulary beyond the radius must not promote the mention");
+});
+
+test("findSiblingMentions is total: bad inputs yield [], and a self-shaped name list is fine", () => {
+  assert.deepEqual(findSiblingMentions(null, ["a"]), []);
+  assert.deepEqual(findSiblingMentions("text", null), []);
+  assert.deepEqual(findSiblingMentions("text", [42, "", null]), []);
+});