@geraldmaron/construct 1.0.19 → 1.0.21

package/README.md

@@ -159,9 +159,11 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 |---|---|
 | `construct capability` | Describe what this Construct install can do (embedded contract; read-only, secret-free) |
 | `construct claude:allow` | Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it) |
+| `construct execution` | Resolve the execution-capability contract for an embedded workflow (orchestrated vs prompt-only; descriptive, not enforced) |
 | `construct hosts` | Show host support for Construct orchestration |
 | `construct mcp` | Manage MCP integrations |
 | `construct models` | Show or update model tier assignments |
+| `construct orchestrate` | Construct-owned local orchestration runtime (Mode-A: single-process, filesystem-backed, no Docker) |
 | `construct plugin` | Manage external Construct plugin manifests |
 
 ### Integrations

package/bin/construct

@@ -3335,6 +3335,83 @@ async function cmdValidate() {
   process.exit(1);
 }
 
+async function cmdExecution(args) {
+  if (args[0] === 'resolve') {
+    const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
+    const { resolveExecution } = await import('../lib/embedded-contract/execution.mjs');
+    const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
+    const request = {
+      workflowType: flag('--workflow-type'),
+      requestedStrategy: flag('--strategy'),
+      useConstruct: !args.includes('--no-construct'),
+      host: flag('--host'),
+      hostModel: flag('--host-model'),
+      hostProvider: flag('--host-provider'),
+      requestedTier: flag('--tier'),
+      capabilities: flag('--capabilities')?.split(',').map((s) => s.trim()).filter(Boolean),
+      allowCrossProviderFallback: args.includes('--allow-cross-provider'),
+    };
+    const envelope = wrapContractResult(resolveExecution(request), { surface: 'cli' });
+    println(JSON.stringify(envelope, null, 2));
+    return;
+  }
+  println('Usage: construct execution resolve [--workflow-type T] [--strategy orchestrated|prompt-only|auto] [--host-model M] [--host-provider P] [--tier reasoning|standard|fast] [--no-construct] [--allow-cross-provider] [--json]');
+}
+
+async function cmdOrchestrate(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const flag = (name) => { const i = rest.indexOf(name); return i !== -1 ? rest[i + 1] : undefined; };
+  const wantsJson = rest.includes('--json') || args.includes('--json');
+
+  if (sub === 'run') {
+    const { runOrchestration, planRun, hostAdapterMetadata } = await import('../lib/orchestration/runtime.mjs');
+    const positional = rest.filter((a, i) => !a.startsWith('--') && !(i > 0 && rest[i - 1].startsWith('--') && !['--no-construct', '--no-execute', '--json'].includes(rest[i - 1])));
+    const text = flag('--text') || positional.join(' ').trim();
+    if (!text) { errorln('Usage: construct orchestrate run "<request>" [--workflow-type T] [--strategy orchestrated|prompt-only|auto] [--host H] [--host-model M] [--no-construct] [--no-execute] [--json]'); process.exit(1); }
+    const request = {
+      request: text,
+      workflowType: flag('--workflow-type'),
+      requestedStrategy: flag('--strategy') || 'auto',
+      useConstruct: !rest.includes('--no-construct'),
+      host: flag('--host'),
+      hostModel: flag('--host-model'),
+      hostProvider: flag('--host-provider'),
+      fileCount: Number(flag('--file-count') || 0),
+      moduleCount: Number(flag('--module-count') || 0),
+    };
+    const run = rest.includes('--no-execute') ? await planRun(request, {}) : await runOrchestration(request, {});
+    if (wantsJson) { println(JSON.stringify(hostAdapterMetadata(run), null, 2)); return; }
+    println(`Run ${run.runId} — ${run.status} · executionMode=${run.execution.executionMode} · backend=${run.workerBackend} · hostRole=${run.hostRole}`);
+    if (run.execution.degraded) println(`  degraded: ${run.execution.degradationReason}`);
+    if (run.tasks.length) println(`  tasks: ${run.tasks.map((t) => `${t.role}(${t.status})`).join(' → ')}`);
+    else println('  tasks: none (no Construct-owned specialist sequence for this execution mode)');
+    return;
+  }
+
+  if (sub === 'status') {
+    const { getRun, getRuns, hostAdapterMetadata } = await import('../lib/orchestration/runtime.mjs');
+    const runId = rest.find((a) => !a.startsWith('--'));
+    if (runId) {
+      const run = await getRun(process.cwd(), runId);
+      if (!run) { errorln(`Run not found: ${runId}`); process.exit(1); }
+      if (wantsJson) { println(JSON.stringify(hostAdapterMetadata(run), null, 2)); return; }
+      println(`Run ${run.runId} — ${run.status} · executionMode=${run.execution.executionMode}`);
+      for (const t of run.tasks) println(`  ${t.id} ${t.role} — ${t.status}`);
+      return;
+    }
+    const runs = await getRuns(process.cwd());
+    if (wantsJson) { println(JSON.stringify(runs, null, 2)); return; }
+    if (!runs.length) { println('No orchestration runs recorded.'); return; }
+    for (const r of runs) println(`  ${r.runId} — ${r.status} · ${r.executionMode || ''} · ${r.createdAt}`);
+    return;
+  }
+
+  println('Usage: construct orchestrate <run|status> [options]');
+  println('  run "<request>" [--workflow-type T] [--strategy S] [--host H] [--host-model M] [--no-construct] [--no-execute] [--json]');
+  println('  status [run-id] [--json]');
+}
+
 async function cmdModels(args) {
   if (args[0] === 'resolve') {
     const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
@@ -5040,6 +5117,8 @@ const handlers = new Map([
   ['docs:reconcile', cmdDocsReconcile],
   ['init:update', cmdInitUpdate],
   ['models', cmdModels],
+  ['execution', cmdExecution],
+  ['orchestrate', cmdOrchestrate],
   ['beads:stats', async (args) => {
     const { getContentionStats, getHumanStatus } = await import('../lib/beads-optimistic.mjs');
     const jsonOutput = args.includes('--json');

package/lib/cli-commands.mjs

@@ -250,7 +250,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Convert documents to indexed markdown',
-    usage: 'construct ingest <file> [--strict] [--legacy-extractor]',
+    usage: 'construct ingest <file> [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--strict] [--legacy-extractor]',
   },
   {
     name: 'infer',
@@ -323,6 +323,29 @@ export const CLI_COMMANDS = [
       { name: 'describe --json', desc: 'Emit versions, interfaces, roles, skills, workflows, schemas, models, policies, telemetry, plugins' },
     ],
   },
+  {
+    name: 'execution',
+    emoji: '🪢',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Resolve the execution-capability contract for an embedded workflow (orchestrated vs prompt-only; descriptive, not enforced)',
+    usage: 'construct execution resolve --json',
+    subcommands: [
+      { name: 'resolve --json', desc: 'Report executionMode, active Construct capabilities, and any degradation given host/strategy context' },
+    ],
+  },
+  {
+    name: 'orchestrate',
+    emoji: '🎼',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Construct-owned local orchestration runtime (Mode-A: single-process, filesystem-backed, no Docker)',
+    usage: 'construct orchestrate <run|status> [options]',
+    subcommands: [
+      { name: 'run "<request>" [--strategy S] [--host H] [--no-construct] [--no-execute] [--json]', desc: 'Plan and run a request through a Construct-owned specialist chain; returns host-adapter metadata' },
+      { name: 'status [run-id] [--json]', desc: 'Inspect a run, or list recent runs' },
+    ],
+  },
   {
     name: 'mcp',
     emoji: '🔌',

package/lib/config/schema.mjs

@@ -5,7 +5,7 @@
  * AJV/zod to keep Construct dependency-free at startup — the loader runs
  * before npm install completes in some bootstrap paths.
  *
- * Schema v1 covers: alias, deployment, providers, autoEmbed, telemetry.
+ * Schema v1 covers: alias, deployment, providers, autoEmbed, ingest, telemetry.
  * Tier model selection lives in `specialists/registry.json` only — this config
  * file is intentionally not a second edit surface for model assignments.
  * Later phases (6, 7b) extend it with `resources` and `costs` blocks
@@ -24,6 +24,18 @@ export const DEFAULT_PROFILE_ID = 'rnd';
 
 export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cursor'];
 
+export const INGEST_STRATEGIES = ['adapter', 'provider'];
+export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
+export const INGEST_ORCHESTRATIONS = ['prompt-only', 'orchestrated'];
+
+export const ORCHESTRATION_WORKER_BACKENDS = ['inline', 'provider'];
+export const ORCHESTRATION_STORES = ['filesystem', 'sqlite', 'postgres'];
+
+// SessionStart context routing. `auto` keeps the rich payload on stdout for
+// interactive sessions and suppresses it (to a debug log) for non-interactive /
+// SDK invocations, so a one-shot command's stdout stays reserved for its output.
+export const HOOK_OUTPUT_MODES = ['auto', 'silent', 'stderr', 'stdout'];
+
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
   alias: 'Construct',
@@ -36,9 +48,21 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   providers: Object.freeze({}),
   profile: DEFAULT_PROFILE_ID,
   autoEmbed: false,
+  ingest: Object.freeze({
+    strategy: 'adapter',
+    fallback: 'none',
+    orchestration: 'prompt-only',
+  }),
+  orchestration: Object.freeze({
+    workerBackend: 'inline',
+    store: 'filesystem',
+  }),
   telemetry: Object.freeze({
     enabled: true,
   }),
+  hooks: Object.freeze({
+    outputMode: 'auto',
+  }),
   roleSelection: Object.freeze({
     primary: null,
     secondary: null,
@@ -84,6 +108,23 @@ export const FIELD_RULES = {
   providers: { type: 'object', required: false },
   profile: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
+  ingest: {
+    type: 'object',
+    required: false,
+    fields: {
+      strategy: { type: 'string', enum: INGEST_STRATEGIES },
+      fallback: { type: 'string', enum: INGEST_FALLBACKS },
+      orchestration: { type: 'string', enum: INGEST_ORCHESTRATIONS },
+    },
+  },
+  orchestration: {
+    type: 'object',
+    required: false,
+    fields: {
+      workerBackend: { type: 'string', enum: ORCHESTRATION_WORKER_BACKENDS },
+      store: { type: 'string', enum: ORCHESTRATION_STORES },
+    },
+  },
   telemetry: {
     type: 'object',
     required: false,
@@ -91,6 +132,13 @@ export const FIELD_RULES = {
       enabled: { type: 'boolean' },
     },
   },
+  hooks: {
+    type: 'object',
+    required: false,
+    fields: {
+      outputMode: { type: 'string', enum: HOOK_OUTPUT_MODES },
+    },
+  },
   roleSelection: {
     type: 'object',
     required: false,

package/lib/decisions/enforced-baseline.json

@@ -4,6 +4,9 @@
     "ADR-0016",
     "ADR-0017",
     "ADR-0018",
+    "ADR-0019",
+    "ADR-0020",
+    "ADR-0021",
     "any-to-business-strategist",
     "any-to-explorer",
     "architect-to-data-engineer",

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, INGEST_ORCHESTRATION_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,8 @@ export async function ingestDocuments(inputPaths, {
   sync = false,
   strict = false,
   highFidelity = true,
+  strategy = null,
+  orchestration = null,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -143,12 +182,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, orchestrationOverride: orchestration, cwd });
+
   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 +264,15 @@ 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,
+      orchestration: resolvedStrategy.orchestration,
+      model: resolvedStrategy.model,
+      provider: resolvedStrategy.provider,
+      fallbackApplied,
+      execution: resolvedStrategy.execution,
+    },
   };
 }
 
@@ -224,26 +284,40 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let sync = false;
   let strict = false;
   let highFidelity = true;
+  let strategy = null;
+  let orchestration = 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.startsWith('--orchestration=')) orchestration = arg.split('=').slice(1).join('=');
     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] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--legacy-extractor]\n` +
+      `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
+      `  --orchestration: prompt-only (deterministic extraction) or orchestrated (engage the specialist chain)\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(', ')}`);
+  }
+  if (orchestration !== null && !INGEST_ORCHESTRATION_STRATEGIES.includes(orchestration)) {
+    throw new Error(`Unsupported orchestration: ${orchestration}. Valid values: ${INGEST_ORCHESTRATION_STRATEGIES.join(', ')}`);
+  }
   const knowledgeTargets = KNOWLEDGE_SUBDIRS.map((s) => `knowledge/${s}`);
   if (!['sibling', ...knowledgeTargets].includes(target)) {
     throw new Error(
@@ -251,5 +325,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, orchestration: orchestration || null, env });
 }

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 });
+}