session-orchestrator 5.10.0 → 5.11.0

package/scripts/lib/memory-proposals/store.mjs

@@ -8,6 +8,9 @@
  *    `createStateLockExclusive` pattern (POSIX-atomic create-or-fail).
  *  - Proposals JSONL: `.orchestrator/metrics/proposals.jsonl` (O_APPEND)
  *  - Per-wave summary: `.orchestrator/metrics/proposals-summary-<wave-id>.json`
+ *  - Overflow JSONL: `.orchestrator/metrics/proposals-overflow.jsonl` — validated
+ *    proposals the quota rejected (#1027 1b). Never counted against the quota,
+ *    never read by the collector; written under the same lock as the queue.
  *  - Confidence floor check: BEFORE lock acquisition (no I/O, no lock held).
  *  - Quota check: INSIDE lock (count + decide + write serialized).
  *
@@ -16,6 +19,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { serializeProposal } from './schema.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { tryAcquireFileLock, releaseFileLock } from '../file-lock.mjs';
@@ -26,6 +30,8 @@ import { writeJsonAtomicSync } from '../io.mjs';
 // ---------------------------------------------------------------------------
 
 const PROPOSALS_JSONL = '.orchestrator/metrics/proposals.jsonl';
+const PROPOSALS_OVERFLOW_JSONL = '.orchestrator/metrics/proposals-overflow.jsonl';
+const OVERFLOW_MAX_BYTES = 1024 * 1024;
 const PROPOSALS_LOCK = '.orchestrator/metrics/proposals-write.lock';
 const PROPOSALS_SUMMARY_PREFIX = '.orchestrator/metrics/proposals-summary-';
 
@@ -60,20 +66,86 @@ const LOCK_POLL_MS = 50;
  */
 function safePath(repoRoot, relPath) {
   const result = validatePathInsideProject(relPath, repoRoot, { canonicalizeRoot: true });
-  if (!result.ok) {
-    const resolved = path.resolve(repoRoot, relPath);
-    // #548 A5 — surface result.reason ('lexical' | 'symlink' | 'input') in the
-    // error so operators can distinguish path-traversal classes at a glance:
-    //  - 'lexical' → relPath escaped repoRoot via ../../ before symlink resolution
-    //  - 'symlink' → relPath resolved through a symlink that points outside repoRoot
-    //  - 'input'   → relPath was malformed (empty, non-string, null byte)
-    throw new TypeError(
-      `store.mjs: path traversal blocked: ${resolved} is outside ${repoRoot} (reason: ${result.reason})`
+  // #548 A5 — surface result.reason ('lexical' | 'symlink' | 'input') in the
+  // error so operators can distinguish path-traversal classes at a glance:
+  //  - 'lexical' → relPath escaped repoRoot via ../../ before symlink resolution
+  //  - 'symlink' → relPath resolved through a symlink that points outside repoRoot
+  //  - 'input'   → relPath was malformed (empty, non-string, null byte)
+  const blocked = (reason) =>
+    new TypeError(
+      `store.mjs: path traversal blocked: ${path.resolve(repoRoot, relPath)} is outside ${repoRoot} (reason: ${reason})`
     );
+  if (!result.ok) throw blocked(result.reason);
+  // The shared validator swallows ENOENT on the target and returns the lexical
+  // path unchecked, so a symlinked ancestor (or a dangling symlink AT the
+  // target) lets the first write land outside the repo (#1027 1b). Closed here,
+  // store-side, so the shared validator's other callers keep their behaviour.
+  if (result.realPath === undefined && !existingAncestorInsideRoot(repoRoot, result.lexicalPath)) {
+    throw blocked('symlink');
   }
   return result.realPath ?? result.lexicalPath;
 }
 
+/**
+ * True when the nearest EXISTING component of `lexicalPath` (the path itself
+ * or the closest ancestor) resolves inside the canonical `repoRoot`. A
+ * symlink there whose target is missing (dangling) counts as an escape — the
+ * write that follows would create the target wherever the link points.
+ *
+ * Only node:fs/node:path on purpose: store-safepath-reason.test.mjs mocks
+ * `@lib/path-utils.mjs` with a single export, so no second import from it.
+ *
+ * Check-then-write TOCTOU: a link swapped in between this check and the
+ * append is not caught (O_NOFOLLOW would narrow the final component only).
+ * Accepted under the local-trust model; revisit if the metrics dir ever
+ * becomes writable by another principal.
+ *
+ * @param {string} repoRoot
+ * @param {string} lexicalPath — absolute, already known to be lexically inside repoRoot
+ * @returns {boolean}
+ */
+function existingAncestorInsideRoot(repoRoot, lexicalPath) {
+  let root = repoRoot;
+  try {
+    root = fs.realpathSync(repoRoot);
+  } catch (err) {
+    if (err?.code !== 'ENOENT' && err?.code !== 'EACCES') throw err;
+  }
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+  const inside = (p) => {
+    const rel = path.relative(fold(root), fold(p));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  };
+  for (let cur = lexicalPath; ; cur = path.dirname(cur)) {
+    // Climbed above the root: root itself is missing, so nothing under it can
+    // be a link — the later mkdir creates a plain tree.
+    if (!inside(cur)) return true;
+    try {
+      fs.lstatSync(cur);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err;
+      continue;
+    }
+    let real;
+    try {
+      real = fs.realpathSync(cur);
+    } catch {
+      // Dangling link or loop at the nearest existing component → escape.
+      // But the lock file is created and unlinked by concurrent writers all
+      // the time: if the component vanished between lstat and realpath it was
+      // never a link, so step up to its parent instead of rejecting.
+      try {
+        fs.lstatSync(cur);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw err;
+      }
+      return false;
+    }
+    return inside(real);
+  }
+}
+
 /**
  * Ensure the parent directory of `filePath` exists.
  * @param {string} filePath
@@ -100,6 +172,153 @@ function jsonlPathFor(repoRoot) {
   return safePath(repoRoot, PROPOSALS_JSONL);
 }
 
+/**
+ * Build the absolute path to the quota-overflow JSONL file.
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function overflowPathFor(repoRoot) {
+  return safePath(repoRoot, PROPOSALS_OVERFLOW_JSONL);
+}
+
+/** Flush a directory entry before depending on its persistence. */
+function syncOverflowDirectory(directory) {
+  const fd = fs.openSync(directory, 'r');
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** Create a file without replacing anything, retaining leftovers on failure. */
+function writeOverflowExclusive(file, bytes, mode) {
+  const fd = fs.openSync(file, 'wx', mode);
+  try {
+    // The umask may narrow the creation mode; restore exactly the old mode.
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Copy legacy files with bounded memory into an exclusive `.partial` file,
+ * then hard-link it to the archive name. An interrupted copy leaves only the
+ * `.partial` name behind, never a truncated file under the archive name; the
+ * link fails with EEXIST instead of overwriting an existing archive. Unsupported
+ * link operations discard only our completed staging copy, leaving active intact.
+ */
+function archiveOverflowExclusive(active, archive, partial, mode) {
+  const source = fs.openSync(active, 'r');
+  try {
+    const destination = fs.openSync(partial, 'wx', mode);
+    try {
+      // The umask may narrow the creation mode; restore exactly the old mode.
+      fs.fchmodSync(destination, mode);
+      const chunk = Buffer.alloc(64 * 1024);
+      let count;
+      while ((count = fs.readSync(source, chunk, 0, chunk.length, null)) > 0) {
+        fs.writeFileSync(destination, chunk.subarray(0, count));
+      }
+      fs.fsyncSync(destination);
+    } finally {
+      fs.closeSync(destination);
+    }
+  } finally {
+    fs.closeSync(source);
+  }
+  try {
+    fs.linkSync(partial, archive);
+  } catch (err) {
+    if (!['EPERM', 'ENOTSUP', 'EXDEV'].includes(err?.code)) throw err;
+    // We exclusively created this complete copy and have not replaced active.
+    // Do not accumulate another full copy on every unsupported-link retry.
+    // Copy/flush failures and collisions deliberately retain their evidence.
+    let cleanupError = '';
+    try {
+      fs.unlinkSync(partial);
+    } catch (cleanup) {
+      cleanupError = `; partial cleanup failed (${cleanup?.code ?? 'unknown'}): ${cleanup.message}`;
+    }
+    // appendProposal exposes message, so preserve the filesystem code there.
+    // This statement is specific to publication failure, never post-rename I/O.
+    throw new Error(
+      `overflow archive publication failed (${err.code}): ${err.message}; new proposal not stored${cleanupError}`,
+      { cause: err }
+    );
+  }
+  fs.unlinkSync(partial);
+}
+
+/**
+ * Preserve the old bytes durably before replacing the active overflow file.
+ * The proposals lock serializes writers of this append/rotation decision.
+ * Failures before rename leave the active file intact; after rename, the
+ * durable archive preserves the old bytes and the replacement has the new
+ * record. Incomplete archives/temps remain for inspection, never deleted.
+ * BV-004: archive aggregate size is unbounded (no retention authorization).
+ * Revisit growth when active file >= 1 MiB or first rotation: measure it.
+ */
+function appendOverflow(repoRoot, overflowPath, line) {
+  ensureDir(overflowPath);
+  let oldSize = 0;
+  let oldMode = 0o600;
+  let unterminated = false;
+  try {
+    const fd = fs.openSync(overflowPath, 'r');
+    try {
+      const oldStat = fs.fstatSync(fd);
+      oldSize = oldStat.size;
+      oldMode = oldStat.mode & 0o777;
+      if (oldSize > 0) {
+        const lastByte = Buffer.alloc(1);
+        if (fs.readSync(fd, lastByte, 0, 1, oldSize - 1) !== 1) {
+          throw new Error('overflow changed while checking its final byte');
+        }
+        unterminated = lastByte[0] !== 10;
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+  const lineBytes = Buffer.from(line, 'utf8');
+  // Optional schema fields have no aggregate size limit. A single oversized
+  // record is preserved whole even though the active file exceeds the cap;
+  // the next record rotates it. Empty/absent files need no recovery archive.
+  if (oldSize === 0 || (!unterminated && oldSize + lineBytes.length <= OVERFLOW_MAX_BYTES)) {
+    fs.appendFileSync(overflowPath, lineBytes);
+    return;
+  }
+  const root = fs.realpathSync(repoRoot);
+  const directory = path.dirname(overflowPath);
+  const token = randomUUID();
+  const archive = safePath(root, path.relative(root, `${overflowPath}.archive-${token}.jsonl`));
+  const partial = safePath(root, path.relative(root, `${overflowPath}.archive-${token}.partial`));
+  const temporary = safePath(root, path.relative(root, `${overflowPath}.tmp-${token}`));
+  // Existing arbitrarily large files copy in bounded chunks.
+  // Preserve access restrictions; rotation must not widen a private inode's
+  // mode through the process umask's default creation permissions.
+  archiveOverflowExclusive(overflowPath, archive, partial, oldMode);
+  // Persist the archive's name (and the partial's removal) plus any newly
+  // created ancestors BEFORE replacing the sole active copy. All these
+  // directories are inside root.
+  for (let current = directory; ; current = path.dirname(current)) {
+    syncOverflowDirectory(current);
+    if (current === root) break;
+    if (current === path.dirname(current)) {
+      throw new Error('overflow directory is not inside the repository root');
+    }
+  }
+  writeOverflowExclusive(temporary, lineBytes, oldMode);
+  fs.renameSync(temporary, overflowPath);
+  syncOverflowDirectory(directory);
+}
+
 /**
  * Build the absolute path to the per-wave summary JSON file.
  * wave_id values are restricted to alphanumerics + hyphens/underscores to
@@ -372,6 +591,23 @@ export async function appendProposal({
     // Step 3b: Quota check.
     // ------------------------------------------------------------------
     if (currentCount >= quotaPerWave) {
+      // Keep the validated proposal (#1027 1b): the quota caps what enters the
+      // queue, not what an agent found. A failed write is fs-error — never a
+      // quota-exceeded that implies the content was preserved. Rotation keeps
+      // every old byte in an exclusive archive before replacing the active file.
+      let overflowPath;
+      try {
+        overflowPath = overflowPathFor(repoRoot);
+      } catch (err) {
+        incrementSummary(summaryPath, 'fs_error'); // traversal still throws, like every store path
+        throw err;
+      }
+      try {
+        appendOverflow(repoRoot, overflowPath, serializeProposal(record) + '\n');
+      } catch (err) {
+        incrementSummary(summaryPath, 'fs_error');
+        return { status: 'fs-error', error: err.message };
+      }
       const summary = readSummary(summaryPath);
       const droppedSoFar = summary.dropped;
       incrementSummary(summaryPath, 'dropped');

package/scripts/lib/project-hygiene.mjs

@@ -555,6 +555,10 @@ const AUDIT_VALUE_FLAGS = new Set([
 const AUDIT_BOOLEAN_FLAGS = new Set([
   '-r', '--recursive', '-s', '--silent', '-g', '--global', '--workspaces', '--offline',
 ]);
+// Python tool runners (#1538): subcommand words after the verb, and the runner
+// options that consume the next token.
+const RUNNER_SUBCOMMANDS = { uvx: [], pipx: ['run'], uv: ['tool', 'run'] };
+const RUNNER_VALUE_FLAGS = new Set(['--from', '--spec', '--python', '-p', '--with']);
 
 /** Inspect executable job/step locations, never arbitrary keys named run/script. */
 function hasAuditStep({ text, platform }) {
@@ -683,6 +687,39 @@ function hasAuditSegment(segment, depth = 0) {
     const trailingArgs = index < 0 ? [] : segment.slice(index);
     return hasAuditSegment([...tokens, ...trailingArgs], depth + 1);
   }
+  if (verb === 'uvx' || verb === 'pipx' || verb === 'uv') {
+    let i = index + 1;
+    // `uvx` is an alias of `uv tool run`; `pipx` executes only through `run`.
+    for (const word of RUNNER_SUBCOMMANDS[verb]) {
+      if (segment[i]?.text !== word) return false;
+      i++;
+    }
+    // Runner options before the tool. Unknown flags count as value-less, so an
+    // unlisted value-taking flag makes its value the "tool" and the line is
+    // missed — a false finding, never a false pass. Revisit if a real CI line
+    // with such a flag is reported as missing its audit.
+    // `--from`/`--spec` name the package that provides the tool; another
+    // package exposing a `pip-audit` entry point is not the audit.
+    let sourcePackage = null;
+    while (segment[i]) {
+      const { text, redirect } = segment[i];
+      // A redirect operand is data, even when it names the audit package.
+      if (redirect) return false;
+      if (text === '--') { i++; break; }
+      if (!text.startsWith('-')) break;
+      if (RUNNER_VALUE_FLAGS.has(text)) {
+        if (!segment[i + 1] || segment[i + 1].redirect) return false;
+        if (text === '--from' || text === '--spec') sourcePackage = segment[i + 1].text;
+        i += 2;
+      } else {
+        i++;
+      }
+    }
+    if (!segment[i] || segment[i].redirect) return false;
+    if (segment.slice(index + 1).some((token) => ['-h', '--help', '--version'].includes(token.text))) return false;
+    if (sourcePackage !== null && !/^pip-audit(?:\s*(?:[=<>~!]=?|@)\s*[\w.+*-]+)?$/.test(sourcePackage)) return false;
+    return /^pip-audit(?:@[\w.+-]+)?$/.test(segment[i].text);
+  }
   if (verb === 'corepack' || verb === 'npx') {
     index++;
     while (['-y', '--yes', '--no-install', '--'].includes(segment[index]?.text)) index++;

package/scripts/lib/role-profile/schema.mjs

@@ -0,0 +1,219 @@
+/**
+ * Offline role-profile evidence contract. Refs #1469.
+ * Validation checks internal consistency, never source authenticity or runtime capability.
+ */
+export const ROLE_PROFILE_CONTRACT_VERSION = 1;
+
+const BINDINGS = new Map([['openai', 'codex-cli'], ['anthropic', 'claude-code']]);
+const DIALECTS = new Map([['openai-reasoning', 'openai'], ['anthropic-effort', 'anthropic']]);
+
+/**
+ * @param {unknown} value JSON data, without accessors or class instances.
+ * @returns {{success: true, data: unknown, diagnostics: object[]} |
+ * {success: false, error: {issues: {code: string, path: (string|number)[], message: string}[]}}}
+ */
+function safeParse(value) {
+  const issues = [];
+  const diagnostics = [];
+  const fail = (code, path, message) => issues.push({ code, path, message });
+  const object = (v, keys, path) => {
+    if (!v || typeof v !== 'object' || Array.isArray(v) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(v))) {
+      fail('INVALID_TYPE', path, 'Expected a plain object');
+      return {};
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(v);
+    if (Object.values(descriptors).some(d => !Object.hasOwn(d, 'value'))) {
+      fail('INVALID_TYPE', path, 'Expected data properties');
+      return {};
+    }
+    for (const key of Reflect.ownKeys(v)) {
+      if (!keys.includes(key)) fail('UNKNOWN_FIELD', [...path, String(key)], 'Unknown field');
+    }
+    for (const key of keys) {
+      if (!Object.hasOwn(v, key)) fail('MISSING_FIELD', [...path, key], 'Required field is missing');
+    }
+    return v;
+  };
+  const string = (v, path) => {
+    if (typeof v !== 'string' || !v.trim()) fail('INVALID_TYPE', path, 'Expected a nonempty string');
+  };
+  const isNull = (v, path) => {
+    if (v !== null) fail('INVALID_RELATION', path, 'Expected null in this evidence state');
+  };
+  const oneOf = (v, values, path) => {
+    if (!values.includes(v)) fail('INVALID_VALUE', path, 'Unsupported discriminator');
+  };
+  const relation = (condition, path, message) => {
+    if (!condition) fail('INVALID_RELATION', path, message);
+  };
+  const evidence = (v, field, path, statuses = ['known', 'unknown']) => {
+    const e = object(v, ['status', field, 'sourceRef', 'reason'], path);
+    oneOf(e.status, statuses, [...path, 'status']);
+    if (e.status === 'unknown') {
+      isNull(e[field], [...path, field]);
+      isNull(e.sourceRef, [...path, 'sourceRef']);
+      string(e.reason, [...path, 'reason']);
+    } else if (statuses.includes(e.status)) {
+      string(e[field], [...path, field]);
+      string(e.sourceRef, [...path, 'sourceRef']);
+      isNull(e.reason, [...path, 'reason']);
+    }
+    return e;
+  };
+
+  const root = object(value, ['contractVersion', 'role', 'taskClass', 'provider', 'transport',
+    'binding', 'model', 'effort', 'harness', 'profile', 'registryVersion', 'selection',
+    'authorization', 'evidence'], []);
+  if (root.contractVersion !== ROLE_PROFILE_CONTRACT_VERSION) {
+    fail('UNSUPPORTED_VERSION', ['contractVersion'], 'Expected contract version 1');
+    return { success: false, error: { issues } };
+  }
+  for (const key of ['role', 'taskClass', 'provider', 'transport']) string(root[key], [key]);
+  const binding = object(root.binding, ['status', 'sourceRef', 'reason'], ['binding']);
+  oneOf(binding.status, ['known', 'unknown'], ['binding', 'status']);
+  if (binding.status === 'known') {
+    string(binding.sourceRef, ['binding', 'sourceRef']);
+    isNull(binding.reason, ['binding', 'reason']);
+    relation(BINDINGS.has(root.provider) && BINDINGS.get(root.provider) === root.transport,
+      ['binding'], 'Known provider/transport binding must match the v1 contract');
+  } else if (binding.status === 'unknown') {
+    isNull(binding.sourceRef, ['binding', 'sourceRef']);
+    string(binding.reason, ['binding', 'reason']);
+  }
+
+  const model = object(root.model, ['requested', 'observed', 'resolution'], ['model']);
+  const requested = object(model.requested, ['kind', 'value'], ['model', 'requested']);
+  oneOf(requested.kind, ['id', 'alias', 'inherit'], ['model', 'requested', 'kind']);
+  if (requested.kind === 'inherit') isNull(requested.value, ['model', 'requested', 'value']);
+  else string(requested.value, ['model', 'requested', 'value']);
+  const observed = evidence(model.observed, 'id', ['model', 'observed']);
+  const resolution = object(model.resolution,
+    ['status', 'baselineId', 'parent', 'sourceRef', 'reason'], ['model', 'resolution']);
+  oneOf(resolution.status, ['exact', 'alias-resolved', 'alias-drift', 'parent-inherit', 'unknown'],
+    ['model', 'resolution', 'status']);
+  if (observed.status === 'unknown') {
+    relation(resolution.status === 'unknown', ['model', 'resolution', 'status'],
+      'Unknown observation must retain unknown resolution');
+  }
+  if (resolution.status === 'unknown') {
+    isNull(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+    isNull(resolution.parent, ['model', 'resolution', 'parent']);
+    isNull(resolution.sourceRef, ['model', 'resolution', 'sourceRef']);
+    string(resolution.reason, ['model', 'resolution', 'reason']);
+  } else if (['exact', 'alias-resolved', 'alias-drift', 'parent-inherit'].includes(resolution.status)) {
+    relation(observed.status === 'known', ['model', 'observed'], 'Resolution requires an observation');
+    string(resolution.sourceRef, ['model', 'resolution', 'sourceRef']);
+    isNull(resolution.reason, ['model', 'resolution', 'reason']);
+    if (resolution.status !== 'alias-drift') isNull(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+    if (resolution.status !== 'parent-inherit') isNull(resolution.parent, ['model', 'resolution', 'parent']);
+    if (resolution.status === 'exact') {
+      relation(requested.kind === 'id' && requested.value === observed.id,
+        ['model', 'resolution'], 'Exact resolution requires the requested ID');
+    } else if (['alias-resolved', 'alias-drift'].includes(resolution.status)) {
+      relation(requested.kind === 'alias', ['model', 'requested', 'kind'], 'Alias resolution requires an alias');
+      if (resolution.status === 'alias-drift') {
+        string(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+        relation(resolution.baselineId !== observed.id, ['model', 'resolution', 'baselineId'],
+          'Alias drift requires a different documented baseline ID');
+      }
+    } else {
+      const parent = object(resolution.parent, ['id', 'sourceRef'], ['model', 'resolution', 'parent']);
+      string(parent.id, ['model', 'resolution', 'parent', 'id']);
+      string(parent.sourceRef, ['model', 'resolution', 'parent', 'sourceRef']);
+      relation(requested.kind === 'inherit' && parent.id === observed.id,
+        ['model', 'resolution'], 'Parent inheritance requires matching parent evidence');
+    }
+  }
+
+  const effort = object(root.effort, ['requested', 'effective', 'support'], ['effort']);
+  const requestedEffort = object(effort.requested, ['provider', 'dialect', 'value'], ['effort', 'requested']);
+  const effective = object(effort.effective,
+    ['provider', 'dialect', 'status', 'value', 'sourceRef', 'reason'], ['effort', 'effective']);
+  const support = object(effort.support, ['status', 'sourceRef', 'reason'], ['effort', 'support']);
+  oneOf(support.status, ['supported', 'unsupported', 'unknown'], ['effort', 'support', 'status']);
+  if (support.status === 'unknown') {
+    isNull(support.sourceRef, ['effort', 'support', 'sourceRef']);
+    string(support.reason, ['effort', 'support', 'reason']);
+  } else if (['supported', 'unsupported'].includes(support.status)) {
+    string(support.sourceRef, ['effort', 'support', 'sourceRef']);
+    isNull(support.reason, ['effort', 'support', 'reason']);
+  }
+  oneOf(effective.status, ['known', 'unknown'], ['effort', 'effective', 'status']);
+  for (const [key, entry] of [['requested', requestedEffort], ['effective', effective]]) {
+    string(entry.provider, ['effort', key, 'provider']);
+    string(entry.dialect, ['effort', key, 'dialect']);
+    relation(entry.provider === root.provider, ['effort', key, 'provider'], 'Effort provider must match the record');
+    if (DIALECTS.has(entry.dialect)) {
+      relation(DIALECTS.get(entry.dialect) === entry.provider, ['effort', key, 'dialect'],
+        'Effort dialect belongs to a different provider');
+    } else {
+      relation(support.status === 'unknown' && effective.status === 'unknown', ['effort', key, 'dialect'],
+        'Unrecognized effort dialect requires unknown support and effective evidence');
+    }
+  }
+  if (requestedEffort.value !== null) string(requestedEffort.value, ['effort', 'requested', 'value']);
+  if (effective.status === 'unknown') {
+    isNull(effective.value, ['effort', 'effective', 'value']);
+    isNull(effective.sourceRef, ['effort', 'effective', 'sourceRef']);
+    string(effective.reason, ['effort', 'effective', 'reason']);
+  } else if (effective.status === 'known') {
+    string(effective.value, ['effort', 'effective', 'value']);
+    string(effective.sourceRef, ['effort', 'effective', 'sourceRef']);
+    isNull(effective.reason, ['effort', 'effective', 'reason']);
+  }
+  if (support.status === 'unsupported') {
+    diagnostics.push({ code: 'UNSUPPORTED_EFFORT', path: ['effort', 'requested', 'value'],
+      message: 'Requested effort is documented as unsupported' });
+    relation(!(effective.status === 'known' && effective.value === requestedEffort.value),
+      ['effort', 'effective'], 'Unsupported requested effort cannot also be claimed effective');
+  }
+
+  const harness = object(root.harness, ['name', 'version'], ['harness']);
+  string(harness.name, ['harness', 'name']);
+  evidence(harness.version, 'value', ['harness', 'version']);
+  const profile = object(root.profile, ['id', 'version'], ['profile']);
+  string(profile.id, ['profile', 'id']);
+  evidence(profile.version, 'value', ['profile', 'version']);
+  evidence(root.registryVersion, 'value', ['registryVersion']);
+  const selection = object(root.selection, ['mode', 'escalationReason'], ['selection']);
+  oneOf(selection.mode, ['profile', 'owner-override', 'escalation'], ['selection', 'mode']);
+  if (selection.mode === 'escalation') string(selection.escalationReason, ['selection', 'escalationReason']);
+  else isNull(selection.escalationReason, ['selection', 'escalationReason']);
+  const auth = object(root.authorization,
+    ['status', 'authority', 'sourceRef', 'scope', 'reason'], ['authorization']);
+  oneOf(auth.status, ['authorized', 'unknown', 'not-required'], ['authorization', 'status']);
+  if (['owner-override', 'escalation'].includes(selection.mode)) {
+    relation(auth.status === 'authorized', ['authorization', 'status'], 'Selection requires owner authorization evidence');
+  }
+  if (auth.status === 'authorized') {
+    relation(auth.authority === 'owner', ['authorization', 'authority'], 'Authorization authority must be owner');
+    string(auth.sourceRef, ['authorization', 'sourceRef']);
+    isNull(auth.reason, ['authorization', 'reason']);
+    const scope = object(auth.scope, ['role', 'provider', 'transport', 'model', 'effort'], ['authorization', 'scope']);
+    for (const key of ['role', 'provider', 'transport']) {
+      string(scope[key], ['authorization', 'scope', key]);
+      relation(scope[key] === root[key], ['authorization', 'scope', key], 'Authorization scope must cover this record');
+    }
+    const scopedModel = object(scope.model, ['kind', 'value'], ['authorization', 'scope', 'model']);
+    for (const key of ['kind', 'value']) relation(scopedModel[key] === requested[key],
+      ['authorization', 'scope', 'model', key], 'Authorization must cover the model request');
+    const scopedEffort = object(scope.effort, ['provider', 'dialect', 'value'], ['authorization', 'scope', 'effort']);
+    for (const key of ['provider', 'dialect', 'value']) relation(scopedEffort[key] === requestedEffort[key],
+      ['authorization', 'scope', 'effort', key], 'Authorization must cover the effort request');
+  } else if (['unknown', 'not-required'].includes(auth.status)) {
+    for (const key of ['authority', 'sourceRef', 'scope']) isNull(auth[key], ['authorization', key]);
+    string(auth.reason, ['authorization', 'reason']);
+  }
+  const measured = evidence(root.evidence, 'timestamp', ['evidence']);
+  if (measured.status === 'known') {
+    const timestamp = measured.timestamp;
+    const valid = typeof timestamp === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(timestamp) &&
+      Number.isFinite(Date.parse(timestamp)) && new Date(timestamp).toISOString() === timestamp;
+    relation(valid, ['evidence', 'timestamp'], 'Expected an actual UTC timestamp with millisecond precision');
+  }
+  return issues.length ? { success: false, error: { issues } } : { success: true, data: value, diagnostics };
+}
+
+/** Versioned schema facade; syntax success grants no runtime approval. */
+export const roleProfileEvidenceSchema = Object.freeze({ safeParse });