@kokuin/controller 0.1.0 → 0.2.0

package/lib/events.js

@@ -25,7 +25,7 @@ export function signEvent(event, privateKeys) {
  * the folded state, so a bad shape must be rejected where it is published, not one event away where
  * it is next read (a non-array `n` would throw in the *next* rotate; a non-array `k` is a `KeyState`
  * whose type lies).
- */ function isKeyList(value) {
+ */ export function isKeyList(value) {
     return Array.isArray(value) && value.every((entry)=>typeof entry === 'string');
 }
 /**
@@ -62,13 +62,17 @@ export function signEvent(event, privateKeys) {
         return false;
     }
     const bytes = canonicalBytes(event);
-    for(let i = 0; i < sigs.length; i++){
+    for (const [i, sig] of sigs.entries()){
         try {
-            const key = tryDecodeKey(keys[i]);
+            const encodedKey = keys[i];
+            if (encodedKey == null) {
+                return false;
+            }
+            const key = tryDecodeKey(encodedKey);
             if (key == null || key.alg !== 'EdDSA') {
                 return false;
             }
-            if (!ed25519.verify(base64urlnopad.decode(sigs[i]), bytes, key.publicKey)) {
+            if (!ed25519.verify(base64urlnopad.decode(sig), bytes, key.publicKey)) {
                 return false;
             }
         } catch  {
@@ -77,33 +81,6 @@ export function signEvent(event, privateKeys) {
     }
     return true;
 }
-/**
- * Whether one of an event's signatures was made by `key` — the counterpart of
- * {@link verifySignatures} for a signer the *event* does not name (resolved from a DID elsewhere). A
- * capability-authorised revoke needs exactly this: its author is the capability's `aud`, which the
- * fold cannot resolve, so it is handed the key and checks the signature itself.
- *
- * Total, EdDSA only — all {@link signEvent} produces. An ES256 audience therefore cannot author a
- * revoke, which fails closed until events grow a second signature algorithm.
- */ export function verifyEventSignedBy(signed, key) {
-    // Both arms are unkillable through the fold (`isSignedEventShape` already established `sigs` is a
-    // string array; a non-EdDSA key would fail `ed25519.verify`; `[].some()` is `false`) and both stay
-    // by the file's guard rule: a direct caller reaches this with a parsed body.
-    if (key.alg !== 'EdDSA' || signed.sigs.length === 0) {
-        return false;
-    }
-    if (!isCanonicalizable(signed.event)) {
-        return false;
-    }
-    const bytes = canonicalBytes(signed.event);
-    return signed.sigs.some((sig)=>{
-        try {
-            return ed25519.verify(base64urlnopad.decode(sig), bytes, key.publicKey);
-        } catch  {
-            return false;
-        }
-    });
-}
 /**
  * Deterministic inception. Only seed-derived, canonical material — no timestamp, nonce, or label —
  * so the DID is a pure function of the seed and profile index. Never add a label: a mistyped one on
@@ -175,22 +152,33 @@ export function verifyInception(signed, did) {
     }
     return verifySignatures(signed.event, signed.sigs, signed.event.k);
 }
+/**
+ * The shape of one snapshot member, nothing more: whether the DID carries the key, whether the key
+ * is Ed25519, and whether it collides with a root key are rules over the whole snapshot and its chain,
+ * checked by the fold. `lease` must be a non-negative safe integer — unix seconds — because grants
+ * compare `exp` against it, and a fraction, a negative or an unsafe integer has no single reading.
+ */ export function isMemberEntry(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const entry = value;
+    return typeof entry.did === 'string' && typeof entry.key === 'string' && typeof entry.add === 'string' && typeof entry.lease === 'number' && Number.isSafeInteger(entry.lease) && entry.lease >= 0;
+}
 /**
  * A rotate reveals the keys the prior event pre-committed and commits the next set, signed by the
  * newly revealed keys (per KERI — what makes a stolen current key unable to rotate). Reproducible
- * from the seed alone unless it carries a seal or deny snapshot.
+ * from the seed and the snapshot unless it carries a seal.
+ *
+ * The root chain holds only key-establishing events, so a rotate's sequence and its derivation index
+ * are the same number: the key it reveals sits one past `prior`'s position.
  *
  * **Throws rather than emitting an event the fold will reject.** The revealed key must be the one
- * `prior` committed in `n`, and `options.keyPosition` decides which key gets derived — so a wrong
- * position used to produce a well-formed, signed event no fold would accept. The two are checked
- * against each other here. When `prior` carries no commitment (a `rev`), `keyPosition` is required:
- * the default would derive a key one past the *revoke*, which nothing committed, and this is the one
- * case unverifiable from `prior` alone.
- */ export function createRotate({ seed, profile, did, prior, options = {} }) {
+ * `prior` committed in `n`, which a prior not built from this chain's own events need not be.
+ */ export function createRotate({ seed, profile, did, prior, snapshot, seal }) {
     const gen = prior.g;
     const seq = prior.s + 1;
-    // The commitment the revealed key must match, when `prior` carries one. An `icp`/`rot` does; a
-    // `rev` and any hand-built prior of another shape does not.
+    // The commitment the revealed key must match. Every `icp`/`rot` carries one; a hand-built prior of
+    // another shape does not.
     const commitment = prior.n;
     const committed = isKeyList(commitment) && commitment.length > 0 ? commitment : undefined;
     // The checks below only have an answer when this seed *is* the log's root — otherwise the
@@ -198,23 +186,20 @@ export function verifyInception(signed, did) {
     // there would stop this generator building a foreign rotate at all (which the conformance suite
     // legitimately does); the fold is the layer that rejects it.
     const root = didFromInception(inceptionEvent(seed, profile)) === did;
-    if (root && committed == null && options.keyPosition == null) {
-        throw new Error('createRotate: prior event pre-commits no key, so keyPosition is required — pass the fold`s ' + 'KeyState.keyGen / keySeq for the position the last icp/rot established');
+    if (root && committed == null) {
+        throw new Error('createRotate: prior event pre-commits no key, so there is nothing to reveal');
     }
-    // The key this rotate reveals is the one the last icp/rot committed, one past *its* position; the
-    // agreement key lands at the same index so `KeyState.keyGen`/`keySeq` names it for a recipient
-    // re-deriving from the seed. See `CreateRotateOptions.keyPosition` for why these diverge from `s`.
-    const keyGen = options.keyPosition?.gen ?? gen;
-    const keySeq = (options.keyPosition?.seq ?? prior.s) + 1;
-    const current = deriveKeyPair(seed, authorityPath(profile, keyGen, keySeq), 'EdDSA');
-    const next = deriveKeyPair(seed, authorityPath(profile, keyGen, keySeq + 1), 'EdDSA');
-    const agreement = deriveKeyPair(seed, agreementPath(profile, keyGen, keySeq), 'X25519');
+    // The agreement key lands at the same index as the authority key, so `KeyState.keyGen`/`keySeq`
+    // names both for a recipient re-deriving from the seed.
+    const current = deriveKeyPair(seed, authorityPath(profile, gen, seq), 'EdDSA');
+    const next = deriveKeyPair(seed, authorityPath(profile, gen, seq + 1), 'EdDSA');
+    const agreement = deriveKeyPair(seed, agreementPath(profile, gen, seq), 'X25519');
     if (root && committed != null) {
         // Exactly what `verifyRotate` checks, checked here where the caller can still act. Arity first:
         // this generator emits a single key, so a prior committing any other number has no rotate here.
         const revealed = encodeKey(current.publicKey, 'EdDSA');
         if (committed.length !== 1 || digestOf(revealed) !== committed[0]) {
-            throw new Error(`createRotate: the key at (gen ${keyGen}, seq ${keySeq}) is not the one the prior event ` + 'pre-committed — pass options.keyPosition naming where the last icp/rot established a ' + 'key (the fold`s KeyState.keyGen / keySeq). A revoke advances `s` without establishing ' + 'one, so `s` and the derivation index part company at the first revoke of a generation ' + 'and stay apart.');
+            throw new Error(`createRotate: the key at (gen ${gen}, seq ${seq}) is not the one the prior event ` + 'pre-committed — the prior is not an event of this log');
         }
     }
     const event = {
@@ -236,8 +221,9 @@ export function verifyInception(signed, did) {
         ],
         kt: 1,
         nt: 1,
-        a: options.seal,
-        d: options.denySnapshot
+        a: seal,
+        m: snapshot.members,
+        d: snapshot.deny
     };
     return {
         event,
@@ -248,9 +234,14 @@ export function verifyInception(signed, did) {
 }
 /**
  * Whether the members a rotate publishes into the folded state have the shape the fold will carry.
- * Shared by {@link verifyRotate} and {@link verifyReset}: both hand `k`/`n`/`d` to the next
- * `KeyState`, and a reset verifies against the recovery key not `k`, so without this it could publish
- * a key set of any shape.
+ * Shared by {@link verifyRotate} and {@link verifyReset}: both hand `k`/`n` to the next `KeyState`,
+ * and a reset verifies against the recovery key not `k`, so without this it could publish a key set
+ * of any shape.
+ *
+ * The snapshot (`m`/`d`) is not judged here: whether it is well formed, disjoint from the root keys
+ * and keeps the generation's retired keys depends on the chain it lands on, so the fold judges it
+ * with a reason of its own (see `validateSnapshot`). These verifiers answer only whether the event
+ * is signed by, and chains to, what it claims.
  *
  * `r` is refused outright — the runtime half of removing it from {@link RotateEvent}. A member the
  * fold silently ignored would be the field-that-lies this removal is about: a reader seeing `r` on a
@@ -258,9 +249,7 @@ export function verifyInception(signed, did) {
  */ function isPublishedRotate(event) {
     return isKeyList(event.k) && isKeyList(event.n) && isEnforcedThreshold(event.kt, event.k) && isEnforcedThreshold(event.nt, event.n) && // A seal is opaque but still a digest string on the wire (see `RotateEvent.a`); a non-string one
     // is a member a reader would have to guess at.
-    (event.a == null || typeof event.a === 'string') && event.r === undefined && // The snapshot replaces the accumulated set, so the fold builds a `Set` from it: a scalar `d`
-    // throws, a string `d` would silently become a set of characters.
-    (event.d == null || isKeyList(event.d));
+    (event.a == null || typeof event.a === 'string') && event.r === undefined;
 }
 /**
  * A rotate is valid when it chains to the prior digest, its revealed keys match the prior event's
@@ -292,14 +281,24 @@ export function verifyInception(signed, did) {
  *
  * Anchored to the inception, not the log head: the recovery key lives on the root-retained
  * derivation branch and its digest is committed in the deterministic inception, so a restored
- * mnemonic can author one with no log knowledge or availability. Carries no options — no seal, `d`
- * always `[]` — so a reset is a pure function of `(seed, profile, gen)`, and two blind resets at one
- * generation produce identical bytes that resolve as idempotent re-derivation, not duplicity.
+ * mnemonic can author one with no log knowledge or availability.
+ *
+ * **Blind** (no `snapshot`): no seal, `d: []` and no `m`, so a blind reset is a pure function of
+ * `(seed, profile, gen)` and two blind resets at one generation produce identical bytes that resolve
+ * as idempotent re-derivation, not duplicity. The new epoch starts empty and root re-adds members.
+ * This is the path for a root that does not know the log's state.
+ *
+ * **With a snapshot**: the same reset carries the member and deny sets, so one recovery-key
+ * signature is the whole recovery. Two resets at one generation with different bytes are then
+ * duplicity — which only the recovery-key holder can cause, and a reset at a higher generation
+ * resolves. Members keep their `add` references, but every grant names its generation, so every
+ * grant minted under the prior one still dies. The snapshot is checked against the **new**
+ * generation's keys, and no retired-key denial of the old one need carry over.
  *
  * The root need not know the current generation, only eventually exceed it (no attacker can author a
  * competing reset at any generation): a blind root starts at `gen = 1` and retries higher if it
  * learns of one — the cost is a round trip, never loss of control.
- */ export function createReset(seed, profile, gen) {
+ */ export function createReset(seed, profile, gen, snapshot) {
     if (gen < 1) {
         throw new Error(`Reset: gen must be >= 1, got ${gen}`);
     }
@@ -327,10 +326,18 @@ export function verifyInception(signed, did) {
             digestOf(encodeKey(next.publicKey, 'EdDSA'))
         ],
         kt: 1,
-        nt: 1,
-        // A reset clears the deny set: every capability under the prior generation is gone anyway.
-        d: []
+        nt: 1
     };
+    if (snapshot == null || snapshot.members.length === 0 && snapshot.deny.length === 0) {
+        // A blind reset clears the deny set: every capability under the prior generation is gone anyway.
+        // Written as `d: []` rather than omitted so a blind reset keeps the bytes it always had. An empty
+        // snapshot is the same state and is written the same way, so a retry with one is byte-identical
+        // to a blind reset rather than a second encoding of it.
+        event.d = [];
+    } else {
+        event.m = snapshot.members;
+        event.d = snapshot.deny;
+    }
     return {
         event,
         sigs: signEvent(event, [
@@ -355,11 +362,23 @@ export function verifyInception(signed, did) {
     if (!isPublishedRotate(event)) {
         return false;
     }
-    // A reset carries an empty deny set and no seal (see {@link createReset}) — the idempotency the
-    // branch selector relies on. Only the recovery-key holder can sign one, so this is not an
-    // attacker's event; it is the rule that makes "blind reset" mean the same bytes for every holder of
-    // the seed. Enforced here too so a reset carrying a non-empty `d` or a seal cannot fold as valid.
-    if (event.a !== undefined || event.d == null || event.d.length !== 0) {
+    // A reset carries no seal, and either a whole snapshot (`m` and `d` together) or none. Without `m`
+    // it is blind, and a blind reset's `d` is exactly the `[]` {@link createReset} writes: one encoding,
+    // so "blind reset" means the same bytes for every holder of the seed — the idempotency the branch
+    // selector relies on. For the same reason an empty snapshot (`m: []` with `d: []`) is refused: it is
+    // the blind state spelled a second way. Only the recovery-key holder can sign one, so this is not an
+    // attacker's event; it is the rule that keeps one state from having two resets at a generation,
+    // and half a snapshot (`d` with no `m`, or `m` with no `d`) from folding as a reset that silently
+    // dismissed every member or cleared every denial. The snapshot's contents are the fold's to judge,
+    // against the new generation's keys.
+    if (event.a !== undefined) {
+        return false;
+    }
+    const emptyDeny = isKeyList(event.d) && event.d.length === 0;
+    if (event.m == null ? !emptyDeny : event.d == null) {
+        return false;
+    }
+    if (Array.isArray(event.m) && event.m.length === 0 && emptyDeny) {
         return false;
     }
     if (!Array.isArray(sigs) || sigs.length !== 1) {
@@ -379,87 +398,19 @@ export function verifyInception(signed, did) {
     ]);
 }
 /**
- * How a `rev` target names a **key** rather than a DID: `#<the multibase key exactly as it appears in
+ * How a deny entry names a **key** rather than a DID: `#<the multibase key exactly as it appears in
  * `k`>`, the same spelling a token's `kid` uses. One spelling for one thing — unambiguous against
  * `did:…` on sight, so a bare multibase string is not a second accepted encoding, any more than for
  * `kid`.
  */ export const KEY_TARGET_PREFIX = '#';
-/** The deny-set spelling of `key` — what {@link createRevoke} takes as its target to deny it. */ export function keyTarget(key) {
+/** The deny-set spelling of `key` — what a snapshot's `d` carries to deny it. */ export function keyTarget(key) {
     return `${KEY_TARGET_PREFIX}${key}`;
 }
 /**
- * The key a `rev` target names, or `null` when it names a DID instead. Total on any string: a target
- * of neither form lands in the deny set as the opaque identifier it is. The body is not validated
+ * The key a deny entry names, or `null` when it names a DID instead. Total on any string: an entry of
+ * neither form lands in the deny set as the opaque identifier it is. The body is not validated
  * against multibase — a `#` naming nothing denies nothing, exactly as a `did:` naming nobody does,
  * and rejecting it would only add a way for a well-formed log to stop folding.
  */ export function keyFromTarget(target) {
     return target.startsWith(KEY_TARGET_PREFIX) ? target.slice(KEY_TARGET_PREFIX.length) : null;
 }
-/**
- * Revoke a DID or a key — see {@link RevokeEvent.x} for the two spellings.
- *
- * Naming the device DID rather than a `jti` makes this one entry per device for its life — covering
- * capabilities the verifier has never seen and future re-mints, where per-`jti` revocation would grow
- * with every renewal. A key target retires a leaked key for material it *already* signed: `rotate`
- * only retires it for new issuance (`resolve` is head-only), but already-issued material verifies
- * through `resolveHistoric`, which survives a rotate by design, so a thief holding a rotated-away key
- * could still mint one that verified. Retirement is therefore explicit, keeping the promise that a
- * routine rotate does not invalidate already-issued material intact.
- *
- * **A key the profile currently publishes cannot be denied** — the fold rejects it (see the `rev`
- * branch of `stepEvent`). Rotate first, then deny the key the rotate retired.
- *
- * `prior` answers "next sequence, what to chain to"; `keyPosition` separately answers "where the
- * active authority key lives". They coincide only for an `icp`/`rot` prior — a `rev` establishes no
- * key, so a revoke on a revoke still points at the last `icp`/`rot` position.
- */ export function createRevoke({ seed, profile, did, prior, target, keyPosition, cap }) {
-    const current = deriveKeyPair(seed, authorityPath(profile, keyPosition.gen, keyPosition.seq), 'EdDSA');
-    return createRevokeWithKey({
-        privateKey: current.privateKey,
-        did,
-        prior,
-        target,
-        cap
-    });
-}
-/**
- * Revoke a DID, signing with an Ed25519 key the caller already holds rather than deriving one from
- * the profile seed.
- *
- * The builder for the actor a capability-authorised revoke exists for: a device holding a management
- * capability, which by design never receives the profile sub-seed. `createRevoke` can only sign as
- * the profile itself, so without this the feature had no API but re-implementing the signing
- * convention per consumer — the duplication `createControllerCapabilityVerifier` prevents on the
- * verifying side.
- *
- * The key is the audience key the capability pins in `cnf`, and the fold checks the event's signature
- * against exactly that, so the two must match. Ed25519 only. Takes the private key rather than an
- * identity because no identity type here signs raw bytes — a `KeyStore` entry hands back exactly this
- * shape. Byte-identical to {@link createRevoke} given the same key; no `keyPosition`, which exists
- * only to derive a key from a seed.
- */ export function createRevokeWithKey({ privateKey, did, prior, target, cap }) {
-    const event = {
-        v: 1,
-        t: 'rev',
-        i: did,
-        g: prior.g,
-        s: prior.s + 1,
-        p: digestOf(prior),
-        crit: true,
-        x: target,
-        cap
-    };
-    return {
-        event,
-        sigs: signEvent(event, [
-            privateKey
-        ])
-    };
-}
-/** Authority-signed revoke. Capability-authorised revokes are checked in the fold. */ export function verifyRevoke(signed, prior) {
-    const { event, sigs } = signed;
-    if (event.t !== 'rev' || event.p !== prior.digest) {
-        return false;
-    }
-    return verifySignatures(event, sigs, prior.keys);
-}

package/lib/fold.d.ts

@@ -1,5 +1,16 @@
-import type { DIDMethodResolver, ResolvedSigningKey } from '@kokuin/token';
-import { type SignedEvent } from './events.js';
+import { type MemberEntry, type StateSnapshot } from './events.js';
+import { type ControllerLog } from './log.js';
+export { ROTATE_NEEDS_SNAPSHOT, SNAPSHOT_DROPS_RETIRED_KEY, SNAPSHOT_MALFORMED, SNAPSHOT_MEMBER_DID_MISMATCH, SNAPSHOT_MEMBER_KEY_IS_ROOT, } from './members.js';
+/**
+ * One management member as a state holds it: the snapshot entry, plus whether a removal has ended
+ * it (`removed`) and whether it may act at all (`effective`: present, not removed, and not targeted
+ * by any entry of the same state's deny set — see `denialTargetsMember`). A chain state's members are
+ * its snapshot's, so none is removed; removal is an epoch effect.
+ */
+export type MemberState = MemberEntry & {
+    removed: boolean;
+    effective: boolean;
+};
 export type KeyState = {
     did: string;
     gen: number;
@@ -8,14 +19,13 @@ export type KeyState = {
     keyGen: number;
     /**
      * Derivation index of the current `keys`: key-establishing events this generation, counting the
-     * `icp`/`rot` that opened it as 0. Equal to `seq` until a revoke intervenes, and deliberately not
-     * the same thing — a revoke advances `seq` while establishing no key, so the pre-rotation chain
-     * (which commits the *next* key's digest, one index on) stops tracking `seq` there. Deriving at
-     * `seq` after a revoke produces a key the log never committed.
+     * `icp`/`rot` that opened it as 0. The root chain holds only key-establishing events, so this is
+     * `seq`; it is named apart because it answers a different question — where to derive the key, not
+     * where the event sits — and an inception's `s` is wire data this package does not derive from.
      */
     keySeq: number;
     keys: Array<string>;
-    /** Key agreement keys — an OR set. Established by icp/rot, carried forward across rev. */
+    /** Key agreement keys — an OR set, established by the same icp/rot as `keys`. */
     agreement: Array<string>;
     next: Array<string>;
     /**
@@ -26,101 +36,59 @@ export type KeyState = {
      */
     recovery: string;
     /**
-     * What this position denies, in the two spellings a `rev` target may take — see `RevokeEvent.x`. A
-     * `did:…` entry denies a *holder* (`@kokuin/capability` refuses a capability whose `aud` it names);
-     * a `#<multibase key>` entry denies a *signer* (`signingKeyFrom` refuses that key, `agreementKeysFrom`
-     * drops it).
+     * What this position denies, in two spellings. A `did:…` entry denies a *holder*
+     * (`@kokuin/capability` refuses a capability whose `aud` it names); a `#<multibase key>` entry
+     * ({@link keyTarget}) denies a *signer* (`signingKeyFrom` refuses that key, `agreementKeysFrom` drops
+     * it). A chain state's set is exactly its event's snapshot `d` (empty after an inception or a blind
+     * reset).
      *
      * One heterogeneous set rather than two fields: the spellings cannot collide, and every mechanism
-     * the set already has (position-dependence, the `d` snapshot, a reset's clear, `resolveDenySet`,
-     * the `@kokuin/capability` wrapper that forwards it) then covers keys with nothing new to wire or
+     * the set already has (position-dependence, the snapshot, a reset's clear, `resolveDenySet`, the
+     * `@kokuin/capability` wrapper that forwards it) then covers keys with nothing new to wire or
      * forget. A second optional resolver member is a second thing a wrapper can drop, and dropping it
      * fails open.
      *
-     * **Invariant, enforced by both branches of `stepEvent`: no key in this state's `keys` or
+     * **Invariant, enforced by the rotate branch of `stepEvent`: no key in this state's `keys` or
      * `agreement` is denied here.** So every reader may take a folded head's key set at face value.
      */
     deny: ReadonlySet<string>;
+    /**
+     * The management set, keyed by each member's `add` digest (its incarnation). A chain state's is its
+     * event's snapshot `m`, in snapshot order.
+     */
+    members: ReadonlyMap<string, MemberState>;
+    /**
+     * Digest of the chain event that opened the epoch this state belongs to. Every chain event opens
+     * one, so for a chain state this is its own `digest`; epoch events name it as their `e`.
+     */
+    epoch: string;
+    /**
+     * Whether the epoch holds more authenticated events than a verifier will evaluate, failing it
+     * closed until root settles. A chain state has seen no epoch events, so it is never saturated.
+     */
+    saturated: boolean;
     /** Digest of the event that produced this state — the `p` any successor must carry. */
     digest: string;
 };
+/**
+ * `states` is one state per chain event, which is what historic resolution scans. `head` is the last
+ * chain state merged with the current epoch: its `deny`, `members` and `saturated` are the live
+ * answers. `applied`, `pending` and `rejected` account for the epoch events presented -- the digests
+ * that took effect, the well-formed ones still waiting on a parent, and the ones refused (see
+ * `FoldEpochResult` for how refusals are counted).
+ */
 export type FoldResult = {
     ok: true;
     states: Array<KeyState>;
+    head: KeyState;
+    applied: Array<string>;
+    pending: number;
+    rejected: number;
 } | {
     ok: false;
     reason: string;
     index: number;
 };
-/**
- * What a capability verifier answers a cap-bearing revoke with.
- *
- * `audienceKey` is the key the capability pins as its audience at mint time, never resolved at
- * verification time; the fold checks the event's own signature against it, binding the grant to the
- * party it was issued to.
- *
- * A key rather than a boolean because the fold, not the verifier, must tie the answer to the event
- * in hand. The log is public, so the serialized capability inside a revoke is readable by everyone
- * who can resolve the profile; with a boolean, any such reader could lift it out and chain a revoke
- * of their own with any bytes in `sigs`, covering whatever the capability's `res` covers — a
- * wildcard, for a management capability, so every device. Among divisions keeping a *single*
- * callback, this is the only one where neither side can leave the binding out.
- */
-export type CapabilityAuthorisation = {
-    authorised: true;
-    audienceKey: ResolvedSigningKey;
-}
-/** `reason` becomes the fold's failure reason verbatim, so it must describe this rejection. */
- | {
-    authorised: false;
-    reason: string;
-};
-export type FoldOptions = {
-    /**
-     * Verify a capability authorising a non-authority signer to revoke. Injected rather than imported
-     * so the sync path stays free of a capability dependency.
-     *
-     * Receives the serialized capability, the controller DID (which must be the capability `sub`), the
-     * DID being denied, and a resolver for the controller **at the position being verified**. That
-     * fourth argument makes the position contract keepable: the capability is issued by the very
-     * profile whose log carries the revoke, and the state to resolve it against is the prefix before
-     * this event — not the head (which would let a device revoked at event 1 keep authoring at event 2,
-     * the deny set being position-dependent only inside the fold) and not the whole log (which would
-     * recurse into the asking fold). Nothing outside the fold knows which position is being verified,
-     * so the fold answers rather than asks: this resolver holds exactly `states[0..i-1]`, is complete
-     * for the profile, and answers `Unknown DID` for anything else so a verifier can merge it into a
-     * wider registry for a chain's delegates. See {@link CapabilityAuthorisation}.
-     */
-    verifyCapability?: (params: VerifyCapabilityParams) => Promise<CapabilityAuthorisation>;
-};
-/** What the fold hands {@link FoldOptions.verifyCapability} — see that member for each field. */
-export type VerifyCapabilityParams = {
-    cap: string;
-    subject: string;
-    target: string;
-    subjectAtPosition: DIDMethodResolver;
-};
-/** A verifier threw. The thrown message is appended after `: `, so match with `startsWith`. */
-export declare const CAPABILITY_VERIFIER_FAILED = "capability verifier failed";
-/** A verifier answered with something that is not a {@link CapabilityAuthorisation}. */
-export declare const CAPABILITY_VERIFIER_MALFORMED_ANSWER = "capability verifier returned a malformed answer";
-/**
- * The capability authorised the revoke and pinned an audience key, and somebody else signed the
- * event. Distinct from a rejected grant: the delegation is sound and the signature is not.
- */
-export declare const REVOKE_NOT_SIGNED_BY_AUDIENCE = "revoke is not signed by the capability audience";
-/**
- * The sync fold met a capability-authorised revoke, which it cannot verify by construction — the
- * management tier working as designed, answered by `foldLogAsync`. The capability follows after `: `,
- * so match with `startsWith`. Exported so speculative folders (`resolveBranches`) can tell it from a
- * genuinely broken log.
- */
-export declare const CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD = "capability-authorised revoke needs an async fold";
-/**
- * The async fold met a capability-authorised revoke with no `verifyCapability` configured. Same
- * shape: the log is fine and the call was not equipped for it.
- */
-export declare const CAPABILITY_REVOKE_NEEDS_VERIFIER = "capability-authorised revoke needs a verifier";
 /**
  * How many events a log may carry that this version cannot understand, beyond the number it can.
  *
@@ -135,28 +103,38 @@ export declare const CAPABILITY_REVOKE_NEEDS_VERIFIER = "capability-authorised r
 export declare const MAX_SKIPPED_SLACK = 8;
 /** What a log padded past {@link MAX_SKIPPED_SLACK} fails with. */
 export declare const TOO_MANY_UNKNOWN_EVENTS = "too many unknown events";
+/** A fold-loop index landed off the event or state array — a broken invariant, not a bad log. */
+export declare const INTERNAL_FOLD_INVARIANT = "internal fold invariant: missing event or prior state";
 /**
- * Fold a controller's log into per-position key state. `states[i]` is the state *after* `events[i]`,
+ * Fold a controller's log into per-position key state. `states[i]` is the state *after* `chain[i]`,
  * which a verifier evaluating at position `i` must use — that is what makes the deny set
  * position-dependent: clearing a DID later never retroactively validates its earlier actions.
  *
- * Synchronous, so it stays usable on an offline verifier's apply path. A capability-authorised revoke
- * needs async verification, so it fails closed here rather than trusting an unchecked capability — use
- * `foldLogAsync` when one may be present.
- */
-export declare function foldLog(did: string, events: Array<SignedEvent>): FoldResult;
-/**
- * Async counterpart of {@link foldLog}. Shares {@link stepEvent}, so the only difference is a
- * capability-authorised revoke: this entry point awaits `options.verifyCapability` instead of failing
- * closed.
+ * The epoch events then merge into the chain's last state to give `head` (see `foldEpoch`). Only request
+ * limits can fail that half: more than {@link MAX_LOG_EVENTS} entries is `LOG_TOO_LARGE`, at
+ * index -1 because it is no event's fault, and so is more than `MAX_FAILED_SIGNATURES` signatures
+ * failing to verify (`TOO_MANY_FAILED_SIGNATURES`). Short of those, nothing in `log.events` can fail
+ * the fold -- a bad entry is counted and dropped -- so a relay cannot make a log unfoldable by padding
+ * it, only refused by forging past the limit, which no honest relay does.
+ *
+ * Synchronous, so it stays usable on an offline verifier's apply path.
  */
-export declare function foldLogAsync(did: string, events: Array<SignedEvent>, options?: FoldOptions): Promise<FoldResult>;
+export declare function foldLog(did: string, log: ControllerLog): FoldResult;
 export declare function keyStateAt(result: FoldResult, position: number): KeyState | undefined;
 /**
- * The deny set of `state` with `drop` removed — what to pass as a rotate's `denySnapshot` to prune a
- * few entries rather than replace the set. A rotate's `d` replaces the accumulated set outright, so
- * pruning by hand means writing out everything that stays; miss one and the profile silently
- * un-revokes a device or un-retires a leaked key. This builds it from the fold's own answer instead.
- * Entries in `drop` the state does not carry are ignored.
+ * The state snapshot `state` holds, minus `drop` — what to pass as a rotate's `snapshot` to carry the
+ * state forward, pruning a few entries rather than replacing it. A rotate's snapshot replaces the
+ * state outright, so writing one by hand means writing out everything that stays; miss one and the
+ * profile silently un-revokes a device, un-retires a leaked key or dismisses a management member.
+ * This builds it from the fold's own answer instead: every member not removed (`drop.members` names
+ * members by `add` digest) and every deny entry (`drop.deny`). Entries in `drop` the state does not
+ * carry are ignored.
+ *
+ * Root's tooling owes its user the warnings the fold cannot give: dropping a holder DID denial
+ * re-authorises it, safe only once every authority that could have minted it a grant has ended; and
+ * a retired root key the chain shows but this deny set lacks is one to add, not to leave out.
  */
-export declare function pruneDenySet(state: KeyState, drop: Iterable<string>): Array<string>;
+export declare function snapshotOf(state: KeyState, drop?: {
+    deny?: Iterable<string>;
+    members?: Iterable<string>;
+}): StateSnapshot;