@deepseek-ai/dsh-client-test-runtime 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/types/assembly/bundle-roster.d.ts

@@ -0,0 +1,15 @@
+import { ClientRoster } from './roster.ts';
+/** The `web` profile's bundle layers, in the order `dsh --profile web` applies them (app-boot `PROFILE_TEMPLATES.web`). */
+export declare const WEB_PROFILE_BUNDLES: readonly string[];
+/**
+ * Compose the browser roster of `bundles`, applied in order.
+ * @param bundles - bundle package names in application order.
+ * @param anchor - file whose package resolution locates the bundles; default this package.
+ * @returns the roster in composition order, one row per package.
+ * @throws {Error} when a bundle, its patch file, or an enabled row's package does not resolve, when the patch list
+ * is not a list or does not apply as written, or when a browser row's `disabled` is a `!!js` expression.
+ */
+export declare function bundleRoster(bundles: readonly string[], anchor?: string): ClientRoster;
+/** The `web` profile's browser roster, composed from its bundles at import. */
+export declare const webApp: ClientRoster;
+//# sourceMappingURL=bundle-roster.d.ts.map

package/lib/types/assembly/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whole-client tier entry (deep import only:
+ * `@deepseek-ai/dsh-client-test-runtime/src/assembly/index.ts`). Kept out of
+ * the package root so slot-tier specs do not load the assembly machinery.
+ * @module @deepseek-ai/dsh-client-test-runtime/src/assembly
+ */
+export { ClientRoster } from './roster.ts';
+export type { AssemblyPlan, ClientPluginModule, ClientRosterRow } from './roster.ts';
+export { TestClient } from './test-client.ts';
+export type { TestClientOptions } from './test-client.ts';
+export { remoteDefaultResponses } from './remote-default-responses.ts';
+export { bundleRoster, webApp } from './bundle-roster.ts';
+export { createClientTest } from './vitest.ts';
+export type { ClientTestFixtures } from './vitest.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/assembly/modules.d.ts

@@ -0,0 +1,25 @@
+import type { ClientModuleLoader, WebBootGraph } from '@deepseek-ai/dsh-client-modules/client';
+import type { AssemblyPlan, ClientPluginModule } from './roster.ts';
+/** The bootstrap row: always this process's static namespace, never a dynamic import or a `provide` replacement. */
+export declare const MODULES_PACKAGE = "@deepseek-ai/dsh-client-modules";
+/**
+ * Resolve each roster row to its plugin module: `plan.provide[name]` when
+ * present, otherwise a `/client` import resolved by the repository's tsconfig
+ * path aliases under Vitest. The bootstrap row is the
+ * statically imported `@deepseek-ai/dsh-client-modules/client` namespace.
+ * @param plan - validated plan.
+ * @returns package name → module, in roster order.
+ * @throws {Error} when an import fails (the package name prefixes the original message) or the bootstrap row is provided.
+ */
+export declare function loadPluginModules(plan: AssemblyPlan): Promise<ReadonlyMap<string, ClientPluginModule>>;
+/**
+ * Build the production module system over queued factories returning the
+ * loaded namespaces. The bootstrap row uses `bootstrapModule`; `staticModules`
+ * is empty because namespaces already hold their own imports. Missing factories
+ * reject through `loadBundle` without fetching.
+ * @param graph - raw boot graph from `graphFromRoster`; `createClientModuleSystem` parses it.
+ * @param modules - loaded plugin modules keyed by package name.
+ * @returns module system to install as `loader.internal`; its `manifest` is the parsed graph.
+ */
+export declare function createInProcessModules(graph: WebBootGraph, modules: ReadonlyMap<string, ClientPluginModule>): ClientModuleLoader;
+//# sourceMappingURL=modules.d.ts.map

package/lib/types/assembly/remote-default-responses.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default responses for every Remote endpoint the web assembly calls while
+ * booting and rendering with no sessions, no workspaces, and default settings.
+ * The comment above each row names the plugin that calls it; endpoints boot
+ * never touches stay absent so a new call fails loud. `$events` is built into
+ * `RemoteMock`.
+ * @module @deepseek-ai/dsh-client-test-runtime/src/assembly/remote-default-responses
+ */
+import { type RemoteTable } from '@deepseek-ai/dsh-remote-mock';
+/** Default responses of the boot-time Remote endpoints; a spec loads it first and layers its own table on top. */
+export declare const remoteDefaultResponses: RemoteTable;
+//# sourceMappingURL=remote-default-responses.d.ts.map

package/lib/types/assembly/remote-proxies.d.ts

@@ -0,0 +1,20 @@
+import type { RemoteMock } from '@deepseek-ai/dsh-remote-mock';
+import type { ClientPluginModule } from './roster.ts';
+/** The assembly row the proxies stand in for; its generated clients exist only in built `lib/`. */
+export declare const REMOTES_PACKAGE = "@deepseek-ai/dsh-api-remotes";
+/**
+ * Namespaces to provide: every `remote.<ns>` a roster module injects, plus the
+ * namespace of every endpoint the mock has a rule for.
+ * @param modules - loaded roster modules.
+ * @param mock - the spec's mock.
+ * @returns sorted namespace names.
+ */
+export declare function remoteNamespacesOf(modules: Iterable<ClientPluginModule>, mock: RemoteMock): readonly string[];
+/**
+ * Plugin providing the namespace proxies; `TestClient.start` mounts it before the Loader rows.
+ * @param namespaces - namespaces to provide.
+ * @param mock - the spec's mock, asked for each endpoint's mode.
+ * @returns the plugin.
+ */
+export declare function remoteProxiesPlugin(namespaces: readonly string[], mock: RemoteMock): ClientPluginModule;
+//# sourceMappingURL=remote-proxies.d.ts.map

package/lib/types/assembly/roster.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Client roster: the ordered package-name rows a whole-client test boots, and
+ * the plan that annotates one with the rows the test provides itself. `webApp`
+ * and `bundleRoster` (`./bundle-roster.ts`) read rosters from the bundle patch
+ * files; a spec may also build one inline with {@link ClientRoster.of}.
+ * @module @deepseek-ai/dsh-client-test-runtime/src/assembly/roster
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebBootGraph } from '@deepseek-ai/dsh-client-modules/client';
+/** One browser plugin row as `dsh.client` declares it, keyed by package name. */
+export interface ClientRosterRow {
+    /** Package name (== manifest entry id == Loader entry name). */
+    readonly name: string;
+    /** Package-name dependency edges from `dsh.client.inject` ([] when absent). */
+    readonly inject: readonly string[];
+    /** Stage-one prefetch mark from `dsh.client.immediately` (false when absent). */
+    readonly immediately: boolean;
+}
+/**
+ * Synthesize the raw `WebBootGraph` for `rows`: one `application` batch
+ * holding every row, `rev: 'local'`, placeholder `/plugins/<name>/client.js`
+ * URLs, since every module is seeded in process and never fetched. Validation
+ * stays with the production `parseBootManifest` inside the module system:
+ * duplicate names and an empty roster are rejected there, not here.
+ * @param rows - roster rows in composition order.
+ * @returns the unparsed graph, as `createClientModuleSystem` consumes it.
+ */
+export declare function graphFromRoster(rows: readonly ClientRosterRow[]): WebBootGraph;
+/** Immutable, name-addressable roster. */
+export declare class ClientRoster {
+    readonly rows: readonly ClientRosterRow[];
+    /**
+     * Build a roster from rows; duplicate names throw.
+     * @param rows - roster rows in composition order.
+     * @returns roster.
+     */
+    static of(rows: readonly ClientRosterRow[]): ClientRoster;
+    private constructor();
+    /**
+     * Keep only `names`, preserving roster order; an unknown name throws with the roster listed.
+     * @param names - package names to keep.
+     * @returns sub-roster.
+     */
+    pick(names: readonly string[]): ClientRoster;
+    /**
+     * The named rows plus every row they inject, transitively, in roster order: the rows a spec needs to boot the
+     * named plugins as the bundle composes them. The shell's platform modules (`PLATFORM_MODULES`, seeded statically
+     * rather than loaded as rows) end the walk. An unknown name throws with the roster listed; a row injecting any
+     * other package outside the roster throws, since the bundle itself would not boot.
+     * @param names - package names whose dependency cone to keep.
+     * @returns sub-roster.
+     */
+    closure(names: readonly string[]): ClientRoster;
+    /**
+     * Drop `names`; an unknown name throws with the roster listed.
+     * @param names - package names to drop.
+     * @returns sub-roster.
+     */
+    without(names: readonly string[]): ClientRoster;
+    private known;
+}
+/** The module face the Loader materializes for one client plugin row. */
+export interface ClientPluginModule {
+    apply(ctx: Context, config?: unknown): unknown;
+    readonly inject?: readonly string[] | Readonly<Record<string, unknown>>;
+    readonly Config?: unknown;
+}
+/** What to boot and what the test supplies itself. */
+export interface AssemblyPlan {
+    readonly roster: ClientRoster;
+    /** Row replacements by package name (the test's own implementation of that row). Names outside the roster throw. */
+    readonly provide?: Readonly<Record<string, ClientPluginModule>>;
+}
+/**
+ * Validate a plan against its roster.
+ * @param plan - plan to check.
+ * @throws {Error} naming any `provide` key outside the roster.
+ */
+export declare function assertPlan(plan: AssemblyPlan): void;
+//# sourceMappingURL=roster.d.ts.map

package/lib/types/assembly/test-client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Whole-client test carrier: boots an {@link AssemblyPlan} through the
+ * production `bootClient` over an in-process module table, with a
+ * `RemoteMock` bound to that client's Connection plugin instance.
+ * @module @deepseek-ai/dsh-client-test-runtime/src/assembly/test-client
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { type ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client';
+import type { RemoteMock } from '@deepseek-ai/dsh-remote-mock';
+import { type AssemblyPlan } from './roster.ts';
+/** Carrier options. */
+export interface TestClientOptions {
+    /**
+     * Mount `uiRenderer` into an element (a fresh `document.body` child when `true`); requires jsdom and a roster
+     * that provides `uiRenderer`. Default false.
+     */
+    readonly mount?: boolean | HTMLElement;
+    /** Wait for `ctx.connection.state === 'connected'` before returning. Default true. */
+    readonly awaitConnected?: boolean;
+    /** Readiness budget in milliseconds before `start` rejects with the mock log summary. Default 5000. */
+    readonly connectTimeoutMs?: number;
+}
+/** A booted client under test. */
+export declare class TestClient {
+    readonly ctx: Context;
+    readonly mock: RemoteMock;
+    readonly container: HTMLElement | undefined;
+    private readonly restore;
+    /**
+     * Load the roster's modules, bind this client's mock to its Connection row,
+     * hold the jsdom shims, and boot through `bootClient` over the synthesized
+     * boot graph; afterwards optionally mount and wait for the connection. The
+     * bound row replaces only the page-global input adapter: both paths call
+     * `installConnection`, while this path supplies the mock carrier, uses
+     * default recovery timings, and captures the current page hostname once for
+     * later reloads. A caller-provided Connection row remains unchanged and owns
+     * its readiness behavior. The `@deepseek-ai/dsh-api-remotes` row is
+     * dropped from the roster: its generated Remote clients exist only in built
+     * `lib/`, and the `remote.<ns>` services the roster injects (plus the
+     * namespaces the mock has rules for at this point) are provided as
+     * contract-free proxies over the same Connection instead; a `provide` entry
+     * for that row is refused. On any failure the context is disposed, an owned
+     * mount removed, and this client's hold on the shims released before the
+     * original error is rethrown.
+     * @param plan - roster and annotations.
+     * @param mock - Remote mock answering every Gateway call.
+     * @param options - mount and readiness options.
+     * @returns the booted client.
+     */
+    static start(plan: AssemblyPlan, mock: RemoteMock, options?: TestClientOptions): Promise<TestClient>;
+    private disposing;
+    private constructor();
+    /** The roster's Connection service (no `Context` augmentation declares it); throws when the roster provides none. */
+    get connection(): ConnectionHandle;
+    /** Flush pending React work and microtasks inside `act` (plain microtask flush without a DOM). */
+    flush(): Promise<void>;
+    /**
+     * Rebuild one Loader entry: Client Modules' registry-first fiber teardown, then
+     * `entry.refresh()`. Each client's module table retains its own instance-bound
+     * Connection plugin, so reloads do not coordinate through process globals.
+     * Requires a live client: after `dispose()` the Loader holds no entries and
+     * the lookup throws before teardown.
+     * @param name - package name of the row.
+     */
+    reload(name: string): Promise<void>;
+    /**
+     * Remove one Loader entry and wait for its plugin cleanup.
+     * @param name - package name of the row.
+     */
+    unload(name: string): Promise<void>;
+    /**
+     * Dispose the plugin tree, then drop an owned mount and release this
+     * client's hold on the shared jsdom shims even when the tree fails to dispose,
+     * then `mock.assertNoUnmatched()` last so its failure is the test's reason
+     * without skipping the cleanup; when both the tree and the check fail, one
+     * error carries both messages. The first call owns the teardown and reports
+     * its failure; every later call waits for that teardown and resolves.
+     */
+    dispose(): Promise<void>;
+    private teardown;
+    private entryOf;
+}
+//# sourceMappingURL=test-client.d.ts.map

package/lib/types/assembly/vitest.d.ts

@@ -0,0 +1,24 @@
+/** Test-scoped Remote mock and lazy client boot, owned by native Vitest fixtures. */
+import { type TestAPI } from 'vitest';
+import { RemoteMock, type MockedRemote } from '@deepseek-ai/dsh-remote-mock';
+import type { AssemblyPlan } from './roster.ts';
+import { TestClient, type TestClientOptions } from './test-client.ts';
+/** Per-test controls; configure the mock before awaiting `start()`. */
+export interface ClientTestFixtures {
+    /** Fresh mock with the assembly's default responses already loaded. */
+    mock: RemoteMock;
+    /** Namespace proxy backed by the same native mocks used by the Connection carrier. */
+    remote: MockedRemote;
+    /** Await the one client owned by this test; rejects after the fixture closes. */
+    start: () => Promise<TestClient>;
+}
+/**
+ * Extend Vitest with a fresh mock and a lazy, automatically disposed client. Repeated `start()` calls share one
+ * promise. Await it to observe startup failures; cleanup waits for startup but does not rethrow its rejection.
+ * Missing mock responses still fail teardown even when no client was started. Page globals remain environment-owned.
+ * @param plan - roster and replacement modules, shared as configuration rather than as a running client.
+ * @param options - mount and readiness settings passed to `TestClient.start`.
+ * @returns Vitest's test function with test-scoped `mock` and `start` fixtures.
+ */
+export declare function createClientTest(plan: AssemblyPlan, options?: TestClientOptions): TestAPI<ClientTestFixtures>;
+//# sourceMappingURL=vitest.d.ts.map

package/lib/types/fixtures.d.ts

@@ -44,6 +44,8 @@ export interface SessionFixture {
     events?: readonly SessionEventLikeEntry[];
     /** Whether the initial event window has an older page. */
     hasMore?: boolean;
+    /** Optional shared initial-opening barrier for the fixture's Client generation. */
+    initialOpen?: (signal: AbortSignal) => void | Promise<void>;
 }
 /**
  * A complete quiescent Session Controller snapshot.

package/lib/types/index.d.ts

@@ -16,9 +16,11 @@ import type { RenderResult } from '@testing-library/react';
 import type { queries } from '@testing-library/dom';
 import type { BoundFunctions } from '@testing-library/dom';
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client';
+import type { SessionReference } from '@deepseek-ai/dsh-api-session-controller/client';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { PanelInfo } from '@deepseek-ai/dsh-client-ui-layout/client';
-import type { ChildrenDecl, ComposedProps, HostObservable, OwnerOf, RenderOpts, SlotComponent, SlotMap, SlotRenderer, SnapshotSelectorHook, StoreInstanceLike } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ChildrenDecl, ComposedProps, HostObservable, OwnerOf, RenderOpts, SlotComponent, SlotMap, SlotRenderer, SlotFactoryMap, SnapshotSelectorHook, StoredFactory, StoreInstanceLike } from '@deepseek-ai/dsh-client-ui-slots';
+import { TestRemote } from './remote.ts';
 import { TestSessions } from './sessions.ts';
 import { TestWorkspaces } from './workspaces.ts';
 import type { Stabilizer } from './fixtures.ts';
@@ -27,8 +29,6 @@ export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot
 export { FixtureSession, TestSessions } from './sessions.ts';
 export { stubSettingsScope } from './settings-scope.ts';
 export type { StubSettingsScope } from './settings-scope.ts';
-export { scriptedSettingsRemote } from './settings-remote.ts';
-export type { ScriptedNamespace, ScriptedSettingsRemote } from './settings-remote.ts';
 export { TestWorkspaces } from './workspaces.ts';
 export { RemoteError, TestRemote } from './remote.ts';
 export { chatSnapshot, conversationSnapshot, sessionSnapshot, workspaceSnapshot, } from './fixtures.ts';
@@ -46,6 +46,10 @@ export declare function bindSnapshotSelector<T>(source: HostObservable<T>): Snap
  * @returns Slot renderer instance.
  */
 export declare function createSlotRenderer(): SlotRenderer;
+/** Per-view render options; the caller owns the explicitly supplied Session reference. */
+export interface SlotTestRenderOptions extends RenderOpts {
+    readonly session?: SessionReference | undefined;
+}
 /**
  * One rendered slot's local view, from {@link SlotTestRuntime.renderSlot}:
  * the renderer's own `[data-slot]` outlet anchor is the snapshot root
@@ -62,8 +66,9 @@ export interface SlotView<K extends keyof SlotMap & string> {
      * Replace the owner props and flush the re-render (the render-site update:
      * in production the owner recomputes the share and React re-renders).
      * @param owner - the next owner props share.
+     * @param opts - replacement render options and borrowed reference; omission keeps this view's options.
      */
-    update(owner: OwnerOf<K>): void;
+    update(owner: OwnerOf<K>, opts?: SlotTestRenderOptions): void;
 }
 /**
  * Mounted feature plugin handle: the live fiber plus an act-wrapped,
@@ -81,8 +86,6 @@ export interface FeatureHandle {
 }
 /** Mutable fail-loud file-upload stub installed by {@link SlotTestRuntime}. */
 export interface TestFileUpload {
-    /** Availability reported to the feature under test. */
-    available: boolean;
     /** Test-supplied upload behavior; the default rejects every call. */
     upload: (sessionId: SessionId, ...args: unknown[]) => Promise<unknown>;
 }
@@ -125,8 +128,10 @@ export declare class SlotTestRuntime {
     readonly slots: SlotRegistry;
     /** The test-owned 'root' occupant. */
     readonly root: TestRoot;
-    /** Sessions double (list/current observable, cells, scopes, behavior faces). */
+    /** Fixture catalog, explicit references, scoped contexts, and behavior faces. */
     readonly sessions: TestSessions;
+    /** One Remote double shared by every feature mounted in this runtime. */
+    readonly remote: TestRemote;
     /** Workspaces double (list observable, recorded intent actions). */
     readonly workspaces: TestWorkspaces;
     /** Test-owned panel selection used by the framework's usePanelInfo hook. */
@@ -188,20 +193,26 @@ export declare class SlotTestRuntime {
      * slot of the same tree.
      * @param key - a key declared through {@link SlotTestRuntime.declare}.
      * @param owner - owner props share for the render site.
-     * @param opts - explicit keyed or list selection; retained by view updates.
+     * @param opts - explicit entry selection and borrowed Session reference; retained by view updates.
      * @returns the slot-local view (snapshot container, scoped queries, owner updates).
      */
-    renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>, opts?: RenderOpts): SlotView<K>;
+    renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>, opts?: SlotTestRenderOptions): SlotView<K>;
     /**
      * Resolve the store instance the renderer would hand a slot's component
      * (identity assertions, action-driven writes). Requires a prior
      * {@link SlotTestRuntime.renderRoot} — the host face exists only inside the
      * installed renderer, exactly as in production.
      * @param key - slot key whose first entry declares the store.
-     * @param scopeKey - session id for session-scope slots; omit for root scope.
+     * @param session - retained Session reference for session-scope slots; omit for root scope.
      * @returns the live store instance.
      */
-    storeOf(key: keyof SlotMap & string, scopeKey?: string): StoreInstanceLike;
+    storeOf(key: keyof SlotMap & string, session?: SessionReference): StoreInstanceLike;
+    /**
+     * Read one registered Factory definition for direct contract assertions.
+     * @param name - registered Factory name.
+     * @returns the live Factory definition.
+     */
+    factoryOf(name: keyof SlotFactoryMap & string): StoredFactory;
     /**
      * Flush pending ledger/store notifications inside act — for mutations made
      * outside the runtime's own methods (e.g. a direct `slots.register`).

package/lib/types/remote.d.ts

@@ -19,6 +19,7 @@ export { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
  * against the real service.
  */
 export declare class TestRemote {
+    private readonly ctx;
     private readonly subscriptions;
     /**
      * Fixed Host facts mirrored from the production `ctx.remote.$host`. Plain
@@ -35,6 +36,13 @@ export declare class TestRemote {
      * @param namespaces - scripted namespace faces reached as `ctx.remote.<name>`.
      */
     constructor(ctx: Context, namespaces?: Readonly<Record<string, object>>);
+    /**
+     * Add scripted namespace faces to this Remote service.
+     * @param namespaces - scripted namespace faces reached as `ctx.remote.<name>`.
+     */
+    provideNamespaces(namespaces: Readonly<Record<string, object>>): void;
+    private validateNamespaces;
+    private installNamespaces;
     /**
      * Deliver one forwarded host event to its subscribers, standing in for the
      * carrier that owns the frame sink.

package/lib/types/sessions.d.ts

@@ -2,11 +2,18 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { AttachmentIdType } from '@deepseek-ai/dsh-attachment';
 import { MutableSessionEventSource } from '@deepseek-ai/dsh-api-session-controller/client';
-import type { AgentContext, ISessions, ProjectionsFace, SessionBinding, SessionFace, SessionListState, SessionEventLikeEntry, SessionLiveEventEntry, SessionSearchResultItem, SessionSnapshot, SessionSummary, SubmissionHandle } from '@deepseek-ai/dsh-api-session-controller/client';
+import type { AgentContext, ISessions, ProjectionsFace, SessionBinding, SessionFace, SessionListState, SessionEventLikeEntry, SessionLiveEventEntry, SessionSearchResultItem, SessionReference, SessionRetainInfo, SessionRetainOptions, SessionSnapshot, SessionSummary, SessionTarget, SubmissionHandle } from '@deepseek-ai/dsh-api-session-controller/client';
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client';
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { SessionFixture, SessionFixtureSnapshot, Stabilizer } from './fixtures.ts';
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+    interface SessionReferenceSourceMap {
+        testFixture: unknown;
+        testView: unknown;
+        testOperation: unknown;
+    }
+}
 /**
  * The fixture-backed session face: lifecycle reads delegate to the fixture's
  * snapshot store; Session verbs are fail-loud stubs unless the
@@ -91,24 +98,29 @@ export declare class FixtureSession implements SessionFace {
 }
 /**
  * Sessions test double behind the renderer host and feature injects: owns the
- * list/current observable, scope minting through the production `createScope`,
+ * catalog observable, scope minting through the production `createScope`,
  * stable Controller bindings, and the session behavior face supplied per
  * fixture. `ui-session` owns standard-source materialization.
  *
  * Implements the same ISessions face features receive as `ctx.sessions`, so
  * a production face change breaks this double at compile time; the extra
- * members (add/updateSessionSnapshot/event-window drivers/setCurrent/remove/
+ * members (add/updateSessionSnapshot/event-window drivers/remove/
  * behavior/calls/stubs) are bench-only surface.
  */
 export declare class TestSessions implements ISessions {
     private readonly stabilize;
     private readonly rootCtx;
-    /** The useSessions standard feed (list rows + current selection). */
+    /** The useSessions catalog feed, independent of view ownership. */
     readonly list: SnapshotStore<SessionListState>;
     private readonly records;
+    private readonly generations;
+    private readonly addresses;
+    private readonly retentionStores;
+    private readonly pendingDrops;
+    private closed;
     /** Calls observed on the service-level face, newest last. */
     readonly calls: {
-        method: 'create' | 'open' | 'openSubagent' | 'setSubagentCatalogOpen' | 'refreshSubagents' | 'clear' | 'refresh' | 'search' | 'fork';
+        method: 'create' | 'setSubagentCatalogOpen' | 'refreshSubagents' | 'refresh' | 'search' | 'fork';
         args: unknown[];
     }[];
     /** The wire schema's `session.search` result bound (production parity). */
@@ -122,20 +134,24 @@ export declare class TestSessions implements ISessions {
      */
     constructor(stabilize: Stabilizer, rootCtx: Context);
     /**
-     * Add a session from a fixture and (by default) make it current.
+     * Add a Session fixture to the catalog without retaining a generation.
      * @param fixture - identity + snapshot/summary overrides + behavior face.
-     * @param opts - pass `current: false` to add without selecting.
      * @returns the stable session id (branded view of `fixture.id`).
      */
-    add(fixture: SessionFixture, opts?: {
-        current?: boolean;
-    }): Promise<SessionId>;
+    add(fixture: SessionFixture): Promise<SessionId>;
     /**
      * Update Session Controller lifecycle state through an immer draft.
      * @param id - session id.
      * @param mutate - draft mutator.
      */
     updateSessionSnapshot(id: string, mutate: (draft: SessionFixtureSnapshot) => void): Promise<void>;
+    /**
+     * Publish one complete projection value through the fixture Session face.
+     * @param id - session id.
+     * @param key - registered projection key.
+     * @param value - complete value for that key.
+     */
+    setProjection(id: string, key: string, value: unknown): Promise<void>;
     /**
      * Replace a Session's complete contiguous event window.
      * @param id - Session identity.
@@ -164,31 +180,33 @@ export declare class TestSessions implements ISessions {
      */
     updateSummary(id: string, patch: Partial<Omit<SessionSummary, 'id'>>): Promise<void>;
     /**
-     * Switch the current selection (undefined = the no-session empty state).
-     * @param id - session id to select, or undefined to clear.
-     */
-    setCurrent(id: string | undefined): Promise<void>;
-    /**
-     * Remove a session: list row, scope fiber, and per-session store instances
-     * (with persisted state) die together — the same single lifecycle axis the
-     * production Client Sessions service drives on session death, minus staging.
+     * Remove a catalog row and mark its retained Session removed without releasing owners.
      * @param id - session id.
      */
     remove(id: string): Promise<void>;
     /**
-     * Resolve (mint on first touch) the session-scoped Cordis context through
-     * the production `createScope`, so real `scopeOf`/scope-addressed services
-     * resolve it.
+     * Borrow the already-retained session-scoped Cordis context.
      * @param id - session id.
-     * @returns the scoped context, or undefined for unknown sessions.
+     * @returns the scoped context, or undefined without a live reference.
      */
     scope(id: string): AgentContext | undefined;
     /**
      * Session assembly binding (inject factories and provide resolvers receive it).
      * @param id - session id.
-     * @returns sessionId + behavior face + scoped ctx, or undefined when unknown.
+     * @returns the live generation's binding, or undefined without a reference.
      */
     binding(id: string): SessionBinding | undefined;
+    retain(target: SessionTarget, options?: SessionRetainOptions): SessionReference;
+    using<T>(target: SessionTarget, options: SessionRetainOptions, operation: (reference: SessionReference) => T | Promise<T>): Promise<T>;
+    retainInfo(id: SessionId): ObservableSnapshot<SessionRetainInfo>;
+    /**
+     * Retain one fixture Session until the supplied Cordis owner stops.
+     * @param ownerCtx - context whose disposal releases the reference.
+     * @param target - fixture Session identity or subagent address.
+     * @param options - reference source and optional readiness cancellation.
+     * @returns the owned reference immediately.
+     */
+    retainFor(ownerCtx: Context, target: SessionTarget, options?: SessionRetainOptions): SessionReference;
     /**
      * Read the session scope tag off a context (service-method boundary mirror).
      * @param ctx - any client context.
@@ -207,25 +225,14 @@ export declare class TestSessions implements ISessions {
      * @param impl - implementation that must return an already-added fixture id.
      */
     stubCreate(impl: (opts: Parameters<ISessions['create']>[0]) => Promise<SessionId>): void;
-    /** Create through the installed test behavior and require an addressable binding. */
+    /** Create through the installed test behavior and require a catalogued fixture. */
     create(opts?: Parameters<ISessions['create']>[0]): Promise<SessionId>;
-    /**
-     * Service-level selection call (recorded, then applied to the list store
-     * synchronously — inject callbacks call this outside any act window; the
-     * store notify is microtask-batched so the next stabilized step observes it).
-     * @param id - session id.
-     */
-    open(id: SessionId): void;
-    /** Open an existing fixture through its catalog address. */
-    openSubagent(address: SubagentAddress): void;
-    /** Resolve the current fixture's retained catalog address. */
+    /** Resolve a retained or catalog-derived address independently of a view. */
     subagentAddress(id: SessionId): SubagentAddress | undefined;
     /** Record catalog consumption; fixture callers drive snapshots explicitly. */
     setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
     /** Record a catalog refresh; fixture callers drive snapshots explicitly. */
     refreshSubagents(parentSessionId: SessionId): Promise<void>;
-    /** Clear the current selection (recorded; the production no-session flow). */
-    clear(): void;
     /** Record a list refresh; fixture callers publish list state explicitly. */
     refresh(): Promise<void>;
     /**
@@ -265,7 +272,14 @@ export declare class TestSessions implements ISessions {
     behavior(id: string): FixtureSession;
     /** Dispose minted scope fibers (runtime dispose path). */
     disposeScopes(): Promise<void>;
-    private bindingOf;
+    private resolveTarget;
+    private retainGeneration;
+    private retentionSnapshot;
+    private publishRetention;
+    private materialize;
+    private startOpening;
+    private drop;
+    private drainDrops;
     private require;
 }
 //# sourceMappingURL=sessions.d.ts.map

package/lib/types/workspaces.d.ts

@@ -84,6 +84,12 @@ export declare class TestWorkspaces implements IWorkspaces {
      * @param sessionId - session to archive.
      */
     archiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unarchive a session (recorded). The default mirrors the production face's
+     * observable effect: the id leaves the list state's archive set.
+     * @param sessionId - session to unarchive.
+     */
+    unarchiveSession(sessionId: SessionId): Promise<void>;
 }
 export {};
 //# sourceMappingURL=workspaces.d.ts.map