implement the secure reset generation state machine

@@ -0,0 +1,385 @@1+// The §11 secure-reset contract: the durable generation record, the six states,2+// create-on-miss refusal, archival by generation, crash recovery at every step,3+// and the sync gate. Runs entirely against an in-memory io — no Chrome, no4+// vault, no crypto.5+6+import { describe, expect, it } from "vitest";7+import {8+  GENERATION_UNKNOWN,9+  LEGACY_ACTIVE,10+  REPAIRING,11+  RESET_CONFIRMED,12+  RESET_REQUIRED,13+  V2_ACTIVE,14+  V2_ANCHOR,15+  assertSyncAllowed,16+  confirmSecureReset,17+  decodeGeneration,18+  encodeGeneration,19+  enterResetRequired,20+  isPostReset,21+  mintDecision,22+  onDirectV2PairingEstablished,23+  resolveGeneration,24+  type ResetResult,25+  type SyncGeneration,26+  type SyncGenerationBlob,27+  type SyncGenerationIo,28+} from "./sync-generation";29+30+class CrashAt extends Error {}31+32+class FakeGenerationIo implements SyncGenerationIo {33+  blob: unknown = null;34+  pairedDevices = false;35+  revocations = false;36+  pendingHolders = false;37+  legacyRouteMaterial = false;38+39+  /** Storage that refuses the write, to model a generation that cannot land. */40+  failWrites = false;41+  failArchive = false;42+  failClear = false;43+  failIdentity = false;44+45+  /** Simulated process death: the checkpoint with this name throws. */46+  crashAt: string | null = null;47+48+  archiveRef: string | null = null;49+  archiveCount = 0;50+  cleared = false;51+  identityMints = 0;52+  deviceId = "anchor-device";53+54+  /** The order the reset actually touched storage. */55+  readonly calls: string[] = [];56+57+  get record(): SyncGeneration | null {58+    return decodeGeneration(this.blob)?.active ?? null;59+  }60+61+  async readBlob(): Promise<unknown> {62+    return this.blob;63+  }64+65+  async writeBlob(blob: SyncGenerationBlob): Promise<boolean> {66+    if (this.failWrites) return false;67+    this.blob = JSON.parse(encodeGeneration(blob)) as unknown;68+    return true;69+  }70+71+  async hasPairedDevices(): Promise<boolean> {72+    return this.pairedDevices;73+  }74+75+  async hasRevocations(): Promise<boolean> {76+    return this.revocations;77+  }78+79+  async hasPendingHolders(): Promise<boolean> {80+    return this.pendingHolders;81+  }82+83+  async hasLegacyRouteMaterial(): Promise<boolean> {84+    return this.legacyRouteMaterial;85+  }86+87+  async archiveLegacyState(generation: number): Promise<string | null> {88+    if (this.failArchive) return null;89+    this.archiveCount += 1;90+    this.archiveRef = `peach_sync_archive_g${generation}_v1`;91+    this.calls.push(`archive:${generation}`);92+    return this.archiveRef;93+  }94+95+  async clearLegacyTrustState(): Promise<boolean> {96+    if (this.failClear) return false;97+    this.cleared = true;98+    this.pairedDevices = false;99+    this.revocations = false;100+    this.pendingHolders = false;101+    this.legacyRouteMaterial = false;102+    this.calls.push("clear");103+    return true;104+  }105+106+  async ensureV2Identity(): Promise<boolean> {107+    if (this.failIdentity) return false;108+    this.identityMints += 1;109+    this.calls.push("identity");110+    return true;111+  }112+113+  async getDeviceId(): Promise<string> {114+    return this.deviceId;115+  }116+117+  reset(nowMs = 1_000): Promise<ResetResult> {118+    return confirmSecureReset(this, {119+      nowMs,120+      checkpoint: (name) => {121+        if (name === this.crashAt) throw new CrashAt(name);122+      },123+    });124+  }125+}126+127+const CHECKPOINTS = [128+  "before-confirmed",129+  "before-archive",130+  "after-archive",131+  "before-clear",132+  "after-clear",133+  "before-identity",134+  "after-identity",135+  "before-generation-write",136+  "after-generation-write",137+];138+139+describe("sync generation — derived state", () => {140+  it("derives V2_ACTIVE at generation 2 for a fresh install, and persists it", async () => {141+    const io = new FakeGenerationIo();142+    const record = await resolveGeneration(io, 1_000);143+    expect(record.state).toBe(V2_ACTIVE);144+    expect(record.generation).toBe(2);145+    expect(io.record).toEqual(record);146+  });147+148+  it("derives LEGACY_ACTIVE at generation 1 when any trust state is present", async () => {149+    const io = new FakeGenerationIo();150+    io.pairedDevices = true;151+    const record = await resolveGeneration(io, 1_000);152+    expect(record.state).toBe(LEGACY_ACTIVE);153+    expect(record.generation).toBe(1);154+  });155+156+  it("resolves an unreadable record to UNKNOWN rather than to a generation", async () => {157+    const io = new FakeGenerationIo();158+    io.blob = "{ not json";159+    expect((await resolveGeneration(io, 1_000)).state).toBe(GENERATION_UNKNOWN);160+    expect(await assertSyncAllowed(io, 1_000)).toBe("sync_generation_unknown");161+  });162+163+  it("refuses a record of another schema instead of misreading it", async () => {164+    // The rollback case: a build that does not know the generation must not165+    // treat v2 state as legacy trust.166+    const io = new FakeGenerationIo();167+    io.blob = {168+      schemaVersion: 99,169+      active: { schemaVersion: 99, generation: 7, state: V2_ACTIVE, createdAt: 1 },170+    };171+    expect(await assertSyncAllowed(io, 1_000)).toBe("sync_generation_unknown");172+  });173+174+  it("refuses an unrecognised state instead of guessing", async () => {175+    const io = new FakeGenerationIo();176+    io.blob = {177+      schemaVersion: 1,178+      active: { schemaVersion: 1, generation: 1, state: "WOBBLING", createdAt: 1 },179+    };180+    expect(await assertSyncAllowed(io, 1_000)).toBe("sync_generation_unknown");181+  });182+183+  it("does not trust a derived record that could not be persisted", async () => {184+    const io = new FakeGenerationIo();185+    io.pairedDevices = true;186+    io.failWrites = true;187+    expect((await resolveGeneration(io, 1_000)).state).toBe(GENERATION_UNKNOWN);188+    expect(await assertSyncAllowed(io, 1_000)).toBe("sync_generation_unknown");189+  });190+});191+192+describe("sync generation — create-on-miss refusal (§11.5)", () => {193+  it("refuses to mint over every class of trust state", async () => {194+    const classes: Array<[string, (io: FakeGenerationIo) => void]> = [195+      ["paired device", (io) => (io.pairedDevices = true)],196+      ["revocation", (io) => (io.revocations = true)],197+      ["pending holder", (io) => (io.pendingHolders = true)],198+      ["legacy route material", (io) => (io.legacyRouteMaterial = true)],199+    ];200+    for (const [label, configure] of classes) {201+      const io = new FakeGenerationIo();202+      configure(io);203+      expect(await mintDecision(io, 1_000), label).toBe("REFUSE_RESET_REQUIRED");204+      expect(io.record?.state, label).toBe(RESET_REQUIRED);205+      expect(io.identityMints, label).toBe(0);206+      expect(await assertSyncAllowed(io, 1_000), label).toBe("reset_required");207+    }208+  });209+210+  it("mints only on a genuinely fresh installation", async () => {211+    const io = new FakeGenerationIo();212+    expect(await mintDecision(io, 1_000)).toBe("MINT");213+    expect(io.record).toBeNull();214+  });215+});216+217+describe("sync generation — the reset", () => {218+  it("archives, clears, mints, then flips the pointer — in that order", async () => {219+    const io = new FakeGenerationIo();220+    io.pairedDevices = true;221+    io.revocations = true;222+223+    expect(await io.reset()).toBe("V2_ANCHOR");224+    expect(io.calls).toEqual(["archive:1", "clear", "identity"]);225+    expect(io.record).toMatchObject({226+      state: V2_ANCHOR,227+      generation: 2,228+      anchorDeviceId: "anchor-device",229+      legacyArchiveRef: "peach_sync_archive_g1_v1",230+    });231+    expect(io.cleared).toBe(true);232+  });233+234+  it("does not retire the v2 generation or mint twice when repeated", async () => {235+    const io = new FakeGenerationIo();236+    io.pairedDevices = true;237+    await io.reset();238+    const firstArchive = io.record?.legacyArchiveRef;239+240+    expect(await io.reset()).toBe("reset_not_completed");241+    expect(io.record?.legacyArchiveRef).toBe(firstArchive);242+    expect(io.identityMints).toBe(1);243+  });244+245+  it("stays in RESET_CONFIRMED and reports the failure when a step fails", async () => {246+    for (const configure of [247+      (io: FakeGenerationIo) => (io.failArchive = true),248+      (io: FakeGenerationIo) => (io.failClear = true),249+      (io: FakeGenerationIo) => (io.failIdentity = true),250+      (io: FakeGenerationIo) => (io.failWrites = true),251+    ]) {252+      const io = new FakeGenerationIo();253+      io.pairedDevices = true;254+      configure(io);255+      expect(await io.reset()).toBe("reset_not_completed");256+      expect(io.record?.state === RESET_CONFIRMED || io.record === null).toBe(true);257+    }258+  });259+});260+261+describe("sync generation — crash injection (§11.8)", () => {262+  it("leaves the archive durable and the retry reaches V2_ANCHOR from any crash point", async () => {263+    for (const name of CHECKPOINTS) {264+      const io = new FakeGenerationIo();265+      io.pairedDevices = true;266+      io.crashAt = name;267+268+      await expect(io.reset()).rejects.toThrow(CrashAt);269+270+      // Never a wrong outcome: nothing retired yet, mid-flight, or committed.271+      const state = io.record?.state;272+      expect([LEGACY_ACTIVE, RESET_CONFIRMED, V2_ANCHOR], name).toContain(state);273+      // Trust is never cleared without an archive first.274+      expect(io.cleared && io.archiveCount === 0, `${name} cleared without an archive`).toBe(false);275+276+      io.crashAt = null;277+      await io.reset();278+      expect(io.record?.state, `retry after ${name}`).toBe(V2_ANCHOR);279+      expect(io.record?.generation, `retry after ${name}`).toBe(2);280+      expect(io.archiveRef).not.toBeNull();281+    }282+  });283+284+  it("blocks sync before the pointer flip and allows it after", async () => {285+    const before = new FakeGenerationIo();286+    before.pairedDevices = true;287+    before.crashAt = "before-generation-write";288+    await expect(before.reset()).rejects.toThrow(CrashAt);289+    expect(before.record?.state).toBe(RESET_CONFIRMED);290+    expect(await assertSyncAllowed(before, 1_000)).toBe("reset_required");291+292+    const after = new FakeGenerationIo();293+    after.pairedDevices = true;294+    after.crashAt = "after-generation-write";295+    await expect(after.reset()).rejects.toThrow(CrashAt);296+    expect(after.record?.state).toBe(V2_ANCHOR);297+    expect(await assertSyncAllowed(after, 1_000)).toBe("allowed");298+    expect(after.archiveRef).not.toBeNull();299+    expect(after.identityMints).toBe(1);300+  });301+302+  it("loses nothing when the crash lands after the archive but before the clear", async () => {303+    const io = new FakeGenerationIo();304+    io.pairedDevices = true;305+    io.revocations = true;306+    io.crashAt = "before-clear";307+308+    await expect(io.reset()).rejects.toThrow(CrashAt);309+310+    expect(io.archiveCount).toBe(1);311+    expect(io.cleared).toBe(false);312+    expect(io.pairedDevices).toBe(true);313+  });314+});315+316+describe("sync generation — the sync gate (§7)", () => {317+  it("allows a legacy device to sync before it resets", async () => {318+    const io = new FakeGenerationIo();319+    io.pairedDevices = true;320+    expect(await assertSyncAllowed(io, 1_000)).toBe("allowed");321+    expect(await isPostReset(io, 1_000)).toBe(false);322+  });323+324+  it("allows a device that has already reset to sync and pair again", async () => {325+    const io = new FakeGenerationIo();326+    io.pairedDevices = true;327+    await io.reset();328+    expect(await assertSyncAllowed(io, 1_000)).toBe("allowed");329+    expect(await isPostReset(io, 1_000)).toBe(true);330+  });331+332+  it("blocks sync from RESET_REQUIRED and never walks a reset device backwards", async () => {333+    const legacy = new FakeGenerationIo();334+    legacy.pairedDevices = true;335+    await enterResetRequired(legacy, 1_000);336+    expect(await assertSyncAllowed(legacy, 1_000)).toBe("reset_required");337+338+    const reset = new FakeGenerationIo();339+    reset.pairedDevices = true;340+    await reset.reset();341+    await enterResetRequired(reset, 2_000);342+    expect(reset.record?.state).toBe(V2_ANCHOR);343+  });344+});345+346+describe("sync generation — repair progression (§11.3)", () => {347+  it("is REPAIRING until a direct peer exists, then V2_ACTIVE", async () => {348+    const io = new FakeGenerationIo();349+    io.pairedDevices = true;350+    await io.reset();351+352+    await onDirectV2PairingEstablished(io, false, 2_000);353+    expect(io.record?.state).toBe(REPAIRING);354+    expect(await isPostReset(io, 2_000)).toBe(true);355+356+    await onDirectV2PairingEstablished(io, true, 3_000);357+    expect(io.record?.state).toBe(V2_ACTIVE);358+  });359+360+  it("never disturbs a device that never reset", async () => {361+    const io = new FakeGenerationIo();362+    io.pairedDevices = true;363+    await onDirectV2PairingEstablished(io, true, 2_000);364+    expect(io.record?.state).toBe(LEGACY_ACTIVE);365+  });366+});367+368+describe("sync generation — §15.4: the reset retires a generation, it does not rotate the root", () => {369+  it("reaches storage only through archive, clear and identity, in that order", async () => {370+    const io = new FakeGenerationIo();371+    io.pairedDevices = true;372+    io.revocations = true;373+    io.legacyRouteMaterial = true;374+375+    expect(await io.reset()).toBe("V2_ANCHOR");376+377+    // The io is the whole surface the reset can reach. It carries no root key,378+    // no recovery material, and no vault-id parameter, so no rotation is379+    // possible by construction; what is worth pinning is the order that makes380+    // the archive safe.381+    expect(io.calls).toEqual(["archive:1", "clear", "identity"]);382+    expect(io.record?.legacyArchiveRef).toBe("peach_sync_archive_g1_v1");383+    expect(io.record?.generation).toBe(2);384+  });385+});

@@ -0,0 +1,421 @@1+// The durable Sync-generation record and its state machine (protocol §11).2+//3+// One record per installation, under a key no legacy build knows, so an older4+// build cannot overwrite it and a fresh install can tell itself apart from an5+// install that merely lost its identity. A missing or corrupt identity over any6+// existing trust is a reset condition, never a silent re-mint.7+//8+// The record carries no secret, so this module reads and writes it while the9+// vault is locked. Everything else it touches is injected through10+// [SyncGenerationIo], which keeps every transition — and every crash point11+// inside one — testable without Chrome.12+13+import { storageGet, storageSet } from "../shared/storage";14+import { PAIR_SECRETS_KEY, SESSION_PAIR_SECRETS_KEY } from "./pair-secrets";15+import {16+  PENDING_ADOPTION_HOLDER_KEY,17+  PENDING_ADOPTION_IDENTITY_KEY,18+} from "./pending-adoption-holder";19+import { REGISTRY_KEY, REVOCATIONS_KEY, listPairedDevices } from "./paired-devices";20+21+export const GENERATION_KEY = "peach_sync_generation_v1";22+23+const SCHEMA_VERSION = 1;24+const LEGACY_GENERATION = 1;25+const V2_GENERATION = 2;26+27+export const LEGACY_ACTIVE = "LEGACY_ACTIVE";28+export const RESET_REQUIRED = "RESET_REQUIRED";29+export const RESET_CONFIRMED = "RESET_CONFIRMED";30+export const V2_ANCHOR = "V2_ANCHOR";31+export const REPAIRING = "REPAIRING";32+export const V2_ACTIVE = "V2_ACTIVE";33+34+/** No record could be read or derived. Refuses sync rather than guessing. */35+export const GENERATION_UNKNOWN = "UNKNOWN";36+37+export type KnownGenerationState =38+  | typeof LEGACY_ACTIVE39+  | typeof RESET_REQUIRED40+  | typeof RESET_CONFIRMED41+  | typeof V2_ANCHOR42+  | typeof REPAIRING43+  | typeof V2_ACTIVE;44+45+export type GenerationState = KnownGenerationState | typeof GENERATION_UNKNOWN;46+47+export type SyncGeneration = {48+  schemaVersion: number;49+  generation: number;50+  state: GenerationState;51+  anchorDeviceId?: string;52+  legacyArchiveRef?: string;53+  createdAt: number;54+};55+56+/**57+ * `previous` is retained so a rewrite of the active record can be validated58+ * against what it replaces, and so a crash on either side of that write leaves59+ * a recoverable record (§11.2, seal before switch).60+ */61+export type SyncGenerationBlob = {62+  schemaVersion: number;63+  active: SyncGeneration;64+  previous?: SyncGeneration;65+};66+67+export type SyncDecision = "allowed" | "reset_required" | "sync_generation_unknown";68+69+export type ResetResult = "V2_ANCHOR" | "reset_not_completed";70+71+/**72+ * The storage boundary. The trust probe is split per class so a test can assert73+ * the refusal for each one, and archival and clearing are separate steps so a74+ * crash between them is injectable.75+ */76+export interface SyncGenerationIo {77+  readBlob(): Promise<unknown>;78+  writeBlob(blob: SyncGenerationBlob): Promise<boolean>;79+  hasPairedDevices(): Promise<boolean>;80+  hasRevocations(): Promise<boolean>;81+  hasPendingHolders(): Promise<boolean>;82+  hasLegacyRouteMaterial(): Promise<boolean>;83+  archiveLegacyState(generation: number): Promise<string | null>;84+  clearLegacyTrustState(): Promise<boolean>;85+  ensureV2Identity(): Promise<boolean>;86+  getDeviceId(): Promise<string>;87+}88+89+const STATE_NAMES: Record<string, true> = {90+  LEGACY_ACTIVE: true,91+  RESET_REQUIRED: true,92+  RESET_CONFIRMED: true,93+  V2_ANCHOR: true,94+  REPAIRING: true,95+  V2_ACTIVE: true,96+};97+98+export function isGenerationState(value: unknown): value is KnownGenerationState {99+  return typeof value === "string" && STATE_NAMES[value] === true;100+}101+102+export function encodeGeneration(blob: SyncGenerationBlob): string {103+  return JSON.stringify(blob);104+}105+106+/**107+ * A record this build cannot read is not a record: another schema, an108+ * unrecognised state, or a nonsensical generation all resolve to null, so the109+ * caller refuses rather than misreading a newer generation as legacy trust.110+ */111+export function decodeGeneration(value: unknown): SyncGenerationBlob | null {112+  try {113+    const parsed: unknown = typeof value === "string" ? JSON.parse(value) : value;114+    if (!parsed || typeof parsed !== "object") return null;115+    const blob = parsed as Partial<SyncGenerationBlob>;116+    if (blob.schemaVersion !== SCHEMA_VERSION) return null;117+    const active = blob.active as Partial<SyncGeneration> | undefined;118+    if (!active || !isGenerationState(active.state)) return null;119+    if (!Number.isInteger(active.generation)) return null;120+    if ((active.generation ?? 0) < LEGACY_GENERATION) return null;121+    return blob as SyncGenerationBlob;122+  } catch {123+    return null;124+  }125+}126+127+export async function hasLegacyTrustState(io: SyncGenerationIo): Promise<boolean> {128+  const [paired, revocations, pending, route] = await Promise.all([129+    io.hasPairedDevices(),130+    io.hasRevocations(),131+    io.hasPendingHolders(),132+    io.hasLegacyRouteMaterial(),133+  ]);134+  return paired || revocations || pending || route;135+}136+137+/**138+ * Read the persisted record, or derive one when none has ever been written. A139+ * derived record that cannot be persisted is not trusted: the caller must not140+ * act on a generation this installation may not actually hold.141+ */142+export async function resolveGeneration(143+  io: SyncGenerationIo,144+  nowMs: number = Date.now(),145+): Promise<SyncGeneration> {146+  const unknown: SyncGeneration = {147+    schemaVersion: SCHEMA_VERSION,148+    generation: LEGACY_GENERATION,149+    state: GENERATION_UNKNOWN,150+    createdAt: nowMs,151+  };152+  const raw = await io.readBlob();153+  if (raw !== null && raw !== undefined) {154+    return decodeGeneration(raw)?.active ?? unknown;155+  }156+  const hasTrust = await hasLegacyTrustState(io);157+  const derived: SyncGeneration = {158+    schemaVersion: SCHEMA_VERSION,159+    generation: hasTrust ? LEGACY_GENERATION : V2_GENERATION,160+    state: hasTrust ? LEGACY_ACTIVE : V2_ACTIVE,161+    createdAt: nowMs,162+  };163+  return (await io.writeBlob({ schemaVersion: SCHEMA_VERSION, active: derived }))164+    ? derived165+    : unknown;166+}167+168+/**169+ * Enter the state that blocks sync and states the migration. Reached by the170+ * user asking for a reset, and by the create-on-miss refusal. Idempotent, and171+ * never moves a device that has already reset back into the legacy generation.172+ */173+export async function enterResetRequired(174+  io: SyncGenerationIo,175+  nowMs: number = Date.now(),176+): Promise<SyncGeneration> {177+  const current = await resolveGeneration(io, nowMs);178+  if (current.state !== LEGACY_ACTIVE && current.state !== RESET_REQUIRED) return current;179+  const next: SyncGeneration = { ...current, state: RESET_REQUIRED };180+  await io.writeBlob({ schemaVersion: SCHEMA_VERSION, active: next, previous: current });181+  return next;182+}183+184+/**185+ * Archive the legacy generation, mint the v2 identity, then flip the pointer —186+ * in that order, so every crash point leaves either a recoverable187+ * RESET_CONFIRMED or a committed V2_ANCHOR, and never a lost archive (§11.3).188+ *189+ * The caller has already confirmed the master password. `checkpoint` fires190+ * immediately before each step that can fail; a test throws from it to inject a191+ * crash at exactly that point.192+ */193+export async function confirmSecureReset(194+  io: SyncGenerationIo,195+  opts: { nowMs: number; checkpoint?: (name: string) => void },196+): Promise<ResetResult> {197+  const { nowMs } = opts;198+  const checkpoint = opts.checkpoint ?? (() => {});199+  const current = await resolveGeneration(io, nowMs);200+  if (201+    current.state !== LEGACY_ACTIVE &&202+    current.state !== RESET_REQUIRED &&203+    current.state !== RESET_CONFIRMED204+  ) {205+    return "reset_not_completed";206+  }207+208+  const persist = (state: SyncGeneration): Promise<boolean> =>209+    io.writeBlob({ schemaVersion: SCHEMA_VERSION, active: state, previous: current });210+211+  checkpoint("before-confirmed");212+  if (!(await persist({ ...current, state: RESET_CONFIRMED }))) return "reset_not_completed";213+214+  checkpoint("before-archive");215+  const archiveRef = await io.archiveLegacyState(current.generation);216+  if (!archiveRef) return "reset_not_completed";217+  checkpoint("after-archive");218+219+  checkpoint("before-clear");220+  if (!(await io.clearLegacyTrustState())) return "reset_not_completed";221+  checkpoint("after-clear");222+223+  checkpoint("before-identity");224+  if (!(await io.ensureV2Identity())) return "reset_not_completed";225+  checkpoint("after-identity");226+227+  // The identity exists by now; a read failure here is not worth abandoning a228+  // reset whose archive is already durable.229+  const anchorDeviceId = await io.getDeviceId().catch(() => undefined);230+  const next: SyncGeneration = {231+    schemaVersion: SCHEMA_VERSION,232+    generation: current.generation + 1,233+    state: V2_ANCHOR,234+    anchorDeviceId,235+    legacyArchiveRef: archiveRef,236+    createdAt: nowMs,237+  };238+  checkpoint("before-generation-write");239+  if (!(await io.writeBlob({ schemaVersion: SCHEMA_VERSION, active: next, previous: current }))) {240+    return "reset_not_completed";241+  }242+  checkpoint("after-generation-write");243+  return "V2_ANCHOR";244+}245+246+/** An anchored device stops being "not re-paired" once a direct v2 peer exists. */247+export async function onDirectV2PairingEstablished(248+  io: SyncGenerationIo,249+  hasDirectDevice: boolean,250+  nowMs: number = Date.now(),251+): Promise<void> {252+  const current = await resolveGeneration(io, nowMs);253+  if (current.state !== V2_ANCHOR && current.state !== REPAIRING) return;254+  const next: SyncGeneration = { ...current, state: hasDirectDevice ? V2_ACTIVE : REPAIRING };255+  await io256+    .writeBlob({ schemaVersion: SCHEMA_VERSION, active: next, previous: current })257+    .catch(() => false);258+}259+260+/** Consulted before a sync session or an adoption grant is opened. */261+export async function assertSyncAllowed(262+  io: SyncGenerationIo,263+  nowMs: number = Date.now(),264+): Promise<SyncDecision> {265+  const current = await resolveGeneration(io, nowMs);266+  if (current.state === RESET_REQUIRED || current.state === RESET_CONFIRMED) return "reset_required";267+  return isGenerationState(current.state) ? "allowed" : "sync_generation_unknown";268+}269+270+/** True once a reset has retired the legacy generation. */271+export async function isPostReset(272+  io: SyncGenerationIo,273+  nowMs: number = Date.now(),274+): Promise<boolean> {275+  const current = await resolveGeneration(io, nowMs);276+  return current.state === V2_ANCHOR || current.state === REPAIRING || current.state === V2_ACTIVE;277+}278+279+/**280+ * Whether a missing or corrupt identity may be minted (§11.5). A missing281+ * identity is only mintable on a genuinely fresh installation, never over any282+ * trust this device already holds.283+ */284+export async function mintDecision(285+  io: SyncGenerationIo,286+  nowMs: number = Date.now(),287+): Promise<"MINT" | "REFUSE_RESET_REQUIRED"> {288+  if (!(await hasLegacyTrustState(io))) return "MINT";289+  await enterResetRequired(io, nowMs);290+  return "REFUSE_RESET_REQUIRED";291+}292+293+/**294+ * Minting and reading the device identity, supplied by `./device-identity` the295+ * same way `vault.ts` receives its identity hooks. Injecting it keeps this296+ * module free of device-identity and therefore free of an import cycle: the297+ * identity loader is a consumer of the generation state, not the reverse.298+ */299+export type GenerationIdentity = {300+  /** True once a usable current identity exists; may mint at RESET_CONFIRMED. */301+  ensureIdentity(): Promise<boolean>;302+  deviceId(): Promise<string>;303+};304+305+let generationIdentity: GenerationIdentity | null = null;306+307+export function setGenerationIdentity(identity: GenerationIdentity): void {308+  generationIdentity = identity;309+}310+311+function emptyList(value: unknown): boolean {312+  return !Array.isArray(value) || value.length === 0;313+}314+315+function emptyRecord(value: unknown): boolean {316+  return !value || typeof value !== "object" || Object.keys(value as object).length === 0;317+}318+319+export const browserGenerationIo: SyncGenerationIo = {320+  async readBlob() {321+    return (await chrome.storage.local.get(GENERATION_KEY))[GENERATION_KEY];322+  },323+324+  async writeBlob(blob) {325+    const encoded = encodeGeneration(blob);326+    try {327+      await storageSet(GENERATION_KEY, encoded);328+      // Read back rather than trusting the set: a successful write is what329+      // licenses retiring the legacy generation.330+      return (await storageGet(GENERATION_KEY)) === encoded;331+    } catch {332+      return false;333+    }334+  },335+336+  async hasPairedDevices() {337+    return (await listPairedDevices()).length > 0;338+  },339+340+  async hasRevocations() {341+    return !emptyList((await chrome.storage.local.get(REVOCATIONS_KEY))[REVOCATIONS_KEY]);342+  },343+344+  async hasPendingHolders() {345+    const stored = await chrome.storage.local.get([346+      PENDING_ADOPTION_HOLDER_KEY,347+      PENDING_ADOPTION_IDENTITY_KEY,348+    ]);349+    return !!stored[PENDING_ADOPTION_HOLDER_KEY] || !!stored[PENDING_ADOPTION_IDENTITY_KEY];350+  },351+352+  async hasLegacyRouteMaterial() {353+    return !emptyRecord((await chrome.storage.local.get(PAIR_SECRETS_KEY))[PAIR_SECRETS_KEY]);354+  },355+356+  /**357+   * Copy the legacy trust material verbatim into an archive tagged with its358+   * generation. The registry, the ledger and the pair secrets are exactly what359+   * §11.4 retains; the generation is tagged both in the key and in the record,360+   * so a rollback build can tell which generation it is looking at.361+   */362+  async archiveLegacyState(generation) {363+    const ref = `peach_sync_archive_g${generation}_v1`;364+    try {365+      const stored = await chrome.storage.local.get([366+        REGISTRY_KEY,367+        REVOCATIONS_KEY,368+        PENDING_ADOPTION_HOLDER_KEY,369+        PENDING_ADOPTION_IDENTITY_KEY,370+        PAIR_SECRETS_KEY,371+      ]);372+      const archive = {373+        schemaVersion: 1,374+        generation,375+        archivedAt: Date.now(),376+        pairedDevices: stored[REGISTRY_KEY] ?? null,377+        revocations: stored[REVOCATIONS_KEY] ?? null,378+        pendingHolder: stored[PENDING_ADOPTION_HOLDER_KEY] ?? null,379+        pendingIdentity: stored[PENDING_ADOPTION_IDENTITY_KEY] ?? null,380+        pairSecrets: stored[PAIR_SECRETS_KEY] ?? null,381+      };382+      await chrome.storage.local.set({ [ref]: archive });383+      const written = (await chrome.storage.local.get(ref))[ref];384+      return JSON.stringify(written) === JSON.stringify(archive) ? ref : null;385+    } catch {386+      return null;387+    }388+  },389+390+  async clearLegacyTrustState() {391+    try {392+      await chrome.storage.local.remove([393+        REGISTRY_KEY,394+        REVOCATIONS_KEY,395+        PENDING_ADOPTION_HOLDER_KEY,396+        PENDING_ADOPTION_IDENTITY_KEY,397+        PAIR_SECRETS_KEY,398+        SESSION_PAIR_SECRETS_KEY,399+      ]);400+      // Verified rather than assumed: the clear is what licenses the mint.401+      const [paired, revocations, pending, route] = await Promise.all([402+        browserGenerationIo.hasPairedDevices(),403+        browserGenerationIo.hasRevocations(),404+        browserGenerationIo.hasPendingHolders(),405+        browserGenerationIo.hasLegacyRouteMaterial(),406+      ]);407+      return !paired && !revocations && !pending && !route;408+    } catch {409+      return false;410+    }411+  },412+413+  async ensureV2Identity() {414+    return generationIdentity ? generationIdentity.ensureIdentity() : false;415+  },416+417+  async getDeviceId() {418+    if (!generationIdentity) throw new Error("generation_identity_unconfigured");419+    return generationIdentity.deviceId();420+  },421+};