@kanf/wema-kake 0.0.0-stage → 0.1.1

package/dist/lib/worker/page-do.d.ts

@@ -0,0 +1,330 @@
+import { DurableObject } from 'cloudflare:workers';
+import type { WemaKakeEnv } from './config';
+import { type OpSummary, type PageSummary, type RevertOutcome } from '../shared/api';
+import { type BoardContent, type HistoryDelta, type Snapshot } from '../shared/delta';
+import type { BoardState } from '../shared/tools';
+import { type ChildRejectCode } from '../shared/hierarchy';
+/** Worker が WebSocket の接続要求を DO へ転送するときに、認証済みの主体を入れるヘッダー */
+export declare const ACTOR_HEADER = "X-Wema-Actor";
+/** 同じく、認証の期限（UNIX 秒）を入れるヘッダー。期限がなければ付けない */
+export declare const AUTH_EXPIRES_HEADER = "X-Wema-Auth-Expires";
+export interface ApplyInput {
+    /** 'user:<email>' / 'agent:<client>'。呼び出し側（Worker）が認証結果から決める */
+    actor: string;
+    clientId: string;
+    opId: string;
+    /** 外から来た値をそのまま渡す。検証は applyOps が行う */
+    deltas: unknown;
+    summary?: string;
+    /** ページがまだ作られていなければ、適用せずに断る（MCP のツールはページを作らない） */
+    mustExist?: boolean;
+}
+/** ページがないときの `reason`。Worker は、これを 404 にする */
+export declare const REASON_PAGE_NOT_FOUND = "page not found";
+export interface ReceiveInput extends Pick<ApplyInput, 'actor' | 'clientId' | 'opId'> {
+    /** 置く付箋と、その間の接続線。外から来た値をそのまま渡す。検証は receiveNotes が行う */
+    notes: unknown;
+    edges: unknown;
+    /** 付箋が元あったページ（操作の履歴の要約に出す） */
+    from: string;
+}
+export type ApplyResult = {
+    ok: true;
+    seq: number;
+    /** 適用して記録したデルタ。全員に配信する。すべて捨てた場合は空で、seq は進まない */
+    deltas: HistoryDelta[];
+    /** 送信元だけが追加で適用するデルタ（サニタイズで変わった text など） */
+    fixups: HistoryDelta[];
+    /**
+     * 接続中のクライアントへ配信したか。配信しないのは、同じ opId の再送（適用済み）と、
+     * デルタをすべて捨てた場合。WebSocket の送信元には、このとき個別に確定を返す
+     */
+    broadcast: boolean;
+} | {
+    ok: false;
+    reason: string;
+    current?: BoardContent;
+};
+export interface RevertInput {
+    /** 取り消す操作の seq */
+    seq: number;
+    /** 取り消しを行う主体。呼び出し側（Worker）が認証結果から決める */
+    actor: string;
+    clientId: string;
+    opId: string;
+    /** 自分（同じ主体）の操作だけを取り消せるようにする。MCP の revert_operation で使う */
+    ownOnly?: boolean;
+    /** 一覧に出す説明。省略すると、取り消しを表す符号（src/shared/op-summary.ts） */
+    summary?: string;
+}
+/**
+ * 取り消せなかった理由の分類。
+ * - not-found: 対象の操作がない（間引かれた場合を含む）
+ * - conflict: すでに取り消されている
+ * - forbidden: `ownOnly` で、他の主体の操作を指定した
+ * - invalid: 入力が不正
+ */
+export type RevertFailure = 'not-found' | 'conflict' | 'forbidden' | 'invalid';
+export type RevertResult = ({
+    ok: true;
+} & RevertOutcome) | {
+    ok: false;
+    code: RevertFailure;
+    reason: string;
+};
+/** ページ 1 つ分の付箋・接続線・操作履歴を持つ */
+export declare class PageDO extends DurableObject<WemaKakeEnv> {
+    /** 適用済みのスキーマのバージョン。0 は一度も書き込まれていないページ */
+    private version;
+    /** ページを削除するたびに増える。削除の前に受け付けた書き込みを、削除の後に実行しないために使う */
+    private generation;
+    /** 実行中、または順番を待っている削除の数 */
+    private deleting;
+    /** 今まさに子にしようとしているページ（adoptChildren の実行中）。互いを同時に子にするのを断る */
+    private adopting;
+    /** 処理中の applyOps。次の呼び出しはこれが終わってから始める */
+    private applyQueue;
+    constructor(ctx: DurableObjectState, env: WemaKakeEnv);
+    private get sql();
+    /** スキーマがある（version > 0）ときだけ呼ぶ */
+    private getMeta;
+    private setMeta;
+    private readVersion;
+    /** スキーマを最新にする。書き込みの前に呼ぶ */
+    private migrate;
+    /** 表示名、ページの色、epoch を伝えるメッセージ。スキーマがある（version > 0）ときだけ呼ぶ */
+    private metaJson;
+    /** スキーマがある（version > 0）ときだけ呼ぶ */
+    private getSeq;
+    getSnapshot(): Snapshot;
+    /** agent（MCP）に渡すボード。付箋には作成者が付く。ページがまだ作られていなければ null */
+    getBoardState(): BoardState | null;
+    /**
+     * 表示名を変える。空文字なら未設定に戻す（表示はスラッグになる）。
+     * 付箋のデルタではないので ops には記録しない。
+     *
+     * まだ作られていないページに呼ぶと、ページができる。`mustExist` なら、作らずに断る
+     * （一覧の画面からの変更。古い一覧に残っている削除済みのページを、作り直さないため）
+     */
+    setTitle(input: unknown, options?: {
+        mustExist?: boolean;
+    }): {
+        ok: true;
+        title: string | null;
+    } | {
+        ok: false;
+        reason: 'invalid title' | typeof REASON_PAGE_NOT_FOUND;
+    };
+    /**
+     * ページの色を変える。null なら、付けていない状態に戻す。表示名と同じく、ops には記録しない。
+     * まだ作られていないページと、削除の途中のページには、付けない（色を選んだだけで、ページを
+     * 作らない。削除されたページを、古いタブから作り直さない）
+     */
+    setColor(input: unknown, actor?: string): Promise<{
+        ok: true;
+        color: string | null;
+    } | {
+        ok: false;
+        reason: 'invalid color' | typeof REASON_PAGE_NOT_FOUND;
+    }>;
+    /** 親ページにある自分の付箋を、このページの色にする。失敗しても、例外にしない */
+    private recolorOwnNote;
+    /**
+     * 色を変える。親ページにある付箋の色は、変えない（`setColor` との違い）。親ページの DO が、
+     * 子ページの付箋の色を変えた後に、子ページへ呼ぶ（matchChildColors）。書き込みの順番待ちに入れない
+     */
+    setOwnColor(input: unknown): {
+        ok: true;
+        color: string | null;
+    } | {
+        ok: false;
+        reason: 'invalid color' | typeof REASON_PAGE_NOT_FOUND;
+    };
+    /**
+     * 親をたどるための情報と、付箋の数。ページがなければ null。
+     * 索引（D1）への反映を待たずに読めるので、作ったばかりのページの概要にも使う
+     */
+    getPageRef(): {
+        title: string | null;
+        color: string | null;
+        parent: string | null;
+        noteCount: number;
+    } | null;
+    /**
+     * ページの概要（子ページの付箋の表示に使うもの）。ページがなければ null。
+     * 索引（D1）への反映を待たないので、変更の直後でも、今の付箋の数と配置が入る
+     */
+    getSummary(): Omit<PageSummary, 'name'> | null;
+    /** このページを `parent` の子にする。すでに別の親があるか、輪になるなら、理由を返す。置けたら null */
+    setParent(parent: string): ChildRejectCode | null;
+    /** `parent` の子であれば、ルートへ戻す */
+    clearParent(parent: string): void;
+    /** このページのスラッグ */
+    private slug;
+    /** 先祖のページ（親、その親、…の順）。上限を超えてたどらない。パンくずと、輪の検査に使う */
+    ancestors(): Promise<{
+        name: string;
+        title: string | null;
+    }[]>;
+    /**
+     * `wanted`（新しく置こうとしている子ページ）を、このページの子にする。
+     * 置けないものが 1 つでもあれば、すべて取りやめて、理由を返す。置けたら null を返す
+     */
+    private adoptChildren;
+    /**
+     * このページを根とする部分木が、`levels` 段に収まるか。子ページの DO を順にたどるので、
+     * 直前の変更も反映される（D1 の索引は、変更の数秒後にしか反映されない）
+     */
+    fitsWithin(levels: number): Promise<boolean>;
+    /**
+     * `candidates` のうち、子ページの付箋がもうないページを、ルートへ戻す。
+     * 失敗しても、書き込みは取り消さない。食い違いは、次の索引の更新（reconcileChildren）で直す
+     */
+    private releaseOrphans;
+    /**
+     * 子ページの付箋の増減を伴う書き込みを行う。`run` の前に、新しく置く子ページを子にし、
+     * 後に、付箋がなくなった子ページをルートへ戻す。置けなければ、`run` を呼ばずに `rejected` を返す
+     */
+    private withChildren;
+    /**
+     * 子ページの付箋の色と、子ページの色をそろえる。`applied` は、適用して記録したデルタ
+     * （断られた変更と、今と同じ色への変更は、入っていない）。
+     *
+     * - 子ページの付箋の色を変えたら、子ページの色を、その色にする
+     * - 子ページの付箋を置いたら（Undo や取り消しで戻したときも）、付箋の色を、子ページの色にする。
+     *   子ページに色が付いていなければ、付箋の色のままにする
+     *
+     * 失敗しても、書き込みは取り消さない。食い違いは、子ページの次の索引の更新か、子ページの色の
+     * 選び直しで直る（どちらも、付箋を子ページの色に合わせる）
+     */
+    private matchChildColors;
+    /**
+     * 子ページ `page` の付箋の色を、子ページの今の色にする。付箋の更新として記録するので、
+     * 開いているブラウザにも届く。色は、順番待ちに入ってから、子ページへ聞く（呼び出しが前後しても、
+     * 最後に子ページの今の色になる）
+     *
+     * @param resetUnset 子ページに色が付いていないときに、付箋を既定の色へ戻すか
+     */
+    recolorChildNotes(page: string, actor: string, resetUnset: boolean): Promise<void>;
+    private recolorChildNotesInOrder;
+    /**
+     * ページを削除する前に、階層から外す。親ページにある自分の付箋を消し、子ページはルートへ戻す
+     * （子孫ごとの削除はしない）。失敗しても削除は続ける。残った食い違いは、付箋の側が
+     * 「削除済み」と表示され、親ページの索引の更新（reconcileChildren）でも直る
+     */
+    private detachFromHierarchy;
+    /**
+     * 子ページ `page` の付箋を、このページから消す（子ページが削除されたとき）。
+     * 付箋の削除として記録するので、開いているブラウザにも届く
+     */
+    removeChildNotes(page: string, actor: string): Promise<void>;
+    /**
+     * ページを新しく作る。すでにあれば何もしない（既存のページの表示名を書き換えない）。
+     * 付箋を書き込めばページはできるので、これは表示名だけのページを先に作るためのもの。
+     */
+    createPage(input: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'exists' | 'invalid title';
+    };
+    /**
+     * ページを、付箋と接続線を置いた状態で作り、D1 の索引にも反映する（最初のページ用。作った直後の
+     * 一覧に出すため、索引への反映を待つ）。すでにあれば何もせず、false を返す
+     */
+    createWithContent(title: string, deltas: HistoryDelta[]): Promise<boolean>;
+    /**
+     * ページを削除する。付箋、接続線、履歴、表示名と、D1 の索引を消す。取り消しはできない。
+     * 貼った画像は R2 に残る（どのページの画像かを記録していない）。
+     */
+    deletePage(actor?: string): Promise<void>;
+    /**
+     * 書き込みを順番待ちに入れる。待っている間にページの削除が始まるか済んでいたら、
+     * 実行せずに `deleted` を返す。
+     */
+    private write;
+    /**
+     * 変更から少し後に、まとめて D1 へ反映する（書き込みごとには反映しない）。
+     * alarm が設定済みなら何もしない。alarm の実行中は未設定に見えるので、反映中に届いた変更は
+     * 次の alarm で反映される。
+     */
+    private scheduleIndexing;
+    /** 失敗して例外で終わると、ランタイムが間隔を空けて再実行する */
+    alarm(): Promise<void>;
+    /**
+     * D1 の索引へ反映する。書き込みや削除と同じ順番待ちに入れる（索引の書き込みが、ページの削除と
+     * 前後しないようにする）
+     */
+    private reindexInOrder;
+    /** 保持期間を過ぎた ops を消す。直近の分は期間を過ぎていても残す */
+    private pruneOps;
+    private reindex;
+    /**
+     * 親ページがもうなければ、ルートへ戻る。親ページの削除のときに、clearParent が届かなかった場合に
+     * 効く（そのままだと、存在しない親を指したままで、一覧に出ない）。次の索引の更新で、D1 にも反映する
+     */
+    private healParent;
+    /**
+     * 索引の上ではこのページの子なのに、子ページの付箋がないページを、ルートへ戻す。
+     * 付箋を消した後の clearParent が失敗した場合の、食い違いを直す
+     */
+    private reconcileChildren;
+    /**
+     * 唯一の書き込み口。ブラウザ（WebSocket）からも MCP からも、これを通して変更する。
+     *
+     * サニタイズは非同期で、かかる時間が text によって違う。待っている間に後続の呼び出しが
+     * 先に保存まで進むと、同じクライアントの操作が送信順に適用されなくなる（作成より先に
+     * その付箋の更新が処理されるなど）ので、呼び出しを 1 つずつ順に処理する。
+     */
+    applyOps(input: ApplyInput): Promise<ApplyResult>;
+    /**
+     * 他のページから移す（写す）付箋と、その間の接続線を受け取って置く。互いの位置関係は保ち、
+     * 今ある付箋の下に置く（送る側は、このページの付箋の位置を知らない）。
+     * ページがまだ作られていなければ、作らずに断る。
+     */
+    receiveNotes(input: ReceiveInput): Promise<ApplyResult>;
+    /** 前の書き込みが終わってから `run` を始める */
+    private inOrder;
+    /** 同じ送信元の同じ操作が記録済みなら、その行を返す */
+    private findOp;
+    /**
+     * 適用したデルタを ops に記録し、seq を進める。`transactionSync` の中で呼ぶこと。
+     * 戻り値の `deliver` は、トランザクションが確定してから呼ぶ（接続中のクライアントへの配信）。
+     */
+    private recordOp;
+    /**
+     * @param prepare 検証の済んだデルタを、適用する前に書き換える（今あるボードに合わせた位置決めなど）。
+     *   同じ操作の再送（適用済み）では、呼ばない
+     * @param matchColors 適用した後に、子ページの色と、その付箋の色をそろえる（matchChildColors）
+     */
+    private applyOpsInOrder;
+    /**
+     * 最近の操作を新しい順に返す。`agentOnly` なら agent（MCP 経由）の操作に、
+     * `actor` を指定するとその主体の操作に絞る。
+     */
+    listOps(options?: {
+        limit?: number;
+        agentOnly?: boolean;
+        actor?: string;
+    }): OpSummary[];
+    /**
+     * 記録済みの操作を取り消す。逆向きのデルタを新しい操作として適用する。
+     * その後に変更された付箋や接続線は取り消さず、`skipped` で返す（部分適用）。
+     */
+    revert(input: RevertInput): Promise<RevertResult>;
+    private revertInOrder;
+    /** Worker が認証を済ませ、主体を ACTOR_HEADER に入れて転送してくる */
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /** 接続直後の同期。`lastSeq` 以降の ops が残っていれば差分を、なければスナップショットを返す */
+    private onHello;
+    /** `lastSeq` 以降の変更を、差分（ops の再送）で返せるか */
+    private canReplay;
+    private onOps;
+    /**
+     * hello を済ませた全接続へ送る。`sender` を指定すると、その送信元の接続にだけ
+     * `toSender` を送る（null なら送らない）。clientId はクライアントの自己申告なので、
+     * 送信元かどうかは主体も合わせて判定する
+     */
+    private broadcast;
+}