fundus 0.0.4 → 0.2.0

package/dist/server/operations.js

@@ -6,12 +6,14 @@
  * operation has exactly one implementation and there is no other save path.
  */
 import { join } from 'node:path';
-import { allDeliveredAssetIds, collectAllReferences, compareCodeUnits, computeLibraryMembership, folderOfRawPath, rawFileNameOfPath } from '../core/index.js';
+import { assetIdError, allDeliveredAssetIds, collectAllReferences, compareCodeUnits, computeLibraryMembership, folderOfRawPath, parentFolderPath, portableFolderPathKey, proposeAssetId, rawFileNameOfPath, typesForFileName } from '../core/index.js';
 import { LibraryStore } from './library-store.js';
 import { generateManifestModules } from './codegen.js';
 import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
 import { processAssets, readCurrentProxy } from './processing/processor.js';
 import { encodeRelativePathForUrl } from './folder-filesystem.js';
+import { classifyRawDirectory, verifyStableRawFile } from './raw-reconciliation.js';
+import { rawSafetyIssues } from './raw-safety.js';
 /**
  * The CLI's `--parameters` merge semantics (M7): a SHALLOW merge at the top
  * level onto the current parameters — a nested object value replaces the whole
@@ -42,6 +44,8 @@ export class FundusOperations {
     #config;
     #registry;
     #store;
+    #operationQueue = Promise.resolve();
+    #pipelineQueue = Promise.resolve();
     constructor(config, registry = serverPluginsByType) {
         this.#config = config;
         this.#registry = registry;
@@ -53,9 +57,171 @@ export class FundusOperations {
     get store() {
         return this.#store;
     }
-    /** Read-only state snapshot (no processing). */
-    async state() {
-        return this.#buildState(await this.#store.read(), []);
+    #enqueueOperation(operation) {
+        const run = this.#operationQueue.then(operation, operation);
+        this.#operationQueue = run.then(() => { }, () => { });
+        return run;
+    }
+    /** Read-only state snapshot, serialized with mutations but never processing or writing. */
+    state() {
+        return this.#enqueueOperation(() => this.#state());
+    }
+    async #state() {
+        await this.#pipelineQueue;
+        const library = await this.#store.read();
+        const classification = await this.#classifyRawDirectory(library);
+        return this.#snapshotState(library, classification);
+    }
+    /** Reconcile only changes that are safe without a user decision: unique moves and deletions. */
+    reconcileRawState() {
+        return this.#enqueueOperation(async () => {
+            let library = await this.#store.read();
+            let classification = await this.#classifyRawDirectory(library);
+            if (!this.#canAutoReconcile(classification)) {
+                return this.#snapshotState(library, classification);
+            }
+            for (let pass = 0; pass < 2; pass++) {
+                const result = await this.#store.transactCandidate(async (candidate, current) => {
+                    const fresh = await this.#classifyRawDirectory(current);
+                    const affectedIds = [];
+                    if (!this.#canAutoReconcile(fresh))
+                        return { classification: fresh, affectedIds };
+                    for (const move of fresh.moves) {
+                        candidate.assets[move.assetId].raw = move.path;
+                        this.#registerFolderAncestors(candidate, folderOfRawPath(move.path));
+                        affectedIds.push(move.assetId);
+                    }
+                    for (const deletion of fresh.deletions) {
+                        delete candidate.assets[deletion.assetId];
+                        affectedIds.push(deletion.assetId);
+                    }
+                    return { classification: fresh, affectedIds };
+                });
+                library = result.library;
+                classification = result.value.classification;
+                if (!result.changed)
+                    return this.#snapshotState(library, classification);
+                await this.#store.syncFolders(library);
+                for (const id of result.value.affectedIds)
+                    await this.#store.deleteProxiesOf(id);
+                const snapshot = await this.#afterMutationSnapshot(library);
+                library = snapshot.library;
+                classification = snapshot.classification;
+                if (classification.moves.length === 0 && classification.deletions.length === 0) {
+                    return snapshot.state;
+                }
+                if (!this.#canAutoReconcile(classification, true))
+                    return snapshot.state;
+            }
+            return this.#snapshotState(library, classification, [
+                {
+                    message: 'Raw directory kept changing during reconciliation; refresh again after external file operations settle.'
+                }
+            ]);
+        });
+    }
+    /** Adopt an already-existing raw file without copying, renaming, or deleting it. */
+    adoptRawFile(token, id, type, manifests = []) {
+        return this.#enqueueOperation(async () => {
+            const result = await this.#store.transactCandidate(async (candidate, current) => {
+                const classification = await this.#classifyRawDirectory(current);
+                const file = classification.unmanaged.find((entry) => this.#newToken(entry.path, entry.hash) === token);
+                if (!file)
+                    throw new Error('This ingestion item is stale; refresh the editor and try again.');
+                const idProblem = assetIdError(id);
+                if (idProblem)
+                    throw new Error(idProblem);
+                if (Object.hasOwn(candidate.assets, id))
+                    throw new Error(`An asset with id "${id}" already exists.`);
+                const compatibleTypes = this.#compatibleTypes(file.path);
+                if (!compatibleTypes.includes(type)) {
+                    throw new Error(`The ${type} type does not accept "${file.path}".`);
+                }
+                const uniqueManifests = [...new Set(manifests)];
+                for (const name of uniqueManifests) {
+                    if (!Object.hasOwn(candidate.manifests, name)) {
+                        throw new Error(`Unknown manifest "${name}".`);
+                    }
+                }
+                const plugin = serverPluginForType(type, this.#registry);
+                let parameters = plugin.descriptor.defaultParameters(plugin.pluginConfig(this.#config));
+                parameters = plugin.descriptor.validateParameters(parameters);
+                if (plugin.seedIngestParameters) {
+                    const seeded = await plugin.seedIngestParameters({
+                        rawPath: join(this.#config.rawDir, file.path),
+                        rawFileName: rawFileNameOfPath(file.path),
+                        parameters,
+                        config: this.#config
+                    });
+                    if (seeded !== undefined)
+                        parameters = plugin.descriptor.validateParameters(seeded);
+                }
+                await verifyStableRawFile(join(this.#config.rawDir, file.path), file.hash);
+                this.#registerFolderAncestors(candidate, folderOfRawPath(file.path));
+                candidate.assets[id] = {
+                    type,
+                    raw: file.path,
+                    rawHash: file.hash,
+                    parameters,
+                    manifests: uniqueManifests.sort()
+                };
+            });
+            await this.#store.syncFolders(result.library);
+            return this.#afterMutation(result.library);
+        });
+    }
+    /** Reset/reseed edited bytes, optionally changing to another compatible type. */
+    acceptEditedRawFile(token, type) {
+        return this.#enqueueOperation(async () => {
+            const result = await this.#store.transactCandidate(async (candidate, current) => {
+                const classification = await this.#classifyRawDirectory(current);
+                const edited = this.#editedRawFiles(classification, current).find((entry) => this.#editedToken(entry.assetId, entry.path, entry.hash) === token);
+                if (!edited)
+                    throw new Error('This edited item is stale; refresh the editor and try again.');
+                if (!this.#compatibleTypes(edited.path).includes(type)) {
+                    throw new Error(`The ${type} type does not accept "${edited.path}".`);
+                }
+                const plugin = serverPluginForType(type, this.#registry);
+                let parameters = plugin.descriptor.validateParameters(plugin.descriptor.defaultParameters(plugin.pluginConfig(this.#config)));
+                if (plugin.seedIngestParameters) {
+                    const seeded = await plugin.seedIngestParameters({
+                        rawPath: join(this.#config.rawDir, edited.path),
+                        rawFileName: rawFileNameOfPath(edited.path),
+                        parameters,
+                        config: this.#config
+                    });
+                    if (seeded !== undefined)
+                        parameters = plugin.descriptor.validateParameters(seeded);
+                }
+                await verifyStableRawFile(join(this.#config.rawDir, edited.path), edited.hash);
+                const record = candidate.assets[edited.assetId];
+                record.type = type;
+                record.rawHash = edited.hash;
+                record.parameters = parameters;
+                return edited.assetId;
+            });
+            await this.#store.deleteProxiesOf(result.value);
+            return this.#afterMutation(result.library);
+        });
+    }
+    /** Accept edited bytes while preserving type, parameters, path and memberships. */
+    dismissEditedRawFile(token) {
+        return this.#enqueueOperation(async () => {
+            const result = await this.#store.transactCandidate(async (candidate, current) => {
+                const classification = await this.#classifyRawDirectory(current);
+                const edited = this.#editedRawFiles(classification, current).find((entry) => this.#editedToken(entry.assetId, entry.path, entry.hash) === token);
+                if (!edited)
+                    throw new Error('This edited item is stale; refresh the editor and try again.');
+                const record = current.assets[edited.assetId];
+                if (!this.#compatibleTypes(edited.path).includes(record.type)) {
+                    throw new Error(`The moved file "${edited.path}" is not compatible with its current ${record.type} type; choose a compatible type and process it.`);
+                }
+                candidate.assets[edited.assetId].rawHash = edited.hash;
+                return edited.assetId;
+            });
+            await this.#store.deleteProxiesOf(result.value);
+            return this.#afterMutation(result.library);
+        });
     }
     /**
      * Ingest an upload: store the raw file + record, then let the owning
@@ -66,7 +232,10 @@ export class FundusOperations {
      * explicit membership set in the same operation; a failing application
      * rolls the whole ingest back, so a failed ingest leaves nothing behind.
      */
-    async ingest(options) {
+    ingest(options) {
+        return this.#enqueueOperation(() => this.#ingest(options));
+    }
+    async #ingest(options) {
         let library = await this.#store.ingest(options);
         try {
             const plugin = serverPluginForType(options.type, this.#registry);
@@ -96,7 +265,10 @@ export class FundusOperations {
         return this.#afterMutation(library);
     }
     /** Apply a PATCH body: parameters and/or manifests and/or a rename — in that order. */
-    async patchAsset(id, body) {
+    patchAsset(id, body) {
+        return this.#enqueueOperation(() => this.#patchAsset(id, body));
+    }
+    async #patchAsset(id, body) {
         let library = await this.#store.read();
         this.#requireAsset(library, id);
         if (body.parameters !== undefined) {
@@ -122,11 +294,24 @@ export class FundusOperations {
         }
         return this.#afterMutation(library);
     }
-    async moveAsset(id, folder) {
+    moveAsset(id, folder) {
+        return this.#enqueueOperation(() => this.#moveAsset(id, folder));
+    }
+    async #moveAsset(id, folder) {
         return this.#afterMutation(await this.#store.moveAsset(id, folder));
     }
+    /** Replace the raw bytes/name and run the normal processing + codegen tail. */
+    replaceRawFile(id, options) {
+        return this.#enqueueOperation(() => this.#replaceRawFile(id, options));
+    }
+    async #replaceRawFile(id, options) {
+        return this.#afterMutation(await this.#store.replaceRawFile(id, options));
+    }
     /** Move a selected asset set as one editor action and roll back on any failure. */
-    async moveAssets(assetIds, folder) {
+    moveAssets(assetIds, folder) {
+        return this.#enqueueOperation(() => this.#moveAssets(assetIds, folder));
+    }
+    async #moveAssets(assetIds, folder) {
         const uniqueIds = [...new Set(assetIds)];
         if (uniqueIds.length === 0)
             throw new Error('At least one asset id is required.');
@@ -154,16 +339,28 @@ export class FundusOperations {
             throw cause;
         }
     }
-    async createFolder(path) {
+    createFolder(path) {
+        return this.#enqueueOperation(() => this.#createFolder(path));
+    }
+    async #createFolder(path) {
         return this.#afterMutation(await this.#store.createFolder(path));
     }
-    async renameFolder(path, newName) {
+    renameFolder(path, newName) {
+        return this.#enqueueOperation(() => this.#renameFolder(path, newName));
+    }
+    async #renameFolder(path, newName) {
         return this.#afterMutation(await this.#store.renameFolder(path, newName));
     }
-    async moveFolder(path, parent) {
+    moveFolder(path, parent) {
+        return this.#enqueueOperation(() => this.#moveFolder(path, parent));
+    }
+    async #moveFolder(path, parent) {
         return this.#afterMutation(await this.#store.moveFolder(path, parent));
     }
-    async deleteFolder(path) {
+    deleteFolder(path) {
+        return this.#enqueueOperation(() => this.#deleteFolder(path));
+    }
+    async #deleteFolder(path) {
         const result = await this.#store.deleteFolder(path);
         return this.#afterMutation(result.library);
     }
@@ -175,7 +372,10 @@ export class FundusOperations {
      * rejected with nothing written. The REST `patchAsset` keeps the editor's
      * lenient replace semantics.
      */
-    async setAsset(id, changes) {
+    setAsset(id, changes) {
+        return this.#enqueueOperation(() => this.#setAsset(id, changes));
+    }
+    async #setAsset(id, changes) {
         const library = await this.#store.read();
         this.#requireAsset(library, id);
         return this.#afterMutation(await this.#applyAssetChanges(library, id, changes));
@@ -185,7 +385,10 @@ export class FundusOperations {
      * a referrer keeps pointing at the old id, so renaming a referenced asset
      * introduces dangling-reference errors. Update the referrers first.
      */
-    async renameAsset(id, newId) {
+    renameAsset(id, newId) {
+        return this.#enqueueOperation(() => this.#renameAsset(id, newId));
+    }
+    async #renameAsset(id, newId) {
         const library = await this.#store.read();
         this.#requireAsset(library, id);
         // A collision or invalid new id is the store's own (clearer) error; the
@@ -204,7 +407,10 @@ export class FundusOperations {
      * (the asset is a reference target) is rejected before anything —
      * including the raw file — is removed; the REST route stays lenient.
      */
-    async deleteAsset(id, options) {
+    deleteAsset(id, options) {
+        return this.#enqueueOperation(() => this.#deleteAsset(id, options));
+    }
+    async #deleteAsset(id, options) {
         if (options?.failOnIntroducedIssues) {
             const library = await this.#store.read();
             this.#requireAsset(library, id);
@@ -215,20 +421,32 @@ export class FundusOperations {
         return this.#afterMutation(await this.#store.deleteAsset(id));
     }
     /** Delete a selected asset set as one lenient editor mutation. */
-    async deleteAssets(assetIds) {
+    deleteAssets(assetIds) {
+        return this.#enqueueOperation(() => this.#deleteAssets(assetIds));
+    }
+    async #deleteAssets(assetIds) {
         const uniqueIds = [...new Set(assetIds)];
         if (uniqueIds.length === 0)
             throw new Error('At least one asset id is required.');
         return this.#afterMutation(await this.#store.deleteAssets(uniqueIds));
     }
-    async createManifest(name) {
+    createManifest(name) {
+        return this.#enqueueOperation(() => this.#createManifest(name));
+    }
+    async #createManifest(name) {
         return this.#afterMutation(await this.#store.createManifest(name));
     }
-    async setManifestAppearance(name, appearance) {
+    setManifestAppearance(name, appearance) {
+        return this.#enqueueOperation(() => this.#setManifestAppearance(name, appearance));
+    }
+    async #setManifestAppearance(name, appearance) {
         return this.#afterMutation(await this.#store.setManifestAppearance(name, appearance));
     }
     /** Apply a PATCH body: appearance fields and/or a rename — in that order. */
-    async patchManifest(name, body) {
+    patchManifest(name, body) {
+        return this.#enqueueOperation(() => this.#patchManifest(name, body));
+    }
+    async #patchManifest(name, body) {
         let library = await this.#store.setManifestAppearance(name, {
             color: body.color,
             emoji: body.emoji
@@ -247,17 +465,33 @@ export class FundusOperations {
      * the module must be updated by hand — both the file name and the exported
      * const change with the manifest name.
      */
-    async renameManifest(name, newName) {
+    renameManifest(name, newName) {
+        return this.#enqueueOperation(() => this.#renameManifest(name, newName));
+    }
+    async #renameManifest(name, newName) {
         return this.#afterMutation(await this.#store.renameManifest(name, newName));
     }
-    async deleteManifest(name) {
+    deleteManifest(name) {
+        return this.#enqueueOperation(() => this.#deleteManifest(name));
+    }
+    async #deleteManifest(name) {
         return this.#afterMutation(await this.#store.deleteManifest(name));
     }
     /** The autosave chain tail: process + regenerate, then report fresh state. */
     async #afterMutation(library) {
+        return (await this.#afterMutationSnapshot(library)).state;
+    }
+    async #afterMutationSnapshot(library) {
+        const run = this.#pipelineQueue.then(() => this.#runAfterMutation(library), () => this.#runAfterMutation(library));
+        this.#pipelineQueue = run.then(() => { }, () => { });
+        return run;
+    }
+    async #runAfterMutation(library) {
         const pipelineIssues = [];
-        const issues = await this.#store.validate(library);
-        if (issues.length === 0) {
+        const classification = await this.#classifyRawDirectory(library);
+        const ordinaryIssues = await this.#store.validate(library);
+        const safetyIssues = this.#rawSafetyIssues(library, classification);
+        if (ordinaryIssues.length === 0 && safetyIssues.length === 0) {
             try {
                 const report = await processAssets(this.#config, library, this.#registry);
                 await generateManifestModules(this.#config, library, report.proxies, this.#registry);
@@ -268,13 +502,15 @@ export class FundusOperations {
                 });
             }
         }
-        return this.#buildState(library, pipelineIssues, issues);
+        const latestLibrary = await this.#store.read();
+        const latestClassification = await this.#classifyRawDirectory(latestLibrary);
+        return {
+            library: latestLibrary,
+            classification: latestClassification,
+            state: await this.#snapshotState(latestLibrary, latestClassification, pipelineIssues)
+        };
     }
-    async #buildState(library, extraIssues, precomputedIssues) {
-        const issues = [
-            ...(precomputedIssues ?? (await this.#store.validate(library))),
-            ...extraIssues
-        ];
+    async #buildState(library, issues, classification) {
         const referencesByAsset = collectAllReferences(library, descriptorsByType(this.#registry));
         const membershipByManifest = computeLibraryMembership(library, referencesByAsset);
         const delivered = allDeliveredAssetIds(membershipByManifest);
@@ -334,7 +570,7 @@ export class FundusOperations {
                 type: record.type,
                 raw: record.raw,
                 folder: folderOfRawPath(record.raw),
-                rawUrl: `/files/raw/${encodeRelativePathForUrl(record.raw)}`,
+                rawUrl: `/files/raw/${encodeRelativePathForUrl(record.raw)}?v=${record.rawHash.slice(0, 12)}`,
                 rawHash: record.rawHash,
                 parameters: record.parameters,
                 manifests: record.manifests,
@@ -374,15 +610,139 @@ export class FundusOperations {
         for (const [type, plugin] of Object.entries(this.#registry)) {
             presetNames[type] = Object.keys(plugin.presets(this.#config)).sort();
         }
+        const rawIngestionQueue = this.#buildRawIngestionQueue(library, classification);
         return {
             library,
             assets,
             issues,
             presetNames,
             manifestMemberships,
-            manifestDeliveredBytes
+            manifestDeliveredBytes,
+            rawIngestionQueue
         };
     }
+    #compatibleTypes(path) {
+        return typesForFileName(path, Object.values(this.#registry).map((plugin) => plugin.descriptor)).sort(compareCodeUnits);
+    }
+    #classifyRawDirectory(library) {
+        return classifyRawDirectory(this.#config.rawDir, library, (path) => this.#compatibleTypes(path).length > 0);
+    }
+    #rawSafetyIssues(library, classification) {
+        return rawSafetyIssues(library, classification, (path) => this.#compatibleTypes(path));
+    }
+    async #snapshotState(library, classification, extraIssues = []) {
+        const issues = [
+            ...(await this.#store.validate(library)),
+            ...this.#rawSafetyIssues(library, classification),
+            ...extraIssues
+        ];
+        const seen = new Set();
+        const uniqueIssues = issues.filter((issue) => {
+            const key = `${issue.assetId ?? ''}|${issue.message}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        return this.#buildState(library, uniqueIssues, classification);
+    }
+    #canAutoReconcile(classification, retry = false) {
+        return (classification.complete &&
+            classification.blockers.length === 0 &&
+            classification.moves.length + classification.deletions.length > 0 &&
+            (!retry || (classification.edited.length === 0 && classification.unmanaged.length === 0)));
+    }
+    #newToken(path, hash) {
+        return `new:${path}:${hash}`;
+    }
+    #editedToken(assetId, path, hash) {
+        return `edited:${assetId}:${path}:${hash}`;
+    }
+    #proposedId(path, reservedIds) {
+        const base = proposeAssetId(rawFileNameOfPath(path));
+        if (!reservedIds.has(base))
+            return base;
+        for (let index = 2;; index++) {
+            const candidate = `${base}${index}`;
+            if (!reservedIds.has(candidate))
+                return candidate;
+        }
+    }
+    #buildRawIngestionQueue(library, classification) {
+        const queue = [];
+        const reservedIds = new Set(Object.keys(library.assets));
+        for (const file of classification.unmanaged) {
+            const compatibleTypes = this.#compatibleTypes(file.path);
+            const proposedId = this.#proposedId(file.path, reservedIds);
+            reservedIds.add(proposedId);
+            queue.push({
+                kind: 'new',
+                token: this.#newToken(file.path, file.hash),
+                path: file.path,
+                hash: file.hash,
+                compatibleTypes,
+                proposedId
+            });
+        }
+        for (const edited of this.#editedRawFiles(classification, library)) {
+            const currentType = library.assets[edited.assetId].type;
+            queue.push({
+                kind: 'edited',
+                token: this.#editedToken(edited.assetId, edited.path, edited.hash),
+                path: edited.path,
+                hash: edited.hash,
+                assetId: edited.assetId,
+                currentType,
+                compatibleTypes: this.#compatibleTypes(edited.path)
+            });
+        }
+        for (const blocker of classification.blockers) {
+            queue.push({
+                kind: 'unsupported',
+                token: `unsupported:${blocker.path}:${blocker.reason}`,
+                path: blocker.path,
+                reason: blocker.reason
+            });
+        }
+        for (const diagnostic of classification.diagnostics) {
+            queue.push({
+                kind: 'unsupported',
+                token: `unsupported:raw-directory:${diagnostic.reason}`,
+                path: diagnostic.path || 'Raw directory',
+                reason: diagnostic.reason
+            });
+        }
+        return queue.sort((a, b) => compareCodeUnits(a.path, b.path));
+    }
+    #editedRawFiles(classification, library) {
+        const edited = new Map(classification.edited.map((entry) => [entry.assetId, entry]));
+        for (const assetId of classification.unchangedAssetIds) {
+            const record = library.assets[assetId];
+            if (!this.#compatibleTypes(record.raw).includes(record.type)) {
+                edited.set(assetId, { assetId, path: record.raw, hash: record.rawHash });
+            }
+        }
+        return [...edited.values()].sort((a, b) => compareCodeUnits(a.path, b.path));
+    }
+    #registerFolderAncestors(library, folder) {
+        if (folder === '')
+            return;
+        const missing = [];
+        for (let current = folder; current !== ''; current = parentFolderPath(current)) {
+            if (!library.folders.includes(current))
+                missing.push(current);
+        }
+        const keys = new Map(library.folders.map((path) => [portableFolderPathKey(path), path]));
+        for (const path of missing.reverse()) {
+            const collision = keys.get(portableFolderPathKey(path));
+            if (collision !== undefined && collision !== path) {
+                throw new Error(`Folder "${path}" collides with existing folder "${collision}".`);
+            }
+            library.folders.push(path);
+            keys.set(portableFolderPathKey(path), path);
+        }
+        library.folders.sort(compareCodeUnits);
+    }
     #requireAsset(library, id) {
         // Own-property check — an inherited key ("constructor", "toString", …)
         // must not pass as an existing asset.

package/dist/server/processing/processor.js

@@ -20,6 +20,7 @@ import { allDeliveredAssetIds, collectAllReferences, computeLibraryMembership, f
 import { jobHash } from '../job-hash.js';
 import { descriptorsByType, processingParametersOf, serverPluginForType, serverPluginsByType } from '../plugins.js';
 import { ensureManagedFolder, listRelativeFiles } from '../folder-filesystem.js';
+import { verifyStableRawFile } from '../raw-reconciliation.js';
 /** Proxy file name shape; its id segment is pinned to core's asset-id grammar. */
 const PROXY_FILE_PATTERN = /^[a-z][A-Za-z0-9]*\.[0-9a-f]{8}\.[a-z0-9]+$/;
 /** Whether a file name in the proxy directory is (shaped like) a fundus proxy. */
@@ -93,6 +94,7 @@ async function processAssetFile(record, rawPath, proxyPath, config, registry) {
     const stem = basename(proxyPath, extension);
     const temporaryPath = join(dirname(proxyPath), `.${stem}.${crypto.randomUUID()}.tmp${extension}`);
     try {
+        await verifyStableRawFile(rawPath, record.rawHash);
         const output = await plugin.process({
             sourcePath: rawPath,
             targetPath: temporaryPath,
@@ -100,6 +102,7 @@ async function processAssetFile(record, rawPath, proxyPath, config, registry) {
             preset: plugin.resolvePreset(parameters, config),
             config
         });
+        await verifyStableRawFile(rawPath, record.rawHash);
         await rename(temporaryPath, proxyPath);
         return output;
     }

package/dist/server/raw-reconciliation.d.ts

@@ -0,0 +1,53 @@
+import { type Library } from '../core/index.js';
+export interface ScannedRawFile {
+    path: string;
+    hash: string;
+}
+export type RawEntryKind = 'file' | 'directory' | 'symlink' | 'special';
+export interface RawDiagnostic {
+    /** Empty only for a root-level diagnostic. */
+    path: string;
+    reason: string;
+}
+export interface RawBlocker extends RawDiagnostic {
+    assetId?: string;
+}
+export interface RawScan {
+    complete: boolean;
+    diagnostics: RawDiagnostic[];
+    files: ScannedRawFile[];
+    blockers: RawBlocker[];
+    /** Every retained entry, including traversal directories and blockers. */
+    occupiedPaths: Set<string>;
+    entryKinds: Map<string, RawEntryKind>;
+    /** Unsupported regular files, retained unhashed only for deletion-safety checks. */
+    ignoredRegularPaths: string[];
+}
+export interface EditedRawFile extends ScannedRawFile {
+    assetId: string;
+}
+export interface RawMove extends ScannedRawFile {
+    assetId: string;
+    from: string;
+}
+export interface RawClassification {
+    complete: boolean;
+    diagnostics: RawDiagnostic[];
+    unchangedAssetIds: string[];
+    edited: EditedRawFile[];
+    moves: RawMove[];
+    deletions: Array<{
+        assetId: string;
+        path: string;
+    }>;
+    unmanaged: ScannedRawFile[];
+    blockers: RawBlocker[];
+}
+/** Hash one regular file without following its final path component. */
+export declare function stableRawFileHash(path: string): Promise<string>;
+export declare function verifyStableRawFile(path: string, expectedHash: string): Promise<void>;
+/** Enumerate without following symlinks and retain structural scan completeness. */
+export declare function scanRawDirectory(rawDir: string, includeFile?: (path: string) => boolean): Promise<RawScan>;
+/** Pure deterministic matching: exact path first, then only 1:1 hash groups. */
+export declare function classifyRawFiles(library: Library, scan: RawScan): RawClassification;
+export declare function classifyRawDirectory(rawDir: string, library: Library, includeExternalFile?: (path: string) => boolean): Promise<RawClassification>;