@phosphorco/bb-identity 0.1.0

package/dist/state-controller-runtime.js

@@ -0,0 +1,950 @@
+// @bun
+// model-runtime.ts
+var ID_MAX_LENGTH = 256;
+var ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/;
+function failure(code, message, retry = "never") {
+  return { code, message, retry };
+}
+function ok(value) {
+  return { ok: true, value };
+}
+function err(code, message, retry = "never") {
+  return { ok: false, error: failure(code, message, retry) };
+}
+function isBoundedString(value, maximum = ID_MAX_LENGTH) {
+  return typeof value === "string" && value.length > 0 && value.length <= maximum;
+}
+function idCodec(kind) {
+  return {
+    decode(input) {
+      const valid = kind === "server-session" ? isBoundedString(input, 4096) && !/[\u0000-\u0020\u007f]/.test(input) : isBoundedString(input) && ID_PATTERN.test(input);
+      if (!valid) {
+        return err("invalid-input", `Invalid ${kind} identifier.`);
+      }
+      return ok(input);
+    },
+    encode(value) {
+      return value;
+    }
+  };
+}
+var identityKeyCodec = {
+  decode(input) {
+    if (!isBoundedString(input, 512) || /[\u0000-\u001f\u007f]/.test(input)) {
+      return err("invalid-input", "Invalid identity key.");
+    }
+    return ok(input);
+  },
+  encode(value) {
+    return value;
+  }
+};
+function newOperationId() {
+  const random = globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  return `op-${random}`;
+}
+function newConflictToken() {
+  return `conflict-${globalThis.crypto?.randomUUID?.() ?? Date.now().toString(36)}`;
+}
+
+// state-service-runtime.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function decodeAddress(value) {
+  if (!isRecord(value) || !nonEmpty(value.collection) || !nonEmpty(value.recordId))
+    return err("invalid-input", "Invalid state address.");
+  const instanceId = idCodec("instance").decode(value.instanceId);
+  const pluginId = idCodec("plugin").decode(value.pluginId);
+  const owner = identityKeyCodec.decode(value.owner);
+  return instanceId.ok && pluginId.ok && owner.ok ? ok({ instanceId: instanceId.value, pluginId: pluginId.value, collection: value.collection, recordId: value.recordId, owner: owner.value }) : err("invalid-input", "Invalid state address identifiers.");
+}
+function decodeVersion(value) {
+  return isRecord(value) && nonEmpty(value.epoch) && typeof value.sequence === "number" && Number.isInteger(value.sequence) && value.sequence >= 0 ? ok({ epoch: value.epoch, sequence: value.sequence }) : err("invalid-input", "Invalid state version.");
+}
+function decodeActor(value) {
+  if (value === null)
+    return ok(null);
+  if (!isRecord(value) || !isRecord(value.identity) || !isRecord(value.presentation) || !nonEmpty(value.presentation.displayName) || value.presentation.handle !== null && typeof value.presentation.handle !== "string" || value.presentation.avatarUrl !== null && typeof value.presentation.avatarUrl !== "string" || !["provider-verified", "local-user", "upstream-default", "integration-asserted", "legacy", "machine"].includes(value.evidence)) {
+    return err("invalid-input", "Invalid state editor snapshot.");
+  }
+  const key = identityKeyCodec.decode(value.identity.key);
+  if (!key.ok)
+    return key;
+  const identity = value.identity;
+  const presentation = { displayName: value.presentation.displayName, handle: value.presentation.handle, avatarUrl: value.presentation.avatarUrl };
+  if (identity.kind === "machine") {
+    const instanceId = idCodec("instance").decode(identity.instanceId);
+    if (!instanceId.ok || value.evidence !== "machine" || identity.hostId !== null && (typeof identity.hostId !== "string" || identity.hostId.length === 0 || identity.hostId.length > 512)) {
+      return err("invalid-input", "Invalid machine editor identity.");
+    }
+    return ok({ identity: { kind: "machine", key: key.value, instanceId: instanceId.value, hostId: identity.hostId }, presentation, evidence: "machine" });
+  }
+  if (value.evidence === "machine")
+    return err("invalid-input", "Machine evidence requires a machine identity.");
+  if (identity.kind === "person" && nonEmpty(identity.issuer) && nonEmpty(identity.subject)) {
+    return ok({ identity: { kind: "person", key: key.value, issuer: identity.issuer, subject: identity.subject }, presentation, evidence: value.evidence });
+  }
+  if (identity.kind === "default-user") {
+    const instanceId = idCodec("instance").decode(identity.instanceId);
+    return instanceId.ok ? ok({ identity: { kind: "default-user", key: key.value, instanceId: instanceId.value }, presentation, evidence: value.evidence }) : instanceId;
+  }
+  if (identity.kind === "external") {
+    const pluginId = idCodec("plugin").decode(identity.pluginId);
+    return pluginId.ok && nonEmpty(identity.subject) ? ok({ identity: { kind: "external", key: key.value, pluginId: pluginId.value, subject: identity.subject }, presentation, evidence: value.evidence }) : err("invalid-input", "Invalid external editor identity.");
+  }
+  return err("invalid-input", "Invalid editor identity.");
+}
+function decodeEnvelope(value, codec) {
+  if (!isRecord(value) || typeof value.schemaVersion !== "number" || !Number.isInteger(value.schemaVersion) || value.schemaVersion < 0) {
+    return err("invalid-input", "Invalid state envelope.");
+  }
+  const address = decodeAddress(value.address);
+  const version = decodeVersion(value.version);
+  const decoded = codec.decode(value.value);
+  const editor = decodeActor(value.lastEditedBy);
+  return address.ok && version.ok && decoded.ok && editor.ok ? ok({ address: address.value, version: version.value, schemaVersion: value.schemaVersion, value: decoded.value, lastEditedBy: editor.value }) : err("invalid-input", "Invalid state envelope fields.");
+}
+function decodeRead(value, codec) {
+  if (!isRecord(value) || typeof value.status !== "string")
+    return err("invalid-input", "Invalid state read.");
+  if (value.status === "present") {
+    const envelope = decodeEnvelope(value.envelope, codec);
+    return envelope.ok ? ok({ status: "present", envelope: envelope.value }) : envelope;
+  }
+  if (value.status === "empty") {
+    const address = decodeAddress(value.address);
+    const version = decodeVersion(value.version);
+    return address.ok && version.ok ? ok({ status: "empty", address: address.value, version: version.value }) : err("invalid-input", "Invalid empty state read.");
+  }
+  if (value.status === "migration-required") {
+    const address = decodeAddress(value.address);
+    return address.ok && typeof value.storedSchemaVersion === "number" && Number.isInteger(value.storedSchemaVersion) && value.storedSchemaVersion >= 0 ? ok({ status: "migration-required", address: address.value, storedSchemaVersion: value.storedSchemaVersion }) : err("invalid-input", "Invalid migration-required read.");
+  }
+  return err("invalid-input", "Unknown state read status.");
+}
+function decodeMutation(value, codec) {
+  if (!isRecord(value) || value.kind !== "initialize" && value.kind !== "replace" || !isRecord(value.expected) || typeof value.schemaVersion !== "number" || !Number.isInteger(value.schemaVersion) || value.schemaVersion < 0 || typeof value.localGeneration !== "number" || !Number.isInteger(value.localGeneration) || value.localGeneration < 0) {
+    return err("invalid-input", "Invalid state mutation.");
+  }
+  const address = decodeAddress(value.address);
+  const expectedVersion = decodeVersion(value.expectedVersion);
+  const actor = identityKeyCodec.decode(value.expected.actor);
+  const session = idCodec("server-session").decode(value.expected.session);
+  const ownerSession = idCodec("owner-session").decode(value.ownerSession);
+  const operationId = idCodec("operation").decode(value.operationId);
+  const decoded = codec.decode(value.value);
+  return address.ok && expectedVersion.ok && actor.ok && session.ok && ownerSession.ok && operationId.ok && decoded.ok ? ok({
+    kind: value.kind,
+    address: address.value,
+    expectedVersion: expectedVersion.value,
+    expected: { actor: actor.value, session: session.value },
+    ownerSession: ownerSession.value,
+    localGeneration: value.localGeneration,
+    operationId: operationId.value,
+    schemaVersion: value.schemaVersion,
+    value: decoded.value
+  }) : err("invalid-input", "Invalid state mutation fields.");
+}
+function decodeOutcome(value, codec) {
+  if (!isRecord(value) || typeof value.status !== "string")
+    return err("invalid-input", "Invalid state outcome.");
+  const operationId = idCodec("operation").decode(value.operationId);
+  if (!operationId.ok)
+    return operationId;
+  if (value.status === "saved" || value.status === "unchanged") {
+    const envelope = decodeEnvelope(value.envelope, codec);
+    return envelope.ok ? ok({ status: value.status, envelope: envelope.value, operationId: operationId.value }) : envelope;
+  }
+  if (value.status === "already-initialized" || value.status === "conflict") {
+    const current = decodeRead(value.current, codec);
+    return current.ok ? ok({ status: value.status, current: current.value, operationId: operationId.value }) : current;
+  }
+  return err("invalid-input", "Unknown state outcome status.");
+}
+function decodeSave(value, codec) {
+  if (isRecord(value) && value.status === "indeterminate") {
+    const operationId = idCodec("operation").decode(value.operationId);
+    return operationId.ok ? ok({ status: "indeterminate", operationId: operationId.value }) : operationId;
+  }
+  return decodeOutcome(value, codec);
+}
+function stateAddressKey(address) {
+  return JSON.stringify([address.instanceId, address.pluginId, address.collection, address.recordId, address.owner]);
+}
+function decodeLookup(value, codec) {
+  if (!isRecord(value) || typeof value.status !== "string")
+    return err("invalid-input", "Invalid state lookup.");
+  if (value.status === "final") {
+    const outcome = decodeOutcome(value.outcome, codec);
+    return outcome.ok ? ok({ status: "final", outcome: outcome.value }) : outcome;
+  }
+  if (value.status === "pending")
+    return ok({ status: "pending" });
+  if (value.status === "absent-final" && value.retry === "same-operation-only")
+    return ok({ status: "absent-final", retry: "same-operation-only" });
+  if (value.status === "unknown" && (value.reason === "unsupported" || value.reason === "expired" || value.reason === "unavailable"))
+    return ok({ status: "unknown", reason: value.reason });
+  return err("invalid-input", "Invalid state lookup metadata.");
+}
+function encodeAddress(address) {
+  return { instanceId: address.instanceId, pluginId: address.pluginId, collection: address.collection, recordId: address.recordId, owner: address.owner };
+}
+function encodeVersion(version) {
+  return { epoch: version.epoch, sequence: version.sequence };
+}
+function encodeActor(actor) {
+  return actor === null ? null : { identity: actor.identity, presentation: actor.presentation, evidence: actor.evidence };
+}
+function encodeEnvelope(envelope, codec) {
+  return { address: encodeAddress(envelope.address), version: encodeVersion(envelope.version), schemaVersion: envelope.schemaVersion, value: codec.encode(envelope.value), lastEditedBy: encodeActor(envelope.lastEditedBy) };
+}
+function encodeRead(read, codec) {
+  return read.status === "present" ? { status: "present", envelope: encodeEnvelope(read.envelope, codec) } : read.status === "empty" ? { status: "empty", address: encodeAddress(read.address), version: encodeVersion(read.version) } : read.status === "migration-required" ? { status: "migration-required", address: encodeAddress(read.address), storedSchemaVersion: read.storedSchemaVersion } : (() => {
+    throw new TypeError("Invalid state read status.");
+  })();
+}
+function encodeMutation(mutation, codec) {
+  return { ...mutation, address: encodeAddress(mutation.address), expectedVersion: encodeVersion(mutation.expectedVersion), value: codec.encode(mutation.value) };
+}
+function encodeOutcome(outcome, codec) {
+  if (outcome.status === "saved" || outcome.status === "unchanged") {
+    return { status: outcome.status, envelope: encodeEnvelope(outcome.envelope, codec), operationId: outcome.operationId };
+  }
+  if ("current" in outcome)
+    return { status: outcome.status, current: encodeRead(outcome.current, codec), operationId: outcome.operationId };
+  throw new TypeError("Invalid state outcome.");
+}
+function encodeSave(save, codec) {
+  return save.status === "indeterminate" ? { status: "indeterminate", operationId: save.operationId } : encodeOutcome(save, codec);
+}
+function stateCodecs(value) {
+  return {
+    read: { decode: (input) => decodeRead(input, value), encode: (input) => encodeRead(input, value) },
+    mutation: { decode: (input) => decodeMutation(input, value), encode: (input) => encodeMutation(input, value) },
+    save: { decode: (input) => decodeSave(input, value), encode: (input) => encodeSave(input, value) },
+    invalidation: {
+      decode(input) {
+        if (!isRecord(input))
+          return err("invalid-input", "Invalid state invalidation.");
+        const address = decodeAddress(input.address);
+        const version = decodeVersion(input.version);
+        const operationId = input.operationId === null ? ok(null) : idCodec("operation").decode(input.operationId);
+        return address.ok && version.ok && operationId.ok ? ok({ address: address.value, version: version.value, operationId: operationId.value }) : err("invalid-input", "Invalid state invalidation fields.");
+      },
+      encode: (input) => ({ address: encodeAddress(input.address), version: encodeVersion(input.version), operationId: input.operationId })
+    },
+    lookup: {
+      decode: (input) => decodeLookup(input, value),
+      encode: (input) => input.status === "final" ? { status: "final", outcome: encodeOutcome(input.outcome, value) } : input
+    }
+  };
+}
+
+// state-controller-runtime.ts
+var defaultScheduler = { now: Date.now, schedule(delay, callback) {
+  const timer = setTimeout(callback, delay);
+  return () => clearTimeout(timer);
+} };
+function frozen(value) {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value))
+      frozen(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+function valueClone(codec, value) {
+  const result = codec.decode(structuredClone(codec.encode(value)));
+  if (!result.ok)
+    throw new TypeError(result.error.message);
+  return frozen(result.value);
+}
+function version(read) {
+  return read.status === "present" ? read.envelope.version : read.version;
+}
+function sameVersion(a, b) {
+  return a.status === b.status && version(a).epoch === version(b).epoch && version(a).sequence === version(b).sequence;
+}
+function createIdentityState(options) {
+  const address = frozen({ ...options.address });
+  const expected = frozen({ ...options.expected });
+  const definition = options.definition;
+  const codec = definition.codec;
+  const codecs = stateCodecs(codec);
+  const drafts = options.drafts;
+  const initial = valueClone(codec, definition.initialValue());
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const retryLimit = options.retryLimit ?? 3;
+  const debounce = options.debounceMs ?? 300;
+  if (!Number.isSafeInteger(retryLimit) || retryLimit < 0 || !Number.isFinite(debounce) || debounce < 0)
+    throw new TypeError("Invalid state scheduling limits");
+  let lifecycle = "new";
+  let epoch = 0;
+  let loadId = 0;
+  let localGeneration = 0;
+  let base = null;
+  let desired = null;
+  let blocked = null;
+  let pending = null;
+  let networkActive = false;
+  let acknowledgedGeneration = -1;
+  let activeSave = null;
+  let startWork = null;
+  let activeLoad = null;
+  let timer = null;
+  let subscription = null;
+  let remotePending = false;
+  let remoteSerial = 0;
+  let remoteHint = null;
+  let closing = false;
+  let checkpoint = null;
+  let recoverySource = null;
+  let automaticSuspensions = 0;
+  let automaticEpoch = 0;
+  let persistQueue = Promise.resolve();
+  let persistSerial = 0;
+  const abort = new AbortController;
+  const listeners = new Set;
+  let snapshot = { status: "loading", address };
+  const currentValue = (read) => read.status === "present" ? read.envelope.value : initial;
+  const dirty = () => base !== null && desired !== null && !definition.equal(currentValue(base), desired.value);
+  const needsSave = () => dirty() || base?.status === "empty" && options.initializeEmpty;
+  const active = (captured = epoch) => lifecycle === "active" && captured === epoch;
+  const clearTimer = () => {
+    timer?.();
+    timer = null;
+  };
+  const draft = () => base === null || desired === null ? null : frozen({ formatVersion: 1, key: { address, actor: expected.actor, ownerSession: options.ownerSession }, schemaVersion: definition.schemaVersion, acknowledged: base, desired: desired.value, localGeneration, inFlight: pending?.mutation ?? null });
+  function emit() {
+    if (lifecycle === "detached" || lifecycle === "disposed")
+      snapshot = { status: "detached", address, draft: draft() };
+    else if (blocked)
+      snapshot = { status: "blocked", address, ...blocked, draft: draft() };
+    else if (base && desired)
+      snapshot = { status: "ready", address, ownerSession: options.ownerSession, acknowledged: base, desired: desired.value, dirty: dirty(), saving: networkActive, localGeneration, remotePending };
+    else
+      snapshot = { status: "loading", address };
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {}
+    }
+  }
+  function block(reason, message, conflict2 = null) {
+    clearTimer();
+    blocked = { reason, message, conflict: conflict2 };
+    emit();
+  }
+  function sessionCheck() {
+    if (!active())
+      return err("disposed", "This state controller is no longer active.");
+    const result = options.currentSession();
+    if (!result.ok) {
+      block("identity-unavailable", result.error.message);
+      return result;
+    }
+    const session = result.value;
+    if (session.status !== "ready") {
+      block("identity-unavailable", session.error.message);
+      return { ok: false, error: session.error };
+    }
+    if (session.instanceId !== address.instanceId || session.actor.identity.key !== expected.actor || session.stamp !== expected.session) {
+      block("owner-changed", "The identity session changed.");
+      return err("stale-context", "The identity session changed.", "after-refresh");
+    }
+    return ok(undefined);
+  }
+  async function safe(run) {
+    try {
+      return await run();
+    } catch (error) {
+      return err("unavailable", error instanceof Error ? error.message : "State operation failed.", "after-reconnect");
+    }
+  }
+  function persist(captured = draft()) {
+    if (!drafts)
+      return Promise.resolve(ok(null));
+    if (!captured)
+      return Promise.resolve(ok(null));
+    const capturedEpoch = epoch;
+    const serial = ++persistSerial;
+    const work = persistQueue.then(async () => {
+      const result = await safe(() => drafts.write(captured, checkpoint?.revision ?? null));
+      if (result.ok)
+        checkpoint = result.value;
+      else if (active(capturedEpoch) && serial === persistSerial)
+        block("storage-error", result.error.message);
+      return result;
+    });
+    persistQueue = work.then(() => {
+      return;
+    });
+    return work;
+  }
+  function schedule() {
+    clearTimer();
+    if (!active() || automaticSuspensions || closing || blocked || pending || !needsSave())
+      return;
+    timer = scheduler.schedule(debounce, () => {
+      timer = null;
+      sendNew(true);
+    });
+  }
+  function readClone(read) {
+    const decoded = codecs.read.decode(structuredClone(codecs.read.encode(read)));
+    if (!decoded.ok)
+      return decoded;
+    const value = decoded.value;
+    const returnedAddress = value.status === "present" ? value.envelope.address : value.address;
+    if (stateAddressKey(returnedAddress) !== stateAddressKey(address) || value.status === "present" && value.envelope.schemaVersion !== definition.schemaVersion)
+      return err("incompatible", "State response does not match this resource.");
+    return ok(frozen(value));
+  }
+  async function applyDecision(context, decision) {
+    if (!active() || blocked?.conflict?.token !== context.token)
+      return err("stale-context", "Conflict decision was superseded.");
+    if (decision.kind === "needs-review") {
+      block("conflict", decision.reason, context);
+      return ok(undefined);
+    }
+    if (context.remote.status === "migration-required") {
+      block("migration-required", "State migration is required.");
+      return err("conflict", "State migration is required.");
+    }
+    base = context.remote;
+    desired = { value: valueClone(codec, decision.kind === "rebase" ? decision.value : currentValue(base)) };
+    localGeneration++;
+    blocked = null;
+    emit();
+    const capturedEpoch = epoch;
+    const saved = await persist();
+    if (!saved.ok)
+      return saved;
+    if (active(capturedEpoch))
+      schedule();
+    return ok(undefined);
+  }
+  async function conflict(cause, remote, original) {
+    if (!desired)
+      return err("unavailable", "State has no local value.");
+    const context = frozen({ cause, token: newConflictToken(), ownerSession: options.ownerSession, base: original, local: desired.value, remote });
+    block("conflict", "Remote state conflicts with local intent.", context);
+    try {
+      return await applyDecision(context, options.onConflict(context));
+    } catch (error) {
+      if (blocked?.conflict?.token !== context.token)
+        return err("stale-context", "Conflict decision was superseded.");
+      block("conflict", error instanceof Error ? error.message : "Conflict policy failed.", context);
+      return err("conflict", "Conflict policy failed.");
+    }
+  }
+  async function applyRemote(read, cause) {
+    if (read.status === "migration-required") {
+      block("migration-required", "State migration is required.");
+      return err("conflict", "State migration is required.");
+    }
+    if (pending) {
+      remotePending = true;
+      emit();
+      return ok(undefined);
+    }
+    if (base && version(base).epoch === version(read).epoch && version(read).sequence < version(base).sequence)
+      return ok(undefined);
+    if (base && dirty()) {
+      if (sameVersion(base, read)) {
+        if (!blocked?.conflict)
+          blocked = null;
+        emit();
+        schedule();
+        return ok(undefined);
+      }
+      return conflict(cause, read, base);
+    }
+    base = read;
+    desired = { value: valueClone(codec, currentValue(read)) };
+    blocked = null;
+    emit();
+    schedule();
+    return ok(undefined);
+  }
+  function queueRemote() {
+    if (!active() || activeLoad || pending)
+      return;
+    reload("reconnect");
+  }
+  function reload(cause) {
+    const valid = sessionCheck();
+    if (!valid.ok)
+      return Promise.resolve(valid);
+    const capturedEpoch = epoch;
+    const id = ++loadId;
+    const serial = remoteSerial;
+    remotePending = false;
+    const work = (async () => {
+      const loaded = await safe(() => options.transport.load({ address, expected }, { signal: abort.signal }));
+      if (!active(capturedEpoch) || id !== loadId || serial !== remoteSerial)
+        return err("cancelled", "State load was superseded.");
+      const live = sessionCheck();
+      if (!live.ok)
+        return live;
+      if (!loaded.ok) {
+        block("storage-error", loaded.error.message);
+        return loaded;
+      }
+      const parsed = readClone(loaded.value);
+      if (!parsed.ok) {
+        block("storage-error", parsed.error.message);
+        return parsed;
+      }
+      return applyRemote(parsed.value, cause);
+    })();
+    activeLoad = work;
+    work.then(() => {
+      if (activeLoad === work) {
+        activeLoad = null;
+        if (active(capturedEpoch) && remoteSerial !== serial)
+          queueRemote();
+      }
+    });
+    return work;
+  }
+  function outcomeCheck(outcome, operationId) {
+    const parsed = codecs.save.decode(structuredClone(codecs.save.encode(outcome)));
+    if (!parsed.ok)
+      return parsed;
+    if (parsed.value.operationId !== operationId || parsed.value.status === "indeterminate")
+      return err("incompatible", "State receipt has a different operation.");
+    const read = "envelope" in parsed.value ? { status: "present", envelope: parsed.value.envelope } : parsed.value.current;
+    const checked = readClone(read);
+    return checked.ok ? ok(frozen(parsed.value)) : checked;
+  }
+  async function applyOutcome(captured, raw) {
+    const checked = outcomeCheck(raw, captured.mutation.operationId);
+    if (!checked.ok) {
+      block("indeterminate", checked.error.message);
+      return checked;
+    }
+    const outcome = checked.value;
+    pending = null;
+    loadId++;
+    blocked = null;
+    if (outcome.status === "saved" || outcome.status === "unchanged") {
+      base = { status: "present", envelope: outcome.envelope };
+      acknowledgedGeneration = Math.max(acknowledgedGeneration, captured.generation);
+      if (localGeneration === captured.generation)
+        desired = { value: valueClone(codec, outcome.envelope.value) };
+      emit();
+    } else if ("current" in outcome) {
+      if (outcome.current.status === "migration-required") {
+        block("migration-required", "State migration is required.");
+        return err("conflict", "State migration is required.");
+      }
+      if (outcome.status === "already-initialized" && localGeneration === captured.generation) {
+        base = outcome.current;
+        desired = { value: valueClone(codec, currentValue(base)) };
+        acknowledgedGeneration = captured.generation;
+        emit();
+      } else {
+        const result = await conflict("save-conflict", outcome.current, captured.base);
+        if (!result.ok)
+          return result;
+      }
+    }
+    const capturedEpoch = epoch;
+    const saved = await persist();
+    if (!saved.ok)
+      return saved;
+    if (active(capturedEpoch)) {
+      if (remotePending)
+        return reload("reconnect");
+      schedule();
+    }
+    return ok(undefined);
+  }
+  function transmit(captured, automatic = false) {
+    const capturedEpoch = epoch;
+    const dispatchEpoch = automaticEpoch;
+    let suppressed = false;
+    const work = (async () => {
+      networkActive = true;
+      emit();
+      const persisted = await persist();
+      if (!active(capturedEpoch))
+        return err("cancelled", "State save was detached.");
+      if (!persisted.ok) {
+        pending = null;
+        networkActive = false;
+        emit();
+        return persisted;
+      }
+      if (automatic && (automaticSuspensions || automaticEpoch !== dispatchEpoch)) {
+        suppressed = true;
+        if (pending === captured)
+          pending = null;
+        networkActive = false;
+        emit();
+        const saved = await persist();
+        return saved.ok ? ok(undefined) : saved;
+      }
+      const valid = sessionCheck();
+      if (!valid.ok) {
+        networkActive = false;
+        return valid;
+      }
+      const response = await safe(() => options.transport.save(captured.mutation, { signal: abort.signal }));
+      if (!active(capturedEpoch) || pending !== captured)
+        return err("cancelled", "State save was detached.");
+      networkActive = false;
+      const live = sessionCheck();
+      if (!live.ok)
+        return live;
+      if (!response.ok) {
+        block("indeterminate", response.error.message);
+        return response;
+      }
+      if (response.value.operationId !== captured.mutation.operationId) {
+        block("indeterminate", "State operation identity changed.");
+        return err("incompatible", "State operation identity changed.");
+      }
+      if (response.value.status === "indeterminate") {
+        block("indeterminate", "State save outcome is unknown.");
+        return err("unavailable", "State save outcome is unknown.", "same-operation");
+      }
+      return applyOutcome(captured, response.value);
+    })();
+    activeSave = work;
+    work.then(() => {
+      if (activeSave === work)
+        activeSave = null;
+      if (suppressed)
+        schedule();
+    });
+    return work;
+  }
+  function sendNew(automatic = false) {
+    if (automatic && automaticSuspensions)
+      return Promise.resolve(ok(undefined));
+    const valid = sessionCheck();
+    if (!valid.ok)
+      return Promise.resolve(valid);
+    if (blocked)
+      return Promise.resolve(err("conflict", blocked.message));
+    if (activeSave)
+      return activeSave;
+    if (pending)
+      return Promise.resolve(err("unavailable", "An earlier save needs reconciliation.", "same-operation"));
+    if (!base || !desired || !needsSave())
+      return Promise.resolve(ok(undefined));
+    const mutation = frozen({ kind: base.status === "empty" ? "initialize" : "replace", address, expectedVersion: { ...version(base) }, expected, ownerSession: options.ownerSession, localGeneration, operationId: newOperationId(), schemaVersion: definition.schemaVersion, value: valueClone(codec, desired.value) });
+    pending = { mutation, base, generation: localGeneration };
+    return transmit(pending, automatic);
+  }
+  let activeReconcile = null;
+  function reconcile(allowReplay) {
+    if (activeReconcile)
+      return activeReconcile;
+    const work = performReconcile(allowReplay);
+    activeReconcile = work;
+    const clear = () => {
+      if (activeReconcile === work)
+        activeReconcile = null;
+    };
+    work.then(clear, clear);
+    return work;
+  }
+  async function performReconcile(allowReplay) {
+    const captured = pending;
+    if (!captured)
+      return ok(undefined);
+    const capturedEpoch = epoch;
+    const valid = sessionCheck();
+    if (!valid.ok)
+      return valid;
+    const result = await safe(() => options.transport.reconcile({ address, expected, operationId: captured.mutation.operationId }, { signal: abort.signal }));
+    if (!active(capturedEpoch) || pending !== captured)
+      return err("cancelled", "State reconciliation was superseded.");
+    const live = sessionCheck();
+    if (!live.ok)
+      return live;
+    if (!result.ok) {
+      block("indeterminate", result.error.message);
+      return result;
+    }
+    if (result.value.status === "final")
+      return applyOutcome(captured, result.value.outcome);
+    if (result.value.status === "absent-final" && allowReplay) {
+      if (captured.mutation.expected.actor !== expected.actor || captured.mutation.expected.session !== expected.session) {
+        block("draft-recovery", "The original operation cannot be re-authored under a new session.");
+        return err("stale-context", "The original operation requires its original session.");
+      }
+      blocked = null;
+      return transmit(captured);
+    }
+    block("indeterminate", "The previous save remains unresolved; no replacement was sent.");
+    return err("unavailable", "The previous save remains unresolved.", "same-operation");
+  }
+  async function performFlush() {
+    clearTimer();
+    const valid = sessionCheck();
+    if (!valid.ok)
+      return valid;
+    const goal = localGeneration;
+    let retries = 0;
+    if (activeSave) {
+      const result = await activeSave;
+      if (!result.ok)
+        return result;
+    }
+    while (active()) {
+      if (pending) {
+        const result2 = await reconcile(retries++ < retryLimit);
+        if (!result2.ok)
+          return result2;
+      }
+      if (blocked)
+        return err("conflict", blocked.message);
+      if (!needsSave() || acknowledgedGeneration >= goal)
+        return ok(undefined);
+      const result = await sendNew();
+      if (!result.ok)
+        return result;
+    }
+    return err("disposed", "The state controller is detached.");
+  }
+  async function flush() {
+    let cancel = () => {};
+    const timeout = new Promise((resolve) => {
+      cancel = scheduler.schedule(30000, () => {
+        if (active())
+          block("indeterminate", "Flush timed out; pending intent is retained.");
+        resolve(err("unavailable", "Flush timed out; pending intent is retained.", "same-operation"));
+      });
+    });
+    try {
+      return await Promise.race([performFlush(), timeout]);
+    } finally {
+      cancel();
+    }
+  }
+  function detach() {
+    if (lifecycle === "detached" || lifecycle === "disposed")
+      return draft();
+    lifecycle = "detached";
+    epoch++;
+    loadId++;
+    clearTimer();
+    abort.abort();
+    subscription?.();
+    subscription = null;
+    emit();
+    return draft();
+  }
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      if (lifecycle === "disposed")
+        return () => {};
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {
+      if (lifecycle === "detached" || lifecycle === "disposed")
+        return Promise.resolve(err("disposed", "Create a new state controller after detach."));
+      if (startWork)
+        return startWork;
+      lifecycle = "active";
+      subscription = options.transport.subscribe(address, (event) => {
+        if (!active() || stateAddressKey(event.address) !== stateAddressKey(address))
+          return;
+        if (base && event.version.epoch === version(base).epoch && event.version.sequence <= version(base).sequence)
+          return;
+        if (remoteHint && event.version.epoch === remoteHint.epoch && event.version.sequence <= remoteHint.sequence)
+          return;
+        remoteHint = { ...event.version };
+        remotePending = true;
+        remoteSerial++;
+        if (blocked?.conflict)
+          block("conflict", "Refreshing the remote state before reviewing this conflict.");
+        else
+          emit();
+        queueRemote();
+      });
+      startWork = reload("dirty-load");
+      return startWork;
+    },
+    edit(value) {
+      const valid = sessionCheck();
+      if (!valid.ok)
+        return valid;
+      if (closing || blocked || snapshot.status !== "ready")
+        return err("unavailable", "State is not editable.");
+      try {
+        desired = { value: valueClone(codec, value) };
+      } catch (error) {
+        return err("invalid-input", error instanceof Error ? error.message : "Invalid state.");
+      }
+      localGeneration++;
+      emit();
+      schedule();
+      return ok(undefined);
+    },
+    suspendAutomaticDispatch() {
+      automaticSuspensions++;
+      automaticEpoch++;
+      clearTimer();
+      let released = false;
+      return () => {
+        if (released)
+          return;
+        released = true;
+        automaticSuspensions--;
+        if (!automaticSuspensions)
+          schedule();
+      };
+    },
+    flush,
+    async reconnect(input) {
+      const valid = sessionCheck();
+      if (!valid.ok)
+        return valid;
+      const existing = activeSave ?? activeReconcile ?? activeLoad;
+      if (input?.reuseInFlight && existing)
+        return existing;
+      if (activeSave) {
+        const settled = await activeSave;
+        if (!settled.ok && !pending)
+          return settled;
+      }
+      if (pending) {
+        const result = await reconcile(false);
+        if (!result.ok)
+          return result;
+      }
+      return reload("reconnect");
+    },
+    async resolveConflict(token, decision) {
+      const valid = sessionCheck();
+      if (!valid.ok)
+        return valid;
+      const context = blocked?.conflict;
+      if (!context || context.token !== token)
+        return err("stale-context", "Conflict decision was superseded.");
+      return applyDecision(context, decision);
+    },
+    async recover(candidate) {
+      if (!drafts)
+        return err("unsupported", "Draft recovery is disabled for this state.");
+      const valid = sessionCheck();
+      if (!valid.ok)
+        return valid;
+      if (activeSave || pending || dirty())
+        return err("conflict", "Resolve current edits before recovering another draft.");
+      const source = candidate.draft;
+      if (source.formatVersion !== 1 || source.key.actor !== expected.actor || source.schemaVersion !== definition.schemaVersion || stateAddressKey(source.key.address) !== stateAddressKey(address))
+        return err("invalid-input", "Draft does not match this resource and actor.");
+      const parsed = readClone(source.acknowledged);
+      if (!parsed.ok || parsed.value.status === "migration-required")
+        return err("invalid-input", "Draft base is invalid.");
+      let mutation = null;
+      if (source.inFlight) {
+        const result = codecs.mutation.decode(structuredClone(codecs.mutation.encode(source.inFlight)));
+        if (!result.ok || stateAddressKey(result.value.address) !== stateAddressKey(address) || result.value.schemaVersion !== definition.schemaVersion || result.value.expected.actor !== expected.actor || result.value.localGeneration > source.localGeneration)
+          return err("invalid-input", "Draft operation does not match its owner or generation.");
+        mutation = frozen(result.value);
+      }
+      clearTimer();
+      base = parsed.value;
+      desired = { value: valueClone(codec, source.desired) };
+      localGeneration = source.localGeneration;
+      recoverySource = frozen(structuredClone(candidate));
+      checkpoint = source.key.ownerSession === options.ownerSession ? recoverySource : null;
+      if (mutation) {
+        pending = { mutation, base, generation: mutation.localGeneration };
+        block("draft-recovery", "Reconciling the original operation.");
+        const result = await reconcile(false);
+        if (!result.ok)
+          return result;
+      }
+      const capturedEpoch = epoch;
+      const loaded = await reload("draft-recovery");
+      if (!loaded.ok || !active(capturedEpoch))
+        return loaded;
+      return ok(undefined);
+    },
+    async discardRecovery(candidate) {
+      if (!drafts)
+        return err("unsupported", "Draft recovery is disabled for this state.");
+      if (!active())
+        return err("disposed", "This state controller is no longer active.");
+      const source = candidate.draft;
+      if (source.formatVersion !== 1 || source.key.actor !== expected.actor || source.schemaVersion !== definition.schemaVersion || stateAddressKey(source.key.address) !== stateAddressKey(address)) {
+        return err("invalid-input", "Draft does not match this resource and actor.");
+      }
+      const removed = await safe(() => drafts.remove(source.key, candidate.revision));
+      if (!removed.ok || !active())
+        return removed.ok ? err("disposed", "This state controller is no longer active.") : removed;
+      const sameCheckpoint = (entry) => entry !== null && entry.revision === candidate.revision && entry.draft.key.actor === source.key.actor && entry.draft.key.ownerSession === source.key.ownerSession && stateAddressKey(entry.draft.key.address) === stateAddressKey(source.key.address);
+      if (sameCheckpoint(checkpoint))
+        checkpoint = null;
+      if (sameCheckpoint(recoverySource))
+        recoverySource = null;
+      return ok(undefined);
+    },
+    async recoveryCandidates(readOptions) {
+      if (readOptions?.signal?.aborted)
+        return err("cancelled", "Recovery lookup was cancelled.");
+      if (!drafts)
+        return ok([]);
+      const result = await safe(() => drafts.find(address, expected.actor, 20));
+      if (readOptions?.signal?.aborted)
+        return err("cancelled", "Recovery lookup was cancelled.");
+      return result;
+    },
+    checkpoint: () => persist(),
+    detach,
+    async close(input) {
+      if (!drafts) {
+        detach();
+        return ok(undefined);
+      }
+      if (input.pending === "flush") {
+        closing = true;
+        const result = await flush();
+        const retained2 = detach();
+        if (!result.ok) {
+          await persist(retained2);
+          return result;
+        }
+        return ok(undefined);
+      }
+      const retained = detach();
+      if (input.pending === "preserve") {
+        const result = await persist(retained);
+        return result.ok ? ok(undefined) : result;
+      }
+      await persistQueue;
+      const candidates = new Map;
+      for (const entry of [checkpoint, recoverySource])
+        if (entry)
+          candidates.set(JSON.stringify(entry.draft.key), entry);
+      for (const entry of candidates.values()) {
+        const removed = await safe(() => drafts.remove(entry.draft.key, entry.revision));
+        if (!removed.ok)
+          return removed;
+      }
+      return ok(undefined);
+    },
+    dispose() {
+      detach();
+      lifecycle = "disposed";
+      listeners.clear();
+    }
+  };
+}
+export {
+  createIdentityState
+};