@kokuin/controller 0.1.0

package/lib/resolver.js

@@ -0,0 +1,121 @@
+import { DID_PREFIX } from './events.js';
+import { authoritativeStates } from './history.js';
+import { allStatesAsync } from './state.js';
+import { agreementKeysFrom, DID_METHOD, signingKeyFrom } from './state-resolver.js';
+const CONTEXT = 'Controller resolver';
+/**
+ * A `did:kokuin:` resolver for `@kokuin/token`. Injected rather than imported by token: this package
+ * depends on token for signing, so the reverse import would cycle. Token resolves `iss` through the
+ * interface without knowing the fold exists.
+ */ export function createControllerResolver(options) {
+    // The fold currently under way for each DID, so overlapping resolutions of one DID share it (two
+    // tokens from one issuer verified in parallel is ordinary — token caches only `did:peer:4`).
+    //
+    // Also the last line against a `loadLog` that re-enters resolution for the DID it is loading. The
+    // fold no longer does that itself, but a caller's `loadLog` can still reach `resolve` for the same
+    // DID: sharing the pending fold makes that a quiet deadlock the caller's request timeout catches,
+    // rather than an await-chained Ed25519 loop that starves the timer queue.
+    //
+    // Not a cache: removed as soon as the fold settles, so a later resolution re-folds.
+    const inFlight = new Map();
+    // Shared by every member: load, fold, throw `Unknown DID` when absent. The whole state array
+    // rather than the head, because `resolveHistoric` answers about rotated-away keys; head-only
+    // members take `states[states.length - 1]`. Always the async fold: it differs from `foldLog` only
+    // in awaiting a capability-authorised revoke's verifier, so a mode-selecting option would choose
+    // nothing — the verifier is the only thing a caller supplies.
+    async function computeStates(did) {
+        const events = await options.loadLog(did);
+        if (events == null || events.length === 0) {
+            throw new Error(`Unknown DID: ${did}`);
+        }
+        const foldOptions = {
+            verifyCapability: options.verifyCapability
+        };
+        if (options.history == null) {
+            return await allStatesAsync({
+                did,
+                events,
+                context: CONTEXT,
+                options: foldOptions
+            });
+        }
+        // Compared against what this party last accepted, so a truncated log — folding cleanly, missing
+        // the revoke that matters — is refused. See `LogStore`.
+        const seen = await options.history.get(did);
+        const { log, states } = await authoritativeStates({
+            did,
+            loaded: events,
+            seen,
+            context: CONTEXT,
+            options: foldOptions
+        });
+        // Only after it has folded, and only in the memory-keeping direction: a log that lost never
+        // reaches here, so the store never moves backwards.
+        await options.history.set(did, log);
+        return states;
+    }
+    async function loadStates(did) {
+        if (!did.startsWith(DID_PREFIX)) {
+            throw new Error(`Unknown DID: ${did}`);
+        }
+        const pending = inFlight.get(did);
+        if (pending != null) {
+            // Awaiting an existing fold, never clearing it — the call that created it owns removal, so a
+            // joiner cannot evict an entry a third caller is about to join.
+            return await pending;
+        }
+        // Deferred by a microtask so the entry is registered *before* `loadLog` runs — otherwise a
+        // `loadLog` that re-enters `resolve` before its own first `await` recurses to a stack overflow
+        // while the map is still empty.
+        const fold = Promise.resolve().then(()=>computeStates(did));
+        inFlight.set(did, fold);
+        try {
+            return await fold;
+        } finally{
+            // Removal is what keeps this from being a cache: the next resolution re-reads and re-folds, so
+            // a revoke landing between two resolutions takes effect. In `finally`, so a rejected fold
+            // clears too.
+            inFlight.delete(did);
+        }
+    }
+    return {
+        method: DID_METHOD,
+        // The head's key set only: a profile that rotated away from a key answers "no" for it here, which
+        // is what makes `rotate` retire a leaked authority key rather than add one beside it.
+        async resolve (did, header = {}) {
+            return signingKeyFrom({
+                did,
+                states: await loadStates(did),
+                header
+            });
+        },
+        // Every key set within the current generation, for a caller verifying past-issued material. A
+        // `rotate` must not invalidate those; a `reset` still does, and the scan stops at the generation
+        // boundary. See `signingKeyFrom` in `state-resolver.ts`.
+        async resolveHistoric (did, header = {}) {
+            return signingKeyFrom({
+                did,
+                states: await loadStates(did),
+                header,
+                historic: true
+            });
+        },
+        async resolveDenySet (did) {
+            // The head's set, deliberately, not the state at any position a capability names: `iat` is
+            // author-supplied and backdatable, so anchoring to it would let a revoked holder pick a
+            // position at which it was not yet denied. The set is position-dependent *within the fold*; the
+            // question a verifier asks is "is this grant valid now". Both spellings ride in it (see
+            // `KeyState.deny`); the key half is enforced by `signingKeyFrom`, and the two forms cannot
+            // collide. `loadStates` throws `Unknown DID` rather than answering an empty (= "nobody
+            // revoked") set.
+            const states = await loadStates(did);
+            return states[states.length - 1].deny;
+        },
+        async resolveAgreementKey (did) {
+            // The head's set only, unlike `resolve`. A retired agreement key is a downgrade, not a grant
+            // the profile already made: the recipient decrypts old ciphertexts by re-deriving from the
+            // seed, never by resolution.
+            return agreementKeysFrom(did, await loadStates(did));
+        }
+    };
+}

package/lib/state-resolver.d.ts

@@ -0,0 +1,60 @@
+import { type DIDMethodResolver, type ResolvedAgreementKey, type ResolvedSigningKey, type ResolveIssuerHeader } from '@kokuin/token';
+import type { KeyState } from './fold.js';
+/** The method segment of {@link DID_PREFIX}, so the two cannot drift. */
+export declare const DID_METHOD: string;
+/**
+ * What a token signed by a revoked key is rejected with. The `#`-prefixed key follows after `: `, so
+ * match with `startsWith`.
+ */
+export declare const KEY_REVOKED = "kid names a key the controller has revoked";
+/**
+ * The signing key `header` names, out of an already-folded log. `historic` picks which question above
+ * is asked, and defaults to the safe one.
+ *
+ * **A revoked key answers neither question.** A `rev` naming `#<key>` retires a key for material it
+ * has *already* signed, and this is where that bites — every `did:kokuin:` signature check reaches a
+ * resolved key through here, so the denial covers `verifyToken` on both `historic` settings, every
+ * capability and revocation record `@kokuin/capability` verifies, and the fold's own cap-authorised
+ * revoke. The historic arm is the live one: a revoked key is never in the head's `k` (the
+ * `KeyState.deny` invariant), so only the backwards scan can select one, and without this
+ * `resolveHistoric` would accept a leaked key forever.
+ *
+ * The head arm cannot be reached from a log this package folded, but is not decoration: `states`
+ * arrives from the caller, and the invariant is the fold's property, not the array's — a
+ * caller-built state whose head publishes a key it also denies resolves to nothing here.
+ *
+ * **Evaluated against the head's deny set, never the position the key was selected at.** A denial is
+ * about the key, not one event, and the position an artefact carries is author-supplied — else a
+ * thief presents a token resolving at a position before the revoke. Deliberately *not* how a DID
+ * denial behaves inside the fold, where `states[i]` is consulted at position `i` because "was this
+ * author allowed to act *here*" is the whole question; the two rules answer different questions.
+ * Inside the fold they coincide anyway: `createStateResolver` gets the prefix `states[0..i-1]`, so
+ * its head *is* the position being verified.
+ */
+export declare function signingKeyFrom({ did, states, header, historic, }: {
+    did: string;
+    states: Array<KeyState>;
+    header: ResolveIssuerHeader;
+    historic?: boolean;
+}): ResolvedSigningKey;
+/**
+ * The head's key agreement set, minus anything it has revoked. A `rev` may name an agreement key as
+ * readily as a signing one (the target spelling is the key, not its purpose), and these are the keys
+ * a *sender* encrypts to — encrypting to a revoked key is the one outcome a denial must prevent.
+ *
+ * Like the signing side, unreachable from a log this package folded (the `KeyState.deny` invariant)
+ * but `states` arrives from the caller. Filtering to empty is the honest answer for a state that
+ * denies everything it publishes: `@kokuin/jwe` then encrypts nothing, the fail-closed direction.
+ */
+export declare function agreementKeysFrom(did: string, states: Array<KeyState>): Array<ResolvedAgreementKey>;
+/**
+ * A `DIDMethodResolver` answering for exactly one profile, out of already-folded state. The fold
+ * hands one to a capability-authorised revoke's verifier, built from the states *before* the event
+ * being verified — the prefix contract made unforgettable: the verifier no longer needs a
+ * position-aware registry, because the fold supplies the answer. See `FoldOptions.verifyCapability`.
+ *
+ * Answers only for `did`; any other identifier is `Unknown DID`, so a caller merging this into a
+ * wider registry falls back to its own resolver for another `did:kokuin:` delegate and never serves
+ * one profile's state for another's. Not a cache: the states are the caller's, fixed at construction.
+ */
+export declare function createStateResolver(did: string, states: Array<KeyState>): DIDMethodResolver;

package/lib/state-resolver.js

@@ -0,0 +1,186 @@
+import { IssuerKeyNotFoundError } from '@kokuin/token';
+import { DID_PREFIX, keyTarget } from './events.js';
+import { decodeKey } from './keys.js';
+/** The method segment of {@link DID_PREFIX}, so the two cannot drift. */ export const DID_METHOD = DID_PREFIX.slice('did:'.length, -1);
+/**
+ * The `kid` fragment's body, or `null` when the header names no key. Format is `#<the multibase key
+ * exactly as it appears in `k`>`, matched against the folded key sets by membership — an index-based
+ * fragment would mean whatever the key set said at the time, and a token outlives that. The bare key
+ * without `#` is rejected, not accepted as a second spelling.
+ *
+ * Every rejection on this path is an `IssuerKeyNotFoundError`, not the plain error the rest of this
+ * file throws: the DID resolved and its log folded — what failed is the key. Load-bearing, because
+ * `resolveIssuerWithDoc` retypes everything else as `UnresolvableIssuerError`, on which
+ * `@kokuin/capability` *denies* a capability; since `kid` is unauthenticated, a fabricated record
+ * naming this DID and any invented key would otherwise deny every capability this controller issued.
+ */ function keyFromKid(did, kid) {
+    if (kid == null) {
+        return null;
+    }
+    if (!kid.startsWith('#')) {
+        throw new IssuerKeyNotFoundError(`Controller ${did} kid is not a key fragment: ${kid}`);
+    }
+    return kid.slice(1);
+}
+/**
+ * The key a token's `kid` names, out of the **head's** key set alone — what `resolve` answers, and
+ * the only question authenticating a live signer may ask ("can this profile sign with this key
+ * *now*"). A key the profile rotated away is not an answer, which is what makes a `rotate` retire a
+ * leaked authority key for new issuance — the middle rung of the `revoke → rotate → reset` ladder.
+ *
+ * A `kid` naming a key not in the head's `k` (including one published earlier) is an error, **never
+ * a fall back to `keys[0]`**, which would check the signature against a key the token never claimed.
+ * An absent `kid` resolves to the head's first key: volunteering one is not the same as accepting one
+ * the token names. Past-issued material is {@link historicSigningKey}, via explicit `resolveHistoric`.
+ */ function headSigningKey(did, states, kid) {
+    const head = states[states.length - 1];
+    const key = keyFromKid(did, kid);
+    if (key == null) {
+        return head.keys[0];
+    }
+    if (!head.keys.includes(key)) {
+        throw new IssuerKeyNotFoundError(`Controller ${did} kid names a key that is not current: ${kid}`);
+    }
+    return key;
+}
+/**
+ * The key a token's `kid` names, out of **every position in the current generation** — what
+ * `resolveHistoric` answers. It accepts a key the profile has since rotated away, so it establishes
+ * "this profile did once hold this key", never "holds". The right answer for material minted in the
+ * past (an already-issued capability, a revocation record), because a routine `rotate` must not
+ * invalidate what the profile issued to third parties who cannot know it rotated; the wrong answer
+ * for a live signer.
+ *
+ * A `reset` is what invalidates (it discards everything under the prior generation), and `gen` never
+ * decreases, so the backwards scan stops dead at the first earlier-generation state. Runs backwards
+ * because the head's own key set is the common answer. A `kid` naming a never-published key, or one
+ * from a superseded generation, is an error — never a fall back to `keys[0]`.
+ */ function historicSigningKey(did, states, kid) {
+    const head = states[states.length - 1];
+    const key = keyFromKid(did, kid);
+    if (key == null) {
+        return head.keys[0];
+    }
+    for(let i = states.length - 1; i >= 0 && states[i].gen === head.gen; i--){
+        if (states[i].keys.includes(key)) {
+            return key;
+        }
+    }
+    throw new IssuerKeyNotFoundError(`Controller ${did} kid names a key outside the current generation: ${kid}`);
+}
+/**
+ * What a token signed by a revoked key is rejected with. The `#`-prefixed key follows after `: `, so
+ * match with `startsWith`.
+ */ export const KEY_REVOKED = 'kid names a key the controller has revoked';
+/**
+ * The signing key `header` names, out of an already-folded log. `historic` picks which question above
+ * is asked, and defaults to the safe one.
+ *
+ * **A revoked key answers neither question.** A `rev` naming `#<key>` retires a key for material it
+ * has *already* signed, and this is where that bites — every `did:kokuin:` signature check reaches a
+ * resolved key through here, so the denial covers `verifyToken` on both `historic` settings, every
+ * capability and revocation record `@kokuin/capability` verifies, and the fold's own cap-authorised
+ * revoke. The historic arm is the live one: a revoked key is never in the head's `k` (the
+ * `KeyState.deny` invariant), so only the backwards scan can select one, and without this
+ * `resolveHistoric` would accept a leaked key forever.
+ *
+ * The head arm cannot be reached from a log this package folded, but is not decoration: `states`
+ * arrives from the caller, and the invariant is the fold's property, not the array's — a
+ * caller-built state whose head publishes a key it also denies resolves to nothing here.
+ *
+ * **Evaluated against the head's deny set, never the position the key was selected at.** A denial is
+ * about the key, not one event, and the position an artefact carries is author-supplied — else a
+ * thief presents a token resolving at a position before the revoke. Deliberately *not* how a DID
+ * denial behaves inside the fold, where `states[i]` is consulted at position `i` because "was this
+ * author allowed to act *here*" is the whole question; the two rules answer different questions.
+ * Inside the fold they coincide anyway: `createStateResolver` gets the prefix `states[0..i-1]`, so
+ * its head *is* the position being verified.
+ */ export function signingKeyFrom({ did, states, header, historic = false }) {
+    const head = states[states.length - 1];
+    if (head.keys.length === 0) {
+        throw new Error(`Controller ${did} has no signing key`);
+    }
+    const selected = historic ? historicSigningKey(did, states, header.kid) : headSigningKey(did, states, header.kid);
+    // `IssuerKeyNotFoundError` like every rejection here: the DID resolved and the log folded, and what
+    // failed is the key. Retyping it unresolvable would let a `kid` (unauthenticated) make this
+    // controller read as unresolvable to every fail-closed caller. See {@link keyFromKid}.
+    if (head.deny.has(keyTarget(selected))) {
+        throw new IssuerKeyNotFoundError(`Controller ${did} ${KEY_REVOKED}: ${keyTarget(selected)}`);
+    }
+    const key = decodeKey(selected);
+    if (key.alg === 'X25519') {
+        throw new Error(`Controller ${did} signing key is not a signature algorithm: ${key.alg}`);
+    }
+    return {
+        alg: key.alg,
+        publicKey: key.publicKey
+    };
+}
+/**
+ * The head's key agreement set, minus anything it has revoked. A `rev` may name an agreement key as
+ * readily as a signing one (the target spelling is the key, not its purpose), and these are the keys
+ * a *sender* encrypts to — encrypting to a revoked key is the one outcome a denial must prevent.
+ *
+ * Like the signing side, unreachable from a log this package folded (the `KeyState.deny` invariant)
+ * but `states` arrives from the caller. Filtering to empty is the honest answer for a state that
+ * denies everything it publishes: `@kokuin/jwe` then encrypts nothing, the fail-closed direction.
+ */ export function agreementKeysFrom(did, states) {
+    const head = states[states.length - 1];
+    return head.agreement.flatMap((value)=>{
+        if (head.deny.has(keyTarget(value))) {
+            return [];
+        }
+        const key = decodeKey(value);
+        if (key.alg !== 'X25519') {
+            throw new Error(`Controller ${did} publishes an unsupported agreement key: ${key.alg}`);
+        }
+        return {
+            alg: key.alg,
+            publicKey: key.publicKey
+        };
+    });
+}
+/**
+ * A `DIDMethodResolver` answering for exactly one profile, out of already-folded state. The fold
+ * hands one to a capability-authorised revoke's verifier, built from the states *before* the event
+ * being verified — the prefix contract made unforgettable: the verifier no longer needs a
+ * position-aware registry, because the fold supplies the answer. See `FoldOptions.verifyCapability`.
+ *
+ * Answers only for `did`; any other identifier is `Unknown DID`, so a caller merging this into a
+ * wider registry falls back to its own resolver for another `did:kokuin:` delegate and never serves
+ * one profile's state for another's. Not a cache: the states are the caller's, fixed at construction.
+ */ export function createStateResolver(did, states) {
+    function statesFor(asked) {
+        if (asked !== did) {
+            throw new Error(`Unknown DID: ${asked}`);
+        }
+        return states;
+    }
+    return {
+        method: DID_METHOD,
+        async resolve (asked, header = {}) {
+            return signingKeyFrom({
+                did: asked,
+                states: statesFor(asked),
+                header
+            });
+        },
+        // The head of *this prefix*, not the log: these states end at the position the fold is verifying.
+        // A capability issued before that position is the archived material `resolveHistoric` exists for.
+        async resolveHistoric (asked, header = {}) {
+            return signingKeyFrom({
+                did: asked,
+                states: statesFor(asked),
+                header,
+                historic: true
+            });
+        },
+        async resolveDenySet (asked) {
+            const known = statesFor(asked);
+            return known[known.length - 1].deny;
+        },
+        async resolveAgreementKey (asked) {
+            return agreementKeysFrom(asked, statesFor(asked));
+        }
+    };
+}

package/lib/state.d.ts

@@ -0,0 +1,28 @@
+import type { SignedEvent } from './events.js';
+import { type FoldOptions, type KeyState } from './fold.js';
+/**
+ * Current state via the synchronous {@link foldLog}. A capability-authorised revoke fails closed
+ * here — see {@link currentStateAsync}.
+ */
+export declare function currentState(did: string, events: Array<SignedEvent>, context: string): KeyState;
+/**
+ * Every per-position state, via {@link foldLogAsync}. What the resolver needs and the identity does
+ * not: a verifier has to answer about keys the log has since rotated away, since a token outlives the
+ * state that gave its `kid` meaning.
+ */
+export declare function allStatesAsync({ did, events, context, options, }: {
+    did: string;
+    events: Array<SignedEvent>;
+    context: string;
+    options?: FoldOptions;
+}): Promise<Array<KeyState>>;
+/**
+ * Current state via {@link foldLogAsync}, which can await `options.verifyCapability` for a
+ * capability-authorised revoke instead of failing closed on it.
+ */
+export declare function currentStateAsync({ did, events, context, options, }: {
+    did: string;
+    events: Array<SignedEvent>;
+    context: string;
+    options?: FoldOptions;
+}): Promise<KeyState>;

package/lib/state.js

@@ -0,0 +1,34 @@
+import { foldLog, foldLogAsync } from './fold.js';
+/**
+ * Fold results to states, turning a fold failure into a throw. The identity and the resolver both
+ * need the same fold-reject-take-last sequence, sync and async, so it lives here once. `context`
+ * names the caller so its diagnostics survive the factoring.
+ */ function foldedStates(did, context, result) {
+    if (!result.ok) {
+        throw new Error(`${context}: invalid log for ${did}: ${result.reason} at event ${result.index}`);
+    }
+    return result.states;
+}
+function lastState(did, context, result) {
+    const states = foldedStates(did, context, result);
+    return states[states.length - 1];
+}
+/**
+ * Current state via the synchronous {@link foldLog}. A capability-authorised revoke fails closed
+ * here — see {@link currentStateAsync}.
+ */ export function currentState(did, events, context) {
+    return lastState(did, context, foldLog(did, events));
+}
+/**
+ * Every per-position state, via {@link foldLogAsync}. What the resolver needs and the identity does
+ * not: a verifier has to answer about keys the log has since rotated away, since a token outlives the
+ * state that gave its `kid` meaning.
+ */ export async function allStatesAsync({ did, events, context, options }) {
+    return foldedStates(did, context, await foldLogAsync(did, events, options));
+}
+/**
+ * Current state via {@link foldLogAsync}, which can await `options.verifyCapability` for a
+ * capability-authorised revoke instead of failing closed on it.
+ */ export async function currentStateAsync({ did, events, context, options }) {
+    return lastState(did, context, await foldLogAsync(did, events, options));
+}

package/lib/supersede.d.ts

@@ -0,0 +1,97 @@
+import { type SignedEvent } from './events.js';
+import { type FoldOptions, type FoldResult } from './fold.js';
+export type Duplicity = {
+    /** Position of the divergence, from the folded state of the first conflicting event. */
+    gen: number;
+    seq: number;
+    /**
+     * Digests of the two conflicting events *at the divergence point*, sorted — not of the branch
+     * heads, which for branches of unequal length say nothing about where they disagree.
+     */
+    digests: [string, string];
+};
+/**
+ * Why branch selection could not name a winner.
+ *
+ * - `duplicity` — two events the controller cannot both have authored at one position. The only one
+ *   that says anything is wrong with the log.
+ * - `no-valid-branch` — nothing presented folded at all.
+ * - `needs-capability-verification` — **every** branch carries a capability-authorised revoke this
+ *   call was not equipped to check, so there is nothing left to compare. The log is fine; use
+ *   {@link resolveBranchesAsync} with a `verifyCapability`. A call where only *some* branches are
+ *   unverifiable answers with the rest and reports the count as {@link ResolveResult.unverified}.
+ *
+ * Added rather than swapped in: `duplicity` still carries the `gen: -1` sentinel for the two
+ * non-duplicity arms, so a caller written against the previous shape still tells them apart.
+ */
+export type ResolveFailure = 'duplicity' | 'no-valid-branch' | 'needs-capability-verification';
+/**
+ * How many presented branches this call could not check, and therefore did not compare.
+ *
+ * Non-zero means the answer is **provisional**: an unfoldable branch may have superseded the one
+ * reported, so a caller acting on a winner must re-resolve through {@link resolveBranchesAsync} with
+ * a `verifyCapability` or treat the result as unconfirmed. Zero for every correctly configured call.
+ *
+ * Reported rather than fatal because the alternative is an unauthenticated DoS on duplicity
+ * detection. A cap-bearing revoke reaches the verifier path *before* any signature check (the
+ * capability names the signer), so a keyless peer can copy the public inception, append a `rev` with
+ * `sigs: []` and arbitrary `cap` bytes, and present it — and refusing the whole resolution on that
+ * would turn a genuine duplicity report between two honest branches into a refusal, for every
+ * profile. Dropping such a branch cannot hand an attacker a win (a branch that does not fold is not a
+ * contender); the only exposure left is a *stale* answer, which this count marks.
+ */
+export type ResolveResult = {
+    ok: true;
+    winner: Array<SignedEvent>;
+    superseded: number;
+    unverified: number;
+} | {
+    ok: false;
+    failure: ResolveFailure;
+    duplicity: Duplicity;
+    unverified: number;
+};
+/**
+ * Whether a branch failed to fold only because this call could not check a capability. Filtering such
+ * a branch out as invalid is what switched duplicity detection off for the management tier — a
+ * `cap`-bearing revoke is the tier working as designed, not a forgery. Matched by prefix against the
+ * fold's exported reasons, the contract those constants exist for.
+ */
+export declare function needsCapabilityVerification(result: FoldResult): boolean;
+/**
+ * Pick the authoritative branch. Two rules, in order:
+ *
+ * 1. The highest folded generation wins outright. Only a reset raises the generation, and only the
+ *    committed recovery key can author a reset — the root's override, unreachable by a thief.
+ * 2. Within that generation, branches are compared **at the point they diverge**, not at their heads:
+ *    a rotate signed by the pre-committed next keys supersedes the current-key event it forked from
+ *    and everything that branch accumulated. Two diverging events with no rotate to settle them are
+ *    duplicity, surfaced rather than merged.
+ *
+ * Comparing heads instead would make branch *length* decisive below the top generation — the one
+ * resource a thief has in abundance (a stolen current key cannot rotate but can sign unlimited
+ * revokes). A longer branch still wins when it is the same history carried further, which the
+ * divergence walk sees as a prefix.
+ *
+ * `superseded` counts the state-advancing events discarded from losing branches (what a cache must
+ * invalidate — folded state is not append-only under supersession); skipped events are not counted.
+ * Branches that do not fold are filtered out before comparison, so a thief who cannot produce a valid
+ * event cannot create a duplicity report.
+ *
+ * This form folds synchronously and cannot check a capability-authorised revoke: such a branch is
+ * counted in {@link ResolveResult.unverified} and left out, and only a call where *every* branch is
+ * one answers `failure: 'needs-capability-verification'`. See {@link ResolveResult.unverified} for
+ * why the count is reported rather than fatal; the remedy is {@link resolveBranchesAsync} with a
+ * verifier.
+ */
+export declare function resolveBranches(did: string, branches: Array<Array<SignedEvent>>): ResolveResult;
+/**
+ * Async counterpart of {@link resolveBranches}, and the form the management tier needs — the sync
+ * fold fails closed on a capability-authorised revoke, so resolving through it would filter every
+ * branch of such a log away as invalid and report "no valid history" for a healthy profile.
+ *
+ * Branches are folded one at a time: `verifyCapability` is caller-supplied code that may do I/O, and
+ * branch counts in a duplicity report are small, so there is nothing to win against calling a
+ * caller's verifier concurrently.
+ */
+export declare function resolveBranchesAsync(did: string, branches: Array<Array<SignedEvent>>, options?: FoldOptions): Promise<ResolveResult>;