@geraldmaron/construct 1.0.16 → 1.0.18

package/lib/embedded-contract/audit.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/embedded-contract/audit.mjs — approval gating and provenance identity for the ECL.
+ *
+ * Read-only contracts (capability, triage, model resolution) never write. The
+ * workflow-invocation contract is the only surface that can mutate durable
+ * state, and only when its approval mode permits. This module is the single
+ * place that maps an approval mode plus the deployment mode to a write gate, so
+ * the rule "no unapproved writes, mandatory audit on team/enterprise writes"
+ * lives in one tested function rather than scattered across call sites.
+ *
+ * The provenance sink for durable writes (the hash-chained audit trail) is wired
+ * by the workflow-invocation surface where writes actually occur and can be
+ * asserted against a real trail; this module owns the identity (traceId) and the
+ * gate decision.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const APPROVAL_MODES = ['proposal-only', 'requires-human-approval', 'allow-durable-write'];
+export const DEFAULT_APPROVAL_MODE = 'proposal-only';
+
+export function isValidApprovalMode(mode) {
+  return typeof mode === 'string' && APPROVAL_MODES.includes(mode);
+}
+
+/**
+ * Mint a trace identifier for one contract invocation. Carried in workflow
+ * responses so an embedder can correlate the call with downstream provenance.
+ *
+ * @returns {string}
+ */
+export function newTraceId() {
+  return `ecl-${randomUUID()}`;
+}
+
+/**
+ * Resolve whether durable writes are permitted for an invocation, whether the
+ * caller must collect human approval first, and whether the write must be
+ * audited. Unknown modes fall back to the safest mode (proposal-only).
+ *
+ * @param {object} opts
+ * @param {string} [opts.approvalMode]
+ * @param {string} [opts.deploymentMode]
+ * @returns {{approvalMode:string,allowWrites:boolean,requiresApproval:boolean,mandatoryAudit:boolean}}
+ */
+export function resolveWriteGate({ approvalMode = DEFAULT_APPROVAL_MODE, deploymentMode = 'solo' } = {}) {
+  const mode = isValidApprovalMode(approvalMode) ? approvalMode : DEFAULT_APPROVAL_MODE;
+  const allowWrites = mode === 'allow-durable-write';
+  const requiresApproval = mode === 'requires-human-approval';
+  const mandatoryAudit = allowWrites && (deploymentMode === 'team' || deploymentMode === 'enterprise');
+  return { approvalMode: mode, allowWrites, requiresApproval, mandatoryAudit };
+}

package/lib/embedded-contract/capability.mjs

@@ -0,0 +1,179 @@
+/**
+ * lib/embedded-contract/capability.mjs — capability discovery contract.
+ *
+ * Builds the read-only, secret-free description of what this Construct install
+ * can do: versions, the contract interfaces (CLI/MCP/SDK), roles, skills,
+ * workflows, schemas, models/providers, policies, telemetry posture, and
+ * plugins. Every section reads from the live registries so the published
+ * contract cannot drift from reality, and each section is independently
+ * guarded — a failing source degrades to a warning rather than breaking
+ * discovery. Provider data carries env-key NAMES and a configured boolean only,
+ * never a credential value; the envelope's no-secrets guard is the backstop.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getInstalledVersion } from '../version.mjs';
+import { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION } from './contract-version.mjs';
+import { listRoles } from '../roles/catalog.mjs';
+import { listModelFamilies } from '../model-router.mjs';
+import { resolveModelTiers } from '../model-registry.mjs';
+import { readSkillFrontmatter } from '../sync/skill-frontmatter.mjs';
+import { loadPluginRegistry } from '../plugin-registry.mjs';
+import { listWorkflowDefs } from './workflow-defs.mjs';
+import { APPROVAL_MODES } from './audit.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// The interfaces section describes the three transports every contract is
+// exposed on; each carries the contract version so an embedder can negotiate.
+
+function buildInterfaces() {
+  return [
+    { surface: 'cli', contractVersion: CONTRACT_VERSION, entrypoints: ['construct capability describe --json', 'construct models resolve --json', 'construct intake classify --json', 'construct graph recommend --json', 'construct workflow invoke --json'] },
+    { surface: 'mcp', contractVersion: CONTRACT_VERSION, tools: ['capability_describe', 'model_resolve', 'triage_recommend', 'workflow_invoke'] },
+    { surface: 'sdk', contractVersion: CONTRACT_VERSION, module: 'construct/embedded-contract', exports: ['describeCapabilities', 'resolveEmbeddedModel', 'recommendPlan', 'invokeWorkflow'] },
+  ];
+}
+
+function listSkillIds(skillsDir, prefix = '') {
+  let out = [];
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      const skillMd = join(skillsDir, entry.name, 'SKILL.md');
+      if (existsSync(skillMd)) out.push(`${prefix}${entry.name}`);
+      else out = out.concat(listSkillIds(join(skillsDir, entry.name), `${prefix}${entry.name}/`));
+    } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md' && entry.name !== 'routing.md') {
+      out.push(`${prefix}${entry.name.replace(/\.md$/, '')}`);
+    }
+  }
+  return out;
+}
+
+function buildSkills(rootDir, warnings) {
+  const skillsDir = join(rootDir, 'skills');
+  if (!existsSync(skillsDir)) return [];
+  const ids = listSkillIds(skillsDir).sort();
+  let missingMetadata = 0;
+  const skills = ids.map((id) => {
+    const candidates = [join(skillsDir, `${id}.md`), join(skillsDir, id, 'SKILL.md')];
+    const file = candidates.find(existsSync);
+    const fm = file ? readSkillFrontmatter(readFileSync(file, 'utf8')) : null;
+    const inputs = Array.isArray(fm?.inputs) ? fm.inputs : null;
+    const artifactType = typeof fm?.artifactType === 'string' ? fm.artifactType : null;
+    if (!inputs || !artifactType) missingMetadata += 1;
+    return { id, description: fm?.description || null, inputs, artifactType };
+  });
+  if (missingMetadata > 0) {
+    warnings.push(`${missingMetadata}/${skills.length} skills have no structured inputs/artifactType yet (optional frontmatter; annotated incrementally).`);
+  }
+  return skills;
+}
+
+function buildSchemas(rootDir, warnings) {
+  const out = [];
+  const dirs = [join(rootDir, 'lib', 'schemas'), join(rootDir, 'schemas')];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.json')) continue;
+      const full = join(dir, file);
+      let version = null;
+      try {
+        const parsed = JSON.parse(readFileSync(full, 'utf8'));
+        version = parsed.version ?? parsed.$id ?? null;
+      } catch { warnings.push(`Schema ${file} could not be parsed.`); }
+      out.push({ id: file.replace(/\.json$/, ''), version, location: relative(rootDir, full) });
+    }
+  }
+  return out;
+}
+
+function buildModels(env) {
+  const families = listModelFamilies({ env });
+  const providers = families.map((f) => ({
+    id: f.id,
+    label: f.label,
+    local: f.local,
+    requiresEnv: f.requiresEnv,
+    configured: f.configured,
+    healthStatus: 'unknown',
+  }));
+  const tiers = resolveModelTiers({ env });
+  return {
+    tiers: tiers.models,
+    tierSources: tiers.sources,
+    providers,
+  };
+}
+
+function buildPolicies(rootDir, warnings) {
+  try {
+    const raw = JSON.parse(readFileSync(join(rootDir, 'specialists', 'policy-inventory.json'), 'utf8'));
+    const arr = Array.isArray(raw) ? raw : (raw.policies || Object.values(raw));
+    return arr.map((p) => ({ id: p.id, enforcement: p.enforcement, mode: p.mode, description: p.description }));
+  } catch (err) {
+    warnings.push(`Policy inventory unavailable: ${err.message}`);
+    return [];
+  }
+}
+
+// Only public, secret-free plugin fields are surfaced — id, declared
+// capabilities, built-in flag, and exposed MCP ids. Plugin manifests can carry
+// requiredEnv and other config, so fields are picked explicitly rather than spread.
+
+function buildPlugins(rootDir, env, warnings) {
+  try {
+    const reg = loadPluginRegistry({ cwd: rootDir, rootDir, env });
+    if (reg.errors?.length) warnings.push(`Plugin registry reported ${reg.errors.length} issue(s).`);
+    return (reg.plugins || []).map((p) => ({
+      id: p.id,
+      capabilities: Array.isArray(p.capabilities) ? p.capabilities : [],
+      builtIn: Boolean(p.builtIn),
+      mcps: (p.mcps || []).map((m) => ({ id: m.id })),
+    }));
+  } catch (err) {
+    warnings.push(`Plugin registry unavailable: ${err.message}`);
+    return [];
+  }
+}
+
+function buildTelemetry(env) {
+  return {
+    tracingEnabled: Boolean(env.OTEL_EXPORTER_OTLP_ENDPOINT) && env.CONSTRUCT_OTEL !== 'off',
+    redaction: 'enabled',
+    note: 'Every contract response passes the no-secrets guard before serialization.',
+  };
+}
+
+/**
+ * Build the capability contract. Pure read; returns a result object carrying a
+ * `warnings` array (lifted into the envelope by the calling surface).
+ *
+ * @param {object} [opts]   { env, rootDir }
+ * @returns {object}
+ */
+export function buildCapabilityContract({ env = process.env, rootDir = REPO_ROOT } = {}) {
+  const warnings = [];
+  const { version: constructVersion, name } = getInstalledVersion();
+
+  return {
+    product: name,
+    constructVersion,
+    contractVersion: CONTRACT_VERSION,
+    minClientContractVersion: MIN_CLIENT_CONTRACT_VERSION,
+    approvalModes: APPROVAL_MODES,
+    interfaces: buildInterfaces(),
+    roles: listRoles(),
+    skills: buildSkills(rootDir, warnings),
+    workflows: listWorkflowDefs(),
+    schemas: buildSchemas(rootDir, warnings),
+    models: buildModels(env),
+    policies: buildPolicies(rootDir, warnings),
+    telemetry: buildTelemetry(env),
+    plugins: buildPlugins(rootDir, env, warnings),
+    warnings,
+  };
+}

package/lib/embedded-contract/contract-version.mjs

@@ -0,0 +1,39 @@
+/**
+ * lib/embedded-contract/contract-version.mjs — version of the Embedded Contract Layer (ECL).
+ *
+ * The ECL is Construct's app-facing surface exposed over CLI-JSON, MCP, and
+ * SDK. Its schema evolves independently of the Construct
+ * package version, so it carries its own semver: additive changes bump the
+ * minor, breaking changes bump the major. Every contract envelope embeds
+ * CONTRACT_VERSION so an embedding application can negotiate compatibility
+ * without reading internal registries.
+ *
+ * Distinct from specialists/contracts.json `version` (handoff contracts) and
+ * lib/plugin-registry.mjs `MANIFEST_VERSION` (plugin manifests); those version
+ * unrelated internal surfaces.
+ */
+
+import { parseSemver, compareSemver } from '../version.mjs';
+
+export const CONTRACT_VERSION = '1.0.0';
+
+// A client built against an older minor of the same major still works, because
+// minor bumps are additive-only; a different major is incompatible either way.
+
+export const MIN_CLIENT_CONTRACT_VERSION = '1.0.0';
+
+/**
+ * Whether a client built against `clientVersion` can talk to a server speaking
+ * `contractVersion`. Same major required; client minor must not exceed server.
+ *
+ * @param {string} clientVersion
+ * @param {string} [contractVersion]
+ * @returns {boolean}
+ */
+export function isClientCompatible(clientVersion, contractVersion = CONTRACT_VERSION) {
+  const client = parseSemver(clientVersion);
+  const server = parseSemver(contractVersion);
+  if (!client || !server) return false;
+  if (client.major !== server.major) return false;
+  return compareSemver(clientVersion, contractVersion) <= 0;
+}

package/lib/embedded-contract/envelope.mjs

@@ -0,0 +1,70 @@
+/**
+ * lib/embedded-contract/envelope.mjs — common response envelope for every contract surface.
+ *
+ * CLI-JSON, MCP, and SDK all wrap their payload with `wrapResponse`, which
+ * stamps the contract version, the installed Construct version, the active
+ * deployment mode, and a generation timestamp, then runs the no-secrets guard
+ * before the payload can be serialized. Routing every surface through one
+ * envelope is what makes the three interfaces structurally identical and keeps
+ * the redaction guard impossible to bypass.
+ *
+ * `generatedAt` (and any per-call traceId carried in `data`) are volatile, so
+ * surface-parity tests compare envelopes with those fields excluded.
+ */
+
+import { getInstalledVersion } from '../version.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION } from './contract-version.mjs';
+import { assertNoSecrets } from './redaction.mjs';
+
+export const CONTRACT_SURFACES = ['cli', 'mcp', 'sdk'];
+
+/**
+ * Wrap a contract payload in the standard envelope and assert it carries no
+ * secrets.
+ *
+ * @param {object} opts
+ * @param {*}        opts.data         The contract-specific payload.
+ * @param {string}   opts.surface      One of CONTRACT_SURFACES.
+ * @param {string[]} [opts.warnings]   Advisory messages for the caller.
+ * @param {Record<string,string>} [opts.env]
+ * @param {string}   [opts.cwd]
+ * @param {string}   [opts.generatedAt] ISO timestamp; injectable for deterministic tests.
+ * @returns {object}
+ */
+export function wrapResponse({ data, surface, warnings = [], env = process.env, cwd = process.cwd(), generatedAt } = {}) {
+  if (!CONTRACT_SURFACES.includes(surface)) {
+    throw new Error(`Unknown contract surface: ${surface}. Expected one of ${CONTRACT_SURFACES.join(', ')}`);
+  }
+
+  const { version: constructVersion } = getInstalledVersion();
+  const deploymentMode = getDeploymentMode(env, { cwd });
+
+  const envelope = {
+    contractVersion: CONTRACT_VERSION,
+    minClientContractVersion: MIN_CLIENT_CONTRACT_VERSION,
+    constructVersion,
+    deploymentMode,
+    surface,
+    generatedAt: generatedAt || new Date().toISOString(),
+    warnings: Array.isArray(warnings) ? warnings : [],
+    data,
+  };
+
+  assertNoSecrets(envelope, { env });
+  return envelope;
+}
+
+/**
+ * Wrap a contract-core result for a surface. The core returns its payload with a
+ * `warnings` array as one field; this lifts `warnings` into the envelope and
+ * keeps the rest as `data`, so CLI, MCP, and SDK produce identical envelopes.
+ *
+ * @param {object} result   The contract core's return value (may carry `warnings`).
+ * @param {object} opts      Forwarded to wrapResponse (surface, env, cwd, generatedAt).
+ * @returns {object}
+ */
+export function wrapContractResult(result, opts = {}) {
+  const { warnings = [], ...data } = result || {};
+  return wrapResponse({ ...opts, data, warnings });
+}

package/lib/embedded-contract/index.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/embedded-contract/index.mjs — SDK entrypoint for the Embedded Contract Layer.
+ *
+ * In-process applications import these functions to use Construct's app-facing
+ * contracts directly. Each returns the same versioned envelope the CLI-JSON and
+ * MCP surfaces emit, so a host can switch transports without reshaping its code.
+ * Published to package consumers via the package.json "exports" map.
+ */
+
+import { wrapContractResult } from './envelope.mjs';
+import { resolveEmbeddedModel as resolveModelCore } from './model-resolve.mjs';
+import { recommendPlan as recommendPlanCore } from './triage.mjs';
+import { invokeWorkflow as invokeWorkflowCore } from './workflow-invoke.mjs';
+import { buildCapabilityContract } from './capability.mjs';
+
+export { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION, isClientCompatible } from './contract-version.mjs';
+export { APPROVAL_MODES } from './audit.mjs';
+
+// File→text resolution for SDK callers: extract a path through the real
+// pipeline (docling/whisper/transcript), then pass { text, ingestion } to
+// recommendPlan/invokeWorkflow. Keeps the plan/invoke cores synchronous.
+
+export { resolveInput as extractFileForContract } from './ingest.mjs';
+
+/**
+ * Resolve which model an embedded workflow should use. Returns a versioned
+ * envelope; the resolution result is under `.data`.
+ *
+ * @param {object} request   See model-resolve.mjs resolveEmbeddedModel.
+ * @param {object} [opts]     { env, cwd, registryPath }
+ * @returns {object}
+ */
+export function resolveEmbeddedModel(request = {}, { env, cwd, registryPath } = {}) {
+  return wrapContractResult(resolveModelCore(request, { env, registryPath }), { surface: 'sdk', env, cwd });
+}
+
+/**
+ * Classify an artifact and return a role-aware plan without enqueuing or
+ * executing. Returns a versioned envelope; the plan is under `.data`.
+ *
+ * @param {object} request   See triage.mjs recommendPlan.
+ * @param {object} [opts]     { env, cwd }
+ * @returns {object}
+ */
+export function recommendPlan(request = {}, { env, cwd } = {}) {
+  return wrapContractResult(recommendPlanCore(request, { env, cwd }), { surface: 'sdk', env, cwd });
+}
+
+/**
+ * Invoke an embedded workflow (roles/skills) with approval gating and
+ * provenance. Async; returns a versioned envelope with the execution plan under
+ * `.data`. Durable writes occur only when approvalMode is allow-durable-write.
+ *
+ * @param {object} request   See workflow-invoke.mjs invokeWorkflow.
+ * @param {object} [opts]     { env, cwd }
+ * @returns {Promise<object>}
+ */
+export async function invokeWorkflow(request = {}, { env, cwd } = {}) {
+  return wrapContractResult(await invokeWorkflowCore(request, { env, cwd }), { surface: 'sdk', env, cwd });
+}
+
+/**
+ * Describe what this Construct install can do (read-only, secret-free). Returns
+ * a versioned envelope; the capability contract is under `.data`.
+ *
+ * @param {object} [opts]   { env, cwd, rootDir }
+ * @returns {object}
+ */
+export function describeCapabilities({ env, cwd, rootDir } = {}) {
+  return wrapContractResult(buildCapabilityContract({ env, rootDir }), { surface: 'sdk', env, cwd });
+}

package/lib/embedded-contract/ingest.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/embedded-contract/ingest.mjs — file→text resolution for embedded contracts.
+ *
+ * The embedded triage and workflow contracts accept either inline text or a file
+ * path. A file path is resolved through Construct's real extraction pipeline
+ * (`extractDocumentTextAsync`: docling for PDF/Office, whisper for audio/video,
+ * transcript/calendar/email extractors) rather than read as raw bytes, so an
+ * external application can hand Construct any supported artifact. Resolution is
+ * honest: a missing ASR backend or an unsupported type returns a structured
+ * error or a clearly-flagged best-effort fallback — never silent gibberish.
+ *
+ * Surfaces (CLI/MCP/SDK) own I/O and call this; the contract cores stay pure and
+ * receive the resolved text plus an `ingestion` metadata block to echo back.
+ */
+
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+
+import { extractDocumentTextAsync, isExtractableDocumentPath } from '../document-extract.mjs';
+
+/**
+ * Resolve contract input from inline text or a file path.
+ *
+ * @param {object} opts
+ * @param {string} [opts.input]     Inline text (returned as-is when provided).
+ * @param {string} [opts.filePath]  Path to extract when no inline text is given.
+ * @param {number} [opts.maxChars]
+ * @returns {Promise<{text:string, ingestion:(object|null), error:(object|null)}>}
+ */
+export async function resolveInput({ input = '', filePath = '', maxChars = null } = {}) {
+  if (input && input.trim()) {
+    return { text: input, ingestion: null, error: null };
+  }
+  if (!filePath) {
+    return { text: '', ingestion: null, error: null };
+  }
+
+  if (isExtractableDocumentPath(filePath)) {
+    try {
+      const extracted = await extractDocumentTextAsync(filePath, { maxChars });
+      return {
+        text: extracted.text || '',
+        ingestion: {
+          sourcePath: filePath,
+          extractionMethod: extracted.extractionMethod,
+          characters: extracted.characters,
+          truncated: extracted.truncated,
+          droppedInfo: extracted.droppedInfo || [],
+        },
+        error: null,
+      };
+    } catch (err) {
+      if (err && err.code === 'ASR_REQUIRED') {
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) or transcribe the file before sending.' } };
+      }
+      if (err && /WHISPER_BINARY_MISSING/.test(String(err.message))) {
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) to transcribe audio/video.' } };
+      }
+      return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'EXTRACTION_FAILED', reason: err.message, remediation: 'Verify the file is readable and of a supported type.' } };
+    }
+  }
+
+  // Extensions outside the extractor registry (e.g. .parquet, an unknown
+  // suffix) fall back to a flagged raw read so plain-text data still classifies
+  // rather than failing outright. Recognized text types including .csv/.tsv are
+  // handled above via the extraction pipeline's UTF-8 path.
+  try {
+    const text = readFileSync(filePath, 'utf8');
+    return {
+      text,
+      ingestion: { sourcePath: filePath, extractionMethod: 'raw-utf8', droppedInfo: [], note: `No structured extractor for ${extname(filePath) || 'this type'}; read as plain text.` },
+      error: null,
+    };
+  } catch (err) {
+    return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'FILE_UNREADABLE', reason: err.message, remediation: 'Check the path and permissions.' } };
+  }
+}

package/lib/embedded-contract/model-resolve.mjs

@@ -0,0 +1,186 @@
+/**
+ * lib/embedded-contract/model-resolve.mjs — embedded model resolution contract.
+ *
+ * Given a host/IDE's provider context, resolve which model an embedded Construct
+ * workflow should use, following a fixed precedence:
+ *   1. host-model           — the host's model, when recognized
+ *   2. same-family-fallback — a tier model in the host model's provider family
+ *   3. tier-default         — Construct's configured tier default (env/config/registry)
+ *   4. config error         — structured error with remediation when nothing resolves
+ *
+ * Cross-provider fallback is only taken when the caller opts in; otherwise host
+ * context that cannot be honored within its family yields a config error rather
+ * than silently switching providers. The contract never reads or returns a
+ * credential value — `requiresCredential` is a derived boolean — and never
+ * claims provider health it cannot verify (`healthStatus` defaults to unknown).
+ */
+
+import { describeModelFamily, listModelFamilies } from '../model-router.mjs';
+import { resolveModelTiers } from '../model-registry.mjs';
+import { resolveProviderCapabilitiesSync } from '../provider-capabilities.js';
+
+const VALID_TIERS = ['reasoning', 'standard', 'fast'];
+const DEFAULT_TIER = 'standard';
+
+// Workflow types lean toward deeper reasoning or faster turnaround; this maps a
+// workflowType to a tier only when the caller did not request one explicitly.
+
+const WORKFLOW_TIER_HINTS = {
+  'architecture-review': 'reasoning',
+  'risk-review': 'reasoning',
+  'research-synthesis': 'reasoning',
+  'prd-draft': 'standard',
+  'proposal-review': 'standard',
+  'evidence-ingest': 'fast',
+};
+
+function normalizeTier(tier) {
+  return VALID_TIERS.includes(tier) ? tier : null;
+}
+
+function resolveTier({ requestedTier, workflowType }) {
+  return normalizeTier(requestedTier) || WORKFLOW_TIER_HINTS[workflowType] || DEFAULT_TIER;
+}
+
+// Capability matching is best-effort against the model's known capability flags;
+// names that cannot be confirmed are surfaced as warnings rather than asserted.
+
+function matchCapabilities(modelId, requested, warnings) {
+  if (!Array.isArray(requested) || requested.length === 0) return [];
+  const caps = resolveProviderCapabilitiesSync(modelId);
+  const matched = [];
+  const unverified = [];
+  for (const name of requested) {
+    const key = String(name);
+    if (caps[key] === true) matched.push(key);
+    else unverified.push(key);
+  }
+  if (unverified.length) {
+    warnings.push(`Capability not confirmed for ${modelId}: ${unverified.join(', ')} (capability verification is best-effort).`);
+  }
+  return matched;
+}
+
+function familyByProvider(hostProvider, env) {
+  if (!hostProvider || typeof hostProvider !== 'string') return null;
+  const families = listModelFamilies({ env });
+  return families.find((f) => f.id === hostProvider)
+    || families.find((f) => f.id === `openrouter-${hostProvider}`)
+    || null;
+}
+
+function success({ selectedModel, family, tier, resolutionSource, fallbackReason = null, tierSource = null, capabilities, warnings, env }) {
+  return {
+    selectedModel,
+    selectedProvider: family ? family.id : null,
+    providerFamily: family ? family.id : null,
+    resolutionSource,
+    requestedTier: tier,
+    fallbackReason,
+    tierSource,
+    capabilitiesMatched: matchCapabilities(selectedModel, capabilities, warnings),
+    healthStatus: 'unknown',
+    estimatedLimits: null,
+    requiresCredential: family ? !family.local && !family.configured : true,
+    error: null,
+    warnings,
+  };
+}
+
+function configError({ tier, reason, remediation, warnings }) {
+  return {
+    selectedModel: null,
+    selectedProvider: null,
+    providerFamily: null,
+    resolutionSource: 'config-error',
+    requestedTier: tier,
+    fallbackReason: null,
+    tierSource: null,
+    capabilitiesMatched: [],
+    healthStatus: 'unknown',
+    estimatedLimits: null,
+    requiresCredential: null,
+    error: { code: 'MODEL_UNRESOLVED', reason, remediation },
+    warnings,
+  };
+}
+
+/**
+ * Resolve the model an embedded workflow should use. Pure and synchronous;
+ * returns a result object carrying a `warnings` array (lifted into the envelope
+ * by the calling surface).
+ *
+ * @param {object} request
+ * @param {string} [request.workflowType]
+ * @param {string} [request.requestedTier]      reasoning | standard | fast
+ * @param {string} [request.host]
+ * @param {string} [request.hostModel]
+ * @param {string} [request.hostProvider]
+ * @param {string[]} [request.capabilities]
+ * @param {boolean} [request.allowCrossProviderFallback=false]
+ * @param {object} [opts]
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.registryPath]
+ * @returns {object}
+ */
+export function resolveEmbeddedModel(request = {}, { env = process.env, registryPath = null } = {}) {
+  const { workflowType, requestedTier, hostModel, hostProvider, capabilities, allowCrossProviderFallback = false } = request;
+  const tier = resolveTier({ requestedTier, workflowType });
+  const warnings = [];
+
+  const hostFamily = hostModel ? describeModelFamily(hostModel, { env }) : null;
+
+  if (hostModel && hostFamily) {
+    return success({ selectedModel: hostModel, family: hostFamily, tier, resolutionSource: 'host-model', capabilities, warnings, env });
+  }
+  if (hostModel && !hostFamily) {
+    warnings.push(`Host model "${hostModel}" is not a recognized provider family; attempting same-family or tier fallback.`);
+  }
+
+  const family = hostFamily || familyByProvider(hostProvider, env);
+  if (family) {
+    const model = family.tiers[tier];
+    if (model) {
+      const fallbackReason = hostModel
+        ? `Exact host model unavailable; resolved the ${tier} model in the same provider family (${family.id}).`
+        : `Resolved the ${tier} model within the host provider family (${family.id}).`;
+      return success({ selectedModel: model, family, tier, resolutionSource: 'same-family-fallback', fallbackReason, capabilities, warnings, env });
+    }
+  }
+
+  const hadHostContext = Boolean(hostModel || hostProvider);
+  if (hadHostContext && !allowCrossProviderFallback) {
+    return configError({
+      tier,
+      reason: 'Host model/provider could not be honored within its family and cross-provider fallback is disabled.',
+      remediation: 'Pass allowCrossProviderFallback=true, supply a recognized hostModel, or configure a same-family credential.',
+      warnings,
+    });
+  }
+
+  const tiers = resolveModelTiers({ env, registryPath });
+  const defaultModel = tiers.models[tier];
+  if (defaultModel) {
+    const fallbackReason = hadHostContext
+      ? 'Host context could not be honored within its family; used the Construct tier default after cross-provider fallback was permitted.'
+      : 'No host context supplied; used the Construct tier default.';
+    return success({
+      selectedModel: defaultModel,
+      family: describeModelFamily(defaultModel, { env }),
+      tier,
+      resolutionSource: 'tier-default',
+      fallbackReason,
+      tierSource: tiers.sources[tier] || 'default',
+      capabilities,
+      warnings,
+      env,
+    });
+  }
+
+  return configError({
+    tier,
+    reason: `No model could be resolved for the ${tier} tier.`,
+    remediation: 'Set CX_MODEL_REASONING/STANDARD/FAST or configure a provider credential.',
+    warnings,
+  });
+}