@mearl/client 2.20.6 → 2.21.0

package/dist/pluginStateDefinition.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { Ajv } from 'ajv';
+const validators = new WeakMap();
+export function compilePluginStateSchema(schema) {
+    let validate = validators.get(schema);
+    if (!validate) {
+        validate = new Ajv({ strict: true }).compile(schema);
+        validators.set(schema, validate);
+    }
+    return validate;
+}
+export function normalizePluginState(value) {
+    if (value === undefined)
+        return;
+    const declaration = JSON.parse(JSON.stringify(value));
+    if (!declaration ||
+        declaration.version !== 1 ||
+        !declaration.collections ||
+        Array.isArray(declaration.collections) ||
+        Object.keys(declaration.collections).length > 32 ||
+        Buffer.byteLength(JSON.stringify(declaration)) > 128 * 1024)
+        throw new Error('Invalid stateStorage declaration');
+    for (const [name, collection] of Object.entries(declaration.collections)) {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) ||
+            !collection ||
+            !['installation', 'host', 'browser-session', 'instance'].includes(collection.scope) ||
+            !['persistent', 'cache', 'memory'].includes(collection.storage) ||
+            !Number.isSafeInteger(collection.schemaVersion) ||
+            collection.schemaVersion < 1 ||
+            !collection.schema ||
+            typeof collection.schema !== 'object' ||
+            Array.isArray(collection.schema) ||
+            collection.schema.$async)
+            throw new Error(`Invalid state collection: ${name}`);
+        if (['browser-session', 'instance'].includes(collection.scope) &&
+            !['cache', 'memory'].includes(collection.storage))
+            throw new Error('Document state requires cache or memory storage');
+        if (collection.storage === 'memory' &&
+            !['browser-session', 'instance'].includes(collection.scope))
+            throw new Error('Memory state requires a browser session or instance scope');
+        if (collection.maxEntries !== undefined &&
+            (!Number.isSafeInteger(collection.maxEntries) ||
+                collection.maxEntries < 1 ||
+                collection.maxEntries > 4096))
+            throw new Error('State maxEntries must be between 1 and 4096');
+        if (collection.maxBytes !== undefined &&
+            (!Number.isSafeInteger(collection.maxBytes) ||
+                collection.maxBytes < 1 ||
+                collection.maxBytes > (collection.storage === 'memory' ? 128 : 16) * 1024 * 1024))
+            throw new Error('State maxBytes exceeds its storage limit');
+        if (collection.ttlMs !== undefined &&
+            (!Number.isSafeInteger(collection.ttlMs) ||
+                collection.ttlMs < 1 ||
+                collection.ttlMs > 7 * 86400000))
+            throw new Error('State TTL must be between 1 ms and 7 days');
+        if (collection.storage === 'persistent' && collection.ttlMs !== undefined)
+            throw new Error('Persistent state does not accept TTL');
+        compilePluginStateSchema(collection.schema);
+    }
+    return declaration;
+}
+export function pluginStateSignature(collection) {
+    return createHash('sha256')
+        .update(JSON.stringify(collection, (_key, value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : value))
+        .digest('hex');
+}

package/dist/pluginStateManager.d.ts

@@ -0,0 +1,24 @@
+import type { PluginRevision } from './pluginRevision.js';
+import { PluginStateStore } from './pluginStateStore.js';
+import type { PluginTaskManager, PluginTaskBridge } from './pluginTaskManager.js';
+import type { PluginOptions } from './plugin.js';
+import type { PluginPageTarget } from './generated-plugin-pages.js';
+export declare class PluginStateManager {
+    private readonly tasks;
+    readonly store: PluginStateStore;
+    private readonly descriptions;
+    private readonly pending;
+    private readonly controller;
+    resolveTarget?: (plugin: string, instanceId: unknown, bridge: PluginTaskBridge, options: PluginOptions) => Promise<{
+        target: PluginPageTarget;
+        assertActive(): void;
+    }>;
+    private readonly maintenance;
+    constructor(tasks: PluginTaskManager);
+    call(plugin: string, input: Record<string, unknown>, bridge: PluginTaskBridge, options?: PluginOptions, binding?: {
+        revision: PluginRevision;
+        signal?: AbortSignal;
+        expectedTarget?: PluginPageTarget;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}

package/dist/pluginStateManager.js

@@ -0,0 +1,132 @@
+import { pluginStateSignature } from './pluginStateDefinition.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findPluginRegistration } from './pluginRegistry.js';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { capturePluginRevision } from './pluginRevision.js';
+import { PluginStateStore } from './pluginStateStore.js';
+export class PluginStateManager {
+    tasks;
+    store = new PluginStateStore();
+    descriptions = new Map();
+    pending = new Set();
+    controller = new AbortController();
+    resolveTarget;
+    maintenance;
+    constructor(tasks) {
+        this.tasks = tasks;
+        this.store.prune();
+        this.maintenance = setInterval(() => {
+            try {
+                this.store.prune();
+            }
+            catch (error) {
+                console.error('Plugin cache maintenance failed:', error);
+            }
+        }, 60000);
+        this.maintenance.unref();
+    }
+    async call(plugin, input, bridge, options = {}, binding) {
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        if (!/^[a-z][a-z0-9-]*$/.test(plugin) ||
+            (bridge.scope.plugin && bridge.scope.plugin !== plugin) ||
+            !input ||
+            typeof input !== 'object' ||
+            Array.isArray(input))
+            throw new Error('Invalid plugin state scope');
+        const revision = binding?.revision ?? capturePluginRevision(plugin);
+        const id = `${revision.installationId}/${revision.revision}`;
+        let description = this.descriptions.get(id);
+        if (!description) {
+            if (this.descriptions.size >= 64)
+                this.descriptions.delete(this.descriptions.keys().next().value);
+            const release = this.tasks.pinRevision(revision);
+            description = this.tasks
+                .describeRevision(revision, this.controller.signal, { cache: true })
+                .finally(release);
+            this.descriptions.set(id, description);
+            this.pending.add(description);
+            void description.finally(() => this.pending.delete(description)).catch(() => { });
+            void description.catch(() => {
+                if (this.descriptions.get(id) === description)
+                    this.descriptions.delete(id);
+            });
+        }
+        const declaration = (await description).stateStorage;
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        const name = String(input.collection ?? '');
+        const definition = declaration && Object.hasOwn(declaration.collections, name)
+            ? declaration.collections[name]
+            : undefined;
+        if (!definition || !/^[a-z][a-z0-9-]{0,63}$/.test(name))
+            throw Object.assign(new Error('Plugin state collection is not declared'), {
+                code: 'PLUGIN_STATE_NOT_DECLARED',
+            });
+        if (input.expectedDeclaration !== undefined &&
+            input.expectedDeclaration !== pluginStateSignature(definition))
+            throw Object.assign(new Error('Plugin state declaration changed during command execution'), {
+                code: 'PLUGIN_STATE_REVISION_CHANGED',
+            });
+        let scope = definition.scope;
+        let assertScope = () => { };
+        if (definition.scope === 'host')
+            scope += `:${this.tasks.host.hostId}`;
+        if (definition.scope === 'instance' || definition.scope === 'browser-session') {
+            if (!this.resolveTarget)
+                throw new Error('Page state scope is unavailable');
+            const resolved = await this.resolveTarget(plugin, input.instanceId, bridge, options);
+            const target = resolved.target;
+            const expected = binding?.expectedTarget;
+            if (expected &&
+                (target.browserSessionId !== expected.browserSessionId ||
+                    target.tabId !== expected.tabId ||
+                    target.frameId !== expected.frameId ||
+                    target.documentId !== expected.documentId))
+                throw Object.assign(new Error('State access cannot change the inherited document'), {
+                    code: 'PLUGIN_PAGE_TARGET_CHANGED',
+                });
+            assertScope = resolved.assertActive;
+            scope +=
+                definition.scope === 'instance'
+                    ? `:${String(input.instanceId)}`
+                    : `:${target.browserSessionId}`;
+        }
+        // No await occurs between the final target check and the atomic store operation.
+        this.controller.signal.throwIfAborted();
+        binding?.signal?.throwIfAborted();
+        let installation;
+        try {
+            installation = JSON.parse(readFileSync(join(pluginHostPaths().installations, `${plugin}.json`), 'utf8'));
+        }
+        catch {
+            /* Removed installations have no writable state scope. */
+        }
+        if (!findPluginRegistration(plugin) || installation?.installationId !== revision.installationId)
+            throw Object.assign(new Error('Plugin state installation was removed or replaced'), {
+                code: 'PLUGIN_STATE_SCOPE_ENDED',
+            });
+        assertScope();
+        const namespace = { installationId: revision.installationId, collection: name, scope };
+        switch (input.operation) {
+            case 'get':
+                return this.store.get(namespace, definition, input.key);
+            case 'get-many':
+                return this.store.getMany(namespace, definition, input.keys);
+            case 'list':
+                return this.store.list(namespace, definition, input);
+            case 'transact':
+                return this.store.transact(namespace, definition, input.transaction);
+            default:
+                throw new Error('Invalid state operation');
+        }
+    }
+    async close() {
+        clearInterval(this.maintenance);
+        this.controller.abort();
+        this.descriptions.clear();
+        this.store.clearMemory();
+        await Promise.allSettled([...this.pending]);
+    }
+}

package/dist/pluginStateStore.d.ts

@@ -0,0 +1,57 @@
+import type { PluginStateCollection, PluginStateEntry, PluginStateTransaction } from './generated-plugin-state.js';
+export interface PluginStateNamespace {
+    installationId: string;
+    collection: string;
+    scope: string;
+}
+/** A collection namespace is one atomic record, including CAS and commit receipts. */
+export declare class PluginStateStore {
+    readonly directory: string;
+    private readonly now;
+    private readonly memory;
+    private memoryBytes;
+    private memoryRevisionFloor;
+    clearMemory(): void;
+    private readonly valueBytes;
+    private memorySize;
+    private saveMemory;
+    constructor(directory?: string, now?: () => number);
+    private path;
+    private read;
+    private entry;
+    discardScope(installationId: string, scope: string): void;
+    prune(skipFile?: string): void;
+    get(namespace: PluginStateNamespace, definition: PluginStateCollection, name: string): {
+        revision: number;
+        schemaVersion: number;
+        key: string;
+        exists: boolean;
+        version: string;
+        value?: unknown;
+        expiresAt?: number;
+    };
+    getMany(namespace: PluginStateNamespace, definition: PluginStateCollection, names: unknown): {
+        entries: PluginStateEntry[];
+        revision: number;
+        schemaVersion: number;
+    };
+    list(namespace: PluginStateNamespace, definition: PluginStateCollection, input?: {
+        cursor?: string;
+        limit?: number;
+        expectedRevision?: number;
+    }): {
+        nextCursor?: string | undefined;
+        entries: PluginStateEntry[];
+        revision: number;
+        schemaVersion: number;
+    };
+    transact(namespace: PluginStateNamespace, definition: PluginStateCollection, input: PluginStateTransaction): {
+        revision: number;
+        schemaVersion: number;
+        reused: boolean;
+    } | {
+        revision: number;
+        schemaVersion: number;
+        reused?: undefined;
+    };
+}

package/dist/pluginStateStore.js

@@ -0,0 +1,396 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { pluginHostPaths } from './pluginHostPaths.js';
+import { writePluginHostFile } from './pluginHostFiles.js';
+import { compilePluginStateSchema } from './pluginStateDefinition.js';
+function fail(code, message) {
+    throw Object.assign(new Error(message), { code });
+}
+function schemaHash(definition) {
+    return createHash('sha256')
+        .update(JSON.stringify({ schema: definition.schema, storage: definition.storage }, (_key, value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : value))
+        .digest('hex');
+}
+function key(value) {
+    if (typeof value !== 'string' ||
+        !value.length ||
+        Buffer.byteLength(value) > 512 ||
+        ['__proto__', 'constructor', 'prototype'].includes(value))
+        fail('PLUGIN_STATE_INVALID', 'Invalid state key');
+}
+/** A collection namespace is one atomic record, including CAS and commit receipts. */
+export class PluginStateStore {
+    directory;
+    now;
+    memory = new Map();
+    memoryBytes = 0;
+    memoryRevisionFloor = 0;
+    clearMemory() {
+        this.memory.clear();
+        this.memoryBytes = 0;
+        this.memoryRevisionFloor = 0;
+    }
+    valueBytes = new WeakMap();
+    memorySize(document) {
+        let bytes = Buffer.byteLength(JSON.stringify({ ...document, entries: {} }));
+        let count = 0;
+        for (const [name, entry] of Object.entries(document.entries)) {
+            let valueBytes = typeof entry.value === 'object' && entry.value !== null
+                ? this.valueBytes.get(entry.value)
+                : undefined;
+            if (valueBytes === undefined) {
+                valueBytes = Buffer.byteLength(JSON.stringify(entry.value));
+                if (typeof entry.value === 'object' && entry.value !== null)
+                    this.valueBytes.set(entry.value, valueBytes);
+            }
+            bytes +=
+                Buffer.byteLength(JSON.stringify(name)) +
+                    1 +
+                    Buffer.byteLength(JSON.stringify({ ...entry, value: null })) -
+                    4 +
+                    valueBytes +
+                    (count++ ? 1 : 0);
+        }
+        return bytes;
+    }
+    saveMemory(path, document, bytes = this.memorySize(document)) {
+        const total = this.memoryBytes - (this.memory.get(path)?.bytes ?? 0) + bytes;
+        if (total > 128 * 1024 * 1024 || (!this.memory.has(path) && this.memory.size >= 512))
+            fail('PLUGIN_STATE_QUOTA', 'Memory state exceeds its host limits');
+        this.memory.set(path, { document, bytes });
+        this.memoryBytes = total;
+    }
+    constructor(directory = pluginHostPaths().state, now = Date.now) {
+        this.directory = directory;
+        this.now = now;
+    }
+    path(namespace) {
+        if (!/^[a-f0-9-]{36}$/i.test(namespace.installationId) ||
+            !/^[a-z][a-z0-9-]{0,63}$/.test(namespace.collection))
+            fail('PLUGIN_STATE_INVALID', 'Invalid state namespace');
+        const id = createHash('sha256').update(namespace.scope).digest('hex');
+        return join(this.directory, namespace.installationId, `${namespace.collection}-${id}.json`);
+    }
+    read(namespace, definition) {
+        try {
+            const file = this.path(namespace);
+            const saved = this.memory.get(file);
+            if ((definition.storage !== 'memory' && saved) ||
+                (definition.storage === 'memory' && !saved && existsSync(file)))
+                fail('PLUGIN_STATE_STORAGE_CHANGED', 'Switching between memory and disk state requires a new collection or namespace');
+            if (definition.storage === 'memory' && !saved) {
+                if (this.memory.size >= 512) {
+                    // Retiring empty collections advances absence versions so stale CAS cannot be reused.
+                    this.memoryRevisionFloor =
+                        Math.max(this.memoryRevisionFloor, ...[...this.memory.values()].map(entry => entry.document.revision)) + 1;
+                    for (const [path, entry] of this.memory)
+                        if (!Object.keys(entry.document.entries).length) {
+                            this.memory.delete(path);
+                            this.memoryBytes -= entry.bytes;
+                        }
+                }
+                throw Object.assign(new Error('Not found'), { code: 'ENOENT' });
+            }
+            const document = saved
+                ? { ...saved.document, entries: { ...saved.document.entries } }
+                : JSON.parse(readFileSync(file, 'utf8'));
+            if (!Number.isSafeInteger(document.revision) ||
+                !Number.isSafeInteger(document.schemaVersion) ||
+                !document.entries ||
+                !Array.isArray(document.commits))
+                throw new Error('Invalid state document');
+            if (definition.storage !== 'persistent') {
+                const entries = Object.fromEntries(Object.entries(document.entries).filter(([, entry]) => entry.expiresAt === undefined || entry.expiresAt > this.now()));
+                if (Object.keys(entries).length !== Object.keys(document.entries).length) {
+                    document.entries = entries;
+                    document.revision++;
+                    if (definition.storage === 'memory')
+                        this.saveMemory(file, document);
+                    else
+                        writePluginHostFile(file, JSON.stringify(document));
+                }
+            }
+            return document;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return {
+                revision: definition.storage === 'memory' ? this.memoryRevisionFloor : 0,
+                schemaVersion: definition.schemaVersion,
+                schemaHash: schemaHash(definition),
+                storage: definition.storage,
+                scope: namespace.scope,
+                entries: {},
+                commits: [],
+            };
+        }
+    }
+    entry(document, name, now) {
+        const entry = Object.hasOwn(document.entries, name) ? document.entries[name] : undefined;
+        return entry && (entry.expiresAt === undefined || entry.expiresAt > now)
+            ? {
+                key: name,
+                exists: true,
+                version: `v:${entry.revision}`,
+                value: document.storage === 'memory' ? structuredClone(entry.value) : entry.value,
+                ...(entry.expiresAt === undefined ? {} : { expiresAt: entry.expiresAt }),
+            }
+            : { key: name, exists: false, version: `a:${document.revision}` };
+    }
+    discardScope(installationId, scope) {
+        if (!/^[a-f0-9-]{36}$/i.test(installationId) || !scope.startsWith('instance:pi_'))
+            throw new Error('Only ended instance scopes can be discarded');
+        const directory = join(this.directory, installationId);
+        const memorySuffix = `-${createHash('sha256').update(scope).digest('hex')}.json`;
+        for (const [path, entry] of this.memory)
+            if (path.startsWith(directory + sep) && path.endsWith(memorySuffix)) {
+                this.memory.delete(path);
+                this.memoryBytes -= entry.bytes;
+            }
+        const suffix = `-${createHash('sha256').update(scope).digest('hex')}.json`;
+        let names;
+        try {
+            names = readdirSync(directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const name of names)
+            if (name.endsWith(suffix))
+                rmSync(join(directory, name), { force: true });
+    }
+    prune(skipFile) {
+        for (const [path, saved] of this.memory) {
+            const document = { ...saved.document, entries: { ...saved.document.entries } };
+            for (const [key, entry] of Object.entries(document.entries))
+                if (entry.expiresAt !== undefined && entry.expiresAt <= this.now())
+                    delete document.entries[key];
+            if (Object.keys(document.entries).length === Object.keys(saved.document.entries).length)
+                continue;
+            document.revision++;
+            this.saveMemory(path, document);
+        }
+        let installations;
+        try {
+            installations = readdirSync(this.directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const installation of installations) {
+            if (!/^[a-f0-9-]{36}$/i.test(installation))
+                continue;
+            for (const name of readdirSync(join(this.directory, installation))) {
+                if (!name.endsWith('.json'))
+                    continue;
+                const file = join(this.directory, installation, name);
+                if (file === skipFile)
+                    continue;
+                try {
+                    const document = JSON.parse(readFileSync(file, 'utf8'));
+                    if (document.storage !== 'cache')
+                        continue;
+                    const entries = Object.fromEntries(Object.entries(document.entries).filter(([, value]) => value.expiresAt === undefined || value.expiresAt > this.now()));
+                    if (Object.keys(entries).length === Object.keys(document.entries).length)
+                        continue;
+                    writePluginHostFile(file, JSON.stringify({ ...document, revision: document.revision + 1, entries }));
+                }
+                catch (error) {
+                    console.error(`Cannot maintain plugin cache ${file}:`, error);
+                }
+            }
+        }
+    }
+    get(namespace, definition, name) {
+        key(name);
+        const document = this.read(namespace, definition);
+        return {
+            ...this.entry(document, name, this.now()),
+            revision: document.revision,
+            schemaVersion: document.schemaVersion,
+        };
+    }
+    getMany(namespace, definition, names) {
+        if (!Array.isArray(names) ||
+            names.length < 1 ||
+            names.length > 128 ||
+            new Set(names).size !== names.length)
+            fail('PLUGIN_STATE_INVALID', 'Expected 1 to 128 unique state keys');
+        names.forEach(name => key(name));
+        const document = this.read(namespace, definition), now = this.now();
+        const entries = names.map(name => this.entry(document, name, now));
+        if (Buffer.byteLength(JSON.stringify(entries)) > 1024 * 1024)
+            fail('PLUGIN_STATE_RESPONSE_TOO_LARGE', 'State batch exceeds 1 MiB; read fewer keys');
+        return { entries, revision: document.revision, schemaVersion: document.schemaVersion };
+    }
+    list(namespace, definition, input = {}) {
+        const document = this.read(namespace, definition);
+        const limit = input.limit ?? 100;
+        if (!Number.isSafeInteger(limit) ||
+            limit < 1 ||
+            limit > 200 ||
+            (input.cursor !== undefined && typeof input.cursor !== 'string'))
+            fail('PLUGIN_STATE_INVALID', 'Invalid state list cursor or limit');
+        if (input.expectedRevision !== undefined && input.expectedRevision !== document.revision)
+            fail('PLUGIN_STATE_CONFLICT', 'State list changed; restart pagination');
+        const now = this.now();
+        const candidates = Object.keys(document.entries)
+            .sort()
+            .filter(name => (input.cursor === undefined || name > input.cursor) &&
+            this.entry(document, name, now).exists);
+        const entries = [];
+        let bytes = 0;
+        for (const name of candidates) {
+            const entry = this.entry(document, name, now), size = Buffer.byteLength(JSON.stringify(entry));
+            if (entries.length && (entries.length >= limit || bytes + size > 256 * 1024))
+                break;
+            entries.push(entry);
+            bytes += size;
+        }
+        return {
+            entries,
+            revision: document.revision,
+            schemaVersion: document.schemaVersion,
+            ...(entries.length < candidates.length ? { nextCursor: entries.at(-1).key } : {}),
+        };
+    }
+    transact(namespace, definition, input) {
+        if (!input ||
+            !Array.isArray(input.operations) ||
+            input.operations.length > 128 ||
+            Buffer.byteLength(JSON.stringify(input)) > 512 * 1024)
+            fail('PLUGIN_STATE_INVALID', 'State transaction exceeds its limits');
+        const document = this.read(namespace, definition);
+        const hash = createHash('sha256')
+            .update(JSON.stringify({
+            input,
+            schemaVersion: definition.schemaVersion,
+            schema: definition.schema,
+        }))
+            .digest('hex');
+        if (input.idempotencyKey !== undefined) {
+            if (typeof input.idempotencyKey !== 'string' ||
+                !input.idempotencyKey.length ||
+                input.idempotencyKey.length > 128)
+                fail('PLUGIN_STATE_INVALID', 'Invalid transaction idempotency key');
+            const existing = document.commits.find(item => item.id === input.idempotencyKey);
+            if (existing) {
+                if (existing.hash !== hash)
+                    fail('PLUGIN_STATE_IDEMPOTENCY_CONFLICT', 'Transaction key refers to different data or schema');
+                return { revision: existing.revision, schemaVersion: document.schemaVersion, reused: true };
+            }
+        }
+        if (input.expectedRevision !== undefined && input.expectedRevision !== document.revision)
+            fail('PLUGIN_STATE_CONFLICT', 'Collection revision changed');
+        if (document.schemaVersion === definition.schemaVersion &&
+            document.schemaHash !== schemaHash(definition))
+            fail('PLUGIN_STATE_SCHEMA_VERSION_REQUIRED', 'Changing the state schema or storage policy requires a new schemaVersion');
+        if (document.schemaVersion > definition.schemaVersion)
+            fail('PLUGIN_STATE_SCHEMA_DOWNGRADE', 'An older plugin revision cannot write a newer state schema');
+        if (document.schemaVersion !== definition.schemaVersion &&
+            (input.migrateFromVersion !== document.schemaVersion || input.expectedRevision === undefined))
+            fail('PLUGIN_STATE_MIGRATION_REQUIRED', 'Schema migration requires the previous schema version and collection revision');
+        if (input.migrateFromVersion !== undefined &&
+            input.migrateFromVersion !== document.schemaVersion)
+            fail('PLUGIN_STATE_CONFLICT', 'State schema changed');
+        const now = this.now(), names = new Set();
+        const entries = Object.fromEntries(Object.entries(document.entries)
+            .filter(([, value]) => value.expiresAt === undefined || value.expiresAt > now)
+            .map(([name, value]) => [name, { ...value }]));
+        const revision = document.revision + 1;
+        if (!Number.isSafeInteger(revision))
+            fail('PLUGIN_STATE_QUOTA', 'State revision limit reached');
+        if (document.storage !== definition.storage)
+            for (const entry of Object.values(entries)) {
+                entry.revision = revision;
+                if (definition.storage !== 'persistent')
+                    entry.expiresAt = now + (definition.ttlMs ?? 86400000);
+                else
+                    delete entry.expiresAt;
+            }
+        const validate = compilePluginStateSchema(definition.schema);
+        for (const operation of input.operations) {
+            key(operation.key);
+            if (names.has(operation.key) ||
+                !['put', 'delete'].includes(operation.type) ||
+                operation.expectedVersion !== this.entry(document, operation.key, now).version)
+                fail('PLUGIN_STATE_CONFLICT', 'State entry version changed or key repeated');
+            names.add(operation.key);
+            if (operation.type === 'delete') {
+                delete entries[operation.key];
+                continue;
+            }
+            if (!validate(operation.value) ||
+                Buffer.byteLength(JSON.stringify(operation.value)) > 256 * 1024)
+                fail('PLUGIN_STATE_SCHEMA_INVALID', 'State value does not match the declared schema or exceeds 256 KiB');
+            const ttl = operation.ttlMs ?? definition.ttlMs ?? 86400000;
+            if (definition.storage === 'persistent' && operation.ttlMs !== undefined)
+                fail('PLUGIN_STATE_INVALID', 'Persistent state does not accept TTL');
+            if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > 7 * 86400000)
+                fail('PLUGIN_STATE_INVALID', 'Invalid cache TTL');
+            entries[operation.key] = {
+                revision,
+                value: definition.storage === 'memory' ? structuredClone(operation.value) : operation.value,
+                ...(definition.storage !== 'persistent' ? { expiresAt: now + ttl } : {}),
+            };
+        }
+        for (const entry of Object.values(entries))
+            if (!validate(entry.value))
+                fail('PLUGIN_STATE_SCHEMA_INVALID', 'Migration leaves entries incompatible with the target schema');
+        const commit = {
+            revision,
+            schemaVersion: definition.schemaVersion,
+            schemaHash: schemaHash(definition),
+            storage: definition.storage,
+            scope: namespace.scope,
+            entries,
+            commits: [
+                ...document.commits,
+                ...(input.idempotencyKey ? [{ id: input.idempotencyKey, hash, revision }] : []),
+            ].slice(-64),
+        };
+        const content = definition.storage === 'memory' ? '' : JSON.stringify(commit);
+        const bytes = definition.storage === 'memory' ? this.memorySize(commit) : Buffer.byteLength(content);
+        if (Object.keys(entries).length > (definition.maxEntries ?? 1024) ||
+            bytes > (definition.maxBytes ?? 8 * 1024 * 1024))
+            fail('PLUGIN_STATE_QUOTA', 'State collection quota exceeded');
+        const file = this.path(namespace);
+        if (definition.storage === 'memory') {
+            this.saveMemory(file, commit, bytes);
+            return { revision, schemaVersion: definition.schemaVersion };
+        }
+        let total = Buffer.byteLength(content);
+        try {
+            for (const name of readdirSync(join(this.directory, namespace.installationId))) {
+                const path = join(this.directory, namespace.installationId, name);
+                if (path !== file && name.endsWith('.json'))
+                    total += statSync(path).size;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (total > 64 * 1024 * 1024) {
+            this.prune(file);
+            total = Buffer.byteLength(content);
+            for (const name of readdirSync(join(this.directory, namespace.installationId))) {
+                const path = join(this.directory, namespace.installationId, name);
+                if (path !== file && name.endsWith('.json'))
+                    total += statSync(path).size;
+            }
+        }
+        if (total > 64 * 1024 * 1024)
+            fail('PLUGIN_STATE_QUOTA', 'Plugin state exceeds 64 MiB');
+        writePluginHostFile(file, content);
+        return { revision, schemaVersion: definition.schemaVersion };
+    }
+}