@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/flows/define.mjs

@@ -0,0 +1,146 @@
+/**
+ * lib/flows/define.mjs — flow definition loader and load-time validator.
+ *
+ * defineFlow() is the single gate a flow definition passes through before the
+ * engine ever sees it: a bad state schema, a dangling step reference, or a
+ * mutating step declaring fanOut all fail here, at load time, rather than as
+ * a runtime convention the engine merely documents. loadFlow() adds a file
+ * source on top: a JS module (.mjs/.js) is dynamically imported and must
+ * export the flow definition, run/router functions included, as its default
+ * export. A JSON file holds only data — no function can live in JSON — so its
+ * steps carry structure (workerBackend, inputs, budget, fanOut, synthesis,
+ * waitFor) and loadFlow's `handlers` option supplies the per-step run/router
+ * functions, merged onto the parsed steps before validation. Both paths
+ * converge on defineFlow(), so there is exactly one place fan-out/join/schema
+ * rules live.
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import fs from 'node:fs';
+
+import { WORKER_BACKENDS, JOIN_MODES, TERMINAL } from './constants.mjs';
+import { FlowDefinitionError } from './errors.mjs';
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateWaitFor(waitFor, stepName, stepNames, errors) {
+  if (waitFor === undefined) return;
+  if (!isPlainObject(waitFor) || !JOIN_MODES.includes(waitFor.mode) || !Array.isArray(waitFor.steps) || waitFor.steps.length === 0) {
+    errors.push(`step "${stepName}": waitFor must be { mode: 'all' | 'any', steps: string[] } with at least one step`);
+    return;
+  }
+  for (const predecessor of waitFor.steps) {
+    if (!stepNames.has(predecessor)) {
+      errors.push(`step "${stepName}": waitFor references unknown step "${predecessor}"`);
+    }
+  }
+}
+
+function validateStep(name, step, stepNames, errors) {
+  if (!isPlainObject(step)) {
+    errors.push(`step "${name}": must be an object`);
+    return;
+  }
+  if (!WORKER_BACKENDS.includes(step.workerBackend)) {
+    errors.push(`step "${name}": workerBackend must be one of ${WORKER_BACKENDS.join(', ')}`);
+  }
+  if (typeof step.run !== 'function') {
+    errors.push(`step "${name}": run must be a function`);
+  }
+  if (step.router !== undefined && typeof step.router !== 'function') {
+    errors.push(`step "${name}": router must be a function when provided`);
+  }
+  if (step.inputs !== undefined && !Array.isArray(step.inputs)) {
+    errors.push(`step "${name}": inputs must be an array of state keys when provided`);
+  }
+  if (step.budget !== undefined && !(typeof step.budget === 'number' && step.budget > 0)) {
+    errors.push(`step "${name}": budget must be a positive number when provided`);
+  }
+  if (step.fanOut) {
+    if (step.readOnly !== true) {
+      errors.push(`step "${name}": fanOut requires readOnly: true (fan-out is restricted to read-only backends)`);
+    }
+    if (typeof step.synthesis !== 'string' || !step.synthesis) {
+      errors.push(`step "${name}": fanOut requires a synthesis step name`);
+    } else if (!stepNames.has(step.synthesis)) {
+      errors.push(`step "${name}": synthesis references unknown step "${step.synthesis}"`);
+    }
+  }
+  validateWaitFor(step.waitFor, name, stepNames, errors);
+}
+
+export function defineFlow(definition) {
+  const errors = [];
+  if (!isPlainObject(definition)) {
+    throw new FlowDefinitionError('flow definition must be an object', ['flow definition must be an object']);
+  }
+
+  const { id = null, stateSchema, startStep, steps } = definition;
+
+  if (!isPlainObject(stateSchema)) errors.push('stateSchema must be an object');
+  if (typeof startStep !== 'string' || !startStep) errors.push('startStep must be a non-empty string');
+  if (!isPlainObject(steps) || Object.keys(steps).length === 0) errors.push('steps must be a non-empty object');
+
+  if (errors.length > 0) {
+    throw new FlowDefinitionError(`flow "${id ?? '(unnamed)'}" is invalid`, errors);
+  }
+
+  const stepNames = new Set(Object.keys(steps));
+  if (!stepNames.has(startStep)) errors.push(`startStep "${startStep}" is not a declared step`);
+
+  for (const [name, step] of Object.entries(steps)) {
+    validateStep(name, step, stepNames, errors);
+  }
+
+  if (errors.length > 0) {
+    throw new FlowDefinitionError(`flow "${id ?? '(unnamed)'}" is invalid`, errors);
+  }
+
+  const normalizedSteps = {};
+  for (const [name, step] of Object.entries(steps)) {
+    normalizedSteps[name] = {
+      workerBackend: step.workerBackend,
+      inputs: step.inputs ? [...step.inputs] : [],
+      run: step.run,
+      router: step.router ?? (() => TERMINAL),
+      budget: step.budget ?? null,
+      readOnly: Boolean(step.readOnly),
+      fanOut: Boolean(step.fanOut),
+      synthesis: step.synthesis ?? null,
+      waitFor: step.waitFor ? { mode: step.waitFor.mode, steps: [...step.waitFor.steps] } : null,
+    };
+  }
+
+  return Object.freeze({
+    id,
+    stateSchema,
+    startStep,
+    steps: Object.freeze(normalizedSteps),
+    stepOrder: Object.freeze(Object.keys(normalizedSteps)),
+  });
+}
+
+export async function loadFlow(source, { handlers = {} } = {}) {
+  const resolved = path.resolve(source);
+  const ext = path.extname(resolved);
+
+  if (ext === '.json') {
+    const raw = fs.readFileSync(resolved, 'utf8');
+    const definition = JSON.parse(raw);
+    const steps = {};
+    for (const [name, step] of Object.entries(definition.steps || {})) {
+      steps[name] = { ...step, ...(handlers[name] || {}) };
+    }
+    return defineFlow({ ...definition, steps });
+  }
+
+  const mod = await import(pathToFileURL(resolved).href);
+  const definition = mod.default ?? mod.flowDefinition;
+  if (!definition) {
+    throw new FlowDefinitionError(`flow module "${source}" has no default export`, [`flow module "${source}" has no default export`]);
+  }
+  return defineFlow(definition);
+}

package/lib/flows/engine.mjs

@@ -0,0 +1,249 @@
+/**
+ * lib/flows/engine.mjs — deterministic step executor and run driver.
+ *
+ * runStep() executes exactly one named step: it enforces the step's effort
+ * budget before calling the step's own logic, merges the returned state delta
+ * back through state.mjs's schema-validated transition, and always returns a
+ * structured StepResult (status/timing/usage/error) — never a bare value and
+ * never a silent truncation on budget exhaustion.
+ *
+ * createRun()/advanceRun() drive a whole flow one ready step at a time. A run
+ * is plain, cloned-not-mutated data (state, frontier, completed set, join
+ * progress, usage, history), inspectable and persistable between ticks —
+ * checkpoint/resume is a later increment, addable on top of that shape
+ * without an engine rewrite.
+ *
+ * Deterministic ordering: when more than one step is ready in the same tick,
+ * the engine always runs the one that appears first in the flow definition's
+ * `steps` object (declaration order), regardless of the order routers added
+ * them to the frontier or which fan-out branch finished first. And-joins
+ * (waitFor: { mode: 'all' }) hold a step out of the frontier until every
+ * listed predecessor has completed and routed into it; the default (or an
+ * explicit `mode: 'any'`) admits a step to the frontier the first time any
+ * predecessor routes into it, which is how branch reconvergence works.
+ */
+
+import { TERMINAL, STEP_STATUS, RUN_STATUS } from './constants.mjs';
+import { transition, createInitialState } from './state.mjs';
+
+function pickInputs(state, keys) {
+  const input = {};
+  for (const key of keys) input[key] = state[key];
+  return input;
+}
+
+export async function runStep(flow, stepName, state, { consumedSoFar = 0 } = {}) {
+  const step = flow.steps[stepName];
+  const startedAt = Date.now();
+  const input = pickInputs(state, step.inputs);
+
+  if (step.budget !== null && consumedSoFar >= step.budget) {
+    const finishedAt = Date.now();
+    return {
+      step: stepName,
+      status: STEP_STATUS.BUDGET_EXHAUSTED,
+      workerBackend: step.workerBackend,
+      input,
+      stateDelta: null,
+      usage: { consumed: 0, total: consumedSoFar, budget: step.budget },
+      startedAt,
+      finishedAt,
+      durationMs: finishedAt - startedAt,
+      error: { code: 'BUDGET_EXHAUSTED', message: `step "${stepName}" exhausted its effort budget (${step.budget})` },
+    };
+  }
+
+  let result;
+  try {
+    result = await step.run(input, { state, stepName, workerBackend: step.workerBackend });
+  } catch (err) {
+    const finishedAt = Date.now();
+    return {
+      step: stepName,
+      status: STEP_STATUS.ERROR,
+      workerBackend: step.workerBackend,
+      input,
+      stateDelta: null,
+      usage: null,
+      startedAt,
+      finishedAt,
+      durationMs: finishedAt - startedAt,
+      error: { code: 'STEP_THREW', message: err.message },
+    };
+  }
+
+  const delta = result?.state ?? {};
+  const consumed = result?.usage?.consumed ?? 0;
+  const total = consumedSoFar + consumed;
+  const usage = step.budget !== null || consumed > 0 ? { consumed, total, budget: step.budget } : null;
+
+  const transitioned = transition(flow.stateSchema, state, delta);
+  const finishedAt = Date.now();
+  const durationMs = finishedAt - startedAt;
+
+  if (!transitioned.ok) {
+    return {
+      step: stepName,
+      status: STEP_STATUS.INVALID_STATE,
+      workerBackend: step.workerBackend,
+      input,
+      stateDelta: delta,
+      usage,
+      startedAt,
+      finishedAt,
+      durationMs,
+      error: transitioned.error,
+    };
+  }
+
+  return {
+    step: stepName,
+    status: STEP_STATUS.DONE,
+    workerBackend: step.workerBackend,
+    input,
+    stateDelta: delta,
+    usage,
+    startedAt,
+    finishedAt,
+    durationMs,
+    error: null,
+    state: transitioned.state,
+  };
+}
+
+export function createRun(flow, initialState = {}) {
+  const seeded = createInitialState(flow.stateSchema, initialState);
+  if (!seeded.ok) {
+    return {
+      flow,
+      state: initialState,
+      frontier: [],
+      completed: new Set(),
+      joinProgress: new Map(),
+      usage: new Map(),
+      history: [],
+      status: RUN_STATUS.ERROR,
+      error: seeded.error,
+    };
+  }
+  return {
+    flow,
+    state: seeded.state,
+    frontier: [flow.startStep],
+    completed: new Set(),
+    joinProgress: new Map(),
+    usage: new Map(),
+    history: [],
+    status: RUN_STATUS.RUNNING,
+    error: null,
+  };
+}
+
+function pickReadyStep(run) {
+  const order = run.flow.stepOrder;
+  let best = null;
+  for (const stepName of run.frontier) {
+    if (best === null || order.indexOf(stepName) < order.indexOf(best)) best = stepName;
+  }
+  return best;
+}
+
+function normalizeRouterResult(nextTargets) {
+  if (nextTargets === TERMINAL) return { targets: [], invalid: false };
+  if (typeof nextTargets === 'string') return { targets: [nextTargets], invalid: false };
+  if (Array.isArray(nextTargets)) return { targets: nextTargets.filter((t) => t !== TERMINAL), invalid: false };
+  return { targets: [], invalid: true };
+}
+
+export async function advanceRun(run) {
+  if (run.status !== RUN_STATUS.RUNNING) return run;
+  if (run.frontier.length === 0) return { ...run, status: RUN_STATUS.COMPLETED };
+
+  const stepName = pickReadyStep(run);
+  const frontier = run.frontier.filter((s) => s !== stepName);
+  const consumedSoFar = run.usage.get(stepName) || 0;
+
+  const result = await runStep(run.flow, stepName, run.state, { consumedSoFar });
+  const usage = new Map(run.usage);
+  if (result.usage) usage.set(stepName, result.usage.total);
+  const history = [...run.history, result];
+
+  if (result.status !== STEP_STATUS.DONE) {
+    const status = result.status === STEP_STATUS.BUDGET_EXHAUSTED ? RUN_STATUS.BUDGET_EXHAUSTED : RUN_STATUS.ERROR;
+    return { ...run, usage, history, frontier: [], status, error: result.error };
+  }
+
+  const completed = new Set(run.completed);
+  completed.add(stepName);
+
+  const step = run.flow.steps[stepName];
+  const routerResult = step.router(result.state);
+  const { targets, invalid } = normalizeRouterResult(routerResult);
+
+  if (invalid) {
+    return {
+      ...run,
+      state: result.state,
+      usage,
+      history,
+      completed,
+      frontier: [],
+      status: RUN_STATUS.ERROR,
+      error: { code: 'ROUTER_INVALID_RESULT', message: `step "${stepName}" router returned an unsupported value` },
+    };
+  }
+
+  const joinProgress = new Map(run.joinProgress);
+  const nextFrontier = [...frontier];
+
+  for (const target of targets) {
+    const targetStep = run.flow.steps[target];
+    if (!targetStep) {
+      return {
+        ...run,
+        state: result.state,
+        usage,
+        history,
+        completed,
+        frontier: [],
+        status: RUN_STATUS.ERROR,
+        error: { code: 'ROUTER_UNKNOWN_STEP', message: `step "${stepName}" router named unknown step "${target}"` },
+      };
+    }
+
+    if (targetStep.waitFor && targetStep.waitFor.mode === 'all') {
+      const satisfied = new Set(joinProgress.get(target) || []);
+      satisfied.add(stepName);
+      joinProgress.set(target, satisfied);
+      const ready = targetStep.waitFor.steps.every((predecessor) => satisfied.has(predecessor));
+      if (ready && !nextFrontier.includes(target)) nextFrontier.push(target);
+    } else if (!nextFrontier.includes(target)) {
+      nextFrontier.push(target);
+    }
+  }
+
+  return {
+    ...run,
+    state: result.state,
+    usage,
+    history,
+    completed,
+    joinProgress,
+    frontier: nextFrontier,
+    status: nextFrontier.length === 0 ? RUN_STATUS.COMPLETED : RUN_STATUS.RUNNING,
+    error: null,
+  };
+}
+
+export async function runFlow(flow, initialState = {}, { maxSteps = 10000 } = {}) {
+  let run = createRun(flow, initialState);
+  let steps = 0;
+  while (run.status === RUN_STATUS.RUNNING && steps < maxSteps) {
+    run = await advanceRun(run);
+    steps += 1;
+  }
+  if (run.status === RUN_STATUS.RUNNING && steps >= maxSteps) {
+    return { ...run, status: RUN_STATUS.ERROR, error: { code: 'MAX_STEPS_EXCEEDED', message: `flow exceeded ${maxSteps} steps without reaching a terminal state` } };
+  }
+  return run;
+}

package/lib/flows/errors.mjs

@@ -0,0 +1,19 @@
+/**
+ * lib/flows/errors.mjs — typed errors for the flow engine.
+ *
+ * FlowDefinitionError is thrown at flow-load time (defineFlow/loadFlow) so an
+ * invalid flow (bad schema, dangling step reference, a mutating fan-out step)
+ * never reaches the execution engine. State-transition and step-execution
+ * failures are NOT thrown — they are returned as structured results (see
+ * state.mjs and engine.mjs) so a caller driving a long-running flow never has
+ * to wrap every step in try/catch to keep going.
+ */
+
+export class FlowDefinitionError extends Error {
+  constructor(message, errors = []) {
+    super(message);
+    this.name = 'FlowDefinitionError';
+    this.code = 'FLOW_DEFINITION_INVALID';
+    this.errors = errors;
+  }
+}

package/lib/flows/index.mjs

@@ -0,0 +1,27 @@
+/**
+ * lib/flows/index.mjs — public entry point for the deterministic flow engine.
+ *
+ * Re-exports the flow-definition loader, the schema-validated state
+ * transition, the and/or join combinators, the step/run execution surface,
+ * and the checkpoint/resume layer as one module so a caller needs a single
+ * import path (`lib/flows/index.mjs`) instead of reaching into individual
+ * files.
+ */
+
+export { defineFlow, loadFlow } from './define.mjs';
+export { validateSchema } from './schema.mjs';
+export { createInitialState, transition } from './state.mjs';
+export { andJoin, anyJoin } from './joins.mjs';
+export { runStep, createRun, advanceRun, runFlow } from './engine.mjs';
+export { TERMINAL, WORKER_BACKENDS, STEP_STATUS, RUN_STATUS, JOIN_MODES } from './constants.mjs';
+export { FlowDefinitionError } from './errors.mjs';
+export {
+  FlowCheckpointError,
+  runsDir,
+  checkpointRun,
+  loadCheckpoint,
+  resumeRun,
+  startRun,
+  tickCheckpointed,
+  runCheckpointed,
+} from './checkpoint.mjs';

package/lib/flows/joins.mjs

@@ -0,0 +1,18 @@
+/**
+ * lib/flows/joins.mjs — and/or join combinators for step declarations.
+ *
+ * andJoin(steps) declares that a step only becomes ready once every listed
+ * predecessor has completed and routed into it (a fan-in barrier). anyJoin
+ * (steps) declares reconvergence — the step is ready the first time any one
+ * of the listed predecessors routes into it, which is also the engine's
+ * default when a step declares no waitFor at all. Both return a plain,
+ * serializable `waitFor` descriptor consumed by defineFlow() and engine.mjs.
+ */
+
+export function andJoin(steps) {
+  return { mode: 'all', steps: [...steps] };
+}
+
+export function anyJoin(steps) {
+  return { mode: 'any', steps: [...steps] };
+}

package/lib/flows/schema.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/flows/schema.mjs — hand-rolled JSON-Schema subset validator.
+ *
+ * Covers the subset flow state schemas need: type (string/number/integer/
+ * boolean/object/array/null, or an array of those for a union), properties,
+ * required, enum, items, additionalProperties, and minimum/maximum/minLength/
+ * maxLength/minItems/maxItems. No $ref, no allOf/anyOf/oneOf, no format
+ * keywords — deliberately not a general JSON-Schema implementation, only the
+ * smallest validator that lets a flow definition describe a typed state
+ * object and reject an invalid transition, per ADR-0001's zero-npm-
+ * dependency-core mandate (no ajv/zod).
+ */
+
+function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+}
+
+function matchesType(value, expected) {
+  const actual = typeOf(value);
+  if (expected === 'number') return actual === 'number' || actual === 'integer';
+  if (expected === 'integer') return actual === 'integer';
+  return actual === expected;
+}
+
+function validateNode(schema, value, path, errors) {
+  if (!schema || typeof schema !== 'object') return;
+
+  const expectedTypes = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : null;
+  if (expectedTypes && !expectedTypes.some((t) => matchesType(value, t))) {
+    errors.push(`${path}: expected type ${expectedTypes.join(' | ')}, got ${typeOf(value)}`);
+    return;
+  }
+
+  if (schema.enum && !schema.enum.some((allowed) => deepEqual(allowed, value))) {
+    errors.push(`${path}: value not in enum [${schema.enum.map(String).join(', ')}]`);
+  }
+
+  if (typeOf(value) === 'object') {
+    validateObject(schema, value, path, errors);
+  } else if (typeOf(value) === 'array') {
+    validateArray(schema, value, path, errors);
+  } else if (typeOf(value) === 'number' || typeOf(value) === 'integer') {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${path}: ${value} is above maximum ${schema.maximum}`);
+  } else if (typeOf(value) === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${path}: length ${value.length} is below minLength ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) errors.push(`${path}: length ${value.length} is above maxLength ${schema.maxLength}`);
+  }
+}
+
+function validateObject(schema, value, path, errors) {
+  const properties = schema.properties || {};
+  for (const key of schema.required || []) {
+    if (!(key in value)) errors.push(`${path}: missing required property "${key}"`);
+  }
+  for (const [key, propValue] of Object.entries(value)) {
+    if (properties[key]) {
+      validateNode(properties[key], propValue, `${path}.${key}`, errors);
+    } else if (schema.additionalProperties === false) {
+      errors.push(`${path}: unexpected property "${key}"`);
+    }
+  }
+}
+
+function validateArray(schema, value, path, errors) {
+  if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${path}: has ${value.length} items, below minItems ${schema.minItems}`);
+  if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(`${path}: has ${value.length} items, above maxItems ${schema.maxItems}`);
+  if (schema.items) {
+    value.forEach((item, i) => validateNode(schema.items, item, `${path}[${i}]`, errors));
+  }
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a !== 'object') return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((k) => deepEqual(a[k], b[k]));
+}
+
+export function validateSchema(schema, value) {
+  const errors = [];
+  validateNode(schema, value, '$', errors);
+  return { valid: errors.length === 0, errors };
+}

package/lib/flows/state.mjs

@@ -0,0 +1,31 @@
+/**
+ * lib/flows/state.mjs — typed state transitions validated against a flow's schema.
+ *
+ * transition() merges a shallow delta into the current state and validates the
+ * result against the flow's state schema before it becomes the new state. A
+ * failing transition never mutates the caller's state: it returns a structured
+ * `{ ok: false, error }` result carrying every schema violation, so the engine
+ * can surface a typed `invalid-state` step result instead of throwing mid-flow.
+ */
+
+import { validateSchema } from './schema.mjs';
+
+export function createInitialState(schema, seed = {}) {
+  const result = validateSchema(schema, seed);
+  if (!result.valid) {
+    return { ok: false, error: { code: 'INVALID_INITIAL_STATE', message: 'initial state fails the flow schema', errors: result.errors } };
+  }
+  return { ok: true, state: seed };
+}
+
+export function transition(schema, state, delta = {}) {
+  const merged = { ...state, ...delta };
+  const result = validateSchema(schema, merged);
+  if (!result.valid) {
+    return {
+      ok: false,
+      error: { code: 'INVALID_STATE_TRANSITION', message: 'state transition produced invalid state', errors: result.errors },
+    };
+  }
+  return { ok: true, state: merged };
+}

package/lib/frameworks/loader.mjs

@@ -0,0 +1,99 @@
+/**
+ * lib/frameworks/loader.mjs — pack-precedence framework resolution (ADR-0062, LMCP-F7).
+ *
+ * A pack manifest's `frameworks` map declares `{ framework-id: relativePath }`,
+ * resolved the same way lib/packs/prompts.mjs resolves `prompts`: relative to
+ * that pack's own directory (`_packDir`), falling back to `packageRoot` for
+ * the core pack (which has no `_packDir`). resolveFramework() walks a
+ * tier-precedence-ordered pack list and returns the first pack that declares
+ * the id, so a project-tier pack (.cx/packs) overrides the core pack for the
+ * same framework id — the same three-tier precedence every other pack asset
+ * obeys (ADR-0055).
+ *
+ * validatePackFrameworks() mirrors validatePackPrompts(): every declared
+ * framework file must exist and pass the ADR-0062 schema (schema.mjs), or
+ * the pack fails closed with the file path and offending field named.
+ */
+
+import { existsSync } from 'node:fs';
+import { join as joinPath } from 'node:path';
+import { parseFrameworkFile } from './schema.mjs';
+
+function packFrameworkRoot(pack, fallbackRoot) {
+  return pack?._packDir || fallbackRoot;
+}
+
+/**
+ * Validate every framework file a pack declares.
+ *
+ * @param {object} pack        a manifest object carrying `frameworks: {id: relPath}`
+ * @param {object} opts
+ * @param {string} opts.packageRoot   fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @param {Set<string>|string[]} [opts.knownRoles]  roles appliesToRole may name
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validatePackFrameworks(pack, { packageRoot, knownRoles } = {}) {
+  const errors = [];
+  const frameworks = pack?.frameworks || {};
+  const root = packFrameworkRoot(pack, packageRoot);
+
+  for (const [frameworkId, relPath] of Object.entries(frameworks)) {
+    if (typeof relPath !== 'string' || !relPath) {
+      errors.push(`pack '${pack.id}': framework entry for '${frameworkId}' has no file path`);
+      continue;
+    }
+    const absPath = joinPath(root, relPath);
+    if (!existsSync(absPath)) {
+      errors.push(`pack '${pack.id}': declared framework file missing for '${frameworkId}': ${relPath}`);
+      continue;
+    }
+    const result = parseFrameworkFile(absPath, { knownRoles });
+    if (!result.valid) {
+      errors.push(...result.errors.map((e) => `pack '${pack.id}': framework '${frameworkId}': ${e}`));
+      continue;
+    }
+    if (result.frontmatter.id !== frameworkId) {
+      errors.push(
+        `pack '${pack.id}': framework '${frameworkId}' declares mismatched frontmatter id '${result.frontmatter.id}'`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Resolve one framework through the pack registry only, honoring tier precedence.
+ *
+ * @param {string} frameworkId
+ * @param {object} opts
+ * @param {object[]} opts.packs      pack list, tier-precedence ordered (project before user before builtin)
+ * @param {string} opts.packageRoot  fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @param {Set<string>|string[]} [opts.knownRoles]
+ * @returns {{found: true, frontmatter: object, body: string, packId: string} | {found: false}}
+ */
+export function resolveFramework(frameworkId, { packs, packageRoot, knownRoles } = {}) {
+  for (const pack of packs || []) {
+    const relPath = pack?.frameworks?.[frameworkId];
+    if (!relPath) continue;
+    const absPath = joinPath(packFrameworkRoot(pack, packageRoot), relPath);
+    if (!existsSync(absPath)) continue;
+
+    const result = parseFrameworkFile(absPath, { knownRoles });
+    if (!result.valid) continue;
+
+    return { found: true, frontmatter: result.frontmatter, body: result.body, packId: pack.id };
+  }
+
+  return { found: false };
+}
+
+/**
+ * List every framework id a pack declares, without loading file contents.
+ *
+ * @param {object} pack
+ * @returns {string[]}
+ */
+export function listPackFrameworks(pack) {
+  return Object.keys(pack?.frameworks || {});
+}