@ngockhoale/ukit 3.3.3 → 3.4.1

package/src/core/agentRuntime/context.js

@@ -1,4 +1,5 @@
-// Bounded runtime-context compiler (G5 / TASK-002).
+// Bounded runtime-context compiler (G5 / TASK-002) + subagent context
+// manifest builder (C89-006 / SPEC §7).
 // Pure module: no I/O, no runtimeConfig reads, no adapter/gate imports.
 // Compiles goal / verified state / evidence / memory records into a frozen
 // BoundedContext under a hard byte budget that includes framing and
@@ -10,7 +11,9 @@
 // ineligible records are excluded (omitted with the policy reason), and
 // eligible-but-unverified records are labeled 'unverified' and quoted —
 // never injected as instruction.
+import crypto from 'node:crypto';
 
+import { validateTaskContract } from './contract.js';
 import { eligible } from '../memory/policy.js';
 
 const STALE_MS = 15 * 60 * 1000; // default freshness window for evidence
@@ -147,3 +150,344 @@ export function compileRuntimeContext({
     }),
   };
 }
+
+// --- C89-006: subagent ContextManifest (SPEC §7, FR-05) ---------------------
+// `buildSubagentContext` selects isolated/curated context for a delegated
+// role from caller-supplied candidates and emits a traceable manifest:
+// every include/exclude carries reason + provenance + a deterministic token
+// estimate, required contract fields are never dropped by size pressure,
+// sensitive/secret refs are redacted before any retrieval runs, exact
+// duplicates collapse while keeping lineage (sourceRefs), and a requested
+// `fork` is honestly labeled `fork_unavailable` until a host probe proves
+// real state inheritance — a summary copy is never a fork.
+//
+// The builder stays pure: it performs no fs/config/adapter access itself.
+// Optional original verification is injected through `resolveOriginal`
+// (wired to eventStore.resolveRunArtifact by callers that need it);
+// persistence is eventStore.persistContextManifestRef, not this module.
+
+const MANIFEST_VERSION = 1;
+export const CONTEXT_MANIFEST_POLICY_VERSION = 'context-selection.v1';
+
+// Deterministic local estimator (chars/4, min 1) — matches the codebase
+// convention without importing the I/O-bearing token module.
+function estimateTokens(value) {
+  const text = String(value ?? '');
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+const isNonEmptyStr = (v) => typeof v === 'string' && v.length > 0;
+const isPlainRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// Fingerprint an item's content exactly (SPEC §7: exact dedupe only first —
+// semantic pruning is deferred). Items with no content fall back to the ref.
+function fingerprintOf(ref, text) {
+  const payload = text != null && text !== '' ? text : `<no-content:${ref}>`;
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+const KNOWN_MODES = Object.freeze(['isolated', 'curated', 'fork']);
+
+function forkCellStatus(hostCapabilities) {
+  return hostCapabilities?.capabilities?.fork?.status ?? null;
+}
+
+/**
+ * Assemble a subagent ContextManifest (SPEC §7).
+ *
+ * @param {object} args
+ * @param {object} args.taskContract TaskContract v1 (validateTaskContract
+ *   enforced at this boundary — a malformed contract gets no context).
+ * @param {string} args.role child role; defaults to taskContract.role.
+ * @param {string} [args.mode] 'isolated'|'curated'|'fork'; defaults to
+ *   taskContract.contextMode then 'curated'. 'fork' resolves
+ *   'fork_unavailable' unless hostCapabilities proves real inheritance.
+ * @param {Array<object>} [args.candidates] parent state/evidence/memory
+ *   candidates. Fields: ref, content|text, required, kind, audience,
+ *   sensitivity ('sensitive' → redacted), provenance, observedAt, ttlMs,
+ *   memoryRecord (routed through memory/policy eligible()), artifactRef
+ *   (resolved via resolveOriginal when supplied).
+ * @param {object} [args.hostCapabilities] probeSubagentCapabilities result.
+ * @param {object} [args.policyContext] {projectId, projectAliases,
+ *   includeUser} for memory eligible().
+ * @param {Function} [args.resolveOriginal] async (artifactRef) →
+ *   {ok:true,sha256?}|{status:'unavailable',reason} — injected resolver;
+ *   availability checks run AFTER sensitivity eligibility so secrets are
+ *   never fetched.
+ * @param {number} [args.budgetTokens] advisory cap: optional items that do
+ *   not fit are excluded 'over_budget'; required items are never dropped —
+ *   an exceedance flips manifest.overBudget instead (quality > budget).
+ * @param {string} [args.runId] parent run id; defaults taskContract.id.
+ * @param {number} [args.now] clock for staleness checks.
+ * @returns {Promise<{ok:true, mode:'isolated'|'curated'|'fork_unavailable'|'fork',
+ *   manifest:object, contextRefs:string[]}|{ok:false, code:string, errors?:string[]}>}
+ */
+export async function buildSubagentContext({
+  taskContract,
+  role,
+  mode,
+  candidates,
+  hostCapabilities,
+  policyContext = {},
+  resolveOriginal = null,
+  budgetTokens = null,
+  runId,
+  now,
+} = {}) {
+  if (taskContract === undefined || taskContract === null) {
+    return { ok: false, code: 'malformed_input' };
+  }
+  const contractVerdict = validateTaskContract(taskContract);
+  if (!contractVerdict.valid) {
+    return { ok: false, code: 'invalid_contract', errors: contractVerdict.errors };
+  }
+  if (candidates != null && !Array.isArray(candidates)) {
+    return { ok: false, code: 'malformed_input' };
+  }
+
+  const effectiveRole = isNonEmptyStr(role) ? role : taskContract.role;
+  const requestedMode = mode ?? taskContract.contextMode ?? 'curated';
+  if (!KNOWN_MODES.includes(requestedMode)) {
+    return { ok: false, code: 'malformed_input' };
+  }
+
+  // Fork honesty (SPEC §7): a real fork exists only where a host probe proves
+  // state inheritance; everything else is the curated fallback labeled
+  // 'fork_unavailable' — copying a short summary is never labeled fork.
+  const effectiveMode = requestedMode === 'fork'
+    ? (forkCellStatus(hostCapabilities) === 'supported' ? 'fork' : 'fork_unavailable')
+    : requestedMode;
+
+  const effectiveRunId = isNonEmptyStr(runId) ? runId : taskContract.id;
+  const nowMs = typeof now === 'number' ? now : Date.now();
+  const budget = Number.isInteger(budgetTokens) && budgetTokens >= 0
+    ? budgetTokens
+    : null;
+
+  const items = [];
+  const pushItem = (entry) => {
+    items.push(Object.freeze(entry));
+    return entry;
+  };
+  const exclude = (ref, reason, extra = {}) =>
+    pushItem({
+      ref,
+      included: false,
+      reason,
+      tokenEstimate: estimateTokens(extra.text ?? ref),
+      provenance: extra.provenance ?? 'unknown',
+      ...(extra.detail != null ? { detail: extra.detail } : {}),
+    });
+
+  // Required contract-derived items first: objective / scope / constraints /
+  // expectedOutput / stopConditions / evidenceRequirement / knownFacts are
+  // the acceptance boundary and are never droppable by size pressure.
+  const contractItem = (ref, text, provenance = 'task-contract') =>
+    pushItem({
+      ref,
+      included: true,
+      reason: 'required_contract',
+      tokenEstimate: estimateTokens(text),
+      provenance,
+      fingerprint: fingerprintOf(ref, text),
+    });
+
+  contractItem('contract:objective', taskContract.objective);
+  for (const [i, p] of (taskContract.scope?.include ?? []).entries()) {
+    contractItem(`contract:scope-include:${i}`, `scope include: ${p}`);
+  }
+  for (const [i, p] of (taskContract.scope?.exclude ?? []).entries()) {
+    contractItem(`contract:scope-exclude:${i}`, `scope exclude: ${p}`);
+  }
+  (taskContract.constraints ?? []).forEach((c, i) => {
+    contractItem(`contract:constraint:${i}`, `constraint: ${c}`);
+  });
+  contractItem('contract:expected-output', taskContract.expectedOutput);
+  if (taskContract.evidenceRequirement != null) {
+    contractItem('contract:evidence-requirement', taskContract.evidenceRequirement);
+  }
+  (taskContract.stopConditions ?? []).forEach((s, i) => {
+    contractItem(`contract:stop-condition:${i}`, `stop: ${s}`);
+  });
+  (taskContract.knownFacts ?? []).forEach((f, i) => {
+    contractItem(`contract:known-fact:${i}`, f.statement, f.source);
+  });
+
+  const memContext = {
+    projectId: isNonEmptyStr(policyContext.projectId) ? policyContext.projectId : null,
+    projectAliases: Array.isArray(policyContext.projectAliases)
+      ? policyContext.projectAliases
+      : undefined,
+    includeUser: policyContext.includeUser === true,
+    now: nowMs,
+  };
+
+  const seenFingerprints = new Map(); // fingerprint → first ref (lineage)
+  let tokensUsed = items.reduce((n, i) => n + i.tokenEstimate, 0);
+  let overBudget = budget != null && tokensUsed > budget;
+
+  for (const [idx, cand] of (candidates ?? []).entries()) {
+    const ref = isNonEmptyStr(cand?.ref) ? cand.ref : `candidate:${idx}`;
+    const provenance = isNonEmptyStr(cand?.provenance)
+      ? cand.provenance
+      : isNonEmptyStr(cand?.source) ? cand.source : 'unknown';
+    const text = typeof cand?.content === 'string' ? cand.content
+      : typeof cand?.text === 'string' ? cand.text : null;
+    const tokenEstimate = estimateTokens(text ?? ref);
+
+    if (!isPlainRec(cand) || !isNonEmptyStr(cand.ref)) {
+      exclude(ref, 'malformed_candidate', { text, provenance });
+      continue;
+    }
+    // Secrets never reach the child — redact before any original resolution
+    // so the resolver never fetches bytes it must not see.
+    if (cand.sensitivity === 'sensitive' || cand.artifactRef?.sensitivity === 'sensitive') {
+      exclude(ref, 'redacted', { text, provenance });
+      continue;
+    }
+    if (cand.memoryRecord != null) {
+      const verdict = eligible(cand.memoryRecord, memContext);
+      if (!verdict.ok) {
+        exclude(ref, verdict.reason, { text, provenance });
+        continue;
+      }
+    }
+    // Cross-run refs are out of scope for this child — deny before resolve.
+    if (isNonEmptyStr(cand.artifactRef?.runId) && cand.artifactRef.runId !== effectiveRunId) {
+      exclude(ref, 'cross_run', { text, provenance });
+      continue;
+    }
+    // Verify the original when a resolver is wired: a missing or
+    // checksum-changed original is marked invalid, never presented as
+    // current, and never silently omitted.
+    if (typeof resolveOriginal === 'function' && isPlainRec(cand.artifactRef)) {
+      let resolved = null;
+      try {
+        resolved = await resolveOriginal(cand.artifactRef);
+      } catch {
+        resolved = null;
+      }
+      if (resolved == null || resolved.status === 'unavailable') {
+        const reason = resolved?.reason;
+        const marked = reason === 'checksum_mismatch' || reason === 'bytes_mismatch'
+          ? 'stale_original'
+          : 'original_unavailable';
+        exclude(ref, marked, { text, provenance, detail: reason ?? 'unresolved' });
+        continue;
+      }
+    }
+    if (typeof cand.observedAt === 'number') {
+      const ttl = typeof cand.ttlMs === 'number' ? cand.ttlMs : STALE_MS;
+      if (nowMs - cand.observedAt > ttl) {
+        exclude(ref, 'stale', { text, provenance });
+        continue;
+      }
+    }
+    if (cand.audience != null) {
+      const aud = Array.isArray(cand.audience) ? cand.audience : [cand.audience];
+      if (!aud.includes(effectiveRole)) {
+        exclude(ref, 'audience_mismatch', { text, provenance });
+        continue;
+      }
+    }
+    // Isolated lanes (SPEC §6 reviewer default) receive requirements / diffs /
+    // tests / evidence — implementer narrative is out by construction.
+    if (effectiveMode === 'isolated' && cand.kind === 'narrative' && cand.required !== true) {
+      exclude(ref, 'isolated_excludes_narrative', { text, provenance });
+      continue;
+    }
+
+    const fingerprint = fingerprintOf(ref, text);
+
+    if (cand.required === true) {
+      pushItem({
+        ref,
+        included: true,
+        reason: 'required',
+        tokenEstimate,
+        provenance,
+        fingerprint,
+      });
+      tokensUsed += tokenEstimate;
+      if (budget != null && tokensUsed > budget) overBudget = true;
+      seenFingerprints.set(fingerprint, ref);
+      continue;
+    }
+
+    // Unknown relevance preserves the item (SPEC §7): the default action is
+    // include, so ambiguous candidates are carried with provenance intact.
+    const prior = seenFingerprints.get(fingerprint);
+    if (prior != null) {
+      // Exact-duplicate collapse — lineage kept on both sides.
+      const kept = items.find((i) => i.ref === prior);
+      const merged = {
+        ...kept,
+        sourceRefs: Object.freeze([...(kept.sourceRefs ?? []), ref]),
+      };
+      items[items.indexOf(kept)] = Object.freeze(merged);
+      exclude(ref, 'duplicate', { text, provenance, detail: `of:${prior}` });
+      continue;
+    }
+    if (budget != null && tokensUsed + tokenEstimate > budget) {
+      exclude(ref, 'over_budget', { text, provenance });
+      continue;
+    }
+    const entry = {
+      ref,
+      included: true,
+      reason: 'relevant',
+      tokenEstimate,
+      provenance,
+      fingerprint,
+    };
+    if (cand.memoryRecord != null
+      && cand.memoryRecord.verified !== true
+      && cand.memoryRecord.trust_tier !== 'verified') {
+      entry.label = 'unverified';
+    }
+    pushItem(entry);
+    seenFingerprints.set(fingerprint, ref);
+    tokensUsed += tokenEstimate;
+  }
+
+  const contextRefs = Object.freeze(
+    items.filter((i) => i.included).map((i) => i.ref),
+  );
+  const excludedCandidates = Object.freeze(
+    items.filter((i) => !i.included).map((i) => i.ref),
+  );
+
+  // Source fingerprint: deterministic over what was fed in — requested mode,
+  // run binding, and the candidate ref set — so manifests can be compared
+  // across identical inputs without trusting a regenerated build.
+  const sourceFingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    runId: effectiveRunId,
+    requestedMode,
+    refs: (candidates ?? []).map((c, i) =>
+      isNonEmptyStr(c?.ref) ? c.ref : `candidate:${i}`),
+  })).digest('hex');
+
+  const manifest = {
+    version: MANIFEST_VERSION,
+    runId: effectiveRunId,
+    mode: effectiveMode,
+    policyVersion: CONTEXT_MANIFEST_POLICY_VERSION,
+    // No shipped host exposes prompt-assembly control — the manifest is an
+    // advisory selection, never a claim about the child's actual prompt.
+    enforcement: 'advisory',
+    items: Object.freeze(items),
+    excludedCandidates,
+    tokensUsed,
+    overBudget,
+    sourceFingerprint,
+  };
+  if (effectiveMode !== requestedMode) manifest.requestedMode = requestedMode;
+
+  return {
+    ok: true,
+    mode: effectiveMode,
+    manifest: Object.freeze(manifest),
+    contextRefs,
+  };
+}

package/src/core/agentRuntime/contract.js

@@ -322,3 +322,299 @@ export function validateNodeQuestion(question, bounds = {}) {
   }
   return ok();
 }
+
+// ---------------------------------------------------------------------------
+// C89-003 — TaskContract v1 / ResultEnvelope v1 (SPEC §4–5).
+//
+// Additive envelope schema: the validators below return `{valid, errors[]}`
+// (callers need the full error list at a trust boundary) instead of the
+// `{ok, code}` shape used by the state-machine validators above. The envelope
+// carries its own `version: 1` — CONTRACT_VERSION stays pinned to the
+// operation-state contract and is not repurposed.
+
+export const TASK_CONTRACT_VERSION = 1;
+export const RESULT_ENVELOPE_VERSION = 1;
+
+/** ResultEnvelope v1 status vocabulary (SPEC §5). */
+export const RESULT_ENVELOPE_STATUSES = Object.freeze([
+  'complete',
+  'partial',
+  'blocked',
+  'needs_context',
+  'needs_capability',
+  'needs_delegation',
+  'needs_review',
+  'failed',
+]);
+
+/** Roles a TaskContract may delegate to (SPEC §6 initial set). */
+export const SUBAGENT_ROLES = Object.freeze(['retriever', 'reasoner', 'reviewer']);
+
+/**
+ * Context modes known to the v1 contract (SPEC §7). Real `fork` is absent:
+ * no host proves state inheritance at this contract version, so the honest
+ * v1 vocabulary stops at `fork_unavailable`.
+ */
+export const SUBAGENT_CONTEXT_MODES = Object.freeze(['isolated', 'curated', 'fork_unavailable']);
+
+/** Bounded budget vocabulary — no numeric caps in v1 (SPEC §10). */
+export const BUDGET_CLASSES = Object.freeze(['small', 'medium', 'large']);
+
+/** Sensitivity annotation on a run-artifact ref (SPEC §5). */
+export const REF_SENSITIVITIES = Object.freeze(['default', 'sensitive']);
+
+/** How a caller's write scope is realized on this host (SPEC §4). */
+export const WRITE_SCOPE_ENFORCEMENT = Object.freeze(['enforced', 'advisory']);
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isStringArray = (v) => Array.isArray(v) && v.every(isNonEmptyString);
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+const TASK_CONTRACT_KEYS = Object.freeze([
+  'version', 'id', 'objective', 'scope', 'constraints', 'knownFacts',
+  'expectedOutput', 'evidenceRequirement', 'role', 'contextMode',
+  'capabilities', 'writeScope', 'budgetClass', 'stopConditions',
+]);
+
+const RESULT_ENVELOPE_KEYS = Object.freeze([
+  'version', 'status', 'summary', 'claims', 'evidenceRefs', 'artifactRefs',
+  'unresolved', 'provenance',
+]);
+
+const REF_KEYS = Object.freeze([
+  'path', 'sha256', 'bytes', 'runId', 'truncated', 'sensitivity',
+  'version', 'capturedAt', 'stream',
+]);
+
+const CLAIM_KEYS = Object.freeze(['statement', 'evidenceRefs', 'confidence']);
+const SCOPE_KEYS = Object.freeze(['include', 'exclude']);
+const WRITE_SCOPE_KEYS = Object.freeze(['include', 'exclude', 'enforcement']);
+const KNOWN_FACT_KEYS = Object.freeze(['statement', 'source']);
+const UNRESOLVED_KEYS = Object.freeze(['reason', 'ref']);
+
+function pushUnknownKeys(errors, obj, allowed, label) {
+  for (const key of Object.keys(obj)) {
+    if (!allowed.includes(key)) errors.push(`${label}: unknown field '${key}'`);
+  }
+}
+
+function validateScopeObject(value, label, allowedKeys, errors) {
+  if (!isPlainRecord(value)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  pushUnknownKeys(errors, value, allowedKeys, label);
+  if (value.include !== undefined && !isStringArray(value.include)) {
+    errors.push(`${label}.include must be an array of non-empty strings`);
+  }
+  if (value.exclude !== undefined && !isStringArray(value.exclude)) {
+    errors.push(`${label}.exclude must be an array of non-empty strings`);
+  }
+}
+
+/**
+ * Validate one run-artifact reference (SPEC §5). A ref is meaningful only
+ * when it can be checksum-verified: `path` AND `sha256` are both required.
+ */
+function validateResultRef(ref, label, errors) {
+  if (!isPlainRecord(ref)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  pushUnknownKeys(errors, ref, REF_KEYS, label);
+  if (!isNonEmptyString(ref.path)) {
+    errors.push(`${label}.path must be a non-empty string`);
+  }
+  if (!SHA256_HEX_RE.test(ref.sha256)) {
+    errors.push(`${label}.sha256 must be a 64-hex digest`);
+  }
+  if (ref.bytes !== undefined && (!Number.isInteger(ref.bytes) || ref.bytes < 0)) {
+    errors.push(`${label}.bytes must be a non-negative integer`);
+  }
+  if (ref.runId !== undefined && !isNonEmptyString(ref.runId)) {
+    errors.push(`${label}.runId must be a non-empty string`);
+  }
+  if (ref.truncated !== undefined && typeof ref.truncated !== 'boolean') {
+    errors.push(`${label}.truncated must be a boolean`);
+  }
+  if (ref.sensitivity !== undefined && !REF_SENSITIVITIES.includes(ref.sensitivity)) {
+    errors.push(`${label}.sensitivity must be one of: ${REF_SENSITIVITIES.join(', ')}`);
+  }
+  if (ref.version !== undefined && ref.version !== RESULT_ENVELOPE_VERSION) {
+    errors.push(`${label}.version must be ${RESULT_ENVELOPE_VERSION}`);
+  }
+  if (ref.capturedAt !== undefined
+    && (typeof ref.capturedAt !== 'string' || Number.isNaN(Date.parse(ref.capturedAt)))) {
+    errors.push(`${label}.capturedAt must be an ISO timestamp`);
+  }
+  if (ref.stream !== undefined && ref.stream !== 'stdout' && ref.stream !== 'stderr') {
+    errors.push(`${label}.stream must be 'stdout' or 'stderr'`);
+  }
+}
+
+/**
+ * Validate a TaskContract v1 (SPEC §4). Required fields: id, objective,
+ * scope, constraints, expectedOutput, role. The schema is closed — unknown
+ * top-level keys reject so a later contract version cannot smuggle
+ * unvalidated fields through a v1 boundary.
+ *
+ * @param {*} value
+ * @returns {{valid:boolean, errors:string[]}}
+ */
+export function validateTaskContract(value) {
+  const errors = [];
+  if (!isPlainRecord(value)) {
+    return { valid: false, errors: ['contract must be an object'] };
+  }
+  pushUnknownKeys(errors, value, TASK_CONTRACT_KEYS, 'contract');
+  if (value.version !== TASK_CONTRACT_VERSION) {
+    errors.push(`version must be ${TASK_CONTRACT_VERSION}`);
+  }
+  if (!isNonEmptyString(value.id)) errors.push('id must be a non-empty string');
+  if (!isNonEmptyString(value.objective)) errors.push('objective must be a non-empty string');
+  if (value.scope === undefined) {
+    errors.push('scope is required');
+  } else {
+    validateScopeObject(value.scope, 'scope', SCOPE_KEYS, errors);
+  }
+  if (!isStringArray(value.constraints)) {
+    errors.push('constraints must be an array of non-empty strings');
+  }
+  if (!isNonEmptyString(value.expectedOutput)) {
+    errors.push('expectedOutput must be a non-empty string');
+  }
+  if (!SUBAGENT_ROLES.includes(value.role)) {
+    errors.push(`role must be one of: ${SUBAGENT_ROLES.join(', ')}`);
+  }
+
+  if (value.knownFacts !== undefined) {
+    if (!Array.isArray(value.knownFacts)) {
+      errors.push('knownFacts must be an array of {statement, source}');
+    } else {
+      value.knownFacts.forEach((fact, i) => {
+        if (!isPlainRecord(fact)) {
+          errors.push(`knownFacts[${i}] must be an object`);
+          return;
+        }
+        pushUnknownKeys(errors, fact, KNOWN_FACT_KEYS, `knownFacts[${i}]`);
+        if (!isNonEmptyString(fact.statement)) {
+          errors.push(`knownFacts[${i}].statement must be a non-empty string`);
+        }
+        // SPEC §4: externally supplied evidence requires provenance.
+        if (!isNonEmptyString(fact.source)) {
+          errors.push(`knownFacts[${i}].source must be a non-empty provenance string`);
+        }
+      });
+    }
+  }
+  if (value.evidenceRequirement !== undefined && !isNonEmptyString(value.evidenceRequirement)) {
+    errors.push('evidenceRequirement must be a non-empty string');
+  }
+  if (value.contextMode !== undefined && !SUBAGENT_CONTEXT_MODES.includes(value.contextMode)) {
+    errors.push(`contextMode must be one of: ${SUBAGENT_CONTEXT_MODES.join(', ')}`);
+  }
+  if (value.capabilities !== undefined && !isStringArray(value.capabilities)) {
+    errors.push('capabilities must be an array of non-empty strings');
+  }
+  if (value.writeScope !== undefined) {
+    if (!isPlainRecord(value.writeScope)) {
+      errors.push('writeScope must be an object');
+    } else {
+      validateScopeObject(value.writeScope, 'writeScope', WRITE_SCOPE_KEYS, errors);
+      if (value.writeScope.enforcement !== undefined
+        && !WRITE_SCOPE_ENFORCEMENT.includes(value.writeScope.enforcement)) {
+        errors.push(`writeScope.enforcement must be one of: ${WRITE_SCOPE_ENFORCEMENT.join(', ')}`);
+      }
+    }
+  }
+  if (value.budgetClass !== undefined && !BUDGET_CLASSES.includes(value.budgetClass)) {
+    errors.push(`budgetClass must be one of: ${BUDGET_CLASSES.join(', ')}`);
+  }
+  if (value.stopConditions !== undefined && !isStringArray(value.stopConditions)) {
+    errors.push('stopConditions must be an array of non-empty strings');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a ResultEnvelope v1 (SPEC §5). The compact control result a child
+ * hands the parent: every status in RESULT_ENVELOPE_STATUSES is terminal for
+ * the child, evidence is by-ref only (never raw bytes).
+ *
+ * @param {*} value
+ * @returns {{valid:boolean, errors:string[]}}
+ */
+export function validateResultEnvelope(value) {
+  const errors = [];
+  if (!isPlainRecord(value)) {
+    return { valid: false, errors: ['envelope must be an object'] };
+  }
+  pushUnknownKeys(errors, value, RESULT_ENVELOPE_KEYS, 'envelope');
+  if (value.version !== RESULT_ENVELOPE_VERSION) {
+    errors.push(`version must be ${RESULT_ENVELOPE_VERSION}`);
+  }
+  if (!RESULT_ENVELOPE_STATUSES.includes(value.status)) {
+    errors.push(`status must be one of: ${RESULT_ENVELOPE_STATUSES.join(', ')}`);
+  }
+  if (typeof value.summary !== 'string') {
+    errors.push('summary must be a string');
+  }
+  if (!Array.isArray(value.claims)) {
+    errors.push('claims must be an array');
+  } else {
+    value.claims.forEach((claim, i) => {
+      const label = `claims[${i}]`;
+      if (!isPlainRecord(claim)) {
+        errors.push(`${label} must be an object`);
+        return;
+      }
+      pushUnknownKeys(errors, claim, CLAIM_KEYS, label);
+      if (!isNonEmptyString(claim.statement)) {
+        errors.push(`${label}.statement must be a non-empty string`);
+      }
+      if (!Array.isArray(claim.evidenceRefs)) {
+        errors.push(`${label}.evidenceRefs must be an array`);
+      } else {
+        claim.evidenceRefs.forEach((ref, j) => validateResultRef(ref, `${label}.evidenceRefs[${j}]`, errors));
+      }
+      if (claim.confidence !== undefined
+        && (typeof claim.confidence !== 'number' || claim.confidence < 0 || claim.confidence > 1)) {
+        errors.push(`${label}.confidence must be a number in [0,1]`);
+      }
+    });
+  }
+  if (!Array.isArray(value.evidenceRefs)) {
+    errors.push('evidenceRefs must be an array');
+  } else {
+    value.evidenceRefs.forEach((ref, i) => validateResultRef(ref, `evidenceRefs[${i}]`, errors));
+  }
+  if (!Array.isArray(value.artifactRefs)) {
+    errors.push('artifactRefs must be an array');
+  } else {
+    value.artifactRefs.forEach((ref, i) => validateResultRef(ref, `artifactRefs[${i}]`, errors));
+  }
+  if (!Array.isArray(value.unresolved)) {
+    errors.push('unresolved must be an array');
+  } else {
+    value.unresolved.forEach((entry, i) => {
+      const label = `unresolved[${i}]`;
+      if (!isPlainRecord(entry)) {
+        errors.push(`${label} must be an object`);
+        return;
+      }
+      pushUnknownKeys(errors, entry, UNRESOLVED_KEYS, label);
+      if (!isNonEmptyString(entry.reason)) {
+        errors.push(`${label}.reason must be a non-empty string`);
+      }
+      if (entry.ref !== undefined) validateResultRef(entry.ref, `${label}.ref`, errors);
+    });
+  }
+  if (!isPlainRecord(value.provenance)) {
+    errors.push('provenance must be an object');
+  } else if (!isNonEmptyString(value.provenance.producer)) {
+    errors.push('provenance.producer must be a non-empty string');
+  }
+  return { valid: errors.length === 0, errors };
+}