docs: record the forwarded-event surface and its face boundaries

Each owner package's README states which of its cordis events are forwarded and
that the declaration now lives in the client-safe ./types export. api/remotes
documents the allowlist as the single control point and the deliberate
both-faces listing of src/types.ts; development.md keeps the split-tsconfig rule
current.
This commit is contained in:
imccyu
2026-08-10 21:32:49 +08:00
parent 7c8ee81818
commit b64da061a8
16 changed files with 48 additions and 14 deletions

View File

@@ -25,7 +25,7 @@ await ctx.credentials.set(ref, 'sk-…') // rejects while a re
await ctx.credentials.unset(ref) // no-op when absent; same shadowing rule
```
`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 UIs refreshing a "configured" badge.
`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 UIs refreshing a "configured" badge. Its declaration lives in the client-safe `./types` subpath export together with the `CredentialRef` type it names (the package root re-exports the type), so a consumer outside the Host compilation face reads the very signature the Host emits instead of restating it.
The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only source (the live process environment, in the local provider) currently supplies the reference, a write would appear to succeed while resolution keeps returning the shadowing value — the seam rejects instead, and `describe().writable` lets a UI render the reference read-only up front.

View File

@@ -25,7 +25,7 @@ await ctx.credentials.set(ref, 'sk-…') // rejects while a re
await ctx.credentials.unset(ref) // no-op when absent; same shadowing rule
```
`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set``unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测,永不触发。消费方不需要该事件(它们按操作重新解析);它服务于配置界面刷新「已配置」徽标。
`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set``unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测,永不触发。消费方不需要该事件(它们按操作重新解析);它服务于配置界面刷新「已配置」徽标。它的声明住在 client-safe 的 `./types` 子路径出口,与其点名的 `CredentialRef` 类型同处一处(包根继续 re-export 该类型),于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名,而不必再写一遍。
`set`/`unset` 的遮蔽规则是刻意设计为明确报错当只读来源本地提供方中即当前进程环境正在提供该引用时写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝,并通过 `describe().writable` 让界面提前把该引用渲染为只读。