@telepath-computer/autofile 0.3.0 → 0.5.0

package/dist/store.js

@@ -1,7 +1,8 @@
 /**
- * Reads and writes Autofile's on-disk types and records, and exposes recognized
- * records, declarations, and blobs as plain resource data. Each operation reads
- * current files and keeps protocol-specific behavior outside the store.
+ * Autofile owns one data folder: record and type operations, blob uploads and
+ * reads, and shared change subscriptions. Operations read current files;
+ * protocol adapters translate these values without owning a second persistence
+ * implementation.
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
@@ -11,41 +12,236 @@ import { setTimeout as delay } from "node:timers/promises";
 import { lookup as lookupMimeType } from "mime-types";
 import { Query } from "mingo";
 import lockfile from "proper-lockfile";
-import { BLOB_NAME_PATTERN, BLOB_URI_PATTERN, MAX_BLOB_BYTES, blobNameFromUri, blobUri, deleteBlobUris, prepareBlob, writePreparedBlobs, } from "./blobs.js";
-import { getStorage, getWriteLockPath } from "./config.js";
+import { blobNameFromUri, deleteBlobUris, blobReferenceProblem, isMediaType, writeBlob, writeBlobStream, } from "./blobs.js";
+import { getWriteLockPath } from "./config.js";
+import { jsonObjectProblem } from "./json.js";
 import { prepareSchema, SchemaRefusal } from "./schema.js";
+import { watchFolder } from "./watch.js";
 const typeNamePattern = /^[a-z][a-z0-9-]*$/u;
 const keyPattern = /^[a-z0-9][a-z0-9-]*$/u;
-const recordUriPattern = /^autofile:\/\/\/([a-z][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/u;
-const typeUriPattern = /^autofile:\/\/\/_types\/([a-z][a-z0-9-]*)$/u;
+const recordUriPattern = /^autofile:\/\/\/records\/([a-z][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/u;
 const timestampPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u;
 const MAX_FIND_RECORDS_PAGE_BYTES = 64 * 1024;
 const tidAlphabet = "234567abcdefghijklmnopqrstuvwxyz";
 const invalidTypeMessage = "type: must use lowercase letters, digits, and hyphens and start with a letter";
 const invalidKeyMessage = "key: must use lowercase letters, digits, and hyphens and start with a letter or digit";
-const invalidRecordUriMessage = "uri: must be a record URI, such as autofile:///task/book-the-dentist";
+const invalidRecordUriMessage = "uri: must be a record URI, such as autofile:///records/task/book-the-dentist";
 const clockIdentifier = BigInt(randomBytes(2).readUInt16BE() & 0x3ff);
 let lastTidTimestamp = 0n;
-/** Opens a store, creating its data folder when it does not exist. */
-export async function openStore(options = {}) {
-    const dataFolder = resolve(options.dataFolder ?? await getStorage());
-    const writeLockPath = resolve(options.writeLockPath ?? getWriteLockPath());
-    await Promise.all([
-        mkdir(dataFolder, { recursive: true }),
-        mkdir(dirname(writeLockPath), { recursive: true }),
-    ]);
-    return createStore(dataFolder, writeLockPath);
+/** A refused operation, with every problem the caller can correct. */
+export class AutofileError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.map(({ message }) => message).join("; "));
+        this.name = "AutofileError";
+        this.problems = problems;
+    }
 }
-function createStore(dataFolder, writeLockPath) {
-    const typeFolder = join(dataFolder, "_types");
-    const blobFolder = join(dataFolder, "_blobs");
-    async function withWriteLock(write) {
+/** The store implementation. Construction resolves paths but performs no I/O. */
+export class Autofile {
+    #dataFolder;
+    #typeFolder;
+    #blobFolder;
+    #writeLockPath;
+    #ready;
+    #closed = false;
+    #closing;
+    #watcher;
+    #notifications = Promise.resolve();
+    #listeners = new Set();
+    #watchTypes = new Set();
+    constructor(options) {
+        if (typeof options?.folder !== "string" || options.folder.length === 0) {
+            refuse("folder: must be a non-empty string");
+        }
+        this.#dataFolder = resolve(options.folder);
+        this.#typeFolder = join(this.#dataFolder, "types");
+        this.#blobFolder = join(this.#dataFolder, "blobs");
+        // Keep the existing process-home lock policy until a separate change moves it.
+        this.#writeLockPath = resolve(getWriteLockPath());
+    }
+    records = {
+        find: (query = {}) => this.#operation(() => this.#findRecords(query)),
+        get: (uri) => this.#operation(() => this.#getRecord(uri)),
+        create: (type, value, options = {}) => this.#operation(() => {
+            if (!isJsonObject(options))
+                return refuse("options: must be an object");
+            const problem = jsonObjectProblem(value);
+            if (problem !== undefined)
+                return refuse(`record: ${problem}`);
+            // Snapshot checked JSON before asynchronous storage work begins.
+            return this.#createRecord(type, JSON.parse(JSON.stringify(value)), { key: options.key });
+        }),
+        update: (uri, patch) => this.#operation(() => {
+            const problem = jsonObjectProblem(patch);
+            if (problem !== undefined)
+                return refuse(`patch: ${problem}`, uri);
+            return this.#updateRecord(uri, JSON.parse(JSON.stringify(patch)));
+        }),
+        delete: (uri) => this.#operation(() => this.#deleteRecord(uri)),
+    };
+    types = {
+        list: () => this.#operation(() => this.#listTypes()),
+        get: (name) => this.#operation(() => this.#getType(name)),
+        create: (name, definition) => this.#operation(() => this.#createType(name, definition)),
+        update: (name, changes) => this.#operation(() => this.#updateType(name, changes)),
+        delete: (name) => this.#operation(() => this.#deleteType(name)),
+    };
+    blobs = {
+        put: (bytes, mediaType) => this.#operation(() => {
+            if (!(bytes instanceof Uint8Array))
+                return refuse("bytes: must be a Uint8Array");
+            if (!isMediaType(mediaType))
+                return refuse("mediaType: must be a valid media type, such as application/pdf");
+            const snapshot = Buffer.from(bytes);
+            return this.#withWriteLock(() => writeBlob(this.#blobFolder, snapshot, mediaType));
+        }),
+        putStream: (chunks, mediaType) => this.#operation(() => {
+            if (typeof chunks?.[Symbol.asyncIterator] !== "function")
+                return refuse("chunks: must be an AsyncIterable of Uint8Array chunks");
+            if (!isMediaType(mediaType))
+                return refuse("mediaType: must be a valid media type, such as application/pdf");
+            return this.#withWriteLock(() => writeBlobStream(this.#blobFolder, snapshotBlobChunks(chunks), mediaType));
+        }),
+        get: (uri) => this.#operation(() => this.#getBlob(uri)),
+        stat: (uri) => this.#operation(() => this.#statBlob(uri)),
+        stream: (uri, range) => this.#operation(() => this.#streamBlob(uri, range)),
+    };
+    /** Checks a schema without accessing storage or checking link targets. */
+    static async prepareSchema(schema) {
+        return prepareDeclarationSchema(snapshotSchema(schema));
+    }
+    /** Subscribes after the shared watcher is ready; the returned function unsubscribes. */
+    async watch(onChange, options = {}) {
+        await this.#operation(() => this.#ensureReady());
+        // Each call is a subscription, even if callers reuse the same function.
+        const listener = { onChange, ...options };
+        this.#listeners.add(listener);
+        this.#watcher ??= this.#startWatcher();
+        try {
+            await this.#watcher;
+            this.#assertOpen();
+        }
+        catch (error) {
+            this.#listeners.delete(listener);
+            this.#watcher = undefined;
+            if (hasErrorCode(error))
+                throw new Error("Change monitoring failed");
+            throw error;
+        }
+        return async () => { this.#listeners.delete(listener); };
+    }
+    /** Stops change subscriptions. Future operations on this instance are refused. */
+    close() {
+        this.#closed = true;
+        this.#listeners.clear();
+        this.#closing ??= (async () => {
+            const watcher = await this.#watcher;
+            await this.#operation(async () => watcher?.close());
+        })();
+        return this.#closing;
+    }
+    async #operation(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (hasErrorCode(error))
+                throw new Error("Storage operation failed");
+            throw error;
+        }
+    }
+    #assertOpen() {
+        if (this.#closed)
+            refuse("Autofile is closed");
+    }
+    async #ensureReady() {
+        this.#assertOpen();
+        this.#ready ??= Promise.all([
+            mkdir(this.#dataFolder, { recursive: true }),
+            mkdir(dirname(this.#writeLockPath), { recursive: true }),
+        ]).then(() => undefined);
+        await this.#ready;
+        this.#assertOpen();
+    }
+    #reportWatchError() {
+        const failure = new Error("Change monitoring failed");
+        for (const listener of this.#listeners)
+            reportSubscriptionError(listener, failure);
+    }
+    async #startWatcher() {
+        const watcher = await watchFolder(this.#dataFolder, (changes) => {
+            // Delivery is ordered independently of the filesystem watcher so a
+            // subscriber may await close without waiting for its own callback.
+            this.#notifications = this.#notifications.then(async () => {
+                await this.#watcher;
+                if (this.#closed)
+                    return;
+                const events = await this.#logicalChanges(changes);
+                if (events.length === 0)
+                    return;
+                for (const subscription of [...this.#listeners]) {
+                    if (!this.#listeners.has(subscription))
+                        continue;
+                    try {
+                        await subscription.onChange(events);
+                    }
+                    catch (error) {
+                        reportSubscriptionError(subscription, toError(error));
+                    }
+                }
+            }).catch(() => this.#reportWatchError());
+        }, () => this.#reportWatchError());
+        try {
+            for (const declaration of await this.#listTypes())
+                this.#watchTypes.add(declaration.type);
+            return watcher;
+        }
+        catch {
+            await watcher.close();
+            throw new Error("Change monitoring failed");
+        }
+    }
+    async #logicalChanges(changes) {
+        const previousTypes = new Set(this.#watchTypes);
+        const uncertainTypes = new Set();
+        const events = [];
+        for (const change of changes) {
+            if (!change.uri.startsWith("autofile:///types/"))
+                continue;
+            const type = change.uri.slice("autofile:///types/".length);
+            try {
+                const declaration = await readValidDeclaration(this.#typeFolder, type);
+                if (declaration === undefined)
+                    this.#watchTypes.delete(type);
+                else
+                    this.#watchTypes.add(type);
+            }
+            catch {
+                // An unavailable declaration does not prove a type disappeared. Retain
+                // known membership and forward this batch's affected hints for rereading.
+                uncertainTypes.add(type);
+                this.#reportWatchError();
+            }
+            if (previousTypes.has(type) || this.#watchTypes.has(type) || uncertainTypes.has(type))
+                events.push(change);
+        }
+        for (const change of changes) {
+            const record = parseRecordUri(change.uri);
+            if (record !== undefined && (previousTypes.has(record.type) || this.#watchTypes.has(record.type) || uncertainTypes.has(record.type))) {
+                events.push(change);
+            }
+        }
+        return events;
+    }
+    async #withWriteLock(write) {
+        await this.#ensureReady();
         let release;
         let retryDelay = 50;
         while (true) {
             try {
-                release = await lockfile.lock(dirname(writeLockPath), {
-                    lockfilePath: writeLockPath,
+                release = await lockfile.lock(dirname(this.#writeLockPath), {
+                    lockfilePath: this.#writeLockPath,
                     stale: 10_000,
                     update: 5_000,
                     retries: 0,
@@ -66,9 +262,16 @@ function createStore(dataFolder, writeLockPath) {
             await release();
         }
     }
-    async function findRecords(input) {
-        if (!typeNamePattern.test(input.type))
-            return refuse(invalidTypeMessage);
+    async #findRecords(input) {
+        await this.#ensureReady();
+        if (input === null || typeof input !== "object" || Array.isArray(input))
+            return refuse("query: must be an object");
+        const requestedTypes = input.type === undefined ? undefined
+            : typeof input.type === "string" ? [input.type] : input.type;
+        if (requestedTypes !== undefined && (!Array.isArray(requestedTypes)
+            || requestedTypes.some((type) => typeof type !== "string" || !typeNamePattern.test(type)))) {
+            refuse(invalidTypeMessage);
+        }
         if (input.q !== undefined && typeof input.q !== "string") {
             return refuse("q: must be a string");
         }
@@ -93,22 +296,27 @@ function createStore(dataFolder, writeLockPath) {
             return refuse(whereRefusal);
         const afterUri = input.cursor === undefined
             ? undefined
-            : decodeRecordCursor(input.cursor, input.type);
+            : decodeRecordCursor(input.cursor, requestedTypes);
         if (input.cursor !== undefined && afterUri === undefined) {
             return refuse("cursor: is invalid");
         }
-        const declaration = await readDeclaration(typeFolder, input.type);
-        if (declaration.status !== "found")
-            return declarationRefusal(input.type, declaration);
-        const schema = await preparedDeclarationSchema(declaration.value, typeUri(input.type));
-        if ("errors" in schema)
-            return schema;
-        const entries = (await recognizedRecordEntries(join(dataFolder, input.type)))
-            .map((entry) => ({
-            entry,
-            uri: recordUri(input.type, entry.name.slice(0, -".json".length)),
-        }))
-            .sort((left, right) => left.uri < right.uri ? -1 : left.uri > right.uri ? 1 : 0);
+        const declarations = requestedTypes === undefined
+            ? await this.#listTypes()
+            : await Promise.all([...new Set(requestedTypes)].map(async (type) => {
+                const declaration = await this.#getType(type);
+                if (declaration === undefined)
+                    refuse("type does not exist", typeUri(type));
+                return declaration;
+            }));
+        const entries = [];
+        for (const declaration of declarations) {
+            const schema = await preparedDeclarationSchema(declaration, declaration.uri);
+            for (const entry of await recognizedRecordEntries(recordFolder(this.#dataFolder, declaration.type))) {
+                const key = entry.name.slice(0, -".json".length);
+                entries.push({ type: declaration.type, key, name: entry.name, uri: recordUri(declaration.type, key), declaration, schema });
+            }
+        }
+        entries.sort((left, right) => left.uri < right.uri ? -1 : left.uri > right.uri ? 1 : 0);
         const start = afterUri === undefined
             ? 0
             : entries.findIndex(({ uri }) => uri > afterUri);
@@ -125,15 +333,15 @@ function createStore(dataFolder, writeLockPath) {
             if (current === undefined)
                 break;
             nextIndex += 1;
-            const { entry, uri } = current;
+            const { type, key, name, uri, declaration, schema } = current;
             let stored;
             let record;
             let resultError;
             try {
-                stored = await readStoredRecord(join(dataFolder, input.type, entry.name));
+                stored = await readStoredRecord(join(recordFolder(this.#dataFolder, type), name));
             }
             catch (error) {
-                resultError = { uri, message: recordFileReadError(error) };
+                resultError = { uri, message: recordReadError(error) };
             }
             if (stored !== undefined) {
                 if (stored.status !== "found") {
@@ -149,14 +357,10 @@ function createStore(dataFolder, writeLockPath) {
                         resultError = { uri, message: validationErrors.join("; ") };
                     }
                     else {
-                        record = {
-                            uri,
-                            createdAt: stored.value.createdAt,
-                            updatedAt: stored.value.updatedAt,
-                            value: fields === undefined
-                                ? stored.value.value
-                                : Object.fromEntries(Object.entries(stored.value.value).filter(([field]) => fields.has(field))),
-                        };
+                        record = recordResult(type, key, declaration, stored.value);
+                        if (fields !== undefined) {
+                            record.value = Object.fromEntries(Object.entries(record.value).filter(([field]) => fields.has(field)));
+                        }
                     }
                 }
             }
@@ -168,7 +372,7 @@ function createStore(dataFolder, writeLockPath) {
             const nextErrors = resultError === undefined ? errors : [...errors, resultError];
             const nextPageBytes = Buffer.byteLength(JSON.stringify({
                 records: nextRecords,
-                errors: nextErrors,
+                unreadable: nextErrors,
             }), "utf8");
             if (records.length + errors.length > 0 && nextPageBytes > MAX_FIND_RECORDS_PAGE_BYTES) {
                 // Reading the candidate is necessary to know its serialized size, but it belongs to the
@@ -187,182 +391,166 @@ function createStore(dataFolder, writeLockPath) {
         }
         return {
             records,
-            errors,
+            unreadable: errors,
             ...(lastReadUri !== undefined && nextIndex < entries.length
                 ? { cursor: encodeRecordCursor(lastReadUri) }
                 : {}),
         };
     }
-    async function getRecord(input) {
-        const parsed = parseRecordUri(input.uri);
+    async #getRecord(uri) {
+        await this.#ensureReady();
+        const parsed = parseRecordUri(uri);
         if (parsed === undefined)
             return refuse(invalidRecordUriMessage);
-        const declaration = await readDeclaration(typeFolder, parsed.type);
+        const declaration = await readDeclaration(this.#typeFolder, parsed.type);
+        if (declaration.status === "missing")
+            return undefined;
         if (declaration.status !== "found")
             return declarationRefusal(parsed.type, declaration);
-        const stored = await readStoredRecord(recordPath(dataFolder, parsed.type, parsed.key));
+        const stored = await readStoredRecord(recordPath(this.#dataFolder, parsed.type, parsed.key));
+        if (stored.status === "missing")
+            return undefined;
         if (stored.status !== "found")
-            return recordReadRefusal(input.uri, stored);
+            return recordReadRefusal(uri, stored);
         const schema = await preparedDeclarationSchema(declaration.value, typeUri(parsed.type));
-        if ("errors" in schema)
-            return schema;
         const validationErrors = await schema.validate(stored.value.value);
-        const result = {
-            uri: input.uri,
-            createdAt: stored.value.createdAt,
-            updatedAt: stored.value.updatedAt,
-            value: stored.value.value,
-        };
+        const result = recordResult(parsed.type, parsed.key, declaration.value, stored.value);
         if (validationErrors.length > 0)
-            result.error = validationErrors.join("; ");
+            result.problems = validationErrors.map((message) => ({ uri, message }));
         return result;
     }
-    async function createRecord(input, options = {}) {
-        return withWriteLock(async () => {
-            if (!typeNamePattern.test(input.type))
+    async #createRecord(type, value, options) {
+        return this.#withWriteLock(async () => {
+            if (typeof type !== "string" || !typeNamePattern.test(type))
                 return refuse(invalidTypeMessage);
-            if (input.key !== undefined && !keyPattern.test(input.key)) {
+            if (options.key !== undefined && (typeof options.key !== "string" || !keyPattern.test(options.key))) {
                 return refuse(invalidKeyMessage);
             }
-            if (!isJsonObject(input.record))
+            if (!isJsonObject(value))
                 return refuse("record: must be a JSON object");
-            const declaration = await readDeclaration(typeFolder, input.type);
+            const declaration = await readDeclaration(this.#typeFolder, type);
             if (declaration.status !== "found")
-                return declarationRefusal(input.type, declaration);
-            const schema = await preparedDeclarationSchema(declaration.value, typeUri(input.type));
-            if ("errors" in schema)
-                return schema;
-            const validationErrors = await schema.validate(input.record);
+                return declarationRefusal(type, declaration);
+            const schema = await preparedDeclarationSchema(declaration.value, typeUri(type));
+            const sourceUri = options.key === undefined ? undefined : recordUri(type, options.key);
+            const validationErrors = await schema.validate(value);
             if (validationErrors.length > 0) {
-                const uri = input.key === undefined ? undefined : recordUri(input.type, input.key);
-                return { errors: validationErrors.map((message) => ({ ...(uri === undefined ? {} : { uri }), message })) };
+                throw new AutofileError(validationErrors.map((message) => ({ ...(sourceUri === undefined ? {} : { uri: sourceUri }), message })));
             }
-            const sourceUri = input.key === undefined ? undefined : recordUri(input.type, input.key);
-            const linkErrors = await missingLinkErrors(dataFolder, typeFolder, schema, input.record, sourceUri);
+            const linkErrors = await missingLinkErrors(this.#dataFolder, this.#typeFolder, schema, value, sourceUri);
             if (linkErrors.length > 0)
-                return { errors: linkErrors };
-            await mkdir(join(dataFolder, input.type), { recursive: true });
-            let key = input.key;
+                throw new AutofileError(linkErrors);
+            await mkdir(recordFolder(this.#dataFolder, type), { recursive: true });
+            let key = options.key;
             if (key === undefined) {
                 do
                     key = nextTid();
-                while (await pathExists(recordPath(dataFolder, input.type, key)));
+                while (await pathExists(recordPath(this.#dataFolder, type, key)));
             }
-            else if (await pathExists(recordPath(dataFolder, input.type, key))) {
-                return refuse("a record with that key already exists", recordUri(input.type, key));
+            else if (await pathExists(recordPath(this.#dataFolder, type, key))) {
+                return refuse("a record with that key already exists", recordUri(type, key));
             }
-            const uri = recordUri(input.type, key);
-            const materialized = await prepareRecordBlobs(blobFolder, schema, input.record, options.allowLocalPaths ?? true, uri);
-            if ("errors" in materialized)
-                return materialized;
-            const materializedLinkErrors = await missingLinkErrors(dataFolder, typeFolder, schema, materialized.value, uri);
-            if (materializedLinkErrors.length > 0)
-                return { errors: materializedLinkErrors };
+            const uri = recordUri(type, key);
+            const blobErrors = await missingBlobErrors(this.#blobFolder, schema, value, uri);
+            if (blobErrors.length > 0)
+                throw new AutofileError(blobErrors);
             const now = new Date().toISOString();
-            await writePreparedBlobs(blobFolder, materialized.blobs);
-            await writeJsonAtomically(recordPath(dataFolder, input.type, key), {
-                createdAt: now,
-                updatedAt: now,
-                value: materialized.value,
-            });
-            return { uri };
+            const stored = { createdAt: now, updatedAt: now, value };
+            await writeJsonAtomically(recordPath(this.#dataFolder, type, key), stored);
+            return recordResult(type, key, declaration.value, stored);
         });
     }
-    async function updateRecord(input, options = {}) {
-        return withWriteLock(async () => {
-            const parsed = parseRecordUri(input.uri);
+    async #updateRecord(uri, patch) {
+        return this.#withWriteLock(async () => {
+            const parsed = parseRecordUri(uri);
             if (parsed === undefined)
                 return refuse(invalidRecordUriMessage);
-            if (!isJsonObject(input.patch))
-                return refuse("patch: must be a JSON object", input.uri);
-            const declaration = await readDeclaration(typeFolder, parsed.type);
+            if (!isJsonObject(patch))
+                return refuse("patch: must be a JSON object", uri);
+            const declaration = await readDeclaration(this.#typeFolder, parsed.type);
             if (declaration.status !== "found")
                 return declarationRefusal(parsed.type, declaration);
-            const path = recordPath(dataFolder, parsed.type, parsed.key);
+            const path = recordPath(this.#dataFolder, parsed.type, parsed.key);
             const stored = await readStoredRecord(path);
             if (stored.status !== "found")
-                return recordReadRefusal(input.uri, stored);
-            const value = mergePatch(stored.value.value, input.patch);
+                return recordReadRefusal(uri, stored);
+            const value = mergePatch(stored.value.value, patch);
+            const problem = jsonObjectProblem(value);
+            if (problem !== undefined)
+                return refuse(`record: ${problem}`, uri);
             const schema = await preparedDeclarationSchema(declaration.value, typeUri(parsed.type));
-            if ("errors" in schema)
-                return schema;
             const validationErrors = await schema.validate(value);
             if (validationErrors.length > 0) {
-                return { errors: validationErrors.map((message) => ({ uri: input.uri, message })) };
+                throw new AutofileError(validationErrors.map((message) => ({ uri, message })));
             }
-            const linkErrors = await missingLinkErrors(dataFolder, typeFolder, schema, value, input.uri);
-            if (linkErrors.length > 0)
-                return { errors: linkErrors };
-            const materialized = await prepareRecordBlobs(blobFolder, schema, value, options.allowLocalPaths ?? true, input.uri);
-            if ("errors" in materialized)
-                return materialized;
-            const materializedLinkErrors = await missingLinkErrors(dataFolder, typeFolder, schema, materialized.value, input.uri);
-            if (materializedLinkErrors.length > 0)
-                return { errors: materializedLinkErrors };
+            const errors = [
+                ...await missingLinkErrors(this.#dataFolder, this.#typeFolder, schema, value, uri),
+                ...await missingBlobErrors(this.#blobFolder, schema, value, uri),
+            ];
+            if (errors.length > 0)
+                throw new AutofileError(errors);
             const previousBlobs = await blobsHeldByRecord(stored.value.value, schema);
-            await writePreparedBlobs(blobFolder, materialized.blobs);
-            await writeJsonAtomically(path, {
+            const updated = {
                 createdAt: stored.value.createdAt,
                 updatedAt: new Date().toISOString(),
-                value: materialized.value,
-            });
-            await deleteUnheldBlobs(dataFolder, typeFolder, previousBlobs);
-            return { uri: input.uri };
+                value,
+            };
+            await writeJsonAtomically(path, updated);
+            await deleteUnheldBlobs(this.#dataFolder, this.#typeFolder, previousBlobs);
+            return recordResult(parsed.type, parsed.key, declaration.value, updated);
         });
     }
-    async function deleteRecord(input) {
-        return withWriteLock(async () => {
-            const parsed = parseRecordUri(input.uri);
+    async #deleteRecord(targetUri) {
+        return this.#withWriteLock(async () => {
+            const parsed = parseRecordUri(targetUri);
             if (parsed === undefined)
                 return refuse(invalidRecordUriMessage);
-            const declaration = await readDeclaration(typeFolder, parsed.type);
+            const declaration = await readDeclaration(this.#typeFolder, parsed.type);
             if (declaration.status !== "found")
                 return declarationRefusal(parsed.type, declaration);
-            const path = recordPath(dataFolder, parsed.type, parsed.key);
+            const path = recordPath(this.#dataFolder, parsed.type, parsed.key);
             if (!await isRegularFile(path))
-                return refuse("record does not exist", input.uri);
+                return refuse("record does not exist", targetUri);
             const changes = [];
             const errors = [];
             let deletedRecord;
             try {
                 const target = await readStoredRecord(path);
                 if (target.status === "missing") {
-                    errors.push({ uri: input.uri, message: "record does not exist" });
+                    errors.push({ uri: targetUri, message: "record does not exist" });
                 }
                 else if (target.status === "invalid") {
-                    errors.push({ uri: input.uri, message: target.message });
+                    errors.push({ uri: targetUri, message: target.message });
                 }
                 else {
                     deletedRecord = target.value;
                 }
             }
             catch (error) {
-                errors.push({ uri: input.uri, message: recordFileReadError(error) });
+                errors.push({ uri: targetUri, message: recordReadError(error) });
             }
-            const typeEntries = (await readDirectory(typeFolder))
+            const typeEntries = (await readDirectory(this.#typeFolder))
                 .filter((entry) => (entry.isFile()
                 && entry.name.endsWith(".json")
                 && typeNamePattern.test(entry.name.slice(0, -".json".length))))
                 .sort((left, right) => left.name.localeCompare(right.name));
             for (const typeEntry of typeEntries) {
                 const type = typeEntry.name.slice(0, -".json".length);
-                const otherDeclaration = await readValidDeclaration(typeFolder, type);
+                const otherDeclaration = await readValidDeclaration(this.#typeFolder, type);
                 if (otherDeclaration === undefined)
                     continue;
                 const schema = await preparedDeclarationSchema(otherDeclaration, typeUri(type));
-                if ("errors" in schema)
-                    continue;
-                for (const entry of await recognizedRecordEntries(join(dataFolder, type))) {
+                for (const entry of await recognizedRecordEntries(recordFolder(this.#dataFolder, type))) {
                     const key = entry.name.slice(0, -".json".length);
                     const uri = recordUri(type, key);
-                    if (uri === input.uri)
+                    if (uri === targetUri)
                         continue;
                     let stored;
                     try {
-                        stored = await readStoredRecord(join(dataFolder, type, entry.name));
+                        stored = await readStoredRecord(join(recordFolder(this.#dataFolder, type), entry.name));
                     }
                     catch (error) {
-                        errors.push({ uri, message: recordFileReadError(error) });
+                        errors.push({ uri, message: recordReadError(error) });
                         continue;
                     }
                     if (stored.status !== "found") {
@@ -374,16 +562,16 @@ function createStore(dataFolder, writeLockPath) {
                     }
                     const validationErrors = await schema.validate(stored.value.value);
                     if (validationErrors.length > 0) {
-                        if (containsStringValue(stored.value.value, input.uri)) {
+                        if (containsStringValue(stored.value.value, targetUri)) {
                             errors.push({
                                 uri,
-                                message: `record does not match its type and holds ${input.uri} as a string value`,
+                                message: `record does not match its type and holds ${targetUri} as a string value`,
                             });
                         }
                         continue;
                     }
                     const pointers = schema.formatFields(stored.value.value, "uri")
-                        .filter((field) => field.value === input.uri)
+                        .filter((field) => field.value === targetUri)
                         .map(({ pointer }) => pointer);
                     if (pointers.length === 0)
                         continue;
@@ -394,7 +582,7 @@ function createStore(dataFolder, writeLockPath) {
                         continue;
                     }
                     changes.push({
-                        path: join(dataFolder, type, entry.name),
+                        path: join(recordFolder(this.#dataFolder, type), entry.name),
                         record: {
                             createdAt: stored.value.createdAt,
                             updatedAt: timestampAfter(stored.value.updatedAt),
@@ -408,302 +596,245 @@ function createStore(dataFolder, writeLockPath) {
                     const uriOrder = (left.uri ?? "").localeCompare(right.uri ?? "");
                     return uriOrder === 0 ? left.message.localeCompare(right.message) : uriOrder;
                 });
-                return { errors };
+                throw new AutofileError(errors);
+            }
+            let targetSchema;
+            try {
+                targetSchema = await preparedDeclarationSchema(declaration.value, typeUri(parsed.type));
+            }
+            catch (error) {
+                if (!(error instanceof AutofileError))
+                    throw error;
             }
-            const targetSchema = await preparedDeclarationSchema(declaration.value, typeUri(parsed.type));
             const previousBlobs = deletedRecord === undefined
                 ? new Set()
-                : "errors" in targetSchema
+                : targetSchema === undefined
                     ? blobUrisIn(deletedRecord.value)
                     : await blobsHeldByRecord(deletedRecord.value, targetSchema);
             for (const change of changes)
                 await writeJsonAtomically(change.path, change.record);
             await unlink(path);
-            await deleteUnheldBlobs(dataFolder, typeFolder, previousBlobs);
-            return { uri: input.uri };
+            await deleteUnheldBlobs(this.#dataFolder, this.#typeFolder, previousBlobs);
         });
     }
-    async function listTypes(_input) {
-        const entries = await readDirectory(typeFolder);
+    async #listTypes() {
+        await this.#ensureReady();
         const types = [];
-        for (const entry of entries) {
+        for (const entry of await readDirectory(this.#typeFolder)) {
             if (!entry.isFile() || !entry.name.endsWith(".json"))
                 continue;
             const type = entry.name.slice(0, -".json".length);
             if (!typeNamePattern.test(type))
                 continue;
-            const declaration = await readValidDeclaration(typeFolder, type);
-            if (declaration === undefined)
-                continue;
-            types.push({ uri: typeUri(type), type, description: declaration.description });
+            const declaration = await readValidDeclaration(this.#typeFolder, type);
+            if (declaration !== undefined)
+                types.push(typeResult(type, declaration));
         }
-        types.sort((left, right) => left.type.localeCompare(right.type));
-        return { types };
+        return types.sort((left, right) => left.type.localeCompare(right.type));
+    }
+    async #getType(type) {
+        await this.#ensureReady();
+        if (typeof type !== "string" || !typeNamePattern.test(type))
+            refuse(invalidTypeMessage);
+        const declaration = await readDeclaration(this.#typeFolder, type);
+        if (declaration.status === "missing")
+            return undefined;
+        if (declaration.status !== "found")
+            return declarationRefusal(type, declaration);
+        await preparedDeclarationSchema(declaration.value, typeUri(type));
+        return typeResult(type, declaration.value);
     }
-    async function getType(input) {
-        if (!typeNamePattern.test(input.type))
+    async #createType(type, definition) {
+        if (typeof type !== "string" || !typeNamePattern.test(type))
             return refuse(invalidTypeMessage);
-        const declaration = await readDeclaration(typeFolder, input.type);
-        if (declaration.status !== "found")
-            return declarationRefusal(input.type, declaration);
-        const schema = await preparedDeclarationSchema(declaration.value, typeUri(input.type));
-        if ("errors" in schema)
-            return schema;
-        return {
-            uri: typeUri(input.type),
-            description: declaration.value.description,
-            ...(declaration.value.titleField === undefined
-                ? {}
-                : { titleField: declaration.value.titleField }),
-            schema: declaration.value.schema,
+        if (!isJsonObject(definition))
+            return refuse("declaration: must be an object");
+        const { description, titleField } = definition;
+        const title = readTypeTitle(definition);
+        if (typeof description !== "string")
+            return refuse("description: must be a string");
+        if (titleField !== undefined && typeof titleField !== "string") {
+            return refuse("titleField: must be a string");
+        }
+        if (title !== undefined && (typeof title !== "string" || title.length === 0)) {
+            return refuse("title: must be a non-empty string");
+        }
+        // Validate and copy caller-owned data before acquiring the asynchronous lock.
+        const declaration = {
+            description,
+            ...(title === undefined ? {} : { title }),
+            ...(titleField === undefined ? {} : { titleField }),
+            schema: snapshotSchema(definition.schema),
         };
-    }
-    async function createType(input) {
-        return withWriteLock(async () => {
-            if (!typeNamePattern.test(input.type))
-                return refuse(invalidTypeMessage);
-            if (typeof input.description !== "string")
-                return refuse("description: must be a string");
-            if (input.titleField !== undefined && typeof input.titleField !== "string") {
-                return refuse("titleField: must be a string");
-            }
-            if (!isJsonObject(input.schema))
-                return refuse("schema: must be a JSON object");
-            const declarationPath = join(typeFolder, `${input.type}.json`);
+        return this.#withWriteLock(async () => {
+            const declarationPath = join(this.#typeFolder, `${type}.json`);
             if (await pathExists(declarationPath)) {
-                return refuse("type already exists", typeUri(input.type));
+                return refuse("type already exists", typeUri(type));
             }
-            const schema = await prepareDeclarationSchema(input.schema, typeUri(input.type));
-            if ("errors" in schema)
-                return schema;
+            await prepareDeclarationSchema(declaration.schema, typeUri(type));
             await Promise.all([
-                mkdir(typeFolder, { recursive: true }),
-                mkdir(join(dataFolder, input.type), { recursive: true }),
+                mkdir(this.#typeFolder, { recursive: true }),
+                mkdir(recordFolder(this.#dataFolder, type), { recursive: true }),
             ]);
-            await writeJsonAtomically(declarationPath, {
-                description: input.description,
-                ...(input.titleField === undefined ? {} : { titleField: input.titleField }),
-                schema: input.schema,
-            });
-            return { uri: typeUri(input.type) };
+            await writeJsonAtomically(declarationPath, declaration);
+            return typeResult(type, declaration);
         });
     }
-    async function updateType(input) {
-        return withWriteLock(async () => {
-            if (!typeNamePattern.test(input.type))
-                return refuse(invalidTypeMessage);
-            const current = await readDeclaration(typeFolder, input.type);
+    async #updateType(type, changes) {
+        if (typeof type !== "string" || !typeNamePattern.test(type))
+            return refuse(invalidTypeMessage);
+        if (!isJsonObject(changes))
+            return refuse("changes: must be an object");
+        const { description, titleField: changedTitleField, schema: changedSchema } = changes;
+        const changedTitle = readTypeTitle(changes);
+        if (description !== undefined && typeof description !== "string") {
+            return refuse("description: must be a string");
+        }
+        if (changedTitleField !== undefined
+            && changedTitleField !== null
+            && typeof changedTitleField !== "string") {
+            return refuse("titleField: must be a string or null");
+        }
+        if (changedTitle !== undefined
+            && changedTitle !== null
+            && (typeof changedTitle !== "string" || changedTitle.length === 0)) {
+            return refuse("title: must be a non-empty string or null");
+        }
+        const schemaSnapshot = changedSchema === undefined ? undefined : snapshotSchema(changedSchema);
+        return this.#withWriteLock(async () => {
+            const current = await readDeclaration(this.#typeFolder, type);
             if (current.status !== "found")
-                return declarationRefusal(input.type, current);
-            if (input.description !== undefined && typeof input.description !== "string") {
-                return refuse("description: must be a string");
-            }
-            if (input.titleField !== undefined
-                && input.titleField !== null
-                && typeof input.titleField !== "string") {
-                return refuse("titleField: must be a string or null");
-            }
-            if (input.schema !== undefined && !isJsonObject(input.schema)) {
-                return refuse("schema: must be a JSON object");
-            }
-            const titleField = input.titleField === null
+                return declarationRefusal(type, current);
+            const titleField = changedTitleField === null
                 ? undefined
-                : input.titleField ?? current.value.titleField;
+                : changedTitleField ?? current.value.titleField;
+            const title = changedTitle === null ? undefined : changedTitle ?? current.value.title;
             const declaration = {
-                description: input.description ?? current.value.description,
+                description: description ?? current.value.description,
+                ...(title === undefined ? {} : { title }),
                 ...(titleField === undefined ? {} : { titleField }),
-                schema: input.schema ?? current.value.schema,
+                schema: schemaSnapshot ?? snapshotSchema(current.value.schema),
             };
-            const schema = await prepareDeclarationSchema(declaration.schema, typeUri(input.type));
-            if ("errors" in schema)
-                return schema;
-            await writeJsonAtomically(join(typeFolder, `${input.type}.json`), declaration);
-            const errors = await invalidRecords(dataFolder, input.type, schema);
-            return { uri: typeUri(input.type), errors };
+            const schema = await prepareDeclarationSchema(declaration.schema, typeUri(type));
+            await writeJsonAtomically(join(this.#typeFolder, `${type}.json`), declaration);
+            const errors = await invalidRecords(this.#dataFolder, type, schema);
+            const result = typeResult(type, declaration);
+            if (errors.length > 0)
+                result.problems = errors;
+            return result;
         });
     }
-    async function deleteType(input) {
-        return withWriteLock(async () => {
-            if (!typeNamePattern.test(input.type))
+    async #deleteType(type) {
+        return this.#withWriteLock(async () => {
+            if (typeof type !== "string" || !typeNamePattern.test(type))
                 return refuse(invalidTypeMessage);
-            const declaration = await readDeclaration(typeFolder, input.type);
+            const declaration = await readDeclaration(this.#typeFolder, type);
             if (declaration.status !== "found")
-                return declarationRefusal(input.type, declaration);
+                return declarationRefusal(type, declaration);
             try {
-                await rmdir(join(dataFolder, input.type));
+                await rmdir(recordFolder(this.#dataFolder, type));
             }
             catch (error) {
-                if (hasCode(error, "ENOTEMPTY") || hasCode(error, "EEXIST")) {
-                    return refuse("type folder is not empty", typeUri(input.type));
+                // Keep the declaration whenever any stored data remains, including
+                // entries that cannot be recognized or read as records.
+                if (["ENOTDIR", "ENOTEMPTY", "EEXIST"].some((code) => hasCode(error, code))) {
+                    return refuse("type still has stored data", typeUri(type));
                 }
                 if (!hasCode(error, "ENOENT"))
                     throw error;
             }
-            await unlink(join(typeFolder, `${input.type}.json`));
-            return { uri: typeUri(input.type) };
+            await unlink(join(this.#typeFolder, `${type}.json`));
         });
     }
-    async function listResources() {
-        const declarationEntries = await readDirectory(typeFolder);
-        const resources = [];
-        for (const entry of declarationEntries) {
-            if (!entry.isFile() || !entry.name.endsWith(".json"))
-                continue;
-            resources.push(...await listTypeResources(entry.name.slice(0, -".json".length)));
-        }
-        resources.push(...await listResourceFolder("_blobs"));
-        resources.sort((left, right) => left.uri < right.uri ? -1 : left.uri > right.uri ? 1 : 0);
-        return resources;
-    }
-    async function getResourceMetadata(uri) {
-        const typeMatch = typeUriPattern.exec(uri);
-        const type = typeMatch?.[1];
-        if (type !== undefined) {
-            const declaration = await readValidDeclaration(typeFolder, type);
-            return declaration === undefined ? undefined : declarationResource(type, declaration);
-        }
-        const blobName = BLOB_URI_PATTERN.exec(uri)?.[1];
-        if (blobName !== undefined) {
-            const size = await regularFileSize(join(blobFolder, blobName), MAX_BLOB_BYTES);
-            return size === undefined ? undefined : {
-                uri,
-                name: `_blobs/${blobName}`,
-                mimeType: mimeTypeForBlob(blobName),
-                size,
-            };
-        }
-        const record = parseRecordUri(uri);
-        if (record === undefined)
-            return undefined;
-        const [declaration, stored] = await Promise.all([
-            readValidDeclaration(typeFolder, record.type),
-            readStoredRecord(recordPath(dataFolder, record.type, record.key)),
-        ]);
-        if (declaration === undefined || stored.status !== "found")
+    async #getBlob(uri) {
+        await this.#ensureReady();
+        const name = blobNameFromUri(uri);
+        if (name === undefined || !await isDirectory(this.#blobFolder))
             return undefined;
-        return recordResource(record.type, record.key, declaration, stored.value);
+        const bytes = await readRegularFile(join(this.#blobFolder, name));
+        return bytes === undefined ? undefined : { bytes, mimeType: mimeTypeForBlob(name) };
     }
-    async function listTypeResources(type) {
-        if (!typeNamePattern.test(type))
-            return [];
-        const declaration = await readValidDeclaration(typeFolder, type);
-        if (declaration === undefined)
-            return [];
-        const resources = [declarationResource(type, declaration)];
-        const recordEntries = await recognizedRecordEntries(join(dataFolder, type));
-        for (const entry of recordEntries) {
-            const key = entry.name.slice(0, -".json".length);
-            const stored = await readStoredRecord(join(dataFolder, type, entry.name));
-            if (stored.status !== "found")
-                continue;
-            resources.push(recordResource(type, key, declaration, stored.value));
-        }
-        return resources;
-    }
-    async function listResourceFolder(folder) {
-        if (folder === "_types") {
-            const declarationEntries = await readDirectory(typeFolder);
-            const resources = [];
-            for (const entry of declarationEntries) {
-                if (!entry.isFile() || !entry.name.endsWith(".json"))
-                    continue;
-                const type = entry.name.slice(0, -".json".length);
-                const resource = await getResourceMetadata(typeUri(type));
-                if (resource !== undefined)
-                    resources.push(resource);
-            }
-            return resources;
-        }
-        if (folder === "_blobs") {
-            const resources = [];
-            for (const entry of await readDirectory(blobFolder)) {
-                if (!entry.isFile() || !BLOB_NAME_PATTERN.test(entry.name))
-                    continue;
-                const resource = await getResourceMetadata(blobUri(entry.name));
-                if (resource !== undefined)
-                    resources.push(resource);
-            }
-            return resources;
-        }
-        if (!typeNamePattern.test(folder))
-            return [];
-        const recordPrefix = `autofile:///${folder}/`;
-        return (await listTypeResources(folder)).filter(({ uri }) => uri.startsWith(recordPrefix));
-    }
-    async function readResource(uri) {
-        const typeMatch = typeUriPattern.exec(uri);
-        const type = typeMatch?.[1];
-        if (type !== undefined) {
-            const declaration = await readValidDeclarationText(typeFolder, type);
-            if (declaration === undefined)
-                return undefined;
-            return { uri, mimeType: "application/json", text: declaration.text };
+    async #statBlob(uri) {
+        await this.#ensureReady();
+        const name = blobNameFromUri(uri);
+        if (name === undefined || !await isDirectory(this.#blobFolder))
+            return undefined;
+        const path = join(this.#blobFolder, name);
+        try {
+            const details = await lstat(path);
+            return details.isFile() ? { size: details.size, mimeType: mimeTypeForBlob(name), path } : undefined;
         }
-        const blobMatch = BLOB_URI_PATTERN.exec(uri);
-        const blobName = blobMatch?.[1];
-        if (blobName !== undefined) {
-            if (!await isDirectory(blobFolder))
-                return undefined;
-            const bytes = await readRegularFile(join(blobFolder, blobName), MAX_BLOB_BYTES);
-            if (bytes === undefined)
+        catch (error) {
+            if (hasCode(error, "ENOENT") || hasCode(error, "ENOTDIR"))
                 return undefined;
-            return { uri, mimeType: mimeTypeForBlob(blobName), blob: bytes.toString("base64") };
+            throw error;
         }
-        const record = parseRecordUri(uri);
-        if (record === undefined)
-            return undefined;
-        if (await readValidDeclaration(typeFolder, record.type) === undefined)
+    }
+    async #streamBlob(uri, range) {
+        await this.#ensureReady();
+        const name = blobNameFromUri(uri);
+        if (name === undefined || !await isDirectory(this.#blobFolder))
             return undefined;
-        const stored = await readStoredRecordText(recordPath(dataFolder, record.type, record.key));
-        if (stored.status !== "found")
+        // Read caller-controlled offsets before opening a file: an accessor may throw.
+        const start = range === undefined ? 0 : range?.start;
+        const requestedEnd = range?.end;
+        const file = await openRegularFile(join(this.#blobFolder, name));
+        if (file === undefined)
             return undefined;
-        return { uri, mimeType: "application/json", text: stored.text };
+        const end = range === undefined ? file.size : requestedEnd;
+        if (typeof start !== "number" || typeof end !== "number"
+            || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+            || start < 0 || end < start || end > file.size) {
+            await file.handle.close();
+            return refuse("range: must contain integer offsets with 0 <= start <= end <= blob size", uri);
+        }
+        return streamFile(file.handle, start, end);
     }
-    return {
-        findRecords,
-        getRecord,
-        createRecord,
-        updateRecord,
-        deleteRecord,
-        listTypes,
-        getType,
-        createType,
-        updateType,
-        deleteType,
-        listResources,
-        getResourceMetadata,
-        listResourceFolder,
-        listTypeResources,
-        readResource,
-    };
 }
-function declarationResource(type, declaration) {
-    return {
-        uri: typeUri(type),
-        name: `_types/${type}`,
-        mimeType: "application/json",
-        description: declaration.description,
-    };
+/** Copies one chunk before asynchronous writes can observe caller mutations. */
+async function* snapshotBlobChunks(chunks) {
+    for await (const chunk of chunks) {
+        if (!(chunk instanceof Uint8Array))
+            refuse("chunks: each chunk must be a Uint8Array");
+        yield Buffer.from(chunk);
+    }
 }
-function recordResource(type, key, declaration, stored) {
-    const title = declaration.titleField === undefined
-        ? undefined
-        : stored.value[declaration.titleField];
+function recordResult(type, key, declaration, stored) {
+    const title = declaration.titleField === undefined ? undefined : stored.value[declaration.titleField];
     return {
-        uri: recordUri(type, key),
-        name: `${type}/${key}`,
+        uri: recordUri(type, key), type, key,
         ...(typeof title === "string" ? { title } : {}),
-        mimeType: "application/json",
-        lastModified: stored.updatedAt,
+        ...stored,
     };
 }
+function typeResult(type, definition) {
+    return { uri: typeUri(type), type, ...definition };
+}
+function jsonText(value) { return `${JSON.stringify(value, null, 2)}\n`; }
+function readTypeTitle(input) {
+    // Read the descriptor so an accessor cannot run caller code or supply a value
+    // that JSON serialization would omit. Validation and snapshotting stay synchronous.
+    const descriptor = Object.getOwnPropertyDescriptor(input, "title");
+    if (descriptor === undefined)
+        return undefined;
+    if (!("value" in descriptor) || !descriptor.enumerable) {
+        refuse("title: must be an enumerable data property");
+    }
+    return descriptor.value;
+}
+function snapshotSchema(schema) {
+    const problem = jsonObjectProblem(schema);
+    if (problem !== undefined)
+        refuse(`schema: ${problem}`);
+    return JSON.parse(JSON.stringify(schema));
+}
 async function prepareDeclarationSchema(schema, uri) {
     try {
         return await prepareSchema(schema);
     }
     catch (error) {
         if (error instanceof SchemaRefusal) {
-            return { errors: error.messages.map((message) => ({ uri, message })) };
+            throw new AutofileError(error.messages.map((message) => ({ ...(uri === undefined ? {} : { uri }), message })));
         }
         throw error;
     }
@@ -736,57 +867,20 @@ async function missingLinkErrors(dataFolder, typeFolder, schema, value, sourceUr
     }
     return errors;
 }
-async function prepareRecordBlobs(blobFolder, schema, value, allowLocalPaths, uri) {
-    const materialized = structuredClone(value);
-    const preparedBlobs = new Map();
+async function missingBlobErrors(blobFolder, schema, value, uri) {
     const errors = [];
-    const visitedPointers = new Set();
+    const checked = new Map();
     for (const field of schema.formatFields(value, "blob")) {
-        if (visitedPointers.has(field.pointer))
-            continue;
-        visitedPointers.add(field.pointer);
         if (typeof field.value !== "string")
             continue;
-        const prepared = await prepareBlob(field.value, blobFolder, allowLocalPaths);
-        if ("message" in prepared) {
-            errors.push(formatFieldError(uri, field.location, prepared.message));
-            continue;
-        }
-        setValueAtPointer(materialized, field.pointer, prepared.uri);
-        preparedBlobs.set(prepared.uri, prepared);
-    }
-    if (errors.length > 0)
-        return { errors };
-    const validationErrors = await schema.validate(materialized);
-    if (validationErrors.length > 0) {
-        return { errors: validationErrors.map((message) => ({ uri, message })) };
-    }
-    const finalBlobs = new Map();
-    const finalPointers = new Set();
-    for (const field of schema.formatFields(materialized, "blob")) {
-        if (finalPointers.has(field.pointer))
-            continue;
-        finalPointers.add(field.pointer);
-        const fieldValue = typeof field.value === "string" ? field.value : undefined;
-        if (fieldValue === undefined || blobNameFromUri(fieldValue) === undefined) {
-            const message = "must hold a blob URI after storing";
-            errors.push(formatFieldError(uri, field.location, message));
-            continue;
-        }
-        let prepared = preparedBlobs.get(fieldValue);
-        if (prepared === undefined) {
-            const existing = await prepareBlob(fieldValue, blobFolder, false);
-            if ("message" in existing) {
-                errors.push(formatFieldError(uri, field.location, existing.message));
-                continue;
-            }
-            prepared = existing;
+        if (!checked.has(field.value)) {
+            checked.set(field.value, await blobReferenceProblem(blobFolder, field.value));
         }
-        finalBlobs.set(fieldValue, prepared);
+        const problem = checked.get(field.value);
+        if (problem !== undefined)
+            errors.push(formatFieldError(uri, field.location, problem));
     }
-    if (errors.length > 0)
-        return { errors };
-    return { value: materialized, blobs: [...finalBlobs.values()] };
+    return errors;
 }
 function formatFieldError(uri, location, message) {
     return { uri, message: location === "" ? message : `${location}: ${message}` };
@@ -805,7 +899,7 @@ async function deleteUnheldBlobs(dataFolder, typeFolder, candidates) {
     const held = await blobsHeldInStore(dataFolder, typeFolder);
     if (held === undefined)
         return;
-    await deleteBlobUris(join(dataFolder, "_blobs"), [...candidates].filter((uri) => !held.has(uri)));
+    await deleteBlobUris(join(dataFolder, "blobs"), [...candidates].filter((uri) => !held.has(uri)));
 }
 async function blobsHeldInStore(dataFolder, typeFolder) {
     const held = new Set();
@@ -833,13 +927,17 @@ async function blobsHeldInStore(dataFolder, typeFolder) {
         }
         let schema;
         if (declaration.status === "found") {
-            const prepared = await preparedDeclarationSchema(declaration.value, typeUri(type));
-            if (!("errors" in prepared))
-                schema = prepared;
+            try {
+                schema = await preparedDeclarationSchema(declaration.value, typeUri(type));
+            }
+            catch (error) {
+                if (!(error instanceof AutofileError))
+                    throw error;
+            }
         }
         let recordEntries;
         try {
-            recordEntries = await recognizedRecordEntries(join(dataFolder, type));
+            recordEntries = await recognizedRecordEntries(recordFolder(dataFolder, type));
         }
         catch (error) {
             if (hasErrorCode(error))
@@ -849,7 +947,7 @@ async function blobsHeldInStore(dataFolder, typeFolder) {
         for (const entry of recordEntries) {
             let record;
             try {
-                record = await readJsonText(join(dataFolder, type, entry.name), "record file");
+                record = await readJson(join(recordFolder(dataFolder, type), entry.name), "record");
             }
             catch (error) {
                 if (hasErrorCode(error))
@@ -891,33 +989,6 @@ function collectBlobUris(value, uris) {
             collectBlobUris(item, uris);
     }
 }
-function setValueAtPointer(value, pointer, replacement) {
-    const path = parseJsonPointer(pointer);
-    const field = path.at(-1);
-    if (field === undefined)
-        return;
-    let parent = value;
-    for (const part of path.slice(0, -1)) {
-        let next;
-        if (Array.isArray(parent))
-            next = parent[Number(part)];
-        else if (isJsonObject(parent))
-            next = parent[part];
-        if (next === undefined)
-            return;
-        parent = next;
-    }
-    if (Array.isArray(parent))
-        parent[Number(field)] = replacement;
-    else if (isJsonObject(parent)) {
-        Object.defineProperty(parent, field, {
-            value: replacement,
-            enumerable: true,
-            configurable: true,
-            writable: true,
-        });
-    }
-}
 async function recordExists(dataFolder, typeFolder, uri) {
     const parsed = parseRecordUri(uri);
     if (parsed === undefined)
@@ -928,10 +999,7 @@ async function recordExists(dataFolder, typeFolder, uri) {
     return stored.status === "found";
 }
 async function readValidDeclaration(typeFolder, type) {
-    return (await readValidDeclarationText(typeFolder, type))?.value;
-}
-async function readValidDeclarationText(typeFolder, type) {
-    const result = await readDeclarationText(typeFolder, type);
+    const result = await readDeclaration(typeFolder, type);
     if (result.status !== "found")
         return undefined;
     try {
@@ -942,15 +1010,22 @@ async function readValidDeclarationText(typeFolder, type) {
             return undefined;
         throw error;
     }
-    return { value: result.value, text: result.text };
+    return result.value;
 }
 async function invalidRecords(dataFolder, type, schema) {
     const errors = [];
-    const entries = await recognizedRecordEntries(join(dataFolder, type));
+    const entries = await recognizedRecordEntries(recordFolder(dataFolder, type));
     for (const entry of entries) {
         const key = entry.name.slice(0, -".json".length);
         const uri = recordUri(type, key);
-        const record = await readStoredRecord(join(dataFolder, type, entry.name));
+        let record;
+        try {
+            record = await readStoredRecord(join(recordFolder(dataFolder, type), entry.name));
+        }
+        catch (error) {
+            errors.push({ uri, message: recordReadError(error) });
+            continue;
+        }
         if (record.status !== "found") {
             errors.push({ uri, message: record.status === "invalid" ? record.message : "record does not exist" });
             continue;
@@ -962,60 +1037,42 @@ async function invalidRecords(dataFolder, type, schema) {
     return errors;
 }
 async function readDeclaration(folder, type) {
-    const result = await readDeclarationText(folder, type);
-    if (result.status !== "found")
-        return result;
-    return { status: "found", value: result.value };
-}
-async function readDeclarationText(folder, type) {
     if (!await isDirectory(folder))
         return { status: "missing" };
-    const result = await readJsonText(join(folder, `${type}.json`), "type declaration");
+    const result = await readJson(join(folder, `${type}.json`), "type declaration");
     if (result.status !== "found")
         return result;
-    if (!isTypeDeclaration(result.value)) {
+    if (!isTypeDefinition(result.value)) {
         return { status: "invalid", message: "type declaration is not valid" };
     }
-    return { status: "found", value: result.value, text: result.text };
-}
-async function readStoredRecord(path) {
-    const result = await readStoredRecordText(path);
-    if (result.status !== "found")
-        return result;
     return { status: "found", value: result.value };
 }
-async function readStoredRecordText(path) {
-    if (!await isDirectory(dirname(path)))
+async function readStoredRecord(path) {
+    if (!await isDirectory(dirname(dirname(path))) || !await isDirectory(dirname(path)))
         return { status: "missing" };
-    const result = await readJsonText(path, "record file");
+    const result = await readJson(path, "record");
     if (result.status !== "found")
         return result;
     if (!isStoredRecord(result.value)) {
-        return { status: "invalid", message: "record file does not contain a valid record" };
+        return { status: "invalid", message: "record is not valid" };
     }
-    return { status: "found", value: result.value, text: result.text };
+    return { status: "found", value: result.value };
 }
-async function readJsonText(path, label) {
+async function readJson(path, label) {
     const bytes = await readRegularFile(path);
     if (bytes === undefined)
         return { status: "missing" };
-    let text;
     try {
-        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        return { status: "found", value: JSON.parse(text) };
     }
     catch {
-        return { status: "invalid", message: `${label} is not valid UTF-8` };
-    }
-    try {
-        return { status: "found", value: JSON.parse(text), text };
-    }
-    catch {
-        return { status: "invalid", message: `${label} cannot be read as JSON` };
+        return { status: "invalid", message: `${label} is unavailable` };
     }
 }
 async function writeJsonAtomically(path, value) {
     const temporaryPath = join(dirname(path), `.${path.slice(path.lastIndexOf("/") + 1)}.${process.pid}.${randomUUID()}`);
-    const text = `${JSON.stringify(value, null, 2)}\n`;
+    const text = jsonText(value);
     try {
         await writeFile(temporaryPath, text, { encoding: "utf8", flag: "wx" });
         await rename(temporaryPath, path);
@@ -1067,34 +1124,33 @@ function nextTid() {
     }
     return tid;
 }
-/** Returns whether a string is the canonical URI of an Autofile resource. */
-export function isResourceUri(uri) {
-    return parseRecordUri(uri) !== undefined
-        || typeUriPattern.test(uri)
-        || BLOB_URI_PATTERN.test(uri);
-}
 function parseRecordUri(uri) {
+    if (typeof uri !== "string")
+        return undefined;
     const match = recordUriPattern.exec(uri);
     if (match === null || match[1] === undefined || match[2] === undefined)
         return undefined;
     return { type: match[1], key: match[2] };
 }
 function recordUri(type, key) {
-    return `autofile:///${type}/${key}`;
+    return `autofile:///records/${type}/${key}`;
 }
 function typeUri(type) {
-    return `autofile:///_types/${type}`;
+    return `autofile:///types/${type}`;
 }
 function mimeTypeForBlob(name) {
     return lookupMimeType(name) || "application/octet-stream";
 }
 function recordPath(dataFolder, type, key) {
-    return join(dataFolder, type, `${key}.json`);
+    return join(recordFolder(dataFolder, type), `${key}.json`);
+}
+function recordFolder(dataFolder, type) {
+    return join(dataFolder, "records", type);
 }
 function encodeRecordCursor(uri) {
     return Buffer.from(uri, "utf8").toString("base64url");
 }
-function decodeRecordCursor(cursor, type) {
+function decodeRecordCursor(cursor, types) {
     if (!/^[A-Za-z0-9_-]+$/u.test(cursor))
         return undefined;
     const bytes = Buffer.from(cursor, "base64url");
@@ -1108,7 +1164,7 @@ function decodeRecordCursor(cursor, type) {
         return undefined;
     }
     const record = parseRecordUri(uri);
-    return record?.type === type ? uri : undefined;
+    return record !== undefined && (types === undefined || types.includes(record.type)) ? uri : undefined;
 }
 function findWhereRefusal(value) {
     if (Array.isArray(value)) {
@@ -1133,11 +1189,23 @@ function findWhereRefusal(value) {
     }
     return undefined;
 }
-function recordFileReadError(error) {
-    const code = error instanceof Error && "code" in error && typeof error.code === "string"
-        ? `: ${error.code}`
-        : "";
-    return `record file cannot be read${code}`;
+function recordReadError(_error) {
+    return "record is unavailable";
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function reportSubscriptionError(subscription, error) {
+    if (subscription.onError === undefined)
+        process.emitWarning(error);
+    else {
+        try {
+            subscription.onError(error);
+        }
+        catch (failure) {
+            process.emitWarning(toError(failure));
+        }
+    }
 }
 function stringValuesContainWords(value, words) {
     if (words.length === 0)
@@ -1219,7 +1287,7 @@ function timestampAfter(previous) {
     return new Date(Math.max(Date.now(), new Date(previous).valueOf() + 1)).toISOString();
 }
 function refuse(message, uri) {
-    return { errors: [{ ...(uri === undefined ? {} : { uri }), message }] };
+    throw new AutofileError([{ ...(uri === undefined ? {} : { uri }), message }]);
 }
 function declarationRefusal(type, result) {
     const uri = typeUri(type);
@@ -1237,6 +1305,8 @@ function recordReadRefusal(uri, result) {
     throw new Error("A found record is not a refusal");
 }
 async function recognizedRecordEntries(folder) {
+    if (!await isDirectory(dirname(folder)))
+        return [];
     return (await readDirectory(folder))
         .filter((entry) => {
         if (!entry.isFile() || !entry.name.endsWith(".json"))
@@ -1305,26 +1375,45 @@ async function openRegularFile(path) {
         throw error;
     }
 }
-async function regularFileSize(path, maximumBytes) {
-    const file = await openRegularFile(path);
-    if (file === undefined)
-        return undefined;
-    try {
-        return file.size <= maximumBytes ? file.size : undefined;
-    }
-    finally {
-        await file.handle.close();
-    }
+/** Keeps a file open only while a bounded, backpressured read is active. */
+function streamFile(handle, start, end) {
+    let position = start;
+    let closing;
+    const close = () => closing ??= handle.close().catch(() => { throw new Error("Storage operation failed"); });
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                if (position === end) {
+                    await close();
+                    controller.close();
+                    return;
+                }
+                const bytes = Buffer.allocUnsafe(Math.min(64 * 1024, end - position));
+                const { bytesRead } = await handle.read(bytes, 0, bytes.length, position);
+                if (closing !== undefined)
+                    return;
+                if (bytesRead === 0) {
+                    await close();
+                    controller.close();
+                    return;
+                }
+                position += bytesRead;
+                controller.enqueue(bytes.subarray(0, bytesRead));
+            }
+            catch {
+                await close();
+                controller.error(new Error("Storage operation failed"));
+            }
+        },
+        cancel: () => close(),
+    });
 }
-async function readRegularFile(path, maximumBytes = Number.POSITIVE_INFINITY) {
+async function readRegularFile(path) {
     const file = await openRegularFile(path);
     if (file === undefined)
         return undefined;
     try {
-        if (file.size > maximumBytes)
-            return undefined;
-        const bytes = await file.handle.readFile();
-        return bytes.byteLength <= maximumBytes ? bytes : undefined;
+        return await file.handle.readFile();
     }
     finally {
         await file.handle.close();
@@ -1341,14 +1430,17 @@ async function pathExists(path) {
         throw error;
     }
 }
-function isTypeDeclaration(value) {
+function isTypeDefinition(value) {
     if (!isJsonObject(value))
         return false;
-    if (Object.keys(value).some((key) => !["description", "titleField", "schema"].includes(key))) {
+    if (Object.keys(value).some((key) => !["description", "title", "titleField", "schema"].includes(key))) {
         return false;
     }
     if (typeof value.description !== "string" || !isJsonObject(value.schema))
         return false;
+    if (value.title !== undefined && (typeof value.title !== "string" || value.title.length === 0)) {
+        return false;
+    }
     return value.titleField === undefined || typeof value.titleField === "string";
 }
 function isStoredRecord(value) {