openworkgraph 0.2.12

package/dist/resource-api.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage } from 'node:http';
+import { Auth } from './auth.js';
+import { Resources } from './resources.js';
+import { Graphs } from './graphs.js';
+import type { ApiResult } from './api.js';
+export declare class ResourceApi {
+    readonly resources: Resources;
+    readonly graphs: Graphs;
+    readonly auth: Auth;
+    constructor(resources: Resources, graphs: Graphs, auth: Auth);
+    private wire;
+    handle(request: IncomingMessage, path: string, token: string, origin: string): Promise<ApiResult>;
+    private content;
+    private binary;
+}

package/dist/resource-api.js

@@ -0,0 +1,256 @@
+import { Auth } from './auth.js';
+import { Resources } from './resources.js';
+import { Graphs, assertProjectWritable } from './graphs.js';
+import { readJson } from './http.js';
+import { ServiceError } from './errors.js';
+import { Repositories } from './persistence/repositories.js';
+import { transaction } from './persistence/database.js';
+const invalid = (message) => { throw new ServiceError('INVALID_REQUEST', message); };
+const notFound = () => { throw new ServiceError('NOT_FOUND', '资源接口不存在。'); };
+function string(value, max = 512) { if (typeof value !== 'string' || !value.trim() || value.length > max || [...value].some(c => c.charCodeAt(0) < 32))
+    return invalid('需要有效且长度受限的字符串。'); return value; }
+function id(value) { const result = string(value, 128); if (!/^[a-zA-Z0-9_-]+$/.test(result))
+    invalid('无效的标识符。'); return result; }
+function integer(value, min = 0, max = Number.MAX_SAFE_INTEGER) { if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max)
+    return invalid('整数超出允许范围。'); return value; }
+function version(value) { if (!/^[1-9][0-9]*$/.test(value))
+    invalid('版本须为规范正整数。'); return integer(Number(value), 1); }
+function fields(body, required, optional = []) {
+    if (!body || required.some(key => !Object.hasOwn(body, key)) || Object.keys(body).some(key => !required.includes(key) && !optional.includes(key)))
+        return invalid('请求字段缺失或包含未知字段。');
+    return body;
+}
+export class ResourceApi {
+    resources;
+    graphs;
+    auth;
+    constructor(resources, graphs, auth) {
+        this.resources = resources;
+        this.graphs = graphs;
+        this.auth = auth;
+    }
+    wire(value) {
+        if (Array.isArray(value))
+            return value.map(item => this.wire(item));
+        if (value && typeof value === 'object') {
+            const result = {};
+            for (const [key, item] of Object.entries(value)) {
+                if (item !== undefined)
+                    result[key] = this.wire(item);
+            }
+            if (typeof result['projectId'] === 'string')
+                result['serviceId'] = this.graphs.serviceId;
+            return result;
+        }
+        return value;
+    }
+    async handle(request, path, token, origin) {
+        const parts = path.split('/');
+        if (parts[0] !== '' || parts[1] !== 'v1' || parts[2] !== 'projects' || !['uploads', 'assets', 'graphs'].includes(parts[4] ?? ''))
+            return { handled: false };
+        const section = parts[4];
+        if (section === 'graphs' && parts[6] !== 'resources')
+            return { handled: false };
+        // Do not collapse empty segments, decode aliases, or ignore trailing segments.
+        const projectId = id(parts[3]);
+        const tail = parts.slice(5);
+        for (const segment of tail)
+            id(segment);
+        const scope = { serviceId: this.graphs.serviceId, projectId };
+        const session = this.auth.withSession(token, origin, s => s);
+        const method = request.method;
+        if (method !== 'GET' && method !== 'POST')
+            return notFound();
+        const body = method === 'POST' ? await readJson(request, 6 * 1024 * 1024) : undefined;
+        const read = (work) => this.auth.withSession(token, origin, work);
+        const reply = (value) => ({ handled: true, body: this.wire(value) });
+        const repo = new Repositories(this.resources.db);
+        const cleanups = [];
+        const prepare = async (promise) => { const blob = await promise; cleanups.push(() => this.resources.discardPrepared(blob)); return blob; };
+        const mutation = async (required, optional, work) => {
+            const input = fields(body, [...required, 'idempotencyKey'], optional), key = string(input['idempotencyKey'], 256), namespace = session.id + ':' + path;
+            const replay = () => read(() => { assertProjectWritable(this.resources.db, projectId); return repo.replay(namespace, key, input); });
+            const prior = replay();
+            if (prior !== undefined) {
+                await this.resources.drainFileDeletions();
+                this.auth.assertActive(token, origin);
+                return reply(prior);
+            }
+            try {
+                const commit = await work(input);
+                const result = read(() => repo.idempotent(namespace, key, input, () => { assertProjectWritable(this.resources.db, projectId); const value = commit(); this.resources.collectGarbage(); return this.wire(value); }));
+                return reply(result);
+            }
+            catch (error) {
+                const duplicate = replay();
+                if (duplicate !== undefined)
+                    return reply(duplicate);
+                throw error;
+            }
+            finally {
+                // Capability-only cleanup still works after revocation or deactivation.
+                if (cleanups.length)
+                    transaction(this.resources.db, () => { for (const cleanup of cleanups)
+                        cleanup(); });
+                await this.resources.drainFileDeletions();
+                this.auth.assertActive(token, origin);
+            }
+        };
+        if (section === 'uploads') {
+            const [uploadId, action] = tail;
+            if (method === 'GET' && tail.length === 1)
+                return reply(read(() => this.resources.uploadStatus(scope, uploadId)));
+            if (method === 'POST' && tail.length === 0)
+                return mutation(['name', 'mime', 'bytes'], ['sha256'], b => {
+                    const name = string(b['name']), mime = string(b['mime'], 128), bytes = integer(b['bytes']);
+                    const sha256 = b['sha256'] === undefined ? undefined : string(b['sha256'], 64);
+                    return () => this.resources.startUpload({ ...scope, name, mime, bytes, ...(sha256 === undefined ? {} : { sha256 }) });
+                });
+            if (method === 'POST' && tail.length === 2 && action === 'chunks')
+                return mutation(['data', 'offset'], [], async (b) => {
+                    const encoded = string(b['data'], Math.ceil(4 * 1024 * 1024 / 3) * 4), offset = integer(b['offset']);
+                    const bytes = Buffer.from(encoded, 'base64');
+                    if (!bytes.length || bytes.toString('base64') !== encoded)
+                        invalid('分块须为规范 Base64。');
+                    const prepared = await this.resources.prepareAppend(scope, uploadId, offset, bytes);
+                    cleanups.push(() => this.resources.discardAppend(scope, prepared));
+                    return () => this.resources.commitAppend(scope, prepared);
+                });
+            if (method === 'POST' && tail.length === 2 && action === 'finish') {
+                const mode = body?.['mode'];
+                if (mode !== 'new' && mode !== 'update' && mode !== 'canvas')
+                    invalid('无效的上传入口。');
+                const required = mode === 'canvas' ? ['mode', 'name', 'graphId'] : mode === 'update' ? ['mode', 'name', 'assetId', 'expectedVersion'] : ['mode', 'name'];
+                return mutation(required, [], async (b) => {
+                    const name = string(b['name']);
+                    const target = mode === 'canvas' ? { ...scope, mode: 'canvas', graphId: id(b['graphId']), name } : mode === 'update' ? { ...scope, mode: 'update', name, assetId: id(b['assetId']), expectedVersion: integer(b['expectedVersion'], 1) } : { ...scope, mode: 'new', name };
+                    if (target.mode === 'canvas')
+                        read(() => this.graphs.writable({ ...target, serviceId: this.graphs.serviceId }));
+                    const prepared = await this.resources.prepareFinish(scope, uploadId);
+                    cleanups.push(() => this.resources.discardPrepared(prepared.blob));
+                    return () => this.resources.commitFinish(scope, prepared, target);
+                });
+            }
+            if (method === 'POST' && tail.length === 2 && action === 'cancel')
+                return mutation([], [], () => () => { this.resources.cancelUpload(scope, uploadId); return { cancelled: true }; });
+        }
+        if (section === 'assets') {
+            const [assetId, action] = tail;
+            if (method === 'POST' && tail.length === 1 && assetId === 'empty-trash')
+                return mutation([], [], () => () => this.resources.emptyTrash(scope));
+            if (method === 'GET' && tail.length === 0)
+                return reply(read(() => this.resources.listAssets(scope)));
+            if (method === 'POST' && tail.length === 1 && assetId === 'query') {
+                const b = fields(body, [], ['name', 'search', 'deleted', 'scope', 'limit', 'offset']);
+                if (b['name'] !== undefined)
+                    string(b['name']);
+                if (b['search'] !== undefined)
+                    string(b['search']);
+                if (b['deleted'] !== undefined && typeof b['deleted'] !== 'boolean')
+                    invalid('deleted 须为布尔值。');
+                if (b['scope'] !== undefined && (typeof b['scope'] !== 'string' || !['project', 'shared', 'available'].includes(b['scope'])))
+                    invalid('无效的查询范围。');
+                if (b['limit'] !== undefined)
+                    integer(b['limit'], 1, 1000);
+                if (b['offset'] !== undefined)
+                    integer(b['offset']);
+                return reply(read(() => this.resources.listAssets(scope, b)));
+            }
+            if (method === 'POST' && tail.length === 1 && assetId === 'same-name') {
+                const b = fields(body, ['name']);
+                const name = string(b['name']);
+                return reply(read(() => this.resources.listSameNameAssets(scope, name)));
+            }
+            if (method === 'GET' && tail.length === 1)
+                return reply(read(() => this.resources.getAsset(scope, assetId)));
+            if (method === 'POST' && tail.length === 2 && action === 'delete')
+                return mutation([], [], () => () => this.resources.softDelete(scope, assetId));
+            if (method === 'POST' && tail.length === 2 && action === 'restore')
+                return mutation([], [], () => () => this.resources.restore(scope, assetId));
+            if (method === 'POST' && tail.length === 2 && action === 'share')
+                return mutation(['shared'], [], b => { const shared = b['shared']; if (typeof shared !== 'boolean')
+                    return invalid('shared 须为布尔值。'); return () => this.resources.setShared(scope, assetId, shared); });
+            if (method === 'POST' && tail.length === 2 && action === 'copy-to-project')
+                return mutation(['targetProjectId', 'expectedVersion'], ['name'], b => {
+                    const targetProjectId = id(b['targetProjectId']), expectedVersion = integer(b['expectedVersion'], 1), name = b['name'] === undefined ? undefined : string(b['name']);
+                    return () => { this.resources.getAsset(scope, assetId); return this.resources.copyAssetToProject({ ...scope, projectId: targetProjectId }, assetId, expectedVersion, name); };
+                });
+            if (method === 'POST' && tail.length === 1 && assetId === 'import-file')
+                return mutation(['path', 'mime', 'name'], [], async (b) => {
+                    const path = string(b['path'], 4096), mime = string(b['mime'], 128), name = string(b['name']);
+                    const blob = await prepare(this.resources.prepareProjectFile(scope, path, mime));
+                    return () => this.resources.createLibraryFromPrepared({ ...scope, mode: 'new', name }, blob);
+                });
+            if (method === 'GET' && (tail.length === 3 || tail.length === 4) && action === 'versions')
+                return this.content(request, scope, 'asset', assetId, version(tail[2]), tail[3], read);
+        }
+        if (section === 'graphs') {
+            const graphId = tail[0], action = tail[2], graphScope = { ...scope, graphId };
+            if (method === 'GET' && tail.length === 2)
+                return reply(read(() => this.resources.listCanvas(graphScope)));
+            if (method === 'POST' && tail.length === 3 && action === 'import-file')
+                return mutation(['path', 'mime', 'name'], ['sourceProjectId'], async (b) => {
+                    const path = string(b['path'], 4096), mime = string(b['mime'], 128), name = string(b['name']);
+                    const sourceProjectId = b['sourceProjectId'] === undefined ? scope.projectId : string(b['sourceProjectId'], 128);
+                    read(() => this.graphs.writable(graphScope));
+                    const blob = await prepare(this.resources.prepareProjectFile({ ...scope, projectId: sourceProjectId }, path, mime));
+                    return () => this.resources.createCanvasFromPrepared(graphScope, blob, name);
+                });
+            if (method === 'POST' && tail.length === 3 && action === 'copy-asset')
+                return mutation(['assetId', 'expectedVersion'], [], b => { const assetId = id(b['assetId']), expectedVersion = integer(b['expectedVersion'], 1); return () => this.resources.copyAssetToCanvas(graphScope, assetId, expectedVersion); });
+            if (method === 'POST' && tail.length === 3 && action === 'copy-resource')
+                return mutation(['sourceGraphId', 'resourceId', 'version'], [], b => { const sourceGraphId = id(b['sourceGraphId']), resourceId = id(b['resourceId']), sourceVersion = integer(b['version'], 1); return () => this.resources.copyCanvasToCanvas(graphScope, sourceGraphId, resourceId, sourceVersion); });
+            if (method === 'POST' && tail.length === 3 && action === 'save-to-library')
+                return mutation(['resourceId', 'expectedVersion', 'name'], [], b => { const resourceId = id(b['resourceId']), expectedVersion = integer(b['expectedVersion'], 1), name = string(b['name']); return () => this.resources.saveCanvasToLibrary(graphScope, resourceId, expectedVersion, name); });
+            if (method === 'POST' && tail.length === 3 && action === 'release')
+                return mutation(['referenceId'], [], b => { const referenceId = id(b['referenceId']); return () => { this.resources.releaseGraphReference(graphScope, referenceId); return { released: true }; }; });
+            if (method === 'GET' && (tail.length === 5 || tail.length === 6) && tail[3] === 'versions')
+                return this.content(request, graphScope, 'canvas', action, version(tail[4]), tail[5], read);
+        }
+        return notFound();
+    }
+    async content(request, scope, kind, id, version, action, read) {
+        const identity = { ...scope, serviceId: this.graphs.serviceId, ...(kind === 'asset' ? { assetId: id } : { resourceId: id }) };
+        if (action === undefined)
+            return { handled: true, body: read(() => ({ ...identity, ...(kind === 'asset' ? this.resources.readAssetVersion(scope, id, version) : this.resources.readCanvasVersion(scope, id, version)) })) };
+        if (action === 'representation') {
+            const result = await this.resources.representation(scope, kind, id, version);
+            return { handled: true, body: read(() => ({ ...identity, ...result })) };
+        }
+        if (action === 'thumbnail') {
+            if (request.headers.range)
+                invalid('缩略图不接受 Range。');
+            const requestedSize = request.url ? new URL(request.url, 'http://localhost').searchParams.get('size') : null;
+            const size = requestedSize === null ? 320 : integer(Number(requestedSize));
+            if (![80, 160, 320, 640, 1280, 2560, 4096].includes(size))
+                invalid('无效的缩略图尺寸。');
+            const result = await this.resources.thumbnail(scope, kind, id, version, size);
+            return read(() => { const response = this.binary(result, false, result.cacheable !== false); if (result.cacheable === false)
+                response.headers = { ...response.headers, 'Cache-Control': 'no-cache' }; return response; });
+        }
+        if (action === 'preview') {
+            if (request.headers.range)
+                invalid('预览表示不接受 Range；媒体范围读取请使用 content。');
+            const result = await this.resources.preview(scope, kind, id, version);
+            if (!('content' in result))
+                return { handled: true, body: read(() => ({ ...identity, ...result })) };
+            return read(() => this.binary(result.content, false));
+        }
+        if (action !== 'content')
+            return notFound();
+        let range;
+        if (request.headers.range) {
+            const match = /^bytes=([0-9]+)-([0-9]*)$/.exec(request.headers.range);
+            if (!match)
+                return invalid('仅支持单个明确起点的字节范围。');
+            range = { start: integer(Number(match[1])), ...(match[2] ? { end: integer(Number(match[2])) } : {}) };
+        }
+        const result = await this.resources.readContent(scope, kind, id, version, range);
+        return read(() => this.binary(result, range !== undefined, !range && (result.mime.startsWith('image/') || result.mime.startsWith('video/'))));
+    }
+    binary(content, ranged, cacheable = false) {
+        const svg = content.mime === 'image/svg+xml';
+        return { handled: true, binary: content.bytes, status: ranged ? 206 : 200, headers: { 'Content-Type': content.mime, 'Content-Length': String(content.bytes.length), 'Accept-Ranges': 'bytes', 'X-Content-Type-Options': 'nosniff', ...(cacheable ? { 'Cache-Control': 'private, max-age=31536000, immutable' } : {}), 'Content-Disposition': !svg && (content.mime.startsWith('image/') || content.mime.startsWith('video/')) ? 'inline' : 'attachment', ...(svg ? { 'Content-Security-Policy': "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data: blob:;" } : {}), ...(ranged ? { 'Content-Range': 'bytes ' + content.start + '-' + content.end + '/' + content.total } : {}) } };
+    }
+}
+//# sourceMappingURL=resource-api.js.map

package/dist/resources-orphans.d.ts

@@ -0,0 +1,41 @@
+/** Deliberately offline, opt-in only. A crash before SQL registration is NOT
+ * covered by ordinary discardPrepared. This policy scans only current immutable
+ * generation files (blobs/{objects,chunks}/UUID), never legacy staging, backups,
+ * runs, unknown directories or unknown names. Default grace is 24 hours.
+ * Any recorded path/hash, hardlink or unfinished backup is retained/fails closed.
+ * Preview tokens are local to one uninterrupted exclusive maintenance session.
+ * No schema migration, reference deletion or automatic startup sweep occurs. */
+export interface OrphanOptions {
+    minAgeMs?: number;
+    maxEntries?: number;
+    maxFileBytes?: number;
+    now?: () => number;
+}
+export interface OrphanCandidate {
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+export interface OrphanPreview {
+    readonly id: string;
+    readonly root: string;
+    readonly candidates: readonly OrphanCandidate[];
+    readonly retained: readonly {
+        path: string;
+        reason: string;
+    }[];
+}
+export interface OrphanCleanup {
+    removed: string[];
+    retained: string[];
+    failed: string[];
+}
+export interface OrphanMaintenance {
+    preview(): Promise<OrphanPreview>;
+    cleanup(preview: OrphanPreview): Promise<OrphanCleanup>;
+}
+/** Existing data only. Acquires the same kernel lock as serve BEFORE opening DB;
+ * never accepts caller-forged held flags, never migrates, never publishes a server.
+ * Escaped controller handles reject after this callback and in-flight calls drain
+ * before the DB/lock are closed. Cleanup must be explicitly requested in callback. */
+export declare function withOfflineResourceOrphans<T>(dataDir: string, work: (maintenance: OrphanMaintenance) => Promise<T>, options?: OrphanOptions): Promise<T>;

package/dist/resources-orphans.js

@@ -0,0 +1,235 @@
+import { DatabaseSync } from 'node:sqlite';
+import { constants } from 'node:fs';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { join, resolve, sep } from 'node:path';
+import { BlobStore } from './blob-store.js';
+import { ServiceError } from './errors.js';
+import { transaction } from './persistence/database.js';
+import { SCHEMA_VERSION } from './persistence/schema.js';
+import { acquireOperationsLock, rootPath } from './operations/lifecycle.js';
+import { safePath } from './operations/files.js';
+const fail = (message) => { throw new ServiceError('MAINTENANCE', message); };
+const generation = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+function stamp(stat) { return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs, stat.nlink].join(':'); }
+function option(value, min) { if (!Number.isSafeInteger(value) || value < min)
+    throw new ServiceError('INVALID_REQUEST', 'Invalid orphan scan bound'); return value; }
+class Maintenance {
+    db;
+    lock;
+    tokens = new WeakMap();
+    chain = Promise.resolve();
+    closing = false;
+    minAge;
+    maxEntries;
+    maxBytes;
+    now;
+    store;
+    constructor(db, lock, options) {
+        this.db = db;
+        this.lock = lock;
+        this.minAge = option(options.minAgeMs ?? 86400000, 0);
+        this.maxEntries = option(options.maxEntries ?? 10000, 1);
+        this.maxBytes = option(options.maxFileBytes ?? 512 * 1024 * 1024, 1);
+        this.now = options.now ?? Date.now;
+        this.store = new BlobStore(join(lock.root, 'blobs'));
+    }
+    assertOwned() {
+        if (!this.lock.held || this.lock.record.serviceId || this.db.prepare('PRAGMA database_list').all().find(row => row['name'] === 'main')?.['file'] !== join(this.lock.root, 'service.sqlite'))
+            fail('Matching unpublished exclusive maintenance ownership required');
+        if (this.db.isTransaction)
+            fail('Orphan filesystem operations cannot run in a transaction');
+    }
+    run(work) {
+        if (this.closing)
+            return Promise.reject(new ServiceError('MAINTENANCE', 'Maintenance session is closed'));
+        const pending = this.chain.then(() => { this.assertOwned(); return work(); });
+        this.chain = pending.catch(() => { });
+        return pending;
+    }
+    async close() { this.closing = true; await this.chain; }
+    references() {
+        if (this.db.prepare('SELECT 1 FROM resource_maintenance_leases LIMIT 1').get() || this.db.prepare("SELECT 1 FROM backups WHERE state='creating' LIMIT 1").get())
+            fail('Unresolved maintenance/backup record; preserve it and recover separately before orphan cleanup');
+        const result = { paths: new Set(), hashes: new Set() };
+        for (const row of this.db.prepare('SELECT path FROM resource_blob_files UNION SELECT path FROM resource_upload_chunks UNION SELECT path FROM resource_file_deletions UNION SELECT path FROM backups WHERE path IS NOT NULL').all())
+            result.paths.add(resolve(this.lock.root, String(row['path'])));
+        for (const row of this.db.prepare("SELECT sha256 FROM blobs UNION SELECT sha256 FROM resource_upload_chunks UNION SELECT sha256 FROM resource_uploads WHERE sha256 IS NOT NULL UNION SELECT expected_sha256 AS sha256 FROM resource_uploads WHERE expected_sha256 IS NOT NULL UNION SELECT sha256 FROM resource_read_leases UNION SELECT sha256 FROM backups WHERE sha256 IS NOT NULL UNION SELECT j.value AS sha256 FROM snapshots s,json_tree(s.payload) j WHERE j.type='text' AND length(j.value)=64").all())
+            result.hashes.add(String(row['sha256']));
+        return result;
+    }
+    protected(path, hash, refs) { return [...refs.paths].some(owned => path === owned || path.startsWith(owned + sep)) || (hash !== undefined && refs.hashes.has(hash)); }
+    async inspect(path) {
+        await safePath(path);
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const before = await file.stat();
+            if (!before.isFile() || before.nlink !== 1 || before.size > this.maxBytes)
+                fail('Generation file changed or is not a bounded single-link file');
+            const hash = createHash('sha256');
+            let bytes = 0;
+            const buffer = Buffer.alloc(64 * 1024);
+            while (true) {
+                const read = await file.read(buffer, 0, buffer.length, null);
+                if (!read.bytesRead)
+                    break;
+                bytes += read.bytesRead;
+                if (bytes > this.maxBytes)
+                    fail('Generation file grew beyond scan bound');
+                hash.update(buffer.subarray(0, read.bytesRead));
+            }
+            const after = await file.stat();
+            if (stamp(before) !== stamp(after) || bytes !== before.size)
+                fail('Generation file changed during preview');
+            return { path, bytes, sha256: hash.digest('hex'), stamp: stamp(after) };
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async scan() {
+        this.assertOwned();
+        const refs = this.references();
+        const result = { candidates: [], retained: [] };
+        let entries = 0;
+        const cutoff = this.now() - this.minAge;
+        for (const kind of ['objects', 'chunks']) {
+            const directory = join(this.lock.root, 'blobs', kind);
+            try {
+                await safePath(directory);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                if (++entries > this.maxEntries)
+                    throw new ServiceError('PAYLOAD_TOO_LARGE', 'Orphan scan entry bound exceeded; no cleanup performed');
+                const path = join(directory, entry.name);
+                await safePath(path);
+                const stat = await lstat(path);
+                let reason;
+                if (!stat.isFile() || !generation.test(entry.name))
+                    reason = 'unknown-layout';
+                else if (stat.nlink !== 1)
+                    reason = 'hardlink';
+                else if (this.protected(path, undefined, refs))
+                    reason = 'recorded-path';
+                else if (Math.max(stat.mtimeMs, stat.ctimeMs) > cutoff)
+                    reason = 'grace-period';
+                else if (stat.size > this.maxBytes)
+                    reason = 'oversize';
+                if (reason) {
+                    result.retained.push({ path, reason });
+                    continue;
+                }
+                const candidate = await this.inspect(path);
+                if (this.protected(path, candidate.sha256, refs))
+                    result.retained.push({ path, reason: 'recorded-hash' });
+                else
+                    result.candidates.push(candidate);
+            }
+        }
+        this.assertOwned();
+        return result;
+    }
+    preview() {
+        return this.run(async () => {
+            const result = await this.scan();
+            const preview = Object.freeze({ id: randomUUID(), root: this.lock.root, candidates: Object.freeze(result.candidates.map(({ path, bytes, sha256 }) => Object.freeze({ path, bytes, sha256 }))), retained: Object.freeze(result.retained.map(row => Object.freeze(row))) });
+            this.tokens.set(preview, result.candidates);
+            return preview;
+        });
+    }
+    cleanup(preview) {
+        return this.run(async () => {
+            const approved = this.tokens.get(preview);
+            if (!approved)
+                throw new ServiceError('INVALID_REQUEST', 'Use an unchanged preview from this exclusive maintenance session');
+            // Full rescan rejects symlinks or backup blockers before queuing any deletion.
+            const current = new Map((await this.scan()).candidates.map(row => [row.path, row]));
+            const eligible = [];
+            const result = { removed: [], retained: [], failed: [] };
+            for (const old of approved) {
+                const latest = current.get(old.path);
+                if (!latest || latest.stamp !== old.stamp || latest.sha256 !== old.sha256)
+                    result.retained.push(old.path);
+                else
+                    eligible.push(latest);
+            }
+            this.assertOwned();
+            const claimed = transaction(this.db, () => {
+                const refs = this.references();
+                const rows = [];
+                for (const candidate of eligible) {
+                    if (this.protected(candidate.path, candidate.sha256, refs)) {
+                        result.retained.push(candidate.path);
+                        continue;
+                    }
+                    this.db.prepare('INSERT INTO resource_file_deletions(path,created_at,completed) VALUES(?,?,0)').run(candidate.path, this.now());
+                    rows.push(candidate);
+                }
+                return rows;
+            });
+            this.tokens.delete(preview);
+            for (const candidate of claimed) {
+                try {
+                    this.assertOwned();
+                    await safePath(candidate.path);
+                    const current = await lstat(candidate.path);
+                    if (stamp(current) !== candidate.stamp) {
+                        // Do not let a later online drain delete a replacement file either.
+                        transaction(this.db, () => this.db.prepare('UPDATE resource_file_deletions SET completed=1 WHERE path=?').run(candidate.path));
+                        result.retained.push(candidate.path);
+                        continue;
+                    }
+                    await this.store.remove(candidate.path);
+                    transaction(this.db, () => this.db.prepare('UPDATE resource_file_deletions SET completed=1 WHERE path=?').run(candidate.path));
+                    result.removed.push(candidate.path);
+                }
+                catch {
+                    result.failed.push(candidate.path);
+                }
+            }
+            return result;
+        });
+    }
+}
+/** Existing data only. Acquires the same kernel lock as serve BEFORE opening DB;
+ * never accepts caller-forged held flags, never migrates, never publishes a server.
+ * Escaped controller handles reject after this callback and in-flight calls drain
+ * before the DB/lock are closed. Cleanup must be explicitly requested in callback. */
+export async function withOfflineResourceOrphans(dataDir, work, options = {}) {
+    const root = await safePath(rootPath(dataDir));
+    if (!(await lstat(root)).isDirectory())
+        fail('Existing data directory required');
+    const lock = await acquireOperationsLock(root);
+    let db;
+    let maintenance;
+    try {
+        const path = await safePath(join(lock.root, 'service.sqlite'));
+        if (!(await lstat(path)).isFile())
+            fail('Existing regular database required');
+        db = new DatabaseSync(path, { allowExtension: false, timeout: 5000, enableForeignKeyConstraints: true });
+        if (db.prepare('PRAGMA user_version').get()?.['user_version'] !== SCHEMA_VERSION)
+            fail('Matching resource schema required; orphan maintenance never migrates');
+        if (db.prepare('PRAGMA quick_check').get()?.['quick_check'] !== 'ok' || db.prepare('PRAGMA foreign_key_check').get())
+            fail('Database integrity check failed');
+        for (const table of ['blobs', 'resource_blob_files', 'resource_uploads', 'resource_upload_chunks', 'resource_file_deletions', 'resource_read_leases', 'resource_maintenance_leases', 'backups', 'snapshots'])
+            if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                fail('Incomplete resource schema');
+        maintenance = new Maintenance(db, lock, options);
+        return await work(maintenance);
+    }
+    finally {
+        try {
+            await maintenance?.close();
+            db?.close();
+        }
+        finally {
+            await lock.release();
+        }
+    }
+}
+//# sourceMappingURL=resources-orphans.js.map