@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/document-ingest.mjs

@@ -9,7 +9,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
-import { extractDocumentText, extractDocumentTextAsync, extractDocumentTextNodeNative, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
+import { extractDocumentTextAsync, extractDocumentTextNodeNative, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
@@ -157,9 +157,9 @@ function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
 // can stall (a large PDF, a slow model download) or fail. Without a bound the
 // caller hangs: the CLI never returns, and the ingest_document MCP tool blocks
 // until the client times out and surfaces an opaque error. Bound the whole
-// docling attempt and fall back to the legacy extractor so ingest always returns
-// a usable result, with the fallback recorded in droppedInfo. Override the bound
-// with CONSTRUCT_DOCLING_TIMEOUT_MS (0 disables the timeout).
+// docling attempt and fall back to the node-native extractor so ingest always
+// returns a usable result, with the fallback recorded in droppedInfo. Override
+// the bound with CONSTRUCT_DOCLING_TIMEOUT_MS (0 disables the timeout).
 
 const DOCLING_TIMEOUT_MS = (() => {
   const raw = Number(process.env.CONSTRUCT_DOCLING_TIMEOUT_MS);
@@ -176,15 +176,15 @@ export function withTimeout(promise, ms, onTimeoutMessage) {
 
 /**
  * Run the high-fidelity (docling) extractor with a bound, falling back to the
- * legacy extractor on timeout or any failure so a caller never hangs. The
+ * node-native extractor on timeout or any failure so a caller never hangs. The
  * extractor functions are injectable for testing; production uses the real
- * docling-async and legacy-sync extractors.
+ * docling-async and node-native extractors.
  */
 export async function extractWithDoclingFallback(sourcePath, {
   maxChars = null,
   timeoutMs = DOCLING_TIMEOUT_MS,
   asyncExtract = extractDocumentTextAsync,
-  syncExtract = extractDocumentText,
+  nodeNativeExtract = extractDocumentTextNodeNative,
 } = {}) {
   try {
     return await withTimeout(
@@ -193,24 +193,23 @@ export async function extractWithDoclingFallback(sourcePath, {
       `docling extraction exceeded ${Math.round(timeoutMs / 1000)}s`,
     );
   } catch (err) {
-    const legacy = syncExtract(sourcePath, { maxChars });
-    legacy.droppedInfo = [
-      ...(legacy.droppedInfo ?? []),
+    const fallback = await nodeNativeExtract(sourcePath, { maxChars });
+    fallback.droppedInfo = [
+      ...(fallback.droppedInfo ?? []),
       {
         kind: 'docling-fallback',
         count: 1,
-        reason: `High-fidelity (docling) extraction failed or timed out (${err.message}); used the legacy extractor. Re-run after \`construct install --with-docling\`, or pass --legacy-extractor to skip docling.`,
+        reason: `High-fidelity (docling) extraction failed or timed out (${err.message}); used the node-native extractor. Re-run after \`construct install --with-docling\`, or pass --fidelity=fast to skip docling.`,
         recoverable: true,
       },
     ];
-    return legacy;
+    return fallback;
   }
 }
 
 // The default adapter path prefers the Node-native extractor (unpdf/mammoth) so
-// plain PDF/DOCX ingest needs no Python venv; it self-degrades to the sync
-// system-binary extractor when the optional dep is absent. High-fidelity stays
-// on docling, reserved for scanned/layout-critical and audio/video.
+// plain PDF/DOCX ingest needs no Python venv; high-fidelity stays on docling for
+// scanned/layout-critical content and formats without a Node backend.
 
 function extractViaAdapter(sourcePath, { highFidelity, maxChars }) {
   return highFidelity
@@ -354,6 +353,7 @@ export async function ingestDocuments(inputPaths, {
     droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
     droppedCount: totalDrops,
     highFidelity,
+    fidelity: highFidelity ? 'high' : 'fast',
     ingestion: {
       strategy: resolvedStrategy.strategy,
       fallback: resolvedStrategy.fallback,
@@ -373,7 +373,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let target = 'knowledge/internal';
   let sync = false;
   let strict = false;
-  let highFidelity = true;
+  let fidelity = 'high';
   let strategy = null;
   let orchestration = null;
 
@@ -384,21 +384,30 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     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.startsWith('--fidelity=')) {
+      const value = arg.split('=').slice(1).join('=');
+      if (value !== 'fast' && value !== 'high') {
+        throw new Error(`Unsupported fidelity: ${value}. Valid values: fast, high`);
+      }
+      fidelity = value;
+    } else if (arg === '--sync') sync = true;
     else if (arg === '--strict') strict = true;
-    else if (arg === '--legacy-extractor') highFidelity = false;
+    else if (arg === '--legacy-extractor') fidelity = 'fast';
     else if (strategy === '') strategy = arg;
     else inputs.push(arg);
   }
 
+  const highFidelity = fidelity === 'high';
+
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--legacy-extractor]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--fidelity=fast|high]\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` +
+      `  --fidelity=fast|high: fast = node-native extractors; high = docling (default)\n` +
+      `  --legacy-extractor: deprecated alias for --fidelity=fast\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }

package/lib/embed/cli.mjs

@@ -392,9 +392,9 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   const { loadEmbedConfig, EMPTY_CONFIG } = await import('./config.mjs');
   const { SnapshotEngine, renderMarkdown } = await import('./snapshot.mjs');
   const { ProviderRegistry } = await import('./providers/registry.mjs');
-  const { loadConstructEnv } = await import('../env-config.mjs');
+  const { prepareConstructEnv } = await import('../runtime-env.mjs');
 
-  const env = loadConstructEnv();
+  const env = prepareConstructEnv();
   const registry = await ProviderRegistry.fromEnv(env);
 
   let cfg;

package/lib/embed/daemon.mjs

@@ -58,54 +58,11 @@ function logCatch(source, err) {
 }
 
 /**
- * Resolve an LLM API key from multiple sources: env → config.env → ~/.env → shell rc.
- * Supports 1Password op:// refs in .zshrc or other shell config files for the
- * telemetry-generation probe.
+ * Resolve an LLM API key via the shared secret resolver (cached op read per process).
  */
 async function resolveLLMKey(varName, env) {
-  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
-  const homeDir = homedir();
-  const files = [join(homeDir, '.construct', 'config.env'), join(homeDir, '.env')];
-  for (const file of files) {
-    try {
-      if (!existsSync(file)) continue;
-      const content = readFileSync(file, 'utf8');
-      const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
-      if (m && m[1]) return m[1].trim();
-    } catch { /* skip */ }
-  }
-  // Check shell rc files for exports and command substitutions (including op:// refs)
-  const rcs = [join(homeDir, '.zshrc'), join(homeDir, '.bashrc'), join(homeDir, '.bash_profile'), join(homeDir, '.profile')];
-  const { spawnSync } = await import('child_process');
-  for (const rc of rcs) {
-    if (!existsSync(rc)) continue;
-    try {
-      const content = readFileSync(rc, 'utf8');
-
-      // op:// ref via 1Password CLI
-      const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
-      const opMatch = content.match(opRe);
-      if (opMatch) {
-        try {
-          const r = spawnSync('op', ['read', opMatch[1]], { encoding: 'utf8', timeout: 5000 });
-          if (r.status === 0 && r.stdout?.trim()) return r.stdout.trim();
-        } catch { /* op read failed */ }
-      }
-
-      // Source the rc file and echo — handles any $(...) command substitution
-      const anyExportRe = new RegExp(`^\\s*export\\s+${varName}=`, 'm');
-      if (anyExportRe.test(content)) {
-        try {
-          const r = spawnSync('zsh', ['-c', `source "${rc}" 2>/dev/null; echo "\${${varName}}"`], { encoding: 'utf8', timeout: 5000 });
-          if (r.status === 0 && r.stdout?.trim()) {
-            const val = r.stdout.trim().split('\n').pop()?.trim();
-            if (val && !val.includes('ERROR') && !val.includes('op read') && !val.startsWith('$(')) return val;
-          }
-        } catch { /* shell eval failed */ }
-      }
-    } catch { /* skip */ }
-  }
-  return null;
+  const { resolveSecret } = await import('../providers/secret-resolver.mjs');
+  return resolveSecret(varName, { env, cwd: process.cwd() });
 }
 
 // ─── Root dir resolution ─────────────────────────────────────────────────────
@@ -614,6 +571,21 @@ export class EmbedDaemon {
       { runImmediately: true },
     );
 
+    // ── Job 7: rss-cap ────────────────────────────────────────────────────────
+    const { memoryCapMbFor, rssOverCap, currentRssMb } = await import('../resources/process-budget.mjs');
+    const rssCapMb = memoryCapMbFor('embed-daemon', this.#rootDir, this.#env);
+    this.#scheduler.register(
+      'rss-cap',
+      60_000,
+      async () => {
+        if (!rssOverCap(rssCapMb)) return;
+        process.stderr.write(
+          `[embed] RSS ${Math.round(currentRssMb())}MB exceeds cap ${rssCapMb}MB — stopping daemon\n`,
+        );
+        this.stop();
+      },
+    );
+
     // ── Job 0: telemetry-setup ───────────────────────────────────────────────────
 // On startup — ensure annotation queues and eval configs exist (idempotent)
 this.#scheduler.register(

package/lib/embed/worker.mjs

@@ -8,7 +8,7 @@
 
 import os from 'node:os';
 import path from 'node:path';
-import { loadConstructEnv } from '../env-config.mjs';
+import { prepareConstructEnv } from '../runtime-env.mjs';
 import { EmbedDaemon } from './daemon.mjs';
 
 function parseArgv(argv) {
@@ -19,7 +19,7 @@ function parseArgv(argv) {
 }
 
 const configPath = parseArgv(process.argv.slice(2));
-const env = loadConstructEnv();
+const env = prepareConstructEnv();
 
 // If no config file, build an auto-discovered config inline and inject it
 let daemonOpts = { env };

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

@@ -61,15 +61,15 @@ function matchCapabilities(modelId, requested, warnings) {
   return matched;
 }
 
-function familyByProvider(hostProvider, env) {
+function familyByProvider(hostProvider, env, allowAmbient) {
   if (!hostProvider || typeof hostProvider !== 'string') return null;
-  const families = listModelFamilies({ env });
+  const families = listModelFamilies({ env, allowAmbient });
   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 }) {
+function success({ selectedModel, family, tier, resolutionSource, fallbackReason = null, tierSource = null, capabilities, warnings, env, allowAmbient }) {
   return {
     selectedModel,
     selectedProvider: family ? family.id : null,
@@ -123,28 +123,28 @@ function configError({ tier, reason, remediation, warnings }) {
  * @param {string} [opts.registryPath]
  * @returns {object}
  */
-export function resolveEmbeddedModel(request = {}, { env = process.env, registryPath = null } = {}) {
+export function resolveEmbeddedModel(request = {}, { env = process.env, registryPath = null, allowAmbient = env === process.env } = {}) {
   const { workflowType, requestedTier, hostModel, hostProvider, capabilities, allowCrossProviderFallback = false } = request;
   const tier = resolveTier({ requestedTier, workflowType });
   const warnings = [];
 
-  const hostFamily = hostModel ? describeModelFamily(hostModel, { env }) : null;
+  const hostFamily = hostModel ? describeModelFamily(hostModel, { env, allowAmbient }) : null;
 
   if (hostModel && hostFamily) {
-    return success({ selectedModel: hostModel, family: hostFamily, tier, resolutionSource: 'host-model', capabilities, warnings, env });
+    return success({ selectedModel: hostModel, family: hostFamily, tier, resolutionSource: 'host-model', capabilities, warnings, env, allowAmbient });
   }
   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);
+  const family = hostFamily || familyByProvider(hostProvider, env, allowAmbient);
   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 });
+      return success({ selectedModel: model, family, tier, resolutionSource: 'same-family-fallback', fallbackReason, capabilities, warnings, env, allowAmbient });
     }
   }
 
@@ -166,7 +166,7 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
       : 'No host context supplied; used the Construct tier default.';
     return success({
       selectedModel: defaultModel,
-      family: describeModelFamily(defaultModel, { env }),
+      family: describeModelFamily(defaultModel, { env, allowAmbient }),
       tier,
       resolutionSource: 'tier-default',
       fallbackReason,
@@ -174,6 +174,7 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
       capabilities,
       warnings,
       env,
+      allowAmbient,
     });
   }
 

package/lib/env-config.mjs

@@ -8,6 +8,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { API_KEY_CREDENTIALS } from './providers/credential-catalog.mjs';
+import { extractOpRef } from './providers/secret-resolver.mjs';
 
 export function parseEnvFile(filePath) {
   if (!filePath || !fs.existsSync(filePath)) return {};
@@ -88,6 +90,22 @@ const ENV_SHADOW_WARN = new Set([
   'CONSTRUCT_DEPLOYMENT_MODE',
 ]);
 
+const CREDENTIAL_ENV_KEYS = new Set(
+  API_KEY_CREDENTIALS.flatMap((entry) => entry.envVars),
+);
+
+function isOpReference(value) {
+  return Boolean(extractOpRef(value));
+}
+
+function preferInjectedCredential(envValue, fileValue) {
+  return Boolean(
+    envValue
+    && !isOpReference(envValue)
+    && isOpReference(fileValue),
+  );
+}
+
 export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = process.env, warn = true } = {}) {
   const rootEnv = rootDir ? parseEnvFile(path.join(rootDir, '.env')) : {};
   const userEnv = parseEnvFile(getUserEnvPath(homeDir));
@@ -103,6 +121,7 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
       // silently and no user action is needed.
       if (!env[key]) continue;
       if (key in fileEnv && fileEnv[key] !== env[key]) {
+        if (preferInjectedCredential(env[key], fileEnv[key])) continue;
         process.stderr.write(
           `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) ` +
           `differs from config.env value (${fileEnv[key].slice(0, 6)}…). ` +
@@ -115,7 +134,14 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
 
   // process.env is the base; config.env (file) values override shell values
   // so that credentials set in the dashboard always win over stale shell exports.
+  // Materialized credentials from `op run` (or an explicit export) win over stored
+  // op:// references so one 1Password auth per invocation is enough.
   const merged = { ...env, ...fileEnv };
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    if (preferInjectedCredential(env[key], fileEnv[key])) {
+      merged[key] = env[key];
+    }
+  }
   const databaseUrl = resolveDatabaseUrl(merged);
   if (databaseUrl && !cleanEnvValue(merged.DATABASE_URL)) {
     merged.DATABASE_URL = databaseUrl;

package/lib/evals/dataset.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/evals/dataset.mjs — provenance-backed evaluation dataset: validation,
+ * leakage-safe splitting, expiry, and held-out selection (construct-6zga.1.6).
+ *
+ * A dataset item carries the provenance the governed improvement loop needs to
+ * evaluate a candidate on data it did not generate: source trace ids, human-label
+ * provenance, redaction state, a capability snapshot, the allowed tools, the
+ * expected evidence and contract behavior, a split assignment, and an expiry.
+ * Split assignment is deterministic and keyed on task family plus source trace, so
+ * every item from one trace lands in the same split — a candidate's generating
+ * trace can never leak across the train/dev/test boundary. selectEvalSet then
+ * strips the generating trace, near-duplicates, and the same user correction from
+ * the evaluation set so a candidate is never scored on its own origin. Reference
+ * shape: schemas/eval-dataset.schema.json.
+ */
+import crypto from 'node:crypto';
+
+export const EVAL_DATASET_SCHEMA_VERSION = 1;
+
+export const DATASET_SPLITS = Object.freeze(['train', 'dev', 'test']);
+export const REDACTION_STATES = Object.freeze(['raw', 'redacted', 'synthetic']);
+export const EVIDENCE_REQUIREMENTS = Object.freeze(['none', 'preferred', 'required']);
+export const LABEL_PROVENANCE = Object.freeze(['human', 'model-assisted', 'unlabeled']);
+export const CONTRACT_OUTCOMES = Object.freeze(['pass', 'fail', 'blocker', 'handoff']);
+export const CAPABILITY_CLASSES = Object.freeze(['hosted-direct', 'hosted-routed', 'local-capable', 'local-constrained', 'unknown']);
+
+function hashBucket(text) {
+  const digest = crypto.createHash('sha256').update(String(text)).digest();
+  return digest.readUInt32BE(0) % 100;
+}
+
+function normalizePrompt(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function promptOf(item) {
+  return item?.taskInput?.prompt ?? item?.prompt ?? '';
+}
+
+export function nearDuplicateKey(item) {
+  const normalized = normalizePrompt(promptOf(item));
+  if (!normalized) return null;
+  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+
+function primarySourceTrace(item) {
+  return Array.isArray(item?.sourceTraceIds) && item.sourceTraceIds.length ? item.sourceTraceIds[0] : null;
+}
+
+/**
+ * Deterministically assign a split. The bucket is keyed on task family plus the
+ * item's primary source trace, so all items sharing a trace co-locate in one
+ * split. devRatio/testRatio are fractions of the bucket space; the remainder is
+ * train.
+ */
+export function assignSplit(item, { devRatio = 0.15, testRatio = 0.15 } = {}) {
+  const trace = primarySourceTrace(item) || item?.id || '';
+  const bucket = hashBucket(`${item?.taskFamily || ''}:${trace}`);
+  const testCut = Math.round(testRatio * 100);
+  const devCut = testCut + Math.round(devRatio * 100);
+  if (bucket < testCut) return 'test';
+  if (bucket < devCut) return 'dev';
+  return 'train';
+}
+
+export function isExpired(item, nowIso) {
+  if (!item?.expiry || !nowIso) return false;
+  return String(item.expiry) <= String(nowIso);
+}
+
+/**
+ * Strip every item that would leak into a candidate's evaluation: the candidate's
+ * own generating / source traces, a near-duplicate task input, and the same user
+ * correction. This is the held-out guarantee (construct-6zga.1.6 AC2).
+ */
+export function excludeLeakage(items, candidate = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const generatingTraces = new Set([
+    ...(Array.isArray(candidate.generatingTraceIds) ? candidate.generatingTraceIds : []),
+    ...(Array.isArray(candidate.sourceTraceIds) ? candidate.sourceTraceIds : []),
+  ]);
+  const candidateDupKey = nearDuplicateKey(candidate);
+  const candidateCorrection = candidate.correctionId ?? candidate.humanLabel?.correctionId ?? null;
+
+  return list.filter((item) => {
+    const traces = Array.isArray(item?.sourceTraceIds) ? item.sourceTraceIds : [];
+    if (traces.some((t) => generatingTraces.has(t))) return false;
+    if (candidateDupKey && nearDuplicateKey(item) === candidateDupKey) return false;
+    const correction = item?.humanLabel?.correctionId ?? null;
+    if (candidateCorrection && correction && correction === candidateCorrection) return false;
+    return true;
+  });
+}
+
+/**
+ * Build the evaluation set for a candidate: the items in the requested split,
+ * minus expired items, minus anything that would leak (excludeLeakage).
+ */
+export function selectEvalSet(items, candidate = {}, { split = 'test', nowIso = null } = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const inSplit = list.filter((item) => item?.split === split && !isExpired(item, nowIso));
+  return excludeLeakage(inSplit, candidate);
+}
+
+/**
+ * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
+ * Returns { valid, errors } against schemas/eval-dataset.schema.json.
+ */
+export function validateDatasetItem(item) {
+  const errors = [];
+  if (!item || typeof item !== 'object') return { valid: false, errors: ['item is not an object'] };
+  if (item.schemaVersion !== EVAL_DATASET_SCHEMA_VERSION) errors.push(`schemaVersion must be ${EVAL_DATASET_SCHEMA_VERSION}`);
+  if (typeof item.id !== 'string' || !item.id) errors.push('id required');
+  if (typeof item.taskFamily !== 'string' || !item.taskFamily) errors.push('taskFamily required');
+  if (!item.taskInput || typeof item.taskInput.prompt !== 'string') errors.push('taskInput.prompt required');
+
+  if (!item.capabilitySnapshot || !CAPABILITY_CLASSES.includes(item.capabilitySnapshot.capabilityClass)) {
+    errors.push('capabilitySnapshot.capabilityClass invalid');
+  }
+  if (!Array.isArray(item.allowedTools)) errors.push('allowedTools must be an array');
+
+  const ev = item.expectedEvidenceBehavior;
+  if (!ev || !EVIDENCE_REQUIREMENTS.includes(ev.requirement) || typeof ev.citationsRequired !== 'boolean') {
+    errors.push('expectedEvidenceBehavior invalid');
+  }
+  if (!item.expectedContractResult || !CONTRACT_OUTCOMES.includes(item.expectedContractResult.outcome)) {
+    errors.push('expectedContractResult.outcome invalid');
+  }
+  if (!item.redaction || !REDACTION_STATES.includes(item.redaction.state)) errors.push('redaction.state invalid');
+
+  if (!Array.isArray(item.sourceTraceIds) || item.sourceTraceIds.length < 1) errors.push('sourceTraceIds must be non-empty');
+  if (!item.humanLabel || !LABEL_PROVENANCE.includes(item.humanLabel.provenance)) errors.push('humanLabel.provenance invalid');
+  if (!DATASET_SPLITS.includes(item.split)) errors.push(`split invalid: ${item.split}`);
+  if (item.expiry !== null && typeof item.expiry !== 'string') errors.push('expiry must be an ISO string or null');
+
+  return { valid: errors.length === 0, errors };
+}