@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/node/revision-catalog-resolver.mjs

@@ -0,0 +1,159 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { withSourceArchive } from './source-archive.mjs';
+
+const execute = promisify(execFile);
+const COMMIT_SHA = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+function revision(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!COMMIT_SHA.test(normalized)) throw new Error('A revision catalog requires the exact complete source commit.');
+  return normalized;
+}
+
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function capture(catalog, sourceRevision) {
+  const portable = JSON.parse(JSON.stringify(catalog));
+  if (portable?.version !== 1 || portable.sourceRevision !== sourceRevision || !Array.isArray(portable.screens?.pages)) {
+    throw new Error(`The catalog does not match its requested source revision: ${sourceRevision.slice(0, 8)}`);
+  }
+  return freeze(portable);
+}
+
+/** A commit must be attached to this checkout or reachable from one of its refs. */
+async function reachableFromRefs(projectRoot, sourceRevision, signal) {
+  const git = args => execute('git', ['-C', projectRoot, ...args], { encoding: 'utf8', signal });
+  const head = (await git(['rev-parse', '--verify', '--quiet', 'HEAD'])).stdout.trim();
+  if (head === sourceRevision) return true;
+  try {
+    await git(['cat-file', '-e', `${sourceRevision}^{commit}`]);
+  } catch (error) {
+    if (error?.code === 1 || error?.code === 128) return false;
+    throw error;
+  }
+  const { stdout } = await git([
+    'for-each-ref', '--count=1', '--format=%(refname)', `--contains=${sourceRevision}`, 'refs/heads', 'refs/remotes', 'refs/tags',
+  ]);
+  return stdout.trim().length > 0;
+}
+
+/** Hosts provide catalog declarations; the SDK owns archive lifetime and bounded shared work. */
+export function createRevisionCatalogResolver({
+  projectRoot = process.cwd(),
+  appDirectory = '.',
+  currentCatalog,
+  generate,
+  reachable = (sourceRevision, signal) => reachableFromRefs(path.resolve(projectRoot), sourceRevision, signal),
+  archive = (sourceRevision, signal, operation) => withSourceArchive({ projectRoot, appDirectory, sourceRevision, signal }, operation),
+  maxEntries = 4,
+  maxAgeMs = 30 * 60_000,
+} = {}) {
+  if (typeof currentCatalog !== 'function' || typeof generate !== 'function'
+    || typeof reachable !== 'function' || typeof archive !== 'function') {
+    throw new TypeError('A catalog resolver requires currentCatalog and generate callbacks.');
+  }
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 0 || !Number.isFinite(maxAgeMs) || maxAgeMs < 0) {
+    throw new TypeError('Catalog cache limits must be finite non-negative values.');
+  }
+  const entries = new Map();
+  const pending = new Map();
+  const controllers = new Set();
+  let queue = Promise.resolve();
+  let disposed = false;
+  const check = signal => {
+    signal?.throwIfAborted();
+    if (disposed) throw new Error('The revision catalog resolver has been disposed.');
+  };
+  const prune = () => {
+    const now = Date.now();
+    for (const [key, entry] of entries) {
+      if (now - entry.createdAt >= maxAgeMs) entries.delete(key);
+    }
+  };
+  const remember = (sourceRevision, catalog) => {
+    prune();
+    if (maxEntries === 0 || maxAgeMs === 0) return;
+    entries.delete(sourceRevision);
+    entries.set(sourceRevision, { catalog, createdAt: Date.now() });
+    while (entries.size > maxEntries) entries.delete(entries.keys().next().value);
+  };
+  const cached = sourceRevision => {
+    prune();
+    const entry = entries.get(sourceRevision);
+    if (!entry) return undefined;
+    entries.delete(sourceRevision); entries.set(sourceRevision, entry);
+    return entry.catalog;
+  };
+  const current = async signal => {
+    check(signal);
+    const catalog = await currentCatalog(signal);
+    check(signal);
+    return capture(catalog, revision(catalog?.sourceRevision));
+  };
+  const build = sourceRevision => {
+    const controller = new AbortController();
+    controllers.add(controller);
+    const work = (async () => {
+      // Archive extraction and compilation share one bounded execution lane.
+      await queue;
+      controller.signal.throwIfAborted();
+      if (!(await reachable(sourceRevision, controller.signal))) {
+        throw new Error(`The source revision is not reachable in this repository: ${sourceRevision.slice(0, 8)}`);
+      }
+      controller.signal.throwIfAborted();
+      const catalog = await archive(sourceRevision, controller.signal,
+        ({ appRoot, signal }) => generate({ archiveRoot: appRoot, sourceRevision, signal }));
+      controller.signal.throwIfAborted();
+      const portable = capture(catalog, sourceRevision);
+      if (!disposed) remember(sourceRevision, portable);
+      return portable;
+    })();
+    queue = work.catch(() => {});
+    const cleanup = () => {
+      controllers.delete(controller);
+      if (pending.get(sourceRevision) === work) pending.delete(sourceRevision);
+    };
+    void work.then(cleanup, cleanup);
+    return work;
+  };
+  const awaitShared = (work, signal) => {
+    if (!signal) return work;
+    return new Promise((resolve, reject) => {
+      const abort = () => reject(signal.reason ?? new DOMException('Catalog request cancelled.', 'AbortError'));
+      if (signal.aborted) { abort(); return; }
+      signal.addEventListener('abort', abort, { once: true });
+      void work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+  };
+  return Object.freeze({
+    async resolve(sourceRevision, signal) {
+      check(signal);
+      const normalized = revision(sourceRevision);
+      const own = await current(signal);
+      if (own.sourceRevision === normalized) return own;
+      const hit = cached(normalized);
+      if (hit) return hit;
+      const work = pending.get(normalized) ?? build(normalized);
+      pending.set(normalized, work);
+      const result = await awaitShared(work, signal);
+      check(signal);
+      return result;
+    },
+    async currentRevision(signal) { return (await current(signal)).sourceRevision; },
+    retained() { prune(); return [...entries.keys()]; },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const controller of controllers) controller.abort(new Error('The revision catalog resolver has been disposed.'));
+      entries.clear(); pending.clear();
+    },
+  });
+}

package/node/source-archive-runtime.mjs

@@ -0,0 +1,63 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+function localPath(value) {
+  return typeof value === 'string' && value.length > 0 && !path.isAbsolute(value)
+    && !/[\\\x00-\x1f\x7f]/.test(value)
+    && !/^[a-z]:/i.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+}
+
+async function directory(root) {
+  return (await lstat(root).catch(error => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }))?.isDirectory() ?? false;
+}
+
+/** Select an existing install only when its lockfile is byte-identical to the archive. */
+export async function resolveSourceArchiveDependencies({ archiveRoot, dependencyRoots, lockfile = 'package-lock.json' }) {
+  if (!localPath(lockfile) || !Array.isArray(dependencyRoots)) {
+    throw new TypeError('Archive dependencies require a relative lockfile and candidate root list.');
+  }
+  if (await directory(path.join(archiveRoot, 'node_modules'))) return [];
+  const lock = await readFile(path.join(archiveRoot, lockfile)).catch(error => {
+    if (error.code === 'ENOENT') throw new Error(`The source archive is missing ${lockfile}.`, { cause: error });
+    throw error;
+  });
+  const rejected = [];
+  for (const candidate of dependencyRoots) {
+    const root = path.resolve(candidate);
+    const modules = path.join(root, 'node_modules');
+    if (!(await directory(modules))) { rejected.push(`${root}: missing node_modules`); continue; }
+    const candidateLock = await readFile(path.join(root, lockfile)).catch(error => {
+      if (error.code === 'ENOENT') return undefined;
+      throw error;
+    });
+    if (!candidateLock?.equals(lock)) { rejected.push(`${root}: ${lockfile} differs`); continue; }
+    return [modules];
+  }
+  throw new Error(`No dependency install matches the source archive lockfile.${rejected.length ? ` (${rejected.join('; ')})` : ''}`);
+}
+
+/** Check the isolation boundary before a trusted generator writes into extracted source. */
+export async function assertIsolatedSourceRoot({ archiveRoot, hostRoot, requiredDirectories = [] }) {
+  if (!Array.isArray(requiredDirectories) || !requiredDirectories.every(localPath)) {
+    throw new TypeError('Required source directories must be relative paths.');
+  }
+  const root = await realpath(archiveRoot);
+  const host = await realpath(hostRoot);
+  const relative = path.relative(host, root);
+  if (relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))) {
+    throw new Error('Source generation requires an isolated archive outside the host working tree.');
+  }
+  const metadata = await lstat(path.join(root, '.git')).catch(error => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (metadata) throw new Error('The isolated source archive must not contain Git working-tree metadata.');
+  if (!(await directory(root))) throw new Error('The source archive must be a directory.');
+  for (const name of requiredDirectories) {
+    if (!(await directory(path.join(root, name)))) throw new Error(`The source archive is missing a regular directory: ${name}`);
+  }
+  return root;
+}

package/node/source-archive.mjs

@@ -0,0 +1,88 @@
+import { execFile } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const executeFile = promisify(execFile);
+const MAX_ARCHIVE_BYTES = 256 * 1024 * 1024;
+async function execute(file, args, options) {
+  options.signal?.throwIfAborted();
+  const work = executeFile(file, args, options);
+  const child = work.child;
+  const closed = child ? new Promise(resolve => child.once('close', resolve)) : Promise.resolve();
+  try { return await work; }
+  finally {
+    // AbortSignal rejects execFile before the child has necessarily stopped writing.
+    const force = child && child.exitCode === null && child.signalCode === null
+      ? setTimeout(() => child.kill('SIGKILL'), 1000) : undefined;
+    try { await closed; } finally { clearTimeout(force); }
+  }
+}
+function relative(value) {
+  return typeof value === 'string' && value.length > 0 && !/[\\\x00-\x1f\x7f]/.test(value)
+    && !path.posix.isAbsolute(value) && !/^[a-z]:/i.test(value)
+    && !value.split('/').some(part => !part || part === '.' || part === '..' || part === '.git');
+}
+
+async function git(projectRoot, args, signal, encoding = 'utf8') {
+  const { stdout } = await execute('git', ['-C', projectRoot, ...args], { encoding, maxBuffer: MAX_ARCHIVE_BYTES, signal });
+  return stdout;
+}
+
+export async function materializeSourceArchive(projectRoot, appDirectory, revision, temporary, signal) {
+  signal.throwIfAborted();
+  if (appDirectory !== '.' && !relative(appDirectory)) throw new Error('The application directory must be project-relative.');
+  const top = await git(projectRoot, ['rev-parse', '--show-toplevel'], signal);
+  if (await fsp.realpath(top.toString().trim()) !== await fsp.realpath(projectRoot)) throw new Error('The preview project root must be the Git repository root.');
+  const commit = (await git(projectRoot, ['rev-parse', '--verify', `${revision}^{commit}`], signal)).toString().trim();
+  if (commit !== revision) throw new Error('The preview requires the exact complete source commit.');
+  const selected = appDirectory === '.' ? [] : [appDirectory];
+  const tree = await git(projectRoot, ['ls-tree', '-r', '-z', revision, '--', ...selected], signal);
+  const entries = tree.toString().split('\0').filter(Boolean);
+  if (!entries.length) throw new Error('The selected application is absent from the source commit.');
+  for (const entry of entries) {
+    const separator = entry.indexOf('\t');
+    const metadata = entry.slice(0, separator).split(' ');
+    const file = entry.slice(separator + 1);
+    if (separator < 0 || !['100644', '100755'].includes(metadata[0]) || metadata[1] !== 'blob' || !relative(file)) throw new Error('Archived source must contain regular files only; links and submodules are unsupported.');
+  }
+  const checkout = path.join(temporary, 'source');
+  const archive = path.join(temporary, 'source.tar');
+  await fsp.mkdir(checkout);
+  const bytes = await git(projectRoot, ['archive', '--format=tar', '--', revision, ...selected], signal, 'buffer');
+  signal.throwIfAborted();
+  await fsp.writeFile(archive, bytes, { signal });
+  await execute('tar', ['-xf', archive, '-C', checkout, '--no-same-owner', '--no-same-permissions'], { signal, maxBuffer: 1024 * 1024 });
+  signal.throwIfAborted();
+  const appRoot = path.join(checkout, appDirectory);
+  if (!(await fsp.lstat(appRoot)).isDirectory()) throw new Error('The archived application must be a directory.');
+  signal.throwIfAborted();
+  return appRoot;
+}
+
+/** The trusted callback must stop its workers and settle before cleanup can remove its archive. */
+export async function withSourceArchive(options, operation) {
+  const { projectRoot, sourceRevision, appDirectory = '.', signal = new AbortController().signal } = options;
+  if (typeof projectRoot !== 'string' || !projectRoot.trim() || typeof operation !== 'function' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sourceRevision ?? '')) throw new Error('A source archive requires a project root, exact commit, and trusted operation.');
+  const root = path.resolve(projectRoot);
+  signal.throwIfAborted();
+  const temporary = await fsp.mkdtemp(path.join(os.tmpdir(), 'pygmalion-source-archive-'));
+  let result; let failure; let failed = false;
+  try {
+    const appRoot = await materializeSourceArchive(root, appDirectory, sourceRevision, temporary, signal);
+    signal.throwIfAborted();
+    result = await operation(Object.freeze({ appRoot, sourceRevision, signal }));
+    signal.throwIfAborted();
+  } catch (error) { failure = error; failed = true; }
+  let cleanupFailure; let cleanupFailed = false;
+  try { await fsp.rm(temporary, { recursive: true, force: true }); }
+  catch (error) { cleanupFailure = error; cleanupFailed = true; }
+  if (cleanupFailed) {
+    if (failed) throw new AggregateError([failure, cleanupFailure], 'Source archive operation and cleanup both failed.', { cause: failure });
+    throw cleanupFailure;
+  }
+  if (failed) throw failure;
+  signal.throwIfAborted();
+  return result;
+}

package/node/source-bindings.mjs

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import ts from 'typescript';
+
+function relativeFile(value) {
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('/')
+    && !/^[a-z]:/i.test(value) && !/[\\\0?#]/.test(value)
+    && !value.split('/').some((part) => !part || part === '.' || part === '..');
+}
+
+/**
+ * Verify source evidence before a host reviews its structured binding plan.
+ * This is not an apply endpoint. It never writes files or converts expressions
+ * into the literal-prop inspection protocol.
+ */
+export function validateSourceBindingProofs(plan, options) {
+  const diagnostics = [];
+  const fail = (code, message, file) => diagnostics.push({ severity: 'error', code, message, ...(file ? { file } : {}) });
+  if (!plan || plan.schema !== 'pygmalion.binding-source-plan' || plan.version !== 1
+    || !plan.catalog || plan.catalog.sourceRevision !== options.sourceRevision
+    || !Array.isArray(plan.bindings) || !Array.isArray(plan.repeats)) {
+    fail('binding-source-plan-invalid', 'A versioned plan must match the source revision being reviewed.');
+    return { valid: false, diagnostics };
+  }
+  const allowedFiles = new Set(options.allowedFiles ?? []);
+  const excluded = options.excludedSourcePrefixes ?? [];
+  if ([...allowedFiles, ...excluded].some((file) => !relativeFile(file))) {
+    fail('binding-source-policy-invalid', 'Source policies require normalized relative paths.');
+    return { valid: false, diagnostics };
+  }
+  if (!plan.bindings.length && !plan.repeats.length) fail('binding-source-empty', 'The plan has no source targets.');
+  const ranges = new Map();
+  for (const entry of [...plan.bindings, ...plan.repeats]) {
+    const proof = entry?.resolution?.proof;
+    if (!proof || !relativeFile(proof.file) || proof.sourceRevision !== options.sourceRevision
+      || typeof proof.fileHash !== 'string' || !/^[a-f0-9]{64}$/.test(proof.fileHash)
+      || !Number.isSafeInteger(proof.start) || !Number.isSafeInteger(proof.end)
+      || proof.start < 0 || proof.end <= proof.start || typeof proof.expected !== 'string'
+      || proof.expected.length !== proof.end - proof.start) {
+      fail('binding-source-proof-invalid', 'Each source target requires an exact revision, file hash, and expression range.'); continue;
+    }
+    const file = proof.file;
+    if (!allowedFiles.has(file) || excluded.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))) {
+      fail('binding-source-file-excluded', 'The host has not allowed this source file for design changes.', file); continue;
+    }
+    const source = options.files instanceof Map ? options.files.get(file) : options.files?.[file];
+    if (typeof source !== 'string') { fail('binding-source-file-missing', 'The source file is unavailable.', file); continue; }
+    if (createHash('sha256').update(source, 'utf8').digest('hex') !== proof.fileHash
+      || source.slice(proof.start, proof.end) !== proof.expected || proof.end > source.length) {
+      fail('binding-source-stale', 'The source file or expression has changed since the proof was created.', file); continue;
+    }
+    const fileRanges = ranges.get(file) ?? [];
+    if (fileRanges.some((range) => range.start < proof.end && proof.start < range.end)) fail('binding-source-overlap', 'Source targets must have disjoint exact ranges.', file);
+    fileRanges.push(proof);
+    ranges.set(file, fileRanges);
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    let expressionFound = false;
+    function visit(node) {
+      if (node.getStart(parsed) === proof.start && node.end === proof.end && ts.isExpression(node)) expressionFound = true;
+      ts.forEachChild(node, visit);
+    }
+    visit(parsed);
+    if (parsed.parseDiagnostics.length || !expressionFound) fail('binding-source-anchor-invalid', 'The source proof must point to a complete expression in valid source.', file);
+  }
+  return { valid: diagnostics.length === 0, diagnostics };
+}

package/node/source-file-lock.mjs

@@ -0,0 +1,15 @@
+import fsp from 'node:fs/promises';
+
+const pending = new Map();
+
+/** Serialize source reads and writes within one process and canonical application root. */
+export async function withSourceFileLock(root, operation) {
+  const key = await fsp.realpath(root);
+  const previous = pending.get(key) ?? Promise.resolve();
+  let release = () => {};
+  const next = new Promise(resolve => { release = () => resolve(undefined); });
+  pending.set(key, next);
+  await previous;
+  try { return await operation(key); }
+  finally { release(); if (pending.get(key) === next) pending.delete(key); }
+}

package/node/source-file-plan.mjs

@@ -0,0 +1,162 @@
+export { withSourceArchive } from './source-archive.mjs';
+export { rewriteTokenSourceReferences } from './token-source-references.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createUnifiedDiff } from './source-diff.mjs';
+import { withSourceFileLock } from './source-file-lock.mjs';
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';
+
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const isHash = value => value === null || typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+function sourcePath(file) {
+  if (typeof file !== 'string' || !file || /[\\\x00-\x1f\x7f?#]/.test(file) || path.posix.isAbsolute(file)
+    || /^[a-z]:/i.test(file) || file.split('/').some(part => !part || ['.', '..', '.git'].includes(part))) {
+    throw new Error('A source file plan requires safe project-relative paths.');
+  }
+  return file;
+}
+
+export function captureSourceFilePlan(input, options) {
+  const plan = JSON.parse(workspaceSourceFingerprint(input));
+  if (plan?.version !== 1 || typeof plan.sourceRevision !== 'string' || !plan.sourceRevision.trim()
+    || !Array.isArray(plan.proofs) || !plan.proofs.length || plan.proofs.length > 3000
+    || !Array.isArray(plan.changes) || !plan.changes.length || plan.changes.length > 1000) {
+    throw new Error('A source file plan requires a revision, complete proofs, and bounded changes.');
+  }
+  if (options.sourceRevision !== plan.sourceRevision) throw new Error('The source file plan does not match the active source revision.');
+  const allowed = new Set((options.allowedFiles ?? []).map(sourcePath));
+  const excluded = (options.excludedSourcePrefixes ?? []).map(prefix => sourcePath(prefix.replace(/\/+$/, '')));
+  const assertNotExcluded = file => {
+    if (excluded.some(prefix => file === prefix || file.startsWith(`${prefix}/`))) throw new Error(`Excluded source files cannot enter a source file plan: ${file}`);
+  };
+  const proofs = new Map();
+  for (const proof of plan.proofs) {
+    sourcePath(proof?.file);
+    assertNotExcluded(proof.file);
+    if (!isHash(proof.sha256) || proofs.has(proof.file)) throw new Error('Source proofs must contain unique files and exact hashes.');
+    proofs.set(proof.file, proof.sha256);
+  }
+  let total = 0;
+  const changed = new Set();
+  for (const change of plan.changes) {
+    sourcePath(change?.file);
+    if (!allowed.has(change.file)) throw new Error(`The host has not permitted this source file: ${change.file}`);
+    if (changed.has(change.file) || !proofs.has(change.file) || !isHash(change.beforeSha256) || proofs.get(change.file) !== change.beforeSha256
+      || typeof change.content !== 'string' || change.content.includes('\0')
+      || Buffer.from(change.content, 'utf8').toString('utf8') !== change.content) throw new Error('Each source change must have one matching proof and UTF-8 text content.');
+    changed.add(change.file); total += Buffer.byteLength(change.content);
+  }
+  if (total > 32 * 1024 * 1024) throw new Error('The source file plan exceeds its text resource limit.');
+  return plan;
+}
+
+/** Refuse symbolic links at every component, including links that stay inside the root. */
+async function inspectFile(root, file) {
+  const parts = file.split('/');
+  let current = root;
+  for (let index = 0; index < parts.length; index++) {
+    current = path.join(current, parts[index]);
+    let stat;
+    try { stat = await fsp.lstat(current); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (stat.isSymbolicLink()) throw new Error(`Source file plans cannot follow symbolic links: ${file}`);
+    if (index < parts.length - 1) {
+      if (!stat.isDirectory()) throw new Error(`A source parent is not a directory: ${file}`);
+    } else {
+      if (!stat.isFile()) throw new Error(`A source proof must identify a regular file: ${file}`);
+      const bytes = await fsp.readFile(current);
+      if (!Buffer.from(bytes.toString('utf8')).equals(bytes)) throw new Error(`Source file plans support UTF-8 text only: ${file}`);
+      return { bytes, sha256: hash(bytes), mode: stat.mode & 0o777 };
+    }
+  }
+  return null;
+}
+
+async function verify(root, plan) {
+  const files = new Map();
+  for (const proof of plan.proofs) {
+    const actual = await inspectFile(root, proof.file);
+    if ((actual?.sha256 ?? null) !== proof.sha256) throw new Error(`Source changed since review: ${proof.file}`);
+    files.set(proof.file, actual);
+  }
+  return files;
+}
+
+async function validated(root, input, options, operation) {
+  // Capture before waiting for another source operation; later caller mutations cannot change the plan.
+  const plan = captureSourceFilePlan(input, options);
+  const signal = options.signal;
+  return withSourceFileLock(root, async base => {
+    signal?.throwIfAborted();
+    const before = await verify(base, plan);
+    signal?.throwIfAborted();
+    const effective = plan.changes.filter(change => (before.get(change.file)?.bytes.toString('utf8') ?? '') !== change.content);
+    if (effective.length !== plan.changes.length) throw new Error('Every declared source change must produce a nonempty diff.');
+    return operation(base, plan, before, signal);
+  });
+}
+
+/** Validate the complete plan and produce diffs without writing any project file. */
+export async function previewSourceFilePlan(root, input, options) {
+  return validated(root, input, options, async (_base, plan, before) => ({
+    files: plan.changes.map(change => ({ file: change.file, diff: createUnifiedDiff(before.get(change.file)?.bytes.toString('utf8') ?? '', change.content, change.file) })),
+    affectedFiles: plan.changes.map(change => change.file).sort(),
+  }));
+}
+
+/** Stage all text, recheck every proof, and restore owned writes if publication fails. */
+export async function applySourceFilePlan(root, input, options) {
+  return validated(root, input, options, async (base, plan, before, signal) => {
+    const staged = new Map(); const published = []; const createdDirectories = [];
+    let result; let failure;
+    try {
+      for (const change of plan.changes) {
+        signal?.throwIfAborted();
+        const parent = path.dirname(path.join(base, change.file));
+        const missing = [];
+        for (let cursor = parent; cursor !== base; cursor = path.dirname(cursor)) {
+          try { await fsp.lstat(cursor); break; } catch (error) { if (error.code !== 'ENOENT') throw error; missing.push(cursor); }
+        }
+        for (const directory of missing.reverse()) { await fsp.mkdir(directory); createdDirectories.push(directory); }
+        await inspectFile(base, change.file);
+        const temporary = path.join(parent, `.pygmalion-source-${randomUUID()}.tmp`);
+        staged.set(change.file, temporary);
+        await fsp.writeFile(temporary, change.content, { flag: 'wx', mode: before.get(change.file)?.mode ?? 0o644 });
+      }
+      await verify(base, plan);
+      signal?.throwIfAborted();
+      for (const change of plan.changes) {
+        signal?.throwIfAborted();
+        const current = await inspectFile(base, change.file);
+        if ((current?.sha256 ?? null) !== change.beforeSha256) throw new Error(`Source changed during apply: ${change.file}`);
+        await fsp.rename(staged.get(change.file), path.join(base, change.file));
+        published.push(change); staged.delete(change.file);
+      }
+      signal?.throwIfAborted();
+      result = { applied: plan.changes.length, changed: plan.changes.length, files: plan.changes.map(change => change.file).sort() };
+    } catch (error) {
+      const failures = [];
+      for (const change of published.reverse()) {
+        try {
+          const current = await inspectFile(base, change.file);
+          if (current?.sha256 !== hash(Buffer.from(change.content))) throw new Error(`Concurrent source edit was preserved during rollback: ${change.file}`, { cause: error });
+          const original = before.get(change.file);
+          if (original) await fsp.writeFile(path.join(base, change.file), original.bytes, { mode: original.mode });
+          else await fsp.unlink(path.join(base, change.file));
+        } catch (rollback) { failures.push(rollback); }
+      }
+      failure = failures.length
+        ? new AggregateError([error, ...failures], 'Source publication failed and concurrent edits prevented complete rollback.', { cause: error })
+        : error;
+    }
+    const cleanup = await Promise.allSettled([...staged.values()].map(file => fsp.rm(file, { force: true })));
+    const cleanupErrors = cleanup.filter(item => item.status === 'rejected').map(item => item.reason);
+    for (const directory of createdDirectories.reverse()) {
+      try { await fsp.rmdir(directory); } catch (error) { if (!['ENOTEMPTY', 'ENOENT'].includes(error.code)) cleanupErrors.push(error); }
+    }
+    if (cleanupErrors.length) throw new AggregateError(failure ? [failure, ...cleanupErrors] : cleanupErrors, 'Source operation cleanup was incomplete.', { cause: failure ?? cleanupErrors[0] });
+    if (failure) throw failure;
+    return result;
+  });
+}

package/node/source-file-proofs.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/** Validate the same source bytes for both preview and apply. Legacy inputs omit the proof. */
+export async function validateInspectSourceProofs(root, input, { sourceRevision } = {}) {
+  if (input?.sourceProof === undefined) return;
+  const proof = input.sourceProof;
+  if (!proof || typeof proof !== 'object' || typeof proof.sourceRevision !== 'string' || !proof.sourceRevision.trim()
+    || !Array.isArray(proof.files) || proof.files.length < 1 || proof.files.length > 500) {
+    throw new Error('Source proof requires an exact revision and file hashes.');
+  }
+  if (sourceRevision !== undefined && proof.sourceRevision !== sourceRevision) {
+    throw new Error('Source proof does not match the active source revision.');
+  }
+  const base = await fsp.realpath(root);
+  const paths = new Set();
+  for (const item of proof.files) {
+    if (!item || typeof item.file !== 'string' || !item.file || path.isAbsolute(item.file)
+      || /[\\\0?#]/.test(item.file) || /^[a-z]:/i.test(item.file)
+      || item.file.split('/').some(part => !part || part === '.' || part === '..' || part === '.git')
+      || typeof item.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(item.sha256) || paths.has(item.file)) {
+      throw new Error('Source proof contains an invalid or duplicate file.');
+    }
+    paths.add(item.file);
+    const actualPath = await fsp.realpath(path.resolve(base, item.file));
+    const relative = path.relative(base, actualPath);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error('Source proof file escapes the application root.');
+    }
+    const stat = await fsp.stat(actualPath);
+    if (!stat.isFile()) throw new Error('Source proof must identify regular source files.');
+    const actual = createHash('sha256').update(await fsp.readFile(actualPath)).digest('hex');
+    if (actual !== item.sha256) throw new Error(`Source changed since the document was loaded: ${item.file}`);
+  }
+  const required = [
+    ...(input.styles ?? []).flatMap(style => [style.file, style.componentFile]),
+    ...(input.texts ?? []).map(text => text.componentFile),
+    ...(input.operations ?? []).map(operation => operation.identity?.componentFile),
+  ];
+  if (required.some(file => typeof file !== 'string' || !paths.has(file))) {
+    throw new Error('Source proof must cover every edited file and component source.');
+  }
+}

package/node/source-module.mjs

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute } from 'node:path';
+
+/** Evaluates trusted declaration code after the supplied bundler produces one in-memory CommonJS module. */
+export async function evaluateBundledSourceModule({ build, buildOptions, filename, require: requireModule }) {
+  if (typeof build !== 'function') throw new TypeError('A source module bundler is required.');
+  if (typeof filename !== 'string' || !isAbsolute(filename)) throw new TypeError('An absolute source module filename is required.');
+  if (requireModule !== undefined && typeof requireModule !== 'function') throw new TypeError('require must be a module loader.');
+  const result = await build({ ...buildOptions, bundle: true, format: 'cjs', platform: 'node', write: false });
+  if (result.outputFiles?.length !== 1 || typeof result.outputFiles[0]?.text !== 'string') {
+    throw new Error('The source module bundler must produce exactly one in-memory output.');
+  }
+  const module = { exports: {} };
+  const evaluate = new Function('module', 'exports', 'require', '__filename', '__dirname', result.outputFiles[0].text);
+  evaluate(module, module.exports, requireModule ?? createRequire(filename), filename, dirname(filename));
+  return module.exports;
+}

package/node/source-responsive-codec.d.mts

@@ -0,0 +1,17 @@
+import type { InspectApplyPayload, InspectMedia } from '../src/editor/inspect';
+import type { ResponsiveLayoutDocument, ResponsiveLayoutProperty, ResponsiveLayoutRange, ResponsiveLayoutSourceTarget } from '../src/workspace/source/responsiveContracts';
+export const RESPONSIVE_PROPERTIES: readonly ResponsiveLayoutProperty[];
+export const RESPONSIVE_COLLAPSED_VALUE: 'none';
+export function responsiveSizingProperty(property: string): boolean;
+export function responsiveFlexControl(property: string): boolean;
+export function sortResponsiveRanges<T extends ResponsiveLayoutRange>(ranges: readonly T[]): T[];
+export function responsiveRangePreviewWidth(ranges: readonly ResponsiveLayoutRange[], rangeId: string, preferred?: number): number;
+export function describeResponsiveValueContract(property: string, permitted?: readonly string[]): string;
+export function responsiveSourcePath(value: unknown): value is string;
+export function responsiveMediaQuery(media: InspectMedia): string;
+export function responsiveSourceHeader(range: ResponsiveLayoutRange): string;
+export function validateResponsiveRanges(ranges: unknown): void;
+export function validResponsiveValue(property: string, value: unknown, permitted?: readonly string[]): boolean;
+export function validateResponsiveTargets(targets: unknown): void;
+export function validateResponsiveState(state: unknown, ranges: readonly ResponsiveLayoutRange[], targets: readonly ResponsiveLayoutSourceTarget[]): asserts state is ResponsiveLayoutDocument;
+export function planResponsiveStyleChanges(before: ResponsiveLayoutDocument, after: ResponsiveLayoutDocument, ranges: readonly ResponsiveLayoutRange[], targets: readonly ResponsiveLayoutSourceTarget[]): InspectApplyPayload['styles'];