mecord-connect 1.0.0

package/runtime/app/src/capabilities/project-command.js

@@ -0,0 +1,599 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+                                                                                                                                                 
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { readDurableStateBytes, readDurableStateText } from '../core/durable-state.js';
+import { PathScope } from './path-scope.js';
+import { ProcessProvider } from './process.js';
+
+const SCORE                  = {
+  reliability: 0.99,
+  latency: 0.96,
+  determinism: 0.99,
+  security: 0.98,
+  reversibility: 0.8,
+  informationQuality: 0.99,
+  interactionCost: 0.01
+};
+
+const MAX_REGISTRY_BYTES = 512 * 1024;
+const MAX_COMMANDS_PER_PROJECT = 100;
+const MAX_ARTIFACTS_PER_COMMAND = 50;
+const MAX_JSON_ARTIFACT_BYTES = 4 * 1024 * 1024;
+const MAX_HASH_ARTIFACT_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+const REGISTRY_OPTIONS = {
+  maxBytes: MAX_REGISTRY_BYTES,
+  errorCode: 'COMMAND_REGISTRY_INVALID',
+  invalidMessage: 'Trusted command registry is invalid.'
+}         ;
+const ARTIFACT_FILE_OPTIONS = {
+  maxBytes: MAX_HASH_ARTIFACT_BYTES,
+  errorCode: 'ARTIFACT_FILE_INVALID',
+  invalidMessage: 'Trusted artifact file is invalid.'
+}         ;
+
+                        
+               
+                                      
+                   
+                      
+  
+
+                       
+             
+                 
+                                                                              
+                     
+                 
+              
+                    
+                                      
+                               
+  
+
+                       
+               
+                             
+  
+
+                 
+             
+                             
+  
+
+                         
+               
+                  
+                                                                 
+                
+                       
+  
+
+                           
+               
+                                
+                  
+                                                                    
+                           
+                          
+  
+
+export class ProjectCommandProvider                               {
+           name = 'project.command.trusted';
+  #scope           ;
+  #allowedRoots          ;
+  #allowedExecutables             ;
+  #registryPath        ;
+
+  constructor(options                                                                                 ) {
+    this.#scope = new PathScope(options.allowedRoots);
+    this.#allowedRoots = options.allowedRoots.map((root) => path.resolve(root));
+    this.#allowedExecutables = new Set(options.allowedExecutables.map((value) => value.toLowerCase()));
+    this.#registryPath = path.resolve(options.registryPath ?? path.join(os.homedir(), '.operator', 'project-commands.json'));
+  }
+
+  supports(action               )          {
+    return ['project.command.inspect', 'project.command.run'].includes(action.capability);
+  }
+
+  score()                  { return SCORE; }
+
+  async resolveRisk(action               )                      {
+    if (action.capability === 'project.command.inspect') return 'read';
+    if (action.capability !== 'project.command.run') throw new OperatorError('CAPABILITY_RISK_UNRESOLVED', 'Unsupported project command capability.');
+    const projectRoot = await this.#scope.resolveExisting(String(action.input.path ?? action.input.cwd ?? ''));
+    const registry = await this.#readRegistry();
+    const project = await this.#matchProject(registry, projectRoot);
+    if (!project) throw new OperatorError('PROJECT_COMMANDS_NOT_REGISTERED', 'No trusted command registry entry exists for this project.');
+    const commandId = validateCommandId(String(action.input.commandId ?? ''));
+    const command = project.commands.find((candidate) => candidate.id === commandId);
+    if (!command) throw new OperatorError('PROJECT_COMMAND_NOT_REGISTERED', `Trusted command ${commandId} is not registered for this project.`);
+    return command.risk              ;
+  }
+
+  async execute(action               , context                             = {})                        {
+    const started = performance.now();
+    try {
+      const projectRoot = await this.#scope.resolveExisting(String(action.input.path ?? action.input.cwd ?? ''));
+      const registry = await this.#readRegistry();
+      const project = await this.#matchProject(registry, projectRoot);
+
+      if (action.capability === 'project.command.inspect') {
+        return {
+          ok: true,
+          capability: action.capability,
+          provider: this.name,
+          output: {
+            projectRoot,
+            registryConfigured: registry !== null,
+            registryLocation: 'operator-local-config',
+            commands: project?.commands.map(({ id, title, kind, executable, args, cwd, timeoutMs, risk, artifacts }) => ({
+              id,
+              title,
+              kind,
+              executable,
+              args,
+              cwd,
+              timeoutMs,
+              risk,
+              artifacts
+            })) ?? []
+          },
+          evidence: [
+            evidence('command_registry', 'pass', 'Returned only commands from the trusted local Operator registry; project manifests were not treated as executable authority.', {
+              projectRoot,
+              commandCount: project?.commands.length ?? 0,
+              registryConfigured: registry !== null
+            })
+          ],
+          durationMs: Math.round(performance.now() - started)
+        };
+      }
+
+      if (!project) throw new OperatorError('PROJECT_COMMANDS_NOT_REGISTERED', 'No trusted command registry entry exists for this project.');
+      const commandId = validateCommandId(String(action.input.commandId ?? ''));
+      const command = project.commands.find((candidate) => candidate.id === commandId);
+      if (!command) throw new OperatorError('PROJECT_COMMAND_NOT_REGISTERED', `Trusted command ${commandId} is not registered for this project.`);
+
+      const expectedRisk = String(action.input.expectedRisk ?? '');
+      if (expectedRisk !== command.risk) {
+        throw new OperatorError('PROJECT_COMMAND_RISK_MISMATCH', 'Caller must acknowledge the command risk declared in the trusted registry.', {
+          details: { expectedRisk, registeredRisk: command.risk }
+        });
+      }
+      if (action.risk !== command.risk) {
+        throw new OperatorError('PROJECT_COMMAND_ACTION_RISK_MISMATCH', 'The action risk evaluated by local policy must exactly match the trusted registry risk.', {
+          details: { actionRisk: action.risk, registeredRisk: command.risk }
+        });
+      }
+
+      const cwd = await resolveCommandCwd(projectRoot, command.cwd);
+      const beforeArtifacts = await snapshotArtifacts(projectRoot, command.artifacts);
+      const process = new ProcessProvider({
+        allowedRoots: [projectRoot],
+        allowedExecutables: [...this.#allowedExecutables]
+      });
+      const result = await process.execute({
+        ...action,
+        capability: 'terminal.execute',
+        risk: command.risk              ,
+        input: {
+          executable: command.executable,
+          args: command.args,
+          cwd,
+          timeoutMs: command.timeoutMs
+        },
+        provenance: { kind: 'trusted_policy', source: `project-command:${command.id}` }
+      }, context);
+
+      const baseOutput = {
+        command: {
+          id: command.id,
+          title: command.title,
+          kind: command.kind,
+          executable: command.executable,
+          args: command.args,
+          cwd: command.cwd,
+          risk: command.risk,
+          artifacts: command.artifacts
+        },
+        execution: result.output
+      };
+
+      if (!result.ok) {
+        return {
+          ...result,
+          capability: action.capability,
+          provider: this.name,
+          output: {
+            ...baseOutput,
+            validation: {
+              configured: command.artifacts.length > 0,
+              passed: false,
+              skipped: true,
+              reason: 'command_failed',
+              artifacts: []
+            }
+          },
+          evidence: [
+            evidence('command_registry', 'pass', 'Executed an explicitly registered trusted project command through the shell-free process provider.', {
+              commandId: command.id,
+              executable: command.executable,
+              risk: command.risk,
+              cwd
+            }),
+            ...result.evidence
+          ]
+        };
+      }
+
+      const validations = await validateArtifacts(projectRoot, command.artifacts, beforeArtifacts);
+      const validationPassed = validations.every((item) => item.passed);
+      const validation = {
+        configured: command.artifacts.length > 0,
+        passed: validationPassed,
+        skipped: false,
+        artifacts: validations
+      };
+      const validationEvidence = command.artifacts.length === 0
+        ? evidence('artifact_validation', 'info', 'Trusted command has no declared artifact validators.', { commandId: command.id })
+        : evidence('artifact_validation', validationPassed ? 'pass' : 'fail', validationPassed
+          ? 'All trusted artifact postconditions passed.'
+          : 'One or more trusted artifact postconditions failed.', {
+          commandId: command.id,
+          artifactCount: validations.length,
+          failed: validations.filter((item) => !item.passed).map((item) => item.path)
+        });
+
+      return {
+        ...result,
+        ok: validationPassed,
+        capability: action.capability,
+        provider: this.name,
+        output: { ...baseOutput, validation },
+        evidence: [
+          evidence('command_registry', 'pass', 'Executed an explicitly registered trusted project command through the shell-free process provider.', {
+            commandId: command.id,
+            executable: command.executable,
+            risk: command.risk,
+            cwd
+          }),
+          ...result.evidence,
+          validationEvidence
+        ],
+        error: validationPassed ? undefined : {
+          code: 'ARTIFACT_VALIDATION_FAILED',
+          message: 'Command exited successfully but trusted artifact validation failed.',
+          retryable: false
+        }
+      };
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('PROJECT_COMMAND_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('command_registry', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  async #readRegistry()                           {
+    let realRegistry        ;
+    try {
+      realRegistry = await fs.realpath(this.#registryPath);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return null;
+      throw error;
+    }
+
+    for (const root of this.#allowedRoots) {
+      let realRoot = root;
+      try { realRoot = await fs.realpath(root); } catch { /* retain lexical root */ }
+      if (isWithin(this.#registryPath, root) || isWithin(realRegistry, realRoot)) {
+        throw new OperatorError('COMMAND_REGISTRY_INSIDE_PROJECT_DENIED', 'Trusted command registry must live outside all project-authorized roots so project files cannot rewrite execution authority.');
+      }
+    }
+
+    let raw        ;
+    try {
+      raw = await readDurableStateText(this.#registryPath, REGISTRY_OPTIONS);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return null;
+      throw error;
+    }
+
+    let parsed         ;
+    try { parsed = JSON.parse(raw); } catch {
+      throw new OperatorError('COMMAND_REGISTRY_INVALID', 'Trusted command registry is not valid JSON.');
+    }
+    return validateRegistry(parsed, this.#allowedExecutables);
+  }
+
+  async #matchProject(registry                 , requestedRoot        )                                      {
+    if (!registry) return undefined;
+    const canonicalAllowedRoots = await Promise.all(this.#allowedRoots.map(async (root) => {
+      try { return await fs.realpath(root); } catch { return root; }
+    }));
+    for (const project of registry.projects) {
+      const plausiblyInScope = this.#allowedRoots.some((root) => isWithin(project.root, root))
+        || canonicalAllowedRoots.some((root) => isWithin(project.root, root));
+      if (!plausiblyInScope) continue;
+      let canonical        ;
+      try {
+        canonical = await this.#scope.resolveExisting(project.root);
+      } catch (error) {
+        if (error instanceof OperatorError && error.code === 'PATH_OUTSIDE_SCOPE') continue;
+        throw error;
+      }
+      if (canonical === requestedRoot) return { ...project, root: canonical };
+    }
+    return undefined;
+  }
+}
+
+function validateRegistry(input         , allowedExecutables             )           {
+  if (!input || typeof input !== 'object') throw new OperatorError('COMMAND_REGISTRY_INVALID', 'Trusted command registry must be an object.');
+  const raw = input                           ;
+  if (raw.version !== 1 || !Array.isArray(raw.projects) || raw.projects.length > 100) {
+    throw new OperatorError('COMMAND_REGISTRY_INVALID', 'Trusted command registry requires version=1 and at most 100 projects.');
+  }
+  const projects = raw.projects.map((entry, projectIndex)                 => {
+    if (!entry || typeof entry !== 'object') throw new OperatorError('COMMAND_REGISTRY_INVALID', `Project entry ${projectIndex} is invalid.`);
+    const project = entry                           ;
+    const root = String(project.root ?? '');
+    if (!path.isAbsolute(root)) throw new OperatorError('COMMAND_REGISTRY_INVALID', `Project ${projectIndex} root must be absolute.`);
+    if (!Array.isArray(project.commands) || project.commands.length > MAX_COMMANDS_PER_PROJECT) {
+      throw new OperatorError('COMMAND_REGISTRY_INVALID', `Project ${projectIndex} commands must be an array of at most ${MAX_COMMANDS_PER_PROJECT}.`);
+    }
+    const seen = new Set        ();
+    const commands = project.commands.map((candidate, commandIndex)                 => {
+      if (!candidate || typeof candidate !== 'object') throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandIndex} is invalid.`);
+      const command = candidate                           ;
+      const id = validateCommandId(String(command.id ?? ''));
+      if (seen.has(id)) throw new OperatorError('COMMAND_REGISTRY_INVALID', `Duplicate command id ${id}.`);
+      seen.add(id);
+      const executable = String(command.executable ?? '');
+      if (!/^[A-Za-z0-9._+-]+(?:\.exe)?$/i.test(executable) || !allowedExecutables.has(executable.toLowerCase())) {
+        throw new OperatorError('COMMAND_EXECUTABLE_DENIED', `Command ${id} executable is not in the local-agent executable allowlist.`);
+      }
+      const args = Array.isArray(command.args) ? command.args.map((value) => String(value)) : [];
+      if (args.length > 200 || args.some((arg) => arg.length > 4000 || arg.includes('\0'))) {
+        throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${id} arguments exceed bounds.`);
+      }
+      const cwd = String(command.cwd ?? '.');
+      if (path.isAbsolute(cwd) || cwd.includes('\0')) throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${id} cwd must be relative.`);
+      const timeoutMs = Math.min(Math.max(Number(command.timeoutMs ?? DEFAULT_TIMEOUT_MS), 100), 10 * 60_000);
+      const risk = String(command.risk ?? 'write');
+      if (!['read', 'write', 'external'].includes(risk)) throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${id} risk is invalid.`);
+      const kind = typeof command.kind === 'string' && ['build', 'test', 'lint', 'format', 'dev', 'database', 'custom'].includes(command.kind)
+        ? command.kind                          
+        : undefined;
+      const title = typeof command.title === 'string' ? command.title.trim().slice(0, 160) || undefined : undefined;
+      const rawArtifacts = command.artifacts === undefined ? [] : command.artifacts;
+      if (!Array.isArray(rawArtifacts) || rawArtifacts.length > MAX_ARTIFACTS_PER_COMMAND) {
+        throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${id} artifacts must be an array of at most ${MAX_ARTIFACTS_PER_COMMAND}.`);
+      }
+      const artifacts = rawArtifacts.map((rawArtifact, artifactIndex)                  => validateArtifact(rawArtifact, id, artifactIndex));
+      return { id, title, kind, executable, args, cwd, timeoutMs, risk: risk                          , artifacts };
+    });
+    return { root: path.resolve(root), commands };
+  });
+  return { version: 1, projects };
+}
+
+function validateArtifact(input         , commandId        , index        )                  {
+  if (!input || typeof input !== 'object') throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandId} artifact ${index} is invalid.`);
+  const raw = input                           ;
+  const artifactPath = String(raw.path ?? '').trim();
+  if (!artifactPath || artifactPath.length > 1000 || artifactPath.includes('\0') || artifactPath.includes('\r') || artifactPath.includes('\n') || path.isAbsolute(artifactPath)) {
+    throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandId} artifact ${index} path must be a bounded relative path.`);
+  }
+  const normalized = path.normalize(artifactPath);
+  if (normalized === '..' || normalized.startsWith(`..${path.sep}`) || path.isAbsolute(normalized)) {
+    throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandId} artifact ${index} escapes the project root.`);
+  }
+  const kind = String(raw.kind ?? 'file');
+  if (!['file', 'directory', 'json'].includes(kind)) throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandId} artifact ${index} kind is invalid.`);
+  const minBytesValue = Number(raw.minBytes ?? (kind === 'directory' ? 0 : 1));
+  if (!Number.isSafeInteger(minBytesValue) || minBytesValue < 0 || minBytesValue > 1024 * 1024 * 1024) {
+    throw new OperatorError('COMMAND_REGISTRY_INVALID', `Command ${commandId} artifact ${index} minBytes is invalid.`);
+  }
+  return {
+    path: artifactPath,
+    kind: kind                           ,
+    minBytes: minBytesValue,
+    mustChange: raw.mustChange === true
+  };
+}
+
+function validateCommandId(value        )         {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value)) throw new OperatorError('INVALID_COMMAND_ID', 'commandId must be 1-64 safe identifier characters.');
+  return value;
+}
+
+async function resolveCommandCwd(projectRoot        , relativeCwd        )                  {
+  const absolute = path.resolve(projectRoot, relativeCwd);
+  if (!isWithin(absolute, projectRoot)) throw new OperatorError('COMMAND_CWD_OUTSIDE_PROJECT', 'Registered command cwd escapes the project root.');
+  const stat = await fs.stat(absolute);
+  if (!stat.isDirectory()) throw new OperatorError('COMMAND_CWD_INVALID', 'Registered command cwd is not an existing directory.');
+  return absolute;
+}
+
+async function snapshotArtifacts(projectRoot        , artifacts                   )                                         {
+  const output = new Map                          ();
+  for (const artifact of artifacts) {
+    const snapshot = await snapshotArtifact(projectRoot, artifact.path);
+    if (snapshot.type === 'symlink' || snapshot.type === 'hardlink') {
+      throw new OperatorError('ARTIFACT_FILE_INVALID', `Trusted artifact ${artifact.path} must not be a symbolic or hard link.`);
+    }
+    output.set(artifact.path, snapshot);
+  }
+  return output;
+}
+
+async function snapshotArtifact(projectRoot        , relativePath        )                            {
+  const absolute = path.resolve(projectRoot, relativePath);
+  if (!isWithin(absolute, projectRoot)) throw new OperatorError('ARTIFACT_PATH_OUTSIDE_PROJECT', `Artifact ${relativePath} escapes the project root.`);
+  const canonicalProjectRoot = await fs.realpath(projectRoot);
+  try {
+    const stat = await fs.lstat(absolute);
+    if (stat.isSymbolicLink()) return { path: relativePath, exists: true, type: 'symlink', size: stat.size };
+
+    const canonical = await fs.realpath(absolute);
+    if (!isWithin(canonical, canonicalProjectRoot)) {
+      throw new OperatorError('ARTIFACT_PATH_OUTSIDE_PROJECT', `Artifact ${relativePath} resolves outside the project root.`);
+    }
+    const canonicalStat = await fs.lstat(canonical);
+    if (!sameFile(stat, canonicalStat)) {
+      throw new OperatorError('ARTIFACT_PATH_CHANGED', `Artifact ${relativePath} changed while its path was being resolved.`);
+    }
+
+    if (canonicalStat.isDirectory()) {
+      const entries = (await fs.readdir(canonical)).sort();
+      const current = await fs.realpath(absolute);
+      if (current !== canonical) throw new OperatorError('ARTIFACT_PATH_CHANGED', `Artifact ${relativePath} changed while it was being inspected.`);
+      const fingerprint = crypto.createHash('sha256').update(entries.join('\0')).digest('hex');
+      return { path: relativePath, exists: true, type: 'directory', size: entries.length, fingerprint };
+    }
+    if (canonicalStat.isFile()) {
+      if (canonicalStat.nlink !== 1) return { path: relativePath, exists: true, type: 'hardlink', size: canonicalStat.size };
+      const fingerprint = canonicalStat.size <= MAX_HASH_ARTIFACT_BYTES
+        ? crypto.createHash('sha256').update(await readDurableStateBytes(canonical, ARTIFACT_FILE_OPTIONS)).digest('hex')
+        : crypto.createHash('sha256').update(`${canonicalStat.size}\0${canonicalStat.mtimeMs}`).digest('hex');
+      const current = await fs.realpath(absolute);
+      if (current !== canonical) throw new OperatorError('ARTIFACT_PATH_CHANGED', `Artifact ${relativePath} changed while it was being inspected.`);
+      return { path: relativePath, exists: true, type: 'file', size: canonicalStat.size, fingerprint };
+    }
+    return { path: relativePath, exists: true, type: 'other', size: canonicalStat.size };
+  } catch (error) {
+    if ((error                         ).code === 'ENOENT') {
+      await assertNearestExistingParentInsideProject(absolute, canonicalProjectRoot, relativePath);
+      return { path: relativePath, exists: false };
+    }
+    throw error;
+  }
+}
+
+async function validateArtifacts(
+  projectRoot        ,
+  artifacts                   ,
+  before                               
+)                                {
+  const validations                       = [];
+  for (const artifact of artifacts) {
+    const beforeSnapshot = before.get(artifact.path) ?? { path: artifact.path, exists: false };
+    const after = await snapshotArtifact(projectRoot, artifact.path);
+    const checks                               = [];
+    checks.push({ check: 'exists', passed: after.exists, detail: after.exists ? 'Artifact exists.' : 'Artifact is missing.' });
+
+    const expectedType = artifact.kind === 'directory' ? 'directory' : 'file';
+    const typePassed = after.exists && after.type === expectedType;
+    checks.push({ check: 'type', passed: typePassed, detail: typePassed
+      ? `Artifact type is ${expectedType}.`
+      : `Expected ${expectedType}; observed ${after.type ?? 'missing'}.` });
+
+    if (expectedType === 'file') {
+      const size = after.size ?? 0;
+      checks.push({ check: 'minBytes', passed: typePassed && size >= artifact.minBytes, detail: `Observed ${size} bytes; required at least ${artifact.minBytes}.` });
+    }
+
+    if (after.type === 'symlink') {
+      checks.push({ check: 'symlink', passed: false, detail: 'Artifact symlinks are not accepted for trusted validation.' });
+    }
+    if (after.type === 'hardlink') {
+      checks.push({ check: 'hardlink', passed: false, detail: 'Hard-linked artifact files are not accepted for trusted validation.' });
+    }
+
+    if (artifact.mustChange) {
+      const changed = after.exists && (!beforeSnapshot.exists || after.type !== beforeSnapshot.type || after.fingerprint !== beforeSnapshot.fingerprint || after.size !== beforeSnapshot.size);
+      checks.push({ check: 'mustChange', passed: changed, detail: changed ? 'Artifact changed during this command run.' : 'Artifact did not change during this command run.' });
+    }
+
+    if (artifact.kind === 'json') {
+      let jsonPassed = false;
+      let detail = 'JSON artifact is unavailable.';
+      if (after.type === 'file') {
+        if ((after.size ?? 0) > MAX_JSON_ARTIFACT_BYTES) {
+          detail = `JSON artifact exceeds ${MAX_JSON_ARTIFACT_BYTES} byte parse limit.`;
+        } else {
+          try {
+            JSON.parse(await readTrustedArtifactText(projectRoot, artifact.path, MAX_JSON_ARTIFACT_BYTES));
+            jsonPassed = true;
+            detail = 'JSON artifact parsed successfully.';
+          } catch (error) {
+            if (error instanceof OperatorError) throw error;
+            detail = 'JSON artifact is not valid JSON.';
+          }
+        }
+      }
+      checks.push({ check: 'json', passed: jsonPassed, detail });
+    }
+
+    validations.push({
+      path: artifact.path,
+      kind: artifact.kind,
+      passed: checks.every((check) => check.passed),
+      checks,
+      before: beforeSnapshot,
+      after
+    });
+  }
+  return validations;
+}
+
+async function readTrustedArtifactText(projectRoot        , relativePath        , maxBytes        )                  {
+  const absolute = path.resolve(projectRoot, relativePath);
+  const canonicalProjectRoot = await fs.realpath(projectRoot);
+  const stat = await fs.lstat(absolute);
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
+    throw new OperatorError('ARTIFACT_FILE_INVALID', `Trusted artifact ${relativePath} must be a single-link regular file.`);
+  }
+  const canonical = await fs.realpath(absolute);
+  if (!isWithin(canonical, canonicalProjectRoot)) {
+    throw new OperatorError('ARTIFACT_PATH_OUTSIDE_PROJECT', `Artifact ${relativePath} resolves outside the project root.`);
+  }
+  const raw = await readDurableStateBytes(canonical, {
+    maxBytes,
+    errorCode: 'ARTIFACT_FILE_INVALID',
+    invalidMessage: `Trusted artifact ${relativePath} is invalid.`
+  });
+  const current = await fs.realpath(absolute);
+  if (current !== canonical) throw new OperatorError('ARTIFACT_PATH_CHANGED', `Artifact ${relativePath} changed while it was being read.`);
+  return raw.toString('utf8');
+}
+
+async function assertNearestExistingParentInsideProject(absolute        , canonicalProjectRoot        , relativePath        )                {
+  let current = path.dirname(absolute);
+  while (true) {
+    try {
+      const canonical = await fs.realpath(current);
+      if (!isWithin(canonical, canonicalProjectRoot)) {
+        throw new OperatorError('ARTIFACT_PATH_OUTSIDE_PROJECT', `Artifact ${relativePath} has a parent directory outside the project root.`);
+      }
+      return;
+    } catch (error) {
+      if ((error                         ).code !== 'ENOENT') throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      current = parent;
+    }
+  }
+}
+
+function sameFile(left                              , right                              )          {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function isWithin(candidate        , root        )          {
+  const rel = path.relative(path.resolve(root), path.resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}