entroly-wasm 1.0.78 → 1.0.80

package/js/work_graph_content_digest.js

@@ -0,0 +1,151 @@
+'use strict';
+
+// Node orchestration-only content identity for passive Work Graph snapshots.
+// Rust decides whether observations are semantically duplicate; this helper
+// merely supplies exact Git blob identity where it can do so without guessing.
+// It never follows symlinks, reads special files, or reads an unbounded file.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_HASH_FILE_BYTES = 64 * 1024 * 1024;
+const HASH_CHUNK_BYTES = 1024 * 1024;
+
+function gitEnv() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_OPTIONAL_LOCKS: '0',
+    GIT_PAGER: 'cat',
+    LC_ALL: 'C',
+    LANG: 'C',
+  };
+}
+
+function runGitText(cwd, args) {
+  const result = spawnSync(
+    'git',
+    [
+      '-c', 'core.fsmonitor=false',
+      '-c', 'core.untrackedCache=false',
+      '-c', 'submodule.recurse=false',
+      '-C', String(cwd),
+      ...args,
+    ],
+    {
+      encoding: 'utf8',
+      env: gitEnv(),
+      maxBuffer: 1024 * 1024,
+      timeout: 5000,
+      windowsHide: true,
+    },
+  );
+  if (result.error || result.status !== 0) return '';
+  return String(result.stdout || '').trim();
+}
+
+function resolveRoot(repoPath) {
+  const candidate = path.resolve(String(repoPath || '.'));
+  const output = runGitText(candidate, ['rev-parse', '--show-toplevel']);
+  if (!output) throw new Error(`not a Git worktree: ${candidate}`);
+  return path.resolve(output);
+}
+
+function objectHashAlgorithm(root) {
+  const value = runGitText(root, ['rev-parse', '--show-object-format']).toLowerCase();
+  return value === 'sha1' || value === 'sha256' ? value : '';
+}
+
+function relativeRegularPath(root, repoRel) {
+  const value = String(repoRel || '').replace(/\\/g, '/');
+  if (!value || value.startsWith('/') || /[\0\r\n]/.test(value)) return null;
+  const parts = value.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..')) return null;
+  const candidate = path.join(root, ...parts);
+  let before;
+  try { before = fs.lstatSync(candidate, { bigint: true }); }
+  catch (_) { return null; }
+  if (!before.isFile() || before.size > BigInt(MAX_HASH_FILE_BYTES)) return null;
+  return { candidate, before };
+}
+
+function sameFile(left, right) {
+  if (!left.isFile() || !right.isFile()) return false;
+  // `dev` is compared only when both sides report one. Node on Windows returns
+  // dev=0 from lstat but a real device id from fstat for the same file, so
+  // requiring strict equality rejected every legitimate file and made
+  // gitBlobDigest return '' for all input -- content identity was silently
+  // dead on win32, which is the binding handoff/resume rely on. The anti-swap
+  // property is preserved: the file index (ino), size, and both timestamps
+  // must still match across lstat -> open -> lstat.
+  if (left.dev !== 0n && right.dev !== 0n && left.dev !== right.dev) return false;
+  return left.ino === right.ino
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs;
+}
+
+function gitBlobDigest(root, repoRel, algorithm) {
+  const safe = relativeRegularPath(root, repoRel);
+  if (!safe) return '';
+
+  let fd;
+  try {
+    let flags = fs.constants.O_RDONLY;
+    if (typeof fs.constants.O_NOFOLLOW === 'number') flags |= fs.constants.O_NOFOLLOW;
+    fd = fs.openSync(safe.candidate, flags);
+    const opened = fs.fstatSync(fd, { bigint: true });
+    const pathAfterOpen = fs.lstatSync(safe.candidate, { bigint: true });
+    if (!sameFile(safe.before, opened) || !sameFile(opened, pathAfterOpen)) return '';
+    if (opened.size > BigInt(MAX_HASH_FILE_BYTES)) return '';
+
+    const hash = crypto.createHash(algorithm);
+    hash.update(Buffer.from(`blob ${opened.size.toString()}\0`, 'ascii'));
+    const buffer = Buffer.allocUnsafe(HASH_CHUNK_BYTES);
+    let offset = 0n;
+    while (offset < opened.size) {
+      const remaining = opened.size - offset;
+      const length = Number(remaining > BigInt(buffer.length) ? BigInt(buffer.length) : remaining);
+      const bytes = fs.readSync(fd, buffer, 0, length, Number(offset));
+      if (bytes <= 0) return '';
+      hash.update(buffer.subarray(0, bytes));
+      offset += BigInt(bytes);
+    }
+
+    const after = fs.fstatSync(fd, { bigint: true });
+    const pathAfterRead = fs.lstatSync(safe.candidate, { bigint: true });
+    if (!sameFile(opened, after) || !sameFile(after, pathAfterRead)) return '';
+    return `git-blob:${hash.digest('hex')}`;
+  } catch (_) {
+    return '';
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (_) {}
+    }
+  }
+}
+
+function enrichWorktreeContentDigests(repoPath, observation) {
+  const changes = observation && observation.changes;
+  if (!Array.isArray(changes)) return observation;
+  const root = resolveRoot(repoPath);
+  const algorithm = objectHashAlgorithm(root);
+
+  for (const change of changes) {
+    if (!change || typeof change !== 'object') continue;
+    change.content_digest = '';
+    if (change.staged || change.conflicted) continue;
+    if (String(change.kind || '') === 'deleted') {
+      change.content_digest = 'worktree:deleted';
+      continue;
+    }
+    if (!algorithm) continue;
+    change.content_digest = gitBlobDigest(root, change.path, algorithm);
+  }
+  return observation;
+}
+
+module.exports = {
+  enrichWorktreeContentDigests,
+};

package/js/work_graph_continuity.d.ts

@@ -0,0 +1,54 @@
+import type {
+  WorkContinuationProof,
+  WorkGraphHandoffReceipt,
+  WorkGraphResumeView,
+} from "./work_graph";
+import type { RepositoryDiscoveryOptions } from "./work_graph_repo";
+import type { WorkGraphStoreOptions } from "./work_graph_store";
+
+export interface ResumeRepositoryOptions {
+  workstreamId?: string | null;
+  maxEvidence?: number;
+  storeOptions?: WorkGraphStoreOptions;
+  repositoryOptions?: RepositoryDiscoveryOptions;
+}
+
+export interface HandoffRepositoryOptions {
+  workstreamId: string;
+  fromAgent: string;
+  toAgent: string;
+  generatedAtMs?: number;
+  storeOptions?: WorkGraphStoreOptions;
+  repositoryOptions?: RepositoryDiscoveryOptions;
+}
+
+export const MAX_RESUME_EVIDENCE: number;
+export const MAX_WORK_ID_CHARS: number;
+
+/**
+ * Refresh bounded durable repository/checkpoint facts and recover unfinished
+ * work from the shared Rust Work Graph. The previous agent does not need to
+ * have produced an explicit handoff.
+ */
+export function resumeRepository(
+  repoPath?: string,
+  options?: ResumeRepositoryOptions,
+): WorkGraphResumeView;
+
+/** Refresh durable facts exactly once, then seal a graph-bound handoff receipt. */
+export function handoffRepository(
+  repoPath: string | undefined,
+  options: HandoffRepositoryOptions,
+): WorkGraphHandoffReceipt;
+
+/**
+ * Refresh durable facts once and return both the compatibility handoff receipt
+ * and the Rust-verified complete continuation proof.
+ */
+export function handoffRepositoryWithProof(
+  repoPath: string | undefined,
+  options: HandoffRepositoryOptions,
+): {
+  handoff: WorkGraphHandoffReceipt;
+  continuation_proof: WorkContinuationProof;
+};

package/js/work_graph_continuity.js

@@ -0,0 +1,128 @@
+'use strict';
+
+// Thin Node orchestration for interrupted-agent recovery and fresh handoff.
+// Repository observation and persistence happen here; all work-state meaning
+// remains in shared Rust.
+const { enrichWorktreeContentDigests } = require('./work_graph_content_digest');
+const { discoverRepositoryObservation } = require('./work_graph_repo');
+const { WorkGraphStateError, WorkGraphStore } = require('./work_graph_store');
+
+const MAX_RESUME_EVIDENCE = 4096;
+const MAX_WORK_ID_CHARS = 512;
+
+function validateMaxEvidence(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 0 || number > MAX_RESUME_EVIDENCE) {
+    throw new WorkGraphStateError(
+      `maxEvidence must be a safe integer between 0 and ${MAX_RESUME_EVIDENCE}`,
+    );
+  }
+  return number;
+}
+
+function requiredId(value, name) {
+  const text = String(value == null ? '' : value).trim();
+  if (!text) throw new WorkGraphStateError(`${name} must not be empty`);
+  if (text.length > MAX_WORK_ID_CHARS || text.includes('\0')) {
+    throw new WorkGraphStateError(
+      `${name} may not exceed ${MAX_WORK_ID_CHARS} characters or contain NUL`,
+    );
+  }
+  return text;
+}
+
+function optionalWorkstreamId(value) {
+  if (value == null || value === '') return null;
+  const text = String(value).trim();
+  if (text.length > MAX_WORK_ID_CHARS || text.includes('\0')) {
+    throw new WorkGraphStateError(
+      `workstreamId may not exceed ${MAX_WORK_ID_CHARS} characters or contain NUL`,
+    );
+  }
+  return text || null;
+}
+
+function passiveObservation(repoPath, repositoryOptions) {
+  const observation = discoverRepositoryObservation(repoPath, repositoryOptions);
+  return enrichWorktreeContentDigests(repoPath, observation);
+}
+
+function resumeRepository(repoPath = '.', options = {}) {
+  // Validate before constructing the store or observing Git. Invalid recovery
+  // requests must not mutate shared state.
+  const maxEvidence = validateMaxEvidence(options.maxEvidence ?? 128);
+  const workstreamId = optionalWorkstreamId(options.workstreamId);
+  const storeOptions = options.storeOptions || {};
+  const repositoryOptions = options.repositoryOptions || {};
+
+  const store = WorkGraphStore.forRepository(repoPath, storeOptions);
+  store.submitObservation(passiveObservation(repoPath, repositoryOptions));
+  return store.resume(workstreamId, maxEvidence);
+}
+
+function handoffRepository(repoPath = '.', options = {}) {
+  // A receipt is a state-sealing operation. Validate everything before touching
+  // disk, then refresh the bounded durable facts exactly once before Rust seals
+  // the handoff against the graph commitment.
+  const workstreamId = requiredId(options.workstreamId, 'workstreamId');
+  const fromAgent = requiredId(options.fromAgent, 'fromAgent');
+  const toAgent = requiredId(options.toAgent, 'toAgent');
+  const storeOptions = options.storeOptions || {};
+  const repositoryOptions = options.repositoryOptions || {};
+  const generatedAtMs = options.generatedAtMs == null ? Date.now() : Number(options.generatedAtMs);
+  if (!Number.isSafeInteger(generatedAtMs)) {
+    throw new WorkGraphStateError('generatedAtMs must be a JavaScript-safe integer');
+  }
+
+  const store = WorkGraphStore.forRepository(repoPath, storeOptions);
+  store.submitObservation(passiveObservation(repoPath, repositoryOptions));
+  return store.handoff(workstreamId, fromAgent, toAgent, generatedAtMs);
+}
+
+function continuationOutstandingRefs(view) {
+  const safeView = view && typeof view === 'object' ? view : {};
+  const selected = safeView.selected_workstream && typeof safeView.selected_workstream === 'object'
+    ? safeView.selected_workstream
+    : {};
+  const values = [
+    ...(Array.isArray(safeView.changed_paths) ? safeView.changed_paths : []),
+    ...(Array.isArray(safeView.failures) ? safeView.failures : []),
+    ...(Array.isArray(selected.task_ids) ? selected.task_ids : []),
+  ];
+  return [...new Set(values
+    .filter((value) => typeof value === 'string' && value.trim())
+    .map((value) => value.trim()))];
+}
+
+function handoffRepositoryWithProof(repoPath = '.', options = {}) {
+  // Preserve the receipt-only API above for compatibility while making the
+  // complete continuation artifact available as one low-ceremony operation.
+  const workstreamId = requiredId(options.workstreamId, 'workstreamId');
+  const fromAgent = requiredId(options.fromAgent, 'fromAgent');
+  const toAgent = requiredId(options.toAgent, 'toAgent');
+  const storeOptions = options.storeOptions || {};
+  const repositoryOptions = options.repositoryOptions || {};
+  const generatedAtMs = options.generatedAtMs == null ? Date.now() : Number(options.generatedAtMs);
+  if (!Number.isSafeInteger(generatedAtMs)) {
+    throw new WorkGraphStateError('generatedAtMs must be a JavaScript-safe integer');
+  }
+
+  const store = WorkGraphStore.forRepository(repoPath, storeOptions);
+  store.submitObservation(passiveObservation(repoPath, repositoryOptions));
+  const handoff = store.handoff(workstreamId, fromAgent, toAgent, generatedAtMs);
+  const view = store.resume(workstreamId, 128);
+  const outstanding = continuationOutstandingRefs(view);
+  const continuationProof = store.continuationProof(handoff, {
+    outstanding_work_refs: outstanding,
+    created_at_ms: generatedAtMs,
+  });
+  return { handoff, continuation_proof: continuationProof };
+}
+
+module.exports = {
+  MAX_RESUME_EVIDENCE,
+  MAX_WORK_ID_CHARS,
+  handoffRepository,
+  handoffRepositoryWithProof,
+  resumeRepository,
+};

package/js/work_graph_repo.d.ts

@@ -0,0 +1,26 @@
+import type { WorkGraphObservation } from "./work_graph";
+
+export interface RepositoryDiscoveryOptions {
+  agentId?: string;
+  sessionId?: string;
+  taskHint?: Record<string, unknown> | null;
+  defaultBranch?: string;
+  maxCommits?: number;
+  observedAtMs?: number;
+  includeCheckpoint?: boolean;
+  checkpointDir?: string;
+}
+
+export interface RepositoryIdentity {
+  repo_id: string;
+  root: string;
+}
+
+export class RepositoryDiscoveryError extends Error {}
+
+export function discoverRepositoryIdentity(path?: string): RepositoryIdentity;
+
+export function discoverRepositoryObservation(
+  path?: string,
+  options?: RepositoryDiscoveryOptions,
+): WorkGraphObservation;