@plane31/blind-relay 0.1.1 → 0.1.3

package/src/testing/sweep.ts

@@ -0,0 +1,407 @@
+/**
+ * The crash and lost-response sweeps of build step 16. One scenario (two accounts, a circle,
+ * records of a slot kind both ways, an event kind, concurrent contexts, a device replacement) runs once with no
+ * fault to count the victim's transaction boundaries, then once per boundary and phase with the
+ * victim's process crashing there, restarting, and finishing the scenario. After every run the
+ * durable-state outcomes of protocol section 11 are checked against the host's view.
+ */
+import { fromHex, toHex } from "../bytes.js";
+import { open, type Client, type ClientEvent } from "../client.js";
+import { KavachError } from "../errors.js";
+import { MemorySecretStore, type Store } from "../store.js";
+import type { Transport } from "../transport.js";
+import { TestClock, testPolicy } from "./clock.js";
+import { FakeHost } from "./fakeHost.js";
+import { FaultyStore, MaliciousTransport, type CrashPhase, type CrashPlan, type MutationName } from "./faults.js";
+import { testResetKeyList, testResetKeys } from "./fixtures.js";
+import { MemoryPlatformProvider } from "./providers.js";
+
+export type DeviceName = "alice" | "bob" | "bob2";
+
+export interface SweepStores {
+  /** A durable store for the named device of this run, empty. */
+  open(run: string, name: DeviceName): Promise<Store> | Store;
+  /** The same durable state as a restarted process opens it: a new handle on the same file. */
+  reopen(run: string, name: DeviceName): Promise<Store> | Store;
+  /** Another in-process handle on the same durable state, when the engine can give one. */
+  fork?(run: string, name: DeviceName): Store;
+  dispose?(run: string): Promise<void> | void;
+}
+
+export interface SweepOptions {
+  readonly stores: SweepStores;
+  readonly victim: DeviceName;
+  readonly phases?: readonly CrashPhase[];
+  /** Run only these boundaries (for narrowing a failure). */
+  readonly only?: readonly number[];
+}
+
+export interface SweepRun {
+  readonly at: number;
+  readonly phase: CrashPhase;
+  /** The scenario step during which the process died. */
+  readonly crashedDuring: string;
+  /** What the re-invoked step answered after the restart. */
+  readonly retry: string;
+}
+
+export interface SweepResult {
+  readonly boundaries: number;
+  readonly runs: readonly SweepRun[];
+}
+
+export interface LostResponseRun {
+  readonly mutation: MutationName;
+  /** Whether the victim actually issued that mutation in this scenario. */
+  readonly exercised: boolean;
+}
+
+const resetKeys = testResetKeys();
+const resetTrust = { managementKey: resetKeys.management.publicKey, minimumVersion: 1n };
+
+interface Device {
+  name: DeviceName;
+  client: Client;
+  store: FaultyStore;
+  secrets: MemorySecretStore;
+  events: ClientEvent[];
+  provider: MemoryPlatformProvider;
+  transport: MaliciousTransport;
+}
+
+interface Runtime {
+  host: FakeHost;
+  clock: TestClock;
+  devices: Map<DeviceName, Device>;
+}
+
+function newHost(): { host: FakeHost; clock: TestClock } {
+  const host = new FakeHost();
+  const clock = new TestClock();
+  host.now = clock.now;
+  host.resetSigner = { key: resetKeys.operational, keyId: resetKeys.operationalKeyId };
+  host.resetKeyList = testResetKeyList(resetKeys, clock.now());
+  return { host, clock };
+}
+
+function accountOf(name: DeviceName): string {
+  return name === "bob2" ? "bob" : name;
+}
+
+/** The transport of a device: bound to the account's current certificate at the host on every call. */
+export function hostTransport(host: FakeHost, account: string): Transport {
+  const bind = (): Transport => {
+    const acct = host.accounts.get(account);
+    return host.asDevice(account, acct ? fromHex(acct.certificateHash) : new Uint8Array(32));
+  };
+  return {
+    get directory() {
+      return bind().directory;
+    },
+    get relay() {
+      return bind().relay;
+    }
+  };
+}
+
+async function openDevice(rt: Runtime, name: DeviceName, store: FaultyStore, secrets: MemorySecretStore, provider: MemoryPlatformProvider, transport: MaliciousTransport): Promise<Device> {
+  const events: ClientEvent[] = [];
+  const client = await open({ accountName: accountOf(name), retentionPolicy: testPolicy, recoveryProvider: provider, resetTrust, secretStore: secrets, store, transport, now: rt.clock.now });
+  client.subscribe((e) => events.push(e));
+  const d: Device = { name, client, store, secrets, events, provider, transport };
+  rt.devices.set(name, d);
+  return d;
+}
+
+type Step = { name: string; run: () => Promise<unknown> };
+
+interface Scenario {
+  steps: Step[];
+  rt: Runtime;
+}
+
+function scenario(rt: Runtime, stores: SweepStores, run: string): Scenario {
+  const d = (n: DeviceName): Device => {
+    const x = rt.devices.get(n);
+    if (!x) throw new Error("no device " + n);
+    return x;
+  };
+  let circleId: Uint8Array = new Uint8Array(16);
+  let aliceId: Uint8Array = new Uint8Array(32);
+  // Distinct opaque payloads with the clock as the event time: the sweep needs bytes, not a codec.
+  const loc = (n: number): [Uint8Array, { eventTime: bigint }] => [Uint8Array.of(1, n), { eventTime: rt.clock.now() }];
+  const sync = (n: DeviceName) => async (): Promise<unknown> => {
+    rt.clock.advance(1_000n);
+    return d(n).client.sync();
+  };
+  const steps: Step[] = [
+    { name: "alice.init", run: () => d("alice").client.initializeAccount() },
+    { name: "bob.init", run: () => d("bob").client.initializeAccount() },
+    {
+      name: "alice.create",
+      run: async () => {
+        circleId = (await d("alice").client.circles.create()).circleId;
+        aliceId = (await d("alice").client.inspect()).identityId ?? aliceId;
+      }
+    },
+    { name: "bob.requestJoin", run: () => d("bob").client.circles.requestJoin(circleId, aliceId) },
+    { name: "alice.sync#1", run: sync("alice") },
+    { name: "alice.approve", run: () => d("alice").client.circles.approve(circleId, "bob") },
+    { name: "alice.sync#2", run: sync("alice") },
+    { name: "bob.sync#1", run: sync("bob") },
+    { name: "alice.sync#3", run: sync("alice") },
+    { name: "alice.enqueue#1", run: () => d("alice").client.enqueue(0, ...loc(1)) },
+    { name: "alice.enqueue#2", run: () => d("alice").client.enqueue(0, ...loc(2)) },
+    { name: "alice.sync#4", run: sync("alice") },
+    { name: "bob.sync#2", run: sync("bob") },
+    { name: "bob.event", run: () => d("bob").client.enqueue(1, ...loc(3)) },
+    { name: "bob.sync#3", run: sync("bob") },
+    { name: "alice.sync#5", run: sync("alice") },
+    {
+      name: "alice.concurrent",
+      run: async () => {
+        if (!stores.fork) return;
+        // A background context: a second client over another handle on the same store.
+        const a = d("alice");
+        const bg = await open({ accountName: "alice", retentionPolicy: testPolicy, recoveryProvider: a.provider, resetTrust, secretStore: a.secrets, store: a.store.fork(), transport: a.transport, now: rt.clock.now });
+        await Promise.all([a.client.sync(), bg.enqueue(0, ...loc(4)), bg.enqueue(0, ...loc(5))]);
+        await a.client.sync();
+      }
+    },
+    { name: "bob2.restore", run: () => d("bob2").client.restoreAccount() },
+    { name: "bob2.sync#1", run: sync("bob2") },
+    { name: "alice.sync#6", run: sync("alice") },
+    { name: "alice.enqueue#3", run: () => d("alice").client.enqueue(0, ...loc(6)) },
+    { name: "alice.sync#7", run: sync("alice") },
+    { name: "bob2.sync#2", run: sync("bob2") },
+    { name: "bob.sync#4", run: sync("bob") },
+    { name: "bob2.event", run: () => d("bob2").client.enqueue(1, ...loc(7)) },
+    { name: "bob2.sync#3", run: sync("bob2") },
+    { name: "alice.sync#8", run: sync("alice") }
+  ];
+  void run;
+  return { steps, rt };
+}
+
+async function setup(stores: SweepStores, run: string, plan: { victim: DeviceName; crash?: CrashPlan; lose?: MutationName }): Promise<Runtime> {
+  const { host, clock } = newHost();
+  const rt: Runtime = { host, clock, devices: new Map() };
+  const bobPlatform = new MemoryPlatformProvider("bob@platform");
+  for (const name of ["alice", "bob", "bob2"] as const) {
+    const inner = await stores.open(run, name);
+    const isVictim = name === plan.victim;
+    const forkInner = stores.fork ? (): Store => stores.fork?.(run, name) as Store : undefined;
+    const store = new FaultyStore(inner, isVictim ? plan.crash : undefined, forkInner);
+    const transport = new MaliciousTransport(hostTransport(host, accountOf(name)));
+    if (isVictim && plan.lose) transport.knobs.loseResponseOf.add(plan.lose);
+    const provider = name === "alice" ? new MemoryPlatformProvider("alice@platform") : bobPlatform.twin();
+    await openDevice(rt, name, store, new MemorySecretStore(), provider, transport);
+  }
+  return rt;
+}
+
+/** The victim's process restarts: a new handle on the same durable state, the same secrets. */
+async function restart(rt: Runtime, stores: SweepStores, run: string, victim: DeviceName): Promise<void> {
+  const old = rt.devices.get(victim);
+  if (!old) throw new Error("no victim");
+  const forkInner = stores.fork ? (): Store => stores.fork?.(run, victim) as Store : undefined;
+  const store = new FaultyStore(await stores.reopen(run, victim), undefined, forkInner);
+  const transport = new MaliciousTransport(hostTransport(rt.host, accountOf(victim)));
+  await openDevice(rt, victim, store, old.secrets, old.provider, transport);
+}
+
+function describeError(e: unknown): string {
+  return e instanceof KavachError ? `${e.code}@${e.stage}` : e instanceof Error ? e.name : String(e);
+}
+
+/** Runs the steps; on the victim's crash restarts it and re-invokes the step, then continues. */
+async function drive(sc: Scenario, stores: SweepStores, run: string, victim: DeviceName): Promise<{ crashedDuring: string; retry: string }> {
+  let crashedDuring = "";
+  let retry = "";
+  for (const step of sc.steps) {
+    const v = sc.rt.devices.get(victim);
+    if (!v) throw new Error("no victim");
+    const lossesBefore = v.transport.losses.length;
+    let failed: unknown;
+    try {
+      await step.run();
+    } catch (e) {
+      failed = e;
+    }
+    if (!v.store.crashed && v.transport.losses.length > lossesBefore && failed !== undefined) {
+      // The app sees a failed operation and retries it; the host already committed the write.
+      try {
+        await step.run();
+        retry = "OK";
+      } catch (e) {
+        if (!(e instanceof KavachError)) throw e;
+        retry = describeError(e);
+      }
+      continue;
+    }
+    if (v.store.crashed) {
+      if (crashedDuring) throw new Error(`crashed twice (${crashedDuring}, ${step.name})`);
+      crashedDuring = step.name;
+      await restart(sc.rt, stores, run, victim);
+      try {
+        await step.run();
+        retry = "OK";
+      } catch (e) {
+        if (!(e instanceof KavachError)) throw e;
+        retry = describeError(e);
+      }
+      continue;
+    }
+    if (failed !== undefined) throw new Error(`step ${step.name} failed without a crash: ${describeError(failed)}`);
+  }
+  return { crashedDuring, retry };
+}
+
+/** The durable-state outcomes of section 11, checked against the host after quiescence. */
+async function checkInvariants(rt: Runtime, label: string): Promise<void> {
+  const fail = (what: string): never => {
+    throw new Error(`[${label}] ${what}`);
+  };
+  const d = (n: DeviceName): Device => rt.devices.get(n) ?? fail("no device " + n);
+  // Quiescence.
+  for (let i = 0; i < 2; i++) {
+    rt.clock.advance(1_000n);
+    await d("alice").client.sync();
+    await d("bob2").client.sync();
+  }
+  const host = rt.host;
+  const alice = host.accounts.get("alice") ?? fail("alice unknown at host");
+  const bob = host.accounts.get("bob") ?? fail("bob unknown at host");
+  // Activation: exactly one replacement, never a third device, never a reset.
+  if (alice.generation !== 1n || alice.deviceIds.size !== 1) fail(`alice generation ${alice.generation} devices ${alice.deviceIds.size}`);
+  if (bob.generation !== 2n || bob.deviceIds.size !== 2) fail(`bob generation ${bob.generation} devices ${bob.deviceIds.size}`);
+  if (alice.previousIdentities.size || bob.previousIdentities.size) fail("an identity was reset");
+  const aliceState = await d("alice").client.getState();
+  const bob2State = await d("bob2").client.getState();
+  const bobState = await d("bob").client.getState();
+  if (aliceState.status !== "ready") fail(`alice is ${aliceState.status}`);
+  if (bob2State.status !== "ready") fail(`bob2 is ${bob2State.status}`);
+  if (bobState.status !== "retired") fail(`old bob is ${bobState.status}`);
+  if (toHex(aliceState.identityId ?? new Uint8Array()) !== alice.identityId) fail("alice identity differs from the host's");
+  if (toHex(bob2State.identityId ?? new Uint8Array()) !== bob.identityId) fail("bob2 identity differs from the host's");
+  if (toHex(bob2State.certificateHash ?? new Uint8Array()) !== bob.certificateHash) fail("bob2 certificate differs from the host's");
+  // Streams: every epoch the host holds is the exact bytes the author saved, and the author's
+  // active epoch is the host's current one.
+  for (const name of ["alice", "bob2", "bob"] as const) {
+    const dev = d(name);
+    const inner = dev.store.inner;
+    const pin = await inner.read((tx) => tx.get("self", "self")) ?? fail(`${name} has no self row`);
+    const s = host.streams.get(pin.streamId) ?? fail(`${name} has no stream at the host`);
+    const rows = await inner.read((tx) => tx.list("epochs"));
+    const byEpoch = new Map(rows.map(([, r]) => [r.epoch, r]));
+    for (const [epoch, e] of s.epochs) {
+      const row = byEpoch.get(epoch) ?? fail(`${name}: host epoch ${epoch} has no local row`);
+      if (row.manifest !== toHex(e.manifest)) fail(`${name}: epoch ${epoch} bytes differ between host and store`);
+    }
+    for (const [, r] of rows) {
+      if (r.status === "prepared") continue;
+      if (r.epoch > s.currentEpoch) fail(`${name}: local epoch ${r.epoch} (${r.status}) above the host's ${s.currentEpoch}`);
+    }
+    const stream = await inner.read((tx) => tx.get("stream", "stream"));
+    if (name !== "bob") {
+      if (stream?.activeEpoch !== s.currentEpoch) fail(`${name}: active epoch ${stream?.activeEpoch} but host current ${s.currentEpoch}`);
+      const active = rows.filter(([, r]) => r.status === "active");
+      if (active.length !== 1) fail(`${name}: ${active.length} active epochs`);
+    }
+    // Records: every append the host saw is in the author's own history, the same recordId was
+    // never asked to accept two different wires, and no counter was reused.
+    const own = new Set((await inner.read((tx) => tx.list("history"))).filter(([, h]) => h.own).map(([, h]) => h.recordId));
+    const log = host.appendLog.filter((a) => a.streamId === pin.streamId);
+    const hashes = new Map<string, string>();
+    for (const a of log) {
+      if (!own.has(a.recordId)) fail(`${name}: record ${a.recordId.slice(0, 8)} reached the host without a history row`);
+      const h = hashes.get(a.recordId);
+      if (h && h !== a.hash) fail(`${name}: record ${a.recordId.slice(0, 8)} was sent with two different wires`);
+      hashes.set(a.recordId, a.hash);
+      if (a.status === "EQUIVOCATION" || a.status === "STALE_APPEND") fail(`${name}: the host answered ${a.status}`);
+    }
+    const outbox = await inner.read((tx) => tx.list("outbox").map(([, r]) => r.status));
+    if (name !== "bob" && outbox.some((st) => st !== "accepted" && st !== "cancelled")) fail(`${name}: outbox left ${outbox.join(",")}`);
+    // Cursors: the client never records a cursor the host does not hold.
+    const subs = await inner.read((tx) => tx.list("subscriptions"));
+    for (const [, sub] of subs) {
+      const hs = host.streams.get(sub.streamId);
+      const hostSub = hs?.subscriptions.get(toHex(dev.client ? (await dev.client.getState()).certificateHash ?? new Uint8Array() : new Uint8Array()));
+      if (hostSub && hostSub.cursor < BigInt(sub.committedCursor)) fail(`${name}: committed cursor ${sub.committedCursor} above the host's ${hostSub.cursor}`);
+    }
+  }
+  // Delivery: bob2 holds alice's newest record of kind 0; alice has bob's kind 1 records.
+  const aliceId = fromHex(alice.identityId);
+  const pin = await d("bob2").client.newest(aliceId, 0);
+  const aliceStream = host.streams.get((await d("alice").store.inner.read((tx) => tx.get("self", "self")))?.streamId ?? "");
+  const accepted = host.appendLog.filter((a) => a.streamId === (aliceStream ? [...host.streams.entries()].find(([, s]) => s === aliceStream)?.[0] : "") && (a.status === "ACCEPTED" || a.status === "ALREADY_ACCEPTED"));
+  const last = [...accepted].reverse().find((a) => a.epoch === aliceStream?.currentEpoch);
+  if (last && (!pin || toHex(pin.recordId) !== last.recordId)) fail(`bob2's slot is ${pin ? toHex(pin.recordId).slice(0, 8) : "missing"}, alice's last is ${last.recordId.slice(0, 8)}`);
+  const events = await d("alice").client.history({ authorIdentityId: fromHex(bob.identityId), kind: 1 });
+  if (events.length < 2) fail(`alice has ${events.length} kind 1 records from bob`);
+}
+
+async function withRun<R>(stores: SweepStores, run: string, fn: () => Promise<R>): Promise<R> {
+  try {
+    return await fn();
+  } finally {
+    await stores.dispose?.(run);
+  }
+}
+
+/** Runs the scenario with no fault and returns the victim's transaction count. */
+export async function countBoundaries(stores: SweepStores, victim: DeviceName): Promise<number> {
+  const run = `reference-${victim}`;
+  return withRun(stores, run, async () => {
+    const rt = await setup(stores, run, { victim });
+    const sc = scenario(rt, stores, run);
+    const { crashedDuring } = await drive(sc, stores, run, victim);
+    if (crashedDuring) throw new Error("the reference run crashed");
+    // Counted before the invariant check, whose own syncs are not part of the scenario.
+    const boundaries = rt.devices.get(victim)?.store.transactions ?? 0;
+    await checkInvariants(rt, "reference");
+    return boundaries;
+  });
+}
+
+export async function crashSweep(options: SweepOptions): Promise<SweepResult> {
+  const { stores, victim } = options;
+  const phases = options.phases ?? ["beforeCommit", "afterCommit"];
+  const boundaries = await countBoundaries(stores, victim);
+  const runs: SweepRun[] = [];
+  for (let at = 1; at <= boundaries; at++) {
+    if (options.only && !options.only.includes(at)) continue;
+    for (const phase of phases) {
+      const run = `${victim}-${phase}-${at}`;
+      await withRun(stores, run, async () => {
+        const rt = await setup(stores, run, { victim, crash: { at, phase } });
+        const sc = scenario(rt, stores, run);
+        const { crashedDuring, retry } = await drive(sc, stores, run, victim);
+        if (!crashedDuring) throw new Error(`[${run}] boundary ${at} was never reached`);
+        await checkInvariants(rt, `${run} during ${crashedDuring}, retry ${retry}`);
+        runs.push({ at, phase, crashedDuring, retry });
+      });
+    }
+  }
+  return { boundaries, runs };
+}
+
+const MUTATIONS: readonly MutationName[] = ["registerAccount", "activateDevice", "publishVault", "publishOwnedCircle", "requestJoin", "publishEpoch", "appendRecord", "ackThrough"];
+
+/** For each mutation the victim issues, the host commits it and the response is lost once. */
+export async function lostResponseSweep(stores: SweepStores, victim: DeviceName): Promise<LostResponseRun[]> {
+  const out: LostResponseRun[] = [];
+  for (const mutation of MUTATIONS) {
+    const run = `${victim}-lost-${mutation}`;
+    await withRun(stores, run, async () => {
+      const rt = await setup(stores, run, { victim, lose: mutation });
+      const sc = scenario(rt, stores, run);
+      const { crashedDuring } = await drive(sc, stores, run, victim);
+      if (crashedDuring) throw new Error("no crash was planned");
+      const v = rt.devices.get(victim);
+      await checkInvariants(rt, run);
+      out.push({ mutation, exercised: v?.transport.losses.includes(mutation) ?? false });
+    });
+  }
+  return out;
+}

package/src/transactions.ts

@@ -0,0 +1,231 @@
+/**
+ * The named transaction boundaries of protocol section 11 (T1 to T5, T8, T9). T6, T6h and T7
+ * live with the outbox and the inbox. Each function takes an open `Tx` so callers can compose
+ * them; nothing here opens the network.
+ */
+import { equalBytes, toHex } from "./bytes.js";
+import { applyAudienceEvent, initialRevisionState, type AudienceEvent } from "./audience.js";
+import { DocumentType, expectType, parseDocument, type AccountDevice } from "./codec.js";
+import { identityId } from "./crypto.js";
+import type { PreparedEpoch } from "./epoch.js";
+import { promote } from "./epoch.js";
+import { KavachError } from "./errors.js";
+import { openAccount, pinFromCertificate, type DeviceKeys, type OwnAccount } from "./identity.js";
+import { big, pinToRow, preparedToRow, revisionToRow, rowToPrepared, rowToRevision, unbig } from "./rows.js";
+import type { ActivationRow, CircleRow, MetaRow, SecretStore, Store, StoreState, Tx, VaultRow } from "./store.js";
+
+export const META = "meta";
+export const SELF = "self";
+export const STREAM = "stream";
+export const REVISION = "revision";
+export const VAULT = "vault";
+
+// Opening -----------------------------------------------------------------------------------------
+
+export type OpenedState =
+  | { readonly kind: "fresh" }
+  | { readonly kind: "initializing"; readonly account: OwnAccount }
+  | { readonly kind: StoreState; readonly meta: MetaRow; readonly account: OwnAccount };
+
+/**
+ * Bind the secret store to the local store. A mismatch between the two is `RECOVERY_REQUIRED`
+ * and is resolved by device replacement, never by inventing counters.
+ */
+export async function openStore(store: Store, secrets: SecretStore, accountName: string): Promise<OpenedState> {
+  const stage = "openStore";
+  const [accountSeed, instanceId] = await Promise.all([secrets.get("accountSeed"), secrets.get("instanceId")]);
+  const meta = await store.read((tx) => tx.get("meta", META));
+  if (!accountSeed || !instanceId) {
+    if (meta) throw new KavachError("RECOVERY_REQUIRED", stage, "store present but secrets missing");
+    return { kind: "fresh" };
+  }
+  const account = openAccount(accountName, accountSeed);
+  if (!meta) return { kind: "initializing", account };
+  if (meta.instanceId !== toHex(instanceId) || meta.identityId !== toHex(account.identityId) || meta.accountName !== accountName || meta.schema !== 1) {
+    throw new KavachError("RECOVERY_REQUIRED", stage, "store header does not match the secret store");
+  }
+  if (meta.state === "INITIALIZING") return { kind: "initializing", account };
+  return { kind: meta.state, meta, account };
+}
+
+// T1 ----------------------------------------------------------------------------------------------
+
+/** T1a: roots into the secret store. Idempotent for the same values. */
+export async function t1Secrets(secrets: SecretStore, roots: { accountSeed: Uint8Array; deviceSeed: Uint8Array; recoveryKey: Uint8Array; instanceId: Uint8Array }): Promise<void> {
+  await secrets.set("accountSeed", roots.accountSeed);
+  await secrets.set("deviceSeed", roots.deviceSeed);
+  await secrets.set("recoveryKey", roots.recoveryKey);
+  await secrets.set("instanceId", roots.instanceId);
+}
+
+/** T1b: the store header with the INITIALIZING marker, the own pin and the stream state. */
+export function t1Header(tx: Tx, input: { account: OwnAccount; device: DeviceKeys; certificate: Uint8Array; instanceId: Uint8Array; generation: bigint }): void {
+  const doc = expectType<AccountDevice>(parseDocument(input.certificate), DocumentType.AccountDevice, "t1");
+  const pin = pinFromCertificate(doc);
+  if (!equalBytes(pin.identityId, input.account.identityId)) throw new KavachError("MALFORMED", "t1", "certificate is not for this account");
+  tx.put("meta", META, {
+    schema: 1,
+    historyIndex: 1,
+    newest: 1,
+    instanceId: toHex(input.instanceId),
+    accountName: input.account.accountName,
+    identityId: toHex(input.account.identityId),
+    certificateHash: toHex(pin.certificateHash),
+    state: "INITIALIZING"
+  });
+  tx.put("self", SELF, {
+    generation: big(input.generation),
+    deviceId: toHex(input.device.deviceId),
+    certificate: toHex(input.certificate),
+    certificateHash: toHex(pin.certificateHash),
+    streamId: toHex(pin.streamId)
+  });
+  tx.put("pins", toHex(pin.identityId), pinToRow(pin));
+  tx.put("certificates", toHex(pin.certificateHash), {
+    identityId: toHex(pin.identityId),
+    certificateHash: toHex(pin.certificateHash),
+    signingKey: toHex(pin.signingKey),
+    boxKey: toHex(pin.boxKey),
+    streamId: toHex(pin.streamId),
+    generation: big(input.generation),
+    wire: toHex(input.certificate),
+    current: true
+  });
+  tx.put("stream", STREAM, { highestCommittedEpoch: 0, activeEpoch: undefined, pendingEpoch: undefined });
+  tx.put("revision", REVISION, revisionToRow(initialRevisionState, undefined));
+}
+
+/** T1c: ACTIVE once the certificate is durable at the host. */
+export function t1Activate(tx: Tx): void {
+  const meta = tx.get("meta", META);
+  if (!meta) throw new KavachError("STORAGE_FAILURE", "t1", "no header");
+  tx.put("meta", META, { ...meta, state: "ACTIVE" });
+}
+
+// T2 ----------------------------------------------------------------------------------------------
+
+/** T2: the exact replacement certificate and vault bytes prepared for activation. */
+export function t2PrepareActivation(tx: Tx, row: ActivationRow): void {
+  tx.put("activation", "pending", row);
+  const meta = tx.get("meta", META);
+  if (meta) tx.put("meta", META, { ...meta, state: "ACTIVATION_PENDING" });
+}
+
+// T3 ----------------------------------------------------------------------------------------------
+
+export interface ChangeResult {
+  readonly changed: boolean;
+  readonly desiredRevision: bigint;
+  readonly cancelled: readonly string[];
+}
+
+/**
+ * T3: a verified circle or device change. Bumps the desired revision, invalidates the active
+ * epoch, burns its counters and cancels queued (not yet handed off) outbox rows sealed under the
+ * obsolete revision. Pauses with `rotation`.
+ */
+export function t3ApplyChange(tx: Tx, event: AudienceEvent): ChangeResult {
+  const row = tx.get("revision", REVISION);
+  const state = row ? rowToRevision(row) : initialRevisionState;
+  const { state: next, changed } = applyAudienceEvent(state, event);
+  if (!changed) return { changed: false, desiredRevision: state.desiredRevision, cancelled: [] };
+  tx.put("revision", REVISION, revisionToRow(next, "rotation"));
+  const stream = tx.get("stream", STREAM);
+  if (stream?.activeEpoch !== undefined) {
+    const active = tx.get("epochs", String(stream.activeEpoch));
+    if (active) tx.put("epochs", String(stream.activeEpoch), { ...active, status: "obsolete" });
+    tx.put("stream", STREAM, { ...stream, activeEpoch: undefined });
+  }
+  const cancelled: string[] = [];
+  for (const [key, out] of tx.list("outbox")) {
+    if (out.status === "queued" && unbig(out.desiredRevision) < next.desiredRevision) {
+      tx.put("outbox", key, { ...out, wire: "", status: "cancelled", reason: "rotation" });
+      cancelled.push(key);
+    }
+  }
+  return { changed: true, desiredRevision: next.desiredRevision, cancelled };
+}
+
+/**
+ * T3c: one circle row change with its bookkeeping. The row is stored, the audience event it
+ * implies (if any) rotates the sending epoch, and the vault is marked so the backup follows the
+ * rows. Every circle write except the restore from the vault itself goes through here.
+ */
+export function t3Circle(tx: Tx, row: CircleRow, event?: AudienceEvent): ChangeResult {
+  tx.put("circles", row.circleId, row);
+  t9MarkVault(tx);
+  return event ? t3ApplyChange(tx, event) : { changed: false, desiredRevision: currentRevision(tx), cancelled: [] };
+}
+
+export function currentRevision(tx: Pick<Tx, "get">): bigint {
+  const row = tx.get("revision", REVISION);
+  return row ? unbig(row.desiredRevision) : 1n;
+}
+
+// T4 and T5 ---------------------------------------------------------------------------------------
+
+/** T4: the exact manifest, wraps, key and audience checkpoint of a prepared epoch. One unresolved epoch per stream. */
+export function t4PersistPrepared(tx: Tx, prepared: PreparedEpoch): void {
+  const stream = tx.get("stream", STREAM) ?? { highestCommittedEpoch: 0, activeEpoch: undefined, pendingEpoch: undefined };
+  // Never overwrite an unresolved epoch, even at the same number: a second preparation carries a
+  // different key, and publishing both is an equivocation against ourselves.
+  if (stream.pendingEpoch !== undefined) throw new KavachError("ROTATION_REQUIRED", "t4", "an epoch is already unresolved");
+  if (prepared.epoch !== stream.highestCommittedEpoch + 1) throw new KavachError("MALFORMED", "t4", "epoch must be highestCommitted + 1");
+  tx.put("epochs", String(prepared.epoch), preparedToRow(prepared));
+  tx.put("stream", STREAM, { ...stream, pendingEpoch: prepared.epoch });
+}
+
+export type PublishRecord = "PROMOTED" | "OBSOLETE";
+
+/** T5: a committed publication. Promotion is conditional on the revision and the exact audience. */
+export function t5Committed(tx: Tx, epoch: number, currentAudienceKey: string): PublishRecord {
+  const stream = tx.get("stream", STREAM);
+  const row = tx.get("epochs", String(epoch));
+  if (!stream || !row) throw new KavachError("STORAGE_FAILURE", "t5", "unknown epoch");
+  // Idempotent: two contexts can both learn of one publication. The second must not reset a
+  // counter the first already started allocating from.
+  if (row.status === "active") return "PROMOTED";
+  if (row.status === "obsolete" || row.status === "retired") return "OBSOLETE";
+  const outcome = promote(rowToPrepared(row), currentRevision(tx), currentAudienceKey);
+  const revision = tx.get("revision", REVISION);
+  if (outcome === "PROMOTED") {
+    tx.put("epochs", String(epoch), { ...row, status: "active", nextCounter: 0 });
+    tx.put("stream", STREAM, { highestCommittedEpoch: Math.max(stream.highestCommittedEpoch, epoch), activeEpoch: epoch, pendingEpoch: undefined });
+    // A promoted epoch resolved whatever paused sending: the rotation, the missing certificate,
+    // or the audience limit. The sync pause belongs to the host and stays.
+    if (revision?.paused && revision.paused !== "sync") tx.put("revision", REVISION, { ...revision, paused: undefined });
+  } else {
+    tx.put("epochs", String(epoch), { ...row, status: "obsolete" });
+    tx.put("stream", STREAM, { ...stream, highestCommittedEpoch: Math.max(stream.highestCommittedEpoch, epoch), pendingEpoch: undefined });
+  }
+  return outcome;
+}
+
+// T8 and T9 ---------------------------------------------------------------------------------------
+
+/** T8: the owner's successor snapshot, kept until the host confirms it. */
+export function t8OwnerSnapshot(tx: Tx, circleId: Uint8Array, snapshot: Uint8Array, revision: bigint, close = false): void {
+  const key = toHex(circleId);
+  const row = tx.get("circles", key);
+  if (!row) throw new KavachError("STORAGE_FAILURE", "t8", "unknown circle");
+  tx.put("circles", key, { ...row, pending: { snapshot: toHex(snapshot), revision: big(revision), ...(close ? { close: true } : {}) } });
+}
+
+/** T9: a vault update prepared for publication (or confirmed). */
+export function t9Vault(tx: Tx, row: VaultRow): void {
+  tx.put("vault", VAULT, row);
+}
+
+/** T9 marker: the circle rows changed in this transaction, so the vault has to be derived from them again. */
+export function t9MarkVault(tx: Tx): void {
+  const row = tx.get("vault", VAULT);
+  if (row && !row.dirty) tx.put("vault", VAULT, { ...row, dirty: true });
+}
+
+/** Own identity id from the header, for callers that only hold a transaction. */
+export function selfIdentity(tx: Pick<Tx, "get">, accountName: string, accountKey: Uint8Array): Uint8Array {
+  const meta = tx.get("meta", META);
+  const iid = identityId(accountName, accountKey);
+  if (meta && meta.identityId !== toHex(iid)) throw new KavachError("RECOVERY_REQUIRED", "selfIdentity");
+  return iid;
+}