@pygmalionjs/pygmalion 0.9.0 → 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-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-service-inputs.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const relative = file => typeof file === 'string' && file.length > 0 && !path.isAbsolute(file)
+  && !/^[a-z]:/i.test(file) && !/[\\\x00-\x1f\x7f?#]/.test(file)
+  && !file.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+
+/** Absence is only proven through ordinary directories, including every existing ancestor. */
+export async function assertSourceInputParent(root, file) {
+  if (!relative(file)) throw new Error('A source input requires a relative file path.');
+  let directory = root;
+  for (const part of file.split('/').slice(0, -1)) {
+    directory = path.join(directory, part);
+    let stat;
+    try { stat = await lstat(directory); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (!stat.isDirectory() || await realpath(directory) !== directory) throw new Error('Source inputs cannot traverse linked directories.');
+  }
+}
+
+export async function readSourceInputs(appRoot, files, { optionalFiles = [], signal, maxBytes = 32 * 1024 * 1024 } = {}) {
+  if (!Array.isArray(files) || !files.length || files.length > 3000 || new Set(files).size !== files.length
+    || files.some(file => !relative(file)) || !Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('Source inputs require unique relative files and a positive byte limit.');
+  const selected = [...files]; const optional = new Set(optionalFiles); const inputs = {}; let bytes = 0;
+  const root = await realpath(appRoot);
+  for (const file of selected) {
+    signal?.throwIfAborted();
+    await assertSourceInputParent(root, file);
+    const absolute = path.join(root, file);
+    let stat;
+    try { stat = await lstat(absolute); }
+    catch (error) { if (!optional.has(file) || error.code !== 'ENOENT') throw error; Object.defineProperty(inputs, file, { value: null, enumerable: true }); continue; }
+    if (!stat.isFile() || await realpath(absolute) !== absolute) throw new Error(`Source input must be a regular unlinked file: ${file}`);
+    if (bytes + stat.size > maxBytes) throw new Error('Source inputs exceed the byte limit.');
+    const buffer = await readFile(absolute); bytes += buffer.length;
+    if (bytes > maxBytes || !Buffer.from(buffer.toString('utf8')).equals(buffer)) throw new Error('Source inputs must be UTF-8 within the byte limit.');
+    Object.defineProperty(inputs, file, { value: buffer.toString('utf8'), enumerable: true, configurable: true, writable: true });
+  }
+  signal?.throwIfAborted();
+  return inputs;
+}
+
+/** Seed isolated UTF-8 source files and always remove the directory after the callback settles. */
+export async function withSourceFiles({ files, signal }, operation) {
+  const entries = files instanceof Map ? [...files] : null;
+  if (!entries || entries.length > 3000 || typeof operation !== 'function'
+    || entries.some(([file, source]) => !relative(file) || typeof source !== 'string' || Buffer.from(source).toString('utf8') !== source)) {
+    throw new Error('Isolated source files require a map of relative paths to UTF-8 strings.');
+  }
+  signal?.throwIfAborted();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'pygmalion-source-'));
+  try {
+    for (const [file, source] of entries) {
+      signal?.throwIfAborted();
+      const destination = path.join(root, file);
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, source, { flag: 'wx' });
+    }
+    signal?.throwIfAborted();
+    const result = await operation(root);
+    signal?.throwIfAborted();
+    return result;
+  } finally { await rm(root, { recursive: true, force: true }); }
+}
+
+export async function readProvenSourceFiles(appRoot, proofs, options = {}) {
+  if (!Array.isArray(proofs) || !proofs.length || proofs.length > 500 || proofs.some(proof => !proof ||
+    !(proof.sha256 === null && options.optionalFiles?.includes(proof.file) || typeof proof.sha256 === 'string' && /^[a-f0-9]{64}$/.test(proof.sha256)))) {
+    throw new Error('Source proofs require exact hashes or explicitly allowed absence.');
+  }
+  const selected = proofs.map(({ file, sha256 }) => ({ file, sha256 }));
+  const inputs = await readSourceInputs(appRoot, selected.map(proof => proof.file), options);
+  return new Map(selected.map(proof => {
+    const source = inputs[proof.file];
+    const hash = source === null ? null : createHash('sha256').update(source).digest('hex');
+    if (hash !== proof.sha256) throw new Error(`Source changed since the baseline was loaded: ${proof.file}`);
+    return [proof.file, { ...proof, source }];
+  }));
+}

package/node/source-service-plugin.mjs

@@ -0,0 +1,57 @@
+/** Local JSON transport. Operation names and all filesystem/build callbacks come from host configuration. */
+export function sourceServicePlugin({ name = 'pygmalion-source-service', endpoint, operations, createService, transformInput = (_operation, input) => input, maxBytes = 40 * 1024 * 1024 }) {
+  if (!/^\/[A-Za-z0-9/_-]+$/.test(endpoint) || endpoint.endsWith('/') || !Array.isArray(operations) || !operations.length
+    || operations.some(operation => !/^[a-z][A-Za-z]+$/.test(operation) || ['constructor', 'dispose'].includes(operation))
+    || typeof createService !== 'function' || typeof transformInput !== 'function' || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new Error('A source transport requires a local endpoint, operation allowlist, factory, and byte limit.');
+  }
+  operations = [...operations];
+  let service; const controllers = new Set();
+  const active = () => { if (!service) throw new Error('The source service has not started.'); return service; };
+  return {
+    validatePreviewRequest(request, signal) { return active().validatePreviewRequest(request, signal); },
+    preparePreviewSource(request, root, signal) { return active().preparePreviewSource(request, root, signal); },
+    plugin: {
+      name, apply: 'serve',
+      configureServer(server) {
+        service = createService(server);
+        if (operations.some(operation => typeof service?.[operation] !== 'function')) throw new Error('The source service must implement each configured operation.');
+        server.httpServer?.once('close', () => {
+          for (const controller of controllers) controller.abort();
+          controllers.clear();
+          Promise.resolve().then(() => service.dispose()).catch(error => server.config?.logger?.error(String(error)));
+        });
+        server.middlewares.use(async (req, res, next) => {
+          const pathname = req.url?.split('?')[0];
+          const operation = pathname?.startsWith(`${endpoint}/`) ? pathname.slice(endpoint.length + 1) : undefined;
+          if (!operations.includes(operation)) return next();
+          res.setHeader('content-type', 'application/json; charset=utf-8'); res.setHeader('cache-control', 'no-store');
+          if (req.method !== 'POST') { res.statusCode = 405; res.end(JSON.stringify({ error: 'Source operations require POST.' })); return; }
+          try {
+            if (req.headers.origin && new URL(req.headers.origin).host !== req.headers.host) throw new Error('Origin mismatch.');
+          } catch { res.statusCode = 403; res.end(JSON.stringify({ error: 'Source operations require the editor origin.' })); return; }
+          if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] ?? '')) {
+            res.statusCode = 415; res.end(JSON.stringify({ error: 'Source operations require JSON.' })); return;
+          }
+          const controller = new AbortController(); controllers.add(controller);
+          const abort = () => { if (!res.writableEnded) controller.abort(); };
+          req.once('aborted', abort); res.once('close', abort);
+          try {
+            const chunks = []; let bytes = 0;
+            for await (const chunk of req) {
+              bytes += chunk.length;
+              if (bytes > maxBytes) throw new Error('Source request exceeds the byte limit.');
+              chunks.push(chunk);
+            }
+            controller.signal.throwIfAborted();
+            const input = transformInput(operation, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            const result = await service[operation](input, controller.signal);
+            controller.signal.throwIfAborted(); res.end(JSON.stringify(result));
+          } catch (error) {
+            if (!res.destroyed && !res.writableEnded) { res.statusCode = 409; res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) })); }
+          } finally { controllers.delete(controller); req.removeListener('aborted', abort); res.removeListener('close', abort); }
+        });
+      },
+    },
+  };
+}

package/node/source-service.mjs

@@ -0,0 +1,4 @@
+export { createWorkspaceSourceSession } from './workspace-source-session.mjs';
+export { createTokenSourceService } from './token-source-service.mjs';
+export { sourceServicePlugin } from './source-service-plugin.mjs';
+export { assertSourceInputParent, readSourceInputs, readProvenSourceFiles, withSourceFiles } from './source-service-inputs.mjs';

package/node/token-source-service.mjs

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { applySourceFilePlan, previewSourceFilePlan, captureSourceFilePlan } from './source-file-plan.mjs';
+
+const capture = value => JSON.parse(fingerprint(value));
+const keyOf = value => createHash('sha256').update(fingerprint(value)).digest('hex');
+const expired = receipt => { const now = Date.now(); return now < receipt.createdAt || now - receipt.createdAt >= 30 * 60_000; };
+function completePreview(result, plan) {
+  const changed = new Set(plan.changes.map(change => change.file));
+  const complete = entries => Array.isArray(entries) && entries.length === changed.size
+    && new Set(entries).size === changed.size && entries.every(file => changed.has(file));
+  if (!result || !Array.isArray(result.files) || !complete(result.files.map(entry => entry?.file))
+    || !complete(result.affectedFiles) || result.files.some(entry => typeof entry.diff !== 'string' || !entry.diff.trim())) {
+    throw new Error('Review must include each changed file exactly once with a nonempty diff and affected-file entry.');
+  }
+}
+
+/** Token codecs describe the product files; this service owns receipts, review, cancellation, and source application. */
+export function createTokenSourceService({
+  appRoot, loadCodec, assertRevision, assertTarget, archive, loadSource, compilePlan, listConsumers,
+  previewPlan = previewSourceFilePlan, applyPlan = applySourceFilePlan, currentRevision,
+  regenerate, install, applyMessage = 'The reviewed token source changes were applied.',
+  regenerationFailureMessage = error => `Source changes were applied, but regeneration failed: ${error instanceof Error ? error.message : String(error)}`,
+}) {
+  if (![loadCodec, assertRevision, assertTarget, archive, loadSource, compilePlan, listConsumers, currentRevision, regenerate, install].every(callback => typeof callback === 'function')) {
+    throw new Error('A token source service requires explicit codec, source, revision, and build callbacks.');
+  }
+  const receipts = new Map();
+  let busy = false; let revision = 0; let disposed = false;
+  const checkActive = signal => {
+    signal.throwIfAborted();
+    if (disposed) throw new Error('The token source service has been disposed.');
+  };
+  const checkRevision = async (value, signal) => {
+    checkActive(signal);
+    if (typeof value !== 'string' || !/^[a-f0-9]{40}$/.test(value)) throw new Error('An exact source revision is required.');
+    await assertRevision(value, signal); checkActive(signal);
+  };
+  const receiptKey = document => keyOf({ sourceRevision: document.sourceRevision, document });
+  const validateRequest = async (input, signal, requireReview = true) => {
+    const request = capture(input);
+    await checkRevision(request?.target?.sourceRevision, signal);
+    if (request.sourceKind !== 'file-plan') throw new Error('A compiled file-plan request is required.');
+    await assertTarget(request.target, signal); checkActive(signal);
+    const receipt = receipts.get(receiptKey(request.document));
+    if (!receipt || receipt.consumed || expired(receipt)) throw new Error('The token source receipt is unavailable or expired. Compile and review again.');
+    if (request.target.sourceRevision !== request.document.sourceRevision || receipt.plan.sourceRevision !== request.target.sourceRevision) throw new Error('The target, token document, and source plan revisions differ.');
+    const beforeFingerprint = fingerprint(receipt.before);
+    const parts = { version: 1, target: request.target, documentId: request.document.id, beforeFingerprint,
+      afterFingerprint: fingerprint(request.document),
+      mappingFingerprint: fingerprint({ version: 1, target: request.target, documentId: request.document.id, baselineFingerprint: beforeFingerprint, files: receipt.plan.proofs }),
+      payloadFingerprint: fingerprint(receipt.plan) };
+    if (fingerprint(request.payload) !== parts.payloadFingerprint || fingerprint(request.identity) !== fingerprint({ ...parts, fingerprint: fingerprint(parts) })) {
+      throw new Error('The complete token document and source plan differ from the reviewed request.');
+    }
+    if (requireReview && !receipt.reviewed.has(request.identity.fingerprint)) throw new Error('Review the complete token source diff for this target first.');
+    return { request, receipt };
+  };
+  const service = {
+    async load(sourceRevision, signal) {
+      await checkRevision(sourceRevision, signal);
+      const codec = await loadCodec();
+      checkActive(signal);
+      const result = await archive(sourceRevision, signal, async ({ appRoot: root }) => {
+        const baseline = await loadSource({ appRoot: root, sourceRevision, codec, signal });
+        checkActive(signal);
+        return capture({ document: baseline.document, proofs: baseline.proofs, sourceFiles: baseline.sourceFiles, ledger: baseline.ledger });
+      });
+      checkActive(signal);
+      return result;
+    },
+    async compile(input, signal) {
+      const { baseline, document } = capture(input);
+      receipts.delete(receiptKey(document));
+      await checkRevision(document.sourceRevision, signal);
+      const codec = await loadCodec();
+      checkActive(signal);
+      const receipt = await archive(document.sourceRevision, signal, async ({ appRoot: root }) => {
+        const actual = await loadSource({ appRoot: root, sourceRevision: document.sourceRevision, codec, signal });
+        checkActive(signal);
+        if (fingerprint(baseline) !== fingerprint({ document: actual.document, proofs: actual.proofs })) throw new Error('The token source baseline differs from the loaded source.');
+        if (document.id !== actual.document.id || actual.document.sourceRevision !== document.sourceRevision) throw new Error('The edited token library differs from the source identity.');
+        await install(root, signal); checkActive(signal);
+        const compiled = await compilePlan({ appRoot: root, sourceRevision: document.sourceRevision, before: actual.document, after: document, codec, signal, dependenciesReady: true });
+        checkActive(signal);
+        const plan = captureSourceFilePlan(compiled, { sourceRevision: document.sourceRevision, allowedFiles: actual.proofs.map(proof => proof.file) });
+        if (plan.version !== 1 || plan.sourceRevision !== document.sourceRevision || fingerprint(plan.proofs) !== fingerprint(actual.proofs)) throw new Error('The compiled plan proofs differ from the loaded source.');
+        if (!plan.changes.length) throw new Error('There are no token source changes to apply.');
+        return { before: capture(actual.document), plan: capture(plan), consumerFiles: [...actual.consumerFiles], reviewed: new Set(), consumed: false, createdAt: Date.now() };
+      });
+
+      checkActive(signal);
+      const key = receiptKey(document); receipts.delete(key); receipts.set(key, receipt);
+      for (const [oldKey, oldReceipt] of receipts) if (expired(oldReceipt)) receipts.delete(oldKey);
+      while (receipts.size > 8) receipts.delete(receipts.keys().next().value);
+      return capture(receipt.plan);
+    },
+    async preview(input, signal) {
+      const { request, receipt } = await validateRequest(input, signal, false);
+      receipt.reviewed.delete(request.identity.fingerprint);
+      const result = await archive(request.target.sourceRevision, signal, ({ appRoot: root }) => previewPlan(root, capture(receipt.plan), {
+        sourceRevision: request.target.sourceRevision, allowedFiles: receipt.plan.changes.map(change => change.file), signal,
+      }));
+      checkActive(signal);
+      if (receipts.get(receiptKey(request.document)) !== receipt || receipt.consumed || expired(receipt)) throw new Error('The token source receipt changed or expired during review. Review again.');
+      completePreview(result, receipt.plan);
+      receipt.reviewed.add(request.identity.fingerprint);
+      return { ...result, revision: ++revision };
+    },
+    async validatePreviewRequest(input, signal) {
+      const { request } = await validateRequest(input, signal);
+      return request;
+    },
+    async apply(input, signal) {
+      const { request, receipt } = await validateRequest(input, signal);
+      receipt.consumed = true; receipts.clear();
+      if (await currentRevision() !== request.target.sourceRevision) throw new Error('The working source revision differs from the selected revision.');
+      checkActive(signal);
+      if (fingerprint(await listConsumers(appRoot, signal)) !== fingerprint(receipt.consumerFiles)) throw new Error('The token consumer file set changed after review. Compile and review again.');
+      checkActive(signal);
+      const result = await applyPlan(appRoot, capture(receipt.plan), {
+        sourceRevision: request.target.sourceRevision, allowedFiles: receipt.plan.changes.map(change => change.file), signal,
+      });
+      receipts.clear();
+      checkActive(signal);
+      if (!result || !Number.isSafeInteger(result.applied) || result.applied < 1) throw new Error('The source writer did not record the reviewed changes. Compile and review again.');
+      try { await regenerate(signal); }
+      catch (error) { return { applied: result.applied, message: regenerationFailureMessage(error) }; }
+      return { applied: result.applied, message: applyMessage };
+    },
+    dispose() { disposed = true; receipts.clear(); },
+  };
+  const operations = new Set();
+  return Object.freeze(Object.fromEntries(Object.entries(service).map(([name, operation]) => [name,
+    name === 'dispose' ? () => {
+      for (const controller of operations) controller.abort(new Error('The token source service has been disposed.'));
+      operation();
+    } : async (input, signal) => {
+      if (disposed) throw new Error('The token source service has been disposed.');
+      signal?.throwIfAborted();
+      const exclusive = name !== 'load';
+      if (exclusive && busy) throw new Error('Another token source operation is in progress.');
+      if (exclusive) busy = true;
+      const controller = new AbortController(); operations.add(controller);
+      const abort = () => controller.abort(signal.reason);
+      signal?.addEventListener('abort', abort, { once: true });
+      try { const result = await operation(input, controller.signal); checkActive(controller.signal); return result; }
+      finally { signal?.removeEventListener('abort', abort); operations.delete(controller); if (exclusive) busy = false; }
+    },
+  ])));
+}

package/node/workspace-draft-entry.mjs

@@ -0,0 +1,52 @@
+function text(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} must be a non-empty string.`);
+  return value;
+}
+
+function literal(value) {
+  const serialized = workspaceSourceFingerprint(value);
+  return serialized.replace(/[<\u2028\u2029]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/** Creates a browser module that reports a mounted draft recipe through the workspace readiness protocol. */
+export function createWorkspaceDraftEntry({
+  documentRevision,
+  recipe,
+  sdkModule = '@pygmalionjs/pygmalion',
+  desiredStateAdapter,
+  failureMessage = 'Draft state could not be reproduced: ',
+}) {
+  text(documentRevision, 'documentRevision');
+  text(sdkModule, 'sdkModule');
+  text(failureMessage, 'failureMessage');
+  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) throw new TypeError('recipe must be an object.');
+  if (desiredStateAdapter) {
+    text(desiredStateAdapter.module, 'desiredStateAdapter.module');
+    text(desiredStateAdapter.exportName, 'desiredStateAdapter.exportName');
+  }
+  return `import { runWorkspaceDraftRecipe } from ${literal(sdkModule)};
+${desiredStateAdapter ? `import * as desiredStateAdapter from ${literal(desiredStateAdapter.module)};` : ''}
+const controller = new AbortController();
+addEventListener('pagehide', () => controller.abort(), { once: true });
+document.documentElement.dataset.pygmalionDraftStatus = 'preparing';
+Promise.resolve().then(() => {
+  controller.signal.throwIfAborted();
+  return runWorkspaceDraftRecipe({ document, window }, JSON.parse(${literal(workspaceSourceFingerprint(recipe))}), {
+    signal: controller.signal,
+    ${desiredStateAdapter ? `applyDesiredState(state, context) { return desiredStateAdapter[${literal(desiredStateAdapter.exportName)}](state, context); },` : ''}
+  });
+}).then(() => {
+  if (controller.signal.aborted) return;
+  document.documentElement.dataset.pygmalionDraftStatus = 'ready';
+  parent.postMessage({ type: 'pygmalion:workspace-draft-ready', documentRevision: ${literal(documentRevision)}, status: 'ready' }, '*');
+}, error => {
+  if (controller.signal.aborted) return;
+  document.documentElement.dataset.pygmalionDraftStatus = 'failed';
+  const message = document.createElement('div');
+  message.setAttribute('role', 'alert');
+  message.textContent = ${literal(failureMessage)} + String(error?.message ?? error);
+  document.body.prepend(message);
+  parent.postMessage({ type: 'pygmalion:workspace-draft-ready', documentRevision: ${literal(documentRevision)}, status: 'failed', message: message.textContent }, '*');
+});`;
+}
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';

package/node/workspace-draft-preview.mjs

@@ -8,6 +8,7 @@ import { writeInspectChanges } from './inspect-writeback.mjs';
 import { validateInspectSourceProofs } from './source-file-proofs.mjs';
 import { applySourceFilePlan } from './source-file-plan.mjs';
 import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';
+import { WORKSPACE_DRAFT_TEMP_PREFIX, WORKSPACE_DRAFT_OUTPUT_DIRECTORY } from './workspace-draft-runtime.mjs';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
 const same = (left, right) => workspaceSourceFingerprint(left) === workspaceSourceFingerprint(right);
@@ -129,7 +130,7 @@ export function createWorkspaceDraftPreviewService(options) {
     run.done = (async () => {
       let ready = false;
       try {
-        run.temporary = await fsp.mkdtemp(path.join(os.tmpdir(), 'pygmalion-draft-preview-'));
+        run.temporary = await fsp.mkdtemp(path.join(os.tmpdir(), WORKSPACE_DRAFT_TEMP_PREFIX));
         controller.signal.throwIfAborted();
         // The archive holds exactly the requested commit, whatever the repository's
         // working tree or HEAD currently contains. Every host callback receives that
@@ -158,7 +159,7 @@ export function createWorkspaceDraftPreviewService(options) {
           if (!(await fsp.stat(dependencies)).isDirectory()) throw new Error('The dependency root must identify an existing node_modules directory.');
           await fsp.symlink(dependencies, path.join(appRoot, 'node_modules'), 'dir');
         }
-        const outputDirectory = path.join(run.temporary, 'output');
+        const outputDirectory = path.join(run.temporary, WORKSPACE_DRAFT_OUTPUT_DIRECTORY);
         await fsp.mkdir(outputDirectory);
         await build({ appRoot, outputDirectory, request: captured.request, sourceRevision, signal: controller.signal });
         controller.signal.throwIfAborted();