@lapis-notes/api 0.1.3 → 0.2.0

package/dist/native-database-protocol.d.ts

@@ -0,0 +1,29 @@
+export type DatabaseMethod = "migrate" | "beginSearchIndexingBatch" | "endSearchIndexingBatch" | "configureSearchEmbeddingProvider" | "getSearchEmbeddingProvider" | "getSearchEmbeddingRuntimeStatus" | "getSearchIndexStats" | "getMeta" | "setMeta" | "scanMeta" | "transactMeta" | "getNotebookState" | "setNotebookState" | "deleteNotebookState" | "loadMetadataSnapshot" | "saveMetadataSnapshot" | "getFileHistory" | "storeFileHistoryRevision" | "listNotifications" | "upsertNotification" | "markNotificationRead" | "clearNotification" | "clearAllNotifications" | "getMemorySourceState" | "listMemorySourceStates" | "upsertMemorySourceState" | "deleteMemorySourceState" | "upsertMemoryCandidate" | "queryMemoryCandidates" | "deleteMemoryCandidatesByConversation" | "recordMemoryRecallSignal" | "listMemoryRecallSignals" | "claimMemoryJob" | "updateMemoryJob" | "listMemoryJobs" | "clearMemoryDerivedState" | "getChangeRevision" | "upsertIndexedFile" | "getIndexedFile" | "listIndexedFileManifest" | "queryIndexedMetadata" | "queryIndexedMetadataPage" | "queryMetadataFacets" | "queryMetadataLinks" | "deleteIndexedFile" | "renameIndexedFile" | "upsertSearchDocument" | "deleteSearchDocument" | "getSearchDocument" | "listSearchDocumentManifest" | "listSearchDocuments" | "rebuildSearchIndex" | "searchDocuments" | "searchDocumentPaths" | "upsertTaskProjection" | "deleteTaskProjection" | "queryTasks" | "getTaskRow" | "listChildLinks" | "listTaskDescendants" | "registerProjectionDefinition" | "unregisterProjectionDefinition" | "replaceProjectionSource" | "markProjectionSourceError" | "deleteProjectionSource" | "queryProjection" | "getProjectionRow" | "queryRelated";
+export type DatabaseValue = {
+    kind: "undefined";
+} | {
+    kind: "value";
+    value: unknown;
+};
+export type DatabaseCall = {
+    method: DatabaseMethod;
+    args?: Array<DatabaseValue>;
+};
+export type ChangeDomain = "metadata" | "search" | "history" | "notification" | "notebook" | "task" | "projection" | "memory" | "meta";
+export type ChangedPath = {
+    oldPath: string;
+    newPath: string;
+};
+export type ChangeSet = {
+    revision: number;
+    domains: Array<ChangeDomain>;
+    paths: Array<string>;
+    renamed?: Array<ChangedPath>;
+    reset?: boolean;
+    committedAt: number;
+};
+export type SearchChunkingSettings = {
+    targetChars: number;
+    breakpointWindowChars: number;
+    breakpointDecay: number;
+};

package/dist/native-database-protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/native-editing-intent-lease.d.ts

@@ -0,0 +1,17 @@
+import type { NativeEditingIntents } from "./native-editing-intents";
+/** One document's native fence; this class never writes document content. */
+export declare class NativeEditingIntentLease {
+    #private;
+    private readonly port;
+    private readonly path;
+    private readonly savedText;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    constructor(port: NativeEditingIntents, path: string, savedText: () => string | null | undefined);
+    get retired(): boolean;
+    get yielded(): boolean;
+    ready(): Promise<void>;
+    changed(): Promise<void>;
+    yield(): Promise<void>;
+    resume(): Promise<void>;
+    retire(): Promise<void>;
+}

package/dist/native-editing-intent-lease.js

@@ -0,0 +1,188 @@
+/** One document's native fence; this class never writes document content. */
+export class NativeEditingIntentLease {
+    port;
+    path;
+    savedText;
+    id = crypto.randomUUID();
+    #generation = 1;
+    #revision = 0;
+    #tail = Promise.resolve();
+    #admission;
+    #changes = new Map();
+    #resuming;
+    #retiring = false;
+    #state = "unknown";
+    constructor(port, path, savedText) {
+        this.port = port;
+        this.path = path;
+        this.savedText = savedText;
+    }
+    get retired() {
+        return this.#state === "retired";
+    }
+    get yielded() {
+        return this.#state === "yielded";
+    }
+    #valid(value) {
+        if (value.kind !== "state" ||
+            value.state.editor_id !== this.id ||
+            value.state.path !== this.path ||
+            value.state.detached)
+            throw new Error(`Native editor intent is unavailable: ${this.path}`);
+        return value.state;
+    }
+    async #transition(command, accepts) {
+        try {
+            const value = await this.port.call(command);
+            if (!accepts(value))
+                throw new Error("Native editor intent reply changed");
+            return value;
+        }
+        catch (error) {
+            // Status can prove an applied transition. It never retries file writes.
+            try {
+                const observed = await this.port.call({
+                    kind: "inspect",
+                    editor_id: this.id,
+                });
+                if (accepts(observed))
+                    return observed;
+            }
+            catch {
+                /* Preserve the definitive transition error and local protection. */
+            }
+            this.#state = "unknown";
+            throw error;
+        }
+    }
+    ready() {
+        if (this.#state === "retired")
+            return Promise.reject(new Error("Native editor intent is retired"));
+        if (this.#admission)
+            return this.#admission;
+        this.#admission = this.#transition({ kind: "acquire", editor_id: this.id, path: this.path }, (value) => {
+            const state = this.#valid(value);
+            return (state.generation === 1 &&
+                state.revision === 0 &&
+                state.active &&
+                !state.dirty);
+        }).then(() => {
+            this.#state = "active";
+        });
+        void this.#admission.catch(() => {
+            this.#admission = undefined;
+        });
+        return this.#admission;
+    }
+    changed() {
+        const revision = ++this.#revision;
+        this.#changes.set(revision, {
+            kind: "changed",
+            editor_id: this.id,
+            generation: this.#generation,
+            revision,
+        });
+        const changed = this.#tail
+            .catch(() => { })
+            .then(() => this.#settleChanges());
+        this.#tail = changed;
+        // Native failures are observed by ready/flush/guard, including debounce callers.
+        void changed.catch(() => { });
+        return changed;
+    }
+    async #settleChanges() {
+        await this.ready();
+        for (const [revision, command] of this.#changes) {
+            await this.#transition(command, (value) => {
+                const state = this.#valid(value);
+                return (state.generation === this.#generation &&
+                    state.revision === revision &&
+                    state.active &&
+                    state.dirty);
+            });
+            this.#changes.delete(revision);
+        }
+    }
+    async #reconcile() {
+        const value = await this.port.call({ kind: "inspect", editor_id: this.id });
+        if (value.kind === "retired" && this.#retiring) {
+            this.#state = "retired";
+            return;
+        }
+        const state = this.#valid(value);
+        if (state.revision !== this.#revision ||
+            (state.generation !== this.#generation &&
+                !(state.active && state.generation === this.#resuming)))
+            throw new Error(`Native editor intent requires recovery: ${this.path}`);
+        this.#generation = state.generation;
+        this.#state = state.active ? "active" : "yielded";
+        this.#resuming = undefined;
+    }
+    yield() {
+        return this.#yield(true);
+    }
+    async #yield(requireSavedMatch) {
+        await this.ready();
+        await this.#tail.catch(() => { });
+        await this.#settleChanges();
+        if (this.#state === "unknown")
+            await this.#reconcile();
+        if (this.#state === "yielded")
+            return;
+        const saved = this.savedText();
+        const current = await this.port.read(this.path);
+        if (requireSavedMatch &&
+            saved !== undefined &&
+            saved !== (current?.text ?? null))
+            throw Object.assign(new Error(`Saved editor content changed: ${this.path}`), { code: "ECONFLICT" });
+        const expected = current
+            ? { kind: "version", version: current.version }
+            : { kind: "missing" };
+        await this.#transition({
+            kind: "yield",
+            editor_id: this.id,
+            generation: this.#generation,
+            revision: this.#revision,
+            expected,
+        }, (value) => {
+            const state = this.#valid(value);
+            return (state.generation === this.#generation &&
+                state.revision === this.#revision &&
+                !state.active &&
+                !state.dirty);
+        });
+        this.#state = "yielded";
+    }
+    async resume() {
+        await this.ready();
+        await this.#tail.catch(() => { });
+        await this.#settleChanges();
+        if (this.#state === "unknown")
+            await this.#reconcile();
+        if (this.#state === "active")
+            return;
+        const generation = this.#generation + 1;
+        this.#resuming = generation;
+        await this.#transition({ kind: "resume", editor_id: this.id, generation }, (value) => {
+            const state = this.#valid(value);
+            return (state.generation === generation &&
+                state.revision === this.#revision &&
+                state.active);
+        });
+        this.#generation = generation;
+        this.#resuming = undefined;
+        this.#state = "active";
+    }
+    async retire() {
+        if (this.#state === "unknown" && this.#retiring)
+            await this.#reconcile();
+        if (this.retired)
+            return;
+        // The registry permits terminal retirement only after the producer is clean.
+        // External deletion/rename may change saved bytes; no mutation follows.
+        await this.#yield(false);
+        this.#retiring = true;
+        await this.#transition({ kind: "retire", editor_id: this.id, generation: this.#generation }, (value) => value.kind === "retired");
+        this.#state = "retired";
+    }
+}

package/dist/native-editing-intents-protocol.d.ts

@@ -0,0 +1,70 @@
+export type ExpectedVersion = {
+    kind: "missing";
+} | {
+    kind: "version";
+    version: string;
+};
+export type TextSnapshot = {
+    path: string;
+    text: string;
+    version: string;
+};
+export type EditingIntentState = {
+    editor_id: string;
+    path: string;
+    generation: number;
+    revision: number;
+    dirty: boolean;
+    active: boolean;
+    detached: boolean;
+};
+export type EditingIntentCommand = {
+    kind: "acquire";
+    editor_id: string;
+    path: string;
+} | {
+    kind: "changed";
+    editor_id: string;
+    generation: number;
+    revision: number;
+} | {
+    kind: "yield";
+    editor_id: string;
+    generation: number;
+    revision: number;
+    expected: ExpectedVersion;
+} | {
+    kind: "resume";
+    editor_id: string;
+    generation: number;
+} | {
+    kind: "retire";
+    editor_id: string;
+    generation: number;
+} | {
+    kind: "recover";
+    editor_id: string;
+    generation: number;
+    revision: number;
+} | {
+    kind: "discard";
+    editor_id: string;
+    generation: number;
+    revision: number;
+} | {
+    kind: "inspect";
+    editor_id: string;
+} | {
+    kind: "list";
+};
+export type EditingIntentValue = {
+    kind: "state";
+    state: EditingIntentState;
+} | {
+    kind: "states";
+    states: Array<EditingIntentState>;
+} | {
+    kind: "retired";
+} | {
+    kind: "missing";
+};

package/dist/native-editing-intents-protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/native-editing-intents.d.ts

@@ -0,0 +1,8 @@
+import type { EditingIntentCommand, EditingIntentValue, TextSnapshot } from "./native-editing-intents-protocol";
+export type * from "./native-editing-intents-protocol";
+/** An admitted native fence; persistence stays with existing App writers. */
+export interface NativeEditingIntents {
+    call(command: EditingIntentCommand): Promise<EditingIntentValue>;
+    /** Expected absence is null; unavailable or unreadable files reject. */
+    read(path: string): Promise<TextSnapshot | null>;
+}

package/dist/native-editing-intents.js

@@ -0,0 +1 @@
+export {};

package/dist/native-editing-problems.d.ts

@@ -0,0 +1,3 @@
+import type { App } from "./context.svelte";
+/** Share one disposable Problems collection across every shell of the same App. */
+export declare function bindNativeEditingProblems(app: App): () => void;

package/dist/native-editing-problems.js

@@ -0,0 +1,180 @@
+const prefix = "lapis-editing-claim:";
+const bindings = new WeakMap();
+const claimCode = (state) => `claim:${state.editor_id}:${state.generation}:${state.revision}:${+state.active}${+state.dirty}${+state.detached}`;
+const issueCode = (issue) => `admission:${issue.registration}:${issue.id}:${issue.status}`;
+/** Share one disposable Problems collection across every shell of the same App. */
+export function bindNativeEditingProblems(app) {
+    const recovery = app.fileEditingSessions.nativeRecovery;
+    if (!recovery)
+        return () => { };
+    let binding = bindings.get(app);
+    if (!binding) {
+        binding = createBinding(app);
+        bindings.set(app, binding);
+    }
+    const owned = binding;
+    owned.references++;
+    let held = true;
+    return () => {
+        if (!held)
+            return;
+        held = false;
+        if (--owned.references === 0) {
+            owned.dispose();
+            bindings.delete(app);
+        }
+    };
+}
+function createBinding(app) {
+    const registry = app.fileEditingSessions;
+    const recovery = registry.nativeRecovery;
+    let active = true;
+    let actions = new Map();
+    let resources = new Set();
+    const run = async (operation) => {
+        if (!active)
+            return;
+        try {
+            await operation();
+        }
+        catch (error) {
+            if (active)
+                app.notifications.notify({
+                    severity: "error",
+                    source: "editing",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+        }
+    };
+    const openSavedFile = (path) => registry.track(async () => {
+        const file = app.vault.getFileByPath(path);
+        if (!file)
+            throw new Error("The saved file is no longer available");
+        const leaf = app.workspace.getLeaf("tab");
+        await leaf.openFile(file, {
+            state: { type: leaf.view.getViewType(), state: { mode: "preview" } },
+        });
+        app.workspace.setActiveLeaf(leaf);
+        await app.workspace.revealLeaf(leaf);
+    });
+    const collection = app.workspace.diagnostics.createCollection("lapis:editing-claims", {
+        label: "Editing",
+        buildItemMenu(menu, entry) {
+            const code = entry.diagnostic.code;
+            const action = typeof code === "string" ? actions.get(code) : undefined;
+            if (!active)
+                return;
+            if (!action) {
+                if (code === "editing-observation-unavailable")
+                    menu.addItem((item) => item
+                        .setTitle("Refresh editing claims")
+                        .setIcon("refresh-cw")
+                        .onClick(() => run(() => registry.track(() => recovery.refresh()))));
+                return;
+            }
+            const path = action.kind === "claim" ? action.state.path : action.issue.path;
+            menu.addItem((item) => item
+                .setTitle("Review saved file")
+                .setIcon("file-text")
+                .setDisabled(!app.vault.getFileByPath(path))
+                .onClick(() => run(() => openSavedFile(path))));
+            if (action.kind === "claim") {
+                const captured = action.state;
+                menu.addItem((item) => item
+                    .setTitle("Recover editing claim")
+                    .setIcon("rotate-ccw")
+                    .setDisabled(!captured.detached)
+                    .onClick(() => run(() => recovery.recover(captured))));
+                menu.addItem((item) => item
+                    .setTitle("Discard editing claim")
+                    .setIcon("trash-2")
+                    .onClick(() => run(() => recovery.discard(captured))));
+            }
+            else {
+                const captured = action.issue;
+                menu.addItem((item) => item
+                    .setTitle("Retry editing admission")
+                    .setIcon("refresh-cw")
+                    .setDisabled(captured.status !== "failed")
+                    .onClick(() => run(() => registry.nativeIssues.retry(captured))));
+            }
+        },
+    });
+    const publish = () => {
+        if (!active)
+            return;
+        const grouped = new Map();
+        const next = new Map();
+        const add = (path, code, message, action) => {
+            const group = grouped.get(path) ?? { path, diagnostics: [] };
+            group.diagnostics.push({
+                message,
+                severity: "warning",
+                source: "Editing",
+                code,
+            });
+            grouped.set(path, group);
+            next.set(code, action);
+        };
+        const snapshot = recovery.snapshot();
+        for (const state of snapshot.claims)
+            add(state.path, claimCode(state), "Unresolved editing claim. Review the saved file before recovering or discarding this claim; unsaved draft content is not stored here.", { kind: "claim", state });
+        for (const issue of registry.nativeIssues.entries)
+            add(issue.path, issueCode(issue), issue.status === "pending"
+                ? `Editing ${issue.phase} is pending. Editable input remains protected.`
+                : `Editing ${issue.phase} failed: ${issue.message}. Retry explicitly to restore editable access.`, { kind: "local", issue });
+        actions = next;
+        const current = new Set(grouped.keys());
+        for (const path of resources)
+            if (!current.has(path))
+                collection.delete({ uri: prefix + encodeURIComponent(path) });
+        const updates = [...grouped.values()].map(({ path, diagnostics }) => [
+            {
+                uri: prefix + encodeURIComponent(path),
+                label: path,
+                detail: path,
+                icon: "file-warning",
+            },
+            diagnostics,
+        ]);
+        updates.push([
+            null,
+            snapshot.error
+                ? [
+                    {
+                        severity: "error",
+                        source: "Editing",
+                        code: "editing-observation-unavailable",
+                        message: `Editing claims could not be checked: ${snapshot.error}. Existing protection remains active.`,
+                    },
+                ]
+                : undefined,
+        ]);
+        collection.set(updates);
+        resources = current;
+    };
+    const stopNavigation = app.workspace.registerDiagnosticOpener(async (location) => {
+        if (!location.resource.uri.startsWith(prefix))
+            return false;
+        if (!active)
+            return true;
+        const path = decodeURIComponent(location.resource.uri.slice(prefix.length));
+        if (resources.has(path) && app.vault.getFileByPath(path))
+            await run(() => openSavedFile(path));
+        return true;
+    });
+    const stopRecovery = recovery.subscribe(publish);
+    const stopIssues = registry.nativeIssues.subscribe(publish);
+    const stopObserver = recovery.observe();
+    return {
+        references: 0,
+        dispose() {
+            active = false;
+            stopObserver();
+            stopIssues();
+            stopRecovery();
+            stopNavigation();
+            collection.dispose();
+        },
+    };
+}

package/dist/native-editing-recovery.d.ts

@@ -0,0 +1,24 @@
+import type { EditingIntentState, NativeEditingIntents } from "./native-editing-intents";
+export interface NativeEditingRecoverySnapshot {
+    readonly claims: readonly Readonly<EditingIntentState>[];
+    readonly error?: string;
+}
+type Track = <T>(operation: () => Promise<T>) => Promise<T>;
+type Listener = (snapshot: NativeEditingRecoverySnapshot) => void;
+/** Passive recovery metadata. Native intents contain no document or draft bytes. */
+export declare class NativeEditingRecovery {
+    #private;
+    private readonly port;
+    private readonly track;
+    constructor(port: NativeEditingIntents, track: Track);
+    snapshot(): NativeEditingRecoverySnapshot;
+    subscribe(listener: Listener): () => void;
+    /** Shell-owned read-only observation; multiple shells share one poll. */
+    observe(): () => void;
+    refresh(): Promise<void>;
+    /** Hosts call this before destructive App/registry teardown. */
+    assertClear(): Promise<void>;
+    recover(captured: EditingIntentState): Promise<void>;
+    discard(captured: EditingIntentState): Promise<void>;
+}
+export {};