@kubun/store-p2p 0.11.0 → 0.12.1

package/lib/migrations.js

@@ -1,10 +1,32 @@
-export function getP2PMigrations(ctx) {
+import { sql } from 'kysely';
+/**
+ * Partial unique index keeping one commit-hub designation per group. Named here
+ * because the store recognises a lost first-bind race by this name appearing in
+ * the driver's constraint-violation error.
+ */ export const COMMIT_HUB_UNIQUE_INDEX = 'uq_p2p_group_hubs_commit';
+/**
+ * A shipped migration is immutable: once a database has run it, editing it
+ * changes nothing on that database and silently diverges the schema from the
+ * code. Every schema change after a release goes in a NEW migration.
+ *
+ * That rule is suspended for this release, deliberately. The eight migrations
+ * this store had accumulated are folded into `0-init`, which is now the whole
+ * schema in one readable place. It is a BREAKING change — a database created
+ * before it will not pick the new shape up and must be recreated — and it costs
+ * nothing here only because the release already requires recreating local
+ * databases for unrelated reasons.
+ *
+ * Reinstate the rule the moment this ships: the next schema change is a new
+ * migration, and `0-init` is immutable again.
+ */ export function getP2PMigrations(ctx) {
     const t = ctx.types;
     const now = ctx.functions.now;
     const init = {
         async up (db) {
             // Groups
-            await db.schema.createTable('kubun_p2p_groups').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('created_by', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
+            await db.schema.createTable('kubun_p2p_groups').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('created_by', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull())// 'joined' | 'left' — see `GroupStatus`. A row is only written on a
+            // completed join or a local create, so the default is the joined state.
+            .addColumn('status', t.text, (col)=>col.notNull().defaultTo('joined')).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
             // Group members
             await db.schema.createTable('kubun_p2p_group_members').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('member_did', t.text, (col)=>col.notNull()).addColumn('role', t.text, (col)=>col.notNull().defaultTo('member'))// LWW version key for the row, set on insert and refreshed on re-add.
             .addColumn('hlc', t.text, (col)=>col.notNull())// HLC at which this peer learned the member was removed from the MLS
@@ -17,7 +39,12 @@ export function getP2PMigrations(ctx) {
             ]).execute();
             await db.schema.createIndex('idx_p2p_group_members_did').ifNotExists().on('kubun_p2p_group_members').column('member_did').execute();
             // Circles
-            await db.schema.createTable('kubun_p2p_circles').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('catalog_ids', t.json, (col)=>col.notNull().defaultTo('[]')).addColumn('hlc', t.text, (col)=>col.notNull())// NULL means the circle is active; a non-null value tombstones the row
+            await db.schema.createTable('kubun_p2p_circles').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('catalog_ids', t.json, (col)=>col.notNull().defaultTo('[]')).addColumn('hlc', t.text, (col)=>col.notNull())// Projection of the group's current `openCircleIDs`: 1 marks the circle
+            // open (every group member has implicit access), 0 closed. Integer 0/1
+            // mirrors the catalog `active` flag, keeping the read-back value uniform
+            // across SQLite and Postgres. A circle is closed until a settings fold
+            // projects it open.
+            .addColumn('open', 'integer', (col)=>col.notNull().defaultTo(0))// NULL means the circle is active; a non-null value tombstones the row
             // so reads exclude it while the removal HLC stays comparable.
             .addColumn('removed_at_hlc', t.text).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
             await db.schema.createIndex('idx_p2p_circles_group').ifNotExists().on('kubun_p2p_circles').column('group_id').execute();
@@ -36,12 +63,20 @@ export function getP2PMigrations(ctx) {
             // enrichment. One group per `jti`, so `jti` is the primary key.
             await db.schema.createTable('kubun_p2p_group_delegation').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('jti', t.text, (col)=>col.notNull().primaryKey()).execute();
             // Group MLS state
-            await db.schema.createTable('kubun_p2p_group_mls_state').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('device_id', t.text, (col)=>col.notNull()).addColumn('mls_state', t.binary, (col)=>col.notNull()).addColumn('credential', t.text, (col)=>col.notNull()).addColumn('epoch', 'integer', (col)=>col.notNull()).addColumn('root_capability', t.text, (col)=>col.notNull().defaultTo('')).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_p2p_group_mls_state', [
+            await db.schema.createTable('kubun_p2p_group_mls_state').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('device_id', t.text, (col)=>col.notNull()).addColumn('mls_state', t.binary, (col)=>col.notNull()).addColumn('credential', t.text, (col)=>col.notNull()).addColumn('epoch', 'integer', (col)=>col.notNull()).addColumn('ledger_entries', t.text, (col)=>col.notNull().defaultTo('[]')).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_p2p_group_mls_state', [
                 'group_id',
                 'device_id'
             ]).execute();
             // Sync peers
-            await db.schema.createTable('kubun_p2p_sync_peers').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('peer_did', t.text, (col)=>col.notNull().unique()).addColumn('endpoint', t.text, (col)=>col.notNull()).addColumn('mode', t.text, (col)=>col.notNull()).addColumn('allowed_users', t.json, (col)=>col.notNull()).addColumn('priority', t.text, (col)=>col.notNull().defaultTo('0')).addColumn('trust_level', t.text, (col)=>col.notNull()).addColumn('config', t.json, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            await db.schema.createTable('kubun_p2p_sync_peers').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('peer_did', t.text, (col)=>col.notNull().unique()).addColumn('endpoint', t.text, (col)=>col.notNull())// No `trust_level`, `allowed_users`, `priority` or `mode`. They were
+            // stored and never read: what a peer may see is decided per document at
+            // the far end, and a locally-written row is not a credential. `priority`
+            // in particular looked like the ranking knob after ranking had moved to
+            // the discovery projection, which is the only thing that knows
+            // availability. `mode` accumulated two incompatible vocabularies for a
+            // question nothing asked of this row — direction comes from `syncPeer`'s
+            // argument, per call.
+            .addColumn('config', t.json, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
             // Sync checkpoints
             await db.schema.createTable('kubun_p2p_sync_checkpoints').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('peer_did', t.text, (col)=>col.notNull()).addColumn('scope', t.text, (col)=>col.notNull()).addColumn('checkpoint_hlc', t.text, (col)=>col.notNull()).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
             // Broadcast log
@@ -53,39 +88,84 @@ export function getP2PMigrations(ctx) {
             await db.schema.createIndex('idx_p2p_broadcast_log_doc').ifNotExists().on('kubun_p2p_broadcast_log').column('doc_id').execute();
             // Hubs (device-local, never synced — no hlc column)
             await db.schema.createTable('kubun_p2p_hubs').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('label', t.text).addColumn('url', t.text, (col)=>col.notNull().unique()).addColumn('server_did', t.text).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
-            // Group hubs (join table, device-local — no hlc column)
-            await db.schema.createTable('kubun_p2p_group_hubs').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('hub_id', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_p2p_group_hubs', [
+            // Group hubs (join table, device-local — no hlc column). A group commits
+            // through exactly one bound hub; `is_commit_hub` marks which. Integer 0/1
+            // mirrors the circle `open` flag so the value reads back uniformly across
+            // SQLite and Postgres.
+            await db.schema.createTable('kubun_p2p_group_hubs').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('hub_id', t.text, (col)=>col.notNull()).addColumn('is_commit_hub', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addPrimaryKeyConstraint('pk_p2p_group_hubs', [
                 'group_id',
                 'hub_id'
             ]).execute();
             await db.schema.createIndex('idx_p2p_group_hubs_hub').ifNotExists().on('kubun_p2p_group_hubs').column('hub_id').execute();
-            // Control ledger: append-only signed-claim log. `entry_id` (content
-            // digest of `signed_token`) is the primary key, so a re-delivered entry
-            // is a no-op insert. Rows are read ordered by `(hlc, entry_id)` for a
-            // deterministic reducer fold; index that pair scoped to the group.
-            await db.schema.createTable('kubun_p2p_control_ledger').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('entry_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('type', t.text, (col)=>col.notNull()).addColumn('subject', t.text, (col)=>col.notNull()).addColumn('value', t.json, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('issuer_did', t.text, (col)=>col.notNull()).addColumn('signed_token', t.text, (col)=>col.notNull()).addColumn('received_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
-            await db.schema.createIndex('idx_p2p_control_ledger_group_order').ifNotExists().on('kubun_p2p_control_ledger').columns([
+            // The single designation is a database constraint, not a convention a
+            // writer upholds. A transaction alone cannot uphold it: two devices
+            // binding their first hub concurrently touch DIFFERENT rows, so under
+            // READ COMMITTED neither blocks the other, both read "no commit hub" and
+            // both claim it — the group then commits to two logs, which is the fork
+            // the designation exists to prevent. Partial unique indexes carry the
+            // same meaning on both adapter families (SQLite >= 3.8, Postgres).
+            await db.schema.createIndex(COMMIT_HUB_UNIQUE_INDEX).ifNotExists().unique().on('kubun_p2p_group_hubs').column('group_id').where(sql.ref('is_commit_hub'), '=', 1).execute();
+            // ControlRequest work queue: the client-visible record of a control-plane
+            // request (a ledger write, an invite, a removal) from enqueue to
+            // settlement, keyed by the same id the commit journal carries for the
+            // attempt. Rows are retained after settling so a client holding the id can
+            // read the outcome back, and leave only on an explicit ack. `result` is
+            // nullable because most requests produce nothing to hand back; it is
+            // written on settle and deleted with the row on ack, so the retention of
+            // whatever it holds is bounded by the request's own lifetime.
+            await db.schema.createTable('kubun_p2p_control_requests').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('kind', t.text, (col)=>col.notNull()).addColumn('status', t.text, (col)=>col.notNull().defaultTo('pending')).addColumn('error', t.text).addColumn('result', t.text).addColumn('enqueued_at', t.text, (col)=>col.notNull()).addColumn('settled_at', t.text).execute();
+            await db.schema.createIndex('idx_p2p_control_requests_group').ifNotExists().on('kubun_p2p_control_requests').columns([
                 'group_id',
-                'hlc',
-                'entry_id'
+                'enqueued_at'
             ]).execute();
-            await db.schema.createIndex('idx_p2p_control_ledger_group_type').ifNotExists().on('kubun_p2p_control_ledger').columns([
+            // CommitJournal store (backs the `@kumiai/rpc` CommitJournal port).
+            // `group_id` is the primary key: a single slot per group, so a fresh `put`
+            // upserts/replaces the whole row.
+            await db.schema.createTable('kubun_p2p_commit_journal').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('publish_id', t.text, (col)=>col.notNull()).addColumn('expected_head', t.text).addColumn('epoch', t.bigint, (col)=>col.notNull()).addColumn('accepted_as', t.text).addColumn('commit', t.binary, (col)=>col.notNull()).addColumn('bodies', t.json, (col)=>col.notNull()).addColumn('kind', t.text, (col)=>col.notNull()).addColumn('journal', t.binary, (col)=>col.notNull()).execute();
+            // App-lane anchor + per-topic read positions (back the `@kumiai/rpc`
+            // `AnchorStore` and `AppCursorStore` ports). The anchor table is a single
+            // slot per group, so a rotation upserts and replaces the whole row;
+            // cursors are keyed by (group, topic) so a deleted group takes its cursors
+            // with it.
+            await db.schema.createTable('kubun_p2p_group_anchor').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('secret', t.binary, (col)=>col.notNull()).addColumn('epoch', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_p2p_app_cursor').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('position', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint('pk_p2p_app_cursor', [
                 'group_id',
-                'type'
+                'topic_id'
             ]).execute();
-            // Projection watermark: how far a given `(group, projection)` fold has
-            // been materialized. An in-order entry (hlc > watermark) applies
-            // incrementally and advances this; an out-of-order or absent watermark
-            // triggers a full reproject. The projection is disposable — this row only
-            // optimizes away re-folding the whole ledger per receive.
-            await db.schema.createTable('kubun_p2p_projection_state').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('projection', t.text, (col)=>col.notNull()).addColumn('projected_through_hlc', t.text, (col)=>col.notNull()).addColumn('updated_at', t.timestamp).addPrimaryKeyConstraint('pk_p2p_projection_state', [
+            // The peer-discovery projection: one row per (group, peer) folded from
+            // authenticated `peer/announce` frames. `peer_did` is the MLS-authenticated
+            // announcer, which is why the primary key is (group, peer) and there is no
+            // column for a body-supplied DID: nothing self-asserted may pick the row.
+            await db.schema.createTable('kubun_p2p_peer_announcements').ifNotExists().addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('peer_did', t.text, (col)=>col.notNull()).addColumn('label', t.text, (col)=>col.notNull().defaultTo('')).addColumn('availability', t.text, (col)=>col.notNull()).addColumn('capabilities', t.json, (col)=>col.notNull().defaultTo('[]')).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('announced_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('announced_epoch', 'integer', (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint('pk_p2p_peer_announcements', [
                 'group_id',
-                'projection'
+                'peer_did'
             ]).execute();
+            // Answers "which groups have I seen this device in", the read a roster
+            // removal and a cross-group route lookup both need.
+            await db.schema.createIndex('idx_p2p_peer_announcements_peer').ifNotExists().on('kubun_p2p_peer_announcements').column('peer_did').execute();
+            // This device's own advertisement, device-wide. One row, keyed on the
+            // device's DID rather than on a fixed sentinel, so a profile written under
+            // one identity is never read back under another.
+            await db.schema.createTable('kubun_p2p_local_peer_profile').ifNotExists().addColumn('peer_did', t.text, (col)=>col.notNull().primaryKey()).addColumn('label', t.text, (col)=>col.notNull().defaultTo('')).addColumn('availability', t.text, (col)=>col.notNull()).addColumn('capabilities', t.json, (col)=>col.notNull().defaultTo('[]')).addColumn('updated_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            // The private half of a join request, held between `prepareJoinRequest`
+            // and `completeJoin`. The offline exchange spans a human round-trip, so
+            // the two calls can be different processes — a CLI device is always two.
+            // Keyed on the requesting DID: a second request replaces the first rather
+            // than leaving dead key material behind, and the row is deleted the moment
+            // it is consumed.
+            await db.schema.createTable('kubun_p2p_pending_join_requests').ifNotExists().addColumn('did', t.text, (col)=>col.notNull().primaryKey())// The caller's own encoding, opaque here: a key package holds BigInts
+            // and binary, which plain JSON cannot carry.
+            .addColumn('payload', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
         },
         async down (db) {
-            await db.schema.dropTable('kubun_p2p_projection_state').ifExists().execute();
-            await db.schema.dropTable('kubun_p2p_control_ledger').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_pending_join_requests').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_local_peer_profile').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_peer_announcements').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_app_cursor').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_group_anchor').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_commit_journal').ifExists().execute();
+            await db.schema.dropTable('kubun_p2p_control_requests').ifExists().execute();
+            await db.schema.dropIndex(COMMIT_HUB_UNIQUE_INDEX).ifExists().execute();
             await db.schema.dropTable('kubun_p2p_group_hubs').ifExists().execute();
             await db.schema.dropTable('kubun_p2p_hubs').ifExists().execute();
             await db.schema.dropTable('kubun_p2p_broadcast_log').ifExists().execute();

package/lib/ops/app-lane.d.ts

@@ -0,0 +1,36 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { AppCursor, GroupAnchor, P2PStoreTables } from '../tables.js';
+/** App-lane anchors and per-topic read cursors. */
+export type AppLaneOps = {
+    /**
+     * Write the group's anchor slot, REPLACING whatever it held. Single slot per
+     * group: the anchor moves as a pair (secret + the epoch it was exported at),
+     * so a rotation overwrites both or neither.
+     */
+    putGroupAnchor(params: {
+        groupID: string;
+        secret: Uint8Array;
+        epoch: number;
+    }): Promise<void>;
+    /** The group's anchor, or `undefined` if the group has never stored one. */
+    getGroupAnchor(groupID: string): Promise<GroupAnchor | undefined>;
+    /**
+     * Write this device's read position on one topic, replacing the previous
+     * position for that (group, topic). `position` is opaque: stored verbatim.
+     */
+    putAppCursor(params: {
+        groupID: string;
+        topicID: string;
+        position: string;
+    }): Promise<void>;
+    /**
+     * The read position on one topic, or `undefined` if this device has never
+     * processed a frame on it.
+     */
+    getAppCursor(params: {
+        groupID: string;
+        topicID: string;
+    }): Promise<AppCursor | undefined>;
+};
+export declare function createAppLaneOps(db: Kysely<P2PStoreTables>, adapter: Adapter): AppLaneOps;

package/lib/ops/app-lane.js

@@ -0,0 +1,38 @@
+export function createAppLaneOps(db, adapter) {
+    return {
+        async putGroupAnchor (params) {
+            const values = {
+                group_id: params.groupID,
+                secret: adapter.encodeBinary(params.secret),
+                epoch: params.epoch
+            };
+            await db.insertInto('kubun_p2p_group_anchor')// Single slot per group: a rotation REPLACES both halves together. The
+            // secret and the epoch it was exported at both feed topic derivation,
+            // so a row mixing one epoch's secret with another's number would derive
+            // a topic no member is on.
+            .values(values).onConflict((oc)=>oc.column('group_id').doUpdateSet((eb)=>({
+                        secret: eb.ref('excluded.secret'),
+                        epoch: eb.ref('excluded.epoch')
+                    }))).execute();
+        },
+        async getGroupAnchor (groupID) {
+            return await db.selectFrom('kubun_p2p_group_anchor').selectAll().where('group_id', '=', groupID).executeTakeFirst();
+        },
+        // --- App-lane cursor operations ---
+        async putAppCursor (params) {
+            await db.insertInto('kubun_p2p_app_cursor').values({
+                group_id: params.groupID,
+                topic_id: params.topicID,
+                position: params.position
+            }).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'topic_id'
+                ]).doUpdateSet((eb)=>({
+                        position: eb.ref('excluded.position')
+                    }))).execute();
+        },
+        async getAppCursor (params) {
+            return await db.selectFrom('kubun_p2p_app_cursor').selectAll().where('group_id', '=', params.groupID).where('topic_id', '=', params.topicID).executeTakeFirst();
+        }
+    };
+}

package/lib/ops/circles.d.ts

@@ -0,0 +1,153 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { Circle, CircleMember, InsertCircle, InsertCircleMember, P2PStoreTables } from '../tables.js';
+/** Circles, their membership rows, and the fold-authoritative projections. */
+export type CircleOps = {
+    createCircle(circle: InsertCircle): Promise<void>;
+    /**
+     * Active-only by default (`removed_at_hlc IS NULL`). Pass
+     * `{ includeRemoved: true }` to also see tombstoned circles — used by the
+     * apply path so a `circle:create`/`circle:update` can HLC-compare against a
+     * tombstoned row and resurrect it, and by the catch-up responder.
+     */
+    getCircle(id: string, options?: {
+        includeRemoved?: boolean;
+    }): Promise<Circle | undefined>;
+    /**
+     * Batch fetch circles by ID. Returns a Map keyed by ID; missing IDs are
+     * absent from the map. Single SQL query with `WHERE id IN (...)`. Empty
+     * input short-circuits with an empty Map (no SQL).
+     *
+     * Caller is responsible for deduplicating IDs.
+     */
+    getCircles(ids: Array<string>): Promise<Map<string, Circle>>;
+    updateCircle(id: string, update: Partial<Pick<InsertCircle, 'name' | 'description' | 'catalog_ids' | 'hlc'>>): Promise<void>;
+    deleteCircle(id: string): Promise<void>;
+    /**
+     * Tombstone an existing circle row at `hlc` using earliest-wins LWW: the
+     * removal sticks only when no removal is recorded yet, or when `hlc` precedes
+     * the stored removal HLC. A removal for a `circleID` with no local row is a
+     * no-op — absence means there is no circle to tombstone, and no row is
+     * created.
+     */
+    markCircleRemoved(circleID: string, hlc: string): Promise<void>;
+    /**
+     * Active-only by default (`removed_at_hlc IS NULL`). Pass
+     * `{ includeRemoved: true }` to include tombstoned circles for the catch-up
+     * responder.
+     */
+    listCirclesByGroup(groupID: string, options?: {
+        includeRemoved?: boolean;
+    }): Promise<Array<Circle>>;
+    addCircleMember(member: InsertCircleMember): Promise<void>;
+    /**
+     * Soft-delete a circle member by tombstoning the row with `hlc`: earliest-wins
+     * LWW, ignore-if-absent. The row stays in the table so the removal HLC stays
+     * comparable.
+     */
+    removeCircleMember(circleID: string, memberDID: string, hlc: string): Promise<void>;
+    /**
+     * The row as stored, INCLUDING a tombstoned one — unlike every sibling reader,
+     * whose default is active-only. A revival has to see the row it revives, so the
+     * caller decides what removal means and any presence check must read
+     * `removed_at_hlc` as well.
+     */
+    getCircleMember(circleID: string, memberDID: string): Promise<CircleMember | undefined>;
+    /**
+     * Active-only by default (`removed_at_hlc IS NULL`). Pass
+     * `{ includeRemoved: true }` to include tombstoned members for the catch-up
+     * responder.
+     */
+    listCircleMembers(circleID: string, options?: {
+        includeRemoved?: boolean;
+    }): Promise<Array<CircleMember>>;
+    getCirclesForMember(memberDID: string): Promise<Array<Circle>>;
+    /**
+     * Circle access predicate over `circleIDs`. True when, for any active circle in
+     * the set, the member either holds an active explicit `circle_members` row OR
+     * the circle is open (`open = 1`) and the member is an active member of the
+     * circle's group. Evaluates `open` at CURRENT state, so delisting a circle from
+     * the group's `openCircleIDs` revokes implicit access immediately. Empty
+     * `circleIDs`, a tombstoned circle, and a tombstoned membership all return
+     * false.
+     */
+    isMemberOfAnyCircle(memberDID: string, circleIDs: Array<string>): Promise<boolean>;
+    /**
+     * WHICH of `circleIDs` the member reaches, each with its group, under exactly
+     * the predicate {@link isMemberOfAnyCircle} tests — same explicit-or-open arms,
+     * same current-state `open`, same tombstone gating. One query for the whole set,
+     * for a caller that must know per circle rather than "any": asking
+     * `isMemberOfAnyCircle` once per id costs a round trip per id, and collapsing
+     * the set into one "any" answer loses the per-circle conjunction an
+     * authorization rule needs.
+     *
+     * The group comes back with the id because a caller conjoining circle access
+     * with group membership would otherwise re-read each circle to learn its group,
+     * and that second read is where a tombstone filter could drift from this one. A
+     * tombstoned or unknown id is simply absent. Order is not guaranteed.
+     */
+    listAccessibleCircles(memberDID: string, circleIDs: Array<string>): Promise<Array<{
+        id: string;
+        groupID: string;
+    }>>;
+    /**
+     * Sync-owner expansion for a circle. Returns the explicit active members, plus
+     * — when the circle is open — every active member of the circle's group. A
+     * closed, tombstoned, or unknown circle yields the explicit members only, so a
+     * closed circle's owner set is unchanged.
+     */
+    listCircleOwners(circleID: string): Promise<Array<string>>;
+    /**
+     * The UNION of {@link listCircleOwners} over several circles: three queries for
+     * the whole set instead of three per circle. Callers that only need the merged
+     * owner set — sync-scope resolution — get it without a per-circle round trip.
+     * Per-circle attribution is deliberately not returned; the open arm makes it
+     * ambiguous anyway, since one group member can be an owner via several open
+     * circles of the same group. A no-op returning an empty array for an empty
+     * list.
+     */
+    listOwnersForCircles(circleIDs: Array<string>): Promise<Array<string>>;
+    /**
+     * Reproject the group's current open set onto its circle rows: set `open = 1`
+     * for every circle in `openCircleIDs` and `open = 0` for every other circle in
+     * the group. Idempotent and current-state authoritative — the caller derives
+     * `openCircleIDs` from the settings fold, so this write simply materializes it.
+     */
+    reconcileCircleOpenFlags(groupID: string, openCircleIDs: Array<string>): Promise<void>;
+    /**
+     * Fold-authoritative circle projection write: unconditionally set the row for
+     * `id` to the supplied derived state. Distinct from the LWW writers —
+     * `createCircle` (insert-only), `updateCircle` (update-only, clears the
+     * tombstone) and `markCircleRemoved` (earliest-wins LWW). A reproject derives
+     * `hlc` from the winning active entry and `removedAtHLC` from the winning
+     * tombstone (or null when active), then overwrites every projected column so
+     * the row equals exactly what the ledger fold decides regardless of prior
+     * contents. A removed circle keeps a tombstone row (`removed_at_hlc` set), not
+     * a hard delete, so `includeRemoved` reads and the read-ACL joins keep working.
+     */
+    reconcileCircleProjection(params: {
+        id: string;
+        groupID: string;
+        name: string;
+        description: string;
+        catalogIDs: Array<string>;
+        hlc: string;
+        removedAtHLC: string | null;
+        open: boolean;
+    }): Promise<void>;
+    /**
+     * Fold-authoritative circle-member projection write, the member-row analogue
+     * of {@link reconcileCircleProjection}: unconditionally upsert the
+     * `(circleID, memberDID)` row to the derived `(role, hlc, removedAtHLC)` state.
+     * A removed member keeps a tombstone row so the read-ACL joins still gate on
+     * the marker.
+     */
+    reconcileCircleMemberProjection(params: {
+        circleID: string;
+        memberDID: string;
+        role: string;
+        hlc: string;
+        removedAtHLC: string | null;
+    }): Promise<void>;
+};
+export declare function createCircleOps(db: Kysely<P2PStoreTables>, adapter: Adapter): CircleOps;