futura-scion 0.2.6 → 0.2.7

package/README.md

@@ -592,6 +592,40 @@ with the violation evidence attached — the human chooses refactor, move,
 or amend the declaration, via the same `scion review` loop as every other
 escalation.
 
+#### Hub rules — shape, not just edges (`architecture.hubs`)
+
+Edges police direction; HUBS police concentration, checked against the
+schematic's measured fan-in/fan-out (`scion map` design data — curator
+models derive the same numbers from edges, so no map build is required):
+
+```yaml
+architecture:
+  hubs:
+    max_fan_in: 100        # no file imported by more than N (change magnets)
+    max_fan_out: 20        # no file importing more than N (God modules)
+    max_layer_fan_in: 300  # no layer funneling more inbound edges than N
+    ignore: [vendor, gen]  # path prefixes exempt from hub accounting
+```
+
+Hub violations are analyzer-shaped **warnings** (`arch-hub-fan-in`,
+`arch-hub-fan-out`, `arch-hub-layer-fan-in`) carrying the measured number,
+the declared ceiling, and the file — a design smell escalates to the human
+arch lane, never machine-patched. All thresholds are opt-in (empty = not
+checked); malformed or typo'd keys fail loud. Live on FS's own source at
+diagnostic thresholds: `kernel/trail.js` flagged at 173 inbound edges
+(change magnet), `daemon.js` at 22 imports (God module).
+
+#### Map-first THINK (`schematic.enabled`)
+
+Every ladder decision attaches the schematic digest — layers, entries,
+hubs, exported surface — as context for all downstream rungs (generator
+prompts, analyzer reasoning, research queries). Served from a warm cache
+(`schematic.digest_ttl_ms`, default 30000) so latency-bounded scans are
+never starved: one refresh per TTL window, amortized across every worker
+and daemon scan. `taskId` and `mapContext` are ambient keys — stripped
+before signature hashing, so identical problems replay identically across
+task ids and map refreshes.
+
 ### Command over tools — the research rung (`scion tools`)
 
 FS's rungs answer from what it knows. The RESEARCH rung gives it hands:

package/config/scion.config.yaml

@@ -11,8 +11,12 @@ ladder:
   min_insight_confidence: 0.55  # reasoner rung admission floor
 
 llm:
-  daily_tokens: 0               # 0 = LLM rung off (zero-LLM doctrine)
+  daily_tokens: 500
 
+  apiKey: null
+  model: "qwen2.5-coder:7b"
+  baseUrl: "http://localhost:11434/v1"
+  provider: "ollama"
 bounds:
   max_turns: 25
   timeout_ms: 300000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "The fused scion of cortex-os-agent + persona: one zero-LLM-dependent agent stack — Mind proposes, Muscle executes, Gate disposes.",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -27,7 +27,8 @@ export const DEFAULTS = Object.freeze({
   forge: { min_support: 3, min_precision: 0.7, max_trigger_terms: 3, max_seeds_per_run: 5 },
   queue: { max_attempts: 3 },
   analyzer: { enabled: true },
-  architecture: { rules: [] },     // declared layer/dependency-direction rules (mind/architecture.js)
+  schematic: { enabled: true, digest_ttl_ms: 30000 },   // map-first THINK: inject the codebase digest into every ladder decide (warm-cache TTL)
+  architecture: { rules: [], hubs: { max_fan_in: null, max_fan_out: null, max_layer_fan_in: null, ignore: [] } },     // declared layer rules (mind/architecture.js); hubs thresholds are the schematic's measured shape (null = not checked)
   daemon: { auto_fix: false, max_fixes_per_scan: 10 },
   muscle: { path_deny: [], path_allow: [] },   // empty deny = shipped defaults
   api: { token: null, port: 5107, host: '127.0.0.1' },

package/src/ladder.js

@@ -27,7 +27,12 @@ import * as replay from './mind/replay.js';
 import * as seeds from './mind/seeds.js';
 import * as brainReasoner from './brain/reasoner.js';
 import * as memory from './brain/memory.js';
-import * as trail from './kernel/trail.js';
+
+// The warm map: one digest, refreshed at most once per TTL window (see the
+// MAP-FIRST THINK block in decide()). Module-level so a hot daemon's scans
+// and every worker's THINK share the same amortized cost.
+let warmMap = null;
+const MAP_CONTEXT_TTL_MS = 30_000;import * as trail from './kernel/trail.js';
 import { forge } from './mind/forge.js';
 import { load as loadConfig } from './config.js';
 import { analyzeSource, readTargetSource } from './mind/analyzer-rung.js';
@@ -154,6 +159,44 @@ export async function decide(problem, opts = {}) {
   const memoryScope = opts.memoryScope ?? cfg.memory.scope ?? 'auto';
   const minInsightConfidence = opts.minInsightConfidence ?? cfg.ladder.min_insight_confidence;
 
+  // MAP-FIRST THINK (the schematics contract): every task starts from the
+  // codebase map, not from re-reading source. The digest is the one-screen
+  // briefing — layers, entries, hubs, surface — attached to the input as
+  // `mapContext` for every downstream rung (analyzer reasoning, generator
+  // prompts, research queries).
+  // COST CONTRACT: mapFor() re-parses only changed files, but even its
+  // hash-only pass reads+hashes every file — per-decide that is real money
+  // on large trees and it starves latency-bounded scans. THINK context
+  // tolerates seconds of staleness, so the digest is served from a WARM
+  // cache (default 30s TTL, config schematic.digest_ttl_ms): at most one
+  // refresh per TTL window. Anything that needs fresh truth (the analyzer
+  // rung, the Gate) reads the real source as always — context never
+  // misleads: a map built for a different root, or disabled in config,
+  // is skipped silently.
+  if (cfg.schematic?.enabled !== false && !input.mapContext) {
+    try {
+      const ttl = Number(cfg.schematic?.digest_ttl_ms ?? MAP_CONTEXT_TTL_MS);
+      const stale = !warmMap || warmMap.root !== project || (Date.now() - warmMap.at > ttl);
+      if (stale) {
+        const sch = await import('./mind/schematic.js');
+        const prev = sch.loadModel();
+        const mapRoot = prev?.root ?? project;
+        const { model } = sch.mapFor(mapRoot);
+        warmMap = model && model.totalSymbols > 0
+          ? { root: model.root, at: Date.now(), digest: sch.digest(model) }
+          : null;
+      }
+      if (warmMap?.digest) {
+        input.mapContext = warmMap.digest;
+        trail.journal('ladder.map-context', {
+          root: warmMap.root, cachedMs: Date.now() - warmMap.at,
+        });
+      }
+    } catch (err) {
+      trail.journal('ladder.map-context-skipped', { error: String(err?.message || err).slice(0, 120) });
+    }
+  }
+
   // Rung 1 — replay (TEXT-ONLY problems): the zero-generation fast path.
   // For problems carrying a concrete file the analyzer (below) runs FIRST:
   // a replay verdict for a file task is an OUTCOME RECORD ("this was fixed

package/src/mind/architecture.js

@@ -127,26 +127,183 @@ export function normalizeRules(archCfg) {
   });
 }
 
+/**
+ * Validate the `architecture.hubs` config section — hub-based layer rules
+ * checked against the SCHEMATIC's measured fan-in/fan-out (mind/schematic
+ * design data). Where `rules` police EDGES (who may import whom), hubs
+ * police SHAPE (how concentrated the dependency graph has become):
+ *
+ *   architecture:
+ *     hubs:
+ *       max_fan_in: 60          # no file imported by more than 60 (change magnet)
+ *       max_fan_out: 20         # no file importing more than 20 (God module)
+ *       max_layer_fan_in: 300   # no LAYER gathering more inbound edges than this
+ *       ignore: [vendor]        # path prefixes excluded from hub accounting
+ *
+ * Every threshold is opt-in (absent = not checked); numbers must be > 0.
+ * Fail loud on malformed config — a typo must not silently disable it.
+ * @param {object} archCfg — config.architecture (may be undefined)
+ * @returns {object|null} normalized hubs or null when unconfigured
+ */
+export function normalizeHubs(archCfg) {
+  const hubs = archCfg?.hubs;
+  if (hubs === undefined || hubs === null) return null;
+  if (typeof hubs !== 'object' || Array.isArray(hubs)) {
+    throw new Error('architecture: hubs must be a mapping { max_fan_in?, max_fan_out?, max_layer_fan_in?, ignore? }');
+  }
+  // A typo'd threshold key (max_fan_inn) must not silently disable the
+  // check — unknown keys fail loud, same doctrine as merge()'s allowlist.
+  const KNOWN = new Set(['max_fan_in', 'max_fan_out', 'max_layer_fan_in', 'ignore']);
+  for (const k of Object.keys(hubs)) {
+    if (!KNOWN.has(k)) {
+      throw new Error(`architecture: unknown hubs field "${k}" — allowed: ${[...KNOWN].join(', ')}`);
+    }
+  }
+  const out = {};
+  for (const key of ['max_fan_in', 'max_fan_out', 'max_layer_fan_in']) {
+    if (hubs[key] === undefined || hubs[key] === null) continue; // null default = not checked
+    const n = Number(hubs[key]);
+    if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+      throw new Error(`architecture: hubs.${key} must be a positive integer`);
+    }
+    out[key] = n;
+  }
+  if (hubs.ignore !== undefined && hubs.ignore !== null) {
+    if (!Array.isArray(hubs.ignore) || !hubs.ignore.every(s => typeof s === 'string' && s.trim() !== '')) {
+      throw new Error('architecture: hubs.ignore must be an array of non-empty path prefixes');
+    }
+    out.ignore = hubs.ignore.map(normPrefix);
+  }
+  if (Object.keys(out).length === 0) {
+    return null; // {} (the default) — no hub thresholds declared, nothing to check
+  }
+  return out;
+}
+
+/**
+ * Hub checks: compare the model's MEASURED concentration (schematic design
+ * data) against the DECLARED thresholds. A violation is a design smell,
+ * not a broken edge — severity 'warning' (design decisions escalate to
+ * humans via the arch task lane; the Gate never machine-patches shape).
+ * @param {object} model — schematic model (design.fan_in/fan_out/layers)
+ * @param {object} hubs — normalized hubs config
+ * @returns {{ violations: Array, stats: object }}
+ */
+function checkHubs(model, hubs) {
+  const ignore = hubs.ignore ?? [];
+  const ignored = (rel) => ignore.some(pfx => under(rel, pfx));
+  const violations = [];
+  // Fan counts: prefer the schematic's persisted design data when present,
+  // otherwise derive from the model's edges (curator models carry no design
+  // field — every internal edge increments importer fan-out and imported
+  // fan-in, identical arithmetic to the schematic's own derivation).
+  const deriveFromEdges = () => {
+    const fi = new Map(); const fo = new Map();
+    for (const e of model.edges ?? []) {
+      if (e.external) continue;
+      fo.set(e.from, (fo.get(e.from) ?? 0) + 1);
+      fi.set(e.to, (fi.get(e.to) ?? 0) + 1);
+    }
+    return { fi, fo };
+  };
+  let fi; let fo;
+  if (model.design?.fan_in && model.design?.fan_out) {
+    fi = new Map(Object.entries(model.design.fan_in));
+    fo = new Map(Object.entries(model.design.fan_out));
+  } else {
+    ({ fi, fo } = deriveFromEdges());
+  }
+  const relFan = (m) => Object.fromEntries(
+    [...m.entries()].map(([p, n]) => [relTo(model.root, p), n])
+  );
+  const fanIn = relFan(fi);
+  const fanOut = relFan(fo);
+
+  if (hubs.max_fan_in !== undefined) {
+    for (const [file, n] of Object.entries(fanIn)) {
+      if (ignored(file)) continue;
+      if (n > hubs.max_fan_in) {
+        violations.push(hubFinding(file, 'arch-hub-fan-in',
+          `hub: ${file} is imported by ${n} files (declared max_fan_in ${hubs.max_fan_in}) — a change magnet: every edit risks ${n} consumers`,
+          { fan_in: n, declared_max: hubs.max_fan_in }));
+      }
+    }
+  }
+  if (hubs.max_fan_out !== undefined) {
+    for (const [file, n] of Object.entries(fanOut)) {
+      if (ignored(file)) continue;
+      if (n > hubs.max_fan_out) {
+        violations.push(hubFinding(file, 'arch-hub-fan-out',
+          `hub: ${file} imports ${n} modules (declared max_fan_out ${hubs.max_fan_out}) — a God module: split it along its consumers`,
+          { fan_out: n, declared_max: hubs.max_fan_out }));
+      }
+    }
+  }
+  if (hubs.max_layer_fan_in !== undefined) {
+    // Layer data comes from the schematic; without it, derive per-top-dir
+    // inbound edge counts from the edges (same top-of-path keying).
+    let layers = model.design?.layers;
+    if (!layers) {
+      layers = {};
+      for (const e of model.edges ?? []) {
+        if (e.external) continue;
+        const top = relTo(model.root, e.to).split('/')[0] ?? '.';
+        layers[top] = layers[top] ?? { files: 0, fan_in: 0, fan_out: 0 };
+        layers[top].fan_in += 1;
+      }
+    }
+    for (const [layer, d] of Object.entries(layers)) {
+      if (d.fan_in > hubs.max_layer_fan_in) {
+        violations.push(hubFinding(`${layer}/`, 'arch-hub-layer-fan-in',
+          `hub: layer ${layer} gathers ${d.fan_in} inbound edges across ${d.files} files (declared max_layer_fan_in ${hubs.max_layer_fan_in}) — the architecture is funneling through one layer`,
+          { fan_in: d.fan_in, files: d.files, declared_max: hubs.max_layer_fan_in }));
+      }
+    }
+  }
+  const stats = {
+    max_fan_in_observed: Math.max(0, ...Object.values(fanIn)),
+    max_fan_out_observed: Math.max(0, ...Object.values(fanOut)),
+    layers: Object.keys(model.design?.layers ?? {}).length,
+  };
+  return { violations, stats };
+}
+
+/** Analyzer-shaped hub finding (design smell → warning severity). */
+function hubFinding(file, rule, description, detail) {
+  return {
+    file,
+    line: 1,
+    rule,
+    severity: 'warning',
+    description,
+    text: '',
+    ...detail,
+  };
+}
+
 /**
  * Check the model's internal edges against the declared rules.
  * External (package) imports are out of scope — layers govern YOUR code.
+ * When `architecture.hubs` is configured, the schematic's measured
+ * fan-in/fan-out is additionally checked against the declared thresholds.
  *
- * @param {object} model — buildModel()/loadModel() output (files + edges)
- * @param {object} [opts] — { rules?: normalized rules (defaults from config), now? }
- * @returns {{ rules: number, checked: number, violations: analyzer-shaped findings[] }}
+ * @param {object} model — buildModel()/loadModel() output (files + edges + design)
+ * @param {object} [opts] — { rules?: normalized rules, hubs?: normalized hubs (defaults from config), now? }
+ * @returns {{ rules: number, checked: number, violations: analyzer-shaped findings[], hubs?: { stats } }}
  */
 export function checkArchitecture(model, opts = {}) {
   const rules = opts.rules ?? normalizeRules(load().architecture);
-  if (rules.length === 0) {
+  const hubs = opts.hubs !== undefined ? opts.hubs : normalizeHubs(load().architecture);
+  let checked = 0;
+  const violations = [];
+  if (rules.length === 0 && !hubs) {
     return { rules: 0, checked: model.edges.filter(e => !e.external).length, violations: [] };
   }
   // A line number requires source: look the import up in the fragment.
-  let checked = 0;
-  const violations = [];
   for (const edge of model.edges) {
     if (edge.external) continue;
     checked++;
-    if (!rules.some(r => matchesRule(edge, r, model.root))) continue;
+    if (rules.length === 0 || !rules.some(r => matchesRule(edge, r, model.root))) continue;
     // Locate the exact import line for an analyzer-shaped finding
     // (deterministic first matching import; unreadable source degrades
     // to line 1 — the violation stands regardless).
@@ -175,7 +332,19 @@ export function checkArchitecture(model, opts = {}) {
       import_target: edge.to,
     });
   }
-  return { rules: rules.length, checked, violations };
+  // HUB checks (schematic shape rules) ride along — independent of edges.
+  let hubStats;
+  if (hubs) {
+    const { violations: hubV, stats } = checkHubs(model, hubs);
+    violations.push(...hubV);
+    hubStats = stats;
+  }
+  return {
+    rules: rules.length,
+    checked,
+    violations,
+    ...(hubs ? { hubs: { checked: true, stats: hubStats } } : {}),
+  };
 }
 
 /**

package/src/mind/generator.js

@@ -94,7 +94,14 @@ export async function generateCandidate(problem, opts = {}) {
     const structured = context && typeof context === 'object' && Array.isArray(context.nodes)
       ? buildCallTreeContext(context, problem)
       : null;
-    raw = await generator({ ...problem, ...(context ? { context } : {}), ...(structured ? { prompt: structured } : {}) });
+    // Map-first THINK: the codebase digest rides along (mapContext) — the
+    // generator sees the architecture briefing without anyone re-reading
+    // source to build it.
+    raw = await generator({
+      ...problem,
+      ...(context ? { context } : {}),
+      ...(structured ? { prompt: structured } : {}),
+    });
   } catch (err) {
     trail.journal('generate.error', { error: String(err?.message || err).slice(0, 200) });
     return null;

package/src/mind/replay.js

@@ -21,9 +21,18 @@ import { normalize as nluNormalize } from './nlu.js';
 
 export const MIN_REPLAY_CONFIDENCE = 0.5;
 
+// AMBIENT keys — context attached to a problem by the harness (routing and
+// map-first THINK metadata) that must NEVER enter a signature: identical
+// problems must replay identically regardless of which task id carries them
+// or how fresh the codebase map was when they arrived.
+const AMBIENT_KEYS = new Set(['taskId', 'mapContext']);
+
 /** Deterministic signature for a repeatable input. */
 export function signatureOf(input) {
-  return createHash('sha1').update(JSON.stringify(input)).digest('hex').slice(0, 24);
+  const clean = input && typeof input === 'object' && !Array.isArray(input)
+    ? Object.fromEntries(Object.entries(input).filter(([k]) => !AMBIENT_KEYS.has(k)))
+    : input;
+  return createHash('sha1').update(JSON.stringify(clean)).digest('hex').slice(0, 24);
 }
 
 /**