@geraldmaron/construct 1.0.15 → 1.0.17

package/lib/contracts/validate.mjs

@@ -157,16 +157,24 @@ export function findContract({ producer, consumer, id, contractsPath = CONTRACTS
  * itself a contract violation (MCP best-practice 2025 — no silent skip on
  * tool-argument omission).
  */
-export function validateHandoff({
-  producer,
-  consumer,
-  id,
-  artifact,
-  packet,
-  contractsPath = CONTRACTS_PATH,
-  repoRoot = REPO_ROOT,
-  enforcement = 'block',
-}) {
+export function validateHandoff(opts = {}) {
+  const {
+    producer,
+    consumer,
+    id,
+    artifact,
+    packet,
+    contractsPath = CONTRACTS_PATH,
+    repoRoot = REPO_ROOT,
+    enforcement = 'block',
+  } = opts;
+  // Distinguish caller-supplied repoRoot from the default. Only an explicit
+  // repoRoot routes the violation log write — the default REPO_ROOT is for
+  // joining schema paths in this module, and forwarding it to the logger
+  // would override the cwd-based project-scope resolver that the test
+  // suite (and runtime project state) relies on.
+  const explicitRepoRoot = Object.prototype.hasOwnProperty.call(opts, 'repoRoot') ? repoRoot : undefined;
+
   const errors = [];
   const postconditionFailures = [];
 
@@ -193,6 +201,7 @@ export function validateHandoff({
       logViolation(`${producer}->${consumer}`, 'output', errors, packet ?? artifact, {
         verdict: postconditionFailures.length > 0 ? 'BLOCKED_CONTRACT' : 'CONTRACT_VIOLATION',
         postconditionFailures,
+        repoRoot: explicitRepoRoot,
       });
       return enforcement === 'block'
         ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`, ...errors], contract: null }
@@ -247,6 +256,7 @@ export function validateHandoff({
   logViolation(contract.id, 'output', errors, packet ?? artifact, {
     verdict,
     postconditionFailures,
+    repoRoot: explicitRepoRoot,
   });
 
   if (enforcement === 'block') return { ok: false, status: 'BLOCKED_CONTRACT', errors, contract };

package/lib/contracts/violation-log.mjs

@@ -39,10 +39,22 @@ const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 // cwd/HOME changes inside the same process (tests, harness reuse) route
 // correctly.
 
-function logFile() {
+function logFile(repoRoot) {
+  // Explicit repoRoot bypasses the marker-walk in resolveProjectScope: the
+  // caller has already decided the scope (test fixture, sandbox, embedded
+  // worktree). Without this, a fixture without a `.cx/` marker falls back
+  // to ~/.cx/ and pollutes the developer's home log.
+  if (repoRoot) return join(repoRoot, '.cx', 'contract-violations.jsonl');
   return resolveProjectScopedPath('contract-violations.jsonl', { ensureDir: false });
 }
 
+// Exposed for diagnostic surfaces (e.g. doctor) that need to print the
+// real path. Resolves on every call so cwd/HOME changes inside the same
+// process route correctly. `repoRoot` overrides cwd-based resolution so
+// callers running against a fixture (tests, sandboxes) can isolate their
+// log writes from the developer's project log.
+export function violationLogPath(repoRoot) { return logFile(repoRoot); }
+
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
 function readLastAgent() {
@@ -50,44 +62,47 @@ function readLastAgent() {
   catch { return 'construct'; }
 }
 
-function readTailRecord() {
-  const file = logFile();
+function readTailRecord(repoRoot) {
+  const file = logFile(repoRoot);
   const lastLine = readLastLineAcrossSegments(file);
   if (!lastLine) return null;
   try { return JSON.parse(lastLine); }
   catch { return null; }
 }
 
-function readPrevLineHash() {
-  const file = logFile();
+function readPrevLineHash(repoRoot) {
+  const file = logFile(repoRoot);
   const lastLine = readLastLineAcrossSegments(file);
   return lastLine ? sha256(lastLine) : null;
 }
 
-function nextSequence() {
-  const tail = readTailRecord();
+function nextSequence(repoRoot) {
+  const tail = readTailRecord(repoRoot);
   const prior = Number.isInteger(tail?.sequence) ? tail.sequence : 0;
   return prior + 1;
 }
 
 /**
  * Append a violation record. Best-effort: file I/O failures are swallowed
- * so logging never crashes the caller.
+ * so logging never crashes the caller. `extra.repoRoot` (extracted, not
+ * persisted) routes the write to a fixture log when callers run against
+ * a tmpdir — required for test isolation.
  */
 export function logViolation(contractId, direction, missing, packet, extra = {}) {
   try {
-    const file = logFile();
+    const { repoRoot, ...persistedExtra } = extra || {};
+    const file = logFile(repoRoot);
     mkdirSync(dirname(file), { recursive: true });
     const record = {
       ts: new Date().toISOString(),
-      sequence: nextSequence(),
+      sequence: nextSequence(repoRoot),
       agent: readLastAgent(),
       contractId,
       direction,
       missing,
       packet_keys: packet && typeof packet === 'object' ? Object.keys(packet) : null,
-      prev_line_hash: readPrevLineHash(),
-      ...extra,
+      prev_line_hash: readPrevLineHash(repoRoot),
+      ...persistedExtra,
     };
     appendBounded('contract-violations', file, JSON.stringify(record) + '\n');
   } catch { /* logging is best-effort */ }

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.' } };
+  }
+}