@polycode-projects/the-mechanical-code-talker 1.5.5 → 1.8.4

package/src/router/guardrail.mjs

@@ -30,19 +30,40 @@
 import { capabilityByName, preconditionsOf, PRECOND } from "./registry.mjs";
 import { hallucinationsIn } from "./call-validator.mjs";
 
+/** PLAN_BREADTH_FIRST_NLU.md §4 — the same read-only breadth-first enrichment as
+ *  resolver.mjs's `dispatchEachCandidate`: every registered capability is
+ *  `readOnly:true` with an empty delete-list, so dispatching the SAME tool once
+ *  per tied candidate is safe. Returns `[{candidate, result}, ...]`, or
+ *  undefined when there is no dispatcher to run it with. */
+async function dispatchEachCandidate(pool, capName, arg, ctx) {
+  if (!ctx.dispatch) return undefined;
+  const results = [];
+  for (const c of pool) {
+    const res = await ctx.dispatch(capName, { [arg]: c.label });
+    results.push({ candidate: c.label, result: res });
+  }
+  return results;
+}
+
 /** Validate a proposed tool_use. Returns a glass-box verdict:
- *    { ok, tool, denied:[{reason,detail}], steps:[{pred,ok,...}], provenance }
+ *    { ok, tool, denied:[{reason,detail}], steps:[{pred,ok,...}], provenance, candidateResults? }
  *  - ok=false with a `default-deny`/`undeclared`/`unknown-arg`/`missing-arg`
  *    denial is a STRUCTURAL rejection (no graph needed).
  *  - ok=false with an `unresolved` step is a BINDING rejection (a `resolves`
- *    precondition whose term matched no entity, or matched ambiguously).
+ *    precondition whose term matched no entity, or matched ambiguously). An
+ *    ambiguous `resolves` term stays a denial (never a guess at which candidate
+ *    is "the" one) but, when `ctx.dispatch` is wired, ADDITIONALLY carries a
+ *    top-level `candidateResults`: the SAME tool dispatched once per tied
+ *    candidate (PLAN_BREADTH_FIRST_NLU.md §4 — mirrors resolver.mjs's
+ *    resolveOne on the exact same ambiguity shape).
  *  - ok=true means the call is RESOLVABLE + well-formed (NOT proven antecedent-
  *    correct — see the file header).
  *  `declaredNames` may be null to skip the declared-set check (validate against
  *  the registry alone); pass it to also enforce the case/session toolset.
  *  `ctx.resolve(term)` is the resolveObject oracle; omit it to skip binding proof
- *  (structural-only validation). */
-export function guard(toolUse, declaredNames = null, ctx = {}) {
+ *  (structural-only validation). Async only because an ambiguous `resolves` term
+ *  may dispatch each candidate via `ctx.dispatch`. */
+export async function guard(toolUse, declaredNames = null, ctx = {}) {
   const name = toolUse?.name;
   const input = toolUse && typeof toolUse.input === "object" && toolUse.input ? toolUse.input : {};
   const denied = [];
@@ -68,6 +89,7 @@ export function guard(toolUse, declaredNames = null, ctx = {}) {
   }
 
   // 2. PRECONDITION CHECK — the STRIPS safety gate, step by step (the proof).
+  let candidateResults;
   for (const pre of preconditionsOf(name)) {
     if (pre.pred === PRECOND.graphLoaded) {
       // graph presence is the harness's responsibility; if a resolver is wired we
@@ -106,15 +128,23 @@ export function guard(toolUse, declaredNames = null, ctx = {}) {
             ? `${name}.${pre.param}="${term}" is ambiguous (narrow it)`
             : `${name}.${pre.param}="${term}" resolves to no graph entity`,
         });
+        if (r && r.ambiguous) {
+          const pool = [r.match, ...(r.candidates || [])].slice(0, 4);
+          const dispatched = await dispatchEachCandidate(pool, name, pre.param, ctx);
+          if (dispatched) candidateResults = dispatched;
+        }
       }
     }
   }
 
   const ok = denied.length === 0;
-  return { ok, tool: name, denied, steps, provenance: ok ? "resolvable (NOT proven antecedent-correct)" : "denied" };
+  return {
+    ok, tool: name, denied, steps, provenance: ok ? "resolvable (NOT proven antecedent-correct)" : "denied",
+    ...(candidateResults ? { candidateResults } : {}),
+  };
 }
 
 /** Convenience boolean: does a proposed tool_use PASS the guardrail? */
-export function admits(toolUse, declaredNames = null, ctx = {}) {
-  return guard(toolUse, declaredNames, ctx).ok;
+export async function admits(toolUse, declaredNames = null, ctx = {}) {
+  return (await guard(toolUse, declaredNames, ctx)).ok;
 }

package/src/router/resolver.mjs

@@ -41,11 +41,23 @@
 
 import { parseQuery } from "../ask.mjs";
 import { selectTool } from "../server-http.mjs";
+import { SUPERLATIVE_EXTREMES } from "../ask-vocab.mjs";
 import {
   capabilities, capabilityByName, preconditionsOf, effectsOf, PRECOND,
 } from "./registry.mjs";
 import { hallucinationsIn } from "./call-validator.mjs";
 
+// A ranking/superlative cue ("most", "biggest", …) in the request — the SAME
+// declared vocabulary ask.mjs's own superlative grammar reads (SUPERLATIVE_EXTREMES),
+// never a new keyword table. Used below to keep a flat imperative frame (a
+// single unranked capability call) from claiming a request that is actually
+// asking to be RANKED — that's the goal-reasoner's job (src/router/goal-reasoner.mjs's
+// keystone argmax over a declared priorityTopic), not a flat listing's.
+const SUPERLATIVE_RE = new RegExp(
+  `\\b(?:${Object.keys(SUPERLATIVE_EXTREMES).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+")).join("|")})\\b`,
+  "i",
+);
+
 // ---- the ask-kind -> epistemic-topic MAPPING (the Stage-1 core) --------------
 // Keyed `${shape}:${kind}` off parseQuery's simple-clause output. The VALUE is
 // the epistemic TOPIC a capability's add-effect must achieve; backwardChain then
@@ -101,7 +113,13 @@ export const NOT_NL_REACHABLE = Object.freeze({});
 // backward-chained to a capability just like an NL intent, so the frame table
 // adds PHRASINGS, never a new routing path. ----
 export const FRAMES = Object.freeze([
-  { re: /\buntested\b|\bwithout\s+(?:a\s+)?tests?\b|\bhas\s+no\s+tests?\b|\bneeds?\s+(?:a\s+)?tests?\b/i, topic: "untested", noArg: true },
+  // skipIfSuperlative: "untested" is a flat listing (which achieves it says
+  // nothing about RANK). A request carrying a superlative cue ("what MOST
+  // needs a test") is asking to be ranked — that's the goal-reasoner's
+  // keystone-argmax job (declared priorityTopic:"impact"), not this frame's.
+  // Skipping here lets the request fall through to an honest C1 refuse, which
+  // driver-goal.mjs escalates to the C2 meta-loop that already ranks.
+  { re: /\buntested\b|\bwithout\s+(?:a\s+)?tests?\b|\bhas\s+no\s+tests?\b|\bneeds?\s+(?:a\s+)?tests?\b/i, topic: "untested", noArg: true, skipIfSuperlative: true },
   { re: /\bblast\s*radius\b|\bimpacts?\b|\bimpacted\b|what\s+(?:a\s+)?change.*(?:reach|affect|touch)|what\s+(?:depends?\s+on|dependents?)\b/i, topic: "impact", arg: "module" },
   // tmct_calls (Stage 2 — the reachability win): the RAW call-edge dump, a grain
   // the relational "call" verb collides with (which routes callers/callees). This
@@ -203,6 +221,7 @@ export function mapParse(parse) {
 export function mapFrame(request) {
   for (const f of FRAMES) {
     if (!f.re.test(request)) continue;
+    if (f.skipIfSuperlative && SUPERLATIVE_RE.test(request)) continue;
     const cap = backwardChain(f.topic);
     if (!cap) continue;
     if (f.noArg) return { name: cap.name, noArg: true, topic: f.topic, source: "frame", why: [`imperative frame => goal (knows ${f.topic})`, `backward-chain => ${cap.name}`] };
@@ -240,14 +259,37 @@ export function proofFor(name, input) {
   return steps;
 }
 
-const REFUSE = (why) => ({ selected: null, refused: true, reason: why });
+const REFUSE = (why, extra) => ({ selected: null, refused: true, reason: why, ...(extra || {}) });
+
+/** PLAN_BREADTH_FIRST_NLU.md §4 — breadth-first ambiguity, read-only capabilities
+ *  ONLY (every registered capability is `readOnly:true` with an empty delete-list,
+ *  so dispatching the SAME tool once per tied candidate carries no double-write
+ *  risk). Runs the bound call for each candidate in `pool` (capped, matching the
+ *  reason string's own display cap) and returns `[{candidate, result}, ...]`, or
+ *  undefined when there is no dispatcher to run it with (`execute:false` or no
+ *  `ctx.dispatch` — e.g. a structural-only / planning caller). Never throws: a
+ *  per-candidate dispatch failure is just an honest miss for that one candidate. */
+async function dispatchEachCandidate(pool, capName, arg, ctx, execute) {
+  if (!execute || !ctx.dispatch) return undefined;
+  const results = [];
+  for (const c of pool) {
+    const res = await ctx.dispatch(capName, { [arg]: c.label });
+    results.push({ candidate: c.label, result: res });
+  }
+  return results;
+}
 
 /** Select a capability for a request and BIND its arguments — the full resolver.
  *  Order: command register -> NL parse -> imperative frame. On a bound selection
  *  it delegates entity binding to ctx.resolve (resolveObject) and, unless
  *  `execute:false`, grounds it via ctx.dispatch. Returns
  *    { selected:{name,input}, proof, why, resolved, observed? }  — a grounded call
- *    { selected:null, refused:true, reason }                     — an honest refusal
+ *    { selected:null, refused:true, reason, candidateResults? }  — an honest refusal
+ *  An ambiguous-term refusal stays `refused:true` (never a guess at which
+ *  candidate is "the" one) but, when a dispatcher is available, ADDITIONALLY
+ *  carries `candidateResults`: the SAME capability dispatched once per tied
+ *  candidate, so a machine caller gets both the honest "still ambiguous" signal
+ *  and every candidate's real answer (PLAN_BREADTH_FIRST_NLU.md §4).
  *  NEVER emits an ungrounded / ambiguous / undeclared call. */
 export async function resolveOne(request, declaredNames, ctx, { execute = true } = {}) {
   const declared = new Set(declaredNames);
@@ -293,7 +335,11 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
     // DELEGATE binding to resolveObject — the resolves(param,as) precondition.
     const r = ctx.resolve ? ctx.resolve(term) : { match: { label: term }, ambiguous: false };
     if (!r || !r.match) return REFUSE(`"${term}" does not resolve to any graph entity (honest miss)`);
-    if (r.ambiguous) return REFUSE(`"${term}" is ambiguous (${[r.match, ...(r.candidates || [])].slice(0, 4).map((m) => m.label).join(", ")}) — narrow it`);
+    if (r.ambiguous) {
+      const pool = [r.match, ...(r.candidates || [])].slice(0, 4);
+      const candidateResults = await dispatchEachCandidate(pool, pick.name, pick.arg, ctx, execute);
+      return REFUSE(`"${term}" is ambiguous (${pool.map((m) => m.label).join(", ")}) — narrow it`, candidateResults ? { candidateResults } : undefined);
+    }
     resolved = r.match;
     input = { [pick.arg]: r.match.label };
     why = [...why, `resolveObject: "${term}" => ${r.match.label} (${r.match.class || "?"}, tier ${r.tier})`];

package/src/sessions.mjs

@@ -25,7 +25,7 @@
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { appendUtterances, CREATED_AT_PROP } from "./memory/core.mjs";
+import { appendUtterances, CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/core.mjs";
 
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 
@@ -117,6 +117,10 @@ export function upsertSession(entities, record) {
     attributes: [
       // referenced via the imported constant (single-sourced from memory/core.mjs)
       { prop: CREATED_AT_PROP, key: "createdAt", value: priorCreatedAt || started || new Date().toISOString() },
+      // this IS a genuinely-mutated individual (re-written every chat turn, PLAN_VIZ.md §2's
+      // concrete "Session" case) — stamp updatedAt explicitly since the derived "max over edges"
+      // rule can't see an own-attribute rewrite that touches no edge.
+      { prop: UPDATED_AT_PROP, key: "updatedAt", value: new Date().toISOString() },
       { prop: "mgx:sessionStarted", key: "started", value: started },
       { prop: "mgx:sessionEnded", key: "ended", value: ended },
       { prop: "mgx:sessionTurns", key: "turns", value: String(turns.length) },

package/src/source.mjs

@@ -12,12 +12,15 @@
 
 import { readFile } from "node:fs/promises";
 import { ToolError } from "./config.mjs";
+import { mergeEntityPayloads } from "./graph-merge.mjs";
 
 let cache = null; // { file, payload } — one artifact per process; cheap re-reads.
+let mergedCache = null; // { key, payload } — the multi-graph path's own cache (config.graphFiles.length > 1)
 let provider = null; // registered custom loader (config) => entities payload | Promise
 
 export function clearCache() {
   cache = null;
+  mergedCache = null;
 }
 
 /** Register a custom graph provider: an async (or sync) `(config) => payload`
@@ -50,6 +53,46 @@ export function emptyEntities() {
   };
 }
 
+/** Read + parse ONE graph artifact file — the same per-file tolerance the
+ *  single-graph path below has always had: a MISSING file (ENOENT) is not an
+ *  error, it's the bootstrap payload; any other read/parse failure is a clean
+ *  ToolError naming the file. Shared by the single- and multi-graph paths. */
+async function readOneGraphFile(file) {
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (e) {
+    if (e?.code === "ENOENT") return emptyEntities();
+    throw new ToolError(`cannot read graph artifact at ${file} (${e?.code || e?.message || e})`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ToolError(`graph artifact ${file} is not valid JSON`);
+  }
+}
+
+/** The multi-graph path (src/graph-merge.mjs): config.graphFiles names MORE
+ *  THAN ONE graph file. Reads each (same per-file ENOENT→bootstrap tolerance
+ *  as the single-graph path), merges them via mergeEntityPayloads, and caches
+ *  the merge under a composite key (the sorted, joined file list) — so
+ *  fetching the identical set of graphs twice in a row, in any order, is a
+ *  cheap cache hit. `config.graphNames[i]`, when present, names graph i for
+ *  mergeEntityPayloads's collision-prefixing (falls back to the array index). */
+async function fetchMergedEntities(config) {
+  const files = config.graphFiles;
+  const key = [...files].map(String).sort().join("|");
+  if (mergedCache && mergedCache.key === key) return mergedCache.payload;
+  const entries = [];
+  for (let i = 0; i < files.length; i++) {
+    const payload = await readOneGraphFile(files[i]);
+    entries.push({ file: files[i], payload, name: config.graphNames?.[i] });
+  }
+  const merged = mergeEntityPayloads(entries);
+  mergedCache = { key, payload: merged };
+  return merged;
+}
+
 /** Fetch the entities payload through the provider seam. With a registered
  *  provider, its result is returned as-is (uncached — a live provider owns its
  *  own caching/refresh policy); a non-object result is a clean ToolError.
@@ -57,7 +100,14 @@ export function emptyEntities() {
  *  process. A MISSING artifact (ENOENT) is not an error: the chat surface
  *  starts from an empty graph and the first session fold-in creates the file —
  *  so we return the bootstrap payload (uncached, so the freshly written file is
- *  picked up next fetch). Every other failure still throws a clean ToolError. */
+ *  picked up next fetch). Every other failure still throws a clean ToolError.
+ *
+ *  MULTI-GRAPH: when `config.graphFiles` names more than one file, this
+ *  delegates to fetchMergedEntities (src/graph-merge.mjs) instead — a
+ *  SEPARATE code path from the block below. The single-graph case (one
+ *  `config.graphFile`, or a one-element `config.graphFiles`) always falls
+ *  through to the unchanged block below — byte-identical to before multi-graph
+ *  support existed. */
 export async function fetchEntities(config) {
   if (provider) {
     let payload;
@@ -72,6 +122,9 @@ export async function fetchEntities(config) {
     }
     return payload;
   }
+  if (Array.isArray(config.graphFiles) && config.graphFiles.length > 1) {
+    return fetchMergedEntities(config);
+  }
   if (cache && cache.file === config.graphFile) return cache.payload;
   let text;
   try {