@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/frameworks/schema.mjs

@@ -0,0 +1,157 @@
+/**
+ * lib/frameworks/schema.mjs — ADR-0062 persona reasoning framework schema validator.
+ *
+ * A framework is Markdown with YAML frontmatter (same convention as
+ * specialists/prompts/*.md). validateFrameworkFrontmatter() checks the
+ * frontmatter object in isolation (required fields, step shape, unique
+ * `emits` tokens, `cites` enum, known `appliesToRole`) — it never reads
+ * files itself, so it is usable directly against a parsed object in tests.
+ * parseFrameworkFile() does the frontmatter extraction plus validation for
+ * a file on disk, mirroring lib/packs/prompts.mjs's parseFrontmatter shape.
+ *
+ * Invalid frameworks fail closed: every error names the offending field and
+ * (when available) the file path, per ADR-0062 §4 — no silent skip.
+ */
+
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+const CITES_VALUES = new Set(['source', 'prior-step']);
+
+const STEP_REQUIRED_FIELDS = ['id', 'move', 'question', 'emits', 'cites'];
+
+const MIN_STEPS = 3;
+const MAX_STEPS = 6;
+
+export function knownRolesFromSpecialists(specialists) {
+  const roles = new Set();
+  for (const spec of specialists || []) {
+    if (spec && typeof spec.role === 'string' && spec.role) roles.add(spec.role);
+  }
+  return roles;
+}
+
+/**
+ * Validate a parsed frontmatter object against the ADR-0062 schema.
+ *
+ * @param {object} fm               parsed YAML frontmatter
+ * @param {object} opts
+ * @param {string} [opts.filePath]  for error-message prefixing
+ * @param {Set<string>|string[]} [opts.knownRoles]  roles appliesToRole may name; skipped when omitted
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateFrameworkFrontmatter(fm, { filePath, knownRoles } = {}) {
+  const prefix = filePath ? `${filePath}: ` : '';
+  const errors = [];
+
+  if (!fm || typeof fm !== 'object' || Array.isArray(fm)) {
+    return { valid: false, errors: [`${prefix}frontmatter must be a YAML object`] };
+  }
+
+  if (!fm.id || typeof fm.id !== 'string') {
+    errors.push(`${prefix}missing required field: id`);
+  }
+  if (fm.version === undefined || fm.version === null) {
+    errors.push(`${prefix}missing required field: version`);
+  }
+  if (!fm.appliesToRole || typeof fm.appliesToRole !== 'string') {
+    errors.push(`${prefix}missing required field: appliesToRole`);
+  } else if (knownRoles) {
+    const roles = knownRoles instanceof Set ? knownRoles : new Set(knownRoles);
+    if (roles.size > 0 && !roles.has(fm.appliesToRole)) {
+      errors.push(`${prefix}appliesToRole '${fm.appliesToRole}' is not a known role`);
+    }
+  }
+  if (!fm.summary || typeof fm.summary !== 'string') {
+    errors.push(`${prefix}missing required field: summary`);
+  }
+
+  if (!Array.isArray(fm.steps) || fm.steps.length === 0) {
+    errors.push(`${prefix}steps must be a non-empty array`);
+    return { valid: errors.length === 0, errors };
+  }
+
+  if (fm.steps.length < MIN_STEPS || fm.steps.length > MAX_STEPS) {
+    errors.push(`${prefix}steps must contain ${MIN_STEPS}-${MAX_STEPS} entries (got ${fm.steps.length})`);
+  }
+
+  const emitsSeen = new Map();
+  const stepIdsSeen = new Set();
+
+  fm.steps.forEach((step, idx) => {
+    const stepPrefix = `${prefix}steps[${idx}]`;
+
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      errors.push(`${stepPrefix}: must be an object`);
+      return;
+    }
+
+    for (const field of STEP_REQUIRED_FIELDS) {
+      if (!step[field] || typeof step[field] !== 'string') {
+        errors.push(`${stepPrefix}: missing required field: ${field}`);
+      }
+    }
+
+    if (step.id) {
+      if (stepIdsSeen.has(step.id)) {
+        errors.push(`${stepPrefix}: duplicate step id '${step.id}'`);
+      }
+      stepIdsSeen.add(step.id);
+    }
+
+    if (step.emits) {
+      if (emitsSeen.has(step.emits)) {
+        errors.push(
+          `${prefix}emits token '${step.emits}' is not unique within the framework (also used by step '${emitsSeen.get(step.emits)}')`
+        );
+      } else {
+        emitsSeen.set(step.emits, step.id || `steps[${idx}]`);
+      }
+    }
+
+    if (step.cites && !CITES_VALUES.has(step.cites)) {
+      errors.push(`${stepPrefix}: cites must be one of ${[...CITES_VALUES].join(', ')} (got '${step.cites}')`);
+    }
+  });
+
+  return { valid: errors.length === 0, errors };
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and validate a framework file from disk.
+ *
+ * @param {string} filePath
+ * @param {object} opts
+ * @param {Set<string>|string[]} [opts.knownRoles]
+ * @returns {{valid: boolean, errors: string[], frontmatter: object|null, body: string|null}}
+ */
+export function parseFrameworkFile(filePath, { knownRoles } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { valid: false, errors: [`${filePath}: failed to read file (${err.message})`], frontmatter: null, body: null };
+  }
+
+  const fm = parseFrontmatter(raw);
+  if (!fm) {
+    return { valid: false, errors: [`${filePath}: missing or invalid frontmatter`], frontmatter: null, body: null };
+  }
+
+  const result = validateFrameworkFrontmatter(fm, { filePath, knownRoles });
+  const body = raw.replace(FRONTMATTER_RE, '');
+
+  return { valid: result.valid, errors: result.errors, frontmatter: fm, body };
+}

package/lib/graph/build-from-corpus.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/graph/build-from-corpus.mjs — corpus-annotation edges for the dependency graph.
+ *
+ * buildFromRegistry only derives test --validates--> capability edges from
+ * registry/capabilities.json's verification.functional / hostEmulation pointers,
+ * so a capability verified solely by unit/integration tests (e.g. local.model.tier,
+ * which declares an explicit untestableRationale for functional coverage) or a
+ * capability tracked only in tests/capabilities/ledger.json never gets an edge.
+ * Walking @capability annotations across the whole test corpus (via
+ * lib/test-corpus-inventory.mjs) and emitting the same validates edge shape,
+ * sourced 'corpus-annotation', closes that gap and merges with (rather than
+ * replaces) registry-derived edges in the store's dedup-by-key write path.
+ *
+ * A capability id tagged in a test but absent from both registry/capabilities.json
+ * and tests/capabilities/ledger.json is not a fabricated node — the ledger and
+ * registry are the id authorities — so annotation-only ids without a known
+ * capability node are skipped and reported back to the caller as orphaned tags.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { extractCapabilityTestEdges } from '../test-corpus-inventory.mjs';
+import { loadCapabilityRegistry } from '../registry/validate.mjs';
+import { defaultLedgerPath } from '../capability-ledger.mjs';
+import { nodeId } from './store.mjs';
+
+function readJsonSafe(filePath) {
+  try { return JSON.parse(readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir
+ * @returns {{ nodes: object[], edges: object[], orphanedCapabilityIds: string[] }}
+ */
+export function buildFromCorpus({ rootDir }) {
+  const registry = loadCapabilityRegistry({ rootDir });
+  const registryIds = new Set((registry.capabilities ?? []).map((cap) => cap.id).filter(Boolean));
+
+  const ledger = readJsonSafe(defaultLedgerPath(rootDir));
+  const ledgerIds = new Set((ledger?.capabilities ?? []).map((cap) => cap.id).filter(Boolean));
+
+  const nodes = [];
+  const edges = [];
+  const orphaned = new Set();
+  const ledgerNodesEmitted = new Set();
+
+  for (const { testPath, capabilityId } of extractCapabilityTestEdges({ rootDir })) {
+    const known = registryIds.has(capabilityId) || ledgerIds.has(capabilityId);
+    if (!known) { orphaned.add(capabilityId); continue; }
+
+    // Ledger-only capabilities (not in registry/capabilities.json) have no
+    // node anywhere else in the graph, so this is the sole place they're created.
+
+    if (!registryIds.has(capabilityId) && !ledgerNodesEmitted.has(capabilityId)) {
+      ledgerNodesEmitted.add(capabilityId);
+      nodes.push({ id: nodeId('capability', capabilityId), type: 'capability', name: capabilityId, attrs: { source: 'ledger' } });
+    }
+
+    const testId = nodeId('test', testPath);
+    nodes.push({ id: testId, type: 'test', name: testPath, attrs: { path: testPath, exists: true } });
+    edges.push({ from: testId, to: nodeId('capability', capabilityId), rel: 'validates', source: 'corpus-annotation' });
+  }
+
+  return { nodes, edges, orphanedCapabilityIds: [...orphaned].sort() };
+}

package/lib/graph/build-from-embed.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/graph/build-from-embed.mjs — seed the living graph with embed-capability
+ * nodes and edges from loaded embed manifests (LMCP-P6).
+ *
+ * Embedded specialists (ADR-0061) were invisible to the graph: build-from-
+ * registry seeds provider/specialist/contract nodes but knows nothing of the
+ * `type:"embed"` manifests, so C8's drift gate could not protect a preset whose
+ * test was deleted or whose binding target broke. This seeder closes that gap.
+ *
+ * Per embed manifest it emits one `embed:<id>` node plus edges into nodes the
+ * registry seeder already produces, reusing the existing relation vocabulary
+ * rather than inventing one:
+ *   embed --uses-->        provider     (each embed.providerBindings entry)
+ *   embed --owned_by-->    specialist   (embed.specialist — who runs it)
+ *   embed --governed_by--> contract     (embed.outputContract)
+ *   test  --validates-->   embed        (`@embed <id>` acceptance-test tag, C10 format)
+ *
+ * The binding-target nodes are NOT created here — an embed that names a
+ * provider/specialist/contract with no node of its own is drift, and
+ * lib/graph/validate.mjs reports the dangling target as an error (strict) so
+ * the C8 gate fails instead of the graph quietly gaining an orphan endpoint.
+ */
+
+import { nodeId } from './store.mjs';
+import { loadEmbedCapabilities } from '../embed/capability-loader.mjs';
+import { extractEmbedTestEdges } from '../test-corpus-inventory.mjs';
+
+/**
+ * @param {{ rootDir: string }} opts
+ * @returns {{ nodes: object[], edges: object[], errors: string[] }}
+ */
+export function buildFromEmbed({ rootDir }) {
+  const { capabilities, errors } = loadEmbedCapabilities({ rootDir });
+
+  const nodes = [];
+  const edges = [];
+  const embedIds = new Set();
+
+  for (const manifest of capabilities) {
+    const embed = manifest.embed ?? {};
+    const id = manifest.id;
+    if (!id) continue;
+    embedIds.add(id);
+
+    const from = nodeId('embed', id);
+    nodes.push({
+      id: from,
+      type: 'embed',
+      name: id,
+      attrs: {
+        specialist: embed.specialist ?? null,
+        outputContract: embed.outputContract ?? null,
+        providerBindings: embed.providerBindings ?? [],
+        runtime: embed.runtime ?? null,
+        proposalAuthority: embed.proposalAuthority ?? null,
+      },
+    });
+
+    for (const providerId of embed.providerBindings ?? []) {
+      edges.push({ from, to: nodeId('provider', providerId), rel: 'uses', source: 'embed-manifest' });
+    }
+    if (embed.specialist) {
+      edges.push({ from, to: nodeId('specialist', embed.specialist), rel: 'owned_by', source: 'embed-manifest' });
+    }
+    if (embed.outputContract) {
+      edges.push({ from, to: nodeId('contract', embed.outputContract), rel: 'governed_by', source: 'embed-manifest' });
+    }
+  }
+
+  // A `@embed <id>` tag on an id with no loaded manifest is a stale annotation,
+  // not a fabricated node — skip it rather than mint a phantom embed node. The
+  // tagging test may carry no `@capability`, so its node is minted here (the
+  // store dedups by id if build-from-corpus also emitted it).
+  for (const { testPath, embedId } of extractEmbedTestEdges({ rootDir })) {
+    if (!embedIds.has(embedId)) continue;
+    const testId = nodeId('test', testPath);
+    nodes.push({ id: testId, type: 'test', name: testPath, attrs: { path: testPath, exists: true } });
+    edges.push({ from: testId, to: nodeId('embed', embedId), rel: 'validates', source: 'embed-manifest' });
+  }
+
+  return { nodes, edges, errors };
+}

package/lib/graph/build-from-registry.mjs

@@ -3,19 +3,30 @@
  * authoritative declarative catalogs.
  *
  * Ingests registry/capabilities.json, lib/embedded-contract/workflow-defs.mjs,
- * and specialists/org into typed nodes and directed edges:
+ * specialists/org into typed nodes and directed edges:
  *   capability --embeds-->     workflow      (embeddedWorkflow)
  *   test       --validates-->  capability    (verification.functional / hostEmulation / per-surface test)
  *   capability --uses-->       skill | rule  (skill + dependencies.skills/.rules)
  *   capability --governed_by-->contract      (contracts[])
  *   capability --exposes-->    surface       (supported surfaces)
+ *
+ * Extended seeding (LMCP-C1) also produces:
+ *   provider   --owned_by-->   specialist    (manifest owner)
+ *   provider   --requires-->   tool          (manifest capabilities/operations)
+ *   specialist --owned_by-->   specialist    (team membership)
+ *   specialist --uses-->       skill         (specialist skills)
+ *   doc        --documents-->  workflow|provider (heuristic linking)
+ *
+ * Embed binding seeding (LMCP-E4) also produces:
+ *   specialist --reads-->      provider      (pack embedBindings[].providers, read/search grant)
+ *
  * Node existence on disk (tests, skills, rules) is stamped as an attr so the
  * Oracle collector can later distinguish declared-but-missing from realized.
  * Covers the registry half of the hybrid population; the import-graph half
  * (file/module nodes, imports/covers/realizes) lands in build-import-graph.
  */
 
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -23,6 +34,9 @@ import { createHash } from 'node:crypto';
 import { listWorkflowDefs } from '../embedded-contract/workflow-defs.mjs';
 import { loadCapabilityRegistry } from '../registry/validate.mjs';
 import { nodeId } from './store.mjs';
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+import { assembleRegistry } from '../registry/assemble.mjs';
+import { loadAllPacks } from '../packs/loader.mjs';
 
 function readJsonSafe(filePath) {
   try { return JSON.parse(readFileSync(filePath, 'utf8')); } catch { return null; }
@@ -49,6 +63,23 @@ function declarationImplFiles(cap, rootDir) {
   return [...new Set(files.filter((rel) => existsRel(rootDir, rel)))];
 }
 
+const DOC_EXTS = new Set(['.md', '.html', '.json']);
+
+function scanDocFiles(dir, baseDir) {
+  const docs = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      docs.push(...scanDocFiles(full, baseDir));
+    } else if (entry.isFile() && DOC_EXTS.has(path.extname(entry.name).toLowerCase())) {
+      docs.push(path.relative(baseDir, full));
+    }
+  }
+  return docs;
+}
+
 function hashFiles(rootDir, rels) {
   const h = createHash('sha256');
   for (const rel of rels) {
@@ -69,7 +100,7 @@ export function buildFromRegistry({ rootDir }) {
   const nodes = [];
   const edges = [];
   const node = (type, key, name, attrs) => nodes.push({ id: nodeId(type, key), type, name: name ?? key, attrs: attrs || {} });
-  const edge = (from, rel, to) => edges.push({ from, to, rel, source: 'registry' });
+  const edge = (from, rel, to, source) => edges.push({ from, to, rel, source: source || 'registry' });
 
   // Workflow catalog: every embedded workflow type is a node regardless of
   // capability coverage, so reverse queries see uncovered workflows.
@@ -148,10 +179,140 @@ export function buildFromRegistry({ rootDir }) {
     }
   }
 
+  // --- Provider nodes from extension manifests ---
+  // Loads builtin manifests and creates provider, tool, and specialist nodes.
+  const manifestDirs = resolveManifestDirs({ rootDir });
+  const builtinManifests = loadManifestsFromDir(manifestDirs.builtin);
+  const manifests = builtinManifests.manifests || [];
+
+  for (const m of manifests) {
+    const provId = nodeId('provider', m.id);
+    node('provider', m.id, m.id, {
+      kind: m.kind,
+      version: m.version,
+      owner: m.owner || null,
+      capabilities: m.capabilities || [],
+      operations: m.operations || [],
+    });
+
+    if (m.owner) {
+      const specId = nodeId('specialist', m.owner);
+      node('specialist', m.owner, m.owner, { autoCreated: true });
+      edge(provId, 'owned_by', specId, 'manifest-loader');
+    }
+
+    const tokens = new Set([
+      ...(m.capabilities || []),
+      ...(m.operations || []),
+    ]);
+    for (const token of tokens) {
+      node('tool', token, token, {});
+      edge(provId, 'requires', nodeId('tool', token), 'manifest-loader');
+    }
+  }
+
+  // --- Specialist --reads--> provider edges from pack embedBindings ---
+  // Every pack (core + user + project tiers) may declare embedBindings
+  // (LMCP-E4); surfacing the read/search grant here makes it visible in
+  // `construct graph`/`construct matrix` alongside the authority-guard
+  // enforcement in lib/embed/authority-guard.mjs, rather than only living in
+  // pack JSON. Errors loading packs are swallowed — a broken project-tier
+  // pack should not blank out the whole registry-seeded graph.
+  try {
+    const { packs } = loadAllPacks({ rootDir });
+    for (const pack of packs) {
+      for (const [specId, binding] of Object.entries(pack.embedBindings || {})) {
+        const specNodeId = nodeId('specialist', specId);
+        node('specialist', specId, specId, { autoCreated: true });
+        for (const providerBinding of binding.providers || []) {
+          if (!providerBinding?.id) continue;
+          const provNodeId = nodeId('provider', providerBinding.id);
+          node('provider', providerBinding.id, providerBinding.id, {});
+          edge(specNodeId, 'reads', provNodeId, 'pack-embed-binding');
+        }
+      }
+    }
+  } catch (err) {
+    // pack loading failures should not abort registry graph seeding
+  }
+
+  // --- Specialist nodes from role registry ---
+  try {
+    const orgRegistry = assembleRegistry(rootDir);
+    const specialists = orgRegistry.specialists || {};
+    const teams = orgRegistry.teams || {};
+
+    for (const [specId, spec] of Object.entries(specialists)) {
+      node('specialist', specId, spec.name || specId, {
+        role: spec.role || null,
+        modelTier: spec.modelTier || null,
+        team: spec.team || null,
+        teamId: spec.teamId || null,
+        groupId: spec.groupId || null,
+        skills: spec.skills || [],
+      });
+
+      if (spec.teamId && teams[spec.teamId]) {
+        edge(nodeId('specialist', specId), 'owned_by', nodeId('specialist', spec.teamId), 'registry');
+      }
+
+      for (const skillRef of spec.skills || []) {
+        edge(nodeId('specialist', specId), 'uses', nodeId('skill', skillRef), 'registry');
+      }
+    }
+  } catch (err) {
+    // specialists/org may not exist in all contexts; skip gracefully
+  }
+
+  // --- Doc nodes from docs/ directory ---
+  const docsDir = path.join(rootDir, 'docs');
+  const docFiles = scanDocFiles(docsDir, rootDir);
+  for (const docRel of docFiles) {
+    node('doc', docRel, docRel, { path: docRel });
+  }
+
+  // --- Documents edges (heuristic linking) ---
+  const providerNodeIds = new Set(nodes.filter(n => n.type === 'provider').map(n => n.id));
+  const workflowNodeIds = new Set(nodes.filter(n => n.type === 'workflow').map(n => n.id));
+
+  for (const dn of nodes) {
+    if (dn.type !== 'doc') continue;
+    const docPath = dn.attrs?.path || dn.name || '';
+
+    if (docPath.includes('adr/') && docPath.toLowerCase().includes('workflow')) {
+      for (const wfId of workflowNodeIds) {
+        edge(dn.id, 'documents', wfId, 'doc-scan');
+      }
+    }
+
+    if (docPath.includes('adr/') && docPath.toLowerCase().includes('provider')) {
+      for (const provId of providerNodeIds) {
+        edge(dn.id, 'documents', provId, 'doc-scan');
+      }
+    }
+
+    if (docPath.includes('adr/') && docPath.toLowerCase().includes('manifest')) {
+      for (const provId of providerNodeIds) {
+        edge(dn.id, 'documents', provId, 'doc-scan');
+      }
+    }
+  }
+
   const sourceHash = hashFiles(rootDir, [
     'registry/capabilities.json',
     'specialists/org',
     'lib/embedded-contract/workflow-defs.mjs',
+    'lib/embedded-contract/workflows',
+    'lib/extensions/manifest-schema.mjs',
+    'lib/extensions/loader.mjs',
+    'lib/extensions/validate.mjs',
+    'lib/extensions/manifests',
+    'docs',
+    'lib/registry/assemble.mjs',
+    'specialists/org',
+    'lib/packs/manifest-schema.mjs',
+    'lib/packs/loader.mjs',
+    'lib/packs/core-pack.mjs',
   ]);
 
   return { nodes, edges, sourceHash };