chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/rail-adjudication-evidence.js

@@ -1,10 +1,11 @@
 import {
-  closeSync, constants, fstatSync, fsyncSync, linkSync, mkdirSync,
-  openSync, readSync, unlinkSync, writeSync,
+  closeSync, constants, fstatSync, fsyncSync, openSync, readSync, writeSync,
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, join, parse, resolve, sep } from 'node:path';
-import { canonicalize, sha256 } from '@chati/core';
+import {
+  canonicalize, directoryPathSync, linkAtSync, mkdirAtSync, openAtSync, sha256, unlinkAtSync,
+} from '@chati/core';
 
 function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
 const MAX_EVIDENCE_BYTES = 4 * 1024 * 1024;
@@ -41,8 +42,8 @@ function readDescriptorBounded(descriptor) {
 }
 
 function openPinnedEvidenceDirectory(path, { create = true } = {}) {
-  if (process.platform !== 'linux') {
-    fail('UNSUPPORTED_ADJUDICATION_EVIDENCE_PLATFORM', 'RAIL adjudication evidence requires Linux descriptor-relative filesystem operations');
+  if (!['linux', 'darwin'].includes(process.platform)) {
+    fail('UNSUPPORTED_ADJUDICATION_EVIDENCE_PLATFORM', `RAIL adjudication evidence requires descriptor-relative operations; unsupported platform: ${process.platform}`);
   }
   const absolute = resolve(path);
   const root = parse(absolute).root;
@@ -50,10 +51,9 @@ function openPinnedEvidenceDirectory(path, { create = true } = {}) {
   let descriptor = openSync(root, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
   try {
     for (const segment of segments) {
-      const childPath = join(`/proc/self/fd/${descriptor}`, segment);
       let childDescriptor;
       try {
-        childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        childDescriptor = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
       } catch (error) {
         if (error?.code !== 'ENOENT' || !create) {
           if (['ELOOP', 'ENOTDIR'].includes(error?.code)) {
@@ -61,9 +61,9 @@ function openPinnedEvidenceDirectory(path, { create = true } = {}) {
           }
           throw error;
         }
-        try { mkdirSync(childPath, { mode: 0o700 }); }
+        try { mkdirAtSync(descriptor, segment, { mode: 0o700 }); }
         catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
-        childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        childDescriptor = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
       }
       const stat = fstatSync(childDescriptor);
       if (!stat.isDirectory()) {
@@ -77,7 +77,6 @@ function openPinnedEvidenceDirectory(path, { create = true } = {}) {
       absolute,
       descriptor,
       identity: fstatSync(descriptor),
-      reference: `/proc/self/fd/${descriptor}`,
     });
   } catch (error) {
     closeSync(descriptor);
@@ -85,13 +84,6 @@ function openPinnedEvidenceDirectory(path, { create = true } = {}) {
   }
 }
 
-function evidenceEntryPath(directory, name) {
-  if (basename(name) !== name || name === '.' || name === '..') {
-    fail('UNSAFE_ADJUDICATION_EVIDENCE_FILE', 'adjudication evidence entry must be one path segment');
-  }
-  return join(directory.reference, name);
-}
-
 function assertPinnedEvidenceDirectory(directory) {
   const descriptorStat = fstatSync(directory.descriptor);
   if (!descriptorStat.isDirectory() || !sameIdentity(descriptorStat, directory.identity)) {
@@ -117,10 +109,9 @@ function readRegular(path, { allowMissing = false, directory = null } = {}) {
     try { activeDirectory = openPinnedEvidenceDirectory(dirname(path), { create: false }); }
     catch (error) { if (allowMissing && error?.code === 'ENOENT') return null; throw error; }
   }
-  const entry = evidenceEntryPath(activeDirectory, basename(path));
   let descriptor;
   try {
-    descriptor = openSync(entry, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    descriptor = openAtSync(activeDirectory.descriptor, basename(path), constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
   } catch (error) {
     if (ownedDirectory) closeSync(activeDirectory.descriptor);
     if (allowMissing && error?.code === 'ENOENT') return null;
@@ -162,8 +153,8 @@ function persistImmutable(path, serialized) {
   const directory = openPinnedEvidenceDirectory(dirname(path));
   const name = basename(path);
   const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
-  const temporary = evidenceEntryPath(directory, temporaryName);
-  const destination = evidenceEntryPath(directory, name);
+  // Diagnostic/test-hook path only. Actual reads and mutations use *at ops.
+  const temporary = join(directoryPathSync(directory.descriptor), temporaryName);
   let temporaryDescriptor;
   try {
     const existing = readRegular(path, { allowMissing: true, directory });
@@ -172,7 +163,7 @@ function persistImmutable(path, serialized) {
       return false;
     }
     runSecurityTestHook('beforeEvidenceTempOpen', { path, temporary, directory: directory.absolute });
-    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    temporaryDescriptor = openAtSync(directory.descriptor, temporaryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
     runSecurityTestHook('afterEvidenceTempOpen', { path, temporary, directory: directory.absolute });
     let offset = 0;
     while (offset < bytes.length) offset += writeSync(temporaryDescriptor, bytes, offset, bytes.length - offset);
@@ -181,7 +172,7 @@ function persistImmutable(path, serialized) {
     temporaryDescriptor = undefined;
     assertPinnedEvidenceDirectory(directory);
     runSecurityTestHook('beforeEvidenceCommit', { path, temporary, directory: directory.absolute });
-    try { linkSync(temporary, destination); }
+    try { linkAtSync(directory.descriptor, temporaryName, directory.descriptor, name); }
     catch (error) {
       if (error?.code !== 'EEXIST') throw error;
       const raced = readRegular(path, { directory });
@@ -194,7 +185,7 @@ function persistImmutable(path, serialized) {
     return true;
   } finally {
     if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
-    try { unlinkSync(temporary); } catch { /* preserve the primary result */ }
+    try { unlinkAtSync(directory.descriptor, temporaryName); } catch { /* preserve the primary result */ }
     fsyncSync(directory.descriptor);
     closeSync(directory.descriptor);
   }

package/src/orchestrator/rail-human-effort-authority.js

@@ -0,0 +1,46 @@
+import { canonicalSerialize } from '@chati/core';
+import { installationAuthorityProjectBinding, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+
+export const HUMAN_EFFORT_AUTHORITY_DOMAIN = 'chati.rail-human-effort.v1';
+const COMMON = ['schema_version', 'purpose', 'session_id', 'attempt_id', 'handoff_id', 'task_id',
+  'project_binding', 'operator_id', 'claim_id', 'account', 'observed_at', 'phase'];
+const FINAL = ['opened_receipt_digest', 'declaration', 'intervals', 'elapsed_ms', 'value', 'unit'];
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+
+export function verifyHumanEffortReceipt(receipt, { projectDir, authorityDirectory, expected = {} } = {}) {
+  try {
+    if (!['opened', 'finished', 'interrupted'].includes(receipt?.phase)) return false;
+    const keys = [...COMMON, ...(receipt.phase === 'opened' ? [] : FINAL), 'authority_id', 'authority_signature'];
+    if (!exact(receipt, keys) || receipt.schema_version !== 1 || receipt.purpose !== 'rail_human_effort') return false;
+    for (const key of ['session_id', 'attempt_id', 'handoff_id', 'task_id', 'operator_id', 'claim_id', 'observed_at']) {
+      if (typeof receipt[key] !== 'string' || !receipt[key].trim()) return false;
+    }
+    if (!/^human-effort-[a-f0-9-]{36}$/.test(receipt.session_id) || !Number.isFinite(Date.parse(receipt.observed_at))) return false;
+    if (!exact(receipt.account, ['uid', 'username', 'hostname']) || !Number.isInteger(receipt.account.uid)
+      || receipt.account.uid < 0 || !['username', 'hostname'].every((key) => typeof receipt.account[key] === 'string' && receipt.account[key])) return false;
+    if (canonicalSerialize(receipt.project_binding) !== canonicalSerialize(installationAuthorityProjectBinding(projectDir, receipt.project_binding.project_id))) return false;
+    if (Object.entries(expected).some(([key, value]) => canonicalSerialize(receipt[key]) !== canonicalSerialize(value))) return false;
+    if (receipt.phase !== 'opened') {
+      if (!/^[a-f0-9]{64}$/.test(receipt.opened_receipt_digest) || !finite(receipt.elapsed_ms)
+        || receipt.unit !== 'milliseconds' || !Array.isArray(receipt.intervals) || receipt.intervals.length > 1024) return false;
+      let prior = 0;
+      let value = 0;
+      for (const interval of receipt.intervals) {
+        if (!exact(interval, ['start_ms', 'end_ms']) || !finite(interval.start_ms) || !finite(interval.end_ms)
+          || interval.start_ms < prior || interval.end_ms < interval.start_ms || interval.end_ms > receipt.elapsed_ms) return false;
+        prior = interval.end_ms;
+        value += interval.end_ms - interval.start_ms;
+      }
+      if (receipt.phase === 'interrupted') {
+        if (receipt.declaration !== 'incomplete' || receipt.value !== null) return false;
+      } else if (receipt.declaration === 'zero-effort') {
+        if (receipt.intervals.length !== 0 || receipt.value !== 0) return false;
+      } else if (receipt.declaration !== 'timed-effort' || receipt.intervals.length === 0 || !finite(receipt.value) || receipt.value !== value) return false;
+    }
+    const { authority_id, authority_signature, ...payload } = receipt;
+    return verifyHostAuthorityPayload(payload, { domain: HUMAN_EFFORT_AUTHORITY_DOMAIN,
+      authorityId: authority_id, signature: authority_signature, authorityDirectory });
+  } catch { return false; }
+}

package/src/orchestrator/rail-human-effort.js

@@ -0,0 +1,149 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, realpathSync } from 'node:fs';
+import { hostname, userInfo } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline';
+import { sha256, tryExclusiveFileLockSync } from '@chati/core';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { installationAuthorityProjectBinding, installationAuthorityStateDirectory, signHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+import { createProjectRailEngine, resolveRailAttemptContext } from './rail-runtime.js';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { HUMAN_EFFORT_AUTHORITY_DOMAIN } from './rail-human-effort-authority.js';
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+
+function acquireEffortLock(projectDir, authorityDirectory) {
+  const root = installationAuthorityStateDirectory(authorityDirectory);
+  if (root === projectDir || root.startsWith(`${projectDir}${sep}`) || projectDir.startsWith(`${root}${sep}`)) {
+    fail('HUMAN_EFFORT_STORAGE_OVERLAP', 'human effort lock must remain outside the project in private authority storage');
+  }
+  const path = join(root, 'human-effort.lock');
+  const content = 'chati-human-effort-lock-v1\n';
+  persistImmutableInstallationFile(path, content, { label: 'human effort host lock', maxBytes: 1024 });
+  const source = readSafeInstallationStorageFile(path, { maxBytes: 1024 });
+  const fd = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  const same = (stat) => stat.dev === source.stat.dev && stat.ino === source.stat.ino
+    && stat.isFile() && stat.nlink === 1n && (stat.mode & 0o777n) === 0o600n && stat.uid === BigInt(userInfo().uid);
+  const assertStable = () => {
+    const current = readSafeInstallationStorageFile(path, { maxBytes: 1024 });
+    if (!same(fstatSync(fd, { bigint: true })) || !same(current.stat) || current.content !== content) {
+      fail('HUMAN_EFFORT_LOCK_CHANGED', 'human effort lock identity or permissions changed during measurement');
+    }
+  };
+  try {
+    assertStable();
+    if (!tryExclusiveFileLockSync(fd)) fail('HUMAN_EFFORT_ALREADY_ACTIVE', 'this host account already has an active human effort session');
+    assertStable();
+    return { assertStable, close: () => closeSync(fd) };
+  } catch (error) { closeSync(fd); throw error; }
+}
+
+/** Live, monotonic supervisor. No API accepts a duration or a finished report. */
+export function openHumanEffortSession(input = {}) {
+  const keys = ['projectDir', 'handoff_id', 'attempt_id', 'authorityDirectory'];
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some((key) => !keys.includes(key))
+    || ['projectDir', 'handoff_id', 'attempt_id'].some((key) => typeof input[key] !== 'string' || !input[key].trim())) {
+    fail('HUMAN_EFFORT_INPUT_INVALID', 'human effort accepts only canonical project, handoff and attempt identifiers');
+  }
+  const projectDir = realpathSync(resolve(input.projectDir));
+  const context = resolveRailAttemptContext({ ...input, projectDir });
+  const artifact = loadRuntimeInstallationV2(projectDir);
+  if (!artifact || artifact.project_id !== context.handoff.project_id) fail('V2_INSTALLATION_REQUIRED', 'human effort requires the verified project installation');
+  if (!['active', 'ready_to_merge'].includes(context.state)) fail('HUMAN_EFFORT_ATTEMPT_INACTIVE', 'human effort session requires an unfinished attempt');
+  const account = userInfo();
+  const base = { schema_version: 1, purpose: 'rail_human_effort', session_id: `human-effort-${randomUUID()}`,
+    project_binding: installationAuthorityProjectBinding(projectDir, artifact.project_id),
+    attempt_id: input.attempt_id, handoff_id: input.handoff_id, task_id: context.task.task_id,
+    operator_id: context.claim.operator_id, claim_id: context.claim.claim_id,
+    account: { uid: account.uid, username: account.username, hostname: hostname() } };
+  const lock = acquireEffortLock(projectDir, input.authorityDirectory);
+  const origin = process.hrtime.bigint();
+  const offset = () => Number(process.hrtime.bigint() - origin) / 1e6;
+  let state = 'ready';
+  let activeStart;
+  const intervals = [];
+  let opened;
+  const persist = (payload) => {
+    lock.assertStable();
+    const proof = signHostAuthorityPayload(payload, { domain: HUMAN_EFFORT_AUTHORITY_DOMAIN, authorityDirectory: input.authorityDirectory });
+    const receipt = { ...payload, authority_id: proof.authority_id, authority_signature: proof.signature };
+    const record = createProjectRailEngine({ projectDir, humanAuthorityDirectory: input.authorityDirectory })
+      .recordHumanEffortObservation({ attempt_id: input.attempt_id, receipt });
+    return { receipt, event_id: record.event_id };
+  };
+  try { opened = persist({ ...base, phase: 'opened', observed_at: new Date().toISOString() }); }
+  catch (error) { lock.close(); throw error; }
+  const result = () => Object.freeze({ ok: true, session_id: base.session_id, status: state, language: context.language });
+  return Object.freeze({
+    status: result,
+    transition(action) {
+      if (!['start', 'pause', 'resume', 'finish', 'zero', 'interrupt'].includes(action) || ['finished', 'interrupted'].includes(state)) {
+        fail('HUMAN_EFFORT_TRANSITION_INVALID', 'invalid human effort command or session already closed');
+      }
+      if ((action === 'start' || action === 'zero') && state !== 'ready'
+        || action === 'pause' && state !== 'active' || action === 'resume' && state !== 'paused'
+        || action === 'finish' && !['active', 'paused'].includes(state)) {
+        fail('HUMAN_EFFORT_TRANSITION_INVALID', `cannot ${action} while ${state}`);
+      }
+      try { lock.assertStable(); }
+      catch (error) { state = 'interrupted'; lock.close(); throw error; }
+      const now = offset();
+      if (action === 'start' || action === 'resume') {
+        if (intervals.length >= 1024) fail('HUMAN_EFFORT_INTERVAL_LIMIT', 'finish this bounded session before starting more intervals');
+        activeStart = now;
+        state = 'active';
+        return result();
+      }
+      if (state === 'active') { intervals.push({ start_ms: activeStart, end_ms: now }); activeStart = undefined; }
+      if (action === 'pause') { state = 'paused'; return result(); }
+      state = action === 'interrupt' ? 'interrupted' : 'finished';
+      try {
+        const final = persist({ ...base, phase: state, observed_at: new Date().toISOString(),
+          opened_receipt_digest: sha256(opened.receipt), declaration: action === 'interrupt' ? 'incomplete' : action === 'zero' ? 'zero-effort' : 'timed-effort',
+          intervals, elapsed_ms: now, unit: 'milliseconds',
+          value: action === 'interrupt' ? null : intervals.reduce((total, interval) => total + (interval.end_ms - interval.start_ms), 0) });
+        return Object.freeze({ ...result(), ok: state === 'finished', source_event_id: final.event_id,
+          receipt_ref: `rail-human-effort://sha256/${sha256(final.receipt)}` });
+      } finally { lock.close(); }
+    },
+  });
+}
+
+export function collectRailHumanEffort({ projectDir, attempt_id, authorityDirectory }) {
+  return createProjectRailEngine({ projectDir, humanAuthorityDirectory: authorityDirectory }).humanEffortForAttempt(attempt_id);
+}
+
+/** Explicit operator interaction, never piped duration JSON or inferred presence. */
+export async function runHumanEffortTerminal(input) {
+  if (!process.stdin.isTTY) fail('HUMAN_EFFORT_TTY_REQUIRED', 'human effort requires an interactive terminal declaration');
+  const session = openHumanEffortSession(input);
+  const instructions = {
+    en: 'Declare your active effort: start, pause, resume, finish. Use zero only to explicitly declare no human effort. EOF/interrupt leaves effort incomplete.',
+    pt: 'Declare seu esforço ativo: start, pause, resume, finish. Use zero somente para declarar explicitamente ausência de esforço humano. EOF/interrupção deixa o registro incompleto.',
+    fr: 'Déclarez votre effort actif : start, pause, resume, finish. Utilisez zero uniquement pour déclarer explicitement aucun effort humain. EOF/interruption laisse le relevé incomplet.',
+    es: 'Declare su esfuerzo activo: start, pause, resume, finish. Use zero solo para declarar explícitamente ningún esfuerzo humano. EOF/interrupción deja el registro incompleto.',
+  };
+  process.stderr.write(`${instructions[session.status().language] ?? instructions.en}\n`);
+  const terminal = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const stop = () => terminal.close();
+  terminal.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  let result;
+  try {
+    for await (const line of terminal) {
+      try { result = session.transition(line.trim()); }
+      catch (error) {
+        if (error.code !== 'HUMAN_EFFORT_TRANSITION_INVALID') throw error;
+        process.stderr.write(`${error.code}: ${error.message}\n`);
+        continue;
+      }
+      if (['finished', 'interrupted'].includes(result.status)) break;
+      process.stderr.write(`${result.status}\n`);
+    }
+  } finally {
+    terminal.close();
+    process.removeListener('SIGTERM', stop);
+    if (!['finished', 'interrupted'].includes(session.status().status)) result = session.transition('interrupt');
+  }
+  return result;
+}