@skillre/dsh-plugin-sticky-wall 0.0.0-stage → 0.2.1

package/lib/store.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Durable note store over the DSH storage domain.
+ *
+ * The Host owns all data: the Client renders snapshots and submits intents, and
+ * every write goes through {@link StickyWallStore} — validate, persist, then
+ * hand back the changed records. The storage domain provides a single
+ * per-domain write chain, so concurrent writes cannot interleave, and its
+ * `per-record` layout keeps one file per note: one damaged record cannot take
+ * the whole wall down.
+ *
+ * The domain spec is mirrored structurally instead of imported: importing
+ * `@deepseek-ai/dsh-storage-domain` would install a second copy of the domain
+ * package (and its zod) inside the plugin instead of resolving the host's. The
+ * mirrored shape is the contract the live Host validates at `open()`:
+ * `{ name, version, layout, invalidRecords, tables: { <name>: { valueSchema } } }`
+ * with zod record schemas.
+ */
+import { z } from 'zod';
+import { type Note, type NoteInput, type NoteLayout, type NotePatch } from './types.js';
+/** Failure carrying a stable code the transport maps onto the RPC envelope. */
+export declare class WallError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/** The domain declaration handed to `ctx.storageDomain.open()`. */
+export declare const DOMAIN_SPEC: {
+    name: string;
+    version: number;
+    layout: "per-record";
+    invalidRecords: "backup-and-skip";
+    tables: {
+        notes: {
+            valueSchema: z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodDefault<z.ZodString>;
+                body: z.ZodString;
+                tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                color: z.ZodDefault<z.ZodEnum<{
+                    yellow: "yellow";
+                    pink: "pink";
+                    green: "green";
+                    blue: "blue";
+                    purple: "purple";
+                    orange: "orange";
+                }>>;
+                pinned: z.ZodDefault<z.ZodBoolean>;
+                archived: z.ZodDefault<z.ZodBoolean>;
+                createdAt: z.ZodString;
+                updatedAt: z.ZodString;
+                layout: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    rotate: z.ZodNumber;
+                    width: z.ZodEnum<{
+                        sm: "sm";
+                        md: "md";
+                        lg: "lg";
+                    }>;
+                }, z.core.$strip>>>;
+            }, z.core.$loose>;
+        };
+    };
+};
+/** The minimal domain table face this store uses; the rest is unused here. */
+export interface DomainTable {
+    get(key: string): unknown;
+    entries(): Iterable<[string, unknown]>;
+    keys(): Iterable<string>;
+    readonly size: number;
+    put(key: string, value: Note): Promise<void>;
+    update(key: string, transform: (value: Note) => Note): Promise<Note>;
+    delete(key: string): Promise<boolean>;
+}
+/** The opened-domain handle the facility returns. */
+export interface DomainHandle {
+    table(name: string): DomainTable;
+    close(): Promise<void>;
+}
+/** The store facade the Host endpoint and the agent tool share. */
+export declare class StickyWallStore {
+    private readonly domain;
+    private readonly maxNotes;
+    private readonly now;
+    private readonly notes;
+    private closed;
+    /**
+     * Store-level mutation chain.
+     *
+     * The storage domain serializes its own writes, but a read-then-write pair
+     * (the `maxNotes` check followed by the `put`) is two steps: two concurrent
+     * creates at the boundary would both read the pre-write count and both
+     * succeed. Every mutation therefore runs on this chain, so each check and its
+     * write are one indivisible step.
+     */
+    private chain;
+    constructor(domain: DomainHandle, maxNotes: number, now?: () => Date);
+    /** Open one domain and wrap it in a store. */
+    static open(open: (spec: typeof DOMAIN_SPEC) => Promise<DomainHandle>, options: {
+        maxNotes: number;
+        seedWelcomeNote: boolean;
+        now?: () => Date;
+    }): Promise<StickyWallStore>;
+    /** Release the domain handle; later writes fail instead of silently dropping. */
+    close(): Promise<void>;
+    private assertOpen;
+    /** Queue one mutation so its checks and writes cannot interleave with another. */
+    private mutate;
+    private liveCount;
+    /**
+     * Reject a write that would take the live (non-archived) note count past
+     * `maxNotes`.
+     *
+     * Every path that can make a note live goes through this — `create`, an
+     * `update` that unarchives, and a batch restore — because the documented cap
+     * is an invariant of the wall, not a hint on the create form.
+     */
+    private assertRoom;
+    /** Write the one-time welcome note on a brand-new wall. */
+    private seedWelcomeNote;
+    /** Every stored note, newest-relevant first; archived ones only on request. */
+    list(includeArchived?: boolean, sort?: 'pinned' | 'created' | 'updated'): Note[];
+    /** Create one note from a Client or agent submission. */
+    create(input: NoteInput, id?: string): Promise<Note>;
+    private createNow;
+    /** Apply one patch; `updatedAt` moves only when a field actually changed. */
+    update(id: string, patch: NotePatch): Promise<Note>;
+    private updateNow;
+    /**
+     * Flip the archived flag on a batch; returns the notes that actually moved.
+     *
+     * Every id is resolved BEFORE the first write: a missing id rejects the whole
+     * request, so a bad batch cannot leave half the selection archived while the
+     * Client still believes the mutation failed.
+     */
+    setArchived(ids: string[], archived: boolean): Promise<Note[]>;
+    private setArchivedNow;
+    /**
+     * Delete a batch; returns the ids that were removed.
+     *
+     * The whole selection is resolved before the first delete, so a request
+     * naming an absent note changes nothing: a caller is never told the batch
+     * failed while part of it was already applied. Batch semantics match
+     * {@link setArchived}.
+     */
+    remove(ids: string[]): Promise<string[]>;
+    private removeNow;
+    /**
+     * Move one card on the free canvas.
+     *
+     * Moving is its own operation rather than an `update` patch: it deliberately
+     * does NOT bump `updatedAt`, because rearranging a wall is not editing a
+     * note's content and must not reshuffle a "by updated" sort. The write is
+     * still serialised on the mutation chain so two drags cannot race.
+     */
+    move(id: string, layout: NoteLayout): Promise<Note>;
+    private moveNow;
+    /**
+     * Tidy the wall: repack every note into a deterministic shelf arrangement.
+     *
+     * Returns only the notes that actually moved, so the Client can reconcile
+     * without refetching the whole wall, and pressing tidy on an already-tidy
+     * wall is a no-op instead of a write storm.
+     */
+    arrange(): Promise<Note[]>;
+    private arrangeNow;
+    /**
+     * Permanently remove every archived note.
+     *
+     * The archived set is read once and deleted in order; a delete failure stops
+     * the sweep and surfaces, leaving the remaining archived notes intact rather
+     * than reporting a clean sweep that did not happen.
+     */
+    clearArchived(): Promise<string[]>;
+    private clearArchivedNow;
+    /** Compact plain-text digest of the wall for the model-facing tool. */
+    summary(limit?: number): {
+        total: number;
+        archived: number;
+        notes: Note[];
+    };
+}

package/lib/store.js

@@ -0,0 +1,452 @@
+/**
+ * Durable note store over the DSH storage domain.
+ *
+ * The Host owns all data: the Client renders snapshots and submits intents, and
+ * every write goes through {@link StickyWallStore} — validate, persist, then
+ * hand back the changed records. The storage domain provides a single
+ * per-domain write chain, so concurrent writes cannot interleave, and its
+ * `per-record` layout keeps one file per note: one damaged record cannot take
+ * the whole wall down.
+ *
+ * The domain spec is mirrored structurally instead of imported: importing
+ * `@deepseek-ai/dsh-storage-domain` would install a second copy of the domain
+ * package (and its zod) inside the plugin instead of resolving the host's. The
+ * mirrored shape is the contract the live Host validates at `open()`:
+ * `{ name, version, layout, invalidRecords, tables: { <name>: { valueSchema } } }`
+ * with zod record schemas.
+ */
+import { z } from 'zod';
+import { arrangeLayouts, clampLayout, normalizeWidth, sameLayout } from './layout.js';
+import { COLORS, WIDTHS, DOMAIN_NAME, DOMAIN_VERSION, LIMITS, } from './types.js';
+/** Failure carrying a stable code the transport maps onto the RPC envelope. */
+export class WallError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'WallError';
+    }
+}
+/** Record schema; every stored note is validated at domain open and on write. */
+const NoteSchema = z
+    .object({
+    id: z.string().min(1).max(128),
+    title: z.string().max(LIMITS.title).default(''),
+    body: z.string().min(1).max(LIMITS.body),
+    tags: z.array(z.string().min(1).max(LIMITS.tag)).max(LIMITS.tags).default([]),
+    color: z.enum(COLORS).default('yellow'),
+    pinned: z.boolean().default(false),
+    archived: z.boolean().default(false),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+    // `null` means "never placed": the Client derives a preview position from
+    // the note id. A stored layout is owned by the Host, so a wall opened in
+    // two windows shows the same arrangement.
+    layout: z
+        .object({
+        x: z.number(),
+        y: z.number(),
+        rotate: z.number(),
+        width: z.enum(WIDTHS),
+    })
+        .nullable()
+        .default(null),
+})
+    .passthrough();
+/** The domain declaration handed to `ctx.storageDomain.open()`. */
+export const DOMAIN_SPEC = {
+    name: DOMAIN_NAME,
+    version: DOMAIN_VERSION,
+    layout: 'per-record',
+    invalidRecords: 'backup-and-skip',
+    tables: { notes: { valueSchema: NoteSchema } },
+};
+/** Normalize one tag: trim, lowercase, collapse inner whitespace, bound length. */
+function normalizeTag(raw) {
+    const value = String(raw ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+    return value.slice(0, LIMITS.tag);
+}
+/** Normalize a submitted tag list: drop empties, deduplicate, cap the count. */
+function normalizeTags(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const tag = normalizeTag(entry);
+        if (tag === '' || seen.has(tag))
+            continue;
+        seen.add(tag);
+        if (seen.size >= LIMITS.tags)
+            break;
+    }
+    return [...seen];
+}
+/** Validate and trim a note body; a live note may not be blank. */
+function normalizeBody(raw) {
+    const value = String(raw ?? '').replace(/\r\n?/g, '\n').trim();
+    if (value === '')
+        throw new WallError('empty-body', 'A note needs some text.');
+    if (value.length > LIMITS.body)
+        throw new WallError('body-too-long', `A note is limited to ${LIMITS.body} characters.`, { limit: LIMITS.body, length: value.length });
+    return value;
+}
+/** Validate and trim a title; an absent title is the empty string. */
+function normalizeTitle(raw) {
+    const value = String(raw ?? '').replace(/\r\n?/g, ' ').trim();
+    if (value.length > LIMITS.title)
+        throw new WallError('title-too-long', `A note title is limited to ${LIMITS.title} characters.`, { limit: LIMITS.title, length: value.length });
+    return value;
+}
+/** Accept only a declared pastel key. */
+function normalizeColor(raw) {
+    const value = String(raw ?? '');
+    const match = COLORS.find((color) => color === value);
+    if (match === undefined)
+        throw new WallError('invalid-color', `Unknown note color ${JSON.stringify(value)}.`, { colors: [...COLORS] });
+    return match;
+}
+/** Validate and clamp a submitted placement; `null` clears it back to derived. */
+function normalizeLayout(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== 'object')
+        throw new WallError('invalid-layout', 'A note placement must be an object.');
+    const value = raw;
+    const x = Number(value.x);
+    const y = Number(value.y);
+    const rotate = Number(value.rotate ?? 0);
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(rotate)) {
+        throw new WallError('invalid-layout', 'A note placement needs finite x, y and rotate values.');
+    }
+    return clampLayout({ x, y, rotate, width: normalizeWidth(value.width) });
+}
+/** Reject ids that are not plausible note keys before touching storage. */
+function assertIds(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new WallError('invalid-ids', 'Select at least one note.');
+    if (raw.length > LIMITS.bulk)
+        throw new WallError('too-many-ids', `At most ${LIMITS.bulk} notes per request.`, { limit: LIMITS.bulk });
+    const ids = [...new Set(raw.map((id) => String(id ?? '')))];
+    if (ids.some((id) => id === '' || id.length > 128))
+        throw new WallError('invalid-ids', 'One of the selected note ids is invalid.');
+    return ids;
+}
+/**
+ * One record's sort weight: pinned first, then the requested ordering, with the
+ * id as a final tiebreaker so two notes written in the same millisecond still
+ * render in a stable order.
+ */
+function compareNotes(sort) {
+    return (left, right) => {
+        if (left.pinned !== right.pinned)
+            return left.pinned ? -1 : 1;
+        if (sort === 'created') {
+            return right.createdAt.localeCompare(left.createdAt) || right.updatedAt.localeCompare(left.updatedAt) || left.id.localeCompare(right.id);
+        }
+        return right.updatedAt.localeCompare(left.updatedAt) || left.id.localeCompare(right.id);
+    };
+}
+/** The store facade the Host endpoint and the agent tool share. */
+export class StickyWallStore {
+    domain;
+    maxNotes;
+    now;
+    notes;
+    closed = false;
+    /**
+     * Store-level mutation chain.
+     *
+     * The storage domain serializes its own writes, but a read-then-write pair
+     * (the `maxNotes` check followed by the `put`) is two steps: two concurrent
+     * creates at the boundary would both read the pre-write count and both
+     * succeed. Every mutation therefore runs on this chain, so each check and its
+     * write are one indivisible step.
+     */
+    chain = Promise.resolve();
+    constructor(domain, maxNotes, now = () => new Date()) {
+        this.domain = domain;
+        this.maxNotes = maxNotes;
+        this.now = now;
+        this.notes = domain.table('notes');
+    }
+    /** Open one domain and wrap it in a store. */
+    static async open(open, options) {
+        const domain = await open(DOMAIN_SPEC);
+        const store = new StickyWallStore(domain, options.maxNotes, options.now ?? (() => new Date()));
+        if (options.seedWelcomeNote)
+            await store.seedWelcomeNote();
+        return store;
+    }
+    /** Release the domain handle; later writes fail instead of silently dropping. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.domain.close();
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new WallError('closed', 'The note wall is shutting down.');
+    }
+    /** Queue one mutation so its checks and writes cannot interleave with another. */
+    mutate(job) {
+        const result = this.chain.then(job);
+        this.chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    liveCount() {
+        let count = 0;
+        for (const [, note] of this.notes.entries())
+            if (!note.archived)
+                count += 1;
+        return count;
+    }
+    /**
+     * Reject a write that would take the live (non-archived) note count past
+     * `maxNotes`.
+     *
+     * Every path that can make a note live goes through this — `create`, an
+     * `update` that unarchives, and a batch restore — because the documented cap
+     * is an invariant of the wall, not a hint on the create form.
+     */
+    assertRoom(incomingLive) {
+        if (incomingLive <= 0)
+            return;
+        const projected = this.liveCount() + incomingLive;
+        if (projected > this.maxNotes) {
+            throw new WallError('wall-full', `The wall already holds ${this.maxNotes} notes; archive or delete one first.`, {
+                limit: this.maxNotes,
+                projected,
+            });
+        }
+    }
+    /** Write the one-time welcome note on a brand-new wall. */
+    async seedWelcomeNote() {
+        if (this.notes.size > 0)
+            return;
+        const stamp = this.now().toISOString();
+        const note = {
+            id: 'welcome',
+            title: '便签墙',
+            body: '随手记下一闪而过的灵感，或一件临时的工作。点右下角的 + 新建一张便签；按 ⌘/Ctrl + Enter 保存。',
+            tags: ['开始'],
+            color: 'yellow',
+            pinned: true,
+            archived: false,
+            createdAt: stamp,
+            updatedAt: stamp,
+            // The one note the plugin places itself, so a brand-new wall opens with a
+            // card that is obviously meant to be dragged.
+            layout: { x: 120, y: 96, rotate: -1.6, width: 'md' },
+        };
+        await this.notes.put(note.id, note);
+    }
+    /** Every stored note, newest-relevant first; archived ones only on request. */
+    list(includeArchived = false, sort = 'pinned') {
+        this.assertOpen();
+        const notes = [];
+        for (const [, note] of this.notes.entries()) {
+            const value = note;
+            if (value.archived && !includeArchived)
+                continue;
+            notes.push(value);
+        }
+        return notes.sort(compareNotes(sort));
+    }
+    /** Create one note from a Client or agent submission. */
+    async create(input, id) {
+        this.assertOpen();
+        return this.mutate(() => this.createNow(input, id));
+    }
+    async createNow(input, id) {
+        const body = normalizeBody(input?.body);
+        const title = normalizeTitle(input?.title);
+        this.assertRoom(1);
+        const stamp = this.now().toISOString();
+        const note = {
+            id: id ?? globalThis.crypto.randomUUID(),
+            title,
+            body,
+            tags: normalizeTags(input?.tags),
+            color: input?.color === undefined ? 'yellow' : normalizeColor(input.color),
+            pinned: input?.pinned === true,
+            archived: false,
+            createdAt: stamp,
+            updatedAt: stamp,
+            layout: input?.layout === undefined ? null : normalizeLayout(input.layout),
+        };
+        if (this.notes.get(note.id) !== undefined)
+            throw new WallError('duplicate-id', `A note with id ${JSON.stringify(note.id)} already exists.`);
+        await this.notes.put(note.id, note);
+        return note;
+    }
+    /** Apply one patch; `updatedAt` moves only when a field actually changed. */
+    async update(id, patch) {
+        this.assertOpen();
+        return this.mutate(() => this.updateNow(id, patch));
+    }
+    async updateNow(id, patch) {
+        const current = this.notes.get(id);
+        if (current === undefined)
+            throw new WallError('not-found', `No note with id ${JSON.stringify(id)}.`, { id });
+        const next = { ...current };
+        if (patch?.body !== undefined)
+            next.body = normalizeBody(patch.body);
+        if (patch?.title !== undefined)
+            next.title = normalizeTitle(patch.title);
+        if (patch?.tags !== undefined)
+            next.tags = normalizeTags(patch.tags);
+        if (patch?.color !== undefined)
+            next.color = normalizeColor(patch.color);
+        if (patch?.pinned !== undefined)
+            next.pinned = patch.pinned === true;
+        if (patch?.archived !== undefined)
+            next.archived = patch.archived === true;
+        // Restoring an archived note makes it live again, so it must fit the cap.
+        if (current.archived && !next.archived)
+            this.assertRoom(1);
+        const changed = ['body', 'title', 'color', 'pinned', 'archived'].some((key) => next[key] !== current[key]) ||
+            JSON.stringify(next.tags) !== JSON.stringify(current.tags);
+        if (!changed)
+            return current;
+        next.updatedAt = this.now().toISOString();
+        return this.notes.update(id, () => next);
+    }
+    /**
+     * Flip the archived flag on a batch; returns the notes that actually moved.
+     *
+     * Every id is resolved BEFORE the first write: a missing id rejects the whole
+     * request, so a bad batch cannot leave half the selection archived while the
+     * Client still believes the mutation failed.
+     */
+    async setArchived(ids, archived) {
+        this.assertOpen();
+        return this.mutate(() => this.setArchivedNow(ids, archived));
+    }
+    async setArchivedNow(ids, archived) {
+        const selected = assertIds(ids);
+        const targets = [];
+        for (const id of selected) {
+            const current = this.notes.get(id);
+            if (current === undefined)
+                throw new WallError('not-found', `No note with id ${JSON.stringify(id)}.`, { id });
+            if (current.archived !== archived)
+                targets.push(current);
+        }
+        // A restore batch makes every target live; check the whole batch up front so
+        // a partial restore can never exceed the cap.
+        if (!archived)
+            this.assertRoom(targets.length);
+        const changed = [];
+        for (const current of targets) {
+            const next = { ...current, archived, updatedAt: this.now().toISOString() };
+            changed.push(await this.notes.update(current.id, () => next));
+        }
+        return changed;
+    }
+    /**
+     * Delete a batch; returns the ids that were removed.
+     *
+     * The whole selection is resolved before the first delete, so a request
+     * naming an absent note changes nothing: a caller is never told the batch
+     * failed while part of it was already applied. Batch semantics match
+     * {@link setArchived}.
+     */
+    async remove(ids) {
+        this.assertOpen();
+        return this.mutate(() => this.removeNow(ids));
+    }
+    async removeNow(ids) {
+        const selected = assertIds(ids);
+        for (const id of selected) {
+            if (this.notes.get(id) === undefined)
+                throw new WallError('not-found', `No note with id ${JSON.stringify(id)}.`, { id });
+        }
+        const removed = [];
+        for (const id of selected) {
+            await this.notes.delete(id);
+            removed.push(id);
+        }
+        return removed;
+    }
+    /**
+     * Move one card on the free canvas.
+     *
+     * Moving is its own operation rather than an `update` patch: it deliberately
+     * does NOT bump `updatedAt`, because rearranging a wall is not editing a
+     * note's content and must not reshuffle a "by updated" sort. The write is
+     * still serialised on the mutation chain so two drags cannot race.
+     */
+    async move(id, layout) {
+        this.assertOpen();
+        return this.mutate(() => this.moveNow(id, layout));
+    }
+    async moveNow(id, layout) {
+        const current = this.notes.get(id);
+        if (current === undefined)
+            throw new WallError('not-found', `No note with id ${JSON.stringify(id)}.`, { id });
+        const next = normalizeLayout(layout);
+        if (sameLayout(current.layout, next))
+            return current;
+        return this.notes.update(id, () => ({ ...current, layout: next }));
+    }
+    /**
+     * Tidy the wall: repack every note into a deterministic shelf arrangement.
+     *
+     * Returns only the notes that actually moved, so the Client can reconcile
+     * without refetching the whole wall, and pressing tidy on an already-tidy
+     * wall is a no-op instead of a write storm.
+     */
+    async arrange() {
+        this.assertOpen();
+        return this.mutate(() => this.arrangeNow());
+    }
+    async arrangeNow() {
+        // Every note, archived ones included. Packing only the live set left an
+        // archived-but-visible card at its dragged position, on top of the freshly
+        // tidied ones — the wall has to be tidy in every filter, not just the
+        // default one.
+        const current = this.list(true, 'pinned');
+        const planned = arrangeLayouts(current);
+        const changed = [];
+        for (const note of current) {
+            const target = planned.get(note.id);
+            if (target === undefined || sameLayout(note.layout, target))
+                continue;
+            changed.push(await this.notes.update(note.id, () => ({ ...note, layout: target })));
+        }
+        return changed;
+    }
+    /**
+     * Permanently remove every archived note.
+     *
+     * The archived set is read once and deleted in order; a delete failure stops
+     * the sweep and surfaces, leaving the remaining archived notes intact rather
+     * than reporting a clean sweep that did not happen.
+     */
+    async clearArchived() {
+        this.assertOpen();
+        return this.mutate(() => this.clearArchivedNow());
+    }
+    async clearArchivedNow() {
+        const archived = this.list(true).filter((note) => note.archived).map((note) => note.id);
+        const removed = [];
+        for (const id of archived) {
+            await this.notes.delete(id);
+            removed.push(id);
+        }
+        return removed;
+    }
+    /** Compact plain-text digest of the wall for the model-facing tool. */
+    summary(limit = 20) {
+        this.assertOpen();
+        const all = this.list(true, 'updated');
+        return {
+            total: all.length,
+            archived: all.filter((note) => note.archived).length,
+            notes: all.slice(0, Math.max(1, Math.min(limit, 50))),
+        };
+    }
+}

package/lib/transport.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Host ↔ Client transport: one exact Fetch route inside Connection's fence.
+ *
+ * Connection owns the Host/Origin check, the browser-session authentication and
+ * the Peer scope; this module registers one exact `POST /api/<endpoint>` route
+ * and only has to validate its own envelope and payload. No physical server, no
+ * Express, and no second RPC channel is claimed.
+ *
+ * The wire envelope is the inspected Connection unary shape:
+ * `{ type: 'client-request', rpcId, method, payload }` in and
+ * `{ type: 'server-response', rpcId, result: { ok: true, value } | { ok: false, error } }`
+ * out. A non-owner Peer is rejected by Connection before this handler runs.
+ */
+import { type Note, type NoteInput, type NoteLayout, type NotePatch, type NoteSort, type WallResult } from './types.js';
+/** Path of the exact route, under the shared `/api` channel. */
+export declare const EXECUTE_PATH = "/api/skillre-sticky-wall/execute";
+/** One buffered exact Fetch route as the Connection registry accepts it. */
+export interface FetchRoute {
+    readonly path: string;
+    readonly methods: readonly ['POST'];
+    readonly requestBody: 'buffered';
+    readonly fetch: (request: Request) => Promise<Response>;
+}
+/** The Host Connection face this plugin depends on. */
+export interface HostConnection {
+    readonly fetch: {
+        register(route: FetchRoute): () => Promise<void>;
+    };
+}
+/** The store operations the route dispatches onto. */
+export interface WallActions {
+    list(includeArchived?: boolean, sort?: NoteSort): Note[];
+    create(input: NoteInput): Promise<Note>;
+    update(id: string, patch: NotePatch): Promise<Note>;
+    setArchived(ids: string[], archived: boolean): Promise<Note[]>;
+    remove(ids: string[]): Promise<string[]>;
+    clearArchived(): Promise<string[]>;
+    move(id: string, layout: NoteLayout): Promise<Note>;
+    arrange(): Promise<Note[]>;
+}
+/**
+ * Build the exact route Connection registers; every failure stays inside the
+ * envelope. `ready` resolves the store lazily so a storage-open failure is
+ * reported on the first request instead of at registration time.
+ */
+export declare function createExecuteRoute(ready: () => Promise<WallActions>): FetchRoute;
+/** Re-export the result envelope type for the Client half's structural mirror. */
+export type { WallResult };