@pygmalionjs/pygmalion 0.8.1 → 0.9.0

package/dist-lib/types/workspace/tokens/controller.d.ts

@@ -0,0 +1,44 @@
+import type { TokenLibraryEngine } from '../../token-library/contracts.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../../editor/host.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceTokenLibraryBaseline, WorkspaceTokenLibraryCapabilities, WorkspaceTokenSourceRequest } from './contracts.js';
+export interface WorkspaceTokenLibraryState {
+    status: 'idle' | 'loading' | 'ready' | 'reviewing' | 'reviewed' | 'applying' | 'applied' | 'error';
+    baseline?: WorkspaceTokenLibraryBaseline;
+    engine?: TokenLibraryEngine;
+    request?: WorkspaceTokenSourceRequest;
+    preview?: InspectPreviewResult;
+    result?: InspectApplyResult;
+    savedFingerprint?: string;
+    saving?: boolean;
+    error?: string;
+}
+/** A library owns its draft and review independently from visual screen sessions. */
+export declare class WorkspaceTokenLibraryController {
+    private state;
+    private listeners;
+    private epoch;
+    private pending;
+    private pendingSave;
+    private saveGeneration;
+    private disposed;
+    private invalidating;
+    private applying;
+    private unsubscribe;
+    private writer;
+    readonly capabilities: WorkspaceTokenLibraryCapabilities;
+    readonly sourceRevision: string;
+    constructor(sourceRevision: string, capabilities: WorkspaceTokenLibraryCapabilities);
+    getSnapshot: () => WorkspaceTokenLibraryState;
+    subscribe: (listener: () => void) => () => void;
+    private update;
+    private invalidate;
+    private current;
+    private subscribeEngine;
+    load(): Promise<boolean>;
+    saveDraft(): Promise<boolean>;
+    review(target: WorkspaceTarget): Promise<boolean>;
+    apply(): Promise<boolean>;
+    reset(): boolean;
+    dispose(): void;
+}

package/dist-lib/types/workspace/view/PrototypePlayer.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { DesignDocument } from '../../document/contracts.js';
+import { type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeClock } from './prototypePlayback.js';
+
+export interface PrototypePlayerProps {
+    document: DesignDocument;
+    /** Uses the same document/component renderer as Edit, with authoring controls disabled. */
+    renderScene(rootId: string, state: PrototypeState): ReactNode;
+    sceneSize?(rootId: string, state: PrototypeState): {
+        width: number;
+        height: number;
+    } | undefined;
+    onClose(): void;
+    clock?: PrototypeClock;
+}
+export declare function PrototypePlayer(props: PrototypePlayerProps): import("react").JSX.Element;

package/dist-lib/types/workspace/view/StoryboardWorkspace.d.ts

@@ -0,0 +1,3 @@
+export declare const StoryboardWorkspace: import("react").FunctionComponent<{
+    sourceRevision: string;
+}>;

package/dist-lib/types/workspace/view/prototypePlayback.d.ts

@@ -0,0 +1,46 @@
+import type { DesignDocument, DocumentNode, ResolvedDocumentNode } from '../../document/contracts.js';
+import { type PrototypeEffect, type PrototypeEvent, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
+export interface PrototypeClock {
+    now(): number;
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+export interface PrototypePlayerSnapshot {
+    state: PrototypeState;
+    previous: PrototypeState | null;
+    effects: readonly PrototypeEffect[];
+    playing: boolean;
+}
+export interface PrototypePlayerOptions extends PrototypeStartOptions {
+    clock: PrototypeClock;
+    /** Effects describe intended links and scrolling; the adapter decides how to execute them. */
+    onEffect?(effect: PrototypeEffect): void;
+}
+export interface PrototypePlayerController {
+    getSnapshot(): PrototypePlayerSnapshot;
+    subscribe(listener: () => void): () => void;
+    dispatch(event: PrototypeEvent): void;
+    pause(): void;
+    resume(): void;
+    dispose(): void;
+}
+/** One document snapshot and one clock. Playback cannot mutate the document engine or its history. */
+export declare function createPrototypePlayer(document: DesignDocument, options: PrototypePlayerOptions): PrototypePlayerController;
+export interface PrototypePresentationScene {
+    id: string;
+    rootId: string;
+    root: ResolvedDocumentNode;
+    x: number;
+    y: number;
+    overlay: boolean;
+    backdrop: {
+        color: string;
+        opacity: number;
+    } | null;
+}
+export declare function prototypeScene(document: DesignDocument, state: PrototypeState): PrototypePresentationScene[];
+export declare function prototypeFlowOptions(document: DesignDocument): {
+    id: string;
+    label: string;
+    node: DocumentNode;
+}[];

package/draft-preview.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { WorkspaceSourceRequest } from './dist-lib/types/workspace/source/flowContracts.js';
+import type { WorkspaceTokenSourceRequest } from './dist-lib/types/workspace/tokens/contracts.js';
+import type { WorkspaceApplicationSurface } from './dist-lib/types/workspace/contracts.js';
+
+export type WorkspaceDraftSourceRequest = WorkspaceSourceRequest | WorkspaceTokenSourceRequest;
+
+export interface WorkspaceDraftPreviewServiceOptions {
+  projectRoot: string;
+  appDirectory?: string;
+  /** Existing node_modules directory reused by the trusted isolated build. */
+  dependenciesRoot?: string;
+  /**
+   * Stage proven working-copy inputs in the disposable archive. Full request proofs are checked afterward.
+   * `appRoot` holds exactly `sourceRevision` (the request target), materialized from the repository
+   * history rather than the working tree, so another revision than the checkout can be built honestly.
+   */
+  prepareSource?(context: { appRoot: string; request: WorkspaceDraftSourceRequest; sourceRevision: string; signal: AbortSignal }): Promise<void>;
+  /** Must stop and settle when aborted; outputDirectory must contain a completed static app. */
+  build(context: { appRoot: string; outputDirectory: string; request: WorkspaceDraftSourceRequest; sourceRevision: string; signal: AbortSignal }): Promise<void>;
+  /** Return true after handling a host API request. False or void allows static routing. */
+  handleRequest?(request: IncomingMessage, response: ServerResponse, context: { request: WorkspaceDraftSourceRequest; sourceRevision: string }): boolean | void | Promise<boolean | void>;
+  /** Active builds and ready origins count toward this bound. Default: 3. */
+  maxRuns?: number;
+  maxOutputFiles?: number;
+  maxOutputBytes?: number;
+}
+
+export declare function createWorkspaceDraftPreviewService(options: WorkspaceDraftPreviewServiceOptions): {
+  /** The host must validate file-plan requests with its canonical compiler before preparing a build. */
+  prepare(input: { request: WorkspaceDraftSourceRequest; documentRevision: string; route: string }, options?: { signal?: AbortSignal }): Promise<WorkspaceApplicationSurface>;
+  /** Abort builds, close origins, and remove every temporary archive. */
+  dispose(): Promise<void>;
+};
+
+/** Minimal Vite-compatible boundary; headless service consumers do not require Vite types. */
+export declare function workspaceDraftPreviewPlugin(options: {
+  service: ReturnType<typeof createWorkspaceDraftPreviewService>;
+  endpoint?: string;
+  /** The built app reports its recipe result through the workspace ready-message protocol. */
+  waitForReady?: boolean;
+  /** Validate file-plan source semantics with the host compiler, not only browser-supplied fingerprints. */
+  resolveRequest(input: unknown, options: { signal: AbortSignal }):
+    { request: WorkspaceDraftSourceRequest; documentRevision: string; route: string } |
+    Promise<{ request: WorkspaceDraftSourceRequest; documentRevision: string; route: string }>;
+}): {
+  name: string;
+  apply: 'serve';
+  configureServer(server: {
+    httpServer?: { once(event: 'close', listener: () => void): unknown } | null;
+    config: { logger: { error(message: string): void } };
+    middlewares: { use(handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void | Promise<void>): unknown };
+  }): void;
+};

package/inspect.d.ts

@@ -1,6 +1,8 @@
 import type { InspectApplyPayload } from './dist-lib/types/lib';
 
 export interface PygmalionInspectWritebackOptions {
+  /** If supplied, source proofs must use this exact source revision. */
+  sourceRevision?: string;
   sourceDirectory?: string;
   normalizeValue?: (property: string, value: string) => string;
 }

package/node/design-session.mjs

@@ -12,6 +12,7 @@ import { normalizeViteMode } from './dev-mirror.mjs';
 import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
 import { createUnifiedDiff } from './source-diff.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
 import { resolvePygmalionPreviewViteCacheDir } from './preview-vite-cache.mjs';
 import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
@@ -696,6 +697,7 @@ export function pygmalionDesignSessionPlugin(options) {
       if (dirty) throw new Error(`There are unconfirmed changes in the edit session task folder:${dirty.split('\n')[0]}`);
 
       const sessionAppRoot = appRootForWorktree(session.worktreeRoot);
+      await validateInspectSourceProofs(sessionAppRoot, input.changes, { sourceRevision: session.baseDevSha });
       const files = collectVisualFiles(sessionAppRoot, changes);
       const before = new Map();
       for (const [relativeFile, absoluteFile] of files) {
@@ -748,6 +750,7 @@ export function pygmalionDesignSessionPlugin(options) {
       if (dirty) throw new Error(`There are unconfirmed changes in the edit session task folder:${dirty.split('\n')[0]}`);
 
       const sessionAppRoot = appRootForWorktree(session.worktreeRoot);
+      await validateInspectSourceProofs(sessionAppRoot, input.changes, { sourceRevision: session.baseDevSha });
       const files = collectVisualFiles(sessionAppRoot, { styles, texts, operations });
       const backups = new Map();
       for (const [relativeFile, absoluteFile] of files) {

package/node/inspect-plugin.mjs

@@ -24,8 +24,10 @@ export { writeSourceOperations } from './source-operations.mjs';
 // POST /__pygmalion-inspect/impact — Check dedependency closure of changed files.
 // The editor doesn't know the endpoint URL — the onInspectApply callback in design-editor.tsx POSTs here.
 
+// Only a real import statement at the start of a line registers; the same text inside a
+// string literal or comment must not create a registration for an undefined identifier.
 const CSS_MODULE_IMPORT_RE =
-  /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.scss)['"]\s*;?/g;
+  /^[ \t]*import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.scss)['"]\s*;?/gm;
 
 export const PYGMALION_INSPECT_CONTROL = PYGMALION_ENDPOINTS.inspectControl;
 

package/node/inspect-writeback.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
 import { createUnifiedDiff } from './source-diff.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
+import { withSourceFileLock } from './source-file-lock.mjs';
 
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts']);
 
@@ -100,8 +102,9 @@ async function applyInspectChanges(root, changes, options) {
   };
 }
 
-export async function previewInspectChanges(root, input, options = {}) {
+async function previewInspectChangesUnlocked(root, input, options = {}) {
   const appRoot = path.resolve(root);
+  await validateInspectSourceProofs(appRoot, input, options);
   const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
   const changes = normalizeInspectChanges(input);
   const files = collectInspectFiles(appRoot, changes, sourceDirectory);
@@ -136,8 +139,9 @@ export async function previewInspectChanges(root, input, options = {}) {
   }
 }
 
-export async function writeInspectChanges(root, input, options = {}) {
+async function writeInspectChangesUnlocked(root, input, options = {}) {
   const appRoot = path.resolve(root);
+  await validateInspectSourceProofs(appRoot, input, options);
   const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
   const changes = normalizeInspectChanges(input);
   const files = collectInspectFiles(appRoot, changes, sourceDirectory);
@@ -161,3 +165,15 @@ export async function writeInspectChanges(root, input, options = {}) {
     throw error;
   }
 }
+
+export async function previewInspectChanges(root, input, options = {}) {
+  const snapshot = structuredClone(input);
+  const configuration = { ...options };
+  return withSourceFileLock(root, base => previewInspectChangesUnlocked(base, snapshot, configuration));
+}
+
+export async function writeInspectChanges(root, input, options = {}) {
+  const snapshot = structuredClone(input);
+  const configuration = { ...options };
+  return withSourceFileLock(root, base => writeInspectChangesUnlocked(base, snapshot, configuration));
+}

package/node/preview-artifact-store.mjs

@@ -1230,7 +1230,6 @@ export function createPreviewArtifactStore({
   ) => {
     const manifest = await readManifest(namespace);
     let aggregate = null;
-    const contentFreshIds = new Set();
     const sourcePendingIds = new Set();
     if (manifest) {
       // Index once per read. The earlier path filtered the complete manifest for
@@ -1272,12 +1271,21 @@ export function createPreviewArtifactStore({
             artifact.frames[request.id]
           ) {
             const frame = artifact.frames[request.id];
+            const acceptedAsFresh = exactSet.has(entry);
             const withProvenance = {
               ...artifact,
               frames: {
                 ...artifact.frames,
                 [request.id]: {
                   ...frame,
+                  // A matching recipe plus unchanged observed source files is
+                  // a content proof for the requested fingerprint. Serve that
+                  // proof under the requested identity so browser bootstrap
+                  // reaches the same exact verdict as the manifest resolver.
+                  // The original capture revision remains truthful provenance.
+                  ...(acceptedAsFresh && request.fingerprint != null
+                    ? { fingerprint: request.fingerprint }
+                    : {}),
                   ...(entry.sourceRevision == null
                     ? {}
                     : { sourceRevision: entry.sourceRevision }),
@@ -1288,8 +1296,7 @@ export function createPreviewArtifactStore({
               aggregate,
               withProvenance,
             );
-            if (exactSet.has(entry)) {
-              contentFreshIds.add(request.id);
+            if (acceptedAsFresh) {
               sourcePendingIds.delete(request.id);
             }
             break;
@@ -1304,10 +1311,6 @@ export function createPreviewArtifactStore({
     );
     return {
       ...selection,
-      // The wire-level selector only knows fingerprints. A frame whose recipe
-      // and observed files were verified against the requested source context is
-      // also current, even when its coarse source fingerprint changed.
-      stale: selection.stale.filter((id) => !contentFreshIds.has(id)),
       ...(sourcePendingIds.size
         ? { sourcePending: [...sourcePendingIds] }
         : {}),

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;
+  });
+}