dsh-plugin-guide 0.2.0 → 0.3.2

package/references/official-docs/docs/subsystems/credentials.md

@@ -34,20 +34,24 @@ interface ResolvedCredential {
 `describe(ref)` answers configuration surfaces without ever exposing a value: whether the reference resolves, from which layer, and whether `set` would currently succeed. The local provider reports a reference supplied by the live process environment as `writable: false` — a write would appear to succeed while resolution kept returning the shadowing value, so the seam rejects it and the UI can render the reference read-only up front.
 
 ```ts type-equiv
-/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+/**
+ * Source and writability facts for one reference, safe for configuration UIs —
+ * never the value. The view has no slot a value could ride in, which is what
+ * lets the whole read half cross the Remote wire.
+ */
 interface CredentialInfo {
-  /** Whether {@link CredentialProvider.resolve} would currently return a value. */
+  /** Whether resolving the reference would currently return a value. */
   configured: boolean
   /** Source layer currently supplying the value; absent while unconfigured. */
   source?: string
-  /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
+  /** Whether the active provider can write this reference. */
   writable: boolean
 }
 ```
 
 ## Change commits
 
-`credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
+`credentials/reference-updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -55,13 +59,78 @@ interface CredentialInfo {
 
 ## 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`) — this section is byte-identical in both language sides of the page. 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).
+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="ctxauthorization--authorizationservice"></a>
+
+### `ctx.authorization` — `AuthorizationService`
+
+`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.
+
+```ts cordis-catalog
+/**
+ * Offer a way to obtain one credential. One flow per key: two plugins
+ * claiming the same key would each write a record in their own format, and
+ * whichever ran last would leave the other reading a payload it cannot parse.
+ *
+ * @param flow - the key it writes, its label, its methods, and its runner.
+ * @returns Disposer that withdraws this flow.
+ * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+ */
+registerFlow(flow: AuthorizationFlow): () => void
+
+/**
+ * Every registered flow, for a surface listing what can be authorized.
+ * @returns one entry per flow, in registration order.
+ */
+list(): readonly AuthorizationEntry[]
+
+/**
+ * One registered flow.
+ * @param key - the credential record to ask about.
+ * @returns the entry, or undefined when no flow claims that key.
+ */
+describe(key: CredentialKey): AuthorizationEntry | undefined
+
+/**
+ * Withdraw the attempt running for a key, if any. Separate from the
+ * request's own signal because a request/response transport answers a Cancel
+ * button on a second call, with no handle on the first one's signal.
+ * @param key - the credential record whose attempt should stop.
+ */
+cancel(key: CredentialKey): void
+
+/**
+ * Run one attempt to authorize a key, and report how it ended.
+ *
+ * One attempt per key at a time. A second caller is refused rather than
+ * joined: the two would be prompting different humans through the same flow,
+ * and the second would answer questions the first was asked.
+ *
+ * @param request - the key, the method, the surface, and the cancel signal.
+ * @returns `authorized` once the flow's record is committed during this
+ *   attempt and observed, or `cancelled` when the human declined or the
+ *   caller withdrew.
+ * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+ *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+ *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+ *   `NOT_COMMITTED` when the flow resolved without committing a record
+ *   during the attempt.
+ */
+async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
+```
+
+Source: [`packages/credentials/authorization/src/index.ts`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
 
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+Abstract credential service over two key spaces that answer two questions.
+
+A CredentialRef answers "what is behind this environment-variable name", layered over the process environment, the provider-managed store, and `.env` files. One seam-wide rule binds that half: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+A CredentialKey answers "what credential does this plugin hold for this id". Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and modifyRecord is the only write path because a correct write depends on the current value (a token refresh is read-decide-replace under one lock).
 
 ```ts cordis-catalog
 /**
@@ -99,17 +168,144 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
  * @param ref - the reference to remove.
  */
 abstract unset(ref: CredentialRef): Promise<void>
+
+/**
+ * Read one stored record. The value is returned as its owner wrote it; a
+ * {@link GrantRecord} payload is not interpreted on the way out.
+ * @param key - the record to read.
+ * @returns the record, or `undefined` while none is stored.
+ */
+abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>
+
+/**
+ * Describe one record for configuration surfaces without exposing its value.
+ * @param key - the record to describe.
+ * @returns presence, discriminant, and writability.
+ */
+abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>
+
+/**
+ * Enumerate every stored record's address and tag. Unlike the reference
+ * half, which has no enumeration because configuration surfaces learn which
+ * references exist from settings schemas, records have no such discovery
+ * path: a surface that cannot list them cannot show what a user is
+ * authorized for, nor find an orphan left by an uninstalled plugin.
+ * @returns every stored record, values excluded.
+ */
+abstract listRecords(): Promise<readonly CredentialRecordEntry[]>
+
+/**
+ * Serialized read-modify-write over one record — the only write path.
+ * `mutate` sees the record as it stands at the moment the write is
+ * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+ * holds across processes where the backing store supports it, which is what
+ * makes a token refresh safe: two processes rotating one refresh token
+ * concurrently would otherwise lose whichever wrote first.
+ * @param key - the record to modify.
+ * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+ * @returns the record after the write, or the current one when `mutate` declined.
+ */
+abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>, ): Promise<CredentialRecord | undefined>
+
+/**
+ * Remove one record; removing an absent record is a no-op.
+ * @param key - the record to remove.
+ */
+abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="ctxcredentialscontroller--credentialscontroller"></a>
+
+### `ctx.credentialsController` — `CredentialsController`
+
+Host service backing the generated `ctx.remote.credentials` namespace. It carries every wire obligation the credential seam itself does not: the batch fan-out bound, the field-by-field view projection, the reference-grammar guard, and the refusal mapping. Secret values cross in one direction only — no method here returns one.
+
+```ts cordis-catalog
+/**
+ * Describe several references for one configuration surface. Batched because
+ * a settings page describes every reference its rows name at once, and one
+ * round trip keeps those rows from settling separately.
+ * @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar
+ *   rejects the whole call as `gateway/bad-request`.
+ * @returns one view per requested name, keyed by that name.
+ * @throws RemoteError when the request is invalid or no credential provider is mounted.
+ */
+@Remote async describe(refs: string[]): Promise<Record<string, CredentialInfo>>
+
+/**
+ * Store one value from a configuration surface. The value crosses the wire in
+ * this direction only: no read path returns it.
+ * @param ref - reference name to store under.
+ * @param value - the non-empty secret value.
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
+ */
+@Remote async set(ref: string, value: string): Promise<void>
+
+/**
+ * Remove one reference from a configuration surface.
+ * @param ref - reference name to remove.
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
+ */
+@Remote async unset(ref: string): Promise<void>
+```
+
+Source: [`packages/api/settings-controller/src/credentials.ts`](../../packages/api/settings-controller/src/credentials.ts)
+
+<a id="authorization-events"></a>
+
+### `authorization/*` events
+
+<a id="authorizationsettled--emit"></a>
+
+#### `authorization/settled` — emit
+
+One authorization attempt has finished and released its key. Fires for every terminal outcome, failures included, so a surface watching a key it did not start (a second browser tab) learns the attempt is over.
+
+```ts cordis-catalog
+/**
+ * One authorization attempt has finished and released its key. Fires for
+ * every terminal outcome, failures included, so a surface watching a key it
+ * did not start (a second browser tab) learns the attempt is over.
+ * @mode emit
+ * @param key - the credential record the finished attempt was authorizing.
+ * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+ */
+'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void
+```
+
+Source: [`packages/credentials/authorization/src/index.ts`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
 
-<a id="credentialsupdated--emit"></a>
+<a id="credentialsrecord-updated--emit"></a>
+
+#### `credentials/record-updated` — emit
+
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/reference-updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/reference-updated`.
+
+```ts cordis-catalog
+/**
+ * Committed change to a stored credential record: a `modifyRecord` that
+ * wrote, a `deleteRecord` that removed, or an external edit observed in
+ * storage. Separate from `credentials/reference-updated` because the two key
+ * grammars are disjoint — a listener that received both on one event could
+ * not tell which space a subject belongs to. Listener failures are
+ * contained on the same terms as `credentials/reference-updated`.
+ * @param key - the record whose stored value changed.
+ * @mode emit
+ */
+'credentials/record-updated'(key: CredentialKey): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts`](../../packages/credentials/credentials/src/types.ts)
+
+<a id="credentialsreference-updated--emit"></a>
 
-#### `credentials/updated` — emit
+#### `credentials/reference-updated` — emit
 
 Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
 
@@ -126,8 +322,8 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
  * @param ref - the reference whose stored value changed.
  * @mode emit
  */
-'credentials/updated'(ref: CredentialRef): void
+'credentials/reference-updated'(ref: CredentialRef): void
 ```
 
-Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+Source: [`packages/credentials/credentials/src/types.ts`](../../packages/credentials/credentials/src/types.ts)
 <!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/credentials.zh.md

@@ -34,20 +34,24 @@ interface ResolvedCredential {
 `describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地提供方把由当前进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
 
 ```ts type-equiv
-/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+/**
+ * Source and writability facts for one reference, safe for configuration UIs —
+ * never the value. The view has no slot a value could ride in, which is what
+ * lets the whole read half cross the Remote wire.
+ */
 interface CredentialInfo {
-  /** Whether {@link CredentialProvider.resolve} would currently return a value. */
+  /** Whether resolving the reference would currently return a value. */
   configured: boolean
   /** Source layer currently supplying the value; absent while unconfigured. */
   source?: string
-  /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
+  /** Whether the active provider can write this reference. */
   writable: boolean
 }
 ```
 
 ## 已提交的变更
 
-`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后发出——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/reference-updated (ref)` 在提供方管理的来源发生已提交变更后发出——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -55,13 +59,78 @@ interface CredentialInfo {
 
 ## 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`) — this section is byte-identical in both language sides of the page. 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).
+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="ctxauthorization--authorizationservice"></a>
+
+### `ctx.authorization` — `AuthorizationService`
+
+`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.
+
+```ts cordis-catalog
+/**
+ * Offer a way to obtain one credential. One flow per key: two plugins
+ * claiming the same key would each write a record in their own format, and
+ * whichever ran last would leave the other reading a payload it cannot parse.
+ *
+ * @param flow - the key it writes, its label, its methods, and its runner.
+ * @returns Disposer that withdraws this flow.
+ * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+ */
+registerFlow(flow: AuthorizationFlow): () => void
+
+/**
+ * Every registered flow, for a surface listing what can be authorized.
+ * @returns one entry per flow, in registration order.
+ */
+list(): readonly AuthorizationEntry[]
+
+/**
+ * One registered flow.
+ * @param key - the credential record to ask about.
+ * @returns the entry, or undefined when no flow claims that key.
+ */
+describe(key: CredentialKey): AuthorizationEntry | undefined
+
+/**
+ * Withdraw the attempt running for a key, if any. Separate from the
+ * request's own signal because a request/response transport answers a Cancel
+ * button on a second call, with no handle on the first one's signal.
+ * @param key - the credential record whose attempt should stop.
+ */
+cancel(key: CredentialKey): void
+
+/**
+ * Run one attempt to authorize a key, and report how it ended.
+ *
+ * One attempt per key at a time. A second caller is refused rather than
+ * joined: the two would be prompting different humans through the same flow,
+ * and the second would answer questions the first was asked.
+ *
+ * @param request - the key, the method, the surface, and the cancel signal.
+ * @returns `authorized` once the flow's record is committed during this
+ *   attempt and observed, or `cancelled` when the human declined or the
+ *   caller withdrew.
+ * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+ *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+ *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+ *   `NOT_COMMITTED` when the flow resolved without committing a record
+ *   during the attempt.
+ */
+async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
+```
+
+Source: [`packages/credentials/authorization/src/index.ts`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
 
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+Abstract credential service over two key spaces that answer two questions.
+
+A CredentialRef answers "what is behind this environment-variable name", layered over the process environment, the provider-managed store, and `.env` files. One seam-wide rule binds that half: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+A CredentialKey answers "what credential does this plugin hold for this id". Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and modifyRecord is the only write path because a correct write depends on the current value (a token refresh is read-decide-replace under one lock).
 
 ```ts cordis-catalog
 /**
@@ -99,17 +168,144 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
  * @param ref - the reference to remove.
  */
 abstract unset(ref: CredentialRef): Promise<void>
+
+/**
+ * Read one stored record. The value is returned as its owner wrote it; a
+ * {@link GrantRecord} payload is not interpreted on the way out.
+ * @param key - the record to read.
+ * @returns the record, or `undefined` while none is stored.
+ */
+abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>
+
+/**
+ * Describe one record for configuration surfaces without exposing its value.
+ * @param key - the record to describe.
+ * @returns presence, discriminant, and writability.
+ */
+abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>
+
+/**
+ * Enumerate every stored record's address and tag. Unlike the reference
+ * half, which has no enumeration because configuration surfaces learn which
+ * references exist from settings schemas, records have no such discovery
+ * path: a surface that cannot list them cannot show what a user is
+ * authorized for, nor find an orphan left by an uninstalled plugin.
+ * @returns every stored record, values excluded.
+ */
+abstract listRecords(): Promise<readonly CredentialRecordEntry[]>
+
+/**
+ * Serialized read-modify-write over one record — the only write path.
+ * `mutate` sees the record as it stands at the moment the write is
+ * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+ * holds across processes where the backing store supports it, which is what
+ * makes a token refresh safe: two processes rotating one refresh token
+ * concurrently would otherwise lose whichever wrote first.
+ * @param key - the record to modify.
+ * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+ * @returns the record after the write, or the current one when `mutate` declined.
+ */
+abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>, ): Promise<CredentialRecord | undefined>
+
+/**
+ * Remove one record; removing an absent record is a no-op.
+ * @param key - the record to remove.
+ */
+abstract deleteRecord(key: CredentialKey): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="ctxcredentialscontroller--credentialscontroller"></a>
+
+### `ctx.credentialsController` — `CredentialsController`
+
+Host service backing the generated `ctx.remote.credentials` namespace. It carries every wire obligation the credential seam itself does not: the batch fan-out bound, the field-by-field view projection, the reference-grammar guard, and the refusal mapping. Secret values cross in one direction only — no method here returns one.
+
+```ts cordis-catalog
+/**
+ * Describe several references for one configuration surface. Batched because
+ * a settings page describes every reference its rows name at once, and one
+ * round trip keeps those rows from settling separately.
+ * @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar
+ *   rejects the whole call as `gateway/bad-request`.
+ * @returns one view per requested name, keyed by that name.
+ * @throws RemoteError when the request is invalid or no credential provider is mounted.
+ */
+@Remote async describe(refs: string[]): Promise<Record<string, CredentialInfo>>
+
+/**
+ * Store one value from a configuration surface. The value crosses the wire in
+ * this direction only: no read path returns it.
+ * @param ref - reference name to store under.
+ * @param value - the non-empty secret value.
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
+ */
+@Remote async set(ref: string, value: string): Promise<void>
+
+/**
+ * Remove one reference from a configuration surface.
+ * @param ref - reference name to remove.
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
+ */
+@Remote async unset(ref: string): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/api/settings-controller/src/credentials.ts`](../../packages/api/settings-controller/src/credentials.ts)
+
+<a id="authorization-events"></a>
+
+### `authorization/*` events
+
+<a id="authorizationsettled--emit"></a>
+
+#### `authorization/settled` — emit
+
+One authorization attempt has finished and released its key. Fires for every terminal outcome, failures included, so a surface watching a key it did not start (a second browser tab) learns the attempt is over.
+
+```ts cordis-catalog
+/**
+ * One authorization attempt has finished and released its key. Fires for
+ * every terminal outcome, failures included, so a surface watching a key it
+ * did not start (a second browser tab) learns the attempt is over.
+ * @mode emit
+ * @param key - the credential record the finished attempt was authorizing.
+ * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+ */
+'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void
+```
+
+Source: [`packages/credentials/authorization/src/index.ts`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
 
-<a id="credentialsupdated--emit"></a>
+<a id="credentialsrecord-updated--emit"></a>
+
+#### `credentials/record-updated` — emit
+
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/reference-updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/reference-updated`.
+
+```ts cordis-catalog
+/**
+ * Committed change to a stored credential record: a `modifyRecord` that
+ * wrote, a `deleteRecord` that removed, or an external edit observed in
+ * storage. Separate from `credentials/reference-updated` because the two key
+ * grammars are disjoint — a listener that received both on one event could
+ * not tell which space a subject belongs to. Listener failures are
+ * contained on the same terms as `credentials/reference-updated`.
+ * @param key - the record whose stored value changed.
+ * @mode emit
+ */
+'credentials/record-updated'(key: CredentialKey): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts`](../../packages/credentials/credentials/src/types.ts)
+
+<a id="credentialsreference-updated--emit"></a>
 
-#### `credentials/updated` — emit
+#### `credentials/reference-updated` — emit
 
 Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
 
@@ -126,8 +322,8 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
  * @param ref - the reference whose stored value changed.
  * @mode emit
  */
-'credentials/updated'(ref: CredentialRef): void
+'credentials/reference-updated'(ref: CredentialRef): void
 ```
 
-Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+Source: [`packages/credentials/credentials/src/types.ts`](../../packages/credentials/credentials/src/types.ts)
 <!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/extensions.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/extensions.md
-extensions.md: f212f99704cb1cc871a77ee6cc10188746771958
-extensions.zh.md: 717b14951dd262213cfc42a380777d233fb6eea5
+extensions.md: 540f3c477b4e128b0c1062192185e6276c9e9263
+extensions.zh.md: ebfe7827484cea2cf8c6d77ca26796f7751d203a

package/references/official-docs/docs/subsystems/extensions.md

@@ -10,7 +10,7 @@ The extensions subsystem lets an agent define versioned Cordis packages, run the
 
 ## 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`) — this section is byte-identical in both language sides of the page. 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).
+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="ctxcordisinspect--cordisinspectregistryservice"></a>
 
@@ -62,7 +62,7 @@ resolveClientQuery( agent: Agent, requestId: CordisInspectRequestId, resolution:
 
 Types: [Agent](core.md)
 
-Source: [`packages/extensions/cordis-host-runner/src/inspect-registry.ts:46`](../../packages/extensions/cordis-host-runner/src/inspect-registry.ts)
+Source: [`packages/extensions/cordis-host-runner/src/inspect-registry.ts`](../../packages/extensions/cordis-host-runner/src/inspect-registry.ts)
 
 <a id="ctxdynamiccordisrunner--dynamiccordisrunnerservice"></a>
 
@@ -254,7 +254,25 @@ inspectPackage( agent: Agent, pluginId: CordisDynamicPluginId, packageId: Cordis
 
 Types: [Agent](core.md)
 
-Source: [`packages/extensions/cordis-host-runner/src/index.ts:124`](../../packages/extensions/cordis-host-runner/src/index.ts)
+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>
 
@@ -275,7 +293,7 @@ One exact Plugin/Package activation is now live in the Host.
 'cordis/dynamic-package'(pkg: DynamicCordisPackage): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:379`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 
 <a id="cordisdynamic-retract--emit"></a>
 
@@ -292,7 +310,7 @@ One exact activation was withdrawn.
 'cordis/dynamic-retract'(retracted: DynamicCordisRetracted): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:385`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 
 <a id="cordisinspect-query--emit"></a>
 
@@ -309,7 +327,7 @@ Request a live read-only query from the Client inspect registry.
 'cordis/inspect-query'(request: CordisInspectQueryRequest): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:391`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 
 <a id="cordisinspect-query-resolved--emit"></a>
 
@@ -326,7 +344,7 @@ Notify every Client that an inspect query has settled or been cancelled.
 'cordis/inspect-query-resolved'(resolved: CordisInspectQueryResolved): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:397`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 
 <a id="cordisrequest-run--emit"></a>
 
@@ -343,7 +361,7 @@ A Client-bearing activation needs a browser page, and may require a user decisio
 'cordis/request-run'(request: DynamicCordisRunRequest): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:367`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 
 <a id="cordisrequest-run-resolved--emit"></a>
 
@@ -360,5 +378,5 @@ A pending Client activation request left the answerable state.
 'cordis/request-run-resolved'(resolved: DynamicCordisRequestResolved): void
 ```
 
-Source: [`packages/extensions/cordis-host-runner/src/types.ts:373`](../../packages/extensions/cordis-host-runner/src/types.ts)
+Source: [`packages/extensions/cordis-host-runner/src/types.ts`](../../packages/extensions/cordis-host-runner/src/types.ts)
 <!-- END GENERATED cordis-surface -->