@geraldmaron/construct 1.0.18 → 1.0.20

package/lib/deployment/parity-contract.mjs

@@ -0,0 +1,148 @@
+/**
+ * lib/deployment/parity-contract.mjs — capability parity across deployment modes.
+ *
+ * Declares, for every dimension of lib/deployment-mode.mjs RESOURCE_TOPOLOGY,
+ * whether the capability is `parity` (present in every mode, backend may differ)
+ * or `mode-specific` (present only in some modes, by design). validateParityContract
+ * cross-checks the declaration against the live topology so the two cannot drift:
+ * a new topology dimension with no declaration, or a `parity` capability absent in
+ * a mode, fails the check. See ADR-0016.
+ *
+ * Scope is the static guard only. A live dual-run harness (run a capability in
+ * solo and team, compare) is the stronger complement, tracked separately — it
+ * needs a provisioned database and so cannot gate every change.
+ */
+
+import { DEPLOYMENT_MODES, resolveResourceMode } from '../deployment-mode.mjs';
+
+export const PARITY_CLASSES = ['parity', 'mode-specific'];
+
+// Backend value 'optional' means the capability is present but may run on a
+// degraded local backend (e.g. file BM25 in place of pgvector); it still counts
+// as present for parity purposes.
+
+export const PARITY_CONTRACT = {
+  queue: {
+    parityClass: 'parity',
+    capability: 'Work intake queue (enqueue, list pending, mark processed)',
+    rationale: 'Filesystem queue (solo) and Postgres queue (team) implement one interface via lib/intake/queue.mjs.',
+    evidence: 'tests/intake-queue-factory.test.mjs',
+  },
+  memory: {
+    parityClass: 'parity',
+    capability: 'Observation/memory store',
+    rationale: 'Local index (solo) and shared Postgres (team) both satisfy the observation schema; Postgres is a secondary store.',
+    evidence: 'lib/observation-store.mjs',
+  },
+  database: {
+    parityClass: 'parity',
+    capability: 'Knowledge retrieval and durable state',
+    rationale: 'Present in every mode; solo degrades to file BM25 + local vectors when Postgres is absent.',
+    evidence: 'lib/storage/hybrid-query.mjs',
+  },
+  telemetry: {
+    parityClass: 'parity',
+    capability: 'Trace capture',
+    rationale: 'Local JSONL is the default in every mode; remote export (OTel/Langfuse) is opt-in, not required for the capability.',
+    evidence: 'lib/telemetry/client.mjs',
+  },
+  workers: {
+    parityClass: 'mode-specific',
+    capability: 'Background worker pool that claims queued work',
+    rationale: 'Solo runs work in-process in the user session; the async Docker/isolated worker pool exists only in team and enterprise.',
+    evidence: 'lib/deployment-mode.mjs',
+  },
+  policy: {
+    parityClass: 'mode-specific',
+    capability: 'Server-side policy enforcement',
+    rationale: 'Solo enforces via local hooks (lightweight); server-side/enforceable policy is a team and enterprise capability.',
+    evidence: 'lib/deployment-mode.mjs',
+  },
+  mcp: {
+    parityClass: 'mode-specific',
+    capability: 'Brokered MCP with policy, audit, and rate limiting',
+    rationale: 'Solo calls MCP tools directly; the broker (and its audit/rate-limit/policy) exists only in team and enterprise.',
+    evidence: 'lib/mcp/broker.mjs',
+  },
+};
+
+function topologyByDimension() {
+  const byMode = {};
+  for (const mode of DEPLOYMENT_MODES) byMode[mode] = resolveResourceMode(mode);
+  const dimensions = new Set();
+  for (const mode of DEPLOYMENT_MODES) for (const dim of Object.keys(byMode[mode])) dimensions.add(dim);
+  return { byMode, dimensions: [...dimensions] };
+}
+
+/**
+ * Cross-check the declared parity contract against the live resource topology.
+ * Returns { ok, errors }. Failures: an undeclared topology dimension, a declared
+ * capability with no topology dimension, an invalid parityClass, a `parity`
+ * capability missing from some mode, or a `mode-specific` capability whose backend
+ * is identical across all modes (then it is not actually mode-specific).
+ */
+export function validateParityContract() {
+  const { byMode, dimensions } = topologyByDimension();
+  const errors = [];
+
+  for (const dim of dimensions) {
+    if (!PARITY_CONTRACT[dim]) {
+      errors.push(`topology dimension "${dim}" has no parity declaration (declare it parity or mode-specific in PARITY_CONTRACT)`);
+    }
+  }
+
+  for (const [dim, decl] of Object.entries(PARITY_CONTRACT)) {
+    if (!dimensions.includes(dim)) {
+      errors.push(`parity declaration "${dim}" has no matching topology dimension`);
+      continue;
+    }
+    if (!PARITY_CLASSES.includes(decl.parityClass)) {
+      errors.push(`"${dim}": invalid parityClass "${decl.parityClass}"`);
+      continue;
+    }
+    const values = DEPLOYMENT_MODES.map((m) => byMode[m][dim]);
+    if (decl.parityClass === 'parity') {
+      const missing = DEPLOYMENT_MODES.filter((m) => !byMode[m][dim]);
+      if (missing.length > 0) {
+        errors.push(`"${dim}" is declared parity but absent in mode(s): ${missing.join(', ')}`);
+      }
+    } else if (new Set(values).size === 1) {
+      errors.push(`"${dim}" is declared mode-specific but its backend is identical across all modes (${values[0]})`);
+    }
+    if (!decl.rationale) errors.push(`"${dim}": mode-specific and parity declarations both require a rationale`);
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function describeParityContract() {
+  const { byMode } = topologyByDimension();
+  const rows = Object.entries(PARITY_CONTRACT).map(([dim, decl]) => {
+    const backends = DEPLOYMENT_MODES.map((m) => `${m}:${byMode[m][dim]}`).join(' ');
+    return { dimension: dim, parityClass: decl.parityClass, backends, capability: decl.capability, rationale: decl.rationale };
+  });
+  return rows;
+}
+
+export async function runDeploymentParityCli(args = []) {
+  if (args.includes('--json')) {
+    const { ok, errors } = validateParityContract();
+    process.stdout.write(JSON.stringify({ ok, errors, contract: describeParityContract() }, null, 2) + '\n');
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  const { ok, errors } = validateParityContract();
+  for (const row of describeParityContract()) {
+    const mark = row.parityClass === 'parity' ? '=' : '≠';
+    process.stdout.write(`${mark} ${row.dimension.padEnd(10)} [${row.parityClass}]  ${row.backends}\n   ${row.capability}\n`);
+  }
+  process.stdout.write('\n');
+  if (ok) {
+    process.stdout.write('✓ parity contract reconciled with deployment topology\n');
+    return;
+  }
+  process.stderr.write(`✗ parity contract has ${errors.length} error(s):\n`);
+  for (const e of errors) process.stderr.write(`  - ${e}\n`);
+  process.exit(1);
+}

package/lib/document-ingest.mjs

@@ -3,7 +3,9 @@
  *
  * Reuses the shared extraction backends from lib/document-extract.mjs, writes
  * markdown outputs into retrieval-friendly project paths, and can optionally
- * trigger storage sync for SQL/vector indexing.
+ * trigger storage sync for SQL/vector indexing. The extraction step honors a
+ * resolved ingest strategy (adapter | provider) with an explicit fallback policy
+ * and records the selected strategy/model in the returned `ingestion` block.
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
@@ -11,6 +13,9 @@ import { extractDocumentText, extractDocumentTextAsync, extractDocumentMetadata,
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
+import { loadProjectConfig } from './config/project-config.mjs';
+import { resolveIngestStrategy, INGEST_STRATEGIES } from './ingest/strategy.mjs';
+import { extractViaProvider } from './ingest/provider-extract.mjs';
 
 const DEFAULT_TARGET_DIR = '.cx/knowledge/internal';
 
@@ -121,6 +126,38 @@ function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
   return join(resolvedDir, `${basename(sourcePath)}.md`);
 }
 
+function extractViaAdapter(sourcePath, { highFidelity, maxChars }) {
+  return highFidelity
+    ? extractDocumentTextAsync(sourcePath, { maxChars })
+    : extractDocumentText(sourcePath, { maxChars });
+}
+
+async function extractWithStrategy(sourcePath, { strategy, fallback, model, provider, highFidelity, maxChars, env }) {
+  const primary = strategy === 'provider' ? 'provider' : 'adapter';
+  const run = (mode) => (mode === 'provider'
+    ? extractViaProvider({ filePath: sourcePath, model, provider, maxChars, env })
+    : extractViaAdapter(sourcePath, { highFidelity, maxChars }));
+
+  try {
+    const extracted = await run(primary);
+    return { extracted, strategyUsed: primary, fallbackApplied: null, error: null };
+  } catch (primaryErr) {
+    if (fallback === 'none' || fallback === primary) {
+      const err = new Error(`ingest ${primary} strategy failed and fallback is "${fallback}": ${primaryErr.message}`);
+      err.code = primaryErr.code || 'INGEST_STRATEGY_FAILED';
+      err.cause = primaryErr;
+      throw err;
+    }
+    const extracted = await run(fallback);
+    return {
+      extracted,
+      strategyUsed: fallback,
+      fallbackApplied: { from: primary, to: fallback, reason: primaryErr.message, code: primaryErr.code || 'INGEST_STRATEGY_FAILED' },
+      error: null,
+    };
+  }
+}
+
 export async function ingestDocuments(inputPaths, {
   cwd = process.cwd(),
   outputPath = null,
@@ -129,6 +166,7 @@ export async function ingestDocuments(inputPaths, {
   sync = false,
   strict = false,
   highFidelity = true,
+  strategy = null,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -143,12 +181,24 @@ export async function ingestDocuments(inputPaths, {
     throw new Error('No supported document files found');
   }
 
+  const { config } = loadProjectConfig(cwd, env);
+  const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy });
+
   const results = [];
   let totalDrops = 0;
+  let fallbackApplied = null;
   for (const sourcePath of files) {
-    const extracted = highFidelity
-      ? await extractDocumentTextAsync(sourcePath, { maxChars: 200_000 })
-      : extractDocumentText(sourcePath, { maxChars: 200_000 });
+    const routed = await extractWithStrategy(sourcePath, {
+      strategy: resolvedStrategy.strategy,
+      fallback: resolvedStrategy.fallback,
+      model: resolvedStrategy.model,
+      provider: resolvedStrategy.provider,
+      highFidelity,
+      maxChars: 200_000,
+      env,
+    });
+    const extracted = routed.extracted;
+    if (routed.fallbackApplied) fallbackApplied = routed.fallbackApplied;
     totalDrops += (extracted.droppedInfo ?? []).reduce((a, d) => a + (Number(d.count) || 1), 0);
     const metadata = extractDocumentMetadata(sourcePath);
     const targetPath = resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target });
@@ -213,6 +263,13 @@ export async function ingestDocuments(inputPaths, {
     droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
     droppedCount: totalDrops,
     highFidelity,
+    ingestion: {
+      strategy: resolvedStrategy.strategy,
+      fallback: resolvedStrategy.fallback,
+      model: resolvedStrategy.model,
+      provider: resolvedStrategy.provider,
+      fallbackApplied,
+    },
   };
 }
 
@@ -224,26 +281,34 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let sync = false;
   let strict = false;
   let highFidelity = true;
+  let strategy = null;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--out-dir=')) outputDir = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
+    else if (arg.startsWith('--strategy=')) strategy = arg.split('=').slice(1).join('=');
+    else if (arg === '--strategy') strategy = '';
     else if (arg === '--sync') sync = true;
     else if (arg === '--strict') strict = true;
     else if (arg === '--legacy-extractor') highFidelity = false;
+    else if (strategy === '') strategy = arg;
     else inputs.push(arg);
   }
 
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--sync] [--strict] [--legacy-extractor]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--sync] [--strict] [--legacy-extractor]\n` +
+      `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
       `  --strict: exit non-zero if any extraction drops occur\n` +
       `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }
+  if (strategy !== null && strategy !== '' && !INGEST_STRATEGIES.includes(strategy)) {
+    throw new Error(`Unsupported strategy: ${strategy}. Valid strategies: ${INGEST_STRATEGIES.join(', ')}`);
+  }
   const knowledgeTargets = KNOWLEDGE_SUBDIRS.map((s) => `knowledge/${s}`);
   if (!['sibling', ...knowledgeTargets].includes(target)) {
     throw new Error(
@@ -251,5 +316,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, env });
 }

package/lib/embed/cli.mjs

@@ -533,6 +533,17 @@ async function cmdEmbedMigrateModel(args) {
     process.stdout.write(
       `Done. embeddingsSynced=${result.embeddingsSynced} model=${result.embeddingModel}\n`
     );
+
+    // Observations share the embedding model/dimension. Re-dimension their
+    // column too, then reconcile re-embeds them from the local source so both
+    // corpora live in one vector space after a model change.
+    await client.unsafe(
+      `BEGIN; TRUNCATE TABLE construct_observations; ` +
+      `ALTER TABLE construct_observations ALTER COLUMN embedding TYPE vector(${targetDim}); COMMIT;`
+    );
+    const { reconcileObservationEmbeddings } = await import('./reconcile.mjs');
+    const recon = await reconcileObservationEmbeddings(process.cwd());
+    process.stdout.write(`Observations reconciled: re-embedded ${recon.reembedded}.\n`);
   } catch (err) {
     process.stderr.write(`migrate-model failed: ${err.message}\n`);
     process.exit(1);

package/lib/embed/conflict-detection.mjs

@@ -15,7 +15,7 @@
  *   Rebuilt on first use or when artifact file count changes.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, renameSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { embed, cosineSimilarity, extractTextFromPacket } from './semantic.mjs';
 import { listArtifacts } from './artifact.mjs';
@@ -253,9 +253,9 @@ export async function detectInterItemConflicts(pendingPackets, { threshold = 0.7
  */
 export function resetArtifactIndex() {
   _artifactIndex = null;
-  if (existsSync(INDEX_FILE)) {
-    const { unlinkSync } = require('node:fs');
-    try { unlinkSync(INDEX_FILE); } catch { /* ignore */ }
+  const { indexFile } = indexPaths();
+  if (existsSync(indexFile)) {
+    try { unlinkSync(indexFile); } catch { /* ignore */ }
   }
 }
 

package/lib/embed/customer-profiles.mjs

@@ -273,7 +273,7 @@ export function searchCustomerProfiles(query) {
         id: entry.id,
         name: entry.name,
         status: entry.status,
-        path: join(PROFILES_DIR, `${slugify(entry.name)}-${entry.id}.md`),
+        path: join(profilesDir, `${slugify(entry.name)}-${entry.id}.md`),
       });
     }
   }

package/lib/embed/reconcile.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/embed/reconcile.mjs — bring the Postgres observation index back in sync
+ * with the local source of truth.
+ *
+ * Observations are embedded inline on write (lib/observation-store.mjs), but
+ * the inline write is skipped whenever Postgres is unreachable at creation time
+ * (the local hashing-bow fallback is used instead), and a model change leaves
+ * every prior row embedded in a stale vector space. This pass is the safety
+ * net: for each local observation it compares the (content_hash, model) the
+ * pg row was embedded with against the live content + current model, and
+ * re-embeds ONLY the rows that are missing or stale. Idempotent — a second run
+ * with no changes re-embeds nothing.
+ *
+ * Reconciliation-on-sync is preferred over a fixed-interval polling cron (see
+ * docs/research/vector-search-best-practices.md): the pass runs where Construct
+ * already touches storage (the model-change re-embed, the storage CLI), keys
+ * idempotency on a content hash, and re-embeds on model change.
+ */
+
+import { VectorClient } from '../storage/vector-client.mjs';
+import { embedText as embedTextEngine, getEmbeddingModelInfo } from '../storage/embeddings-engine.mjs';
+import { listObservations, getObservation, observationSearchText, observationContentHash } from '../observation-store.mjs';
+
+export async function reconcileObservationEmbeddings(rootDir, { env = process.env, limit = Infinity, embed = embedTextEngine, modelId = null } = {}) {
+  const client = new VectorClient({ env });
+  const result = { checked: 0, reembedded: 0, model: null, skipped: null };
+
+  try {
+    if (!(await client.isHealthy()) || !(await client.isPgvectorEnabled())) {
+      result.skipped = 'no-pg';
+      return result;
+    }
+
+    const currentModel = modelId || (await getEmbeddingModelInfo({ env })).model;
+    result.model = currentModel;
+
+    const ids = (listObservations(rootDir, { limit: Number.MAX_SAFE_INTEGER }) || []).map((e) => e.id);
+    const fingerprints = await client.getObservationFingerprints(ids);
+
+    for (const id of ids) {
+      if (result.reembedded >= limit) break;
+      const obs = getObservation(rootDir, id);
+      if (!obs) continue;
+      result.checked += 1;
+
+      const searchText = observationSearchText(obs);
+      const hash = observationContentHash(searchText);
+      const fp = fingerprints.get(id);
+      if (fp && fp.contentHash === hash && fp.model === currentModel) continue;
+
+      const { embedding, model } = await embed(searchText, { env });
+      await client.storeObservation({ ...obs, embedding, contentHash: hash, model: model || currentModel });
+      result.reembedded += 1;
+    }
+
+    return result;
+  } finally {
+    await client.close();
+  }
+}

package/lib/embedded-contract/capability.mjs

@@ -32,9 +32,9 @@ const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 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'] },
+    { surface: 'cli', contractVersion: CONTRACT_VERSION, entrypoints: ['construct capability describe --json', 'construct models resolve --json', 'construct execution resolve --json', 'construct intake classify --json', 'construct graph recommend --json', 'construct workflow invoke --json'] },
+    { surface: 'mcp', contractVersion: CONTRACT_VERSION, tools: ['capability_describe', 'model_resolve', 'construct_execution_resolve', 'triage_recommend', 'workflow_invoke'] },
+    { surface: 'sdk', contractVersion: CONTRACT_VERSION, module: 'construct/embedded-contract', exports: ['describeCapabilities', 'resolveEmbeddedModel', 'resolveExecution', 'recommendPlan', 'invokeWorkflow'] },
   ];
 }
 

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

@@ -15,7 +15,7 @@
 
 import { parseSemver, compareSemver } from '../version.mjs';
 
-export const CONTRACT_VERSION = '1.0.0';
+export const CONTRACT_VERSION = '1.1.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.

package/lib/embedded-contract/execution.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/embedded-contract/execution.mjs — embedded execution-capability contract.
+ *
+ * An embedded host can request Construct orchestration but cannot otherwise tell
+ * whether a run actually engaged personas/skills/routing or degraded to a
+ * prompt-only envelope — and if it degraded, why. This contract answers that
+ * before or at workflow start: given a requested strategy and the host's model
+ * context, it derives an `executionMode`, the Construct capabilities that mode
+ * contributes, and an explicit degradation reason.
+ *
+ * Honesty boundary (ADR-0019): orchestration in the embedded layer is
+ * DESCRIPTIVE, not enforced. Construct returns a plan; the host runtime performs
+ * the reasoning. So this contract reports what Construct PLANNED and can RESOLVE
+ * a model for — never an observation that the host executed personas. Every
+ * response carries a `semantics` disclaimer to that effect, and
+ * `constructCapabilitiesActive` describes Construct's contribution, not proof of
+ * host execution. Claiming observed orchestration would violate the
+ * no-fabrication rule. A `same-family-fallback` (host model unavailable) and a
+ * `config-error` (no model) both surface as `degraded: true`.
+ *
+ * Pure and synchronous; reuses resolveEmbeddedModel (no second model surface)
+ * and returns a result object carrying `warnings`, lifted into the envelope by
+ * the calling surface.
+ */
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { getWorkflowDef } from './workflow-defs.mjs';
+
+export const EXECUTION_MODES = ['construct-orchestrated', 'construct-prompt-only', 'host-direct', 'same-family-fallback'];
+export const CONSTRUCT_STRATEGIES = ['orchestrated', 'prompt-only', 'auto'];
+export const CONSTRUCT_CAPABILITIES = ['personas', 'skills', 'workflow-routing', 'prompt-envelope'];
+
+export const EXECUTION_SEMANTICS = 'Reports Construct-planned capability and model-resolvability before/at workflow start; does not observe host execution. constructCapabilitiesActive describes what Construct contributes, not proof the host ran personas/skills.';
+
+const ORCHESTRATED_CAPS = ['personas', 'skills', 'workflow-routing', 'prompt-envelope'];
+const PROMPT_ONLY_CAPS = ['prompt-envelope'];
+
+function normalizeStrategy(value) {
+  const lowered = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return CONSTRUCT_STRATEGIES.includes(lowered) ? lowered : null;
+}
+
+/**
+ * Resolve the execution-capability contract for an embedded workflow.
+ *
+ * @param {object} request
+ * @param {string} [request.workflowType]        workflow whose orchestration plan is being weighed
+ * @param {string} [request.requestedStrategy]   orchestrated | prompt-only | auto (default auto)
+ * @param {boolean} [request.useConstruct=true]  false ⇒ host-direct (host runs without Construct)
+ * @param {string} [request.host]
+ * @param {string} [request.hostModel]
+ * @param {string} [request.hostProvider]
+ * @param {string} [request.requestedTier]
+ * @param {string[]} [request.capabilities]
+ * @param {boolean} [request.allowCrossProviderFallback=false]
+ * @param {object} [opts]
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.registryPath]
+ * @returns {object}
+ */
+export function resolveExecution(request = {}, { env = process.env, cwd = process.cwd(), registryPath = null } = {}) {
+  const {
+    workflowType = null,
+    requestedStrategy: rawStrategy,
+    useConstruct = true,
+    host, hostModel, hostProvider, requestedTier, capabilities, allowCrossProviderFallback = false,
+  } = request;
+
+  const warnings = [];
+  const requestedStrategy = normalizeStrategy(rawStrategy) || 'auto';
+  if (rawStrategy != null && !normalizeStrategy(rawStrategy)) {
+    warnings.push(`Unknown requestedStrategy "${rawStrategy}"; defaulted to "auto".`);
+  }
+
+  const deploymentMode = getDeploymentMode(env, { cwd });
+
+  // Model resolution is the single source of provider/model truth; its warnings
+  // are namespaced so an embedder can tell model concerns from execution ones.
+  const modelResolution = resolveEmbeddedModel(
+    { workflowType, requestedTier, host, hostModel, hostProvider, capabilities, allowCrossProviderFallback },
+    { env, registryPath },
+  );
+  for (const w of modelResolution.warnings || []) warnings.push(`model-resolution: ${w}`);
+
+  const { resolutionSource, selectedModel, selectedProvider } = modelResolution;
+  const orchestrationAvailable = resolutionSource !== 'config-error';
+
+  // An explicit-but-unknown workflowType has no plan; absent a workflowType,
+  // Construct's generic router can still orchestrate, so a plan is available.
+  const knownWorkflow = workflowType ? Boolean(getWorkflowDef(workflowType)) : true;
+  if (workflowType && !knownWorkflow) {
+    warnings.push(`Unknown workflowType "${workflowType}"; no orchestration plan is available for it.`);
+  }
+  const orchestrationPlanned = knownWorkflow;
+
+  const base = {
+    requestedStrategy,
+    selectedProvider,
+    selectedModel,
+    resolutionSource,
+    orchestrationPlanned,
+    orchestrationAvailable,
+    deploymentMode,
+    modelResolution: stripWarnings(modelResolution),
+    semantics: EXECUTION_SEMANTICS,
+    warnings,
+  };
+
+  if (useConstruct === false) {
+    return {
+      ...base,
+      executionMode: 'host-direct',
+      effectiveStrategy: 'host-direct',
+      constructCapabilitiesActive: [],
+      degraded: false,
+      degradationReason: null,
+    };
+  }
+
+  if (requestedStrategy === 'prompt-only') {
+    return {
+      ...base,
+      executionMode: 'construct-prompt-only',
+      effectiveStrategy: 'prompt-only',
+      constructCapabilitiesActive: [...PROMPT_ONLY_CAPS],
+      degraded: false,
+      degradationReason: null,
+    };
+  }
+
+  // orchestrated or auto: deliver orchestration only when a plan exists AND a
+  // model resolves. A same-family fallback runs but did not honor the host's
+  // exact model, so it is reported as its own mode and as degraded.
+  const canOrchestrate = orchestrationPlanned && orchestrationAvailable;
+  if (canOrchestrate) {
+    if (resolutionSource === 'same-family-fallback') {
+      return {
+        ...base,
+        executionMode: 'same-family-fallback',
+        effectiveStrategy: 'orchestrated',
+        constructCapabilitiesActive: [...ORCHESTRATED_CAPS],
+        degraded: true,
+        degradationReason: `Host model unavailable; resolved a same-family tier model — ${modelResolution.fallbackReason || 'same-family fallback applied'}.`,
+      };
+    }
+    return {
+      ...base,
+      executionMode: 'construct-orchestrated',
+      effectiveStrategy: 'orchestrated',
+      constructCapabilitiesActive: [...ORCHESTRATED_CAPS],
+      degraded: false,
+      degradationReason: null,
+    };
+  }
+
+  // Could not orchestrate. Degradation is asserted only when orchestration was
+  // explicitly requested, or when no model resolved at all (auto still needs a
+  // model to do anything useful).
+  let degraded = false;
+  let degradationReason = null;
+  if (!orchestrationAvailable) {
+    degraded = true;
+    degradationReason = `Model could not be resolved; orchestration requires a runnable model — ${modelResolution.error?.reason || 'no model available'}.`;
+  } else if (requestedStrategy === 'orchestrated') {
+    degraded = true;
+    degradationReason = `Orchestration was requested but no orchestration plan is available${workflowType ? ` for workflowType "${workflowType}"` : ''}.`;
+  }
+
+  return {
+    ...base,
+    executionMode: 'construct-prompt-only',
+    effectiveStrategy: 'prompt-only',
+    constructCapabilitiesActive: [...PROMPT_ONLY_CAPS],
+    degraded,
+    degradationReason,
+  };
+}
+
+function stripWarnings(result) {
+  const { warnings, ...rest } = result || {};
+  return rest;
+}

package/lib/embedded-contract/index.mjs

@@ -12,9 +12,11 @@ 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';
+import { resolveExecution as resolveExecutionCore } from './execution.mjs';
 
 export { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION, isClientCompatible } from './contract-version.mjs';
 export { APPROVAL_MODES } from './audit.mjs';
+export { EXECUTION_MODES, CONSTRUCT_STRATEGIES, CONSTRUCT_CAPABILITIES } from './execution.mjs';
 
 // File→text resolution for SDK callers: extract a path through the real
 // pipeline (docling/whisper/transcript), then pass { text, ingestion } to
@@ -69,3 +71,17 @@ export async function invokeWorkflow(request = {}, { env, cwd } = {}) {
 export function describeCapabilities({ env, cwd, rootDir } = {}) {
   return wrapContractResult(buildCapabilityContract({ env, rootDir }), { surface: 'sdk', env, cwd });
 }
+
+/**
+ * Resolve the execution-capability contract for an embedded workflow: the
+ * executionMode, the contributed Construct capabilities, and any degradation
+ * with a reason. Returns a versioned envelope; the resolution is under `.data`.
+ * Read-only; performs no model call beyond model resolution.
+ *
+ * @param {object} request   See execution.mjs resolveExecution.
+ * @param {object} [opts]     { env, cwd, registryPath }
+ * @returns {object}
+ */
+export function resolveExecution(request = {}, { env, cwd, registryPath } = {}) {
+  return wrapContractResult(resolveExecutionCore(request, { env, cwd, registryPath }), { surface: 'sdk', env, cwd });
+}