@phosphorco/bb-identity 0.1.0

package/react.d.ts

@@ -0,0 +1,129 @@
+/**
+ * React ownership, state hooks and shared normalized identity presentation.
+ * Feature conflict presentation and retry policy remain feature-owned.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import type {
+  IdentityClient,
+  IdentityConnection,
+  IdentitySession,
+  IdentityStateBinding,
+  IdentityStateBindingOptions,
+  IdentityView,
+  PendingEditPolicy,
+  StateBindingSource,
+  ViewSnapshot,
+} from './client.js';
+import type { IdentityError, IdentityProfile, ProfilePresentation, Result } from './model.js';
+import type { PendingDraft, SyncSnapshot } from './state.js';
+
+export interface IdentityProviderProps {
+  /** Borrowed: Provider never starts or disposes this client. Null suspends
+   * children while retaining this mounted Provider's preservation/failure owner. */
+  readonly client: IdentityClient | null;
+  /** Rendered until a non-null client and the Provider owner are committed. */
+  readonly fallback?: ReactNode;
+  readonly children?: ReactNode;
+}
+
+export type IdentityContextProps = { readonly children?: ReactNode } & (
+  | { readonly view?: never; readonly pendingEdits?: PendingEditPolicy }
+  | { readonly view: IdentityView; readonly pendingEdits?: never }
+);
+
+/** Provider and Context establish ownership for the exported hooks/controls. */
+export interface BbIdentityComponents {
+  readonly Provider: ComponentType<IdentityProviderProps>;
+  /** Borrows an injected view or owns a default view for this Context subtree. */
+  readonly Context: ComponentType<IdentityContextProps>;
+}
+export declare const BbIdentity: BbIdentityComponents;
+
+/** Presentation is supplied by the caller; this component never fetches a profile. */
+export interface IdentityAvatarProps {
+  readonly presentation: ProfilePresentation | null;
+  /** Human-readable fallback and accessible label; never pass an opaque identity key. */
+  readonly label: string;
+  readonly className?: string;
+}
+export declare const IdentityAvatar: ComponentType<IdentityAvatarProps>;
+
+/** Compact normalized profile label. The fallback is caller-owned product wording. */
+export interface IdentityLabelProps {
+  readonly profile: IdentityProfile | null;
+  readonly fallback: string;
+  readonly className?: string;
+  readonly primaryClassName?: string;
+  readonly secondaryClassName?: string;
+}
+export declare const IdentityLabel: ComponentType<IdentityLabelProps>;
+
+export interface IdentityViewPickerLabels {
+  readonly trigger: string;
+  readonly self: string;
+  readonly viewingFallback: string;
+  readonly dialog: string;
+  readonly search: string;
+  readonly noResults: string;
+  readonly searchUnavailable: string;
+}
+export interface IdentityViewPickerProps {
+  /** Presentation only; selection always uses the normalized profile identity. */
+  readonly selectedProfile?: IdentityProfile | null;
+  /** Disables selecting a different view, but never the separate return-self control. */
+  readonly selectionDisabled?: boolean;
+  readonly labels: IdentityViewPickerLabels;
+  readonly className?: string;
+  readonly contentClassName?: string;
+  readonly searchClassName?: string;
+  readonly resultsClassName?: string;
+  readonly avatarClassName?: string;
+  /** Observes the same Result displayed by the control; feature retry policy stays local. */
+  readonly onResult?: (result: Result<void>) => void;
+}
+/** Uses the current Context view/client; no module-global client, view, or directory cache. */
+export declare const IdentityViewPicker: ComponentType<IdentityViewPickerProps>;
+
+export interface IdentityViewStatusLabels {
+  readonly viewing: string;
+  readonly returnSelf: string;
+}
+export interface IdentityViewStatusProps {
+  readonly labels: IdentityViewStatusLabels;
+  readonly className?: string;
+  /** Feature-specific selectors remain feature-owned. */
+  readonly returnSelfAttributes?: Readonly<Record<string, string>>;
+  readonly onResult?: (result: Result<void>) => void;
+}
+/** Shows an overriding-view status and its always-available, scope-fenced return action. */
+export declare const IdentityViewStatus: ComponentType<IdentityViewStatusProps>;
+
+/** Native SDK hook composition. Null means committed acquisition is still pending. */
+export declare function useBbIdentityConnection(): IdentityConnection | null;
+/** Native SDK hook composition. Null means the committed connection/client is not live yet. */
+export declare function useBbIdentityClient(): IdentityClient | null;
+/** Reads the explicitly borrowed Provider client; missing Provider is a setup error. */
+export declare function useBorrowedIdentityClient(): IdentityClient;
+export declare function useIdentitySession(): IdentitySession;
+
+/** Framework-neutral binding ownership attached to the default Context view. */
+export declare function useIdentityStateBinding<T>(
+  options: Omit<IdentityStateBindingOptions<T>, 'client' | 'view'> & StateBindingSource<T>,
+): IdentityStateBinding<T> | null;
+/** Renderable snapshot for a nullable committed binding. */
+export declare function useIdentityStateSnapshot<T>(binding: IdentityStateBinding<T> | null):
+  | SyncSnapshot<T>
+  | { readonly status: 'waiting-for-identity' };
+
+export declare function useIdentityViewSnapshot(): ViewSnapshot;
+export declare function useIdentityViewActions(): Pick<IdentityView, 'select' | 'reset'>;
+
+/** Presentation-only failure record. The immutable generation acknowledges exactly one record. */
+export interface IdentityPreservationFailure {
+  readonly generation: number;
+  readonly draft: PendingDraft<unknown>;
+  readonly error: IdentityError;
+}
+export declare function useIdentityPreservationFailures(): readonly IdentityPreservationFailure[];
+/** Returns false for an absent or superseded generation; feature code owns retry/recovery. */
+export declare function useAcknowledgeIdentityPreservationFailure(): (generation: number) => boolean;

package/server.d.ts

@@ -0,0 +1,80 @@
+/** Request-bound server API; separate target intent, captured target facts, and live lifecycle validity. */
+import type { AcceptanceOutcome, ActorReference, ActorSnapshot, Codec, Directory, Disposable, ExecutionProvenance,
+  IdentityKey, InstanceId, OperationId, OperationLookup, ParticipantReader, PersonReference,
+  PersonSendInput, ReadOptions, RequestExpectation, Result, SendInput, TargetSelection, Unsubscribe } from './model.js';
+import type { ExternalAuthorInput, IdentityHost, IdentityCapabilities, ServerSession, HostInvalidation } from './host.js';
+
+declare const resolvedTarget: unique symbol;
+export interface TargetSnapshot {
+  readonly actor: ActorSnapshot & { readonly identity: ActorReference };
+  readonly subject: ActorReference;
+  readonly expected: RequestExpectation;
+}
+export interface ResolvedTarget<Intent extends 'read' | 'write'> {
+  readonly [resolvedTarget]: Intent;
+  readonly intent: Intent;
+  /** Reads frozen captured target facts for the commit checks. */
+  snapshot(): TargetSnapshot;
+  readonly signal: AbortSignal;
+}
+export interface CommitScope {
+  readonly instanceId: InstanceId;
+  readonly pluginId: import('./model.js').PluginId;
+  readonly collection: string; readonly recordId: string;
+  readonly subject: IdentityKey; readonly expected: RequestExpectation; readonly schemaVersion: number;
+}
+/** Validates write intent, captured actor/subject/session, address, namespace, and live lifecycle signal. */
+export interface CommitValidator {
+  readonly boundary: 'same-process-synchronous';
+  validate(target: ResolvedTarget<'write'>, scope: CommitScope): Result<void>;
+}
+export type TargetPolicy = { readonly kind: 'self-only' } | { readonly kind: 'collaborators' };
+export interface ReadTargetRequest {
+  readonly selection: TargetSelection; readonly policy: TargetPolicy; readonly intent: 'read';
+}
+export interface WriteTargetRequest {
+  readonly selection: TargetSelection; readonly policy: TargetPolicy; readonly intent: 'write';
+  readonly expected: RequestExpectation; readonly expectedSubject: IdentityKey;
+}
+export type TargetRequest = ReadTargetRequest | WriteTargetRequest;
+export interface PersonRequest<Input> extends Disposable {
+  readonly actor: ActorSnapshot & { readonly identity: ActorReference };
+  readonly expected: RequestExpectation;
+  readonly capabilities: IdentityCapabilities;
+  readonly signal: AbortSignal;
+  target(input: ReadTargetRequest): Promise<Result<ResolvedTarget<'read'>>>;
+  target(input: WriteTargetRequest): Promise<Result<ResolvedTarget<'write'>>>;
+  send(input: PersonSendInput<Input>, options?: ReadOptions): Promise<AcceptanceOutcome>;
+  /** Host-bound on enhanced BB; upstream preserves the singleton convention with weaker lifetime guarantees. */
+  callPlugin<T>(input: { readonly pluginId: string; readonly method: string; readonly payload: import('./model.js').Json;
+    readonly output: Codec<T> }, options?: ReadOptions): Promise<Result<T>>;
+}
+export interface IdentityServer<RequestContext, ToolContext, Input> extends Disposable {
+  readonly instanceId: InstanceId;
+  readonly directory: Directory;
+  readonly participants: ParticipantReader;
+  readonly history: import('./model.js').ProvenanceReader;
+  readonly commits: CommitValidator;
+  session(context: RequestContext, options?: ReadOptions): Promise<ServerSession>;
+  selfProfile(context: RequestContext, options?: ReadOptions): Promise<Result<import('./model.js').IdentityProfile>>;
+  subscribe(listener: (event: HostInvalidation) => void): Unsubscribe;
+  personRequest(context: RequestContext, options?: ReadOptions): Promise<Result<PersonRequest<Input>>>;
+  toolProvenance(context: ToolContext): Promise<Result<ExecutionProvenance>>;
+  sendExternal(author: ExternalAuthorInput, input: SendInput<Input>, options?: ReadOptions): Promise<AcceptanceOutcome>;
+  /** Lookup reports retained operation outcomes; IDs are scoped to this instance/plugin. */
+  lookupOperation(operationId: OperationId, options?: ReadOptions): Promise<Result<OperationLookup<AcceptanceOutcome>>>;
+}
+export declare function createIdentityServer<R, T, I>(options: { readonly host: IdentityHost<R, T, I> }): IdentityServer<R, T, I>;
+/** Wire query DTOs contain no AbortSignal. Options are local to this handler invocation. */
+export interface IdentityEndpoint<RequestContext> extends Disposable {
+  bootstrap(context: RequestContext, options?: ReadOptions): Promise<Result<ServerSession>>;
+  selfProfile(context: RequestContext, options?: ReadOptions): Promise<Result<import('./model.js').IdentityProfile>>;
+  search(context: RequestContext, input: import('./model.js').DirectoryQuery, options?: ReadOptions): ReturnType<Directory['search']>;
+  profiles(context: RequestContext, input: import('./model.js').ProfileQuery, options?: ReadOptions): ReturnType<Directory['getMany']>;
+  participants(context: RequestContext, input: import('./model.js').ParticipantQuery, options?: ReadOptions): ReturnType<ParticipantReader['list']>;
+  participantPreviews(context: RequestContext, input: import('./model.js').ParticipantPreviewQuery, options?: ReadOptions): ReturnType<ParticipantReader['previews']>;
+}
+export declare function createIdentityEndpoint<R, T, I>(options: {
+  readonly server: IdentityServer<R, T, I>;
+  readonly publish: (event: import('./client.js').ClientInvalidation) => void;
+}): IdentityEndpoint<R>;

package/state.d.ts

@@ -0,0 +1,170 @@
+/** Framework-neutral synchronization; feature-owned schemas and transactional storage. */
+import type { ActorSnapshot, Codec, ConflictToken, Disposable, IdentityKey, InstanceId, OperationId,
+  OperationLookup, OwnerSessionId, PluginId, ReadOptions, RequestExpectation, Result, Scheduler, Unsubscribe } from './model.js';
+import type { CommitValidator, ResolvedTarget } from './server.js';
+export interface StateAddress {
+  readonly instanceId: InstanceId; readonly pluginId: PluginId;
+  readonly collection: string; readonly recordId: string; readonly owner: IdentityKey;
+}
+/** Ordered only within an epoch. Reset/recreation produces a fresh epoch; empty records have stable versions. */
+export interface StateVersion { readonly epoch: string; readonly sequence: number; }
+export interface StateDefinition<T> {
+  readonly collection: string; readonly schemaVersion: number; readonly codec: Codec<T>;
+  initialValue(): T;
+  equal(left: T, right: T): boolean;
+}
+/** Share this feature-owned descriptor between client and server; address construction is package-owned. */
+export interface StateResource<T> {
+  readonly pluginId: PluginId; readonly definition: StateDefinition<T>;
+}
+/** Borrows the same root-owned connection as identity; state never opens a competing feed. */
+export declare function createStateTransport<T>(options: {
+  readonly connection: import('./client.js').IdentityConnection; readonly resource: StateResource<T>;
+}): StateTransport<T>;
+export interface StateEnvelope<T> {
+  readonly address: StateAddress; readonly version: StateVersion; readonly schemaVersion: number;
+  readonly value: T; readonly lastEditedBy: ActorSnapshot | null;
+}
+export type StateRead<T> =
+  | { readonly status: 'present'; readonly envelope: StateEnvelope<T> }
+  | { readonly status: 'empty'; readonly address: StateAddress; readonly version: StateVersion }
+  | { readonly status: 'migration-required'; readonly address: StateAddress; readonly storedSchemaVersion: number };
+export interface StateMutation<T> {
+  /** Initialization never rebases defaults. An existing winner is adopted. */
+  readonly kind: 'initialize' | 'replace';
+  readonly address: StateAddress; readonly expectedVersion: StateVersion;
+  readonly expected: RequestExpectation; readonly ownerSession: OwnerSessionId;
+  readonly localGeneration: number; readonly operationId: OperationId;
+  readonly schemaVersion: number; readonly value: T;
+}
+export type StateOutcome<T> =
+  | { readonly status: 'saved' | 'unchanged'; readonly envelope: StateEnvelope<T>; readonly operationId: OperationId }
+  | { readonly status: 'already-initialized'; readonly current: StateRead<T>; readonly operationId: OperationId }
+  | { readonly status: 'conflict'; readonly current: StateRead<T>; readonly operationId: OperationId };
+export type StateSave<T> = StateOutcome<T> | { readonly status: 'indeterminate'; readonly operationId: OperationId };
+export interface StateInvalidation { readonly address: StateAddress; readonly version: StateVersion; readonly operationId: OperationId | null; }
+export interface StateReadRequest { readonly address: StateAddress; readonly expected: RequestExpectation; }
+export interface StateLookupRequest extends StateReadRequest { readonly operationId: OperationId; }
+export interface StateTransport<T> {
+  load(input: StateReadRequest, options?: ReadOptions): Promise<Result<StateRead<T>>>;
+  save(input: StateMutation<T>, options?: ReadOptions): Promise<Result<StateSave<T>>>;
+  reconcile(input: StateLookupRequest, options?: ReadOptions): Promise<Result<OperationLookup<StateOutcome<T>>>>;
+  subscribe(address: StateAddress, listener: (event: StateInvalidation) => void): Unsubscribe;
+}
+/** Deduplicate immutable operation BEFORE CAS; replay exact original outcome even if current record advanced.
+ * Same ID with changed mutation fails invalid-operation. Record+receipt commit atomically.
+ * Retain receipts for receiptRetentionMs; expired IDs yield unknown, never permission to replace a pending op.
+ */
+export interface AtomicStateStorage<T> {
+  readonly boundary: 'same-process-synchronous';
+  readonly receiptRetentionMs: number;
+  read(address: StateAddress, options?: ReadOptions): Promise<Result<StateRead<T>>>;
+  commit(input: {
+    readonly mutation: StateMutation<T>;
+    /** Invoke inside the synchronous transaction immediately before mutation; no await through commit. */
+    readonly validateAtCommit: () => Result<ActorSnapshot>;
+  }): Promise<Result<StateSave<T>>>;
+  reconcile(input: { readonly address: StateAddress; readonly operationId: OperationId }): Promise<Result<OperationLookup<StateOutcome<T>>>>;
+}
+export interface StateService<T> {
+  read(target: ResolvedTarget<'read'> | ResolvedTarget<'write'>, recordId: string, options?: ReadOptions): Promise<Result<StateRead<T>>>;
+  save(target: ResolvedTarget<'write'>, mutation: StateMutation<T>, options?: ReadOptions): Promise<Result<StateSave<T>>>;
+  reconcile(target: ResolvedTarget<'read'> | ResolvedTarget<'write'>, recordId: string, operationId: OperationId): Promise<Result<OperationLookup<StateOutcome<T>>>>;
+}
+export declare function createStateService<T>(options: {
+  readonly instanceId: InstanceId; readonly pluginId: PluginId; readonly definition: StateDefinition<T>;
+  readonly storage: AtomicStateStorage<T>; readonly commits: CommitValidator;
+  readonly publish: (event: StateInvalidation) => void;
+}): StateService<T>;
+/** Decode wrapper metadata as well as the feature value; local signals are never part of the wire codec. */
+export declare function stateCodecs<T>(value: Codec<T>): {
+  readonly read: Codec<StateRead<T>>; readonly mutation: Codec<StateMutation<T>>;
+  readonly save: Codec<StateSave<T>>; readonly invalidation: Codec<StateInvalidation>;
+  readonly lookup: Codec<OperationLookup<StateOutcome<T>>>;
+};
+
+export interface DraftKey { readonly address: StateAddress; readonly actor: IdentityKey; readonly ownerSession: OwnerSessionId; }
+export interface PendingDraft<T> {
+  readonly formatVersion: 1; readonly key: DraftKey; readonly schemaVersion: number;
+  readonly acknowledged: Exclude<StateRead<T>, { status: 'migration-required' }>;
+  readonly desired: T; readonly localGeneration: number;
+  /** Exact immutable submitted mutation, separate from newer desired content. */
+  readonly inFlight: StateMutation<T> | null;
+}
+export interface DraftCheckpoint<T> { readonly revision: number; readonly draft: PendingDraft<T>; }
+export interface DraftStorage<T> {
+  /** Bounded recovery lookup across prior controller incarnations; never silently choose between drafts. */
+  find(address: StateAddress, actor: IdentityKey, limit: number): Promise<Result<readonly DraftCheckpoint<T>[]>>;
+  write(draft: PendingDraft<T>, expectedRevision: number | null): Promise<Result<DraftCheckpoint<T>>>;
+  /** An obsolete controller cannot erase a newer checkpoint. */
+  remove(key: DraftKey, expectedRevision: number): Promise<Result<void>>;
+}
+export type ConflictDecision<T> =
+  | { readonly kind: 'rebase'; readonly value: T }
+  | { readonly kind: 'accept-remote' }
+  | { readonly kind: 'needs-review'; readonly reason: string };
+export interface ConflictContext<T> {
+  readonly cause: 'save-conflict' | 'dirty-load' | 'reconnect' | 'epoch-change' | 'draft-recovery';
+  /** A conflict decision is valid only for this token and this controller incarnation. */
+  readonly token: ConflictToken; readonly ownerSession: OwnerSessionId;
+  readonly base: StateRead<T>; readonly local: T; readonly remote: StateRead<T>;
+}
+export type SyncSnapshot<T> =
+  | { readonly status: 'loading'; readonly address: StateAddress }
+  | { readonly status: 'ready'; readonly address: StateAddress; readonly ownerSession: OwnerSessionId;
+      readonly acknowledged: StateRead<T>; readonly desired: T; readonly dirty: boolean;
+      readonly saving: boolean; readonly localGeneration: number; readonly remotePending: boolean }
+  | { readonly status: 'blocked'; readonly address: StateAddress;
+      readonly reason: 'identity-unavailable' | 'owner-changed' | 'conflict' | 'indeterminate' | 'storage-error' | 'migration-required' | 'draft-recovery';
+      readonly draft: PendingDraft<T> | null; readonly conflict: ConflictContext<T> | null; readonly message: string }
+  | { readonly status: 'detached'; readonly address: StateAddress; readonly draft: PendingDraft<T> | null };
+export interface IdentityState<T> extends Disposable {
+  getSnapshot(): SyncSnapshot<T>;
+  subscribe(listener: () => void): Unsubscribe;
+  start(): Promise<Result<void>>;
+  edit(value: T): Result<void>;
+  /** Reference-counted transition pause. Stops automatic dispatch, including work
+   * awaiting a checkpoint; explicit flush remains available. Release resumes scheduling. */
+  suspendAutomaticDispatch(): Unsubscribe;
+  /** Waits for the pending intent observed at invocation, with a 30-second scheduler bound.
+   * Timeout retains the exact uncertain operation; it cannot retract accepted work.
+   */
+  flush(): Promise<Result<void>>;
+  /** Refresh identity first. Every remote divergence while dirty invokes conflict policy with ORIGINAL base. */
+  /** Health notifications may reuse current recovery; explicit reconnects refresh authority. */
+  reconnect(options?: { readonly reuseInFlight?: boolean }): Promise<Result<void>>;
+  /** Rejects a token superseded by a later remote divergence, even in this same controller. */
+  resolveConflict(token: ConflictToken, decision: ConflictDecision<T>): Promise<Result<void>>;
+  /** Recovery selection is explicit; exact uncertain operations are reconciled before accepting/rebasing desired. */
+  recover(checkpoint: DraftCheckpoint<T>): Promise<Result<void>>;
+  /** Explicitly forget one exact recovery checkpoint. A newer revision cannot
+   * be erased by a stale recovery list. */
+  discardRecovery(checkpoint: DraftCheckpoint<T>): Promise<Result<void>>;
+  /** At most 20 candidates for this address AND actual actor, across prior incarnations.
+   * Store survives controller disposal; schema mismatch and another actor's draft require an explicit
+   * feature import, never automatic recovery. Reconcile old uncertain operations without re-authoring.
+   */
+  recoveryCandidates(options?: ReadOptions): Promise<Result<readonly DraftCheckpoint<T>[]>>;
+  checkpoint(): Promise<Result<DraftCheckpoint<T> | null>>;
+  /** Immediate: stop writes/timers and fence late callbacks. The returned
+   * in-memory draft is durable only when this controller was given DraftStorage. */
+  detach(reason: 'identity-invalidated' | 'view-change' | 'unmount'): PendingDraft<T> | null;
+  /** Fallible preservation is separate from unconditional detach/dispose. With
+   * no DraftStorage, preserve is deliberately in-session only. Flush is bounded;
+   * discard cannot recall accepted work. */
+  close(options: { readonly pending: 'flush' | 'preserve' | 'discard' }): Promise<Result<void>>;
+}
+export declare function createIdentityState<T>(options: {
+  readonly address: StateAddress; readonly expected: RequestExpectation; readonly ownerSession: OwnerSessionId;
+  readonly definition: StateDefinition<T>; readonly transport: StateTransport<T>; readonly drafts?: DraftStorage<T>;
+  readonly scheduler?: Scheduler; readonly debounceMs?: number;
+  /** Maximum same-operation resubmissions during one explicit flush after an absent-final lookup.
+   * Default 3; zero forbids resubmission. Unknown/pending outcomes never authorize a retry.
+   */
+  readonly retryLimit?: number;
+  readonly onConflict: (context: ConflictContext<T>) => ConflictDecision<T>;
+  readonly initializeEmpty: boolean;
+  /** Must return the currently observed server session, not a captured initial identity. */
+  readonly currentSession: () => Result<import('./host.js').ServerSession>;
+}): IdentityState<T>;
+export declare function stateAddressKey(address: StateAddress): string;

package/testing.d.ts

@@ -0,0 +1,202 @@
+/** Testing entry point: production-adapter inputs and separately labelled normalized consumer fixtures. */
+import type { ActorReference, ActorSnapshot, Codec, Contribution, ContributionId, ExecutionProvenance,
+  IdentityKey, OperationId, PersonReference, Result, Scheduler,
+  SessionStamp, Unsubscribe } from './model.js';
+import type { IdentityHost, UpstreamDriver } from './host.js';
+import type { ConnectionHealth, IdentityClientTransport, IdentityConnection, IdentityConnectionEvent } from './client.js';
+import type { AtomicStateStorage, StateAddress, StateEnvelope, StateRead, StateResource, StateVersion } from './state.js';
+import type { TargetPolicy } from './server.js';
+export interface ManualClock extends Scheduler {
+  advance(milliseconds: number): Promise<void>;
+  flush(): Promise<void>;
+  readonly pendingTimers: number;
+}
+export interface Deferred<T> { readonly promise: Promise<T>; resolve(value: T): void; reject(reason: unknown): void; }
+export declare function createManualClock(initialMilliseconds?: number): ManualClock;
+export declare function deferred<T>(): Deferred<T>;
+/** Person fixture is for multi-person scenarios. Singleton comes only from the instance's reserved default. */
+export declare function personFixture(input: { readonly subject: string; readonly name: string }): ActorSnapshot & { readonly identity: PersonReference };
+export interface FakeRequest { readonly id: string; readonly origin: 'interactive-user' | 'agent' | 'background' | 'external' | 'unauthenticated'; }
+export interface FakeToolCall { readonly id: string; }
+export interface Pause { readonly reached: Promise<void>; release(): void; }
+export interface AdapterHarness<Input> {
+  readonly upstream: UpstreamDriver<FakeRequest, FakeToolCall, Input>;
+  readonly clock: ManualClock;
+  /** Production inspectForkExtension and createHostAdapter path, not a supplied normalized host. */
+  connect(): IdentityHost<FakeRequest, FakeToolCall, Input>;
+  setRawExtension(value: unknown): void;
+  /** @throws This adapter fixture does not model operation lookup controls. */
+  setLookup(status: 'supported' | 'unsupported' | 'pending' | 'absent-final' | 'expired' | 'unavailable'): void;
+  request(origin?: FakeRequest['origin']): FakeRequest;
+  /** Multi-user replacement advances the session stamp and invalidates every issued request; singleton rejects it. */
+  setActor(actor: ActorSnapshot & { readonly identity: ActorReference }): Result<void>;
+  setIdentityAvailability(status: 'ready' | 'unavailable' | 'unauthenticated'): void;
+  settle(request: FakeRequest): void;
+  /** @throws Streaming is not modeled by this adapter fixture. */
+  constructStreamingResponse(request: FakeRequest): void;
+  /** @throws Streaming is not modeled by this adapter fixture. */
+  finishStream(request: FakeRequest): void;
+  abort(request: FakeRequest): void;
+  replaceProvider(result: 'succeed' | 'fail'): void;
+  disconnect(): void;
+  reconnect(): void;
+  /** @throws Acceptance pause points are not modeled by this adapter fixture. */
+  pauseAcceptance(point: 'before-dispatch' | 'before-commit' | 'after-commit-before-response'): Pause;
+  /** @throws Response loss is not modeled by this adapter fixture. */
+  loseNextAcceptanceResponse(): void;
+  /** @throws Causal contribution/attempt controls are not modeled by this adapter fixture. */
+  beginAttempt(groups: readonly (readonly ContributionId[])[]): string;
+  editContribution(id: ContributionId, editor: ActorSnapshot): void;
+  continueAttempt(attemptId: string, reason: string): string;
+  toolCallForAttempt(attemptId: string): FakeToolCall;
+  /** @throws Causal contribution/attempt controls are not modeled by this adapter fixture. */
+  readonly accepted: readonly Contribution[];
+  readonly observations: { readonly submissions: number; readonly rawExtensionReads: number;
+    readonly profileReads: number; readonly participantReads: number; readonly subscriptions: number };
+  dispose(): void;
+}
+export declare function createAdapterHarness<Input>(options: {
+  readonly mode: 'single-user' | 'multi-user';
+  /** Plain fixture IDs are validated and branded inside the test runtime. */
+  readonly instanceId?: string; readonly pluginId?: string;
+  readonly inputCodec: Codec<Input>; readonly clock?: ManualClock;
+}): AdapterHarness<Input>;
+/** Unit-only shortcut, intentionally not evidence of host causal attribution correctness. */
+export declare function consumerProvenanceFixture(provenance: ExecutionProvenance): FakeToolCall;
+/** Raw connection controls exercise production decoder/health paths, not a pre-normalized client.
+ * `state` and `identity` health can change independently so a state-only outage is reproducible.
+ */
+export interface ConnectionHarness {
+  readonly connection: IdentityConnection;
+  /** Exercises production createIdentityClientTransport and createStateTransport paths. */
+  connect(): IdentityClientTransport;
+  setHealth(health: ConnectionHealth): void;
+  replyNext(method: string, payload: unknown): void;
+  emit(event: IdentityConnectionEvent): void;
+  pauseNextRequest(method: string): Pause;
+  readonly observations: { readonly methods: readonly string[]; readonly disposeCalls: number };
+}
+export declare function createConnectionHarness(): ConnectionHarness;
+export interface StateStorageHarness<T> {
+  readonly storage: AtomicStateStorage<T>;
+  seed(envelope: StateEnvelope<T>): void;
+  seedEmpty(address: StateAddress, version: StateVersion): void;
+  seedReadFailure(error: import('./model.js').IdentityError): void;
+  seedLegacy(address: StateAddress, schemaVersion: number): void;
+  readCommitted(address: StateAddress): StateEnvelope<T> | null;
+  /** Snapshot timing is explicit to reproduce stale successful loads. */
+  pauseNextRead(options: { readonly capture: 'before-pause' | 'after-release' }): Pause;
+  pauseNextCommit(): Pause;
+  loseNextCommitResponse(): void;
+  expireReceipt(operationId: OperationId): void;
+  readonly commits: readonly { readonly actor: IdentityKey; readonly address: StateAddress; readonly version: StateVersion }[];
+}
+export declare function createStateStorageHarness<T>(options: { readonly clock: ManualClock }): StateStorageHarness<T>;
+
+/** The parts of `createFakePluginHost()` (from `@get-bb/plugin-sdk/testing`) the wire fake uses. */
+/** Structural, so `/testing` declarations compile without the optional SDK peer installed. */
+export interface WireFakeHost {
+  readonly bb: {
+    readonly pluginId: string;
+    onDispose(dispose: () => void | Promise<void>): void;
+    readonly rpc: { register(contract: never, handlers: never): unknown };
+    readonly realtime: { publish(channel: string, payload: never): unknown };
+    readonly sdk: unknown;
+  };
+  readonly harness: {
+    readonly behavior: { callRpc(method: string, input?: unknown): Promise<unknown> };
+    readonly inspection: { readonly pluginId: string };
+  };
+}
+export interface IdentityWireFakeOptions<T> {
+  /** A fresh SDK fake host for the feature plugin; the production binding registers on it. */
+  readonly host: WireFakeHost;
+  /** `single-user` runs the upstream singleton path; `multi-user` adds a switchable actor and directory. */
+  readonly mode: 'single-user' | 'multi-user';
+  /** The feature's shared state resource; its pluginId must be the host's. */
+  readonly resource: StateResource<T>;
+  readonly policy?: TargetPolicy;
+  readonly readPolicy?: TargetPolicy;
+  readonly instanceId?: string;
+  /** Initial multi-user actor; default subject `wire-fake-user`. */
+  readonly actor?: { readonly subject: string; readonly name: string };
+  readonly clock?: ManualClock;
+}
+/**
+ * Wire-level identity server for client and app tests. Handlers run the production
+ * `bindBbIdentity` binding, endpoint and state bridge on the SDK fake host, with
+ * state in `createStateStorageHarness`. Source conformance only, not native host proof.
+ */
+export interface IdentityWireFake<T> {
+  /** `bb-identity.v1.*` handlers, shaped for SDK `testing/app` `renderSlot(…, { rpc })`. */
+  readonly rpc: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+  /** The realtime channel identity clients subscribe to. */
+  readonly channel: 'bb-identity/v1';
+  /** Each server publication, JSON-normalized. Forward it to the rendered slot's `emitRealtime`. */
+  onRealtime(listener: (channel: string, payload: unknown) => void): Unsubscribe;
+  readonly host: WireFakeHost;
+  /** Committed state, versions, pauses and operation outcomes. */
+  readonly storage: StateStorageHarness<T>;
+  /** Current multi-user actor; null in single-user mode. */
+  readonly actor: (ActorSnapshot & { readonly identity: ActorReference }) | null;
+  /** Multi-user only: replace the actor. The session stamp advances and older requests are fenced. */
+  switchActor(subject: string): void;
+  /** Multi-user only: add a person the directory can search and look up. */
+  addPerson(person: { readonly subject: string; readonly name: string }): void;
+  /** The identity key of a multi-user person, for state addresses. */
+  personKey(subject: string): IdentityKey;
+  /** Another writer commits a new version (same value unless given) and the change is published. */
+  invalidateExternally(address: StateAddress, value?: T): StateEnvelope<T>;
+  /** The next `count` state loads fail as `unavailable` with retry `after-reconnect`. */
+  failNextLoads(count: number): void;
+  /** The next state save commits, then the caller sees a transport failure. */
+  loseNextSaveResponse(): void;
+  /** Hold every state load until release. */
+  holdLoads(): Pause;
+  /** Hold every state commit until release. */
+  holdSaves(): Pause;
+  /** Every identity RPC method called, in order. */
+  readonly calls: readonly string[];
+  /** Every state save input, JSON-normalized. */
+  readonly saveInputs: readonly unknown[];
+  committed(address: StateAddress): StateEnvelope<T> | null;
+  dispose(): void;
+}
+export declare function createIdentityWireFake<T>(options: IdentityWireFakeOptions<T>): IdentityWireFake<T>;
+
+/** Test registrar shared by `node:test` and `bun:test`. */
+export interface StateStorageConformanceTest {
+  (name: string, fn: () => Promise<void>): unknown;
+  skip?(name: string, fn: () => Promise<void>): unknown;
+}
+export interface OpenedStateStorage<T> {
+  readonly storage: AtomicStateStorage<T>;
+  /** Reopen the same persisted store, as after a process restart. */
+  reopen?(): Promise<AtomicStateStorage<T>> | AtomicStateStorage<T>;
+  /** True while a synchronous commit transaction is open, so the suite can prove validateAtCommit runs inside it. */
+  insideCommit?(): boolean;
+  close?(): Promise<void> | void;
+}
+export interface StateStorageConformanceOptions<T> {
+  readonly test: StateStorageConformanceTest;
+  /** Open the feature's real storage over a fresh, empty store. It must read time from `now`. */
+  open(input: { readonly now: () => number }): Promise<OpenedStateStorage<T>> | OpenedStateStorage<T>;
+  /** A state address for `recordId` in the feature's collection. */
+  address(recordId: string): StateAddress;
+  /** Two distinct feature values. */
+  readonly values: readonly [T, T];
+  readonly schemaVersion?: number;
+  /** Editor snapshot returned by validateAtCommit. */
+  readonly actor?: ActorSnapshot;
+  /** Test-name prefix; default `state storage conformance: `. */
+  readonly prefix?: string;
+  /** Record a known gap with its reason instead of running the check. */
+  readonly skip?: { readonly restart?: string };
+}
+/**
+ * Registers the AtomicStateStorage contract checks: stable empty versions, one
+ * initialize winner, unchanged and conflict outcomes, immutable address-scoped
+ * operation ids with exact replay, expiry tombstones, commit-time rejection that
+ * leaves no record or outcome, and restart durability.
+ */
+export declare function defineStateStorageConformance<T>(options: StateStorageConformanceOptions<T>): void;