@phosphorco/bb-identity 0.1.0

package/host.d.ts

@@ -0,0 +1,277 @@
+/** Integration ports. Raw fork protocol is structural and independent of package brands. */
+import type { AcceptanceOutcome, ActorReference, ActorSnapshot, Codec, Contribution, ContributionReference,
+  Directory, Disposable, ExecutionProvenance, IdentityError, IdentityProfile, InstanceId, OperationLookup,
+  ParticipantReader, PersonReference, PluginId, ProfilePresentation, ProviderGeneration, IssuerId, ReadOptions, RequestExpectation,
+  Result, Scheduler, SendInput, SessionStamp, Unsubscribe, Wire } from './model.js';
+
+declare const requestLease: unique symbol;
+export interface IdentityCapabilities {
+  readonly requestIdentity: 'singleton' | 'host-resolved';
+  readonly acceptance: 'pre-dispatch-check' | 'transactional-check';
+  readonly forwarding: 'singleton-convention' | 'host-bound';
+  readonly directory: { readonly search: boolean; readonly lookup: boolean };
+  readonly participants: boolean;
+  readonly externalSend: 'source-labelled' | 'structured';
+  readonly toolProvenance: 'unknown' | 'partial' | 'causal';
+  readonly operationLookup: boolean;
+}
+/** Wire DTO; loading/disposed are local client states, not server session responses. */
+export type ServerSession =
+  | { readonly status: 'ready'; readonly instanceId: InstanceId; readonly mode: 'single-user' | 'multi-user';
+      readonly actor: ActorSnapshot & { readonly identity: ActorReference };
+      readonly stamp: SessionStamp; readonly capabilities: IdentityCapabilities }
+  | { readonly status: 'unauthenticated' | 'unavailable' | 'incompatible'; readonly instanceId: InstanceId; readonly error: IdentityError };
+export declare const serverSessionCodec: Codec<ServerSession>;
+/** Same-process, synchronous validation only; callers must not span an await or process boundary. */
+export interface LiveRequest {
+  readonly [requestLease]: true;
+  readonly signal: AbortSignal;
+  readonly session: Extract<ServerSession, { status: 'ready' }>;
+  validate(expected: RequestExpectation): Result<void>;
+  /** Releases this adapter-owned scope only; never the shared host service. */
+  release(): void;
+}
+export type HostInvalidation =
+  | { readonly kind: 'session'; readonly reason: 'actor' | 'provider' | 'capabilities' }
+  | { readonly kind: 'directory'; readonly keys: readonly string[] }
+  | { readonly kind: 'participants'; readonly threadIds: readonly string[] }
+  | { readonly kind: 'disconnected' | 'reconnected' | 'disposed' };
+export interface ExternalAuthorInput { readonly subject: string; readonly presentation: ProfilePresentation; }
+export interface IdentityHost<RequestContext, ToolContext, Input> extends Disposable {
+  readonly pluginId: PluginId;
+  readonly instanceId: InstanceId;
+  session(context: RequestContext, options?: ReadOptions): Promise<ServerSession>;
+  /** Resolves the request's current actor from its live session; directory capability is not required. */
+  selfProfile(context: RequestContext, options?: ReadOptions): Promise<Result<IdentityProfile>>;
+  openPersonRequest(context: RequestContext, options?: ReadOptions): Promise<Result<LiveRequest>>;
+  readToolProvenance(context: ToolContext): Promise<Result<ExecutionProvenance>>;
+  readonly directory: Directory;
+  readonly participants: ParticipantReader;
+  readonly history: import('./model.js').ProvenanceReader;
+  /** Checks synchronously before upstream dispatch; enhanced host checks again inside acceptance. */
+  send(request: LiveRequest, input: SendInput<Input>, options?: ReadOptions): Promise<AcceptanceOutcome>;
+  sendExternal(author: ExternalAuthorInput, input: SendInput<Input>, options?: ReadOptions): Promise<AcceptanceOutcome>;
+  lookupOperation(operationId: SendInput<Input>['operationId'], options?: ReadOptions): Promise<Result<OperationLookup<AcceptanceOutcome>>>;
+  forward(request: LiveRequest, destinationPlugin: string, method: string, input: import('./model.js').Json): Promise<unknown>;
+  registerProvider(provider: IdentityProvider): Promise<Result<ProviderRegistrationV1>>;
+  subscribe(listener: (event: HostInvalidation) => void): Unsubscribe;
+}
+/** Upstream driver is implemented by /bb, not by each feature. Host namespaces use reserved local storage scope. */
+export interface UpstreamDriver<RequestContext, ToolContext, Input> {
+  readonly instanceId: InstanceId;
+  readonly pluginId: PluginId;
+  readonly inputCodec: Codec<Input>;
+  readonly scheduler: Scheduler;
+  session(context: RequestContext): Promise<ServerSession>;
+  selfProfile(context: RequestContext, options?: ReadOptions): Promise<Result<IdentityProfile>>;
+  openScope(context: RequestContext): Promise<Result<HostRequestHandle>>;
+  /** Native response only; driver cannot promise request lifecycle checks inside upstream's transaction. */
+  submit(input: SendInput<Input>, options?: ReadOptions): Promise<AcceptanceOutcome>;
+  labelExternal(author: ExternalAuthorInput, input: readonly Input[]): readonly Input[];
+  toolCorrelation(context: ToolContext): ExecutionProvenance;
+  /** Ordinary SDK RPC; validates locally before dispatch, without original-request propagation. */
+  forward(context: RequestContext, destinationPlugin: string, method: string,
+    input: import('./model.js').Json, options?: ReadOptions): Promise<unknown>;
+  subscribe(listener: (event: HostInvalidation) => void): Unsubscribe;
+}
+
+/** Host-owned, structural in-process object. Not JSON, not a package-private symbol or public credential. */
+export interface HostRequestHandle {
+  readonly signal: AbortSignal;
+  readonly session: Wire<Extract<ServerSession, { status: 'ready' }>>;
+  validate(expected: Wire<RequestExpectation>): Wire<Result<void>>;
+  release(): void;
+}
+/** Core dispatch classes; route selection does not select a person actor. */
+export type ForkInvocationRouteClass =
+  | 'interactive-session' | 'external-credential' | 'anonymous'
+  | 'plugin-background' | 'agent-tool' | 'local-cli';
+/** Fresh per invocation. It is not a provider/plugin generation registration or auth lease. */
+export interface ForkInvocationScope {
+  readonly signal: AbortSignal;
+  validate(): { readonly ok: true } | { readonly ok: false; readonly code: 'retired' | 'invalidated' };
+  release(): void;
+}
+/** Enhanced open-request result. Core returns the request-scoped lifecycle signal for this request/session. */
+export interface ForkRequestHandle extends HostRequestHandle {
+  readonly scope: ForkInvocationScope;
+}
+/** Opaque dispatcher context; only the registered returned handler receives it. */
+export interface ForkInvocationContext<RequestContext> {
+  readonly request: RequestContext; readonly scope: ForkInvocationScope;
+}
+/** Generation-bound dispatch binding. Disposal is exact-generation conditional. */
+export interface ForkInvocationRegistration extends Disposable {
+  readonly generation: string; readonly status: 'staged' | 'active' | 'retired';
+}
+/** One acceptance entry point prevents external work from masquerading as a person scope. */
+export type ForkAcceptanceRequest<Input> = {
+  readonly source:
+    | { readonly kind: 'scope'; readonly scope: ForkInvocationScope }
+    | { readonly kind: 'external'; readonly author: ExternalAuthorInput };
+  readonly input: Wire<SendInput<Input>>;
+};
+/** Core-owned in-process registration result. It deliberately has no package brands.
+ * The adapter normalizes this to ProviderRegistrationV1 before exposing it to provider authors.
+ */
+export interface ForkProviderRegistration extends Disposable {
+  readonly generation: string;
+  readonly configuration: Readonly<ProviderBoundaryConfigurationV1>;
+  getStatus(): 'staged' | 'active' | 'retired';
+  readonly signal: AbortSignal;
+  subscribe(listener: (status: 'staged' | 'active' | 'retired') => void): Unsubscribe;
+  invalidate(change: { readonly kind: 'authentication'; readonly subjects?: readonly { readonly issuer: string; readonly subject: string }[] }
+    | { readonly kind: 'directory'; readonly revision: string }): Result<void>;
+  /** Successful values use plain strings at the core boundary; adapter brands only after validation. */
+  person(issuer: string, subject: string): Wire<Result<PersonReference>>;
+}
+/** Core-facing provider input. It intentionally has no package-private generation brand. */
+export interface ForkIdentityProvider {
+  readonly issuers: readonly string[];
+  readonly validateReadiness?: (input: { readonly generation: string;
+    readonly configuration: Readonly<ProviderBoundaryConfigurationV1>;
+    readonly deadlineAt: number; readonly signal: AbortSignal }) => Promise<Wire<Result<void>>>;
+  resolve(evidence: ProviderEvidenceV1): Promise<Wire<
+    | { readonly status: 'resolved'; readonly issuer: string; readonly subject: string; readonly presentation: ProfilePresentation }
+    | { readonly status: 'not-applicable' }
+    | { readonly status: 'rejected' | 'unavailable'; readonly reason: string }
+  >>;
+  directory?(input: { readonly query: string; readonly cursor?: string; readonly limit: number;
+    readonly history: 'current' | 'include-historical' }, options?: ReadOptions): Promise<Wire<Result<{
+      readonly records: readonly ProviderDirectoryRecord[]; readonly nextCursor: string | null; readonly revision: string;
+    }>>>;
+  lookup?(subjects: readonly { readonly issuer: string; readonly subject: string }[], options?: ReadOptions): Promise<Wire<Result<{
+    readonly revision: string; readonly records: readonly {
+      readonly issuer: string; readonly subject: string; readonly record: ProviderDirectoryRecord | null;
+    }[];
+  }>>>;
+}
+/** Core implements these host-owned operations, not IdentityHost's fallback/directory composition. */
+export interface ForkIdentityProtocolV1<RequestContext, ToolContext, Input> {
+  readonly version: 1;
+  /** Persisted core storage namespace; stable across plugin replacement and never request-derived. */
+  readonly instanceId: string;
+  /** Enables this plugin generation's producer-owned external message rendering in the SDK host. */
+  experimental_useProducerMessageRendering?(): void;
+  /** /bb installs exactly the returned handler through native RPC/HTTP registration after schema
+   * validation. Core supplies the request-scoped context and its lifecycle signal out of band.
+   */
+  bindInvocation<Args extends readonly unknown[], Output>(
+    input: { readonly routeClass: ForkInvocationRouteClass;
+      readonly handler: (context: ForkInvocationContext<RequestContext>, ...args: Args) => Output }
+  ): { readonly registration: ForkInvocationRegistration; readonly handler: (...args: Args) => Output };
+  session(context: RequestContext): Promise<Wire<ServerSession>>;
+  selfProfile(context: RequestContext, options?: ReadOptions): Promise<Wire<Result<IdentityProfile>>>;
+  openRequest(context: RequestContext): Promise<Result<ForkRequestHandle>>;
+  /** Checks source scope/live request during durable acceptance; retained receipts remain queryable after the request ends. */
+  accept(input: ForkAcceptanceRequest<Input>, options?: ReadOptions): Promise<Wire<AcceptanceOutcome>>;
+  lookup(operationId: string, options?: ReadOptions): Promise<Wire<Result<OperationLookup<AcceptanceOutcome>>>>;
+  provenance(context: ToolContext): Promise<Wire<Result<ExecutionProvenance>>>;
+  historyContributions(query: Wire<import('./model.js').ContributionQuery>, options?: ReadOptions): Promise<Wire<Result<import('./model.js').EvidencePage<Contribution>>>>;
+  historyAttempts(query: Wire<import('./model.js').AttemptQuery>, options?: ReadOptions): Promise<Wire<Result<import('./model.js').EvidencePage<ExecutionProvenance>>>>;
+  /** Borrowed provider callbacks; package composes/searches/normalizes them with default/external profiles. */
+  directorySources(): readonly ProviderDirectorySource[];
+  participants(input: Wire<import('./model.js').ParticipantQuery>, options?: ReadOptions): Promise<Wire<Awaited<ReturnType<ParticipantReader['list']>>>>;
+  /** RPC-only forwarding fences the original scope and destination generation before and after work. */
+  forwardRpc(scope: ForkInvocationScope, destination: { readonly pluginId: string; readonly method: string },
+    input: import('./model.js').Json): Promise<unknown>;
+  registerProvider(provider: ForkIdentityProvider): Promise<Result<ForkProviderRegistration>>;
+  subscribe(listener: (event: HostInvalidation) => void): Unsubscribe;
+}
+export type ExtensionDiscovery<R, T, I> =
+  | { readonly status: 'absent' }
+  | { readonly status: 'supported'; readonly protocol: ForkIdentityProtocolV1<R, T, I> }
+  | { readonly status: 'unsupported-version'; readonly version: number }
+  | { readonly status: 'malformed'; readonly error: IdentityError };
+/** The only optional fork discovery member. It is read from a trusted SDK host object, never browser data. */
+export interface ForkIdentityExtensionSurface { readonly experimental_p6rIdentity?: unknown; }
+/** Runs against trusted experimental_p6rIdentity property value, never a browser payload. */
+export declare function inspectForkExtension<R, T, I>(value: unknown): ExtensionDiscovery<R, T, I>;
+export declare function createHostAdapter<R, T, I>(options: {
+  readonly upstream: UpstreamDriver<R, T, I>;
+  readonly extension: ExtensionDiscovery<R, T, I>;
+  readonly directory?: Directory;
+}): IdentityHost<R, T, I>;
+
+/** Operator-owned selection; supplied by host configuration, never by request payload or provider.
+ * Credential names are allowlisted here; providers receive only this boundary's selected evidence.
+ */
+export interface ProviderBoundaryConfigurationV1 {
+  readonly version: 1; readonly boundaryId: string; readonly pluginId: string;
+  readonly ingressIds: readonly string[];
+  readonly credentials: readonly { readonly name: string; readonly source: 'header' | 'cookie'; readonly field: string }[];
+  readonly resolver: { readonly timeoutMs: number };
+}
+/** In-process envelope: credentials await provider verification, transport facts are host-established.
+ * Never log/persist credentials in profiles, bootstrap, provenance, or generic event payloads.
+ */
+export interface ProviderEvidenceV1 {
+  readonly version: 1; readonly configuration: ProviderBoundaryConfigurationV1;
+  readonly request: { readonly authority: string; readonly method: string; readonly pathname: string;
+    readonly transport: 'http' | 'websocket'; readonly receivedAt: number };
+  readonly ingress: { readonly id: string | null; readonly kind: 'owned-proxy' | 'local' | 'unverified';
+    readonly authenticatedPeer: string | null };
+  readonly credentials: readonly { readonly name: string; readonly value: string }[];
+  readonly deadlineAt: number;
+  readonly signal: AbortSignal;
+}
+export interface ProviderDirectoryRecord {
+  readonly issuer: string; readonly subject: string; readonly presentation: ProfilePresentation;
+  readonly status: 'current' | 'historical';
+}
+export interface IdentityProvider {
+  readonly issuers: readonly IssuerId[];
+  /** Optional provider-local readiness. Host structural/configuration checks are mandatory.
+   * It receives no request evidence or credentials and cannot resolve an actor.
+   */
+  readonly validateReadiness?: (input: { readonly generation: ProviderGeneration;
+    readonly configuration: Readonly<ProviderBoundaryConfigurationV1>;
+    readonly deadlineAt: number; readonly signal: AbortSignal }) => Promise<Result<void>>;
+  resolve(evidence: ProviderEvidenceV1): Promise<
+    | { readonly status: 'resolved'; readonly issuer: string; readonly subject: string; readonly presentation: ProfilePresentation }
+    | { readonly status: 'not-applicable' }
+    | { readonly status: 'rejected' | 'unavailable'; readonly reason: string }
+  >;
+  /** Issuer/subject records are normalized into keys by the package; providers do not invent codecs. */
+  directory?(input: { readonly query: string; readonly cursor?: string; readonly limit: number; readonly history: 'current' | 'include-historical' }, options?: ReadOptions): Promise<Result<{
+    readonly records: readonly ProviderDirectoryRecord[]; readonly nextCursor: string | null; readonly revision: string;
+  }>>;
+  /** Revisions/cursors belong to a provider generation and directory snapshot. Stale cursors fail
+   * explicitly; outages are errors, never empty/missing. Reject undeclared issuer records.
+   */
+  lookup?(subjects: readonly { readonly issuer: string; readonly subject: string }[], options?: ReadOptions): Promise<Result<{
+    readonly revision: string; readonly records: readonly {
+    readonly issuer: string; readonly subject: string; readonly record: ProviderDirectoryRecord | null;
+  }[] }>>;
+}
+export interface ProviderDirectorySource {
+  readonly issuers: readonly string[];
+  readonly generation: string;
+  readonly directory?: NonNullable<IdentityProvider['directory']>;
+  readonly lookup?: NonNullable<IdentityProvider['lookup']>;
+  person(issuer: string, subject: string): Wire<Result<PersonReference>>;
+}
+/** Atomic activation belongs to the enhanced host; failure retains old generation, sockets reauthenticate.
+ * Disposal is generation-scoped. Provider removal yields unavailable, never absent-capability singleton mode.
+ */
+/** Package-normalized registration; request lifecycle remains separate from provider state. */
+export interface ProviderRegistrationV1 extends Disposable {
+  readonly generation: ProviderGeneration;
+  /** Registration during factory execution stages a candidate, it does not wait for activation.
+   * Host commits replacement only after plugin activation succeeds; failed candidates are cleaned up
+   * while prior provider resources remain live. Stale disposal/invalidation cannot affect a successor.
+   */
+  getStatus(): 'staged' | 'active' | 'retired';
+  /** Read-only non-secret configuration captured for this generation's readiness validation. */
+  readonly configuration: Readonly<ProviderBoundaryConfigurationV1>;
+  readonly signal: AbortSignal;
+  subscribe(listener: (status: 'staged' | 'active' | 'retired') => void): Unsubscribe;
+  /** Authentication invalidation updates provider enrichment; it does not by itself block ordinary work.
+   * Directory changes do not alone change actors.
+   */
+  invalidate(change: { readonly kind: 'authentication'; readonly subjects?: readonly { readonly issuer: string; readonly subject: string }[] }
+    | { readonly kind: 'directory'; readonly revision: string }): Result<void>;
+  person(issuer: IssuerId, subject: string): Result<PersonReference>;
+  /** Removes only this generation's registration when it is still current; never retires the plugin generation. */
+  dispose(): void;
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+/** @phosphorco/bb-identity: portable values only. Runtime-specific APIs use explicit subpaths. */
+export type * from './model.js';
+export { idCodec, newOperationId, identityKeyCodec, profileCodec, provenanceCodec, defaultIdentityKey } from './model.js';

package/model.d.ts

@@ -0,0 +1,231 @@
+/** Shared serializable vocabulary. No React, BB SDK, storage, or provider imports. */
+declare const identityKey: unique symbol;
+declare const opaqueId: unique symbol;
+export type IdentityKey = string & { readonly [identityKey]: true };
+export type Id<Kind extends string> = string & { readonly [opaqueId]: Kind };
+export type InstanceId = Id<'instance'>;
+export type PluginId = Id<'plugin'>;
+export type ThreadId = Id<'thread'>;
+export type ContributionId = Id<'contribution'>;
+export type OperationId = Id<'operation'>;
+export type Revision = Id<'revision'>;
+export type Cursor = Id<'cursor'>;
+export type OwnerSessionId = Id<'owner-session'>;
+/** Identifies one reviewed divergence within an owner-controller incarnation. */
+export type ConflictToken = Id<'conflict'>;
+/** Host-issued opaque provider generation; it is not activation authority. */
+export type ProviderGeneration = Id<'provider-generation'>;
+/** Issuers are stable provider identifiers; canonical identity construction remains host-owned. */
+export type IssuerId = string;
+export type SessionStamp = Id<'server-session'>;
+/** Freshness assertion only; not a credential. Rotates on actor/provider discontinuity, including A→B→A. */
+export interface RequestExpectation { readonly actor: IdentityKey; readonly session: SessionStamp; }
+export type TargetSelection = { readonly kind: 'self' } | { readonly kind: 'person'; readonly key: IdentityKey };
+/** Injected by bindings/tests; no hidden clock in timed primitives. */
+export interface Scheduler {
+  now(): number;
+  schedule(delayMs: number, callback: () => void): Unsubscribe;
+}
+/** Serializable counterpart for a structural host protocol; preserves literal discriminants. */
+export type Wire<T> = T extends IdentityKey | Id<string> ? string
+  : T extends readonly (infer V)[] ? readonly Wire<V>[]
+  : T extends object ? { readonly [K in keyof T]: Wire<T[K]> } : T;
+
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };
+export type Unsubscribe = () => void;
+export interface Disposable { dispose(): void; }
+export interface ReadOptions { readonly signal?: AbortSignal; }
+
+/** Expected failures are values. Implementations may still throw programmer errors. */
+export interface IdentityError {
+  readonly code: 'unavailable' | 'unauthenticated' | 'unsupported' | 'incompatible'
+    | 'invalid-input' | 'not-found' | 'ambiguous' | 'stale-owner' | 'stale-context'
+    | 'conflict' | 'cancelled' | 'disposed' | 'limit-exceeded' | 'invalid-operation' | 'expired';
+  readonly message: string;
+  readonly retry: 'never' | 'after-refresh' | 'after-reconnect' | 'same-operation';
+}
+export type Result<T> = { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: IdentityError };
+
+/** Codecs validate bounds/canonical form at runtime; casts are not validation. */
+export interface Codec<T> {
+  decode(input: unknown): Result<T>;
+  encode(value: T): Json;
+}
+/** Validates a bounded ID at an SDK/wire boundary; IDs are never authority tokens. */
+export declare function idCodec<Kind extends string>(kind: Kind): Codec<Id<Kind>>;
+export declare function newOperationId(): OperationId;
+export declare const identityKeyCodec: Codec<IdentityKey>;
+export declare const profileCodec: Codec<IdentityProfile>;
+export declare const provenanceCodec: Codec<ExecutionProvenance>;
+/** Singleton belongs to host state, not the browser or package installation. */
+export declare function defaultIdentityKey(instance: InstanceId): IdentityKey;
+
+export interface ProfilePresentation {
+  readonly displayName: string;
+  readonly handle: string | null;
+  readonly avatarUrl: string | null;
+}
+export type IdentityReference =
+  | { readonly kind: 'person'; readonly key: IdentityKey; readonly issuer: string; readonly subject: string }
+  | { readonly kind: 'default-user'; readonly key: IdentityKey; readonly instanceId: InstanceId }
+  | { readonly kind: 'machine'; readonly key: IdentityKey; readonly instanceId: InstanceId; readonly hostId: string | null }
+  | { readonly kind: 'external'; readonly key: IdentityKey; readonly pluginId: PluginId; readonly subject: string };
+/** Human/default identities remain valid person selections; machine actors are separate. */
+export type PersonReference = Extract<IdentityReference, { kind: 'person' | 'default-user' }>;
+/** An actor that can own a request or self-scoped state, including machine fallback. */
+export type ActorReference = PersonReference | Extract<IdentityReference, { kind: 'machine' }>;
+export type MachineReference = Extract<IdentityReference, { kind: 'machine' }>;
+export interface IdentityProfile {
+  readonly identity: IdentityReference;
+  readonly presentation: ProfilePresentation;
+  readonly revision: Revision;
+  readonly status: 'current' | 'historical';
+}
+export interface ActorSnapshot {
+  readonly identity: IdentityReference;
+  readonly presentation: ProfilePresentation;
+  /** Historical evidence, never permission to perform a later action. */
+  readonly evidence: 'provider-verified' | 'local-user' | 'upstream-default' | 'integration-asserted' | 'legacy' | 'machine';
+}
+export type Origin =
+  | { readonly kind: 'person'; readonly actor: ActorSnapshot & { readonly identity: PersonReference } }
+  | { readonly kind: 'machine'; readonly actor: ActorSnapshot & { readonly identity: MachineReference } }
+  | { readonly kind: 'external'; readonly actor: ActorSnapshot & { readonly identity: Extract<IdentityReference, { kind: 'external' }> } }
+  | { readonly kind: 'agent'; readonly agentId: string | null }
+  | { readonly kind: 'system'; readonly reason: string }
+  | { readonly kind: 'unknown'; readonly reason: 'legacy' | 'upstream-unattributed' | 'missing-source' };
+export interface ContributionReference {
+  readonly threadId: ThreadId;
+  readonly contributionId: ContributionId;
+}
+/** A contribution is independent of delivery grouping and execution attempts. */
+export interface Contribution {
+  readonly reference: ContributionReference;
+  readonly author: Origin;
+  readonly latestEditor: ActorSnapshot | null;
+  readonly acceptedAt: string;
+  readonly mentionedPeople: readonly PersonReference[];
+}
+export type AttemptInputSource =
+  | { readonly kind: 'contribution'; readonly reference: ContributionReference }
+  | { readonly kind: 'interaction'; readonly interactionId: string; readonly resolver: Origin }
+  | { readonly kind: 'generated'; readonly purpose: 'continuation' | 'resolved-resource' | 'system-context';
+      readonly basedOn: readonly ContributionReference[] };
+/** Ordered delivery groups; an individual group can contain multiple original/generated sources. */
+export interface AttemptInputGroup { readonly sources: readonly AttemptInputSource[]; }
+export interface ExecutionCorrelation {
+  readonly threadId: ThreadId;
+  readonly turnId: string;
+  readonly attemptId: string;
+  readonly toolCallId: string | null;
+}
+/** Native identifiers are opaque; lookup never guesses from text or the latest author. */
+export type ContributionQuery = (
+  | { readonly kind: 'references'; readonly references: readonly ContributionReference[] }
+  | { readonly kind: 'native-message'; readonly threadId: ThreadId; readonly messageId: string }
+  | { readonly kind: 'native-event'; readonly threadId: ThreadId; readonly eventId: string }
+) & {
+  /** Cursor is bound to this exact query and retained-history snapshot. */
+  readonly cursor?: Cursor;
+  readonly limit?: number;
+};
+export type EvidencePage<T> =
+  | { readonly status: 'known' | 'partial'; readonly items: readonly T[]; readonly nextCursor: Cursor | null;
+      /** Traversal completeness is distinct from known/partial evidence. */
+      readonly traversal: 'complete' | 'continued'; readonly missing: readonly string[] }
+  | { readonly status: 'pending' }
+  | { readonly status: 'unavailable'; readonly reason: 'unsupported' | 'missing-history' | 'outage' };
+export type AttemptQuery = ({ readonly kind: 'operation'; readonly operationId: OperationId }
+  | { readonly kind: 'contribution'; readonly reference: ContributionReference }) & {
+    readonly cursor?: Cursor; readonly limit?: number;
+  };
+/** Bounded reads: 100 references, default 50/max 200 attempts. Known has no missing facts.
+ * Each attempt preserves execution-time snapshots. A queued operation may be pending;
+ * a known empty result is authoritative only within retained coverage, never inferred upstream.
+ */
+export interface ProvenanceReader {
+  contributions(query: ContributionQuery, options?: ReadOptions): Promise<Result<EvidencePage<Contribution>>>;
+  attempts(query: AttemptQuery, options?: ReadOptions): Promise<Result<EvidencePage<ExecutionProvenance>>>;
+}
+/** Snapshots are fixed when the attempt accepts input, unaffected by later edits.
+ * Known: every referenced contribution appears exactly once in contributions, with no unresolved causal source.
+ * Partial: missing references are explicit. Consumers never choose the first/latest author as a substitute.
+ */
+export type ExecutionProvenance =
+  | { readonly status: 'known'; readonly correlation: ExecutionCorrelation;
+      readonly inputGroups: readonly AttemptInputGroup[]; readonly contributions: readonly Contribution[] }
+  | { readonly status: 'partial'; readonly correlation: ExecutionCorrelation | null;
+      readonly inputGroups: readonly AttemptInputGroup[]; readonly contributions: readonly Contribution[];
+      readonly missing: readonly ContributionReference[]; readonly reason: string }
+  | { readonly status: 'unknown'; readonly correlation: ExecutionCorrelation | null; readonly reason: string };
+export interface Page<T> {
+  readonly items: readonly T[];
+  readonly nextCursor: Cursor | null;
+  /** Cursors are bound to the same query and snapshot; a stale cursor errors. */
+  readonly revision: Revision;
+}
+export interface PageRequest { readonly cursor?: Cursor; readonly limit: number; }
+export interface DirectoryQuery extends PageRequest {
+  readonly query: string; readonly kinds: readonly IdentityReference['kind'][];
+  readonly history: 'current' | 'include-historical';
+}
+export interface ProfileQuery { readonly keys: readonly IdentityKey[]; }
+export interface ParticipantQuery extends PageRequest { readonly threadId: ThreadId; }
+export interface ParticipantPreviewQuery { readonly threadIds: readonly ThreadId[]; readonly perThreadLimit: number; }
+export interface Directory {
+  search(input: DirectoryQuery, options?: ReadOptions): Promise<Result<Page<IdentityProfile>>>;
+  getMany(input: ProfileQuery, options?: ReadOptions): Promise<Result<readonly ProfileLookup[]>>;
+  /** Invalidations, not an unbounded global roster broadcast. */
+  subscribe(keys: readonly IdentityKey[], listener: (event: DirectoryInvalidation) => void): Unsubscribe;
+}
+export type ProfileLookup = { readonly key: IdentityKey; readonly status: 'found'; readonly profile: IdentityProfile }
+  | { readonly key: IdentityKey; readonly status: 'missing' };
+/** `null` is an explicit conservative reset when the producer has no authoritative directory revision. */
+export interface DirectoryInvalidation { readonly keys: readonly IdentityKey[]; readonly revision: Revision | null; }
+export interface Participant {
+  readonly identity: IdentityReference;
+  readonly presentation: ProfilePresentation;
+  readonly roles: readonly ('author' | 'editor' | 'mentioned' | 'interaction-resolver')[];
+}
+/** Deduplicated people/external identities from retained visible durable history; aggregates roles.
+ * Excludes queue-only drafts. Mentioned-only identities need no fabricated authorship evidence.
+ */
+export interface ParticipantReader {
+  list(input: ParticipantQuery, options?: ReadOptions): Promise<Result<Page<Participant> & { readonly coverage: 'complete-history' | 'partial-history' }>>;
+  /** Bounded preview per thread; hasMore prevents interpreting truncation as absence. */
+  previews(input: ParticipantPreviewQuery, options?: ReadOptions): Promise<Result<readonly {
+    readonly threadId: ThreadId; readonly participants: readonly Participant[]; readonly hasMore: boolean;
+    readonly coverage: 'complete-history' | 'partial-history'; readonly revision: Revision;
+  }[]>>;
+}
+
+export interface NativeSubmissionIds {
+  readonly deliveryId: string | null; readonly queuedMessageId: string | null;
+  readonly turnId: string | null;
+}
+export type AcceptanceReceipt =
+  | { readonly evidence: 'host-accepted'; readonly operationId: OperationId; readonly acceptedAt: string;
+      readonly references: readonly ContributionReference[]; readonly native: NativeSubmissionIds;
+      readonly provenance: 'structured'; readonly deduplication: 'guaranteed'; readonly retainedUntil: string }
+  | { readonly evidence: 'upstream-response'; readonly operationId: OperationId;
+      readonly acceptedAt: null; readonly references: null; readonly native: NativeSubmissionIds;
+      readonly provenance: 'source-labelled' | 'upstream-default'; readonly deduplication: 'not-guaranteed' };
+/** Upstream successful submission does not fabricate exact native acceptance evidence. */
+export type AcceptanceOutcome =
+  | { readonly status: 'submitted'; readonly receipt: AcceptanceReceipt }
+  | { readonly status: 'rejected'; readonly error: IdentityError }
+  | { readonly status: 'indeterminate'; readonly operationId: OperationId; readonly message: string };
+export type OperationLookup<Outcome> =
+  | { readonly status: 'final'; readonly outcome: Outcome }
+  | { readonly status: 'pending' }
+  | { readonly status: 'absent-final'; readonly retry: 'same-operation-only' }
+  | { readonly status: 'unknown'; readonly reason: 'unsupported' | 'expired' | 'unavailable' };
+export interface SendInput<Input> {
+  readonly operationId: OperationId;
+  readonly threadId: ThreadId;
+  readonly input: readonly Input[];
+  /** `auto` steers active work and starts idle work; it is never normalized by this package. */
+  readonly mode: 'auto' | 'start' | 'steer-if-active' | 'queue-if-active';
+}
+export interface PersonSendInput<Input> extends SendInput<Input> { readonly expected: RequestExpectation; }

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@phosphorco/bb-identity",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Portable identity, provenance, and state contracts for BB integrations.",
+  "author": "Phosphor",
+  "homepage": "https://github.com/phosphorco/bb-community-plugins/tree/main/packages/bb-identity#readme",
+  "bugs": {
+    "url": "https://github.com/phosphorco/bb-community-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phosphorco/bb-community-plugins.git",
+    "directory": "packages/bb-identity"
+  },
+  "keywords": [
+    "bb",
+    "identity",
+    "provenance",
+    "state"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index-runtime.js"
+    },
+    "./model": {
+      "types": "./model.d.ts",
+      "import": "./dist/model-runtime.js"
+    },
+    "./host": {
+      "types": "./host.d.ts",
+      "import": "./dist/host-runtime.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./dist/server-runtime.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "import": "./dist/testing-runtime.js"
+    },
+    "./state": {
+      "types": "./state.d.ts",
+      "import": "./dist/state-runtime.js"
+    },
+    "./bb": {
+      "types": "./bb.d.ts",
+      "import": "./dist/bb-entry-runtime.js"
+    },
+    "./client": {
+      "types": "./client.d.ts",
+      "import": "./dist/client-entry-runtime.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./dist/react-entry-runtime.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "index.d.ts",
+    "model.d.ts",
+    "host.d.ts",
+    "server.d.ts",
+    "testing.d.ts",
+    "client.d.ts",
+    "state.d.ts",
+    "bb.d.ts",
+    "react.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "peerDependencies": {
+    "@get-bb/plugin-sdk": "^0.4.15 || ^0.5.9",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@get-bb/plugin-sdk": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@get-bb/plugin-sdk": "0.5.29",
+    "@playwright/test": "1.63.0",
+    "@types/bun": "1.3.14",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "bun": "1.3.14",
+    "react": "19.2.1",
+    "react-dom": "19.2.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "bun build index-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build model-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build host-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build server-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build testing-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build state-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build bb-entry-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build client-entry-runtime.ts --outdir dist --target browser --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build react-entry-runtime.ts --outdir dist --target browser --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build state-service-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build state-controller-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\" && bun build state-transport-runtime.ts --outdir dist --target bun --format esm --external \"react\" --external \"react/*\" --external \"react-dom\" --external \"react-dom/*\" --external \"@get-bb/plugin-sdk\" --external \"@get-bb/plugin-sdk/*\" --external \"zod\"",
+    "test": "bun test ./type-tests/*.runtime.test.ts ./type-tests/*.runtime.test.mjs ./type-tests/client-runtime.test.mjs && node --experimental-strip-types --experimental-loader ./type-tests/source-ts-loader.mjs --test ./type-tests/portable-binding-acceptance.node.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "browser-check": "PLAYWRIGHT_BROWSERS_PATH=0 bun ./type-tests/browser/run.mts"
+  }
+}