@agentshouse/app-bridge 0.1.0-cfb240c3fb89d → 0.1.0-cfefe363de456

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-import type { MdRuntimeClient } from './mdruntime/client.js';
+import type { MdRuntimeClient, Open } from './mdruntime/client.js';
 import type { HouseCalls } from './calls.js';
 export type { HouseCalls } from './calls.js';
-type Open<Value extends string> = Value | (string & {});
 export type HouseCallInput<Name extends string> = Name extends keyof HouseCalls ? HouseCalls[Name] : unknown;
 export interface HouseRuntime extends Omit<MdRuntimeClient, 'call'> {
     call<Name extends Open<keyof HouseCalls>>(name: Name, input: HouseCallInput<Name>): ReturnType<MdRuntimeClient['call']>;
@@ -110,6 +109,20 @@ export interface HouseBrowserRefused extends Error {
     readonly code: string;
     readonly retryable: boolean;
 }
+export interface HouseTrialWithheld {
+    readonly code: Open<'house_trial_withheld'>;
+    readonly retryable: true;
+}
+export type HouseTask = unknown;
+export type HouseActivation = Open<'committed' | 'abandoned'>;
+export interface HouseCooperation {
+    checkpoint(): Promise<void> | void;
+    persist(): Promise<void> | void;
+    capture(): Promise<HouseTask> | HouseTask;
+    restore(task: HouseTask | null): Promise<void> | void;
+    ready(): Promise<boolean> | boolean;
+    settle(activation: HouseActivation): void;
+}
 export interface HouseBridge {
     readonly runtime: Promise<HouseRuntime>;
     address(): string | null;
@@ -130,6 +143,7 @@ export interface HouseBridge {
     onStatus(listener: (status: HouseStatus) => void): () => void;
     messages(listener: (message: HouseAppMessage) => void): () => void;
     analyticsConsent(choice: HouseAnalyticsChoice): void;
+    cooperate(cooperation: HouseCooperation): () => void;
 }
 export interface HouseHeld {
     readonly houseBridge: HouseBridge;

package/dist/mdruntime/acquisition.d.ts

@@ -0,0 +1,13 @@
+export type RuntimeDemand = {
+    readonly whole: boolean;
+    readonly rooms: readonly string[];
+    readonly handles: readonly string[];
+    readonly conversations: boolean;
+};
+export declare const WHOLE_DEMAND: RuntimeDemand;
+export declare function demanded(demand: RuntimeDemand, room: {
+    readonly locator: string;
+    readonly handle: string;
+}): boolean;
+export declare function wider(next: RuntimeDemand, current: RuntimeDemand): boolean;
+export declare function narrower(next: RuntimeDemand, current: RuntimeDemand): boolean;

package/dist/mdruntime/adapter.d.ts

@@ -238,17 +238,15 @@ export type ContractUnavailable = ProviderRefusal & {
 export type DiscoverResult = Discovery | TransportUncertainty | RevokedAuthorization | ContractUnavailable;
 export type PageToken = string;
 export type ChangeAuthor = {
-    kind: 'user';
+    kind: Open<'user' | 'site'>;
     id: string;
     name: string;
-} | {
-    kind: 'site';
+};
+export type Member = {
+    kind: Open<'user'>;
     id: string;
     name: string;
 };
-export type Member = Extract<ChangeAuthor, {
-    kind: 'user';
-}>;
 export type HeadChange = {
     author: ChangeAuthor | null;
     time: string;
@@ -446,8 +444,12 @@ export type StreamReceipts = {
     }): Promise<void>;
     drop(keys: readonly string[]): Promise<void>;
 };
+export type AcquiredDemand = {
+    rooms: readonly string[];
+    conversations: boolean;
+};
 export type RoomStream = {
-    hold(rooms: readonly HeldRoom[]): void;
+    hold(rooms: readonly HeldRoom[], demand: AcquiredDemand | null): void;
     reopen(): void;
     published(locator: string, roomVersion: string): void;
     observe(notify: (event: RoomStreamEvent) => void, receipts: StreamReceipts): () => void;

package/dist/mdruntime/client.d.ts

@@ -7,6 +7,7 @@ import type { BinaryAnswer, CallResult, HistoryAnswer, Offline, QueueEntry } fro
 import type { DocumentQuery, DocumentResult, GroupQuery, GroupResult, PendingResult } from './query.js';
 import type { RoomDraft, RoomDraftParts, RoomDraftWrite } from './room-draft.js';
 import type { SearchRequest, SearchResult } from './search.js';
+import type { Readiness } from './readiness.js';
 import type { SyncStatus } from './status.js';
 import { type RuntimePort } from './wire.js';
 export type MdRuntimeClient = {
@@ -52,9 +53,11 @@ export type MdRuntimeClient = {
     reached(locator: string, roomVersion: string, path?: string): Promise<boolean>;
     log(): Promise<string>;
     persistence(): Promise<boolean>;
+    retry(): Promise<void>;
     observe: {
         (topic: 'deployment-facts'): Promise<Observation<unknown>>;
         (topic: 'rooms'): Promise<Observation<readonly AppRoom[]>>;
+        (topic: 'readiness'): Promise<Observation<Readiness>>;
         (topic: 'connection-refusal'): Promise<Observation<ConnectionRefusal | null>>;
         (topic: 'storage-loss'): Promise<Observation<string | null>>;
         (topic: 'sync-status'): Promise<Observation<SyncStatus>>;
@@ -75,4 +78,5 @@ export type MdRuntimeClient = {
 export declare function connectMdRuntime(port: RuntimePort): MdRuntimeClient;
 export declare function inTurn(client: MdRuntimeClient, work: () => Promise<void>): Promise<void>;
 export type { Observation } from './observation.js';
-export type { RuntimePort } from './wire.js';
+export type { Open } from './open.js';
+export { unanswered, type RuntimePort, type WireMember } from './wire.js';

package/dist/mdruntime/connection.d.ts

@@ -13,6 +13,8 @@ import { type SaveRefusal } from './save.js';
 import { type RoomDraft, type RoomDraftWrite } from './room-draft.js';
 import { type SyncStatus } from './status.js';
 import { type RuntimeShell } from './durability.js';
+import { type RuntimeDemand } from './acquisition.js';
+import { type CapacityCause, type CodeAvailability, type Persistence, type Readiness, type SearchObligation } from './readiness.js';
 import { type NarrowedView, type PortReach, type RuntimeView } from './reach.js';
 export type AppTypedSelection = {
     roots: readonly string[];
@@ -99,8 +101,10 @@ export type MdRuntime = {
     reached(locator: string, roomVersion: string, path?: string): boolean;
     log(): string;
     persistence(): boolean;
+    retry(): Promise<void>;
     observe: {
         (topic: 'rooms'): Promise<Observation<readonly AppRoom[]>>;
+        (topic: 'readiness'): Promise<Observation<Readiness>>;
         (topic: 'connection-refusal'): Promise<Observation<ConnectionRefusal | null>>;
         (topic: 'storage-loss'): Promise<Observation<string | null>>;
         (topic: 'sync-status'): Promise<Observation<SyncStatus>>;
@@ -117,11 +121,19 @@ export type MdRuntime = {
     };
     reauthorize(): Promise<void>;
 };
-export type RuntimeTopic = 'rooms' | 'connection-refusal' | 'storage-loss' | 'sync-status' | 'service-mode' | 'member' | 'query' | 'queue' | 'room-drafts' | 'presentation' | 'conversation' | 'conversations' | 'agents';
+export type RuntimeTopic = 'rooms' | 'readiness' | 'connection-refusal' | 'storage-loss' | 'sync-status' | 'service-mode' | 'member' | 'query' | 'queue' | 'room-drafts' | 'presentation' | 'conversation' | 'conversations' | 'agents';
+export type ReadinessPort = {
+    readonly target: string;
+    readonly code: CodeAvailability;
+    readonly capacity: CapacityCause | null;
+    readonly search: SearchObligation;
+};
 export type ComposedRuntime = RuntimeView & {
     stop(): Promise<void>;
     lose(locators: readonly string[]): Promise<void>;
-    within(reach: PortReach | null): NarrowedView;
+    acquire(demand: RuntimeDemand): void;
+    persisted(answer: Persistence): void;
+    within(reach: PortReach | null, port: ReadinessPort): NarrowedView;
 };
 export declare function composeRuntime(options: MdRuntimeOptions): ComposedRuntime;
 export {};

package/dist/mdruntime/conversation.d.ts

@@ -86,6 +86,7 @@ export type ConversationStore = {
     catchUp(progress: CycleProgress): Promise<void>;
     resend(progress: CycleProgress): Promise<void>;
     current(): boolean;
+    known(): boolean;
     reconnected(): void;
     reopened(): void;
     watch(conversation: string, options: ConversationOptions, deliver: (view: ConversationView) => void): () => void;
@@ -99,4 +100,5 @@ export type ConversationStore = {
 };
 export declare function unheldView(conversation: string): ConversationView;
 export declare const SESSION_STARTED = "Session started";
+export declare function newChat(agent: string): string;
 export declare function createConversationStore(deps: ConversationDependencies): ConversationStore;

package/dist/mdruntime/durability.d.ts

@@ -1,8 +1,14 @@
+import type { Persistence } from './readiness.js';
+export type StorageEstimate = {
+    readonly usage: number;
+    readonly quota: number;
+};
 export type RuntimeShell = {
-    persistentStorage: boolean;
+    persistence: Persistence;
     generation: string | null;
     keepGeneration(value: string): void | Promise<void>;
     dropGeneration(): void | Promise<void>;
+    estimate?(): Promise<StorageEstimate | null>;
 };
 export declare function detectStorageLoss(stored: string | null, reported: string | null): string | null;
 export declare function nextGeneration(stored: string | null, reported: string | null): string;

package/dist/mdruntime/model.d.ts

@@ -29,12 +29,13 @@ export type ModelState = {
     types: VerifiedModel['types'];
 };
 export type TypesResult = {
-    status: 'unavailable';
+    status: Open<'unavailable'>;
     reason: ModelUnavailableReason;
+    types: null;
     schema?: string | null;
     revision?: string | null;
 } | {
-    status: 'current' | 'cached';
+    status: Open<'current' | 'cached'>;
     identity: string;
     version: string;
     verifiedWith: ModelIdentity;

package/dist/mdruntime/query.d.ts

@@ -1,6 +1,7 @@
 import { type Definition } from '../mdmodel/index.js';
 import type { HeadChange } from './adapter.js';
 import type { BinaryFileRecord } from './binary.js';
+import type { Open } from './open.js';
 export type Value = string | number | boolean | null;
 export type Predicate = Value | {
     $eq: Value;
@@ -110,7 +111,7 @@ export type QueryCoverage = {
     indexes: readonly string[];
     overlay: readonly string[];
 };
-export type Awaits = 'acquisition' | 'preparation' | 'index';
+export type Awaits = Open<'acquisition' | 'preparation' | 'index'>;
 export type PendingRoom = {
     room: string;
     awaits: Awaits;

package/dist/mdruntime/reach.d.ts

@@ -1,7 +1,8 @@
 import type { ReferrerScope } from './adapter.js';
-import type { MdRuntime, RuntimeTopic } from './connection.js';
+import type { MdRuntime, ReadinessPort, RuntimeTopic } from './connection.js';
 import type { Plan, PlanReach, QueryResult } from './query.js';
-import type { SearchResult } from './search.js';
+import type { Readiness } from './readiness.js';
+import { type SearchResult } from './search.js';
 export type ReachedDocument = {
     readonly room: string;
     readonly path: string;
@@ -19,12 +20,14 @@ export type RuntimeView = {
 };
 export type NarrowedView = RuntimeView & {
     narrow(reach: PortReach | null): void;
+    facts(port: ReadinessPort): void;
 };
 export type Reachable = RuntimeView & {
     plan(input: unknown, reach: PortReach | null): Plan;
     query(plan: Plan): Promise<QueryResult>;
     watchPlan(plan: Plan, deliver: (message: unknown) => void): () => void;
     search(input: unknown, reach: PortReach | null): Promise<SearchResult>;
+    watchReadiness(port: ReadinessPort, reach: PortReach | null, deliver: (readiness: Readiness) => void): () => void;
     referrerScope(referrer: unknown): ReferrerScope | null;
 };
 export declare function holds(reach: PortReach | null, room: string): boolean;
@@ -38,4 +41,4 @@ export declare function governs(reach: PortReach | null, room: {
     readonly selection: boolean;
 };
 export declare function planReach(reach: PortReach | null): PlanReach | null;
-export declare function narrowed(runtime: Reachable, given: PortReach | null): NarrowedView;
+export declare function narrowed(runtime: Reachable, given: PortReach | null, told: ReadinessPort): NarrowedView;

package/dist/mdruntime/readiness.d.ts

@@ -0,0 +1,52 @@
+import type { Open } from './open.js';
+export type CodeAvailability = Open<'stored' | 'absent'>;
+export type RoomPreparation = Open<'complete' | 'acquiring' | 'preparing' | 'indexing' | 'refused' | 'unadmitted'>;
+export type RoomCoverage = {
+    readonly room: string;
+    readonly state: RoomPreparation;
+};
+export type ConversationCoverage = Open<'complete' | 'acquiring' | 'indexing' | 'undeclared'>;
+export type SearchObligation = Open<'required' | 'unused'>;
+export type TargetCoverage = {
+    readonly complete: boolean;
+    readonly listed: boolean;
+    readonly rooms: readonly RoomCoverage[];
+    readonly conversations: ConversationCoverage;
+    readonly search: SearchObligation;
+};
+export type Persistence = Open<'granted' | 'denied' | 'unavailable'>;
+export type Durability = Open<'persistent' | 'best-effort'>;
+export type ConnectionAvailability = Open<'connected' | 'connecting' | 'unreachable'>;
+export type HouseOutcome = Open<'open' | 'write-halted' | 'refused'>;
+export type CapacityCause = {
+    readonly cause: Open<'insufficient-space' | 'quota-exceeded'>;
+    readonly needed: number | null;
+    readonly available: number | null;
+};
+export type RefusedRoom = {
+    readonly room: string;
+    readonly file: string;
+    readonly rule: string;
+    readonly location: string | null;
+};
+export type ReadinessStatus = Open<'preparing' | 'paused' | 'refused' | 'ready' | 'lost'>;
+export type Readiness = {
+    readonly status: ReadinessStatus;
+    readonly ready: boolean;
+    readonly usable: boolean;
+    readonly code: CodeAvailability;
+    readonly coverage: TargetCoverage;
+    readonly durability: Durability;
+    readonly persistence: Persistence;
+    readonly connection: ConnectionAvailability;
+    readonly house: HouseOutcome;
+    readonly capacity: CapacityCause | null;
+    readonly refused: readonly RefusedRoom[];
+    readonly lost: boolean;
+};
+export type ReadinessFacts = Omit<Readiness, 'status' | 'ready' | 'usable' | 'durability' | 'coverage'> & {
+    readonly coverage: Omit<TargetCoverage, 'complete'>;
+    readonly established: boolean;
+};
+export declare const SETTLED_ROOMS: ReadonlySet<string>;
+export declare function readinessOf(facts: ReadinessFacts): Readiness;

package/dist/mdruntime/room-draft.d.ts

@@ -87,7 +87,7 @@ type ChangedUnderneath = {
     readonly file?: string | null;
 };
 export type ReturnReason = ProviderRefusal & {
-    readonly kind: 'conflicted' | 'rejected' | 'expired' | 'withdrawn';
+    readonly kind: Open<'conflicted' | 'rejected' | 'expired' | 'withdrawn'>;
 };
 export declare function returnedBy(kind: 'expired' | 'withdrawn'): ReturnReason;
 export type RoomDraft = {

package/dist/mdruntime/search.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderRefusal } from './adapter.js';
 import type { ChangeSet } from './change-set.js';
 import { type CoveredRoom, type Filter, type PendingRoom } from './query.js';
 import type { Open } from './open.js';
@@ -29,18 +30,23 @@ export type SearchCoverage = {
 };
 export type PendingConversation = {
     conversation: string;
-    awaits: 'index';
-};
-export type SearchPending = {
-    pending: readonly (PendingRoom | PendingConversation)[];
+    awaits: Open<'index'>;
 };
 export type SearchHits = {
     documents: readonly DocumentHit[];
     messages: readonly MessageHit[];
 };
+export type SearchPending = SearchHits & {
+    pending: readonly (PendingRoom | PendingConversation)[];
+    coverage: SearchCoverage;
+};
+export type SearchUndeclared = ProviderRefusal & {
+    kind: 'undeclared';
+};
 export type SearchResult = (SearchHits & {
     coverage: SearchCoverage;
-}) | SearchPending;
+}) | SearchPending | SearchUndeclared;
+export declare function undeclaredSearch(): SearchUndeclared;
 export type SearchedDocument = {
     room: string;
     path: string;
@@ -77,7 +83,7 @@ export type SearchIndex = {
     search(plan: SearchPlan, documents: readonly {
         room: string;
         path: string;
-    }[] | null, conversations: readonly string[]): SearchHits;
+    }[] | null, conversations: readonly string[], rooms: ReadonlySet<string> | null): SearchHits;
 };
 export declare function searchPlanOf(input: unknown): SearchPlan;
 export declare function createSearchIndex(source: SearchSource): SearchIndex;

package/dist/mdruntime/status.d.ts

@@ -1,9 +1,13 @@
 import type { Open } from './open.js';
+import type { ProviderRefusal } from './adapter.js';
 import type { ReturnReason } from './room-draft.js';
 export type AttentionEntry = {
     room: string;
     path: string;
     returned: ReturnReason;
+} | {
+    room: string;
+    refusal: ProviderRefusal;
 };
 export type SyncStatus = {
     state: Open<'pending' | 'syncing' | 'synced'>;

package/dist/mdruntime/store.d.ts

@@ -46,6 +46,9 @@ export type PendingState = {
     readonly upload?: unknown;
     readonly accepted?: string;
 };
+export type TargetRecord = {
+    established: boolean;
+};
 export type QueueRecord = {
     locator: string;
     pending: readonly {
@@ -82,6 +85,7 @@ export type ChatDraftRecord = {
     files: readonly ChatDraftFile[];
     revision: string;
     submitted?: readonly ChatSubmission[];
+    moves?: readonly string[];
 };
 export type RecordWrite = {
     next: ReplicaRecord;
@@ -107,6 +111,8 @@ export type RuntimeStore = {
     declare(limits: readonly ProviderLimit[], capabilities: readonly Capability[]): Promise<void>;
     member(): Promise<Member | null>;
     keepMember(member: Member | null): Promise<void>;
+    targets(): Promise<Readonly<Record<string, TargetRecord>>>;
+    keepTargets(targets: Readonly<Record<string, TargetRecord>>): Promise<void>;
     queues(): Promise<readonly QueueRecord[]>;
     submit(locator: string, id: string, submission: Submission, lost: boolean): Promise<void>;
     accept(locator: string, id: string, roomVersion: string): Promise<void>;
@@ -122,7 +128,7 @@ export type RuntimeStore = {
     turnArrived(conversation: string, turn: string): Promise<boolean>;
     dropConversations(conversations: readonly string[]): Promise<void>;
     chatDrafts(): Promise<readonly ChatDraftRecord[]>;
-    keepChatDraft(record: ChatDraftRecord): Promise<void>;
+    keepChatDrafts(records: readonly ChatDraftRecord[]): Promise<void>;
     dropChatDraft(conversation: string): Promise<void>;
     keepRoomDraft(record: RoomDraftRecord): Promise<void>;
     discardRoomDraft(locator: string, path: string): Promise<void>;
@@ -149,4 +155,5 @@ export declare function authoredBy(holder: string): Promise<boolean>;
 export declare function authoredBinding(): Promise<string | null>;
 export declare function bindAuthored(binding: string): Promise<void>;
 export declare function removeRuntimeStore(holder?: string): Promise<boolean>;
+export declare function openDatabase(name: string, version: number, upgrade: (opening: IDBOpenDBRequest, oldVersion: number) => void): Promise<IDBDatabase>;
 export declare function openRuntimeStore(fenced: (locator: string) => boolean): Promise<RuntimeStore>;

package/dist/mdruntime/wire.d.ts

@@ -8,40 +8,140 @@ export type RuntimePort = {
     start(): void;
 };
 export type WireReach = 'within' | 'app' | 'runtime' | 'actions' | 'whole';
+export type WireEffect = 'read' | 'write' | 'action';
+export type WireCall = {
+    readonly reach: WireReach;
+    readonly effect: WireEffect;
+};
 declare const MEMBERS: {
-    readonly rooms: 'within';
-    readonly query: 'within';
-    readonly search: 'within';
-    readonly types: 'within';
-    readonly save: 'within';
-    readonly history: 'within';
-    readonly 'binaryFile.read': 'within';
-    readonly 'binaryFile.readReference': 'within';
-    readonly call: 'actions';
-    readonly reached: 'within';
-    readonly log: 'whole';
-    readonly persistence: 'runtime';
-    readonly reauthorize: 'runtime';
-    readonly 'roomDraft.list': 'within';
-    readonly 'roomDraft.read': 'within';
-    readonly 'roomDraft.write': 'within';
-    readonly 'roomDraft.discard': 'within';
-    readonly 'presentation.read': 'app';
-    readonly 'presentation.write': 'app';
-    readonly 'conversation.list': 'within';
-    readonly 'conversation.read': 'within';
-    readonly 'conversation.create': 'within';
-    readonly 'conversation.send': 'within';
-    readonly 'conversation.answer': 'within';
-    readonly 'conversation.interrupt': 'within';
-    readonly 'conversation.kill': 'within';
-    readonly 'conversation.cancel': 'within';
-    readonly 'conversation.delete': 'within';
-    readonly 'chatDraft.write': 'within';
-    readonly 'chatDraft.discard': 'within';
+    readonly rooms: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly query: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly search: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly types: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly save: {
+        readonly reach: 'within';
+        readonly effect: 'write';
+    };
+    readonly history: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'binaryFile.read': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'binaryFile.readReference': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly call: {
+        readonly reach: 'actions';
+        readonly effect: 'action';
+    };
+    readonly reached: {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly log: {
+        readonly reach: 'whole';
+        readonly effect: 'read';
+    };
+    readonly persistence: {
+        readonly reach: 'runtime';
+        readonly effect: 'read';
+    };
+    readonly retry: {
+        readonly reach: 'runtime';
+        readonly effect: 'write';
+    };
+    readonly reauthorize: {
+        readonly reach: 'runtime';
+        readonly effect: 'write';
+    };
+    readonly 'roomDraft.list': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'roomDraft.read': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'roomDraft.write': {
+        readonly reach: 'within';
+        readonly effect: 'write';
+    };
+    readonly 'roomDraft.discard': {
+        readonly reach: 'within';
+        readonly effect: 'write';
+    };
+    readonly 'presentation.read': {
+        readonly reach: 'app';
+        readonly effect: 'read';
+    };
+    readonly 'presentation.write': {
+        readonly reach: 'app';
+        readonly effect: 'write';
+    };
+    readonly 'conversation.list': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'conversation.read': {
+        readonly reach: 'within';
+        readonly effect: 'read';
+    };
+    readonly 'conversation.create': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.send': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.answer': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.interrupt': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.kill': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.cancel': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'conversation.delete': {
+        readonly reach: 'within';
+        readonly effect: 'action';
+    };
+    readonly 'chatDraft.write': {
+        readonly reach: 'within';
+        readonly effect: 'write';
+    };
+    readonly 'chatDraft.discard': {
+        readonly reach: 'within';
+        readonly effect: 'write';
+    };
 };
 declare const TOPICS: {
     readonly rooms: 'within';
+    readonly readiness: 'within';
     readonly 'connection-refusal': 'runtime';
     readonly 'storage-loss': 'runtime';
     readonly 'deployment-facts': 'runtime';
@@ -56,8 +156,8 @@ declare const TOPICS: {
     readonly conversations: 'within';
     readonly agents: 'within';
 };
-export declare const WIRE_REACH: {
-    readonly members: Readonly<Record<string, WireReach>>;
+export declare const WIRE: {
+    readonly members: Readonly<Record<string, WireCall>>;
     readonly topics: Readonly<Record<string, WireReach>>;
 };
 export type WireMember = keyof typeof MEMBERS;
@@ -95,6 +195,10 @@ export type WireAnswer = {
 } | {
     kind: 'ended';
 };
+export declare function unanswered(call: {
+    readonly id: number;
+    readonly member: WireMember;
+}): WireAnswer | null;
 export declare const AUTHORIZATION_ENDED = "the host authorization ended";
 export declare const PORT_CLOSED = "the port closed";
 export declare function request(message: unknown): WireRequest | null;

package/dist/test-host.d.ts

@@ -1,5 +1,5 @@
 import type { MdRuntimeClient } from './mdruntime/client.js';
-import type { HouseAnalyticsChoice, HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './index.js';
+import type { HouseActivation, HouseAnalyticsChoice, HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab, HouseTask } from './index.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
@@ -15,6 +15,9 @@ export interface HouseBridgeTestHost {
     publish(status: HouseStatus): void;
     message(message: HouseAppMessage): void;
     attachRuntime(runtime: MdRuntimeClient): void;
+    checkpoint(): Promise<HouseTask>;
+    restore(task: HouseTask | null): Promise<boolean>;
+    settle(activation: HouseActivation): void;
 }
 export interface HouseBridgeTestHostOptions {
     readonly address?: string;

package/dist/test-host.js

@@ -57,6 +57,7 @@ export function createHouseBridgeTestHost(options = {}) {
     let published = options.status ?? null;
     let shown = null;
     let seen = null;
+    let cooperation = null;
     let attached = () => { };
     const runtime = new Promise((resolve) => {
         attached = resolve;
@@ -144,7 +145,19 @@ export function createHouseBridgeTestHost(options = {}) {
             consents.push(choice);
             publish({ ...published, analytics: { measures: true, choice } });
         },
+        cooperate(given) {
+            cooperation = given;
+            return () => {
+                if (cooperation === given)
+                    cooperation = null;
+            };
+        },
     };
+    function cooperating() {
+        if (cooperation === null)
+            throw new Error('the App registered no cooperation');
+        return cooperation;
+    }
     Object.defineProperty(globalThis, 'houseBridge', { value: bridge, configurable: true });
     if (published !== null)
         publish(published);
@@ -169,5 +182,19 @@ export function createHouseBridgeTestHost(options = {}) {
         attachRuntime(client) {
             attached(client);
         },
+        async checkpoint() {
+            const held = cooperating();
+            await held.checkpoint();
+            await held.persist();
+            return JSON.parse(JSON.stringify((await held.capture()) ?? null));
+        },
+        async restore(task) {
+            const held = cooperating();
+            await held.restore(task);
+            return (await held.ready()) === true;
+        },
+        settle(activation) {
+            cooperating().settle(activation);
+        },
     };
 }

package/docs/families.md

@@ -45,6 +45,15 @@
   The App reports the visitor's choice with `analyticsConsent('accept')` or
   `analyticsConsent('decline')`; the shell hands it to House's analytics loader, and
   the choice never reaches House.
+- **Handoff** - when House hands its runtime over to a newer build, the App keeps
+  running, its `runtime` client and observations included: a call it makes
+  meanwhile waits for the newer runtime, however long that takes, and is
+  answered once, by it; each observation goes on with the newer runtime's
+  values; and the status and the address arrive again. A runtime that ended
+  before answering has its reads answered by the next one; since it may have
+  applied any other call, an act on House is answered the outcome
+  `transport-uncertainty`, and every other call, a Save or a draft write among
+  them, fails with the retryable code `transport-uncertainty`.
 - **Site image read** - given a Published Room and an original attachment
   reference, it answers the web copy's path and metadata, or `null` when no
   copy exists. The original bytes never cross this bridge at a Site.
@@ -84,6 +93,31 @@
   after its latest release, as a JPEG `Blob`, or `null` when House holds none
   or does not answer. A Site's own renderer reads none.
 
+- **Cooperation** - `cooperate({ checkpoint, persist, capture, restore,
+ready, settle })` lets House activate a newer release of the App while it
+  runs, keeping the User's task; the function it returns withdraws it.
+  Register it in the entry script, before the first draw, or House treats the
+  page as not cooperating and the newer release waits for the App's next
+  open. When a newer release is stored, House calls `checkpoint()`, which
+  resolves at the App's next safe checkpoint and may never resolve, then
+  `persist()`, which makes authored work durable, then `capture()`, which
+  answers the meaningful task the App owns, such as the selected record,
+  filters, cursor, selection and scroll position, as JSON of at most 65,536
+  characters; House keeps the address itself. In the newer release House
+  calls `restore(task)` once its document has drawn, so the scroll position
+  and focus it sets hold, or `restore(null)` when it opens the release without
+  a task, then `ready()`, the App's own check that its local data and
+  capabilities work, and finally `settle('committed')` once the release is
+  active or `settle('abandoned')` when House returns to the release before
+  it, restoring the same task there. A release House opens already active is
+  settled `'committed'` at once, after `restore(task)` when House hands it a
+  task, and a cooperation registered after House settled is settled at its
+  registration. Until `settle('committed')` House fails the release's outside
+  calls at once, as offline, those of the workers it starts included, and
+  refuses its Saves, write acts and external calls with the retryable code
+  `house_trial_withheld`, so a start-up effect is not repeated; run start-up
+  effects after `settle('committed')`.
+
 ## The test host
 
 `createHouseBridgeTestHost(options)` plays House in one page: it installs a
@@ -106,4 +140,7 @@ given by Site identifier, answers every `install()` `'manual'`, as a browser
 with no install prompt does, answers every `notifications()` `'unavailable'`,
 as a browser without push does, settles every `setBadge`, delivers each App
 message `message({ from, body })` plays, and hands `bridge.runtime` the MD
-Runtime client `attachRuntime(client)` gives it.
+Runtime client `attachRuntime(client)` gives it. `checkpoint()` runs the
+registered cooperation's checkpoint, persist and capture and answers the task,
+`restore(task)` runs its restore and answers its readiness check, and
+`settle(activation)` hands it the outcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-cfb240c3fb89d",
+  "version": "0.1.0-cfefe363de456",
   "description": "Types of the agents.house App bridge House hands every App: navigation, the tab title and icon, ceremonies, installation, notifications and the icon badge, status, Site image reads, App release code, App and Site screenshot reads, and App messages, with an accessor and an in-page test host.",
   "license": "MIT",
   "type": "module",