@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/node/workspace-draft-runtime.mjs

@@ -0,0 +1,67 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const WORKSPACE_DRAFT_TEMP_PREFIX = 'pygmalion-draft-preview-';
+export const WORKSPACE_DRAFT_OUTPUT_DIRECTORY = 'output';
+
+function relative(value) {
+  return typeof value === 'string' && value.length > 0 && !path.isAbsolute(value)
+    && !/^[a-z]:/i.test(value) && !/[\\\x00-\x1f\x7f?#]/.test(value)
+    && value.split('/').every(part => part && part !== '.' && part !== '..' && part !== '.git');
+}
+
+/** Own CLI cancellation listeners without exiting ahead of an active child process. */
+export function createWorkspaceDraftLifecycle() {
+  const controller = new AbortController();
+  const listeners = new Map();
+  for (const [name, exitCode] of [['SIGTERM', 143], ['SIGINT', 130]]) {
+    const listener = () => {
+      if (controller.signal.aborted) return;
+      process.exitCode = exitCode;
+      controller.abort(new DOMException('Draft execution cancelled.', 'AbortError'));
+    };
+    listeners.set(name, listener);
+    process.on(name, listener);
+  }
+  return Object.freeze({
+    signal: controller.signal,
+    dispose() { for (const [name, listener] of listeners) process.removeListener(name, listener); listeners.clear(); },
+  });
+}
+
+/** Verify that source and output belong to one SDK-created temporary layout. */
+export async function assertWorkspaceDraftDirectories({ appRoot, outputDirectory, appDirectory = '.' }) {
+  if (appDirectory !== '.' && !relative(appDirectory)) throw new TypeError('The draft application directory must be project-relative.');
+  const isolatedRoot = await realpath(appRoot);
+  const outputRoot = await realpath(outputDirectory);
+  const temporaryRoot = path.dirname(outputRoot);
+  const systemTemporary = await realpath(os.tmpdir());
+  if (path.dirname(temporaryRoot) !== systemTemporary || !path.basename(temporaryRoot).startsWith(WORKSPACE_DRAFT_TEMP_PREFIX)
+    || isolatedRoot !== path.join(temporaryRoot, 'source', appDirectory)
+    || path.basename(outputRoot) !== WORKSPACE_DRAFT_OUTPUT_DIRECTORY
+    || !(await stat(isolatedRoot)).isDirectory() || !(await stat(outputRoot)).isDirectory()) {
+    throw new Error('Draft compilation requires source and output directories from one isolated SDK preview.');
+  }
+  return Object.freeze({ appRoot: isolatedRoot, outputDirectory: outputRoot, temporaryRoot });
+}
+
+/** Import the explicit root ESM entry from this install, without falling back to the caller's dependencies. */
+export async function importIsolatedPackage({ appRoot, name }) {
+  if (typeof name !== 'string' || !/^(?:@[a-zA-Z0-9][\w.-]*\/)?[a-zA-Z0-9][\w.-]*$/.test(name)) {
+    throw new TypeError('An isolated package requires a complete package name.');
+  }
+  const directory = await realpath(path.join(appRoot, 'node_modules', name));
+  const metadata = JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+  const entry = metadata.exports?.['.']?.import;
+  if (typeof entry !== 'string' || !entry.startsWith('./') || !relative(entry.slice(2))) {
+    throw new Error(`The isolated package must declare a relative root import export: ${name}`);
+  }
+  const resolved = await realpath(path.join(directory, entry));
+  const local = path.relative(directory, resolved);
+  if (!relative(local) || !(await stat(resolved)).isFile()) {
+    throw new Error(`The isolated package entry must remain inside its package directory: ${name}`);
+  }
+  return import(pathToFileURL(resolved).href);
+}

package/node/workspace-source-identity.d.mts

@@ -0,0 +1 @@
+export declare function workspaceSourceFingerprint(value: unknown): string;

package/node/workspace-source-identity.mjs

@@ -0,0 +1,21 @@
+/** Full JSON identity with sorted object keys; array order and every value are retained. */
+export function workspaceSourceFingerprint(value) {
+  const ancestors = new Set();
+  const encode = (item) => {
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return JSON.stringify(item);
+    if (typeof item === 'number' && Number.isFinite(item)) return Object.is(item, -0) ? '-0' : String(item);
+    if (!item || typeof item !== 'object' || ancestors.has(item)
+      || (!Array.isArray(item) && ![Object.prototype, null].includes(Object.getPrototypeOf(item)))) throw new Error('Source fingerprints require complete, finite JSON values.');
+    ancestors.add(item);
+    try {
+      if (Object.getOwnPropertySymbols(item).length) throw new Error('Source fingerprints cannot omit symbol properties.');
+      if (Array.isArray(item)) {
+        if (Object.keys(item).length !== item.length || Array.from({ length: item.length }, (_, index) => index).some((index) => !Object.hasOwn(item, index))) throw new Error('Source fingerprints require dense JSON arrays.');
+        return `[${item.map(encode).join(',')}]`;
+      }
+      return `{${Object.keys(item).sort().map((key) => `${JSON.stringify(key)}:${encode(item[key])}`).join(',')}}`;
+    } finally { ancestors.delete(item); }
+  };
+  return encode(value);
+}
+

package/node/workspace-source-plan.mjs

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto';
+import { captureSourceFilePlan } from './source-file-plan.mjs';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const same = (left, right) => fingerprint(left) === fingerprint(right);
+function freeze(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+const capture = value => freeze(JSON.parse(fingerprint(value)));
+function limit(value, maximum, label) {
+  const selected = value ?? maximum;
+  if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) throw new Error(`${label} must be a positive integer no greater than ${maximum}.`);
+  return selected;
+}
+function targetIdentity(target) {
+  if (!record(target) || !text(target.screenId) || !text(target.sourceRevision)
+    || Object.keys(target).some(key => !['screenId', 'sourceRevision'].includes(key))) throw new Error('A source target requires an exact screen and source revision.');
+}
+function documentIdentity(document, target) {
+  if (!record(document) || document.schemaVersion !== 1 || !text(document.id)
+    || document.sourceRevision !== target.sourceRevision || !text(document.rootId)
+    || !record(document.nodes) || !record(document.nodes[document.rootId]) || !record(document.metadata)
+    || (document.metadata.screenId !== undefined && document.metadata.screenId !== target.screenId)) {
+    throw new Error('The complete design document must belong to the selected source target.');
+  }
+}
+function baselineIdentity(baseline, target) {
+  if (!record(baseline)) throw new Error('A source baseline requires a document and mapping.');
+  documentIdentity(baseline.document, target);
+  const mapping = baseline.mapping;
+  if (!record(mapping) || mapping.version !== 1 || !same(mapping.target, target)
+    || mapping.documentId !== baseline.document.id || mapping.baselineFingerprint !== fingerprint(baseline.document)
+    || !Array.isArray(mapping.rules) || !Array.isArray(mapping.files) || !mapping.files.length || mapping.files.length > 3000) {
+    throw new Error('The complete source mapping must identify its baseline, target, and file proofs.');
+  }
+  const files = new Set();
+  for (const proof of mapping.files) {
+    if (!record(proof) || !text(proof.file) || /[\\\x00-\x1f\x7f?#]/.test(proof.file)
+      || proof.file.startsWith('/') || /^[a-z]:/i.test(proof.file)
+      || proof.file.split('/').some(part => !part || ['.', '..', '.git'].includes(part))
+      || (proof.sha256 !== null && (typeof proof.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(proof.sha256))) || files.has(proof.file)) {
+      throw new Error('Source mapping proofs require unique relative files and exact SHA-256 hashes or explicit absence.');
+    }
+    files.add(proof.file);
+  }
+}
+function requestIdentity(target, baseline, document, plan) {
+  const parts = { version: 1, target, documentId: document.id, beforeFingerprint: fingerprint(baseline.document),
+    afterFingerprint: fingerprint(document), mappingFingerprint: fingerprint(baseline.mapping), payloadFingerprint: fingerprint(plan) };
+  return { ...parts, fingerprint: fingerprint(parts) };
+}
+function completePreview(result, plan) {
+  const files = new Set(plan.changes.map(change => change.file));
+  const complete = entries => Array.isArray(entries) && entries.length === files.size
+    && new Set(entries).size === files.size && entries.every(file => files.has(file));
+  if (!record(result) || !Array.isArray(result.files) || !complete(result.files.map(entry => entry?.file))
+    || !complete(result.affectedFiles) || result.files.some(entry => !text(entry.diff))) {
+    throw new Error('Review must include each changed file exactly once with a nonempty diff and affected-file entry.');
+  }
+}
+
+/**
+ * Authorize only plans compiled from a fresh host baseline and completely reviewed for one target.
+ * This service performs no source I/O. Host callbacks own compilation semantics and current file proofs.
+ */
+export function createWorkspaceSourcePlanService(options) {
+  const callbacks = Object.fromEntries(['loadBaseline', 'compilePlan', 'previewPlan', 'applyPlan', 'assertTarget'].map(name => [name, options?.[name]]));
+  if (Object.values(callbacks).some(callback => typeof callback !== 'function')) throw new Error('A source plan service requires baseline, compiler, preview, apply, and target callbacks.');
+  const ttl = limit(options.receiptTtlMs, 30 * 60_000, 'Receipt lifetime');
+  const capacity = limit(options.maxReceipts, 8, 'Receipt capacity');
+  const now = options.now ?? Date.now;
+  if (typeof now !== 'function') throw new Error('The source receipt clock must be callable.');
+  const clock = () => { const value = now(); if (!Number.isFinite(value)) throw new Error('The source receipt clock must return a finite timestamp.'); return value; };
+  const receipts = new Map(); const operations = new Set();
+  let disposed = false; let busy = null; let revision = 0;
+  const keyOf = (target, document) => hash(fingerprint({ target, document }));
+  const expired = (receipt, time) => time < receipt.createdAt || time - receipt.createdAt >= ttl;
+
+  const run = async (exclusive, externalSignal, operation) => {
+    if (disposed) throw new Error('The source plan service has been disposed.');
+    if (exclusive && busy) throw new Error('Another source plan operation is in progress.');
+    externalSignal?.throwIfAborted();
+    const controller = new AbortController();
+    const current = { controller };
+    const failureCleanups = [];
+    const abort = () => controller.abort(externalSignal.reason);
+    const check = () => {
+      controller.signal.throwIfAborted();
+      if (disposed) throw new Error('The source plan service has been disposed.');
+    };
+    operations.add(current); if (exclusive) busy = current;
+    try {
+      externalSignal?.addEventListener('abort', abort, { once: true });
+      const result = await operation({ signal: controller.signal, check, onFailure: cleanup => failureCleanups.push(cleanup) });
+      check(); return result;
+    } catch (error) {
+      for (const cleanup of failureCleanups) cleanup();
+      throw error;
+    } finally {
+      externalSignal?.removeEventListener('abort', abort); operations.delete(current);
+      if (busy === current) busy = null;
+    }
+  };
+  const assertTarget = async (target, operation) => {
+    operation.check(); targetIdentity(target);
+    await callbacks.assertTarget(target, operation.signal); operation.check();
+  };
+  const currentReceipt = (key, receipt, operation) => {
+    operation.check();
+    if (!receipt || receipts.get(key) !== receipt || expired(receipt, clock())) {
+      receipts.delete(key);
+      throw new Error('The compiled source receipt is missing, expired, or consumed. Compile and review again.');
+    }
+  };
+  const validate = async (input, operation, requireReview) => {
+    const request = capture(input);
+    if (!record(request) || request.sourceKind !== 'file-plan') throw new Error('A compiled file-plan request is required.');
+    targetIdentity(request.target); documentIdentity(request.document, request.target);
+    await assertTarget(request.target, operation);
+    const key = keyOf(request.target, request.document); const receipt = receipts.get(key);
+    currentReceipt(key, receipt, operation);
+    const identity = requestIdentity(receipt.target, receipt.baseline, receipt.document, receipt.plan);
+    if (!same(request.payload, receipt.plan) || !same(request.identity, identity)) throw new Error('The request must match the complete compiled document, source mapping, target, and file plan.');
+    if (requireReview && receipt.reviewed !== identity.fingerprint) throw new Error('Review the complete source diff for this target before applying or building.');
+    return { request, key, receipt };
+  };
+  return {
+    load(input, signal) {
+      return run(false, signal, async operation => {
+        const target = capture(input); await assertTarget(target, operation);
+        const baseline = capture(await callbacks.loadBaseline(target, operation.signal));
+        operation.check(); baselineIdentity(baseline, target); operation.check(); return baseline;
+      });
+    },
+    compile(input, signal) {
+      return run(true, signal, async operation => {
+        const { target, baseline, document } = capture(input);
+        targetIdentity(target); baselineIdentity(baseline, target); documentIdentity(document, target);
+        if (document.id !== baseline.document.id || document.rootId !== baseline.document.rootId) throw new Error('The edited document must retain the source baseline identity.');
+        if (same(document, baseline.document)) throw new Error('There are no document changes to compile.');
+        const key = keyOf(target, document); receipts.delete(key);
+        await assertTarget(target, operation);
+        const actual = capture(await callbacks.loadBaseline(target, operation.signal));
+        operation.check(); baselineIdentity(actual, target);
+        if (!same(baseline, actual)) throw new Error('The supplied baseline differs from the current host source baseline.');
+        const compiled = await callbacks.compilePlan(capture({ target, baseline: actual, document }), operation.signal);
+        operation.check();
+        const plan = capture(captureSourceFilePlan(compiled, { sourceRevision: target.sourceRevision, allowedFiles: actual.mapping.files.map(proof => proof.file) }));
+        if (!same(plan.proofs, actual.mapping.files)) throw new Error('The compiled plan must retain every source mapping proof exactly.');
+        if (plan.changes.some(change => change.beforeSha256 === hash(change.content))) throw new Error('Every compiled source change must produce different content.');
+        const createdAt = clock(); operation.check();
+        for (const [oldKey, receipt] of receipts) if (expired(receipt, createdAt)) receipts.delete(oldKey);
+        const receipt = { target, baseline: actual, document, plan, createdAt, reviewed: null };
+        receipts.set(key, receipt);
+        operation.onFailure(() => { if (receipts.get(key) === receipt) receipts.delete(key); });
+        while (receipts.size > capacity) receipts.delete(receipts.keys().next().value);
+        return plan;
+      });
+    },
+    preview(input, signal) {
+      return run(true, signal, async operation => {
+        const { request, key, receipt } = await validate(input, operation, false);
+        receipt.reviewed = null;
+        const result = capture(await callbacks.previewPlan(receipt.plan, request.target, operation.signal));
+        currentReceipt(key, receipt, operation); completePreview(result, receipt.plan);
+        receipt.reviewed = request.identity.fingerprint;
+        operation.onFailure(() => { receipt.reviewed = null; });
+        return capture({ ...result, revision: ++revision });
+      });
+    },
+    validatePreviewRequest(input, signal) {
+      return run(true, signal, async operation => (await validate(input, operation, true)).request);
+    },
+    apply(input, signal) {
+      return run(true, signal, async operation => {
+        const { request, receipt } = await validate(input, operation, true);
+        // Once a writer starts, every cached review requires recompilation, including failed or aborted writes.
+        receipts.clear(); operation.check();
+        const result = capture(await callbacks.applyPlan(receipt.plan, request.target, operation.signal));
+        operation.check();
+        if (!record(result) || !Number.isSafeInteger(result.applied) || result.applied < 1) throw new Error('The source writer did not record the reviewed changes. Compile and review again.');
+        return result;
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true; receipts.clear();
+      for (const operation of operations) operation.controller.abort(new Error('The source plan service has been disposed.'));
+    },
+  };
+}

package/node/workspace-source-session.mjs

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { applySourceFilePlan, previewSourceFilePlan } from './source-file-plan.mjs';
+import { createWorkspaceSourcePlanService } from './workspace-source-plan.mjs';
+import { readSourceInputs } from './source-service-inputs.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => fingerprint(left) === fingerprint(right);
+function capture(value) {
+  const freeze = item => { if (item && typeof item === 'object') { Object.values(item).forEach(freeze); Object.freeze(item); } return item; };
+  return freeze(JSON.parse(fingerprint(value)));
+}
+const baselineKey = (target, baseline) => fingerprint([target, fingerprint(baseline.document), fingerprint(baseline.mapping)]);
+
+/** Retain server proofs across external edits while keeping projection and compilation host-defined. */
+export function createWorkspaceSourceSession({
+  appRoot, allowedFiles, overlayFiles = allowedFiles, optionalFiles = [], inputFiles,
+  loadCodec, assertTarget: validateTarget, archive, currentRevision, projectBaseline,
+  compilePlan, previewPlan = previewSourceFilePlan, applyPlan = applySourceFilePlan,
+  reconcile, projectReconcileInputs, applyMessage = 'The reviewed source changes were applied.',
+}) {
+  if (![inputFiles, loadCodec, validateTarget, archive, currentRevision, projectBaseline, compilePlan, reconcile, projectReconcileInputs].every(callback => typeof callback === 'function')) {
+    throw new Error('A source session requires explicit projection, compilation, reconciliation, revision, and archive callbacks.');
+  }
+  const readInputs = (root, files, signal) => readSourceInputs(root, files, { optionalFiles, signal });
+  const baselines = new Map();
+  const working = new Map();
+  const operations = new Set();
+  let disposed = false; let busy; let archiveService;
+  const check = signal => { signal.throwIfAborted(); if (disposed) throw new Error('The source service has been disposed.'); };
+  const retain = (map, key, value) => {
+    map.delete(key); map.set(key, { ...value, createdAt: Date.now() });
+    while (map.size > 8) { const oldest = map.keys().next().value; map.get(oldest).service?.dispose(); map.delete(oldest); }
+  };
+  const lookup = (map, key) => {
+    const value = map.get(key);
+    const now = Date.now();
+    if (value && (now < value.createdAt || now - value.createdAt >= 30 * 60_000)) { value.service?.dispose(); map.delete(key); return undefined; }
+    return value;
+  };
+  const run = async (signal, operation) => {
+    if (disposed) throw new Error('The source service has been disposed.');
+    signal?.throwIfAborted();
+
+    while (busy?.controller.signal.aborted) {
+      await busy.settled; signal?.throwIfAborted();
+      if (disposed) throw new Error('The source service has been disposed.');
+    }
+    if (busy) throw new Error('Another source review is in progress.');
+    const controller = new AbortController();
+    let finish;
+    const settled = new Promise(resolve => { finish = resolve; });
+    const slot = { controller, settled }; busy = slot; operations.add(controller);
+    const abort = () => controller.abort(signal.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    try { const result = await operation(controller.signal); check(controller.signal); return result; }
+    finally { signal?.removeEventListener('abort', abort); operations.delete(controller); if (busy === slot) busy = undefined; finish(); }
+  };
+  const assertTarget = async (target, signal) => {
+    check(signal);
+    if (!target || typeof target.screenId !== 'string' || !/^[a-f0-9]{40}$/.test(target.sourceRevision ?? '')) throw new Error('An exact source target is required.');
+    await validateTarget(target, signal); check(signal);
+  };
+  const assertHead = async (target, signal) => {
+    check(signal);
+    if (await currentRevision() !== target.sourceRevision) throw new Error('The working source revision differs from the selected revision.');
+    check(signal);
+  };
+  const fromInputs = async (codec, target, sourceInputs, projectedStructure, signal) => {
+    const result = await projectBaseline({ codec, target, sourceInputs, projectedStructure }, signal);
+    check(signal); return capture(result);
+  };
+  const currentInputs = async (context, signal) => {
+    await assertHead(context.target, signal);
+    const actual = await readInputs(appRoot, Object.keys(context.inputs), signal);
+    await assertHead(context.target, signal);
+    if (!same(actual, context.inputs)) throw new Error('Working inputs changed after reconciliation. Review the source again.');
+  };
+
+  const overlay = async (context, root, signal) => {
+    if (await realpath(root) === await realpath(appRoot)) throw new Error('Reconciled inputs require an isolated source root.');
+    const original = await readInputs(root, Object.keys(context.archiveInputs), signal);
+    if (!same(original, context.archiveInputs)) throw new Error('The isolated archive differs from the retained source proof.');
+    const changes = Object.keys(original).filter(file => original[file] !== context.inputs[file]).map(file => {
+      if (context.inputs[file] === null) throw new Error('Reconciliation cannot delete a source input.');
+      return { file, beforeSha256: original[file] === null ? null : hash(original[file]), content: context.inputs[file] };
+    });
+    if (changes.length) await applySourceFilePlan(root, { version: 1, sourceRevision: context.target.sourceRevision,
+      proofs: Object.entries(original).map(([file, source]) => ({ file, sha256: source === null ? null : hash(source) })), changes,
+    }, { sourceRevision: context.target.sourceRevision, allowedFiles: overlayFiles, signal });
+    check(signal);
+    if (!same(await readInputs(root, Object.keys(context.inputs), signal), context.inputs)) throw new Error('The isolated inputs differ from the reconciled baseline.');
+  };
+  const isolated = (target, context, signal, operation) => archive(target.sourceRevision, signal, async ({ appRoot: root }) => {
+    if (context) await overlay(context, root, signal);
+    check(signal); return operation(root);
+  });
+  const clearOtherReviews = active => {
+    if (active !== archiveService) { archiveService.dispose(); archiveService = makeService(); }
+    for (const [key, context] of working) if (context.service !== active) { context.service.dispose(); working.delete(key); }
+  };
+  function makeService(context) {
+    const service = createWorkspaceSourcePlanService({
+      async assertTarget(target, signal) { await assertTarget(target, signal); if (context) await currentInputs(context, signal); },
+      async loadBaseline(target, signal) {
+        if (context) return context.baseline;
+        const codec = await loadCodec(); check(signal);
+        return isolated(target, null, signal, async root => {
+          const inputs = capture(await readInputs(root, inputFiles(codec), signal));
+          const baseline = await fromInputs(codec, target, inputs, undefined, signal);
+          retain(baselines, baselineKey(target, baseline), { target: capture(target), baseline, inputs, codec });
+          return baseline;
+        });
+      },
+      compilePlan({ target, baseline, document }, signal) {
+        return isolated(target, context, signal, root => compilePlan({ appRoot: root, sourceRevision: target.sourceRevision,
+          before: baseline.document, after: document, mapping: baseline.mapping, signal, ...(context ? { reconciledIdentity: context.identity } : {}) }));
+      },
+      previewPlan(plan, target, signal) {
+        return isolated(target, context, signal, root => previewPlan(root, plan, { sourceRevision: target.sourceRevision, allowedFiles, signal }));
+      },
+      async applyPlan(plan, target, signal) {
+        await assertHead(target, signal); clearOtherReviews(service);
+        const result = await applyPlan(appRoot, plan, { sourceRevision: target.sourceRevision, allowedFiles, signal });
+        return { applied: result.applied, message: applyMessage };
+      },
+    });
+    return service;
+  }
+  archiveService = makeService();
+  const forBaseline = input => lookup(working, baselineKey(input.target, input.baseline));
+  const forRequest = request => lookup(working, fingerprint([request.target, request.identity?.beforeFingerprint ?? '', request.identity?.mappingFingerprint ?? '']));
+  return Object.freeze({
+    load(input, signal) { const target = capture(input); return run(signal, current => archiveService.load(target, current)); },
+    compile(input, signal) { const request = capture(input); return run(signal, current => (forBaseline(request)?.service ?? archiveService).compile(request, current)); },
+    preview(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).preview(request, current)); },
+    apply(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).apply(request, current)); },
+    validatePreviewRequest(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).validatePreviewRequest(request, current)); },
+    preparePreviewSource(input, root, signal) {
+      const request = capture(input);
+      return run(signal, async current => {
+        const context = forRequest(request);
+        await (context?.service ?? archiveService).validatePreviewRequest(request, current);
+        if (context) await overlay(context, root, current);
+      });
+    },
+    reconcile(input, signal) {
+      if (!input || typeof input !== 'object' || Object.keys(input).some(key => !['target', 'baseline', 'document'].includes(key))) {
+        throw new Error('Reconciliation accepts only a target, baseline, and document.');
+      }
+      const request = capture(input);
+      return run(signal, async current => {
+        await assertTarget(request.target, current); await assertHead(request.target, current);
+        const key = baselineKey(request.target, request.baseline);
+        const origin = lookup(baselines, key) ?? lookup(working, key);
+        if (!origin) throw new Error('The retained source baseline is unavailable. Load it again.');
+        const externalInputs = capture(await readInputs(appRoot, Object.keys(origin.inputs), current));
+        await assertHead(request.target, current);
+        const loadBaseline = ({ target, sourceInputs, projectedStructure }, operationSignal) => fromInputs(origin.codec, target, sourceInputs, projectedStructure, operationSignal);
+        const result = capture(await reconcile({ ...request, baselineInputs: origin.inputs, externalInputs, loadBaseline,
+          ...(origin.identity ? { baselineIdentity: origin.identity } : {}) }, current));
+        check(current);
+        if (result.status !== 'ready') return result;
+        const projected = projectReconcileInputs({ baselineInputs: origin.inputs, externalInputs,
+          ...(origin.identity ? { baselineIdentity: origin.identity } : {}) });
+        const baseline = await fromInputs(origin.codec, request.target, externalInputs, projected.projectedStructure, current);
+        if (!same(result.baseline, baseline) || !same(result.document, request.document)) throw new Error('The reconciled result differs from the verified baseline or complete document.');
+        const nextKey = baselineKey(request.target, baseline);
+        if (nextKey !== key) {
+          const context = { target: request.target, baseline, inputs: externalInputs, archiveInputs: origin.archiveInputs ?? origin.inputs, codec: origin.codec, identity: projected.identity };
+          await currentInputs(context, current);
+          context.service = makeService(context);
+          lookup(working, nextKey)?.service.dispose(); retain(working, nextKey, context);
+        }
+        return result;
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const controller of operations) controller.abort(new Error('The source service has been disposed.'));
+      archiveService.dispose(); for (const context of working.values()) context.service.dispose();
+      working.clear(); baselines.clear();
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {
@@ -48,12 +48,54 @@
       "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
     },
-    "./style.css": "./dist-lib/style.css"
+    "./style.css": "./dist-lib/style.css",
+    "./binding-source": {
+      "types": "./binding-source.d.ts",
+      "default": "./node/source-bindings.mjs"
+    },
+    "./draft-preview": {
+      "types": "./draft-preview.d.ts",
+      "default": "./node/workspace-draft-preview.mjs"
+    },
+    "./source-files": {
+      "types": "./source-files.d.ts",
+      "default": "./node/source-file-plan.mjs"
+    },
+    "./source-structure": {
+      "types": "./source-structure.d.ts",
+      "default": "./node/source-structure.mjs"
+    },
+    "./source-plan": {
+      "types": "./workspace-source-plan.d.ts",
+      "default": "./node/workspace-source-plan.mjs"
+    },
+    "./source-responsive": {
+      "types": "./source-responsive.d.ts",
+      "default": "./node/source-responsive.mjs"
+    },
+    "./host-runtime": {
+      "types": "./host-runtime.d.ts",
+      "default": "./node/host-runtime.mjs"
+    },
+    "./source-service": {
+      "types": "./source-service.d.ts",
+      "default": "./node/source-service.mjs"
+    },
+    "./draft-entry": {
+      "types": "./workspace-draft-entry.d.ts",
+      "default": "./node/workspace-draft-entry.mjs"
+    },
+    "./source-module": {
+      "types": "./source-module.d.ts",
+      "default": "./node/source-module.mjs"
+    },
+    "./source-reconciler": {
+      "types": "./jsx-source-reconciler.d.ts",
+      "default": "./node/jsx-source-reconciler.mjs"
+    }
   },
   "files": [
     "dist-lib",
-    "docs/coverage-contracts.md",
-    "docs/screen-state-contract.md",
     "node/contract.mjs",
     "node/contract.d.mts",
     "node/component-branches.mjs",
@@ -79,6 +121,12 @@
     "node/source-diff.mjs",
     "node/source-graph.mjs",
     "node/source-operations.mjs",
+    "node/source-file-proofs.mjs",
+    "node/workspace-source-identity.mjs",
+    "node/workspace-source-identity.d.mts",
+    "node/workspace-draft-preview-plugin.mjs",
+    "node/workspace-draft-preview.mjs",
+    "draft-preview.d.ts",
     "node/storyboard-canonical.mjs",
     "node/storyboard-capture-scheduler.mjs",
     "node/storyboard-capture-sessions.mjs",
@@ -92,13 +140,49 @@
     "qa.d.ts",
     "storyboard.d.ts",
     "runtime.d.ts",
-    "vite.d.ts"
+    "vite.d.ts",
+    "node/source-bindings.mjs",
+    "binding-source.d.ts",
+    "node/source-file-plan.mjs",
+    "node/source-file-lock.mjs",
+    "source-files.d.ts",
+    "node/source-archive.mjs",
+    "node/token-source-references.mjs",
+    "node/source-structure.mjs",
+    "source-structure.d.ts",
+    "node/workspace-source-plan.mjs",
+    "workspace-source-plan.d.ts",
+    "node/source-structure-reconcile.mjs",
+    "node/source-structure-wrapper-codec.mjs",
+    "node/source-structure-wrapper-codec.d.mts",
+    "node/source-responsive.mjs",
+    "source-responsive.d.ts",
+    "node/source-responsive-codec.mjs",
+    "node/source-responsive-codec.d.mts",
+    "host-runtime.d.ts",
+    "node/host-runtime.mjs",
+    "source-service.d.ts",
+    "node/source-service.mjs",
+    "workspace-draft-entry.d.ts",
+    "node/workspace-draft-entry.mjs",
+    "source-module.d.ts",
+    "node/source-module.mjs",
+    "node/workspace-draft-process.mjs",
+    "node/revision-catalog-resolver.mjs",
+    "node/source-archive-runtime.mjs",
+    "node/source-service-inputs.mjs",
+    "node/source-service-plugin.mjs",
+    "node/workspace-source-session.mjs",
+    "node/token-source-service.mjs",
+    "jsx-source-reconciler.d.ts",
+    "node/jsx-source-reconciler.mjs",
+    "node/workspace-draft-runtime.mjs"
   ],
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
     "build:lib": "vite build --config vite.lib.config.ts && npm run build:types",
-    "test": "node --test node/*.test.mjs src/*.test.mjs src/**/*.test.mjs",
+    "test": "node --test 'node/**/*.test.mjs' 'src/**/*.test.mjs'",
     "lint": "eslint .",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",

package/source-files.d.ts

@@ -0,0 +1,35 @@
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { InspectPreviewResult } from './dist-lib/types/editor/host.js';
+
+export interface SourceFilePlanOptions {
+  sourceRevision: string;
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  signal?: AbortSignal;
+}
+/** Capture and validate a serializable plan without reading or changing source files. */
+export declare function captureSourceFilePlan(plan: SourceFilePlan, options: SourceFilePlanOptions): SourceFilePlan;
+export declare function previewSourceFilePlan(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'>>;
+export declare function applySourceFilePlan(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<{ applied: number; changed: number; files: string[] }>;
+
+export interface TokenSourceReferenceEdit { start: number; end: number; before: string; after: string }
+export interface TokenSourceReferenceDiagnostic { code: string; message: string; file: string; start?: number; name?: string }
+/** Diagnostics block the complete rewrite; offsets address UTF-16 source positions. */
+export declare function rewriteTokenSourceReferences(input: {
+  file: string;
+  source: string;
+  renames: readonly { from: string; to: string | null }[];
+}): {
+  source: string;
+  edits: TokenSourceReferenceEdit[];
+  diagnostics: TokenSourceReferenceDiagnostic[];
+  references: { name: string; start: number; end: number; kind: 'static' | 'finite' }[];
+};
+
+/**
+ * Build/validation workers must settle before the callback returns and its archive is removed.
+ * Cancellation waits for callback settlement and cleanup, then rejects even if the callback returned.
+ */
+export declare function withSourceArchive<T>(options: {
+  projectRoot: string; sourceRevision: string; appDirectory?: string; signal?: AbortSignal;
+}, operation: (context: Readonly<{ appRoot: string; sourceRevision: string; signal: AbortSignal }>) => Promise<T>): Promise<T>;