super-dsh 0.3.0-a → 0.3.0-d

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/extensions.zh.md

@@ -1,382 +0,0 @@
-# 扩展
-
-[English](extensions.md) | 中文
-
-extensions 子系统允许 agent（智能体）定义带版本的 Cordis 包、运行其 host 与浏览器两半，并在编写代码前查询获准公开的运行时元数据。包生命周期与沙箱行为由 [`packages/extensions`](../../packages/extensions/README.zh.md) 包组说明。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxcordisinspect--cordisinspectregistryservice"></a>
-
-### `ctx.cordisInspect` — `CordisInspectRegistryService`
-
-Registry and cross-page router behind the two model-facing inspect tools.
-
-```ts cordis-catalog
-/**
- * Register one Host provider.
- * @param registration - manifest and local query handler.
- * @returns idempotent disposer.
- */
-register(registration: HostCordisInspectProviderRegistration): () => void
-
-/**
- * Replace the mirrored Client provider directory.
- * @param providers - complete Client manifest snapshot.
- */
-syncClientManifest(providers: readonly CordisInspectProviderManifest[]): void
-
-/**
- * Return the complete known Host and Client provider directory.
- * @returns Host providers followed by the Client providers.
- */
-list(): CordisInspectProviderView[]
-
-/**
- * Execute one provider query on its owning platform.
- * @param platform - Host or Client runtime.
- * @param providerId - provider selected from {@link list}.
- * @param methodName - declared method name.
- * @param input - optional lossless JSON input.
- * @param agent - requesting Agent and scope.
- * @param signal - tool-call cancellation.
- * @returns provider JSON data.
- */
-async query( platform: CordisInspectPlatform, providerId: string, methodName: string, input: JsonValue | undefined, agent: Agent, signal: AbortSignal, ): Promise<JsonValue>
-
-/**
- * Accept the first valid Client response for a pending query.
- * @param agent - Agent whose Session owns the query.
- * @param requestId - Pending Client query identity.
- * @param resolution - Client provider result or failure.
- * @returns whether this response settled the still-pending query.
- */
-resolveClientQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/extensions/cordis-host-runner/src/inspect-registry.ts`](../../packages/extensions/cordis-host-runner/src/inspect-registry.ts)
-
-<a id="ctxdynamiccordisrunner--dynamiccordisrunnerservice"></a>
-
-### `ctx.dynamicCordisRunner` — `DynamicCordisRunnerService`
-
-Dynamic Plugin registry and Host-half lifecycle.
-
-```ts cordis-catalog
-/**
- * Define a new Plugin's first Package or append a Package to an existing Plugin.
- * @param request - Session ownership, Plugin selection, metadata, and source code.
- * @returns Host-minted Plugin and Package identities with declared-half metadata.
- */
-define(request: DynamicCordisDefineRequest): DynamicCordisDefineReceipt
-
-/**
- * Remove a Plugin, its active run, and all immutable Packages.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity to remove.
- * @returns Whether removal succeeded and whether it stopped an active run.
- */
-async undefine(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisUndefineReceipt>
-
-/**
- * Remove a Plugin from the user panel and queue the resulting state change for the model's next step.
- * @param agent - Agent whose Session owns the Plugin and receives the context.
- * @param pluginId - Stable Plugin identity to remove.
- * @returns Whether removal succeeded and whether it stopped an active run.
- */
-@Remote('undefineFromPanel') async undefineFromPanel(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisUndefineReceipt>
-
-/**
- * Start or update one Package for a model tool call. An unauthorized Client
- * Package waits for approval; Plugin-wide authorization covers later versions.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity to activate.
- * @param packageId - Immutable Package version to activate.
- * @param mode - Whether to run the current version or switch versions.
- * @param signal - Tool-call cancellation signal while the activation request is being created.
- * @returns The successful activation identity or an actionable refusal.
- */
-async run( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, mode: CordisDynamicRunMode, signal?: AbortSignal, ): Promise<DynamicCordisRunResponse>
-
-/**
- * Start Host code for an approved request or a direct panel gesture.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity to activate.
- * @param packageId - Immutable Package version to activate.
- * @param mode - Whether to run the current version or switch versions.
- * @param requestId - Model-driven request identity, or null for a direct user gesture.
- * @param approveFutureVersions - Whether this approval covers later Packages of the same Plugin.
- * @returns The exact Host activation or a failure message.
- */
-@Remote('runHostHalf') async runHostHalf( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, mode: CordisDynamicRunMode, requestId: ApprovalRequestId | null, approveFutureVersions: boolean, ): Promise<DynamicCordisHostHalfResult>
-
-/**
- * Fetch Client code for the exact active run.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity to read.
- * @param pluginRunId - Exact active run authorized to receive source.
- * @returns Client source and its Plugin, Package, and run identities.
- */
-@Remote('getClientCode') getClientCode( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, ): DynamicCordisClientSource
-
-/**
- * Resolve one model-driven Client activation request.
- * @param requestId - Request identity to settle once.
- * @param resolution - Browser refusal or exact Client activation result.
- * @returns Whether the still-pending request accepted this resolution.
- */
-@Remote('resolveRequestRun') async resolveRequestRun( requestId: ApprovalRequestId, resolution: DynamicCordisRunResolution, ): Promise<DynamicCordisResolveAck>
-
-/**
- * Settle a direct panel run after this page loaded or failed its Client half.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity being settled.
- * @param resolution - Exact Client activation result from the acting page.
- * @returns The committed activation or its failure.
- */
-@Remote('settleUserRun') async settleUserRun( agent: Agent, pluginId: CordisDynamicPluginId, resolution: DynamicCordisRunResolution, ): Promise<DynamicCordisRunResponse>
-
-/**
- * Stop the active run while retaining every Package version.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity to stop.
- * @returns Success or the reason no run was stopped.
- */
-async stop(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisStopResponse>
-
-/**
- * Stop a Plugin from the user panel and queue the resulting state change for the model's next step.
- * @param agent - Agent whose Session owns the Plugin and receives the context.
- * @param pluginId - Stable Plugin identity to stop.
- * @returns Success or the reason no run was stopped.
- */
-@Remote('stopFromPanel') async stopFromPanel(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisStopResponse>
-
-/**
- * Replace the Host mirror of the Client inspect provider directory.
- * @param providers - complete Client provider manifest.
- * @returns null after accepting the manifest.
- */
-@Remote('syncInspectManifest') syncInspectManifest(providers: readonly CordisInspectProviderManifest[]): null
-
-/**
- * Claim one pending Client inspect query with its live result.
- * @param agent - Session that owns the query.
- * @param requestId - exact pending query identity.
- * @param resolution - provider result or structured refusal.
- * @returns whether this answer won the query.
- */
-@Remote('resolveInspectQuery') resolveInspectQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
-
-/**
- * Frame-wide inventory, grouped as one row per stable Plugin.
- * @returns Source-free metadata for every process-local Plugin.
- */
-@Remote('inventory') inventory(): DynamicCordisInventoryRow[]
-
-/**
- * Read one Session's Host-rich state for inspection and result rendering.
- * @param agent - Agent whose Session selects visible Plugins.
- * @returns Plugin versions, active runs, Host fibers, and render failures.
- */
-snapshot(agent: Agent): DynamicCordisSnapshotRow[]
-
-/**
- * Read source-free context for an explicit `@pluginId` user gesture.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity referenced by the user.
- * @returns The preferred modification base, or undefined when unavailable.
- */
-reference(agent: Agent, pluginId: CordisDynamicPluginId): DynamicCordisReference | undefined
-
-/**
- * List source-free Plugin summaries owned by one Session.
- * @param agent - Agent whose Session selects visible Plugins.
- * @returns one summary per Plugin in creation order.
- */
-listPlugins(agent: Agent): DynamicCordisPluginInspection[]
-
-/**
- * Inspect one Plugin without returning Package source.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - stable Plugin identity.
- * @returns version pointers, latest run, and all Package summaries.
- */
-inspectPlugin(agent: Agent, pluginId: CordisDynamicPluginId): DynamicCordisPluginInspection
-
-/**
- * Read one exact immutable Package and its Host and Client source.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity that owns the Package.
- * @param packageId - Exact immutable Package identity to inspect.
- * @returns Package metadata, source, and the Plugin's lifecycle pointers.
- */
-inspectPackage( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, ): DynamicCordisPackageInspection
-
-/**
- * Record a post-load render failure for the exact active run.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity that rendered.
- * @param pluginRunId - Exact active run that produced the failure.
- * @param failure - Slot, message, and entry-retirement result.
- * @returns Null after recording or ignoring a stale report.
- */
-@Remote('reportRenderFailure') async reportRenderFailure( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, failure: DynamicCordisRenderFailure, ): Promise<null>
-
-/**
- * Report a Client guard rejection that happened after the Package completed activation.
- * @param agent - Agent whose Session must own the Plugin.
- * @param pluginId - Stable Plugin identity whose Client code was rejected.
- * @param pluginRunId - Exact active run that produced the rejection.
- * @param failure - Original guard message and stack.
- * @returns Null after reporting or ignoring a stale/startup failure.
- */
-@Remote('reportClientGuardFailure') async reportClientGuardFailure( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, failure: CordisErrorDetails, ): Promise<null>
-
-/**
- * Invoke an active Host method while rejecting stale Client runs.
- * @param pluginId - Stable Plugin identity that owns the method.
- * @param pluginRunId - Exact active run authorizing the call.
- * @param method - Registered Host handler name.
- * @param args - JSON argument delivered to the handler.
- * @returns The JSON result or a typed invocation failure.
- */
-@Remote('invoke') async invoke( pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, method: string, args: JsonValue, ): Promise<DynamicCordisInvokeResult>
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/extensions/cordis-host-runner/src/index.ts`](../../packages/extensions/cordis-host-runner/src/index.ts)
-
-<a id="ctxinspector--inspectorservice"></a>
-
-### `ctx.inspector` — `InspectorService`
-
-Shared Host/Client service façade over the realm's source publisher.
-
-```ts cordis-catalog
-/**
- * Publish one JSON observation without waiting for Worker delivery.
- * @param topic - Domain-owned topic name.
- * @param payload - JSON value validated before it reaches the carrier.
- * @param monotonicMs - Source-clock timestamp; defaults to `performance.now()`.
- */
-publish(topic: string, payload: InspectorJsonValue, monotonicMs?: number): void
-```
-
-Source: [`packages/experimental/inspector/src/index.ts`](../../packages/experimental/inspector/src/index.ts)
-
-<a id="cordis-events"></a>
-
-### `cordis/*` events
-
-<a id="cordisdynamic-package--emit"></a>
-
-#### `cordis/dynamic-package` — emit
-
-One exact Plugin/Package activation is now live in the Host.
-
-```ts cordis-catalog
-/**
- * One exact Plugin/Package activation is now live in the Host.
- * @param pkg - stable plugin, immutable package, run identity, and label.
- * @mode emit
- */
-'cordis/dynamic-package'(pkg: DynamicCordisPackage): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-
-<a id="cordisdynamic-retract--emit"></a>
-
-#### `cordis/dynamic-retract` — emit
-
-One exact activation was withdrawn.
-
-```ts cordis-catalog
-/**
- * One exact activation was withdrawn.
- * @param retracted - plugin, package, and run identity.
- * @mode emit
- */
-'cordis/dynamic-retract'(retracted: DynamicCordisRetracted): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-
-<a id="cordisinspect-query--emit"></a>
-
-#### `cordis/inspect-query` — emit
-
-Request a live read-only query from the Client inspect registry.
-
-```ts cordis-catalog
-/**
- * Request a live read-only query from the Client inspect registry.
- * @param request - correlation, Session, provider, method, and JSON input.
- * @mode emit
- */
-'cordis/inspect-query'(request: CordisInspectQueryRequest): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-
-<a id="cordisinspect-query-resolved--emit"></a>
-
-#### `cordis/inspect-query-resolved` — emit
-
-Notify every Client that an inspect query has settled or been cancelled.
-
-```ts cordis-catalog
-/**
- * Notify every Client that an inspect query has settled or been cancelled.
- * @param resolved - exact query identity that is no longer answerable.
- * @mode emit
- */
-'cordis/inspect-query-resolved'(resolved: CordisInspectQueryResolved): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-
-<a id="cordisrequest-run--emit"></a>
-
-#### `cordis/request-run` — emit
-
-A Client-bearing activation needs a browser page, and may require a user decision.
-
-```ts cordis-catalog
-/**
- * A Client-bearing activation needs a browser page, and may require a user decision.
- * @param request - correlation identity, owner, target version, mode, and approval requirement.
- * @mode emit
- */
-'cordis/request-run'(request: DynamicCordisRunRequest): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-
-<a id="cordisrequest-run-resolved--emit"></a>
-
-#### `cordis/request-run-resolved` — emit
-
-A pending Client activation request left the answerable state.
-
-```ts cordis-catalog
-/**
- * A pending Client activation request left the answerable state.
- * @param resolved - request identity and outcome.
- * @mode emit
- */
-'cordis/request-run-resolved'(resolved: DynamicCordisRequestResolved): void
-```
-
-Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/feedback.md

@@ -1,266 +0,0 @@
-# Message Feedback
-
-English | [中文](feedback.zh.md)
-
-[`@deepseek-ai/dsh-message-feedback`](../../packages/feedback/message-feedback) owns editable feedback for individual assistant messages. It is deliberately separate from the immutable Session-level `feedback/record` event: message feedback is a local storage-domain sidecar, not Session-log content or a projection, and it performs no telemetry handoff.
-
-Source: [`packages/feedback/message-feedback/src/types.ts`](../../packages/feedback/message-feedback/src/types.ts)
-
-## Public types
-
-```ts type-equiv
-/** Opaque compare-and-set token for one exact feedback item revision. */
-type MessageFeedbackVersion = Branded<'MessageFeedbackVersion'>
-```
-
-```ts type-equiv
-/** The human's overall judgment of one assistant message. */
-type MessageFeedbackRating = 'positive' | 'negative'
-```
-
-```ts type-equiv
-/** One current feedback value and its opaque mutation token. */
-interface MessageFeedbackItem {
-  /** Stable identity of the assistant message inside the owning Session. */
-  readonly messageId: MessageId
-  /** Overall positive or negative judgment. */
-  readonly rating: MessageFeedbackRating
-  /** Optional explanation, preserved verbatim after validation. */
-  readonly note?: string
-  /** Equality-only token replaced by every material create or update. */
-  readonly version: MessageFeedbackVersion
-  /** Host-assigned creation time in Unix epoch milliseconds. */
-  readonly createdAt: number
-  /** Host-assigned time of the most recent material update. */
-  readonly updatedAt: number
-}
-```
-
-```ts type-equiv
-/** Read all message feedback belonging to one persisted Session lifecycle. */
-interface MessageFeedbackListRequest {
-  /** Persisted Session whose sidecar should be read. */
-  readonly sessionId: SessionId
-}
-```
-
-```ts type-equiv
-/** Current feedback values for one Session, in first-creation order. */
-interface MessageFeedbackListValue {
-  /** Fresh immutable item snapshots. */
-  readonly items: readonly MessageFeedbackItem[]
-}
-```
-
-```ts type-equiv
-/** Create or replace feedback for one assistant message. */
-interface MessageFeedbackPutRequest {
-  /** Persisted Session that owns the target message. */
-  readonly sessionId: SessionId
-  /** Target assistant-message identity. */
-  readonly messageId: MessageId
-  /** Desired overall judgment. */
-  readonly rating: MessageFeedbackRating
-  /** Optional non-blank explanation. */
-  readonly note?: string
-  /** Observed item version, or `null` to require that no item exists. */
-  readonly ifVersion: MessageFeedbackVersion | null
-}
-```
-
-```ts type-equiv
-/** Delete feedback for one message after observing its current version. */
-interface MessageFeedbackDeleteRequest {
-  /** Persisted Session that owns the sidecar. */
-  readonly sessionId: SessionId
-  /** Message whose feedback should be absent after this operation. */
-  readonly messageId: MessageId
-  /** Observed item version; ignored when the item is already absent. */
-  readonly ifVersion: MessageFeedbackVersion
-}
-```
-
-```ts type-equiv
-/** Idempotent deletion acknowledgement. */
-interface MessageFeedbackDeleteValue {
-  /** Stable postcondition shared by the first deletion and every retry. */
-  readonly absent: true
-}
-```
-
-```ts type-equiv
-/** No persisted Session header exists for the requested id. */
-interface MessageFeedbackSessionNotFound {
-  readonly code: 'session-not-found'
-  readonly sessionId: SessionId
-}
-```
-
-```ts type-equiv
-/** The id does not name a derived, append-origin assistant message. */
-interface MessageFeedbackTargetNotFound {
-  readonly code: 'target-not-found'
-  readonly sessionId: SessionId
-  readonly messageId: MessageId
-}
-```
-
-```ts type-equiv
-/** A material mutation did not match the addressed item's current version. */
-interface MessageFeedbackVersionConflict {
-  readonly code: 'version-conflict'
-  /** Authoritative current item, or `null` when it does not exist. */
-  readonly current: MessageFeedbackItem | null
-}
-```
-
-```ts type-equiv
-/** A supplied note contains no non-whitespace character. */
-interface MessageFeedbackNoteBlank {
-  readonly code: 'note-blank'
-}
-```
-
-```ts type-equiv
-/** A supplied note exceeds the configured UTF-8 byte limit. */
-interface MessageFeedbackNoteTooLarge {
-  readonly code: 'note-too-large'
-  readonly maxBytes: number
-  readonly actualBytes: number
-}
-```
-
-```ts type-equiv
-/** Failures shared by the public message-feedback operations. */
-type MessageFeedbackFailure =
-  | MessageFeedbackSessionNotFound
-  | MessageFeedbackTargetNotFound
-  | MessageFeedbackVersionConflict
-  | MessageFeedbackNoteBlank
-  | MessageFeedbackNoteTooLarge
-```
-
-```ts type-equiv
-/** Successful public operation result. */
-interface MessageFeedbackSuccess<T> {
-  readonly ok: true
-  readonly value: T
-}
-```
-
-```ts type-equiv
-/** Rejected public operation result with a stable business failure. */
-interface MessageFeedbackRejected<E extends MessageFeedbackFailure> {
-  readonly ok: false
-  readonly error: E
-}
-```
-
-```ts type-equiv
-/** Result returned by the message-feedback `list` operation. */
-type MessageFeedbackListResult =
-  | MessageFeedbackSuccess<MessageFeedbackListValue>
-  | MessageFeedbackRejected<MessageFeedbackSessionNotFound>
-```
-
-```ts type-equiv
-/** Result returned by the message-feedback `put` operation. */
-type MessageFeedbackPutResult =
-  | MessageFeedbackSuccess<MessageFeedbackItem>
-  | MessageFeedbackRejected<
-    | MessageFeedbackSessionNotFound
-    | MessageFeedbackTargetNotFound
-    | MessageFeedbackVersionConflict
-    | MessageFeedbackNoteBlank
-    | MessageFeedbackNoteTooLarge
-  >
-```
-
-```ts type-equiv
-/** Result returned by the message-feedback `delete` operation. */
-type MessageFeedbackDeleteResult =
-  | MessageFeedbackSuccess<MessageFeedbackDeleteValue>
-  | MessageFeedbackRejected<MessageFeedbackSessionNotFound | MessageFeedbackVersionConflict>
-```
-
-## Data and concurrency
-
-One Session sidecar row contains its header identity `{createdAt, cwd}` and feedback items keyed by `MessageId`. Each item carries a positive or negative rating, an optional note, Host-assigned `createdAt`/`updatedAt` timestamps, and its own opaque version. Versions are compared only for equality and only against the addressed message; callers do not order or synthesize them.
-
-`put` uses strict optimistic concurrency: every request for an existing item must match its current `ifVersion`, including a no-op. A conflict returns the authoritative current item (or `null`), so a caller can reconcile a lost response or a concurrent edit without another read. Deleting an already absent item succeeds. A per-Session queue encloses inspection, read, conflict evaluation, and whole-row write, so these guarantees cover concurrent calls in one Host process.
-
-## Target and lifecycle authority
-
-A live owner's in-memory log supplies the target Session observation directly; a cold target is read through a `SessionPersistence.open(id, 'read')` handle without publishing or resuming an Agent and without writing recovery. A `stat(id)` preflight classifies definite absence; a read failure for a Session `stat` confirmed propagates as infrastructure failure. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin, usage-only empty, and non-assistant records are not feedback targets.
-
-The stored `{createdAt, cwd}` identity must match the inspected header. A mismatch is treated as absence: `list` returns no items, while `put` may replace the stale row with one bound to the current header identity. Forks use a new Session identity and receive no sidecar copy even when their seed contains the same messages.
-
-## Persistence and Remote contract
-
-The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through a fresh read handle, which observes at least the flushed prefix by the seam's freshness guarantee. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `TypertRemoteService` and `@Remote`; the generated Cordis API below is the method-level authority.
-
-Plugin disposal closes mutation admission, drains accepted per-Session queue work, and then closes the storage domain.
-
-## Web surface
-
-[`@deepseek-ai/dsh-client-ui-message-feedback`](../../packages/client/ui-message-feedback) is the browser consumer. `@deepseek-ai/dsh-api-remotes` mounts the generated `messageFeedback` contribution, so the plugin calls `ctx.remote.messageFeedback` and never touches the transport.
-
-The controls are the `feedback` entry (order 10) of the `conversation.chat.assistant-actions` list slot, which `ui-conversation` declares and renders inside the finalized assistant message's IconActions row. `AssistantMessageNode` carries the optional `messageId` from the `assistant/message` event. The field is absent on interruption-frozen partials, and the render site skips the slot when it is absent. The strip renders once per turn, on the closing assistant message: the Host accepts every append-origin step message as a target, but earlier steps of a multi-step turn render tool rows rather than a rateable body, so the UI exposes a narrower set than the Host contract allows.
-
-One `MessageFeedbackController` per Session backs every message control in that Session: a single `list` read seeds the whole transcript, deferred to first hover or focus rather than fired on mount. Each mutation sends the version that controller last observed as `ifVersion`; a `version-conflict` reply carries the authoritative item, so the controller reconciles from the reply instead of refetching. Mutations serialize per Session so a queued operation compares against the committed version. A `connection/reset` refreshes only Sessions already read.
-
-## Boundaries and limitations
-
-- The mutation queue is process-local. Storage-domain has no cross-process conditional write, so multiple Host writers to one storage root have no compare-and-swap or lost-update guarantee.
-- Session persistence has no durable deletion API. The service does not treat `session/disposed` or `api-session/removed` as deletion and therefore performs no fake cascade; orphan sidecar rows may remain after out-of-band log removal.
-- A request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization.
-- Cold requests scan the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation. One Session row also has no item-count or aggregate-byte cap; `maxNoteBytes` bounds only each note until a concrete consumer owns a row policy.
-- Header identity detects a reused id only when `{createdAt, cwd}` differs; a cloned log retaining the same header identity is indistinguishable by this contract.
-- The Host contract records no authenticated actor or audit identity and therefore assumes a trusted caller boundary.
-- The Web controls appear in the chat view only. The trajectory and waterfall views render no feedback entry even though their assistant nodes carry the same `messageId`.
-- The sidecar publishes no live frames, so a second tab's rating becomes visible on reconnect or on the next conflict reply rather than immediately.
-- The note editor does not pre-check `maxNoteBytes`; an oversized note fails on save with `note-too-large` rather than while typing.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxmessagefeedback--messagefeedbackservice"></a>
-
-### `ctx.messageFeedback` — `MessageFeedbackService`
-
-Storage-domain sidecar service. It inspects persisted Session history and never creates or resumes an Agent or Session.
-
-```ts cordis-catalog
-/**
- * Read feedback belonging to the current persisted Session lifecycle.
- * A stale row from a reused Session id is invisible.
- * @param request - Session identity to inspect and list.
- * @returns current immutable items or `session-not-found`.
- */
-@Remote('list') async list(request: MessageFeedbackListRequest): Promise<MessageFeedbackListResult>
-
-/**
- * Create or replace feedback for one derived append-origin assistant
- * message. Every request must match the addressed item's current version;
- * a matching no-op returns the stored item without changing its revision.
- * @param request - target, desired value, and observed item version.
- * @returns the committed item or an explicit business failure.
- */
-@Remote('put') put(request: MessageFeedbackPutRequest): Promise<MessageFeedbackPutResult>
-
-/**
- * Delete one feedback item. Absence is successful regardless of the
- * supplied version; an existing item requires an exact version match.
- * @param request - Session, message, and observed item version.
- * @returns the stable absent postcondition, or an explicit failure.
- */
-@Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise<MessageFeedbackDeleteResult>
-```
-
-Source: [`packages/feedback/message-feedback/src/index.ts`](../../packages/feedback/message-feedback/src/index.ts)
-<!-- END GENERATED cordis-surface -->