@lapis-notes/api 0.1.0 → 0.1.3

package/dist/registry-schema/catalog-v2.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { registryCatalogEntrySchema, registryCatalogDetailSchema, registryCatalogStatusSchema, registryImageReferenceSchema, registryReleaseSchema, registryReleaseChangelogSchema, } from "./catalog-v1.js";
+export { registryCatalogStatusSchema, registryImageReferenceSchema, registryReleaseChangelogSchema, };
+/** Authored variants remain optional; display fallbacks never rewrite metadata. */
+export const registryImageSetSchema = z
+    .object({
+    preview: registryImageReferenceSchema.optional(),
+    full: registryImageReferenceSchema.optional(),
+    light: registryImageReferenceSchema.optional(),
+    dark: registryImageReferenceSchema.optional(),
+})
+    .refine((images) => Object.values(images).some(Boolean), "At least one image variant is required");
+export const registryMediaV2Schema = z.object({
+    alt: z.string().min(1),
+    images: registryImageSetSchema,
+});
+export const registryGalleryV2Schema = registryMediaV2Schema.extend({
+    id: z.string().min(1),
+});
+export const registryAppearanceV2Schema = z.object({
+    icon: z.string().min(1),
+    accent: z.string().min(1),
+    logo: registryMediaV2Schema.optional(),
+});
+export const registryReleaseV2Schema = registryReleaseSchema.omit({
+    releaseEventId: true,
+    manifestSha256: true,
+    releaseSequence: true,
+});
+export const registryCatalogV2EntrySchema = registryCatalogEntrySchema.extend({
+    schemaVersion: z.literal(2).optional(),
+    appearance: registryAppearanceV2Schema.optional(),
+    links: registryCatalogDetailSchema.shape.links,
+});
+export const registryCatalogV2IndexSchema = z.object({
+    schemaVersion: z.literal(2),
+    generatedAt: z.string().datetime({ offset: true }),
+    plugins: z.array(registryCatalogV2EntrySchema),
+});
+export const registryCatalogV2DetailSchema = registryCatalogDetailSchema.extend({
+    schemaVersion: z.literal(2),
+    appearance: registryAppearanceV2Schema.optional(),
+    media: z
+        .object({
+        banner: registryMediaV2Schema.optional(),
+        overview: registryMediaV2Schema.optional(),
+    })
+        .optional(),
+    gallery: z.array(registryGalleryV2Schema).optional(),
+    versions: z.record(z.string().min(1), registryReleaseV2Schema),
+});
+export function resolveRegistryMedia(media, variant = "preview") {
+    const images = media.images;
+    const reference = images[variant] ??
+        images.full ??
+        images.light ??
+        images.dark ??
+        images.preview;
+    if (!reference)
+        throw new Error("Media has no usable image variant");
+    return reference;
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Expected registry object");
+    return value;
+}
+function appearance(value) {
+    if (value === undefined)
+        return undefined;
+    const result = record(value);
+    if (result.logo === undefined)
+        return result;
+    const logo = record(result.logo);
+    return {
+        ...result,
+        logo: logo.images ? logo : { alt: logo.alt, images: { full: logo } },
+    };
+}
+/** Call only after the source adapter has verified the original signed input. */
+export function normalizeRegistryCatalogEntry(value) {
+    const entry = record(value);
+    const author = entry.author ?? record(entry.owner ?? {}).name;
+    return registryCatalogV2EntrySchema.parse({
+        ...entry,
+        schemaVersion: 2,
+        appearance: appearance(entry.appearance),
+        status: entry.status ?? "active",
+        badges: entry.badges ?? [],
+        links: {
+            ...(entry.links ?? {}),
+            ...(!entry.links
+                ?.documentation && typeof entry.readmeUrl === "string"
+                ? { documentation: entry.readmeUrl }
+                : {}),
+        },
+        owner: entry.owner ?? {
+            name: author,
+            verified: entry.channel === "official",
+        },
+    });
+}
+export function normalizeRegistryCatalogIndex(value) {
+    const index = record(value);
+    if (index.schemaVersion !== 1 && index.schemaVersion !== 2)
+        throw new Error("Unsupported registry schema version");
+    if (!Array.isArray(index.plugins))
+        throw new Error("Expected registry plugin list");
+    return registryCatalogV2IndexSchema.parse({
+        ...index,
+        schemaVersion: 2,
+        plugins: index.plugins.map(normalizeRegistryCatalogEntry),
+    });
+}
+export function normalizeRegistryCatalogDetail(value) {
+    const detail = record(value);
+    if (detail.schemaVersion !== 1 && detail.schemaVersion !== 2)
+        throw new Error("Unsupported registry schema version");
+    const owner = record(detail.owner ?? {});
+    return registryCatalogV2DetailSchema.parse({
+        ...detail,
+        schemaVersion: 2,
+        author: detail.author ?? owner.name,
+        authorUrl: detail.authorUrl ?? owner.url,
+        status: detail.status ?? "active",
+        links: {
+            ...(detail.links ?? {}),
+            ...(!detail.links
+                ?.documentation && typeof detail.readmeUrl === "string"
+                ? { documentation: detail.readmeUrl }
+                : {}),
+        },
+        owner: { ...owner, verified: owner.verified ?? false },
+        appearance: appearance(detail.appearance),
+    });
+}
+export { registryChangelogFromMarkdown } from "./release-notes.js";

package/dist/registry-schema/index.d.ts

@@ -0,0 +1 @@
+export * from "./catalog-v2.js";

package/dist/registry-schema/index.js

@@ -0,0 +1 @@
+export * from "./catalog-v2.js";

package/dist/registry-schema/release-notes.d.ts

@@ -0,0 +1,5 @@
+export declare function registryChangelogFromMarkdown(name: string, version: string, markdown: string, override?: unknown): {
+    title: string;
+    description?: string | undefined;
+    tags?: ("security" | "fix" | "feature" | "improvement" | "breaking" | "deprecation" | "removal")[] | undefined;
+} | undefined;

package/dist/registry-schema/release-notes.js

@@ -0,0 +1,21 @@
+import { registryReleaseChangelogSchema } from "./catalog-v1.js";
+export function registryChangelogFromMarkdown(name, version, markdown, override) {
+    if (override !== undefined)
+        return registryReleaseChangelogSchema.parse(override);
+    const lines = markdown.split(/\r?\n/u);
+    const start = lines.findIndex((line) => {
+        const heading = /^##\s+\[?v?([^\]\s]+)\]?/u.exec(line);
+        return heading?.[1] === version;
+    });
+    if (start < 0)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && /^##\s/u.test(line));
+    const description = lines
+        .slice(start + 1, end < 0 ? undefined : end)
+        .join("\n")
+        .trim();
+    return registryReleaseChangelogSchema.parse({
+        title: `${name} ${version}`,
+        ...(description ? { description } : {}),
+    });
+}

package/dist/server-host.d.ts

@@ -0,0 +1,28 @@
+import type { VaultProfile } from "./storage/vault-state";
+export declare const LAPIS_SERVER_PROTOCOL_MAJOR = 1;
+export type ServerVaultRole = "owner" | "editor" | "viewer";
+export interface ServerVaultProfile extends VaultProfile {
+    kind: "server-hosted";
+    role: ServerVaultRole;
+    archived: boolean;
+}
+export interface ServerHostCapabilities {
+    appDatabase: true;
+    fileWatch: true;
+    languageService: true;
+    pluginAssets: true;
+    vaultResources: true;
+    ai: false;
+    terminal: false;
+    collaboration: false;
+    multiInstance: false;
+}
+export type ServerHostErrorCode = "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "PRECONDITION_FAILED" | "INVALID_PATH" | "PROTOCOL_MISMATCH" | "RESYNC_REQUIRED" | "RATE_LIMITED" | "INTERNAL";
+export declare class ServerHostError extends Error {
+    readonly code: ServerHostErrorCode;
+    readonly requestId?: string | undefined;
+    constructor(code: ServerHostErrorCode, message: string, requestId?: string | undefined);
+}
+export declare class VaultConflictError extends ServerHostError {
+    constructor(message?: string);
+}

package/dist/server-host.js

@@ -0,0 +1,17 @@
+export const LAPIS_SERVER_PROTOCOL_MAJOR = 1;
+export class ServerHostError extends Error {
+    code;
+    requestId;
+    constructor(code, message, requestId) {
+        super(message);
+        this.code = code;
+        this.requestId = requestId;
+        this.name = "ServerHostError";
+    }
+}
+export class VaultConflictError extends ServerHostError {
+    constructor(message = "The vault file changed before it could be saved") {
+        super("CONFLICT", message);
+        this.name = "VaultConflictError";
+    }
+}

package/dist/storage/app-database.d.ts

@@ -3,7 +3,7 @@ import { type SearchQueryEvaluationOptions, type SearchQueryTextRangeOptions } f
 import { type IndexProjectionDefinitionRecord, type IndexProjectionEdgeRecord, type IndexQuery, type IndexQueryResult, type IndexRelatedQuery, type IndexProjectionRowRecord, type IndexProjectionSourceRecord, type IndexProjectionValueRecord, type MarkProjectionSourceErrorInput, type ReplaceProjectionSourceInput } from "./index-projection";
 import { type AppDatabaseLinkKind, type AppDatabaseTaskChildQuery, type AppDatabaseTaskQuery, type AppDatabaseTaskRecord } from "./task-projection";
 export type { SearchEmbeddingProviderConfig, SearchEmbeddingRuntimeStatus, } from "./search-embedding-provider";
-export type RuntimeTarget = "web-pwa" | "deno-desktop" | "test";
+export type RuntimeTarget = "web-pwa" | "deno-desktop" | "deno-server" | "test";
 export interface LocalSearchQueryEnhancementProviderConfig {
     kind: "local-model";
     queryExpansionModelId: string;
@@ -79,7 +79,7 @@ export interface AppDatabaseSearchIndexStats {
 export declare function supportsSearchQueryEnhancementRuntime(runtimeTarget?: RuntimeTarget | null): boolean;
 export type AppDatabaseKind = "turso-wasm" | "turso-native" | "memory";
 export type AppDatabaseStorageMode = "local" | "synced" | "remote";
-export type AppDatabaseTransport = "native" | "wasm-worker" | "broadcast-proxy" | "memory";
+export type AppDatabaseTransport = "native" | "http-rpc" | "wasm-worker" | "broadcast-proxy" | "memory";
 export type AppDatabaseRole = "direct" | "owner" | "proxy" | "blocked" | "test";
 export interface AppDatabaseCapabilities {
     nativeFullTextSearch: boolean;
@@ -264,6 +264,37 @@ export interface AppDatabaseChangeSet {
     reset?: boolean;
     committedAt: number;
 }
+/** A namespaced application-metadata row returned without exposing storage. */
+export interface AppDatabaseMetaEntry<T = unknown> {
+    key: string;
+    value: T;
+}
+export interface AppDatabaseMetaScanQuery {
+    prefix: string;
+    after?: string;
+    limit?: number;
+}
+export interface AppDatabaseMetaScanPage<T = unknown> {
+    entries: AppDatabaseMetaEntry<T>[];
+    nextCursor?: string;
+}
+export interface AppDatabaseMetaCheck {
+    key: string;
+    exists?: boolean;
+    value?: unknown;
+}
+export interface AppDatabaseMetaMutation {
+    key: string;
+    value?: unknown;
+    delete?: boolean;
+}
+export interface AppDatabaseMetaTransaction {
+    checks?: AppDatabaseMetaCheck[];
+    mutations: AppDatabaseMetaMutation[];
+}
+export interface AppDatabaseMetaTransactionResult {
+    applied: boolean;
+}
 export type AppDatabaseChangeListener = (change: AppDatabaseChangeSet) => void;
 export interface SearchDocumentRecord {
     path: string;
@@ -591,6 +622,8 @@ export interface AppDatabase {
     getSearchIndexStats(): Promise<AppDatabaseSearchIndexStats>;
     getMeta<T = unknown>(key: string): Promise<T | undefined>;
     setMeta(key: string, value: unknown): Promise<void>;
+    scanMeta<T = unknown>(query: AppDatabaseMetaScanQuery): Promise<AppDatabaseMetaScanPage<T>>;
+    transactMeta(transaction: AppDatabaseMetaTransaction): Promise<AppDatabaseMetaTransactionResult>;
     getNotebookState(sourcePath: string): Promise<AppDatabaseNotebookState | undefined>;
     setNotebookState(sourcePath: string, state: AppDatabaseNotebookState): Promise<void>;
     deleteNotebookState(sourcePath: string): Promise<void>;
@@ -770,6 +803,8 @@ export declare class MemoryAppDatabase implements AppDatabase {
     getSearchIndexStats(): Promise<AppDatabaseSearchIndexStats>;
     getMeta<T = unknown>(key: string): Promise<T | undefined>;
     setMeta(key: string, value: unknown): Promise<void>;
+    scanMeta<T = unknown>({ prefix, after, limit, }: AppDatabaseMetaScanQuery): Promise<AppDatabaseMetaScanPage<T>>;
+    transactMeta({ checks, mutations, }: AppDatabaseMetaTransaction): Promise<AppDatabaseMetaTransactionResult>;
     getNotebookState(sourcePath: string): Promise<AppDatabaseNotebookState | undefined>;
     setNotebookState(sourcePath: string, state: AppDatabaseNotebookState): Promise<void>;
     deleteNotebookState(sourcePath: string): Promise<void>;

package/dist/storage/app-database.js

@@ -1047,9 +1047,49 @@ export class MemoryAppDatabase {
         return clone(this.meta[key]);
     }
     async setMeta(key, value) {
-        this.meta[key] = clone(value);
+        if (value === undefined)
+            delete this.meta[key];
+        else
+            this.meta[key] = clone(value);
         this.emitChange(["meta"]);
     }
+    async scanMeta({ prefix, after, limit = 100, }) {
+        const boundedLimit = Math.max(1, Math.min(500, Math.floor(limit)));
+        const keys = Object.keys(this.meta)
+            .filter((key) => key.startsWith(prefix) && (!after || key > after))
+            .sort();
+        const pageKeys = keys.slice(0, boundedLimit);
+        return {
+            entries: pageKeys.map((key) => ({
+                key,
+                value: clone(this.meta[key]),
+            })),
+            nextCursor: keys.length > pageKeys.length ? pageKeys.at(-1) : undefined,
+        };
+    }
+    async transactMeta({ checks = [], mutations, }) {
+        for (const check of checks) {
+            const exists = Object.prototype.hasOwnProperty.call(this.meta, check.key);
+            if (check.exists !== undefined && exists !== check.exists) {
+                return { applied: false };
+            }
+            if ("value" in check &&
+                JSON.stringify(this.meta[check.key]) !== JSON.stringify(check.value)) {
+                return { applied: false };
+            }
+        }
+        for (const mutation of mutations) {
+            if (mutation.delete || mutation.value === undefined) {
+                delete this.meta[mutation.key];
+            }
+            else {
+                this.meta[mutation.key] = clone(mutation.value);
+            }
+        }
+        if (mutations.length > 0)
+            this.emitChange(["meta"]);
+        return { applied: true };
+    }
     async getNotebookState(sourcePath) {
         return this.getMeta(notebookStateMetaKey(sourcePath));
     }

package/dist/storage/browser-coordinated-app-database.d.ts

@@ -1,4 +1,4 @@
-import type { AppDatabase, AppDatabaseChangeListener, AppDatabaseDescriptor, AppDatabaseFileHistory, AppDatabaseIndexedFile, AppDatabaseIndexedFileManifestPage, AppDatabaseIndexedFileManifestQuery, AppDatabaseIndexedMetadataPage, AppDatabaseIndexedMetadataPageQuery, AppDatabaseIndexedMetadataQuery, AppDatabaseIndexedMetadataRow, AppDatabaseKind, AppDatabaseMetadataFacetQuery, AppDatabaseMetadataFacetRow, AppDatabaseMetadataLinkQuery, AppDatabaseMemoryCandidateInput, AppDatabaseMemoryCandidateQuery, AppDatabaseMemoryCandidateResult, AppDatabaseMemoryJobClaimInput, AppDatabaseMemoryJobRecord, AppDatabaseMemoryJobUpdateInput, AppDatabaseMemoryRecallSignalRecord, AppDatabaseMemorySourceRecord, AppDatabaseProvider, AppDatabaseNotificationRecord, AppDatabaseSearchIndexStats, AppDatabaseNotebookState, AppDatabaseSearchOptions, AppDatabaseSearchResult, AppDatabaseStoreFileHistoryRevisionInput, AppDatabaseStoreFileHistoryRevisionResult, MetadataCacheSnapshot, SearchDocumentRecord, SearchDocumentManifestPage, SearchDocumentManifestQuery, SearchEmbeddingProviderConfig, SearchEmbeddingRuntimeStatus, AppDatabaseLinkRecord } from "./app-database";
+import type { AppDatabase, AppDatabaseChangeListener, AppDatabaseDescriptor, AppDatabaseFileHistory, AppDatabaseIndexedFile, AppDatabaseIndexedFileManifestPage, AppDatabaseIndexedFileManifestQuery, AppDatabaseIndexedMetadataPage, AppDatabaseIndexedMetadataPageQuery, AppDatabaseIndexedMetadataQuery, AppDatabaseIndexedMetadataRow, AppDatabaseKind, AppDatabaseMetadataFacetQuery, AppDatabaseMetadataFacetRow, AppDatabaseMetadataLinkQuery, AppDatabaseMemoryCandidateInput, AppDatabaseMemoryCandidateQuery, AppDatabaseMemoryCandidateResult, AppDatabaseMemoryJobClaimInput, AppDatabaseMemoryJobRecord, AppDatabaseMemoryJobUpdateInput, AppDatabaseMemoryRecallSignalRecord, AppDatabaseMemorySourceRecord, AppDatabaseMetaScanPage, AppDatabaseMetaScanQuery, AppDatabaseMetaTransaction, AppDatabaseMetaTransactionResult, AppDatabaseProvider, AppDatabaseNotificationRecord, AppDatabaseSearchIndexStats, AppDatabaseNotebookState, AppDatabaseSearchOptions, AppDatabaseSearchResult, AppDatabaseStoreFileHistoryRevisionInput, AppDatabaseStoreFileHistoryRevisionResult, MetadataCacheSnapshot, SearchDocumentRecord, SearchDocumentManifestPage, SearchDocumentManifestQuery, SearchEmbeddingProviderConfig, SearchEmbeddingRuntimeStatus, AppDatabaseLinkRecord } from "./app-database";
 import type { AppDatabaseTaskChildQuery, AppDatabaseTaskQuery, AppDatabaseTaskRecord } from "./task-projection";
 import { BrowserAppDatabaseCoordinator } from "./browser-app-database-coordination";
 export type BrowserCoordinatedAppDatabaseMode = "turso-owner" | "turso-proxy";
@@ -36,6 +36,8 @@ export declare class BrowserCoordinatedAppDatabase implements AppDatabase {
     getSearchIndexStats(): Promise<AppDatabaseSearchIndexStats>;
     getMeta<T = unknown>(key: string): Promise<T | undefined>;
     setMeta(key: string, value: unknown): Promise<void>;
+    scanMeta<T = unknown>(query: AppDatabaseMetaScanQuery): Promise<AppDatabaseMetaScanPage<T>>;
+    transactMeta(transaction: AppDatabaseMetaTransaction): Promise<AppDatabaseMetaTransactionResult>;
     getNotebookState(sourcePath: string): Promise<AppDatabaseNotebookState | undefined>;
     setNotebookState(sourcePath: string, state: AppDatabaseNotebookState): Promise<void>;
     deleteNotebookState(sourcePath: string): Promise<void>;

package/dist/storage/browser-coordinated-app-database.js

@@ -16,6 +16,8 @@ const APP_DATABASE_RPC_METHODS = new Set([
     "getSearchIndexStats",
     "getMeta",
     "setMeta",
+    "scanMeta",
+    "transactMeta",
     "getNotebookState",
     "setNotebookState",
     "deleteNotebookState",
@@ -269,6 +271,12 @@ export class BrowserCoordinatedAppDatabase {
     async setMeta(key, value) {
         await this.invoke("setMeta", key, value);
     }
+    async scanMeta(query) {
+        return this.invoke("scanMeta", query);
+    }
+    async transactMeta(transaction) {
+        return this.invoke("transactMeta", transaction);
+    }
     async getNotebookState(sourcePath) {
         return this.invoke("getNotebookState", sourcePath);
     }

package/dist/storage/browser.d.ts

@@ -1,4 +1,4 @@
-import type { DataAdapter, DataWriteOptions, ListedFiles, Stat, AsyncResourceAdapter, VaultIdentityAdapter } from "./fs";
+import type { DataAdapter, DataWriteOptions, AtomicDataWriteOptions, ListedFiles, Stat, AsyncResourceAdapter, VaultIdentityAdapter, VaultReadHandle } from "./fs";
 import { ScopedVaultStore, type KeyValueStore, type VaultProfile } from "./vault-state";
 export type BrowserFileSystemPermissionMode = "read" | "readwrite";
 export type BrowserFileSystemPermissionState = "granted" | "denied" | "prompt";
@@ -15,6 +15,7 @@ export interface BrowserFileSystemWritableFileStream {
     write(data: ArrayBuffer | Blob | string | Uint8Array): Promise<void>;
     seek(position: number): Promise<void>;
     close(): Promise<void>;
+    abort?(reason?: unknown): Promise<void>;
 }
 export interface BrowserFileSystemCreateWritableOptions {
     keepExistingData?: boolean;
@@ -102,6 +103,8 @@ export declare class BrowserHandleVaultAdapter implements DataAdapter, VaultIden
     stat(normalizedPath: string): Promise<Stat | null>;
     read(normalizedPath: string): Promise<string>;
     readBinary(normalizedPath: string): Promise<ArrayBuffer>;
+    openRead(normalizedPath: string): Promise<VaultReadHandle>;
+    atomicWrite(normalizedPath: string, source: ReadableStream<Uint8Array>, options?: AtomicDataWriteOptions): Promise<void>;
     write(normalizedPath: string, data: string, options?: DataWriteOptions): Promise<void>;
     writeBinary(normalizedPath: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>;
     private writeFile;

package/dist/storage/browser.js

@@ -405,6 +405,90 @@ export class BrowserHandleVaultAdapter {
             return toArrayBuffer(await (await handle.getFile()).arrayBuffer());
         });
     }
+    async openRead(normalizedPath) {
+        const path = normalizeVaultPath(normalizedPath);
+        const file = await this.withHandleRetry(async () => {
+            const handle = await this.getHandle(path);
+            if (!handle || handle.kind !== "file")
+                throw createFsError("ENOENT", path);
+            return handle.getFile();
+        });
+        return {
+            size: file.size,
+            mtime: file.lastModified ?? Date.now(),
+            stream: ({ offset = 0, length, signal } = {}) => {
+                const start = Math.max(0, Math.min(file.size, Math.floor(offset)));
+                const end = Math.min(file.size, start + Math.max(0, Math.floor(length ?? file.size - start)));
+                const slice = file.slice(start, end);
+                const stream = typeof slice.stream === "function"
+                    ? slice.stream()
+                    : new ReadableStream({
+                        async start(controller) {
+                            controller.enqueue(new Uint8Array(await slice.arrayBuffer()));
+                            controller.close();
+                        },
+                    });
+                if (!signal)
+                    return stream;
+                const reader = stream.getReader();
+                return new ReadableStream({
+                    async pull(controller) {
+                        if (signal.aborted) {
+                            await reader.cancel(signal.reason);
+                            controller.error(signal.reason ?? new DOMException("Aborted", "AbortError"));
+                            return;
+                        }
+                        const next = await reader.read();
+                        if (next.done)
+                            controller.close();
+                        else
+                            controller.enqueue(next.value);
+                    },
+                    cancel(reason) {
+                        return reader.cancel(reason);
+                    },
+                });
+            },
+        };
+    }
+    async atomicWrite(normalizedPath, source, options = {}) {
+        const path = normalizeVaultPath(normalizedPath);
+        await this.withPathLock(path, () => this.withHandleRetry(async () => {
+            const [parent, name] = await this.getParentDirectory(path, { create: true });
+            const existing = await this.readStoredStat(path);
+            const handle = await parent.getFileHandle(name, { create: true });
+            const writable = await handle.createWritable({ keepExistingData: false });
+            const reader = source.getReader();
+            let size = 0;
+            try {
+                while (true) {
+                    if (options.signal?.aborted) {
+                        throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+                    }
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    await writable.write(next.value);
+                    size += next.value.byteLength;
+                }
+                await writable.close();
+            }
+            catch (error) {
+                await writable.abort?.(error).catch(() => undefined);
+                throw error;
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const now = Date.now();
+            await this.writeStoredStat(path, {
+                type: "file",
+                ctime: options.ctime ?? existing?.ctime ?? now,
+                mtime: options.mtime ?? now,
+                size,
+            });
+        }));
+    }
     async write(normalizedPath, data, options) {
         await this.writeFile(normalizedPath, data, options);
     }

package/dist/storage/desktop-native.d.ts

@@ -6,7 +6,7 @@
  * `getNativeDesktopBridge()` / `hasNativeDesktopBridge()`.
  */
 import type { AppDatabaseChangeSet, AppDatabaseNotificationSeverity } from "./app-database";
-import type { ChangeEvent, AsyncResourceAdapter, DataWriteOptions, ListedFiles, NativeWatchAdapter, NativeWatchSubscription, Stat, VaultAdapter, VaultAdapterCapabilities, VaultIdentityAdapter, WatchErrorEvent, WatchOptions } from "./fs";
+import type { ChangeEvent, AsyncResourceAdapter, DataWriteOptions, ListedFiles, NativeWatchAdapter, NativeWatchSubscription, Stat, VaultAdapter, VaultAdapterCapabilities, VaultReadHandle, AtomicDataWriteOptions, VaultIdentityAdapter, WatchErrorEvent, WatchOptions } from "./fs";
 import { type KeyValueStore, type VaultProfile } from "./vault-state";
 export type NativeDesktopRuntime = "deno-desktop";
 export type NativeDesktopPlatformOs = "macos" | "windows" | "linux" | "unknown";
@@ -18,7 +18,7 @@ export interface NativeDesktopPlatformInfo {
     readonly appVersion?: string;
     readonly packaged?: boolean;
 }
-export type NativeDesktopCapabilityId = "resource" | "database" | "search" | "notebook" | "language-service" | "model" | "plugin-sidecar" | "plugin-assets" | "file-watch" | "notifications" | "file-system-actions" | "agent-runtime" | "terminal-runtime";
+export type NativeDesktopCapabilityId = "resource" | "database" | "search" | "notebook" | "language-service" | "model" | "plugin-sidecar" | "plugin-assets" | "file-watch" | "notifications" | "file-system-actions" | "nostr-signer" | "agent-runtime" | "terminal-runtime" | "secure-storage";
 export type NativeAgentProcessMessage = {
     processId: string;
     type: "stdout" | "stderr" | "exit";
@@ -151,6 +151,8 @@ export declare class NativeDesktopVaultAdapter implements VaultAdapter, VaultIde
     stat(normalizedPath: string): Promise<Stat | null>;
     read(normalizedPath: string): Promise<string>;
     readBinary(normalizedPath: string): Promise<ArrayBuffer>;
+    openRead(normalizedPath: string): Promise<VaultReadHandle>;
+    atomicWrite(normalizedPath: string, source: ReadableStream<Uint8Array>, options?: AtomicDataWriteOptions): Promise<void>;
     write(normalizedPath: string, data: string, options?: DataWriteOptions): Promise<void>;
     writeBinary(normalizedPath: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>;
     append(normalizedPath: string, data: string, options?: DataWriteOptions): Promise<void>;

package/dist/storage/desktop-native.js

@@ -133,7 +133,15 @@ function createFsError(code, path) {
 }
 function toNativeError(error) {
     if (error instanceof Error) {
-        return error;
+        const nativeError = error;
+        if (!nativeError.code) {
+            // Deno's binding serializes a native Error to text, then rejects with a
+            // fresh Error. Restore the same portable code handled for string errors.
+            const match = /^(?:Error:\s*)?([A-Z0-9_]+):\s*(.*)$/u.exec(nativeError.message);
+            if (match)
+                nativeError.code = match[1];
+        }
+        return nativeError;
     }
     const message = typeof error === "string" ? error : String(error);
     const match = /^([A-Z0-9_]+):\s*(.*)$/u.exec(message);
@@ -276,6 +284,87 @@ export class NativeDesktopVaultAdapter {
         });
         return new Uint8Array(data).buffer;
     }
+    async openRead(normalizedPath) {
+        const path = normalizeVaultPath(normalizedPath);
+        const rootPath = this.rootPath;
+        const stat = await this.stat(path);
+        if (!stat || stat.type !== "file")
+            throw createFsError("ENOENT", path);
+        return {
+            size: stat.size,
+            mtime: stat.mtime,
+            stream: ({ offset = 0, length, signal } = {}) => {
+                let cursor = Math.max(0, Math.min(stat.size, Math.floor(offset)));
+                const end = Math.min(stat.size, cursor + Math.max(0, Math.floor(length ?? stat.size - cursor)));
+                return new ReadableStream({
+                    async pull(controller) {
+                        if (signal?.aborted) {
+                            controller.error(signal.reason ?? new DOMException("Aborted", "AbortError"));
+                            return;
+                        }
+                        if (cursor >= end) {
+                            controller.close();
+                            return;
+                        }
+                        const data = await invokeNative("desktop_fs_read_range", {
+                            rootPath,
+                            normalizedPath: path,
+                            offset: cursor,
+                            length: Math.min(256 * 1024, end - cursor),
+                        });
+                        const bytes = Uint8Array.from(data);
+                        if (bytes.byteLength === 0) {
+                            controller.close();
+                            return;
+                        }
+                        cursor += bytes.byteLength;
+                        controller.enqueue(bytes);
+                    },
+                });
+            },
+        };
+    }
+    async atomicWrite(normalizedPath, source, options = {}) {
+        const path = normalizeVaultPath(normalizedPath);
+        const operationId = await invokeNative("desktop_fs_atomic_write_begin", {
+            rootPath: this.rootPath,
+            normalizedPath: path,
+            options: { ctime: options.ctime, mtime: options.mtime },
+        });
+        const reader = source.getReader();
+        try {
+            while (true) {
+                if (options.signal?.aborted) {
+                    throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+                }
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                await invokeNative("desktop_fs_atomic_write_chunk", {
+                    rootPath: this.rootPath,
+                    normalizedPath: path,
+                    operationId,
+                    data: [...next.value],
+                });
+            }
+            await invokeNative("desktop_fs_atomic_write_commit", {
+                rootPath: this.rootPath,
+                normalizedPath: path,
+                operationId,
+            });
+        }
+        catch (error) {
+            await invokeNative("desktop_fs_atomic_write_abort", {
+                rootPath: this.rootPath,
+                normalizedPath: path,
+                operationId,
+            }).catch(() => undefined);
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
     async write(normalizedPath, data, options) {
         await invokeNative("desktop_fs_write_text", {
             rootPath: this.rootPath,

package/dist/storage/fs.d.ts

@@ -24,6 +24,21 @@ export interface FileStats extends FileProperties {
     size: number;
 }
 export type DataWriteOptions = Partial<FileProperties>;
+export interface VaultReadStreamOptions {
+    offset?: number;
+    length?: number;
+    signal?: AbortSignal;
+}
+export interface VaultReadHandle {
+    size: number;
+    mtime: number;
+    stream(options?: VaultReadStreamOptions): ReadableStream<Uint8Array>;
+}
+export interface AtomicDataWriteOptions extends DataWriteOptions {
+    signal?: AbortSignal;
+    /** Opaque host-issued correlation used by the App's mutation broker. */
+    operationOrigin?: string;
+}
 export declare abstract class TAbstractFile {
     parent: TFolder | null;
     path: string;
@@ -140,6 +155,8 @@ export interface VaultAdapterCapabilities {
  */
 export interface VaultAdapter extends DataAdapter {
     getCapabilities?(): Partial<VaultAdapterCapabilities>;
+    openRead?(normalizedPath: string): Promise<VaultReadHandle>;
+    atomicWrite?(normalizedPath: string, source: ReadableStream<Uint8Array>, options?: AtomicDataWriteOptions): Promise<void>;
 }
 export interface VaultIdentityAdapter {
     getVaultId(): string;