@kubun/store-p2p 0.10.0 → 0.11.0

package/lib/api.d.ts

@@ -1,7 +1,6 @@
 import type { Adapter } from '@kubun/db-adapter';
-import { type Logger } from '@kubun/logger';
 import type { Kysely } from 'kysely';
-import type { Circle, CircleMember, DelegationToken, Group, GroupMember, GroupMLSState, HeldRevocation, Hub, InsertCircle, InsertCircleMember, InsertDelegationToken, InsertGroup, InsertGroupHub, InsertGroupMember, InsertGroupMLSState, InsertHub, InsertRevokedCapability, InsertSyncPeer, P2PStoreTables, PaginatedResult, PaginationParams, RevokedCapability, SyncPeer } from './tables.js';
+import type { Circle, CircleMember, ControlLedgerEntry, Group, GroupMember, GroupMLSState, Hub, InsertCircle, InsertCircleMember, InsertControlLedgerEntry, InsertGroup, InsertGroupDelegation, InsertGroupHub, InsertGroupMember, InsertGroupMLSState, InsertHub, InsertSyncPeer, P2PStoreTables, PaginatedResult, PaginationParams, SyncPeer } from './tables.js';
 export type P2PStoreAPI = {
     createGroup(group: InsertGroup): Promise<void>;
     getGroup(id: string): Promise<Group | undefined>;
@@ -10,6 +9,13 @@ export type P2PStoreAPI = {
     listGroups(): Promise<Array<Group>>;
     listGroupsOffsetPaged(params: PaginationParams): Promise<PaginatedResult<Group>>;
     addGroupMember(member: InsertGroupMember): Promise<void>;
+    /**
+     * Add (or revive) several members in a single multi-row insert. Same
+     * re-add-clears-tombstone semantics as {@link addGroupMember}, applied to every
+     * row. A single statement keeps the whole batch atomic and avoids issuing one
+     * round-trip per member on a single-connection adapter. A no-op for an empty list.
+     */
+    addGroupMembers(members: Array<InsertGroupMember>): Promise<void>;
     /**
      * Soft-delete a member by tombstoning the row with `hlc`. Delegates to
      * `markMemberRemoved`: earliest-wins LWW, ignore-if-absent. The row stays in
@@ -36,6 +42,34 @@ export type P2PStoreAPI = {
     } | undefined>;
     getGroupMember(groupID: string, memberDID: string): Promise<GroupMember | undefined>;
     isGroupMember(groupID: string, memberDID: string): Promise<boolean>;
+    /**
+     * Whether `did` was a member of `groupID` at the given HLC, ignoring role.
+     * Mirrors {@link isGroupAdmin}'s removal-boundary semantics without the
+     * `role = 'admin'` filter: with no `atHLC`, tombstoned rows are excluded
+     * (`removed_at_hlc IS NULL`); with `atHLC`, a member removed at HLC `R` still
+     * counts iff `atHLC < R`. Conjoined with ledger admin authority so an
+     * MLS-removed member loses admin regardless of the ledger.
+     */
+    isGroupMemberAtHLC(groupID: string, did: string, atHLC?: string): Promise<boolean>;
+    /**
+     * Whether `did` holds an active `admin` role in `groupID`. With no `atHLC`,
+     * tombstoned rows are ignored (`removed_at_hlc IS NULL`) — the apply-time
+     * admin check. With `atHLC`, an admin removed at HLC `R` still counts iff the
+     * supplied HLC strictly precedes `R` (`atHLC < R`): a write claiming a moment
+     * before the removal is admitted, one at or after it is denied. This mirrors
+     * the membership boundary in `checkMembership` (which denies at
+     * `removed_at_hlc <= mutationHLC`), so the two checks agree on the
+     * remove-boundary instant.
+     */
+    isGroupAdmin(groupID: string, did: string, atHLC?: string): Promise<boolean>;
+    /**
+     * Overlay the role column for an existing member. Update-only: a grant for a
+     * DID with no membership row is a no-op, since membership is MLS-native and a
+     * non-member can hold no role. Never touches `hlc` or `removed_at_hlc`, so it
+     * neither churns membership LWW nor resurrects a tombstone — it is purely the
+     * projection target for the admin-roster fold.
+     */
+    setGroupMemberRole(groupID: string, memberDID: string, role: string): Promise<void>;
     isMemberOfAnyGroup(viewerDID: string, groupIDs: Array<string>): Promise<boolean>;
     listGroupMembers(groupID: string): Promise<Array<GroupMember>>;
     getGroupsForMember(memberDID: string): Promise<Array<Group>>;
@@ -50,7 +84,15 @@ export type P2PStoreAPI = {
      */
     getGroupsForMembers(memberDIDs: Array<string>): Promise<Map<string, Array<Group>>>;
     createCircle(circle: InsertCircle): Promise<void>;
-    getCircle(id: string): Promise<Circle | undefined>;
+    /**
+     * 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
@@ -61,131 +103,93 @@ export type P2PStoreAPI = {
     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>;
-    listCirclesByGroup(groupID: string): Promise<Array<Circle>>;
+    /**
+     * 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>;
-    removeCircleMember(circleID: string, memberDID: string): 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>;
     getCircleMember(circleID: string, memberDID: string): Promise<CircleMember | undefined>;
-    listCircleMembers(circleID: string): Promise<Array<CircleMember>>;
+    /**
+     * 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>>;
     isMemberOfAnyCircle(memberDID: string, circleIDs: Array<string>): Promise<boolean>;
     /**
-     * Store a delegation token. A re-minted grant covering the same
-     * `(grantor, audience, resource)` replaces the existing row when its `hlc`
-     * is causally newer; an older or equal `hlc` is ignored. Held rows
-     * (`audience` is self) and issued rows (`grantor` is self) are distinct keys
-     * and never collide.
-     *
-     * Returns `true` when the stored row is new or materially different from
-     * the prior row (insert, or LWW upsert that changed any of `jti`, `token`,
-     * `act`, `exp`, `group_id`). Returns `false` when the call was a no-op:
-     * either the incoming `hlc` lost LWW against an existing row, or the LWW
-     * upsert won but every content field matched the prior row (identical
-     * re-broadcast). Used by emission gates to suppress duplicate
-     * `delegationTokenAdded` events on idempotent re-stores.
-     */
-    addDelegationToken(token: InsertDelegationToken): Promise<boolean>;
-    getDelegationTokens(params: {
-        grantor: string;
-        audience: string;
-    }): Promise<Array<DelegationToken>>;
-    /**
-     * Return the tokens held by `audience` that are still valid at `atTime`
-     * (`exp > atTime`). `atTime` is a Unix epoch in seconds, matching the
-     * `exp` column. Expired tokens and tokens addressed to other audiences are
-     * excluded.
-     */
-    getHeldTokens(params: {
-        audience: string;
-        atTime: number;
-    }): Promise<Array<DelegationToken>>;
-    listIssuedTokens(grantor: string): Promise<Array<DelegationToken>>;
-    /**
-     * Look up a delegation token by its `jti`. `jti` is not part of the schema's
-     * composite PK `(grantor, audience, resource)`, so the column is non-unique
-     * at the SQL level; in practice every `grantWriteCapability` call mints a
-     * fresh random `jti`, so collisions across distinct `(grantor, audience,
-     * resource)` tuples do not occur. Returns the first matching row, or `null`
-     * when no row exists for the given `jti`.
-     */
-    getDelegationTokenByJti(jti: string): Promise<DelegationToken | null>;
-    /**
-     * Store a revocation record keyed by the revoked capability's `jti`. LWW on
-     * `hlc` — a re-broadcast with an older or equal `hlc` is ignored. Returns
-     * `true` when the row is new, or when LWW won and any content field
-     * (`revoker_did`, `revoked_iat`, `revocation_token`, `verified_at`,
-     * `cap_exp`, `group_id`) materially changed. Returns `false` on a no-op
-     * (lost LWW, or won LWW with byte-identical content). Used by emission
-     * gates to suppress duplicate downstream events on idempotent re-stores.
-     *
-     * `verified_at` is `null` while the revoker-vs-cap-issuer cross-check is
-     * pending; verification flips it via `markRevocationVerified`.
-     */
-    addRevocation(input: InsertRevokedCapability): Promise<boolean>;
-    getRevocation(jti: string): Promise<RevokedCapability | null>;
-    /**
-     * Hot-path check used at mutation-apply time. Returns `true` only when a
-     * row exists for `jti` AND it has been verified against the cap's issuer
-     * (`verified_at IS NOT NULL`). Pending (unverified) revocations do not
-     * gate writes; the gate fails open for light clients that do not
-     * replicate the revocations table.
-     */
-    isRevoked(jti: string): Promise<boolean>;
-    /**
-     * Return verified revocations that target capabilities held by `audience`.
-     * INNER JOIN against `kubun_p2p_delegation_tokens` on `jti` — verified
-     * revocations whose cap row is missing locally are excluded, and
-     * `audience`/`grantor` are sourced from the cap row. Pending revocations
-     * (`verified_at IS NULL`) are not surfaced. No `atTime` filter: verified
-     * revocations remain visible to the audience until lifecycle GC removes
-     * them, even after the underlying cap has expired.
-     */
-    getHeldRevocations(params: {
-        audience: string;
-    }): Promise<Array<HeldRevocation>>;
-    /**
-     * Flip a pending revocation to verified. Idempotent: returns `true` only
-     * when a previously-pending row was updated; returns `false` when the row
-     * is missing or already verified.
-     */
-    markRevocationVerified(jti: string, params: {
-        cap_exp: number;
-        verified_at?: number;
-    }): Promise<boolean>;
-    getPendingRevocationByJti(jti: string): Promise<RevokedCapability | null>;
+     * 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;
+    }): Promise<void>;
     /**
-     * Delete a pending revocation row (`verified_at IS NULL`) for the given
-     * `jti`. Verified rows are preserved — a verified revocation is binding and
-     * must not be removed by this method (use `purgeExpiredRevocations` for
-     * lifecycle cleanup). Returns `true` when a pending row was deleted, `false`
-     * otherwise (no row, or row already verified).
-     *
-     * Used by the cap-arrival cross-check: when a held cap arrives whose issuer
-     * does not match a pre-existing pending revocation's `revoker_did`, the
-     * pending row is treated as a forged broadcast and dropped.
+     * 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.
      */
-    deletePendingRevocation(jti: string): Promise<boolean>;
+    reconcileCircleMemberProjection(params: {
+        circleID: string;
+        memberDID: string;
+        role: string;
+        hlc: string;
+        removedAtHLC: string | null;
+    }): Promise<void>;
     /**
-     * Delete verified revocation rows whose underlying capability expired more
-     * than `graceSeconds` ago (`cap_exp + graceSeconds < now`). Rows with a
-     * NULL `cap_exp` and pending (unverified) rows are preserved — they have
-     * no expiry to compare against. Returns the number of rows deleted.
+     * Record the group a delegation `jti` was granted in. Idempotent on `jti`
+     * (the primary key): a re-record for a `jti` already present is a no-op. The
+     * delegation token itself lives in the core delegation store; this edge only
+     * carries the group association the p2p layer needs.
      */
-    purgeExpiredRevocations(params: {
-        graceSeconds: number;
-    }): Promise<number>;
+    addGroupDelegation(edge: InsertGroupDelegation): Promise<void>;
     /**
-     * Delete pending revocation rows (`verified_at IS NULL`) whose `created_at`
-     * is older than `maxAgeSeconds`. Verified rows are preserved regardless of
-     * their `created_at` age. Returns the number of rows deleted.
-     *
-     * A negative `maxAgeSeconds` pushes the threshold into the future and will
-     * delete every pending row regardless of age — intended only for test
-     * scaffolding (avoids needing raw-SQL `UPDATE` to backdate `created_at`).
-     * Do not pass negative values from production code paths.
-     */
-    purgeDeadPendingRevocations(params: {
-        maxAgeSeconds: number;
-    }): Promise<number>;
+     * Resolve the group a delegation `jti` was granted in, or `null` when no edge
+     * exists. Used to target revoke broadcasts and to enrich revocation listings
+     * with their originating group.
+     */
+    getGroupIDByJTI(jti: string): Promise<string | null>;
+    /**
+     * Batch variant of {@link getGroupIDByJTI}: resolve the group each `jti` was
+     * granted in, returning a `Map` keyed by `jti`. A `jti` with no edge is absent
+     * from the map. Used to enrich revocation listings without an N+1 lookup.
+     */
+    getGroupIDsByJTIs(jtis: Array<string>): Promise<Map<string, string>>;
     saveMLSState(state: InsertGroupMLSState): Promise<void>;
     getMLSState(groupID: string, deviceID: string): Promise<GroupMLSState | undefined>;
     deleteMLSState(groupID: string, deviceID: string): Promise<void>;
@@ -206,6 +210,31 @@ export type P2PStoreAPI = {
         version: string;
         mlsGroupID: string;
     }): Promise<boolean>;
+    /**
+     * Append a verified ledger entry. Idempotent on `entry_id` (the token
+     * digest): a re-delivered entry is a no-op. `issuer_did` is normalized on
+     * write. Returns `true` when a new row was inserted, `false` on a duplicate.
+     */
+    appendLedgerEntry(entry: InsertControlLedgerEntry): Promise<boolean>;
+    /** All ledger entries for a group, ordered by `(hlc, entry_id)`. */
+    getLedgerEntries(groupID: string): Promise<Array<ControlLedgerEntry>>;
+    /** Ledger entries for a group filtered by `type`, ordered by `(hlc, entry_id)`. */
+    getLedgerEntriesByType(groupID: string, type: string): Promise<Array<ControlLedgerEntry>>;
+    /**
+     * The HLC through which `projection` has been folded for `groupID`, or `null`
+     * when no projection has run yet. A caller treats an entry whose HLC is `>`
+     * this value as in-order (apply incrementally); `<=` or `null` means the
+     * cached projection is no longer a correct fold-through-this-entry and must be
+     * rebuilt from the whole ledger.
+     */
+    getProjectionWatermark(groupID: string, projection: string): Promise<string | null>;
+    /**
+     * Set the `(groupID, projection)` watermark to `hlc`. Overwrite-on-conflict:
+     * the row is unconditionally replaced. Callers must only advance the watermark
+     * — the incremental path passes a value strictly newer than the current one,
+     * and the reproject path passes the true max over the folded ledger.
+     */
+    setProjectionWatermark(groupID: string, projection: string, hlc: string): Promise<void>;
     insertHub(hub: InsertHub): Promise<void>;
     getHub(id: string): Promise<Hub | undefined>;
     getHubByURL(url: string): Promise<Hub | undefined>;
@@ -222,4 +251,4 @@ export type P2PStoreAPI = {
     listGroupsByHubID(hubID: string): Promise<Array<Group>>;
     deleteGroupHubsByHubID(hubID: string): Promise<void>;
 };
-export declare function createP2PStore(db: Kysely<P2PStoreTables>, adapter: Adapter, logger?: Logger): P2PStoreAPI;
+export declare function createP2PStore(db: Kysely<P2PStoreTables>, adapter: Adapter): P2PStoreAPI;