@kokuin/controller 0.1.0 → 0.2.0

package/lib/identity.js

@@ -3,16 +3,20 @@ import { ed25519 } from '@noble/curves/ed25519.js';
 import { agreementPath, authorityPath, deriveKeyPair } from './derivation.js';
 import { didFromInception } from './events.js';
 import { encodeKey } from './keys.js';
-import { currentState, currentStateAsync } from './state.js';
+import { isControllerLog, MALFORMED_LOG } from './log.js';
+import { currentState } from './state.js';
 const CONTEXT = 'Controller identity';
 /**
  * The DID the log claims to be, read from its inception before any fold runs — the fold needs the DID
  * to check the inception against, so it cannot be the thing that produces it.
  */ function didFromLog(log) {
-    if (log.length === 0) {
+    if (!isControllerLog(log)) {
+        throw new Error(`${CONTEXT}: ${MALFORMED_LOG}`);
+    }
+    if (log.chain.length === 0) {
         throw new Error(`${CONTEXT}: empty log`);
     }
-    const first = log[0];
+    const first = log.chain[0];
     if (first.event.t !== 'icp') {
         throw new Error(`${CONTEXT}: first event must be an inception`);
     }
@@ -48,15 +52,16 @@ const CONTEXT = 'Controller identity';
 }
 /**
  * Bind a private key the caller holds to the DID, having checked the folded state publishes its
- * public half. Shared by all four entry points, so the membership rule and `kid` binding are written
- * once. Membership, not `keys[0]`: a set may publish several keys and the one in hand need not be
+ * public half. Shared by both entry points (the seed one through {@link identityForState}), so the
+ * membership rule and `kid` binding are written once. Membership, not `keys[0]`: a set may publish several keys and the one in hand need not be
  * first (co-signers' keys belong to other holders); what must hold is that the resolver can answer
  * with this key. A key outside the set signs unverifiable tokens, so fail loudly at construction.
  */ function identityForKey({ privateKey, publicKey, did, state, mismatch }) {
     if (state.keys.length === 0) {
-        // Defensive, unreachable through either fold today (`verifySignatures` rejects an empty key set,
-        // `rev` carries `keys` forward). Kept so a future event type that can empty the set fails here
-        // rather than deriving a key for a controller that publishes none. `resolver.ts` holds it too.
+        // Defensive, unreachable through the fold today (`verifySignatures` rejects an empty key set, and
+        // the chain holds only key-establishing events). Kept so a future event type that can empty the
+        // set fails here rather than deriving a key for a controller that publishes none. `resolver.ts`
+        // holds it too.
         throw new Error(`Controller ${did} has no signing key`);
     }
     const key = encodeKey(publicKey, 'EdDSA');
@@ -68,8 +73,8 @@ const CONTEXT = 'Controller identity';
     return withKid(createSigningIdentityForDID(did, privateKey), `#${key}`);
 }
 /**
- * Derive the signing key the folded state establishes and bind it to the DID. Shared by the sync and
- * async seed entry points, which differ only in how they reach the state.
+ * Derive the signing key the folded state establishes and bind it to the DID: the seed entry point's
+ * half, kept apart from folding the log so it reads as the derivation alone.
  */ function identityForState({ seed, profile, did, state }) {
     const authority = deriveKeyPair(seed, authorityPath(profile, state.keyGen, state.keySeq), 'EdDSA');
     const signing = identityForKey({
@@ -80,8 +85,8 @@ const CONTEXT = 'Controller identity';
         mismatch: 'derived key is not one of the current authority keys'
     });
     // The agreement key sits at the same (keyGen, keySeq) as the authority key — both icp and rot
-    // derive them at matching indices, and a rev carries the agreement set forward — so one position
-    // locates both. Verified against the folded set, failing closed like the authority membership check.
+    // derive them at matching indices — so one position locates both. Verified against the folded
+    // set, failing closed like the authority membership check.
     const agreement = deriveKeyPair(seed, agreementPath(profile, state.keyGen, state.keySeq), 'X25519');
     const encoded = encodeKey(agreement.publicKey, 'X25519');
     if (!state.agreement.includes(encoded)) {
@@ -95,20 +100,19 @@ const CONTEXT = 'Controller identity';
 /**
  * A signing identity for a `did:kokuin:` profile, whose `iss` is the profile DID.
  *
- * Takes the log and folds it here, so the signing key is always the one that log's current state
- * establishes, never one the caller named. The log is the caller's freshness contract: an identity
+ * Takes the log and folds its chain here, so the signing key is always the one that log's current
+ * state establishes, never one the caller named. Its epoch events are not folded: they never change a
+ * root key (see `currentState`). The log is the caller's freshness contract: an identity
  * built from a stale or truncated log signs with a retired key, minting tokens a current verifier
  * rejects. Rebuild from a re-read log after a rotation rather than holding one across it.
  *
- * The key is derived at `keyGen`/`keySeq`, not `gen`/`seq`: a revoke advances the sequence without
- * establishing a key (Amendment A), so deriving at `gen`/`seq` would produce a key never in `k` — an
- * unverifiable token, silently. Every token carries `kid: #<the key that signed it>`, so there is no
- * `kid` parameter — one naming any other key is a request it could not honour, and is rejected on
- * mismatch rather than dropped.
+ * The key is derived at `keyGen`/`keySeq`, the derivation index the fold names for the current keys
+ * — on a chain of key-establishing events the same number as `seq`, but the question asked is where
+ * the key lives, not where the event sits. Every token carries `kid: #<the key that signed it>`, so
+ * there is no `kid` parameter — one naming any other key is a request it could not honour, and is
+ * rejected on mismatch rather than dropped.
  *
- * Synchronous, and stays so (kubun's apply path depends on it): a log whose revoke carries a
- * capability cannot fold without awaiting a verifier, so it throws here — use
- * {@link createControllerIdentityAsync}.
+ * Synchronous, and stays so: kubun's apply path depends on it.
  *
  * @throws when the log does not fold, or when the derived key is not one of the profile's current
  * authority keys (a wrong `seed` or `profile` for this log).
@@ -121,27 +125,6 @@ const CONTEXT = 'Controller identity';
         state: currentState(did, log, CONTEXT)
     });
 }
-/**
- * Async sibling of {@link createControllerIdentity} for a log whose revoke carries a capability
- * authorising a non-authority signer, which only `foldLogAsync` can check. Identical otherwise, so a
- * log without such a revoke resolves to the same identity through either entry point.
- *
- * @param options forwarded to the async fold; without `verifyCapability` such a log still fails to
- * fold rather than being trusted.
- */ export async function createControllerIdentityAsync({ seed, profile, log, options }) {
-    const did = didFromLog(log);
-    return identityForState({
-        seed,
-        profile,
-        did,
-        state: await currentStateAsync({
-            did,
-            events: log,
-            context: CONTEXT,
-            options: options
-        })
-    });
-}
 /**
  * A signing identity for a `did:kokuin:` profile, from the current authority private key rather than
  * the profile seed.
@@ -149,7 +132,7 @@ const CONTEXT = 'Controller identity';
  * The seed form above needs the root seed to derive the key, but the custody tiers say the daily path
  * must not touch it: the root seed lives on a Ledger or cold mnemonic, and a device never receives the
  * profile sub-seed (a sub-seed holder can derive the *next* key and therefore rotate, voiding
- * pre-rotation). This is the same split {@link createRevokeWithKey} makes, for the same reason.
+ * pre-rotation).
  *
  * What the key in hand can do is exactly the intended granularity: it signs as the profile and cannot
  * rotate, since a rotate must reveal the key the log committed in `n` and only the seed derives that.
@@ -169,22 +152,3 @@ const CONTEXT = 'Controller identity';
         mismatch: 'the supplied key is not one of the current authority keys'
     });
 }
-/**
- * Async sibling of {@link createControllerIdentityWithKey}, for a log whose revoke carries a
- * capability authorising a non-authority signer. The pairing is not incidental: a profile that uses
- * the management tier is the same profile whose daily signer should not hold the seed.
- */ export async function createControllerIdentityWithKeyAsync({ privateKey, log, options }) {
-    const did = didFromLog(log);
-    return identityForKey({
-        privateKey,
-        publicKey: ed25519.getPublicKey(privateKey),
-        did,
-        state: await currentStateAsync({
-            did,
-            events: log,
-            context: CONTEXT,
-            options: options
-        }),
-        mismatch: 'the supplied key is not one of the current authority keys'
-    });
-}

package/lib/index.d.ts

@@ -11,13 +11,18 @@
  */
 export { canonicalBytes, digestOf, isCanonicalizable, MAX_CANONICAL_DEPTH, verifyDigest, withinCanonicalDepth, } from './canonical.js';
 export { agreementPath, authorityPath, deriveKeyMaterial, deriveKeyPair, recoveryPath, } from './derivation.js';
-export { type CreateRevokeOptions, type CreateRotateOptions, createInception, createReset, createRevoke, createRevokeWithKey, createRotate, DID_PREFIX, didFor, didFromInception, type EventCommon, type EventType, type InceptionEvent, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, type RevokeEvent, type RotateEvent, type SignedEvent, verifyInception, verifyReset, verifyRevoke, verifyRotate, verifySignatures, } from './events.js';
-export { CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD, CAPABILITY_REVOKE_NEEDS_VERIFIER, CAPABILITY_VERIFIER_FAILED, CAPABILITY_VERIFIER_MALFORMED_ANSWER, type CapabilityAuthorisation, type FoldOptions, type FoldResult, foldLog, foldLogAsync, type KeyState, keyStateAt, MAX_SKIPPED_SLACK, pruneDenySet, REVOKE_NOT_SIGNED_BY_AUDIENCE, TOO_MANY_UNKNOWN_EVENTS, type VerifyCapabilityParams, } from './fold.js';
-export { authoritativeStates, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE, type LogStore, } from './history.js';
-export { createControllerIdentity, createControllerIdentityAsync, createControllerIdentityWithKey, createControllerIdentityWithKeyAsync, } from './identity.js';
+export { TOO_MANY_FAILED_SIGNATURES } from './epoch.js';
+export { type AddEvent, type CreateAddParams, type CreateRemoveParams, type CreateRenewParams, type CreateRevokeParams, createAdd, createRemove, createRenew, createRevoke, type EpochEvent, type EpochEventCommon, type EpochEventType, type EpochSigner, isEpochEventShape, type RemoveEvent, type RenewEvent, type RevokeEvent, verifyEpochSignature, } from './epoch-events.js';
+export { type CreateRotateParams, createInception, createReset, createRotate, DID_PREFIX, didFor, didFromInception, type EventCommon, type EventType, type InceptionEvent, isMemberEntry, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, type MemberEntry, type RotateEvent, type SignedEvent, type StateSnapshot, verifyInception, verifyReset, verifyRotate, verifySignatures, } from './events.js';
+export { type FoldResult, foldLog, type KeyState, keyStateAt, MAX_SKIPPED_SLACK, type MemberState, ROTATE_NEEDS_SNAPSHOT, SNAPSHOT_DROPS_RETIRED_KEY, SNAPSHOT_MALFORMED, SNAPSHOT_MEMBER_DID_MISMATCH, SNAPSHOT_MEMBER_KEY_IS_ROOT, snapshotOf, TOO_MANY_UNKNOWN_EVENTS, } from './fold.js';
+export { type AuthoritativeLog, type AuthoritativeLogParams, authoritativeLog, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE, type LogStore, } from './history.js';
+export { createControllerIdentity, createControllerIdentityWithKey, } from './identity.js';
 export { decodeKey, encodeKey, type KeyAlgorithm, type TaggedKey, tryDecodeKey, } from './keys.js';
 export { type ProvideControllerIdentityParams, provideControllerIdentity, } from './keystore-identity.js';
+export { DEFAULT_LEASE_SECONDS, MAX_EPOCH_EVENTS, MAX_EVENT_BYTES, MAX_EVENT_PARENTS, MAX_EVENT_SIGNATURES, MAX_FAILED_SIGNATURES, MAX_LOG_EVENTS, } from './limits.js';
+export { type ControllerLog, epochHeads, isControllerLog, LOG_TOO_LARGE, LOG_UNFOLDABLE, MALFORMED_LOG, mergeLogs, pruneLog, } from './log.js';
 export { enumerateProfiles, handleForDID, type ProfileEntry } from './profiles.js';
-export { type ControllerResolverOptions, createControllerResolver } from './resolver.js';
-export { type Duplicity, type ResolveFailure, type ResolveResult, resolveBranches, resolveBranchesAsync, } from './supersede.js';
+export { type ControllerResolver, type ControllerResolverOptions, createControllerResolver, } from './resolver.js';
+export { EPOCH_SATURATED, MEMBER_NOT_EFFECTIVE } from './state-resolver.js';
+export { type Duplicity, type ResolveFailure, type ResolveResult, resolveBranches, } from './supersede.js';
 export { VERSION_TAG } from './version.js';

package/lib/index.js

@@ -10,13 +10,18 @@
  * @module controller
  */ export { canonicalBytes, digestOf, isCanonicalizable, MAX_CANONICAL_DEPTH, verifyDigest, withinCanonicalDepth } from './canonical.js';
 export { agreementPath, authorityPath, deriveKeyMaterial, deriveKeyPair, recoveryPath } from './derivation.js';
-export { createInception, createReset, createRevoke, createRevokeWithKey, createRotate, DID_PREFIX, didFor, didFromInception, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, verifyInception, verifyReset, verifyRevoke, verifyRotate, verifySignatures } from './events.js';
-export { CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD, CAPABILITY_REVOKE_NEEDS_VERIFIER, CAPABILITY_VERIFIER_FAILED, CAPABILITY_VERIFIER_MALFORMED_ANSWER, foldLog, foldLogAsync, keyStateAt, MAX_SKIPPED_SLACK, pruneDenySet, REVOKE_NOT_SIGNED_BY_AUDIENCE, TOO_MANY_UNKNOWN_EVENTS } from './fold.js';
-export { authoritativeStates, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE } from './history.js';
-export { createControllerIdentity, createControllerIdentityAsync, createControllerIdentityWithKey, createControllerIdentityWithKeyAsync } from './identity.js';
+export { TOO_MANY_FAILED_SIGNATURES } from './epoch.js';
+export { createAdd, createRemove, createRenew, createRevoke, isEpochEventShape, verifyEpochSignature } from './epoch-events.js';
+export { createInception, createReset, createRotate, DID_PREFIX, didFor, didFromInception, isMemberEntry, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, verifyInception, verifyReset, verifyRotate, verifySignatures } from './events.js';
+export { foldLog, keyStateAt, MAX_SKIPPED_SLACK, ROTATE_NEEDS_SNAPSHOT, SNAPSHOT_DROPS_RETIRED_KEY, SNAPSHOT_MALFORMED, SNAPSHOT_MEMBER_DID_MISMATCH, SNAPSHOT_MEMBER_KEY_IS_ROOT, snapshotOf, TOO_MANY_UNKNOWN_EVENTS } from './fold.js';
+export { authoritativeLog, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE } from './history.js';
+export { createControllerIdentity, createControllerIdentityWithKey } from './identity.js';
 export { decodeKey, encodeKey, tryDecodeKey } from './keys.js';
 export { provideControllerIdentity } from './keystore-identity.js';
+export { DEFAULT_LEASE_SECONDS, MAX_EPOCH_EVENTS, MAX_EVENT_BYTES, MAX_EVENT_PARENTS, MAX_EVENT_SIGNATURES, MAX_FAILED_SIGNATURES, MAX_LOG_EVENTS } from './limits.js';
+export { epochHeads, isControllerLog, LOG_TOO_LARGE, LOG_UNFOLDABLE, MALFORMED_LOG, mergeLogs, pruneLog } from './log.js';
 export { enumerateProfiles, handleForDID } from './profiles.js';
 export { createControllerResolver } from './resolver.js';
-export { resolveBranches, resolveBranchesAsync } from './supersede.js';
+export { EPOCH_SATURATED, MEMBER_NOT_EFFECTIVE } from './state-resolver.js';
+export { resolveBranches } from './supersede.js';
 export { VERSION_TAG } from './version.js';

package/lib/keystore-identity.d.ts

@@ -1,5 +1,4 @@
 import type { FullIdentity, KeyEntry } from '@kokuin/token';
-import type { FoldOptions } from './fold.js';
 import type { LogStore } from './history.js';
 export type ProvideControllerIdentityParams = {
     /** The seed source: `provideAsync()`'s bytes are the controller root seed. Generates on first use. */
@@ -8,8 +7,6 @@ export type ProvideControllerIdentityParams = {
     profile: number;
     /** Where the last accepted log for the DID lives — loaded to restore, written to on first generate. */
     logStore: LogStore;
-    /** Forwarded to the fold for a log whose revoke carries a capability only the async fold can verify. */
-    options?: FoldOptions;
 };
 /**
  * Resolve a `did:kokuin:` {@link FullIdentity} from a keystore entry and a log store.
@@ -19,4 +16,4 @@ export type ProvideControllerIdentityParams = {
  * log yet). The DID is a pure function of `(seed, profile)`, so the same entry and profile always
  * resolve the same identity. A `KeyStore` caller passes `keyStore.entry(keyID)` as `entry`.
  */
-export declare function provideControllerIdentity({ entry, profile, logStore, options, }: ProvideControllerIdentityParams): Promise<FullIdentity>;
+export declare function provideControllerIdentity({ entry, profile, logStore, }: ProvideControllerIdentityParams): Promise<FullIdentity>;

package/lib/keystore-identity.js

@@ -1,5 +1,5 @@
 import { createInception, didFor } from './events.js';
-import { createControllerIdentityAsync } from './identity.js';
+import { createControllerIdentity } from './identity.js';
 /**
  * Resolve a `did:kokuin:` {@link FullIdentity} from a keystore entry and a log store.
  *
@@ -7,20 +7,23 @@ import { createControllerIdentityAsync } from './identity.js';
  * one after), and the log store yields the event log (bootstrapping the inception when the DID has no
  * log yet). The DID is a pure function of `(seed, profile)`, so the same entry and profile always
  * resolve the same identity. A `KeyStore` caller passes `keyStore.entry(keyID)` as `entry`.
- */ export async function provideControllerIdentity({ entry, profile, logStore, options }) {
+ */ export async function provideControllerIdentity({ entry, profile, logStore }) {
     const seed = await entry.provideAsync();
     const did = didFor(seed, profile);
     let log = await logStore.get(did);
-    if (log == null) {
-        log = [
+    if (log == null || log.chain.length === 0) {
+        const inception = [
             createInception(seed, profile)
         ];
-        await logStore.set(did, log);
+        // Through the merge, so a log another writer stored meanwhile is kept rather than overwritten.
+        log = await logStore.merge(did, async (current)=>current != null && current.chain.length > 0 ? current : {
+                chain: inception,
+                events: []
+            });
     }
-    return createControllerIdentityAsync({
+    return createControllerIdentity({
         seed,
         profile,
-        log,
-        options
+        log
     });
 }

package/lib/limits.d.ts

@@ -0,0 +1,29 @@
+/** Authenticated, causally valid events one epoch may carry before it saturates. */
+export declare const MAX_EPOCH_EVENTS = 4096;
+/**
+ * Request limit: epoch events in one input. Above {@link MAX_EPOCH_EVENTS}, so a saturating epoch can
+ * still be presented whole and remembered as saturated rather than turned away as oversized.
+ */
+export declare const MAX_LOG_EVENTS = 8192;
+/**
+ * Request limit: signatures that fail to verify in one input, counted over every distinct copy the
+ * fold checks, each charged for every signature it carries. Past it the input is refused as a whole.
+ *
+ * Nothing honest fails a signature check: every copy a verifier holds verified when it was kept, and
+ * Ed25519 signing is deterministic, so a relay passing on what it holds carries no failures at all. So
+ * the limit can be small, and is: 64 checks cost a few tens of milliseconds, against the seconds an
+ * unbounded flood of forgeries cost when the limit was only {@link MAX_LOG_EVENTS}. It is above zero
+ * so that a little corruption in transit does not cost a whole presentation.
+ */
+export declare const MAX_FAILED_SIGNATURES = 64;
+/** Request limit: parents one epoch event may list. */
+export declare const MAX_EVENT_PARENTS = 16;
+/** Request limit: canonical bytes of one epoch event body. */
+export declare const MAX_EVENT_BYTES = 8192;
+/** A member's lease when the caller names none: 90 days, in seconds. */
+export declare const DEFAULT_LEASE_SECONDS = 7776000;
+/**
+ * Request limit: signatures one epoch event may carry. Not counted in {@link MAX_EVENT_BYTES}, so it
+ * bounds the walk separately; a member event carries exactly one, a root event one per chain key.
+ */
+export declare const MAX_EVENT_SIGNATURES = 16;

package/lib/limits.js

@@ -0,0 +1,27 @@
+// Two kinds of limit, never confused. A *request* limit rejects input: unauthenticated or invalid
+// events only ever get turned away, they never change remembered state. *Saturation* is the one
+// limit authenticated input can reach: an epoch carrying more distinct, causally valid events than
+// it allows fails closed until root settles into a fresh one. Work is counted in events, edges and
+// signatures, never elapsed time, so every verifier draws the same line.
+/** Authenticated, causally valid events one epoch may carry before it saturates. */ export const MAX_EPOCH_EVENTS = 4096;
+/**
+ * Request limit: epoch events in one input. Above {@link MAX_EPOCH_EVENTS}, so a saturating epoch can
+ * still be presented whole and remembered as saturated rather than turned away as oversized.
+ */ export const MAX_LOG_EVENTS = 8192;
+/**
+ * Request limit: signatures that fail to verify in one input, counted over every distinct copy the
+ * fold checks, each charged for every signature it carries. Past it the input is refused as a whole.
+ *
+ * Nothing honest fails a signature check: every copy a verifier holds verified when it was kept, and
+ * Ed25519 signing is deterministic, so a relay passing on what it holds carries no failures at all. So
+ * the limit can be small, and is: 64 checks cost a few tens of milliseconds, against the seconds an
+ * unbounded flood of forgeries cost when the limit was only {@link MAX_LOG_EVENTS}. It is above zero
+ * so that a little corruption in transit does not cost a whole presentation.
+ */ export const MAX_FAILED_SIGNATURES = 64;
+/** Request limit: parents one epoch event may list. */ export const MAX_EVENT_PARENTS = 16;
+/** Request limit: canonical bytes of one epoch event body. */ export const MAX_EVENT_BYTES = 8192;
+/** A member's lease when the caller names none: 90 days, in seconds. */ export const DEFAULT_LEASE_SECONDS = 7_776_000;
+/**
+ * Request limit: signatures one epoch event may carry. Not counted in {@link MAX_EVENT_BYTES}, so it
+ * bounds the walk separately; a member event carries exactly one, a root event one per chain key.
+ */ export const MAX_EVENT_SIGNATURES = 16;

package/lib/log.d.ts

@@ -0,0 +1,124 @@
+import { type EpochLimits } from './epoch.js';
+import { type EpochEvent } from './epoch-events.js';
+import type { SignedEvent } from './events.js';
+import { type FoldResult, type KeyState } from './fold.js';
+/**
+ * Everything a controller's log holds: the root chain, which fixes the keys and every settlement, and
+ * the epoch events that built up on the chain's last event since. They are separate lists because
+ * they fold by different rules -- the chain is a sequence, order is meaning; the epoch is a set,
+ * order is nothing -- and a presentation of one is no claim about the other.
+ */
+export type ControllerLog = {
+    chain: Array<SignedEvent>;
+    events: Array<SignedEvent<EpochEvent>>;
+};
+/** What a request carrying more epoch events than {@link MAX_LOG_EVENTS} fails with. */
+export declare const LOG_TOO_LARGE = "controller log exceeds request limits";
+/** What an input that is not a {@link ControllerLog} at all fails with. */
+export declare const MALFORMED_LOG = "malformed log";
+/**
+ * Whether `value` has the two lists a log is made of. Only the outer shape: every entry is untrusted
+ * and is checked by the fold that reads it, which reports a bad one rather than throwing.
+ */
+export declare function isControllerLog(value: unknown): value is ControllerLog;
+/** What a resolver answers with when the loaded log loses to the one already seen. */
+export declare const LOG_NOT_AUTHORITATIVE = "the loaded log does not supersede the one already seen";
+/** What a resolver answers with when the loaded log and the one already seen are a genuine fork. */
+export declare const LOG_FORKED = "the loaded log and the one already seen are a fork";
+/** What {@link mergeLogs} and {@link pruneLog} fail with when no chain they were given folds. */
+export declare const LOG_UNFOLDABLE = "no controller log chain folds";
+/** A fold of a held log, with the copy of each applied event whose signature the fold verified. */
+export type HeldFold = {
+    result: Extract<FoldResult, {
+        ok: true;
+    }>;
+    /** Per applied digest, the copy that verified. See {@link appliedCopies}. */
+    authentic: ReadonlyMap<string, SignedEvent<EpochEvent>>;
+};
+/**
+ * Fold a log this party already holds: the chain through the full fold, the epoch under the held
+ * request limit rather than `MAX_LOG_EVENTS`. The request limit bounds what one *input* may make a
+ * verifier do; a held log is the union of inputs that each passed it and is already bounded by what
+ * memory keeps (one epoch, at most `MAX_EPOCH_EVENTS + 1` events once saturated), but the union with a
+ * fresh presentation can exceed it. Folding through {@link foldLog} would turn that into
+ * `LOG_TOO_LARGE` — "no memory" — which is exactly the forgetting the history exists to prevent.
+ *
+ * Nothing in `log` is trusted: every signature is checked, under the failed-signature limit.
+ */
+export declare function foldHeld(did: string, log: ControllerLog, limits?: Partial<EpochLimits>): HeldFold | Extract<FoldResult, {
+    ok: false;
+}>;
+/**
+ * The chain's states merged with `events` as the current epoch, as {@link foldLog} reports it.
+ * `trusted` is this party's own memory (see `FoldEpochParams.trusted`), never a presentation. Refused,
+ * at index -1, when `events` passes the failed-signature limit.
+ */
+export declare function withEpoch(did: string, states: Array<KeyState>, events: Array<unknown>, limits?: Partial<EpochLimits>, trusted?: Array<unknown>): HeldFold | Extract<FoldResult, {
+    ok: false;
+}>;
+/**
+ * The parents an epoch event built now should name: the current epoch's applied events that no
+ * applied event names as a parent, sorted ascending, or `[head.epoch]` when none applied. An event
+ * naming every tip is causally after everything its author has seen, and authorisation is judged
+ * against exactly that causal past -- naming fewer leaves the author's own view out of it.
+ *
+ * Pending and rejected events are never heads: they are not part of the folded epoch. Throws, with
+ * the fold's reason, when the log does not fold; a builder has nothing to extend then.
+ *
+ * At most `MAX_EVENT_PARENTS` are returned, so the answer is always a valid `parents`: when the epoch
+ * has more tips (concurrent events are free to make), the smallest digests. The event built on them is
+ * causally after those alone; the rest stay tips, and the next event built from `epochHeads` names
+ * them, so repeated building folds every tip in. Throws `LOG_TOO_LARGE` on a log larger than any a
+ * verifier holds.
+ */
+export declare function epochHeads(did: string, log: ControllerLog): Array<string>;
+/**
+ * One copy of each event the fold applied, in the fold's own order (parents first): all that may be
+ * remembered of an epoch. An entry the fold did not apply was never authenticated, so it never
+ * reaches memory however it was presented.
+ *
+ * The copy is the one the fold itself verified, never re-derived here. Copies of one body share a
+ * digest and differ only in signatures, and the fold applies the event if *any* copy verifies — so
+ * "applied" alone does not say which copy to keep. Keeping the first one presented would let a relay
+ * put a forged copy ahead of the genuine one and have memory keep the forgery, losing the event on
+ * the next fold; re-checking signatures against a signer looked up afresh would answer a subtly
+ * different question from the one the fold answered, and drop the event whenever they disagree.
+ *
+ * Saturation: an epoch holding more than `MAX_EPOCH_EVENTS` applied events is kept as only the
+ * first `MAX_EPOCH_EVENTS + 1` of them. A prefix of the fold's topological order is closed under
+ * ancestors, and an event's authorisation is a function of its ancestors alone, so the prefix refolds
+ * to the same events applied — one more than the limit, saturated on every refold, never more held.
+ */
+export declare function appliedCopies({ result, authentic }: HeldFold, limits?: Partial<EpochLimits>): Array<SignedEvent<EpochEvent>>;
+/**
+ * Two views of one controller's log, combined. A pure merge, for a party joining what it holds with
+ * what it was handed (a grant's proof, a peer's copy) before folding.
+ *
+ * The chain is settled by the branch rules: `b`'s when it extends `a`'s, else the winner of
+ * {@link resolveBranches}, and a fork throws rather than merging two histories root never wrote as
+ * one. The events are a union, deduplicated by digest *and signatures*: a copy carrying different
+ * signatures is kept beside the first, since the fold applies an event when any copy verifies and
+ * keeping only the first would let a forged copy shadow the genuine one. Entries that are not epoch
+ * events at all are dropped; the fold would only have refused them.
+ *
+ * Nothing here authenticates an event. The result is input to a fold, not memory: persist what
+ * `authoritativeLog` returns instead. A union of two inputs can exceed the request limit a single
+ * input is held to, which {@link foldLog} then reports. Each input may be at most what a verifier
+ * holds plus one presentation; a larger one throws `LOG_TOO_LARGE` before any work.
+ */
+export declare function mergeLogs(did: string, a: ControllerLog, b: ControllerLog): ControllerLog;
+/**
+ * The least of a log that still folds to the same head: the inception, the current generation's
+ * chain, and the current epoch's applied events.
+ *
+ * Earlier generations go because a reset chains to the inception, not to what preceded it, and the
+ * generation's keys and tombstones are read off the generation alone. Unknown events the chain fold
+ * skipped go too: they moved no state, so nothing chains to them. Earlier epochs' events go because
+ * an event naming another epoch has no effect; unapplied ones because they were never authenticated.
+ * A saturated epoch keeps exactly enough to stay saturated (see {@link appliedCopies}).
+ *
+ * Meant for a log this party already holds: the epoch is folded under the held request limit, not
+ * `MAX_LOG_EVENTS` (see {@link foldHeld}). Throws {@link LOG_UNFOLDABLE} when the chain does not fold,
+ * and the request limit's reason when the log passes one.
+ */
+export declare function pruneLog(did: string, log: ControllerLog): ControllerLog;