@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/evidence/artifact-store.ts

@@ -0,0 +1,154 @@
+import { randomUUID } from 'crypto';
+import { closeSync, mkdirSync, openSync, readSync, statSync } from 'fs';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import type { ExecutionJob } from '../execution/jobs/types';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+
+export interface ExecutionArtifactRecord {
+  schemaVersion: 1;
+  artifactId: string;
+  repoId: string;
+  jobId: string;
+  kind: 'job-result' | 'job-error' | 'command-output' | 'evidence';
+  mediaType: 'application/json' | 'text/plain';
+  path: string;
+  byteLength: number;
+  createdAt: string;
+}
+
+function artifactRoot(controllerHome: string, repoId: string): string {
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'artifacts');
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function artifactDataPath(controllerHome: string, repoId: string, artifactId: string): string {
+  return join(artifactRoot(controllerHome, repoId), 'data', `${sanitizeFileComponent(artifactId)}.json`);
+}
+
+function metadataPath(controllerHome: string, repoId: string, artifactId: string): string {
+  return join(artifactRoot(controllerHome, repoId), 'records', `${sanitizeFileComponent(artifactId)}.json`);
+}
+
+export function writeExecutionArtifact(
+  controllerHome: string,
+  job: ExecutionJob,
+  kind: ExecutionArtifactRecord['kind'],
+  value: unknown,
+): ExecutionArtifactRecord {
+  const artifactId = `ART-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const dataPath = artifactDataPath(controllerHome, job.repoId, artifactId);
+  writeJsonAtomic(dataPath, value);
+  const record: ExecutionArtifactRecord = {
+    schemaVersion: 1,
+    artifactId,
+    repoId: job.repoId,
+    jobId: job.jobId,
+    kind,
+    mediaType: 'application/json',
+    path: dataPath,
+    byteLength: statSync(dataPath).size,
+    createdAt: new Date().toISOString(),
+  };
+  writeJsonAtomic(metadataPath(controllerHome, job.repoId, artifactId), record);
+  return record;
+}
+
+export function readExecutionArtifact(
+  controllerHome: string,
+  repoId: string,
+  artifactId: string,
+  maxBytes = 512 * 1024,
+): { artifact: ExecutionArtifactRecord; content: unknown; truncated: boolean } {
+  const artifact = readJsonFile<ExecutionArtifactRecord>(metadataPath(controllerHome, repoId, artifactId));
+  if (artifact.repoId !== repoId || artifact.artifactId !== artifactId) throw new Error('ARTIFACT_IDENTITY_MISMATCH');
+  const bounded = Math.max(1_024, Math.min(maxBytes, 2 * 1024 * 1024));
+  // Derive the path from trusted identifiers. Never follow a path stored in mutable metadata.
+  const dataPath = artifactDataPath(controllerHome, repoId, artifactId);
+  const byteLength = statSync(dataPath).size;
+  const length = Math.min(byteLength, bounded);
+  const buffer = Buffer.alloc(length);
+  const descriptor = openSync(dataPath, 'r');
+  try { readSync(descriptor, buffer, 0, length, 0); } finally { closeSync(descriptor); }
+  if (byteLength <= bounded) {
+    return { artifact: { ...artifact, path: dataPath, byteLength }, content: JSON.parse(buffer.toString('utf8')), truncated: false };
+  }
+  return {
+    artifact: { ...artifact, path: dataPath, byteLength },
+    content: {
+      preview: buffer.toString('utf8'),
+      byteLength,
+      message: 'Artifact content is larger than the requested bound. Request a larger bounded window if needed.',
+    },
+    truncated: true,
+  };
+}
+
+export function boundExecutionResult(
+  controllerHome: string,
+  job: ExecutionJob,
+  result: Record<string, unknown>,
+  kind: ExecutionArtifactRecord['kind'] = 'job-result',
+): { result: Record<string, unknown>; artifact?: ExecutionArtifactRecord } {
+  // Default success budget stays compact (~16KB). Callers still fetch full
+  // content via get_artifact when externalized.
+  const DEFAULT_INLINE_SUCCESS = 16 * 1024;
+  const DEFAULT_INLINE_ERROR = 32 * 1024;
+  const configured = typeof job.payload.maxOutputBytes === 'number' ? job.payload.maxOutputBytes : DEFAULT_INLINE_SUCCESS;
+  const maxBytes = kind === 'job-error'
+    ? Math.max(DEFAULT_INLINE_ERROR, Math.min(configured, 512 * 1024))
+    : Math.max(DEFAULT_INLINE_SUCCESS, Math.min(configured, 512 * 1024));
+  const serialized = JSON.stringify(result);
+  const bytes = Buffer.byteLength(serialized);
+
+  if (kind === 'job-error') {
+    const artifact = writeExecutionArtifact(controllerHome, job, kind, result);
+    return {
+      artifact,
+      result: {
+        externalized: true,
+        byteLength: bytes,
+        referenceType: 'artifact',
+        artifactId: artifact.artifactId,
+        artifactKind: artifact.kind,
+        // Keep a short human message, never the full JSON dump.
+        message: typeof result.message === 'string'
+          ? String(result.message).slice(0, 800)
+          : (typeof result.error === 'string' ? String(result.error).slice(0, 800) : 'Job failed; full details externalized.'),
+        detailPointer: {
+          tool: 'get_artifact',
+          repoId: job.repoId,
+          artifactId: artifact.artifactId,
+          maxBytes,
+        },
+        next: `Call get_artifact with repo_id=${job.repoId} and artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
+      },
+    };
+  }
+
+  if (bytes <= maxBytes) {
+    // Prefer inlining compact stdout/stderr when present.
+    return { result };
+  }
+  const artifact = writeExecutionArtifact(controllerHome, job, kind, result);
+  return {
+    artifact,
+    result: {
+      truncated: true,
+      externalized: true,
+      byteLength: bytes,
+      referenceType: 'artifact',
+      artifactId: artifact.artifactId,
+      artifactKind: artifact.kind,
+      preview: serialized.slice(0, Math.min(2 * 1024, serialized.length)),
+      detailPointer: {
+        tool: 'get_artifact',
+        repoId: job.repoId,
+        artifactId: artifact.artifactId,
+        maxBytes,
+      },
+      next: `Call get_artifact with repo_id=${job.repoId} and artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
+    },
+  };
+}

package/src/runtime/evidence/event-ledger.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+import { readFileSync } from 'fs';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { appendJsonLine } from '../shared/json-files';
+import type { ExecutionJob, ExecutionJobEvent } from '../execution/jobs/types';
+
+function ledgerPath(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'events', 'ledger.jsonl');
+}
+
+function jobEventPath(controllerHome: string, repoId: string, jobId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'events', 'jobs', `${jobId}.jsonl`);
+}
+
+export interface RuntimeEntityEvent {
+  schemaVersion: 1;
+  eventId: string;
+  eventType: string;
+  repoId: string;
+  entityType: 'job' | 'plugin' | 'schedule' | 'occurrence' | 'portfolio' | 'campaign' | 'candidate-finding' | 'release' | 'lease' | 'schedule-decision' | 'assistant-action-proposal' | 'assistant-standing-grant';
+  entityId: string;
+  correlationId?: string;
+  causationId?: string;
+  requestId: string;
+  revision: number;
+  occurredAt: string;
+  data?: Record<string, unknown>;
+}
+
+export function appendRuntimeEvent(
+  controllerHome: string,
+  input: Omit<RuntimeEntityEvent, 'schemaVersion' | 'eventId' | 'occurredAt'>,
+): RuntimeEntityEvent {
+  const event: RuntimeEntityEvent = {
+    schemaVersion: 1,
+    eventId: `EVT-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    occurredAt: new Date().toISOString(),
+    ...input,
+  };
+  appendJsonLine(ledgerPath(controllerHome, input.repoId), event);
+  return event;
+}
+
+export function appendJobEvent(
+  controllerHome: string,
+  job: ExecutionJob,
+  eventType: string,
+  data?: Record<string, unknown>,
+): ExecutionJobEvent {
+  const event: ExecutionJobEvent = {
+    schemaVersion: 1,
+    eventId: `EVT-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    eventType,
+    repoId: job.repoId,
+    entityType: 'job',
+    entityId: job.jobId,
+    correlationId: job.origin.correlationId,
+    causationId: job.origin.causationId,
+    requestId: job.requestId,
+    revision: job.revision,
+    occurredAt: new Date().toISOString(),
+    data,
+  };
+  appendJsonLine(ledgerPath(controllerHome, job.repoId), event);
+  appendJsonLine(jobEventPath(controllerHome, job.repoId, job.jobId), event);
+  return event;
+}
+
+export function readJobEvents(controllerHome: string, repoId: string, jobId: string, limit = 200): ExecutionJobEvent[] {
+  try {
+    const lines = readFileSync(jobEventPath(controllerHome, repoId, jobId), 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(-Math.max(1, Math.min(limit, 1000)));
+    return lines.map((line) => JSON.parse(line) as ExecutionJobEvent);
+  } catch {
+    return [];
+  }
+}

package/src/runtime/evidence/evidence-store.ts

@@ -0,0 +1,68 @@
+import { createHash, randomUUID } from 'crypto';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import type { ExecutionJob } from '../execution/jobs/types';
+
+export interface ExecutionEvidence {
+  schemaVersion: 1;
+  evidenceId: string;
+  repoId: string;
+  checkoutId?: string;
+  jobId: string;
+  revision: string;
+  operation: string;
+  environmentFingerprint: string;
+  executedAt: string;
+  outcome: 'succeeded' | 'failed';
+  details?: Record<string, unknown>;
+}
+
+function gitRevision(repoRoot: string): string {
+  const result = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--verify', 'HEAD'], { encoding: 'utf8', timeout: 5_000 });
+  return result.status === 0 ? result.stdout.trim() : 'unversioned';
+}
+
+function environmentFingerprint(): string {
+  return createHash('sha256').update(JSON.stringify({
+    platform: process.platform,
+    arch: process.arch,
+    node: process.version,
+    bun: process.versions.bun ?? null,
+  })).digest('hex').slice(0, 24);
+}
+
+function executionEvidencePath(controllerHome: string, repoId: string, evidenceId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'evidence', `${sanitizeFileComponent(evidenceId)}.json`);
+}
+
+export function readExecutionEvidence(controllerHome: string, repoId: string, evidenceId: string): ExecutionEvidence {
+  const evidence = readJsonFile<ExecutionEvidence>(executionEvidencePath(controllerHome, repoId, evidenceId));
+  if (evidence.repoId !== repoId || evidence.evidenceId !== evidenceId) throw new Error('EVIDENCE_IDENTITY_MISMATCH');
+  return evidence;
+}
+
+export function recordExecutionEvidence(
+  controllerHome: string,
+  repoRoot: string,
+  job: ExecutionJob,
+  outcome: 'succeeded' | 'failed',
+  details?: Record<string, unknown>,
+): ExecutionEvidence {
+  const evidence: ExecutionEvidence = {
+    schemaVersion: 1,
+    evidenceId: `EVD-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    repoId: job.repoId,
+    checkoutId: job.checkoutId,
+    jobId: job.jobId,
+    revision: gitRevision(repoRoot),
+    operation: job.payload.operation,
+    environmentFingerprint: environmentFingerprint(),
+    executedAt: new Date().toISOString(),
+    outcome,
+    details,
+  };
+  writeJsonAtomic(executionEvidencePath(controllerHome, job.repoId, evidence.evidenceId), evidence);
+  return evidence;
+}

package/src/runtime/evidence/process-check-receipt.ts

@@ -0,0 +1,43 @@
+export type ProcessCheckReceiptStatus = 'passed' | 'failed' | 'timed_out' | 'cancelled';
+export type ProcessCheckReceiptRuntimeStatus = 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+
+/**
+ * Stable, persistence-safe evidence contract shared by Edit Sessions, Work and Tasks.
+ * It deliberately contains no execution-runtime implementation types.
+ */
+export interface ProcessCheckReceiptEvidence {
+  schemaVersion: 1;
+  receiptId: string;
+  resultDigest: string;
+  repoId: string;
+  checkoutId?: string;
+  workId?: string;
+  executionSessionId?: string;
+  editSessionId?: string;
+  editRevision?: number;
+  issueId?: string;
+  taskId?: string;
+  checkId: string;
+  requestId?: string;
+  processId: string;
+  commandId?: string;
+  /** Physical checkout that executed the Check; differs from checkoutId on safe cross-checkout reuse. */
+  sourceCheckoutId?: string;
+  /** Existing controller-check cache identity proving content/definition/environment equivalence. */
+  checkCacheKey?: string;
+  checkRevision?: string;
+  checkDefinitionDigest?: string;
+  checkEnvironmentFingerprint?: string;
+  /** True when this consumer is bound to a physical Process originally launched by another consumer/checkout. */
+  reusedExecution?: boolean;
+  status: ProcessCheckReceiptStatus;
+  runtimeStatus: ProcessCheckReceiptRuntimeStatus;
+  ok: boolean;
+  exitCode?: number;
+  timedOut: boolean;
+  cancelled: boolean;
+  artifactPath: string;
+  summary: string;
+  startedAt: string;
+  finishedAt: string;
+}

package/src/runtime/evidence/result-store.ts

@@ -0,0 +1,209 @@
+import { randomUUID } from 'crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import { redactSensitiveValue, type SensitiveRedactionCount } from './sensitive-output';
+
+export interface ControllerResultRecord {
+  schemaVersion: 1;
+  resultId: string;
+  resultRef: string;
+  repoId: string;
+  sessionId: string;
+  principalId: string;
+  workId?: string;
+  kind: 'inspection' | 'command' | 'validation' | 'finalization' | 'generic';
+  byteLength: number;
+  createdAt: string;
+  redaction?: {
+    schemaVersion: 1;
+    sanitizedAt: string;
+    redactionCount: number;
+    types: string[];
+  };
+}
+
+function resultRoot(controllerHome: string, repoId: string): string {
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'results');
+  mkdirSync(join(root, 'records'), { recursive: true, mode: 0o700 });
+  mkdirSync(join(root, 'data'), { recursive: true, mode: 0o700 });
+  return root;
+}
+
+function recordPath(controllerHome: string, repoId: string, resultId: string): string {
+  return join(resultRoot(controllerHome, repoId), 'records', `${sanitizeFileComponent(resultId)}.json`);
+}
+
+function dataPath(controllerHome: string, repoId: string, resultId: string): string {
+  return join(resultRoot(controllerHome, repoId), 'data', `${sanitizeFileComponent(resultId)}.json`);
+}
+
+function writePrivateJson(path: string, value: unknown): void {
+  writeJsonAtomic(path, value);
+  try { chmodSync(path, 0o600); } catch { /* Windows or restricted filesystem. */ }
+}
+
+function redactionMetadata(redactions: SensitiveRedactionCount[]): NonNullable<ControllerResultRecord['redaction']> {
+  return {
+    schemaVersion: 1,
+    sanitizedAt: new Date().toISOString(),
+    redactionCount: redactions.reduce((total, entry) => total + entry.count, 0),
+    types: redactions.map((entry) => entry.type).sort(),
+  };
+}
+
+function sanitizeStoredResult(
+  controllerHome: string,
+  record: ControllerResultRecord,
+): { record: ControllerResultRecord; value: unknown; changed: boolean } {
+  const path = dataPath(controllerHome, record.repoId, record.resultId);
+  const raw = readJsonFile<unknown>(path);
+  const sanitized = redactSensitiveValue(raw);
+  if (!sanitized.changed) return { record, value: raw, changed: false };
+  writePrivateJson(path, sanitized.value);
+  const next: ControllerResultRecord = {
+    ...record,
+    byteLength: statSync(path).size,
+    redaction: redactionMetadata(sanitized.redactions),
+  };
+  writePrivateJson(recordPath(controllerHome, record.repoId, record.resultId), next);
+  return { record: next, value: sanitized.value, changed: true };
+}
+
+function parseRef(resultRef: string): { repoId: string; resultId: string } {
+  const match = /^result:\/\/([^/]+)\/([^/]+)$/.exec(resultRef.trim());
+  if (!match) throw new Error('RESULT_REF_INVALID: expected result://<repoId>/<resultId>');
+  return { repoId: match[1]!, resultId: match[2]! };
+}
+
+export function writeControllerResult(input: {
+  controllerHome: string;
+  repoId: string;
+  sessionId: string;
+  principalId: string;
+  workId?: string;
+  kind: ControllerResultRecord['kind'];
+  value: unknown;
+}): ControllerResultRecord {
+  const resultId = `res_${randomUUID().replace(/-/g, '')}`;
+  const resultRef = `result://${input.repoId}/${resultId}`;
+  const path = dataPath(input.controllerHome, input.repoId, resultId);
+  const sanitized = redactSensitiveValue(input.value);
+  writePrivateJson(path, sanitized.value);
+  const record: ControllerResultRecord = {
+    schemaVersion: 1,
+    resultId,
+    resultRef,
+    repoId: input.repoId,
+    sessionId: input.sessionId,
+    principalId: input.principalId,
+    ...(input.workId ? { workId: input.workId } : {}),
+    kind: input.kind,
+    byteLength: statSync(path).size,
+    createdAt: new Date().toISOString(),
+    ...(sanitized.changed ? { redaction: redactionMetadata(sanitized.redactions) } : {}),
+  };
+  writePrivateJson(recordPath(input.controllerHome, input.repoId, resultId), record);
+  return record;
+}
+
+function authorizeRecord(record: ControllerResultRecord, sessionId: string, principalId: string, workId?: string): void {
+  if (record.sessionId !== sessionId || record.principalId !== principalId) throw new Error('RESULT_ACCESS_DENIED: result belongs to another session or principal');
+  if (workId && record.workId && record.workId !== workId) throw new Error('RESULT_ACCESS_DENIED: result belongs to another work handle');
+}
+
+export function readControllerResult(input: {
+  controllerHome: string;
+  resultRef: string;
+  sessionId: string;
+  principalId: string;
+  workId?: string;
+  cursor?: number;
+  limit?: number;
+}): { record: ControllerResultRecord; items: unknown; cursor: number; nextCursor?: number; truncated: boolean } {
+  const parsed = parseRef(input.resultRef);
+  const record = readJsonFile<ControllerResultRecord>(recordPath(input.controllerHome, parsed.repoId, parsed.resultId));
+  if (record.resultRef !== input.resultRef || record.repoId !== parsed.repoId) throw new Error('RESULT_IDENTITY_MISMATCH');
+  authorizeRecord(record, input.sessionId, input.principalId, input.workId);
+  const sanitized = sanitizeStoredResult(input.controllerHome, record);
+  const value = sanitized.value;
+  const cursor = Math.max(0, Math.trunc(input.cursor ?? 0));
+  const limit = Math.max(1, Math.min(500, Math.trunc(input.limit ?? 100)));
+  if (Array.isArray(value)) {
+    const items = value.slice(cursor, cursor + limit);
+    return { record: sanitized.record, items, cursor, ...(cursor + items.length < value.length ? { nextCursor: cursor + items.length } : {}), truncated: cursor + items.length < value.length };
+  }
+  if (typeof value === 'string') {
+    const items = value.slice(cursor, cursor + limit * 4_096);
+    return { record: sanitized.record, items, cursor, ...(cursor + items.length < value.length ? { nextCursor: cursor + items.length } : {}), truncated: cursor + items.length < value.length };
+  }
+  if (value && typeof value === 'object' && Array.isArray((value as Record<string, unknown>).items)) {
+    const source = (value as Record<string, unknown>).items as unknown[];
+    const items = source.slice(cursor, cursor + limit);
+    return { record: sanitized.record, items, cursor, ...(cursor + items.length < source.length ? { nextCursor: cursor + items.length } : {}), truncated: cursor + items.length < source.length };
+  }
+  return { record: sanitized.record, items: value, cursor, truncated: false };
+}
+
+export function searchControllerResult(input: {
+  controllerHome: string;
+  resultRef: string;
+  sessionId: string;
+  principalId: string;
+  workId?: string;
+  query: string;
+  limit?: number;
+}): { record: ControllerResultRecord; matches: Array<{ line: number; text: string }>; truncated: boolean } {
+  const parsed = parseRef(input.resultRef);
+  const record = readJsonFile<ControllerResultRecord>(recordPath(input.controllerHome, parsed.repoId, parsed.resultId));
+  if (record.resultRef !== input.resultRef || record.repoId !== parsed.repoId) throw new Error('RESULT_IDENTITY_MISMATCH');
+  authorizeRecord(record, input.sessionId, input.principalId, input.workId);
+  const sanitized = sanitizeStoredResult(input.controllerHome, record);
+  const value = sanitized.value;
+  const query = input.query.trim().toLowerCase();
+  if (!query) throw new Error('RESULT_QUERY_REQUIRED');
+  const lines = JSON.stringify(value, null, 2).split(/\r?\n/);
+  const limit = Math.max(1, Math.min(500, Math.trunc(input.limit ?? 100)));
+  const matches = lines.flatMap((text, index) => text.toLowerCase().includes(query) ? [{ line: index + 1, text: text.slice(0, 2_000) }] : []).slice(0, limit);
+  return { record: sanitized.record, matches, truncated: lines.filter((text) => text.toLowerCase().includes(query)).length > matches.length };
+}
+
+/**
+ * Bounded maintenance entry point for historical result artifacts. It returns
+ * only counts and ids; sensitive contents are never included in the report.
+ */
+export function sanitizeControllerResultStore(controllerHome: string, repoId: string, limit = 10_000): {
+  scanned: number;
+  changed: number;
+  failed: number;
+  resultIds: string[];
+} {
+  const root = resultRoot(controllerHome, repoId);
+  const recordsDir = join(root, 'records');
+  let scanned = 0;
+  let changed = 0;
+  let failed = 0;
+  const resultIds: string[] = [];
+  const maximum = Math.max(1, Math.min(100_000, Math.trunc(limit)));
+  for (const entry of readdirSync(recordsDir).sort()) {
+    if (!entry.endsWith('.json')) continue;
+    if (scanned >= maximum) break;
+    scanned += 1;
+    try {
+      const record = readJsonFile<ControllerResultRecord>(join(recordsDir, entry));
+      if (!record?.resultId || record.repoId !== repoId || !existsSync(dataPath(controllerHome, repoId, record.resultId))) {
+        failed += 1;
+        continue;
+      }
+      const sanitized = sanitizeStoredResult(controllerHome, record);
+      if (sanitized.changed) {
+        changed += 1;
+        resultIds.push(record.resultId);
+      }
+    } catch {
+      failed += 1;
+    }
+  }
+  return { scanned, changed, failed, resultIds };
+}