@acornly/adapter-supabase 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Free Solo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @acornly/adapter-supabase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A `StorageAdapter` that keeps Acornly notes in a site's own Supabase project, with no Acornly Cloud involved. The site pays its own Supabase bill and Acornly charges nothing.
+
+The adapter reads and writes as whoever is signed in on the site's Supabase client (Supabase Auth), or as an anonymous visitor when nobody is. Row-level security in the site's database decides what each of them may see and change.
+
+## Set up the database
+
+Run the installer, [`supabase/install.sql`](supabase/install.sql), in the site's project, as the database owner: paste it into the dashboard's SQL editor, or `psql -v ON_ERROR_STOP=1 "$DATABASE_URL" -f node_modules/@acornly/adapter-supabase/supabase/install.sql`. Everything it creates is prefixed with `acornly`, so it sits next to the site's own tables.
+
+The installer is versioned: it holds every migration in [`supabase/migrations`](supabase/migrations), runs in one transaction, and applies only the ones it has not applied before, recording each in `acornly_meta.migrations` with when it ran. So after upgrading the package, run the new `install.sql` again, as it is; nothing needs copying. Its first line names the last migration it holds.
+
+- A project that already has the migrations from `supabase db push` is recognised from the Supabase CLI's history (`supabase_migrations.schema_migrations`), and the installer carries on from there.
+- A project where they were pasted in by hand is refused, since the installer cannot tell which ones it has. Record each file already applied, by the version and name in its file name, then run the installer again:
+
+  ```sql
+  create schema if not exists acornly_meta;
+  create table if not exists acornly_meta.migrations (
+    version text primary key,
+    name text not null,
+    applied_at timestamptz not null default now()
+  );
+  insert into acornly_meta.migrations (version, name) values
+    ('20261005090000', 'contexthive_annotations'),
+    ('20261005130000', 'contexthive_threads');
+  ```
+
+- Pick one way and keep to it: the installer, or your own Supabase CLI migrations. Mixing them applies a migration twice.
+- To keep the schema in your own Supabase CLI migrations instead, copy the files in `supabase/migrations` into the site's `supabase/migrations` and run `supabase db push`, as before. They ship in the npm package too, under `node_modules/@acornly/adapter-supabase/supabase/migrations`.
+
+Then list the scopes the site accepts notes in. Signed-in users can write only to these, plus their own `user:<id>` scope:
+
+```sql
+insert into public.acornly_scopes (scope) values ('app:my-site');
+-- Let visitors who are not signed in read the public notes on these pages:
+insert into public.acornly_scopes (scope, anonymous_read) values ('web:example.com', true);
+```
+
+## Use it
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+import { SupabaseAdapter } from "@acornly/adapter-supabase";
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+const adapter = new SupabaseAdapter({
+  client: supabase,
+  onRealtimeStatus: (status) => console.debug("live updates:", status),
+});
+```
+
+`@supabase/supabase-js` 2.117 or later in 2.x is a peer dependency: the adapter uses the site's client and adds nothing to the bundle for it.
+
+## Access rules
+
+| Who                                | Can read                                       | Can write                                                                   |
+| ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
+| The note's creator                 | Their own notes, always                        | Edit or remove their own notes, in listed scopes or their own `user:` scope |
+| Anyone signed in                   | `public` notes                                 | New notes in listed scopes and their own `user:` scope                      |
+| A visitor who is not signed in     | `public` notes in scopes with `anonymous_read` | Nothing                                                                     |
+| The site's server (`service_role`) | Everything (it bypasses row-level security)    | Any note, setting `creator_id` itself; replies under any note               |
+
+- Supabase's anonymous sign-ins count as visitors who are not signed in, although they have a user id.
+- Two audiences are supported: `private` (only the creator) and `public`. Circles, user lists and links need Acornly Cloud and are refused.
+- Context on context (replies, tags, reactions, highlights on a note) targets its parent: `target.source` is `urn:contexthive:annotation:<encoded parent id>`, and it carries `ext.threadRoot` and `ext.depth`. Add it with `adapter.threads.addChild` (or core's `addContext`). The database checks it against the stored parent, locked for the check: the parent must exist, be readable by the replier and not be deleted, and the child must have its scope, thread root, the next depth, and `ext.parentRev` exactly when it quotes the parent. A child can narrow its parent's audience (a private reply under a public note) but never widen it, on create or on edit. Children nest to any depth.
+- If a note is later narrowed, other people's replies anywhere below it are hidden from everyone who can no longer read it; their creators still see them and can edit (without widening) or delete them. Replies whose parent is gone (its author was deleted) are hidden from everyone but their authors.
+- Plain updates keep the tree: no note moves to another scope, document or thread, `ext.depth`, `ext.parentRev` and a child's target stay, `ext.deleted` changes only through a delete, a deleted placeholder cannot be edited, and a note with replies keeps its `creator.id`. Plain deletes refuse replies and notes with replies, even from the raw Data API.
+- Delete with `adapter.threads.deleteNode` (or core's `deleteContext`), which calls `acornly_delete_node`. Only the author (or the site's server) can delete a note. One with any reply, even one the author cannot see, becomes a placeholder: no body, author name or edited mark, `ext.deleted: true`. One without replies is removed, and so is each placeholder above it left with none, whoever wrote it.
+- Edit history lives in `acornly_versions` (`adapter.versions`). Only the note's author can save, read or clear its versions; removing a note or turning it into a placeholder drops them.
+- Deleting a user removes their notes. Other people's replies under them stay, and are hidden by `assembleThread` since their parent is gone; a reply under a removed thread root goes with it.
+- The database owns `ext.rev`: a note starts at 1 and each update adds one. Every update and remove checks the expected rev, so of two concurrent edits one wins and the other gets a `ConflictError`.
+- The trigger copies `id`, scope, the document, the parent id, audience, `threadRoot` and `modified` out of the stored annotation into indexed columns, so they always agree. Clients can write only the annotation itself, and cannot move a note to another scope, document or thread.
+- A note's document is its `target.source`, or for a note on a PDF the file's key in `ext.documentKey` (`urn:x-pdf:<fingerprint>`), so the same file opened from another URL lists its notes; `target.source` keeps the URL the note was made on. The key is taken when the note is created and kept on every update, whatever the update says.
+- `modified` comes from the client and is what `list({ since })` compares, so a client with a wrong clock can make its edit invisible to other clients' delta syncs. Treat delta sync as a shortcut and resync with a full `list` now and then.
+- Key fields (`id`, `ext.scope`, `target.source`, `modified`, `ext.threadRoot`) must be strings, and `ext.depth` and `ext.parentRev` numbers; the rest of the annotation is stored as sent, so validate notes from other users before trusting their shape.
+- `creator_id` is the signed-in user who created the note, set by the database. Show that as the author: the annotation's own `creator` field is whatever the client sent.
+- Each note is limited to 64 KB of JSON.
+- Ids are chosen by the client, so creating an id that already exists fails even when the existing note is hidden. Use random ids (Acornly's are ULIDs) so this reveals nothing.
+- The site's server code (the `service_role` key, or the owner in SQL) must set `creator_id` itself. A database function the site writes runs its client callers as clients, even when the function is owned by `postgres`. Other roles count as clients too, so triggers that run as Supabase's auth or storage roles, and custom roles, cannot write notes on a user's behalf.
+- `list` reads in pages of 1,000 rows, the Data API's default `max_rows`. Keep `max_rows` at 1,000 or more, or `list` stops after the first page.
+
+## Realtime
+
+`subscribe` listens on a Realtime channel, filtered by document (by scope when the URL has a comma, which Realtime filters cannot match), and Realtime applies the read rules before sending a change. A subscriber hears about its own adapter's writes at once and does not hear them again when Realtime echoes them. A note removed and created again with the same id is told as created again.
+
+Things Realtime does not do, which a site should know:
+
+- **Replies are not followed.** A subscription follows one page, and replies target their parent rather than the page, so subscribers hear about a note turning into a placeholder but not about replies being added or edited. Load threads with `threads.listThread` when they are opened.
+- **Removals reach every subscriber.** Realtime sends only the id of a deleted row and cannot filter deletes, so every subscriber, visitors included, learns the id and time of every removal in the table. An id a subscriber never had is a no-op for the store. Use ids that reveal nothing (Acornly's are random ULIDs).
+- **Losing access is silent.** When a note is narrowed from public to private, or a reply is hidden because its root was narrowed, people who could read it get no event and keep showing it until their next `list`.
+- **Nothing is replayed after a drop.** Changes made while the connection is down are lost. When `onRealtimeStatus` reports `SUBSCRIBED` again after another status, call `list` to catch up.
+- **Changes are checked when sent.** Realtime checks each change against the row as it stands when it sends the change, so an insert followed at once by a delete may arrive only as the delete.
+
+## Develop
+
+The SQL is tested in this package's own Supabase CLI project (`supabase/config.toml`, project `@acornly/adapter-supabase`), on its own ports (API on 54421, database on 54422), so it runs beside the Acornly Cloud stack in `/supabase` without the schemas ever meeting.
+
+```sh
+cd packages/adapter-supabase
+supabase start -x studio,imgproxy,mailpit,logflare,vector,supavisor,edge-runtime,storage-api,postgres-meta
+pnpm test:db   # the shared contract suite and the access-rule tests
+```
+
+A new migration goes in `supabase/migrations`; then regenerate the installer with `pnpm --filter @acornly/adapter-supabase build:install` (`scripts/build-install.mjs`) and commit both. `pnpm test` fails while `install.sql` is out of date (`src/install.test.ts`), and `test/install.test.ts` checks in the stack that it installs the same schema as the migrations, recognises a `supabase db push` project and changes nothing when run again.
+
+`test/contract.test.ts` runs `runAdapterContract` and `runThreadContract` from `@acornly/core/testing` as a signed-in user. `test/access.test.ts` signs in as two users and as an anonymous visitor and checks every rule above, including what Realtime delivers. The tests default to the Supabase CLI's local keys; set `API_URL`, `DB_URL`, `ANON_KEY` and `SERVICE_ROLE_KEY` (for example `eval "$(supabase status -o env)"`) to point at another local stack. They wipe the notes table, the scopes and every `@example.test` or anonymous user, so they refuse a non-local stack unless `ACORNLY_TEST_REMOTE=wipe` is set; never point them at a project with real data. Add a test for every new rule, and break the rule on purpose once to watch it fail.

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { type Annotation, type ChangeEvent, type ListQuery, type StorageAdapter, type ThreadStore, type Unsubscribe, type VersionStore } from "@acornly/core";
+export interface SupabaseAdapterOptions {
+    /**
+     * The site's own Supabase client. The adapter reads and writes as whoever is signed in on it
+     * (Supabase Auth), or as an anonymous visitor when nobody is.
+     */
+    client: SupabaseClient;
+    /**
+     * Table in the `public` schema. Defaults to `acornly_annotations`, as the shipped SQL creates.
+     * Threads and edit history use the shipped functions and `acornly_versions`, which work on
+     * that table only.
+     */
+    table?: string;
+    /**
+     * Called as each subscription's Realtime channel changes state: `SUBSCRIBED` once live changes
+     * flow, or `CHANNEL_ERROR`, `TIMED_OUT` or `CLOSED` with the reason. Realtime retries on its own;
+     * use this to show that live updates are paused.
+     */
+    onRealtimeStatus?: (status: RealtimeStatus, error?: Error) => void;
+}
+export type RealtimeStatus = "SUBSCRIBED" | "TIMED_OUT" | "CLOSED" | "CHANNEL_ERROR";
+/**
+ * Keeps annotations in a site's own Supabase project, in the table the SQL in this package's
+ * `supabase/migrations` creates. Row-level security there decides what each user may read and
+ * write; the database owns `ext.rev` and each write checks it, so concurrent edits conflict
+ * instead of overwriting each other.
+ *
+ * Subscribers hear about this adapter's own writes at once, and about everyone else's through
+ * Supabase Realtime, filtered by the same read rules.
+ */
+export declare class SupabaseAdapter implements StorageAdapter {
+    readonly capabilities: {
+        realtime: boolean;
+        search: boolean;
+        offline: boolean;
+    };
+    private readonly client;
+    private readonly table;
+    private readonly listeners;
+    private readonly onRealtimeStatus;
+    constructor(options: SupabaseAdapterOptions);
+    /** Earlier versions, in `acornly_versions`: only the note's author can save or read them. */
+    readonly versions: VersionStore;
+    /**
+     * Reply threads. The database checks each new child against its locked parent, and deletes run
+     * in `acornly_delete_node`, which may remove placeholders other people wrote.
+     */
+    readonly threads: ThreadStore;
+    list(q: ListQuery): Promise<Annotation[]>;
+    get(id: string): Promise<Annotation | null>;
+    create(a: Annotation): Promise<Annotation>;
+    update(a: Annotation, expectedRev: number): Promise<Annotation>;
+    remove(id: string, expectedRev: number): Promise<void>;
+    /**
+     * Runs `request`, which removes `id` and says where it was, or returns null when it removed
+     * nothing. While it runs, every subscriber tracks the remove so Realtime's echo of it, and the
+     * changes from before it, are not told after it. Tells subscribers once it succeeds.
+     */
+    private trackRemove;
+    subscribe(q: Omit<ListQuery, "since">, onChange: (e: ChangeEvent) => void): Unsubscribe;
+    /**
+     * A write matched no row: the note is missing (or hidden from the caller), its rev moved on,
+     * or the caller may read it but not change it.
+     */
+    private explainMiss;
+    private onRemote;
+    /**
+     * Tells this adapter's subscribers about one of its own writes, except `skip`: those already
+     * heard about it from Realtime.
+     */
+    private emit;
+    private tell;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;CACpE;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,eAAe,CAAC;AA2DrF;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,QAAQ,CAAC,YAAY;;;;MAAqD;IAC1E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6C;gBAElE,OAAO,EAAE,sBAAsB;IAM3C,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAqB7B;IAEF;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAsE3B;IAEI,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAoBzC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU3C,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB1C,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc/D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5D;;;;OAIG;YACW,WAAW;IAsCzB,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW;IAmCvF;;;OAGG;YACW,WAAW;IAYzB,OAAO,CAAC,QAAQ;IAiDhB;;;OAGG;IACH,OAAO,CAAC,IAAI;IAuBZ,OAAO,CAAC,IAAI;CAUb"}

package/dist/index.js

@@ -0,0 +1,440 @@
+import { afterAnnotationPrefix, AudienceError, ConflictError, NotFoundError, ThreadError, documentKeyOf, parentIdOf, } from "@acornly/core";
+/**
+ * Rows per request when listing. Matches the Data API's default `max_rows`; a project that lowers
+ * `max_rows` below this would see `list` stop after the first page.
+ */
+const PAGE = 1000;
+/** How long to wait for the Realtime echo of an own remove before giving up on it. */
+const ECHO_WAIT_MS = 30_000;
+let channelCount = 0;
+/**
+ * Keeps annotations in a site's own Supabase project, in the table the SQL in this package's
+ * `supabase/migrations` creates. Row-level security there decides what each user may read and
+ * write; the database owns `ext.rev` and each write checks it, so concurrent edits conflict
+ * instead of overwriting each other.
+ *
+ * Subscribers hear about this adapter's own writes at once, and about everyone else's through
+ * Supabase Realtime, filtered by the same read rules.
+ */
+export class SupabaseAdapter {
+    capabilities = { realtime: true, search: false, offline: false };
+    client;
+    table;
+    listeners = new Set();
+    onRealtimeStatus;
+    constructor(options) {
+        this.client = options.client;
+        this.table = options.table ?? "acornly_annotations";
+        this.onRealtimeStatus = options.onRealtimeStatus;
+    }
+    /** Earlier versions, in `acornly_versions`: only the note's author can save or read them. */
+    versions = {
+        saveVersion: async (a) => {
+            const { error } = await this.client
+                .from("acornly_versions")
+                .upsert({ annotation: a }, { onConflict: "note_id,rev" });
+            if (error)
+                throw toError(error);
+        },
+        listVersions: async (id) => {
+            const { data, error } = await this.client
+                .from("acornly_versions")
+                .select("annotation")
+                .eq("note_id", id)
+                .order("rev")
+                .returns();
+            if (error)
+                throw toError(error);
+            return data.map((row) => row.annotation);
+        },
+        clearVersions: async (id) => {
+            const { error } = await this.client.from("acornly_versions").delete().eq("note_id", id);
+            if (error)
+                throw toError(error);
+        },
+    };
+    /**
+     * Reply threads. The database checks each new child against its locked parent, and deletes run
+     * in `acornly_delete_node`, which may remove placeholders other people wrote.
+     */
+    threads = {
+        listThread: async (q) => {
+            // One call: the function returns the whole thread as one JSON array.
+            const { data, error } = await this.client.rpc("acornly_list_thread", {
+                root_id: q.threadRoot,
+                thread_scope: q.scope,
+            });
+            if (error)
+                throw toError(error);
+            return data;
+        },
+        countChildren: async (ids) => {
+            const counts = Object.fromEntries(ids.map((id) => [id, 0]));
+            if (!ids.length)
+                return counts;
+            const { data, error } = await this.client.rpc("acornly_count_children", {
+                ids: [...new Set(ids)],
+            });
+            if (error)
+                throw toError(error);
+            for (const row of data) {
+                counts[row.id] = Number(row.children);
+            }
+            return counts;
+        },
+        addChild: async (child) => {
+            const parentId = parentIdOf(child);
+            if (parentId === null)
+                throw new Error(`Annotation ${child.id} is not context on context`);
+            const { data, error } = await this.client
+                .from(this.table)
+                .insert({ annotation: child })
+                .select("annotation")
+                .single();
+            if (error) {
+                if (error.code === "P0002")
+                    throw new NotFoundError(parentId);
+                throw error.code === "23505"
+                    ? new Error(`Annotation ${child.id} already exists`, { cause: error })
+                    : toError(error);
+            }
+            this.emit({ type: "created", annotation: data.annotation });
+            return data.annotation;
+        },
+        deleteNode: async (id, expectedRev, now) => {
+            let result;
+            await this.trackRemove(id, async () => {
+                const { data, error } = await this.client.rpc("acornly_delete_node", {
+                    note_id: id,
+                    expected_rev: expectedRev,
+                    deleted_at: now,
+                });
+                if (error) {
+                    if (error.code === "P0002")
+                        throw new NotFoundError(id);
+                    if (error.code === "CH003") {
+                        throw new ConflictError(id, expectedRev, Number(error.details));
+                    }
+                    if (error.code === "42501") {
+                        throw new Error(`Not allowed to change annotation ${id}`, { cause: error });
+                    }
+                    throw toError(error);
+                }
+                result = data;
+                return "placeholder" in result ? null : result.removed[0];
+            });
+            if ("placeholder" in result) {
+                this.emit({ type: "updated", annotation: result.placeholder });
+                return { placeholder: result.placeholder, removed: [] };
+            }
+            // The note itself was told above; these are the placeholders that went with it.
+            for (const above of result.removed.slice(1)) {
+                this.emit({ type: "removed", id: above.id }, above);
+            }
+            return { removed: result.removed.map((r) => r.id) };
+        },
+    };
+    async list(q) {
+        const found = [];
+        for (let from = 0;; from += PAGE) {
+            let query = this.client
+                .from(this.table)
+                .select("annotation")
+                .eq("scope", q.scope)
+                .eq("document", q.documentId);
+            if (q.since !== undefined)
+                query = query.gt("modified", q.since);
+            const { data, error } = await query
+                .order("modified")
+                .order("id")
+                .range(from, from + PAGE - 1)
+                .returns();
+            if (error)
+                throw toError(error);
+            for (const row of data)
+                found.push(row.annotation);
+            if (data.length < PAGE)
+                return found;
+        }
+    }
+    async get(id) {
+        const { data, error } = await this.client
+            .from(this.table)
+            .select("annotation")
+            .eq("id", id)
+            .maybeSingle();
+        if (error)
+            throw toError(error);
+        return data?.annotation ?? null;
+    }
+    async create(a) {
+        if (isAnnotationTarget(a.target.source)) {
+            throw new ThreadError(`Annotation ${a.id} targets an annotation; use threads.addChild`);
+        }
+        const { data, error } = await this.client
+            .from(this.table)
+            .insert({ annotation: a })
+            .select("annotation")
+            .single();
+        if (error) {
+            throw error.code === "23505"
+                ? new Error(`Annotation ${a.id} already exists`, { cause: error })
+                : toError(error);
+        }
+        this.emit({ type: "created", annotation: data.annotation });
+        return data.annotation;
+    }
+    async update(a, expectedRev) {
+        const { data, error } = await this.client
+            .from(this.table)
+            .update({ annotation: a })
+            .eq("id", a.id)
+            .eq("rev", expectedRev)
+            .select("annotation")
+            .maybeSingle();
+        if (error)
+            throw toError(error);
+        if (!data)
+            return this.explainMiss(a.id, expectedRev);
+        this.emit({ type: "updated", annotation: data.annotation });
+        return data.annotation;
+    }
+    async remove(id, expectedRev) {
+        const removed = await this.trackRemove(id, async () => {
+            const { data, error } = await this.client
+                .from(this.table)
+                .delete()
+                .eq("id", id)
+                .eq("rev", expectedRev)
+                .select("scope, document")
+                .maybeSingle();
+            if (error)
+                throw toError(error);
+            return data;
+        });
+        if (!removed)
+            return this.explainMiss(id, expectedRev);
+    }
+    /**
+     * Runs `request`, which removes `id` and says where it was, or returns null when it removed
+     * nothing. While it runs, every subscriber tracks the remove so Realtime's echo of it, and the
+     * changes from before it, are not told after it. Tells subscribers once it succeeds.
+     */
+    async trackRemove(id, request) {
+        // Every subscriber gets the delete's echo, whatever its document, so all of them track it.
+        const tracked = new Map();
+        for (const l of this.listeners) {
+            if (l.removes.has(id))
+                continue;
+            const pending = { state: "sent" };
+            l.removes.set(id, pending);
+            tracked.set(l, pending);
+        }
+        let removed = null;
+        const alreadyTold = new Set();
+        try {
+            removed = await request();
+        }
+        finally {
+            for (const [l, pending] of tracked) {
+                // Forgotten when the channel rejoined.
+                if (l.removes.get(id) !== pending)
+                    continue;
+                if (!removed) {
+                    // Nothing was removed, so what arrived meanwhile is current: tell it now.
+                    l.removes.delete(id);
+                    if (pending.held)
+                        this.onRemote(l, pending.held.change);
+                }
+                else if (pending.state === "echoed") {
+                    l.removes.delete(id);
+                    alreadyTold.add(l);
+                }
+                else {
+                    pending.state = "due";
+                    pending.dueAt = Date.now();
+                    delete pending.held;
+                }
+            }
+        }
+        if (removed)
+            this.emit({ type: "removed", id }, removed, alreadyTold);
+        return removed;
+    }
+    subscribe(q, onChange) {
+        const listener = {
+            documentId: q.documentId,
+            scope: q.scope,
+            onChange,
+            delivered: new Map(),
+            removes: new Map(),
+            live: false,
+            stopped: false,
+        };
+        this.listeners.add(listener);
+        const table = { schema: "public", table: this.table };
+        const filter = filterFor(q);
+        const onRemote = (change) => this.onRemote(listener, change);
+        const channel = this.client
+            .channel(`acornly:${this.table}:${++channelCount}`)
+            // Realtime can filter inserts and updates by column, but not deletes.
+            .on("postgres_changes", { event: "INSERT", ...table, ...filter }, onRemote)
+            .on("postgres_changes", { event: "UPDATE", ...table, ...filter }, onRemote)
+            .on("postgres_changes", { event: "DELETE", ...table }, onRemote)
+            .subscribe((status, error) => {
+            if (listener.stopped)
+                return;
+            // Changes made before the channel was (re)joined are not replayed, echoes included:
+            // stop waiting for them. After a drop the app should `list` again once it is back.
+            if (status !== "SUBSCRIBED" || !listener.live)
+                listener.removes.clear();
+            listener.live = status === "SUBSCRIBED";
+            this.onRealtimeStatus?.(status, error);
+        });
+        return () => {
+            listener.stopped = true;
+            this.listeners.delete(listener);
+            void this.client.removeChannel(channel);
+        };
+    }
+    /**
+     * A write matched no row: the note is missing (or hidden from the caller), its rev moved on,
+     * or the caller may read it but not change it.
+     */
+    async explainMiss(id, expectedRev) {
+        const { data, error } = await this.client
+            .from(this.table)
+            .select("rev")
+            .eq("id", id)
+            .maybeSingle();
+        if (error)
+            throw toError(error);
+        if (!data)
+            throw new NotFoundError(id);
+        if (data.rev !== expectedRev)
+            throw new ConflictError(id, expectedRev, data.rev);
+        throw new Error(`Not allowed to change annotation ${id}`);
+    }
+    onRemote(listener, change) {
+        if (listener.stopped)
+            return;
+        const id = change.eventType === "DELETE" ? change.old.id : change.new.annotation?.id;
+        if (!id)
+            return;
+        let own = listener.removes.get(id);
+        if (own?.state === "due" && Date.now() - own.dueAt > ECHO_WAIT_MS) {
+            // The echo never came (a dropped message); stop waiting for it.
+            listener.removes.delete(id);
+            own = undefined;
+        }
+        if (change.eventType === "DELETE") {
+            if (own?.state === "due") {
+                // The echo of this adapter's own remove, already told.
+                listener.removes.delete(id);
+                return;
+            }
+            if (own?.state === "sent") {
+                own.state = "echoed";
+                delete own.held;
+            }
+            if (listener.delivered.get(id) === "removed")
+                return;
+            // Realtime sends only the id of a deleted row, so every subscriber hears about it and an id
+            // it never had is a no-op for it. Only ids it has heard of, or is removing, are remembered.
+            if (own || listener.delivered.has(id))
+                listener.delivered.set(id, "removed");
+            this.tell(listener, { type: "removed", id });
+            return;
+        }
+        const annotation = change.new.annotation;
+        if (!matches(listener, documentKeyOf(annotation), annotation.ext.scope))
+            return;
+        if (own?.state === "sent") {
+            // The change that would make the remove fail, or one from before it: decide once it settles.
+            if (!own.held || own.held.rev <= annotation.ext.rev) {
+                own.held = { change, rev: annotation.ext.rev };
+            }
+            return;
+        }
+        // From before this adapter's own remove of the note.
+        if (own?.state === "due")
+            return;
+        const last = listener.delivered.get(id);
+        if (change.eventType === "UPDATE" && last === "removed")
+            return;
+        if (typeof last === "number" && last >= annotation.ext.rev)
+            return;
+        // An insert after a removal is the same id created again.
+        listener.delivered.set(id, annotation.ext.rev);
+        this.tell(listener, {
+            type: change.eventType === "INSERT" ? "created" : "updated",
+            annotation,
+        });
+    }
+    /**
+     * Tells this adapter's subscribers about one of its own writes, except `skip`: those already
+     * heard about it from Realtime.
+     */
+    emit(event, where, skip) {
+        const document = where?.document ?? documentKeyOf(event.annotation);
+        const scope = where?.scope ?? event.annotation.ext.scope;
+        for (const l of this.listeners) {
+            if (skip?.has(l) || !matches(l, document, scope))
+                continue;
+            if (event.type === "removed") {
+                if (l.delivered.get(event.id) === "removed")
+                    continue;
+                l.delivered.set(event.id, "removed");
+            }
+            else {
+                const last = l.delivered.get(event.annotation.id);
+                // Realtime's echo beat the response: already told.
+                if (typeof last === "number" && last >= event.annotation.ext.rev)
+                    continue;
+                l.delivered.set(event.annotation.id, event.annotation.ext.rev);
+            }
+            this.tell(l, event);
+        }
+    }
+    tell(listener, event) {
+        // A throwing listener must not fail a write that has already committed.
+        try {
+            listener.onChange(structuredClone(event));
+        }
+        catch (err) {
+            queueMicrotask(() => {
+                throw err;
+            });
+        }
+    }
+}
+function matches(l, document, scope) {
+    return l.documentId === document && l.scope === scope;
+}
+/**
+ * The Realtime filter for a subscription. Realtime cannot match a value containing a comma, so
+ * such a document falls back to its scope, and a scope with a comma to no filter; `matches`
+ * always checks both on arrival.
+ */
+function filterFor(q) {
+    if (!q.documentId.includes(","))
+        return { filter: `document=eq.${q.documentId}` };
+    if (!q.scope.includes(","))
+        return { filter: `scope=eq.${q.scope}` };
+    return {};
+}
+/** Maps the shipped SQL's error codes to core's errors. */
+function toError(error) {
+    if (error.code === "CH001")
+        return new ThreadError(error.message);
+    if (error.code === "CH002")
+        return new AudienceError(error.message);
+    return new Error(error.message, { cause: error });
+}
+function isAnnotationTarget(source) {
+    // The database reports a source that is not a string.
+    if (typeof source !== "string")
+        return false;
+    return afterAnnotationPrefix(source) !== undefined;
+}
+//# sourceMappingURL=index.js.map