@lapis-notes/api 0.1.3 → 0.2.0

package/dist/native-editing-recovery.js

@@ -0,0 +1,198 @@
+const matches = (left, right) => left.editor_id === right.editor_id &&
+    left.path === right.path &&
+    left.generation === right.generation &&
+    left.revision === right.revision &&
+    left.active === right.active &&
+    left.dirty === right.dirty &&
+    left.detached === right.detached;
+/** Passive recovery metadata. Native intents contain no document or draft bytes. */
+export class NativeEditingRecovery {
+    port;
+    track;
+    #listeners = new Set();
+    #adopted = new Set();
+    #acting = new Set();
+    #snapshot = Object.freeze({
+        claims: Object.freeze([]),
+    });
+    #observers = 0;
+    #epoch = 0;
+    #mutation = 0;
+    #timer;
+    #pending;
+    constructor(port, track) {
+        this.port = port;
+        this.track = track;
+    }
+    snapshot() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#snapshot);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Shell-owned read-only observation; multiple shells share one poll. */
+    observe() {
+        if (this.#observers++ === 0)
+            void this.#poll(++this.#epoch);
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            if (--this.#observers === 0) {
+                this.#epoch++;
+                clearTimeout(this.#timer);
+                this.#timer = undefined;
+            }
+        };
+    }
+    async #poll(epoch) {
+        try {
+            await this.#load(epoch);
+        }
+        catch {
+            /* Failure remains in the snapshot. */
+        }
+        if (this.#observers && epoch === this.#epoch)
+            this.#timer = setTimeout(() => void this.#poll(epoch), 1000);
+    }
+    refresh() {
+        return this.#load(this.#epoch);
+    }
+    #load(epoch) {
+        if (this.#pending?.epoch === epoch)
+            return this.#pending.promise;
+        const mutation = this.#mutation;
+        const promise = (async () => {
+            try {
+                const value = await this.port.call({ kind: "list" });
+                if (value.kind !== "states")
+                    throw new Error("Native editing claims are unavailable");
+                if (epoch !== this.#epoch || mutation !== this.#mutation)
+                    return;
+                const retained = new Set(value.states.map((state) => state.editor_id));
+                for (const id of this.#adopted)
+                    if (!retained.has(id))
+                        this.#adopted.delete(id);
+                this.#publish(value.states.filter((state) => state.detached || this.#adopted.has(state.editor_id)));
+            }
+            catch (error) {
+                if (epoch === this.#epoch && mutation === this.#mutation)
+                    this.#publish(this.#snapshot.claims, error);
+                throw error;
+            }
+        })();
+        const pending = { epoch, promise };
+        this.#pending = pending;
+        void promise
+            .finally(() => {
+            if (this.#pending === pending)
+                this.#pending = undefined;
+        })
+            .catch(() => { });
+        return promise;
+    }
+    /** Hosts call this before destructive App/registry teardown. */
+    async assertClear() {
+        await this.refresh();
+        if (this.#snapshot.claims.length)
+            throw new Error("Unresolved editing claims require review in Problems");
+    }
+    recover(captured) {
+        return this.#act("recover", captured);
+    }
+    discard(captured) {
+        return this.#act("discard", captured);
+    }
+    #act(kind, captured) {
+        return this.track(async () => {
+            const current = this.#snapshot.claims.find((state) => state.editor_id === captured.editor_id);
+            if (!current || !matches(current, captured))
+                throw new Error("Editing claim changed; refresh Problems");
+            if (this.#acting.has(current.editor_id))
+                throw new Error("Editing claim recovery is pending");
+            if (kind === "recover" && !current.detached)
+                throw new Error("Editing claim is already attached");
+            this.#acting.add(current.editor_id);
+            this.#mutation++;
+            const accepts = (value) => kind === "discard"
+                ? value.kind === "retired"
+                : value.kind === "state" &&
+                    matches(value.state, {
+                        ...current,
+                        generation: current.generation + 1,
+                        detached: false,
+                    });
+            try {
+                let value;
+                try {
+                    value = await this.port.call({
+                        kind,
+                        editor_id: current.editor_id,
+                        generation: current.generation,
+                        revision: current.revision,
+                    });
+                    if (!accepts(value))
+                        throw new Error("Editing claim recovery response changed");
+                }
+                catch (error) {
+                    try {
+                        const inspected = await this.port.call({
+                            kind: "inspect",
+                            editor_id: current.editor_id,
+                        });
+                        if (!accepts(inspected))
+                            throw error;
+                        value = inspected;
+                    }
+                    catch {
+                        throw error;
+                    }
+                }
+                const remaining = this.#snapshot.claims.filter((state) => state.editor_id !== current.editor_id);
+                if (value.kind === "state") {
+                    this.#adopted.add(current.editor_id);
+                    this.#publish([...remaining, value.state]);
+                }
+                else {
+                    this.#adopted.delete(current.editor_id);
+                    this.#publish(remaining);
+                }
+            }
+            catch (error) {
+                this.#publish(this.#snapshot.claims, error);
+                throw error;
+            }
+            finally {
+                this.#acting.delete(current.editor_id);
+            }
+        });
+    }
+    #publish(claims, error) {
+        const message = error
+            ? error instanceof Error
+                ? error.message
+                : String(error)
+            : undefined;
+        if (this.#snapshot.error === message &&
+            claims.length === this.#snapshot.claims.length &&
+            claims.every((state, index) => matches(state, this.#snapshot.claims[index])))
+            return;
+        this.#snapshot = Object.freeze({
+            claims: Object.freeze(claims.map((state) => Object.freeze({ ...state }))),
+            ...(message ? { error: message } : {}),
+        });
+        for (const listener of this.#listeners) {
+            try {
+                listener(this.#snapshot);
+            }
+            catch (error) {
+                console.error("Editing recovery subscriber failed", error);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { FileEditingSession } from "./file-editing-sessions";
+import type { NativeEditingIntents } from "./native-editing-intents";
+/** Producer-owned local protection and last acknowledged destination bytes. */
+export interface NativeEditingSession {
+    /** Block input synchronously, before native admission's first await. */
+    hold(): () => void | Promise<void>;
+    savedText(): string | null | undefined;
+    /**
+     * Observe native-owned saved bytes while the existing producer stays
+     * protected.
+     */
+    refreshSavedText?(text: string | null): void | Promise<void>;
+    /** Logical state has no editable buffer while idle. Documents remain default. */
+    readonly lifetime?: "interactive" | "operation";
+}
+export type NativeEditingPhase = "admission" | "handoff" | "rearm" | "retirement";
+export interface NativeEditingIssue {
+    readonly id: string;
+    readonly path: string;
+    readonly phase: NativeEditingPhase;
+    readonly status: "pending" | "failed";
+    readonly message: string;
+}
+export type FileEditingRegistration = (() => void) & {
+    readonly native: boolean;
+    /** An explicit retry may reconcile native admission without changing identity. */
+    ready(): Promise<void>;
+    /** Capture a newer dirty generation; the active intent already fences writers. */
+    changed(): void;
+    /** Quiesce an acknowledged noninteractive operation; documents stay active. */
+    idle(): Promise<void>;
+};
+/** Adds a native fence to an existing writer without replacing its persistence. */
+export declare class NativeRegisteredEditingSession implements FileEditingSession {
+    #private;
+    private readonly session;
+    private readonly port;
+    private readonly path;
+    private readonly retiring;
+    constructor(session: FileEditingSession, port: NativeEditingIntents, path: string, retiring: () => boolean);
+    get dirty(): boolean;
+    get retired(): boolean;
+    get issue(): NativeEditingIssue | undefined;
+    subscribe(listener: () => void): () => void;
+    settle(): Promise<void>;
+    ready(): Promise<void>;
+    changed(): void;
+    idle(): Promise<void>;
+    flush(): Promise<void>;
+    protect(): Promise<() => Promise<void>>;
+}

package/dist/native-editing-session.js

@@ -0,0 +1,251 @@
+import { NativeEditingIntentLease } from "./native-editing-intent-lease";
+/** Adds a native fence to an existing writer without replacing its persistence. */
+export class NativeRegisteredEditingSession {
+    session;
+    port;
+    path;
+    retiring;
+    #lease;
+    #initialRelease;
+    #initiallyDirty;
+    #initialDirtyReported = false;
+    #protected = 0;
+    #scoped;
+    #admitted = false;
+    #idle = false;
+    #refreshPending = false;
+    #handoffFailure;
+    #issue;
+    #epoch = 0;
+    #pending = new Set();
+    #listeners = new Set();
+    constructor(session, port, path, retiring) {
+        this.session = session;
+        this.port = port;
+        this.path = path;
+        this.retiring = retiring;
+        if (!session.native)
+            throw new Error(`Native editing lifecycle is required: ${path}`);
+        this.#scoped = session.native.lifetime === "operation";
+        this.#initiallyDirty = session.dirty;
+        if (!this.#scoped || this.#initiallyDirty)
+            void this.ready().catch(() => { });
+    }
+    get dirty() {
+        return this.session.dirty;
+    }
+    get retired() {
+        return !this.#lease || this.#lease.retired;
+    }
+    get issue() {
+        return this.#issue;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #publish(issue) {
+        this.#issue = issue;
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("Native editor issue listener failed", error);
+            }
+        }
+    }
+    async settle() {
+        while (this.#pending.size)
+            await Promise.allSettled([...this.#pending]);
+    }
+    #transition(phase, run) {
+        this.#epoch++;
+        const pending = Object.freeze({
+            id: crypto.randomUUID(),
+            path: this.path,
+            phase,
+            status: "pending",
+            message: `Native editor ${phase} is pending`,
+        });
+        this.#publish(pending);
+        const transition = (async () => {
+            try {
+                await run();
+                if (this.#issue === pending)
+                    this.#publish(undefined);
+            }
+            catch (error) {
+                if (this.#issue === pending)
+                    this.#publish(Object.freeze({
+                        ...pending,
+                        status: "failed",
+                        message: `Native editor ${phase} requires retry`,
+                    }));
+                throw error;
+            }
+        })();
+        this.#pending.add(transition);
+        void transition
+            .finally(() => this.#pending.delete(transition))
+            .catch(() => { });
+        return transition;
+    }
+    #hold() {
+        this.#initialRelease ??= this.session.native.hold();
+        if (typeof this.#initialRelease !== "function")
+            throw new Error("Invalid native editing protection release");
+    }
+    #intent() {
+        return (this.#lease ??= new NativeEditingIntentLease(this.port, this.path, () => this.#scoped && !this.session.dirty
+            ? undefined
+            : this.session.native.savedText()));
+    }
+    async #releaseInitial() {
+        if (!this.#initialRelease)
+            return;
+        await this.#initialRelease();
+        this.#initialRelease = undefined;
+    }
+    async #refreshSaved() {
+        if (this.session.dirty)
+            throw new Error(`Protected saved-text refresh requires clean state: ${this.path}`);
+        const native = this.session.native;
+        const before = native.savedText();
+        const current = await this.port.read(this.path);
+        const text = current?.text ?? null;
+        if (before === undefined || before === text)
+            return;
+        if (!native.refreshSavedText)
+            throw new Error(`Protected saved-text refresh is unavailable: ${this.path}`);
+        await native.refreshSavedText(text);
+        if (this.session.dirty || native.savedText() !== text)
+            throw new Error(`Protected saved-text refresh was not acknowledged: ${this.path}`);
+    }
+    async ready() {
+        this.#hold();
+        const lease = this.#intent();
+        if (!this.#admitted || (this.#scoped && (this.#idle || this.#issue))) {
+            const phase = this.#admitted ? "rearm" : "admission";
+            await this.#transition(phase, () => this.#scoped ? lease.resume() : lease.ready());
+            this.#admitted = true;
+            this.#idle = false;
+        }
+        else
+            await lease.ready();
+        if (this.#initiallyDirty && !this.#initialDirtyReported) {
+            this.#initialDirtyReported = true;
+            this.changed();
+        }
+        await this.#releaseInitial();
+    }
+    changed() {
+        if (!this.#lease)
+            throw new Error("Native state admission is required");
+        const epoch = this.#epoch;
+        void this.#lease.changed().catch(() => {
+            if (this.#epoch !== epoch)
+                return;
+            this.#publish(Object.freeze({
+                id: crypto.randomUUID(),
+                path: this.path,
+                phase: "handoff",
+                status: "failed",
+                message: "Native editor change reporting requires retry",
+            }));
+        });
+    }
+    async idle() {
+        if (!this.#scoped ||
+            !this.#lease ||
+            this.session.dirty ||
+            (this.#idle && !this.#issue))
+            return;
+        this.#hold();
+        await this.#transition("handoff", () => this.#lease.yield());
+        this.#idle = true;
+        await this.#releaseInitial();
+    }
+    async flush() {
+        if (this.#lease?.retired && !this.session.dirty)
+            return;
+        if (this.#scoped && !this.session.dirty) {
+            await this.idle();
+            return;
+        }
+        await this.ready();
+        await this.session.flush();
+        if (this.retiring() && !this.session.dirty)
+            await this.#transition("retirement", () => this.#lease.retire());
+        else if (this.#scoped)
+            await this.idle();
+        else if (this.#protected && !this.session.dirty)
+            await this.#yieldProtected();
+    }
+    async #yieldProtected() {
+        try {
+            await this.#reconcileBeforeYield();
+            await this.#transition("handoff", () => this.#lease.yield());
+            this.#handoffFailure = undefined;
+        }
+        catch (error) {
+            this.#handoffFailure = { error };
+            throw error;
+        }
+    }
+    /**
+     * A clean interactive producer acknowledges authoritative saved bytes under
+     * the guard's held protection (LN-CORE-028), so external drift reconciles
+     * exactly like the producer's own file-change projection before the yield
+     * comparison. A failed observation defers to the fenced yield check, which
+     * retains protection and the observable handoff retry.
+     */
+    async #reconcileBeforeYield() {
+        if (this.session.dirty || !this.session.native?.refreshSavedText)
+            return;
+        try {
+            await this.#refreshSaved();
+        }
+        catch {
+            /* The yield comparison below remains the authoritative fenced failure. */
+        }
+    }
+    async protect() {
+        // The producer acquires its local lock synchronously before yielding.
+        const protection = this.session.protect();
+        const release = await protection;
+        this.#protected++;
+        let held = true, cleanupStarted = false;
+        return async () => {
+            if (!held)
+                return;
+            const retry = cleanupStarted;
+            cleanupStarted = true;
+            if (this.retiring() && !this.session.dirty && this.#lease) {
+                await this.#transition("retirement", () => this.#lease.retire());
+                this.#handoffFailure = undefined;
+            }
+            else {
+                if (this.#handoffFailure) {
+                    // Initial cleanup cannot turn the failed Yield into a no-op Resume.
+                    if (!retry)
+                        throw this.#handoffFailure.error;
+                    await this.#yieldProtected();
+                }
+                if (!this.#scoped || this.session.dirty)
+                    await this.#transition("rearm", async () => {
+                        if (this.#lease?.yielded && !this.session.dirty)
+                            this.#refreshPending = true;
+                        await this.#intent().resume();
+                        if (this.#refreshPending) {
+                            await this.#refreshSaved();
+                            this.#refreshPending = false;
+                        }
+                    });
+            }
+            await release();
+            held = false;
+            this.#protected--;
+        };
+    }
+}

package/dist/native-history-index-protocol.d.ts

@@ -0,0 +1,80 @@
+export type HistoryExpression = {
+    type: "term";
+    field: string | null;
+    value: string;
+} | {
+    type: "and";
+    clauses: Array<HistoryExpression>;
+} | {
+    type: "or";
+    clauses: Array<HistoryExpression>;
+} | {
+    type: "not";
+    operand: HistoryExpression;
+};
+export type HistoryIndexQuery = {
+    expression: HistoryExpression;
+    case_sensitive: boolean;
+    cursor: string | null;
+    limit: number;
+};
+export type HistoryIndexCommand = {
+    kind: "start";
+} | {
+    kind: "status";
+} | {
+    kind: "query";
+    search: HistoryIndexQuery;
+} | {
+    kind: "context";
+    commit: string;
+    path: string;
+    start: number;
+    end: number;
+};
+export type HistoryIndexProgress = {
+    generation: number;
+    indexed: number;
+    omitted: number;
+    complete: boolean;
+};
+export type HistoryCheckpoint = {
+    operation: string;
+    commit: string;
+    change_id: string;
+    description: string;
+    timestamp_millis: number;
+};
+export type HistorySavedRevision = {
+    checkpoint: HistoryCheckpoint;
+    author: string;
+    email: string;
+};
+export type HistoryIndexRecord = {
+    revision: HistorySavedRevision;
+    parents: Array<string>;
+    path: string | null;
+    content_id: string | null;
+    deleted: boolean;
+    previous: string | null;
+    unavailable: boolean;
+};
+export type HistoryIndexHit = {
+    record: HistoryIndexRecord;
+    excerpt: string;
+    line: number | null;
+};
+export type HistoryIndexPage = {
+    status: HistoryIndexProgress;
+    hits: Array<HistoryIndexHit>;
+    next: string | null;
+    reset: boolean;
+};
+export type HistoryIndexContext = {
+    text: string;
+    start: number;
+    end: number;
+    before: boolean;
+    after: boolean;
+};
+export type HistoryIndexValue = HistoryIndexProgress | HistoryIndexPage | HistoryIndexContext;

package/dist/native-history-index-protocol.js

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

package/dist/native-history-index.d.ts

@@ -0,0 +1,6 @@
+import type { HistoryIndexCommand, HistoryIndexValue } from "./native-history-index-protocol";
+export type * from "./native-history-index-protocol";
+/** Already admitted to one vault; observers never own indexing or capture. */
+export interface NativeHistoryIndex {
+    call(command: HistoryIndexCommand): Promise<HistoryIndexValue>;
+}

package/dist/native-history-index.js

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

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

@@ -0,0 +1,63 @@
+import type { SearchChunkingSettings } from "./native-database-protocol";
+export type ProjectionContribution = {
+    projection_id: string;
+    owner_plugin_id: string;
+    schema_version: number;
+    configuration_hash: string;
+    path_prefix: string | null;
+};
+export type SearchProviderContribution = {
+    provider_id: string;
+    version: string;
+    priority: number;
+};
+export type SearchIndexingSelection = {
+    providers: Array<SearchProviderContribution>;
+    chunking: SearchChunkingSettings;
+};
+export type IndexingCommand = {
+    kind: "select_metadata";
+} | {
+    kind: "select_search";
+    selection: SearchIndexingSelection;
+} | {
+    kind: "disable_search";
+} | {
+    kind: "register_processor";
+    owner_plugin_id: string;
+    extension: string;
+} | {
+    kind: "register_projection";
+    contribution: ProjectionContribution;
+} | {
+    kind: "disable_projection";
+    projection_id: string;
+} | {
+    kind: "refresh";
+    rebuild: boolean;
+} | {
+    kind: "status";
+};
+export type IndexingPhase = "idle" | "discovering" | "metadata" | "tasks" | "docs" | "search";
+export type IndexingStatus = {
+    passes: number;
+    indexed: number;
+    deleted: number;
+    pending: number;
+    error: string | null;
+    active: boolean;
+    processed: number;
+    total: number;
+    phase: IndexingPhase;
+    completed_at?: number;
+};
+export type ContributionPlacement = "native" | "client_dependent";
+export type ContributionStatus = {
+    projection_id: string;
+    placement: ContributionPlacement;
+    message: string | null;
+};
+export type IndexingValue = {
+    status: IndexingStatus | null;
+    contribution: ContributionStatus | null;
+};

package/dist/native-indexing-protocol.js

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