@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/groups/circle-projection.d.ts

@@ -0,0 +1,122 @@
+import type { Logger } from '@kubun/logger';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import { type CircleDefValue, type CircleMemberValue, type GroupSettingsValue, type IsAdminAtHLC } from './circle-reducers.js';
+import type { GroupAnchor } from './group-anchor.js';
+import { type VerifiedLedgerEntry } from './ledger-entry.js';
+import { type FoldInput } from './ledger-fold.js';
+/**
+ * Projection keys, one per entry type — the watermark slot a reproject /
+ * incremental advances. Mirrors `ADMIN_ROSTER_PROJECTION`: a single projection
+ * per ledger type, so the key is the type itself.
+ */
+export declare const CIRCLE_DEF_PROJECTION = "circle.def";
+export declare const CIRCLE_MEMBER_PROJECTION = "circle.member";
+export declare const GROUP_SETTINGS_PROJECTION = "group.settings";
+export declare const loadVerifiedCircleDefEntries: (store: P2PStoreAPI, groupID: string, logger?: Logger) => Promise<FoldInput<CircleDefValue>[]>;
+export declare const loadVerifiedCircleMemberEntries: (store: P2PStoreAPI, groupID: string, logger?: Logger) => Promise<FoldInput<CircleMemberValue>[]>;
+export declare const loadVerifiedGroupSettingsEntries: (store: P2PStoreAPI, groupID: string, logger?: Logger) => Promise<FoldInput<GroupSettingsValue>[]>;
+/**
+ * One projected circle row as the fold decides it. `hlc` is the winning active
+ * entry's HLC (the row's `hlc` column); `removedAtHLC` is the winning tombstone
+ * HLC, or null when the circle is active. A removed circle retains its last
+ * active definition so the tombstone row carries real columns — mirroring the
+ * LWW store where `markCircleRemoved` only sets `removed_at_hlc` and leaves the
+ * name/description intact.
+ */
+export type CircleDefProjectionRow = {
+    name: string;
+    description: string;
+    catalogIDs: Array<string>;
+    hlc: string;
+    removedAtHLC: string | null;
+};
+/**
+ * Fold the circle-definition ledger into a per-circle projection covering ALL
+ * subjects, active and removed — the active reducer drops removed circles, but a
+ * projection must keep a tombstone row for them. Replays in total order under
+ * the same admin-authority gate as the reducer: an active entry sets the
+ * definition and clears any tombstone (re-add), a tombstone marks the row
+ * removed while keeping its last active value. A circle whose only entry is a
+ * tombstone (no prior active value) produces no row, matching the LWW store's
+ * ignore-if-absent removal.
+ */
+export declare function projectCircleDefs(entries: Array<FoldInput<CircleDefValue>>, isAdminAtHLC: IsAdminAtHLC): Map<string, CircleDefProjectionRow>;
+/** One projected circle-member row, keyed by the composite ledger subject. */
+export type CircleMemberProjectionRow = {
+    circleID: string;
+    memberDID: string;
+    role: string;
+    hlc: string;
+    removedAtHLC: string | null;
+};
+/**
+ * Fold the circle-member ledger into a per-subject projection covering ALL
+ * subjects, active and removed. Same structure as {@link projectCircleDefs}: an
+ * active entry sets the role and clears any tombstone, a tombstone marks the row
+ * removed while keeping its last active role. A malformed subject is skipped, as
+ * is a tombstone with no prior active value.
+ */
+export declare function projectCircleMembers(entries: Array<FoldInput<CircleMemberValue>>, isAdminAtHLC: IsAdminAtHLC): Map<string, CircleMemberProjectionRow>;
+/**
+ * Authoritatively rebuild a circle/settings projection from the whole ledger and
+ * reset the watermark to the newest folded entry. Used on a first projection, an
+ * out-of-order arrival, or drift repair — anywhere the cached projection can no
+ * longer be trusted as a fold-through-watermark. Authority is the admin fold
+ * (`adminAuthorityFromEntries`), so every projection honors the same admin gate
+ * the broadcast path enforces. Each `reconcile*` write is unconditional, so the
+ * row converges to exactly the fold's decision regardless of prior contents.
+ */
+export type ReprojectCircleParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    logger?: Logger;
+};
+export declare function reprojectCircleDefs(params: ReprojectCircleParams): Promise<void>;
+export declare function reprojectCircleMembers(params: ReprojectCircleParams): Promise<void>;
+/**
+ * Reproject group settings onto the group row. Settings are PARTIAL per-field
+ * (no tombstone), so the committed reducer's active map IS the full projection:
+ * fold it under the admin gate, then write the merged fields via the
+ * unconditional `updateGroup`. A field no entry ever set stays at the group's
+ * original value (creation-time name/description).
+ */
+export declare function reprojectGroupSettings(params: ReprojectCircleParams): Promise<void>;
+/**
+ * Apply one strictly-newer-than-watermark entry onto the current projection
+ * without re-folding the whole ledger. The caller guarantees the entry is
+ * in-order, so the projection already equals the fold-so-far. Authority is the
+ * admin fold at the entry's own HLC: a non-admin issuer is dropped (never
+ * thrown). Unlike the admin roster's incremental applier — whose authority reads
+ * the projection itself — circle authority lives in the separate admin
+ * sub-ledger, so the admin entries are loaded here.
+ *
+ * The watermark is advanced by the caller (the ingest handler), not here —
+ * mirroring the admin roster's split of responsibility — so the projection
+ * mutation and the watermark advance stay in the handler's single transaction
+ * even when the entry is dropped (it is still durable and accounted for).
+ */
+export type ApplyCircleDefEntryIncrementalParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    verified: VerifiedLedgerEntry<CircleDefValue>;
+    logger?: Logger;
+};
+export declare function applyCircleDefEntryIncremental(params: ApplyCircleDefEntryIncrementalParams): Promise<void>;
+export type ApplyCircleMemberEntryIncrementalParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    verified: VerifiedLedgerEntry<CircleMemberValue>;
+    logger?: Logger;
+};
+export declare function applyCircleMemberEntryIncremental(params: ApplyCircleMemberEntryIncrementalParams): Promise<void>;
+export type ApplyGroupSettingsEntryIncrementalParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    verified: VerifiedLedgerEntry<GroupSettingsValue>;
+    logger?: Logger;
+};
+export declare function applyGroupSettingsEntryIncremental(params: ApplyGroupSettingsEntryIncrementalParams): Promise<void>;

package/lib/groups/circle-projection.js

@@ -0,0 +1,288 @@
+import { loadVerifiedAdminEntries } from './admin-roster.js';
+import { adminAuthorityFromEntries, CIRCLE_DEF_ENTRY_TYPE, CIRCLE_MEMBER_ENTRY_TYPE, createGroupSettingsReducer, decodeCircleMemberSubject, GROUP_SETTINGS_ENTRY_TYPE } from './circle-reducers.js';
+import { verifyLedgerEntry } from './ledger-entry.js';
+import { foldLedger } from './ledger-fold.js';
+/**
+ * Projection keys, one per entry type — the watermark slot a reproject /
+ * incremental advances. Mirrors `ADMIN_ROSTER_PROJECTION`: a single projection
+ * per ledger type, so the key is the type itself.
+ */ export const CIRCLE_DEF_PROJECTION = CIRCLE_DEF_ENTRY_TYPE;
+export const CIRCLE_MEMBER_PROJECTION = CIRCLE_MEMBER_ENTRY_TYPE;
+export const GROUP_SETTINGS_PROJECTION = GROUP_SETTINGS_ENTRY_TYPE;
+function isRemovedDef(value) {
+    return 'removed' in value && value.removed === true;
+}
+function isRemovedMember(value) {
+    return 'removed' in value && value.removed === true;
+}
+/** Total order over the ledger: HLC first, content-addressed id breaks ties. */ function byTotalOrder(a, b) {
+    if (a.verified.entry.hlc !== b.verified.entry.hlc) {
+        return a.verified.entry.hlc < b.verified.entry.hlc ? -1 : 1;
+    }
+    if (a.entryID === b.entryID) return 0;
+    return a.entryID < b.entryID ? -1 : 1;
+}
+function maxHLC(entries) {
+    let max = null;
+    for (const { verified } of entries){
+        if (max == null || verified.entry.hlc > max) max = verified.entry.hlc;
+    }
+    return max;
+}
+// --- Per-type verified-entry loaders ---
+/**
+ * Build a verified-entry loader for one ledger type, memoized per group on the
+ * stored id set. The stored token is re-verified rather than trusting the
+ * decoded `value` column — the ledger is the source of truth and must stay
+ * self-verifying, so a token that no longer verifies is dropped and the rest
+ * survive. The cache key is derived purely from content-addressed entry ids, so
+ * a forged or altered entry yields a different id set, a different key, and a
+ * full re-verification; one slot per group self-invalidates on every append.
+ * One cache instance per type keeps the slots isolated across ledger types.
+ */ function createVerifiedEntryLoader(entryType) {
+    const cache = new Map();
+    return async (store, groupID, logger)=>{
+        const rows = await store.getLedgerEntriesByType(groupID, entryType);
+        const key = rows.map((row)=>row.entry_id).join('\n');
+        const cached = cache.get(groupID);
+        if (cached != null && cached.key === key) {
+            return cached.entries;
+        }
+        const entries = [];
+        for (const row of rows){
+            const verified = await verifyLedgerEntry(row.signed_token);
+            if (verified == null) {
+                logger?.warn('circle projection: dropped stored entry whose token no longer verifies', {
+                    groupID,
+                    entryType,
+                    entryID: row.entry_id
+                });
+                continue;
+            }
+            entries.push({
+                verified,
+                entryID: row.entry_id
+            });
+        }
+        cache.set(groupID, {
+            key,
+            entries
+        });
+        return entries;
+    };
+}
+export const loadVerifiedCircleDefEntries = createVerifiedEntryLoader(CIRCLE_DEF_ENTRY_TYPE);
+export const loadVerifiedCircleMemberEntries = createVerifiedEntryLoader(CIRCLE_MEMBER_ENTRY_TYPE);
+export const loadVerifiedGroupSettingsEntries = createVerifiedEntryLoader(GROUP_SETTINGS_ENTRY_TYPE);
+/**
+ * Fold the circle-definition ledger into a per-circle projection covering ALL
+ * subjects, active and removed — the active reducer drops removed circles, but a
+ * projection must keep a tombstone row for them. Replays in total order under
+ * the same admin-authority gate as the reducer: an active entry sets the
+ * definition and clears any tombstone (re-add), a tombstone marks the row
+ * removed while keeping its last active value. A circle whose only entry is a
+ * tombstone (no prior active value) produces no row, matching the LWW store's
+ * ignore-if-absent removal.
+ */ export function projectCircleDefs(entries, isAdminAtHLC) {
+    const rows = new Map();
+    for (const { verified } of [
+        ...entries
+    ].sort(byTotalOrder)){
+        if (!isAdminAtHLC(verified.issuer, verified.entry.hlc)) continue;
+        const { subject, value, hlc } = verified.entry;
+        if (isRemovedDef(value)) {
+            const existing = rows.get(subject);
+            if (existing == null) continue;
+            rows.set(subject, {
+                ...existing,
+                removedAtHLC: hlc
+            });
+        } else {
+            rows.set(subject, {
+                name: value.name,
+                description: value.description,
+                catalogIDs: value.catalogIDs,
+                hlc,
+                removedAtHLC: null
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * Fold the circle-member ledger into a per-subject projection covering ALL
+ * subjects, active and removed. Same structure as {@link projectCircleDefs}: an
+ * active entry sets the role and clears any tombstone, a tombstone marks the row
+ * removed while keeping its last active role. A malformed subject is skipped, as
+ * is a tombstone with no prior active value.
+ */ export function projectCircleMembers(entries, isAdminAtHLC) {
+    const rows = new Map();
+    for (const { verified } of [
+        ...entries
+    ].sort(byTotalOrder)){
+        if (!isAdminAtHLC(verified.issuer, verified.entry.hlc)) continue;
+        const { subject, value, hlc } = verified.entry;
+        if (isRemovedMember(value)) {
+            const existing = rows.get(subject);
+            if (existing == null) continue;
+            rows.set(subject, {
+                ...existing,
+                removedAtHLC: hlc
+            });
+        } else {
+            const decoded = decodeCircleMemberSubject(subject);
+            if (decoded == null) continue;
+            rows.set(subject, {
+                circleID: decoded.circleID,
+                memberDID: decoded.memberDID,
+                role: value.role,
+                hlc,
+                removedAtHLC: null
+            });
+        }
+    }
+    return rows;
+}
+async function adminAuthorityFor(params) {
+    const adminEntries = await loadVerifiedAdminEntries(params.store, params.groupID, params.logger);
+    return adminAuthorityFromEntries(adminEntries, params.anchor);
+}
+export async function reprojectCircleDefs(params) {
+    const { store, groupID } = params;
+    const [isAdmin, entries] = await Promise.all([
+        adminAuthorityFor(params),
+        loadVerifiedCircleDefEntries(store, groupID, params.logger)
+    ]);
+    const rows = projectCircleDefs(entries, isAdmin);
+    for (const [circleID, row] of rows){
+        await store.reconcileCircleProjection({
+            id: circleID,
+            groupID,
+            name: row.name,
+            description: row.description,
+            catalogIDs: row.catalogIDs,
+            hlc: row.hlc,
+            removedAtHLC: row.removedAtHLC
+        });
+    }
+    const max = maxHLC(entries);
+    if (max != null) {
+        await store.setProjectionWatermark(groupID, CIRCLE_DEF_PROJECTION, max);
+    }
+}
+export async function reprojectCircleMembers(params) {
+    const { store, groupID } = params;
+    const [isAdmin, entries] = await Promise.all([
+        adminAuthorityFor(params),
+        loadVerifiedCircleMemberEntries(store, groupID, params.logger)
+    ]);
+    const rows = projectCircleMembers(entries, isAdmin);
+    for (const row of rows.values()){
+        await store.reconcileCircleMemberProjection({
+            circleID: row.circleID,
+            memberDID: row.memberDID,
+            role: row.role,
+            hlc: row.hlc,
+            removedAtHLC: row.removedAtHLC
+        });
+    }
+    const max = maxHLC(entries);
+    if (max != null) {
+        await store.setProjectionWatermark(groupID, CIRCLE_MEMBER_PROJECTION, max);
+    }
+}
+/**
+ * Reproject group settings onto the group row. Settings are PARTIAL per-field
+ * (no tombstone), so the committed reducer's active map IS the full projection:
+ * fold it under the admin gate, then write the merged fields via the
+ * unconditional `updateGroup`. A field no entry ever set stays at the group's
+ * original value (creation-time name/description).
+ */ export async function reprojectGroupSettings(params) {
+    const { store, groupID, anchor } = params;
+    const [isAdmin, entries] = await Promise.all([
+        adminAuthorityFor(params),
+        loadVerifiedGroupSettingsEntries(store, groupID, params.logger)
+    ]);
+    const { settings } = foldLedger(entries, anchor, createGroupSettingsReducer(isAdmin));
+    const merged = settings.get(groupID);
+    if (merged != null) {
+        await store.updateGroup(groupID, merged);
+    }
+    const max = maxHLC(entries);
+    if (max != null) {
+        await store.setProjectionWatermark(groupID, GROUP_SETTINGS_PROJECTION, max);
+    }
+}
+export async function applyCircleDefEntryIncremental(params) {
+    const { store, groupID, anchor, verified, logger } = params;
+    const adminEntries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const isAdmin = adminAuthorityFromEntries(adminEntries, anchor);
+    const { subject, value, hlc } = verified.entry;
+    if (!isAdmin(verified.issuer, hlc)) {
+        logger?.warn('circle projection: dropped incremental circle.def from a non-admin issuer', {
+            groupID,
+            issuer: verified.issuer
+        });
+    } else if (isRemovedDef(value)) {
+        // Tombstone an existing active row, leaving its name/description intact —
+        // the LWW removal write, correct for an in-order entry on the active row.
+        await store.markCircleRemoved(subject, hlc);
+    } else {
+        await store.reconcileCircleProjection({
+            id: subject,
+            groupID,
+            name: value.name,
+            description: value.description,
+            catalogIDs: value.catalogIDs,
+            hlc,
+            removedAtHLC: null
+        });
+    }
+}
+export async function applyCircleMemberEntryIncremental(params) {
+    const { store, groupID, anchor, verified, logger } = params;
+    const adminEntries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const isAdmin = adminAuthorityFromEntries(adminEntries, anchor);
+    const { subject, value, hlc } = verified.entry;
+    if (!isAdmin(verified.issuer, hlc)) {
+        logger?.warn('circle projection: dropped incremental circle.member from a non-admin issuer', {
+            groupID,
+            issuer: verified.issuer
+        });
+    } else if (isRemovedMember(value)) {
+        const decoded = decodeCircleMemberSubject(subject);
+        if (decoded != null) {
+            await store.removeCircleMember(decoded.circleID, decoded.memberDID, hlc);
+        }
+    } else {
+        const decoded = decodeCircleMemberSubject(subject);
+        if (decoded != null) {
+            await store.reconcileCircleMemberProjection({
+                circleID: decoded.circleID,
+                memberDID: decoded.memberDID,
+                role: value.role,
+                hlc,
+                removedAtHLC: null
+            });
+        }
+    }
+}
+export async function applyGroupSettingsEntryIncremental(params) {
+    const { store, groupID, anchor, verified, logger } = params;
+    const adminEntries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const isAdmin = adminAuthorityFromEntries(adminEntries, anchor);
+    const { value, hlc } = verified.entry;
+    if (!isAdmin(verified.issuer, hlc)) {
+        logger?.warn('circle projection: dropped incremental group.settings from a non-admin issuer', {
+            groupID,
+            issuer: verified.issuer
+        });
+    } else {
+        // Per-field merge onto the group row: `updateGroup` sets only the fields the
+        // entry carries (an explicit `''` clears; an omitted field is left alone).
+        await store.updateGroup(groupID, {
+            name: value.name,
+            description: value.description
+        });
+    }
+}

package/lib/groups/circle-reducers.d.ts

@@ -0,0 +1,178 @@
+import { type AdminRoleValue } from './admin-roster.js';
+import type { GroupAnchor } from './group-anchor.js';
+import type { FoldInput, LedgerReducer } from './ledger-fold.js';
+/**
+ * The fold's authority gate: was `issuer` a group admin at `hlc`? The reducer
+ * factories take this predicate so the projection fold stays synchronous and
+ * deterministic from the ledger alone — every peer that folds the same ledger
+ * resolves the same authority and converges to the same state. By design this
+ * gate is the LEDGER admin-fold ONLY: membership and MLS-removal are enforced
+ * outside the projection (the live broadcast gate and the MLS roster), never
+ * conjoined here, so the fold never needs an async store read.
+ */
+export type IsAdminAtHLC = (issuer: string, hlc: string) => boolean;
+/** Ledger entry `type` for a circle-membership claim. */
+export declare const CIRCLE_MEMBER_ENTRY_TYPE = "circle.member";
+/**
+ * The claim carried by a circle-member entry. The active form names the
+ * member's role within the circle; the tombstone form removes them. Both are
+ * whole-value: the highest-ordered entry for a subject replaces the projected
+ * state outright, so the value alone decides active-with-role vs removed. `role`
+ * mirrors the store's free-form role column (no fixed enum), so it stays a
+ * string rather than inventing a circle-specific role type.
+ */
+export type CircleMemberValue = {
+    role: string;
+} | {
+    removed: true;
+};
+/**
+ * Deterministic composite subject for a circle member. The signed entry's
+ * `subject` encodes both the circle and the member, so the ledger's `subject`
+ * column uniquely identifies the pair and per-member LWW ordering + dedup work
+ * without consulting the value.
+ *
+ * Unambiguous because the member is a normalized DID (`did:method:...`), which
+ * never contains the `/member:` separator: every reachable separator therefore
+ * sits between the circle id and the DID, and the decoder splits on the last
+ * one. The labeled `circle:` / `/member:` prefixes also keep the encoding
+ * distinct from any other reducer's subject scheme.
+ */
+export declare function encodeCircleMemberSubject(circleID: string, memberDID: string): string;
+/** Tolerant inverse of {@link encodeCircleMemberSubject}: null on a malformed subject. */
+export declare function decodeCircleMemberSubject(subject: string): {
+    circleID: string;
+    memberDID: string;
+} | null;
+/**
+ * Folded circle membership, keyed by composite subject. Only active members are
+ * present — a subject whose highest-ordered entry is a tombstone is absent from
+ * the map.
+ */
+export type CircleMemberState = {
+    members: Map<string, {
+        circleID: string;
+        memberDID: string;
+        role: string;
+    }>;
+};
+/**
+ * Per-member last-writer-wins circle roster. {@link foldLedger} sorts by the
+ * total order `(hlc, entryID)`, so each subject's highest-ordered entry is
+ * applied last and decides the outcome: an active value sets the member with its
+ * role, a tombstone removes them. Whole-value replacement means add / remove /
+ * re-add converge to the same state on every peer regardless of arrival order.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC so a key authorized when it wrote stays authorized even after a later
+ * revoke. The gate is the ledger admin-fold ONLY — membership and MLS-removal
+ * are enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */
+export declare function createCircleMemberReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<CircleMemberValue, CircleMemberState>;
+/** Ledger entry `type` for a circle definition (create / update / delete). */
+export declare const CIRCLE_DEF_ENTRY_TYPE = "circle.def";
+/**
+ * The claim carried by a circle-definition entry. The active form is the whole
+ * circle definition; the tombstone form deletes it. Both are whole-value: the
+ * highest-ordered entry for a circle replaces the projected definition outright,
+ * so create and update share one shape and the value alone decides present vs
+ * deleted.
+ */
+export type CircleDefValue = {
+    name: string;
+    description: string;
+    catalogIDs: Array<string>;
+} | {
+    removed: true;
+};
+/**
+ * Folded circle definitions, keyed by circleID. Only present circles appear — a
+ * circle whose highest-ordered entry is a tombstone is absent from the map.
+ */
+export type CircleDefState = {
+    circles: Map<string, {
+        name: string;
+        description: string;
+        catalogIDs: Array<string>;
+    }>;
+};
+/**
+ * Per-circle last-writer-wins definition. The signed entry's `subject` is the
+ * circleID directly, so no decode is needed. {@link foldLedger} sorts by the
+ * total order `(hlc, entryID)`, so each circle's highest-ordered entry is
+ * applied last and decides the outcome: an active value sets the definition, a
+ * tombstone deletes it. Whole-value replacement means create / update / delete
+ * converge to the same state on every peer regardless of arrival order.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
+ * enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */
+export declare function createCircleDefReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<CircleDefValue, CircleDefState>;
+/** Ledger entry `type` for a group-settings claim. */
+export declare const GROUP_SETTINGS_ENTRY_TYPE = "group.settings";
+/**
+ * The claim carried by a group-settings entry. Unlike `circle.def` /
+ * `circle.member`, this value is PARTIAL: an entry sets only the fields it
+ * carries and stays silent about the rest. A field omitted from the
+ * value leaves the prior value untouched; setting a field to `''` is a real
+ * value that clears it. There is no tombstone — group settings are never
+ * deleted, only overwritten field by field.
+ */
+export type GroupSettingsValue = {
+    name?: string;
+    description?: string;
+};
+/** Folded group settings, keyed by groupID (the entry subject). */
+export type GroupSettingsState = {
+    settings: Map<string, {
+        name?: string;
+        description?: string;
+    }>;
+};
+/**
+ * Per-field last-writer-wins group settings. The signed entry's `subject` is the
+ * groupID directly, so no decode is needed. {@link foldLedger} sorts by the total
+ * order `(hlc, entryID)` and applies low→high, so for each field the
+ * highest-ordered entry that SETS that field wins naturally.
+ *
+ * This reducer merges per field rather than replacing the whole value the way
+ * `circle.def` / `circle.member` do: those project a single cohesive record
+ * where add / remove / re-add must converge to one state, so whole-value
+ * replacement is correct. Group settings instead accumulate independent fields
+ * (`name`, `description`) that different entries touch in isolation, so a
+ * name-only update must not clobber a previously-set description. Presence is
+ * decided by `value.field !== undefined` rather than `'field' in value`: an
+ * explicit `undefined` is treated as "not set" (no change), while `''` is a real
+ * value that clears the field.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
+ * enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */
+export declare function createGroupSettingsReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<GroupSettingsValue, GroupSettingsState>;
+/**
+ * Build an {@link IsAdminAtHLC} predicate from the group's verified admin-role
+ * ledger entries. It re-folds the admin sub-ledger at each queried entry's HLC,
+ * so the answer is rotation-aware (was-admin-at-HLC, not is-admin-now): a key
+ * granted admin at HLC h authorizes entries at or after h, and a later revoke
+ * stops authorizing entries from that point on. `foldAdminRoster`'s `atHLC`
+ * compare is inclusive (`entry.hlc <= atHLC`), so an entry at exactly the grant
+ * HLC sees the grant and is authorized, and an entry at exactly the revoke HLC
+ * sees the revoke and is not.
+ *
+ * Callers load the verified admin entries once (via `loadVerifiedAdminEntries`)
+ * and reuse the returned predicate across the circle / def / settings folds.
+ *
+ * Authority here is ledger-admin-only: it answers "did the ledger grant this
+ * issuer admin at this HLC?" and does NOT check the issuer's MLS membership at
+ * that HLC. So an admin who was removed from the MLS group but whose admin role
+ * was never revoked on the ledger still has authorizing entries folded in.
+ * Closing that requires removal to write a ledger revocation atomically with the
+ * MLS-roster delta (the same MLS-commit/roster atomicity work that keeps a
+ * removed member's writes from applying); it is deliberately out of scope here.
+ */
+export declare function adminAuthorityFromEntries(adminEntries: Array<FoldInput<AdminRoleValue>>, anchor: GroupAnchor): IsAdminAtHLC;