@buddhilive/dsh-credentials 0.1.2-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 packages/credentials/credentials/README.md
+README.md: 30eff7799e664b08224e2d9732b2fcee4867ad98
+README.zh.md: d20050324106cec46e6ae7d7a13b4ece085ab893

package/README.md

@@ -0,0 +1,191 @@
+---
+description: "The credential seam for users and maintainers resolving, describing, or storing credentials — reference values and durable records — without putting secret values in configuration."
+kind: "package-reference"
+---
+
+# @buddhilive/dsh-credentials
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-credentials` keeps secret values out of configuration: you store an API key once and reference it by name (`DEEPSEEK_API_KEY`) from settings or `cordis.yml`, and the product supplies the value when a provider request needs it. Beside those references it also keeps durable credential records — per-plugin entries such as an authorization grant or provider environment values — so a plugin holds what it manages for its own ids across restarts. A rotated key takes effect on the very next request — no restart, no configuration edit. Configuration UIs can tell you whether a key or record is set, where it comes from, and whether you can change it, without ever showing a value. Storing an empty value counts as "no key", so a blank can never masquerade as a configured secret; a record's presence is the whole fact, so an entry carrying no value is a deliberate statement, not a blank.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+This package is the part of the product that stores and looks up secret values: store a key once, reference it by name everywhere, and read, check, or remove it at any time. It also keeps durable credential records, so a plugin can store, update, and remove the credentials it holds for its own ids. The product's default composition already includes a credential store; a custom composition loads the local store package with a file path.
+
+### When to use it
+
+Use a credential store whenever configuration must stay free of secret values: settings files that are synced, shared, or rendered in a configuration UI, or teams that rotate keys without editing configuration. Use records when a plugin must keep credentials with no single environment variable — an authorization grant from a sign-in flow, or provider environment values — and when a configuration UI should list what a user is authorized for. A configuration UI can show whether a key or record is set, where it comes from, and whether you can change it — never the value itself. If you only need one fixed environment variable, read that variable directly and skip the store.
+
+### Adding it to your composition
+
+Load the local store package with a document path:
+
+```yaml
+- name: '@buddhilive/dsh-credentials-local'
+  config:
+    path: /absolute/path/to/.credentials.yaml
+```
+
+The local store README owns the full configuration surface; the generated [configuration catalog](../../../docs/config-catalog.md#buddhilivedsh-credentials-local) is the exhaustive field list.
+
+### Storing, checking, and removing keys
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialRef } from '@buddhilive/dsh-credentials'
+
+declare const ctx: Context
+
+const ref = credentialRef('DEEPSEEK_API_KEY')          // POSIX shell identifier, branded
+const hit = await ctx.credentials.resolve(ref)         // { value, source } | undefined
+const info = await ctx.credentials.describe(ref)       // { configured, source?, writable } — never the value
+await ctx.credentials.set(ref, 'sk-…')                 // rejects while a read-only source shadows the ref
+await ctx.credentials.unset(ref)                       // no-op when absent; same shadowing rule
+```
+
+Store a key with `set`, remove it with `unset`, check its status with `describe`, and read the current value with `resolve` when an operation needs it. `describe` reports whether the key is set, where it comes from, and whether you can write to it — it never returns the value.
+
+### Storing, updating, and removing records
+
+A plugin addresses each record by `<scope>/<id>` — its own registered name plus an id it chooses, such as a provider route key — and reads, modifies, or removes what it holds:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialKey } from '@buddhilive/dsh-credentials'
+
+declare const ctx: Context
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')   // <owner>/<id>, branded
+const hit = await ctx.credentials.readRecord(key)        // CredentialRecord | undefined
+await ctx.credentials.describeRecord(key)                // { configured, kind?, writable } — never the value
+await ctx.credentials.listRecords()                      // [{ key, kind }] — never values
+await ctx.credentials.modifyRecord(key, async () => ({ kind: 'grant', payload: { token: '…' } }))
+await ctx.credentials.deleteRecord(key)                  // no-op when absent
+```
+
+`modifyRecord` is the only write path: it hands your mutation the record as it stands at the moment the write is exclusive, and returning `undefined` leaves the entry untouched. Records have no empty-value rule — a record carrying neither a key nor environment values states that its owner confirmed ambient authentication — and a configuration UI can enumerate every record to show what you are authorized for and find records a removed plugin left behind.
+
+### Using a key in configuration
+
+A settings section or `cordis.yml` entry names a key instead of containing it — an LLM adapter, for example, takes `apiKeyEnv`:
+
+```yaml
+apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+Requests that need the key use its current stored value, so rotating the key takes effect on the very next request — no restart and no configuration edit.
+
+### What can go wrong
+
+- **A key the launching environment supplies cannot be overwritten** — `DEEPSEEK_API_KEY=… dsh` (or a CI secret, a container `-e`) wins for this run and is reported read-only; clear the variable in the launching shell before storing a different value.
+- **An empty value cannot be stored** — storing an empty string is refused; remove the key instead.
+- **Key values never appear in configuration UIs or diagnostics** — the UI shows whether a key is set, where it comes from, and whether you can change it; the value itself stays in the store.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the package and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+One doctrine and four consequences:
+
+- **Configuration carries references, never secrets.** A settings section or `cordis.yml` entry names a credential; the value behind the reference lives with a provider. The settings document stays safe to sync and to render, `describe()` answers without holding a value, and rotating a secret touches no configuration file.
+- **Consumers resolve per operation.** Resolution is a per-call read with no cross-operation cache; that read is the hot-update mechanism.
+- **An empty stored value is absent.** `resolve` skips it, `describe` reports it unconfigured — a blank can never masquerade as a configured secret.
+- **Records are durable, and presence is the fact.** A record is stored per `<scope>/<id>` and survives restarts; the empty-value rule does not apply, so an `api-key` record carrying neither a key nor environment values is a deliberate statement, not a blank.
+- **Listener failures are contained.** `notifyUpdated` fans `credentials/reference-updated` out so every listener runs; a sync throw or async rejection is logged without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran.
+
+### The credentials/reference-updated event
+
+`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 UIs refreshing a "configured" badge.
+
+`credentials/record-updated (key)` fires after a committed change to a stored record — a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. It stays a separate event because the two key grammars are disjoint: a listener receiving both spaces on one event could not tell which one a subject belongs to.
+
+### Record write and read paths
+
+`modifyRecord` is the only record write path because a correct write depends on the current value: a token refresh is read-decide-replace, and the mutation sees the record as it stands at the moment the write is exclusive — returning `undefined` leaves the entry untouched. Exclusion holds across processes where the backing store supports it, which is what stops two processes rotating one refresh token from losing whichever wrote first. Reads mirror the reference half but never layer: nothing can shadow a record, and a `grant` payload is returned exactly as its owner wrote it, because only the owning plugin can interpret it.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service Definition: the `credentialRef`/`credentialKey` brands, `ResolvedCredential`/`CredentialRecordInfo`, the abstract provider over both key spaces, contained fan-out |
+| [`src/types.ts`](src/types.ts) | Client-safe type surface: the `CredentialRef` and `CredentialKey` brands, the stored-record union, the `CredentialInfo` reference view, the `credentials/reference-updated` and `credentials/record-updated` declarations |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: `credentials/reference-updated` only fires while a credentials service is live |
+
+### Client-safe types
+
+The `./types` subpath export holds the event declarations together with the `CredentialRef` and `CredentialKey` brands, the stored-record union they name, and the `CredentialInfo` reference view a configuration surface reads, and the package root re-exports them. A consumer outside the Host compilation face therefore reads the very signature the Host emits instead of restating it.
+
+### Lifecycle
+
+The service is a Cordis `Service` registered by the provider: disposing the mounting fiber removes `ctx.credentials`. The invariant companion checks that `credentials/reference-updated` never fires without a live service — an emission after disposal means a provider leaked work past its teardown quiescence.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared subsystem vocabulary to the shipped store and the capability architecture.
+
+- [Credentials subsystem reference](../../../docs/subsystems/credentials.md) — `CredentialRef`/`CredentialKey`, per-operation resolution, UI-safe info, provider layers, and the generated cordis surface.
+- [Local credentials store](../credentials-local/README.md) — the default on-machine store: where keys and records live and how the environment layers rank.
+- [Capability seams](../../../docs/capability-seams.md) — the Service Definition / Service Provider / Consumer split this package follows.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the consuming adapter, which resolves each credential reference and owns every model-facing use a value authorizes.
+
+#### KV Cache effect
+
+No direct invalidation; resolved values never enter a request prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when this package is a poor fit or needs special care. They are current package constraints, not a task backlog.
+
+- **References have no enumeration** — the seam answers questions about references it is given; configuration surfaces learn them from settings schemas, so a `list()` over that half has no current consumer. Records do enumerate, because they have no schema to be discovered from.
+- **References are environment-variable-shaped** — one flat POSIX-identifier namespace, because a reference doubles as the environment name it resolves through. Records carry the richer `<owner>/<id>` addressing.
+- **Process-environment changes are invisible** — no notification can fire for a variable changed in the launching shell; a UI only re-reads `describe()` on its own navigation.
+- **A record's owner is its scope, and nothing verifies the scope is mounted** — the seam stores what it is given and reports what it stores; recognizing an orphan is the caller's join between `listRecords()` and whatever registry owns that scope, and the seam has no registry of its own to check against.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the package code.
+
+The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers; a remote settings provider never needs to carry secrets. None is shipped, and no current consumer requires one.
+
+</details>

package/README.zh.md

@@ -0,0 +1,191 @@
+---
+description: "面向用户与维护者的凭据 seam：在不把机密值写进配置的前提下解析、描述或存储凭据——引用值与持久化记录。"
+kind: "package-reference"
+---
+
+# @buddhilive/dsh-credentials
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-credentials` 让机密值留在配置之外：API 密钥只存一次，在 settings 或 `cordis.yml` 中按名引用（`DEEPSEEK_API_KEY`），产品在提供方请求需要时提供该值。在这些引用之外，它还保存持久化的凭据记录——按插件组织的条目，例如授权 grant 或提供方环境值——让插件跨重启持有它为自身 id 管理的凭据。轮换后的密钥会作用于紧随其后的下一次请求——无需重启，无需改配置。配置界面能告诉你某个密钥或记录是否已设置、来自哪里、能否修改，而绝不显示值本身。存储空值等于「没有密钥」，因此空白永远不会伪装成已配置的机密；记录的存在本身就是全部事实，一条不含任何值的条目是有意陈述，而不是空白。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+本包是产品中负责存储与查询机密值的部分：密钥只存一次、处处按名引用，并可在任意时刻读取、检查或移除。它还保存持久化的凭据记录，让插件可以为自身 id 存储、更新或移除它持有的凭据。产品的默认组合已包含凭据存储；自定义组合只需加载本地存储包并给出文件路径。
+
+### 何时使用
+
+只要配置需要与机密值绝缘，就使用凭据存储：需要同步、共享或渲染进配置界面的设置文件，或希望在不改配置的情况下轮换密钥的团队。当插件必须保存没有单一环境变量的凭据——登录流程产生的授权 grant，或提供方环境值——并希望配置界面能列出用户已授权什么时，请使用记录。配置界面能显示某个密钥或记录是否已设置、来自哪里、能否修改——但绝不显示值本身。如果只需要一个固定的环境变量，直接读该变量即可，无需存储。
+
+### 加入你的组合
+
+加载本地存储包并给出文档路径：
+
+```yaml
+- name: '@buddhilive/dsh-credentials-local'
+  config:
+    path: /absolute/path/to/.credentials.yaml
+```
+
+本地存储 README 拥有完整配置面；生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-credentials-local)是穷尽式字段清单。
+
+### 存储、检查与移除密钥
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialRef } from '@buddhilive/dsh-credentials'
+
+declare const ctx: Context
+
+const ref = credentialRef('DEEPSEEK_API_KEY')          // POSIX shell identifier, branded
+const hit = await ctx.credentials.resolve(ref)         // { value, source } | undefined
+const info = await ctx.credentials.describe(ref)       // { configured, source?, writable } — never the value
+await ctx.credentials.set(ref, 'sk-…')                 // rejects while a read-only source shadows the ref
+await ctx.credentials.unset(ref)                       // no-op when absent; same shadowing rule
+```
+
+用 `set` 存储密钥、用 `unset` 移除、用 `describe` 检查状态、在操作需要时用 `resolve` 读取当前值。`describe` 报告密钥是否已设置、来自哪里、能否写入——它绝不返回值。
+
+### 存储、更新与移除记录
+
+插件按 `<scope>/<id>` 寻址每条记录——自身注册名加一个自选 id，例如提供方路由键——并读取、修改或移除它所持有的内容：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialKey } from '@buddhilive/dsh-credentials'
+
+declare const ctx: Context
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')   // <owner>/<id>, branded
+const hit = await ctx.credentials.readRecord(key)        // CredentialRecord | undefined
+await ctx.credentials.describeRecord(key)                // { configured, kind?, writable } — never the value
+await ctx.credentials.listRecords()                      // [{ key, kind }] — never values
+await ctx.credentials.modifyRecord(key, async () => ({ kind: 'grant', payload: { token: '…' } }))
+await ctx.credentials.deleteRecord(key)                  // no-op when absent
+```
+
+`modifyRecord` 是唯一写路径：它让你的变更函数看到写入取得独占那一刻的记录，返回 `undefined` 则保持原状。记录没有空值规则——一条既无 key 也无环境值的记录，陈述的是其拥有者确认了 ambient 认证——配置界面还可以枚举每条记录，显示你已授权什么，并找出已卸载插件留下的记录。
+
+### 在配置中使用密钥
+
+settings 分节或 `cordis.yml` 条目按名引用密钥，而不是包含密钥本身——例如 LLM（大语言模型）适配器接受 `apiKeyEnv`：
+
+```yaml
+apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+需要该密钥的请求使用它当前存储的值，因此轮换密钥会作用于紧随其后的下一次请求——无需重启，无需改配置。
+
+### 可能出错的地方
+
+- **启动环境提供的密钥无法被覆盖**——`DEEPSEEK_API_KEY=… dsh`（或 CI 机密、容器 `-e`）在本轮运行中优先，并被报告为只读；请先在启动 shell 中清除该变量，再存储其他值。
+- **空值无法存储**——存储空字符串会被拒绝；请改为移除密钥。
+- **密钥值绝不会出现在配置界面或诊断信息中**——界面只显示密钥是否已设置、来自哪里、能否修改；值本身留在存储中。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释本包背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+一条准则，四个推论：
+
+- **配置只携带引用，绝不携带机密。** settings 分节或 `cordis.yml` 条目点名一个凭据；引用背后的值存放在提供方处。设置文档可以放心同步、放心渲染，`describe()` 无需持有值就能回答，轮换机密不触碰任何配置文件。
+- **消费方按操作解析。** 解析是一次按调用读取，无跨操作缓存；这次读取正是热更新机制。
+- **空的存储值等于不存在。** `resolve` 跳过它，`describe` 报告未配置——空白永远不会伪装成已配置的机密。
+- **记录是持久化的，存在即事实。** 记录按 `<scope>/<id>` 存储并跨重启保留；空值规则不适用，因此一条既无 key 也无环境值的 `api-key` 记录是有意陈述，而不是空白。
+- **监听器失败被包含。** `notifyUpdated` 扇出 `credentials/reference-updated`，保证每个监听器都会运行；同步抛出与异步拒绝都会被记录，不改变已提交操作的结果，`INVARIANT` 编码的失败除外——它们在所有监听器运行完毕后重新抛出。
+
+### credentials/reference-updated 事件
+
+`credentials/reference-updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+
+`credentials/record-updated (key)` 在存储记录发生已提交变更后触发——一次确实写入的 `modifyRecord`、一次确实移除的 `deleteRecord`，或在存储中观察到的外部编辑。它保持独立事件，因为两个键文法互斥：一个监听器若在同一事件上同时收到两个空间，将无法分辨主体属于哪一边。
+
+### 记录写入与读取路径
+
+`modifyRecord` 是唯一写路径，因为正确的写入依赖当前值：刷新 token 是「读—决定—替换」，变更函数看到的是写入取得独占那一刻的记录——返回 `undefined` 则保持原状。独占在支持它的底层存储上跨进程成立，这正是防止两个进程同时轮换一个 refresh token、丢掉先写那一个的机制。读取与引用一侧对称，但绝不分层：没有任何东西能遮蔽记录，`grant` 的 payload 会原样返回给其拥有者，因为只有拥有它的插件能解释它。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service Definition：`credentialRef`/`credentialKey` 品牌、`ResolvedCredential`/`CredentialRecordInfo`、覆盖两个键空间的抽象提供方、包含式扇出 |
+| [`src/types.ts`](src/types.ts) | 客户端安全类型面：`CredentialRef` 与 `CredentialKey` 品牌、存储记录联合类型、`CredentialInfo` 引用视图、`credentials/reference-updated` 与 `credentials/record-updated` 事件声明 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：`credentials/reference-updated` 只在凭据服务存活时触发 |
+
+### 客户端安全类型
+
+`./types` 子路径出口把事件声明与其点名的 `CredentialRef`、`CredentialKey` 品牌、存储记录联合类型，以及配置界面读取的 `CredentialInfo` 引用视图放在一起，包根继续 re-export 它们。于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
+
+### 生命周期
+
+服务是提供方注册的 Cordis `Service`：释放挂载 fiber 会移除 `ctx.credentials`。不变式伴生插件检查 `credentials/reference-updated` 绝不在服务存活之前触发——释放后仍有发射意味着提供方把工作泄漏到了 teardown 完全停稳之后。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享子系统词汇逐步进入随附存储与能力架构。
+
+- [凭据子系统参考](../../../docs/subsystems/credentials.zh.md)——`CredentialRef`/`CredentialKey`、按操作解析、对 UI 安全的信息、提供方层与生成的 cordis 接口面。
+- [本地凭据存储](../credentials-local/README.zh.md)——默认本机存储：密钥与记录存放在哪里、环境层如何排序。
+- [能力 seam](../../../docs/capability-seams.zh.md)——本包遵循的 Service Definition / Service Provider / Consumer 拆分。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+经由消费方适配器间接生效：适配器解析每个凭据引用，并拥有值所授权的全部模型可见用途。
+
+#### KV Cache 影响
+
+无直接失效；解析出的值绝不进入请求前缀。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本包何时不合适或需要特别注意。它们是当前包约束，不是任务积压。
+
+- **引用不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，对这一半做 `list()` 没有当前消费方。记录出于无 schema 可发现的原因则可枚举。
+- **引用限定为环境变量形状**——单一扁平的 POSIX 标识符命名空间，因为引用同时就是它借以解析的环境变量名。记录使用更丰富的 `<owner>/<id>` 寻址。
+- **进程环境变化不可见**——无法为启动 shell 中改变的变量发出通知；界面只能在自身导航时重新读取 `describe()`。
+- **记录的拥有者就是它的 scope，而没有任何环节核验该 scope 是否已挂载**——seam 存下被交予的内容，并报告它存了什么；识别孤儿是调用方在 `listRecords()` 与拥有该 scope 的注册表之间做的连接，seam 自身没有可供核对的注册表。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
+
+该 seam 的接口为 keyring、辅助命令与 KMS 后端提供方预留了扩展空间；远端设置提供方永远不必携带机密。目前没有任何一种随附，也没有当前消费方需要它们。
+
+</details>

package/lib/index.js

@@ -0,0 +1,159 @@
+import { Service } from "@deepseek-ai/cordis";
+import { brandString } from "@buddhilive/dsh-brand";
+//#region lib/types/index.js
+/**
+* Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+* *references* to secrets — environment-variable names — while providers own
+* the actual values and their storage. Consumers resolve a reference once per
+* operation, so a changed credential reaches the next operation without any
+* plugin restart, and configuration surfaces describe a reference without
+* ever seeing its value.
+* @module @buddhilive/dsh-credentials
+*/
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+* Brand a raw string as a {@link CredentialRef}.
+* @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+* @returns the branded reference.
+*/
+function credentialRef(value) {
+	if (!isCredentialRefName(value)) throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`);
+	return brandString(value);
+}
+/**
+* Whether a raw string could name a reference at all. Consumers that receive
+* environment-variable names from somewhere else — a provider library's own
+* ambient discovery, a hook payload — ask this before resolving, because a name
+* outside the grammar has no reference to miss and should read as "not set"
+* rather than as a thrown error.
+* @param value - candidate reference.
+* @returns true when {@link credentialRef} would accept it.
+*/
+function isCredentialRefName(value) {
+	return REF_PATTERN.test(value);
+}
+/**
+* Whether a raw string could be a {@link credentialKey} segment at all.
+* Consumers whose addressing units come from somewhere else — a settings dict
+* key, a library's own provider id — ask this before building a key, because a
+* unit outside the grammar can never have stored a record and should read as
+* "nothing stored" rather than as a thrown error.
+* @param value - candidate segment.
+* @returns true when {@link credentialKey} would accept it as either segment.
+*/
+function isCredentialKeySegment(value) {
+	return KEY_SEGMENT_PATTERN.test(value);
+}
+/**
+* Brand a scope and an id as a {@link CredentialKey}.
+* @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+* @param id - that plugin's own addressing unit, such as a provider route key.
+* @returns the branded key.
+* @throws TypeError when either segment is not a lowercase hyphenated identifier.
+*/
+function credentialKey(scope, id) {
+	for (const segment of [scope, id]) if (!KEY_SEGMENT_PATTERN.test(segment)) throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+	return brandString(`${scope}/${id}`);
+}
+/**
+* Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+* read half of {@link credentialKey}, for a provider admitting keys off disk.
+* @param value - candidate key in its joined form.
+* @returns the branded key.
+* @throws TypeError when the value is not exactly two valid segments.
+*/
+function parseCredentialKey(value) {
+	const segments = value.split("/");
+	const [scope, id] = segments;
+	if (segments.length !== 2 || scope === void 0 || id === void 0) throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`);
+	return credentialKey(scope, id);
+}
+/**
+* The owning plugin's name for one key. A record whose scope names no
+* currently registered owner is an orphan, which a configuration surface must
+* report as such rather than as a working credential.
+* @param key - the key to read.
+* @returns the scope segment.
+*/
+function credentialKeyScope(key) {
+	return key.slice(0, key.indexOf("/"));
+}
+/**
+* The owning plugin's own addressing unit for one key — the half that plugin
+* chose, such as a provider route.
+* @param key - the key to read.
+* @returns the id segment.
+*/
+function credentialKeyId(key) {
+	return key.slice(key.indexOf("/") + 1);
+}
+/**
+* Abstract credential service over two key spaces that answer two questions.
+*
+* A {@link 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 {@link 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 {@link 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).
+*/
+var CredentialProvider = class extends Service {
+	constructor(ctx) {
+		super(ctx, "credentials");
+	}
+	/**
+	* Fan `credentials/reference-updated` out with contained listener failures: every
+	* listener runs, and a sync throw or async rejection is logged without
+	* changing the committed operation's outcome — except `INVARIANT`-coded
+	* failures, which rethrow after every listener ran (the rethrow reaches the
+	* caller only from synchronous listeners, so invariant checks on this event
+	* must not be async functions). Providers call this only after the write or
+	* reload actually committed, so a broken observer can never make a durable
+	* change look failed.
+	* @param ref - the reference whose stored value changed.
+	*/
+	notifyUpdated(ref) {
+		this.fanOut("credentials/reference-updated", ref);
+	}
+	/**
+	* Fan `credentials/record-updated` out on exactly the terms
+	* {@link notifyUpdated} documents, for the record half of the seam.
+	* @param key - the record whose stored value changed.
+	*/
+	notifyRecordUpdated(key) {
+		this.fanOut("credentials/record-updated", key);
+	}
+	/** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+	fanOut(event, subject) {
+		let invariantFailure;
+		const args = [event, subject];
+		for (const listener of this.ctx.events.dispatch("emit", args)) try {
+			const returned = listener(subject);
+			if (returned != null && typeof returned.then === "function") Promise.resolve(returned).then(void 0, (error) => {
+				this.warnListenerFailure(event, subject, error);
+			});
+		} catch (error) {
+			if (error?.code === "INVARIANT") {
+				invariantFailure ??= error;
+				continue;
+			}
+			this.warnListenerFailure(event, subject, error);
+		}
+		if (invariantFailure !== void 0) throw invariantFailure;
+	}
+	/** Contained-listener diagnostic shared by the sync and async failure paths. */
+	warnListenerFailure(event, subject, error) {
+		this.ctx.logger.warn("credentials: a %s listener for \"%s\" failed", event, subject);
+		this.ctx.logger.warn(error);
+	}
+};
+//#endregion
+export { CredentialProvider, CredentialProvider as default, credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName, parseCredentialKey };

package/lib/invariant.js

@@ -0,0 +1,31 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@buddhilive/dsh-credentials`.
+* @module @buddhilive/dsh-credentials/invariant
+*/
+const PACKAGE_NAME = "@buddhilive/dsh-credentials";
+/** Cordis companion plugin name. */
+const name = "credentials-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Install the commit-event lifecycle contract: `credentials/reference-updated` names a
+* committed provider-source change, so it can only fire while a credentials
+* service is live — an emission after disposal means a provider leaked work
+* past its teardown quiescence. The value relation itself (`describe`
+* agreeing with `resolve`) is asynchronous provider I/O and stays pinned by
+* each provider's own suite.
+*/
+const install = (ctx, fail) => {
+	ctx.on("credentials/reference-updated", (ref) => {
+		if (ctx.get("credentials") === void 0) fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`);
+	});
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+ * *references* to secrets — environment-variable names — while providers own
+ * the actual values and their storage. Consumers resolve a reference once per
+ * operation, so a changed credential reaches the next operation without any
+ * plugin restart, and configuration surfaces describe a reference without
+ * ever seeing its value.
+ * @module @buddhilive/dsh-credentials
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { CredentialInfo, CredentialKey, CredentialRecord, CredentialRef } from './types.ts';
+export type { ApiKeyRecord, CredentialInfo, CredentialKey, CredentialRecord, CredentialRef, GrantRecord, } from './types.ts';
+/**
+ * Brand a raw string as a {@link CredentialRef}.
+ * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+ * @returns the branded reference.
+ */
+export declare function credentialRef(value: string): CredentialRef;
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export declare function isCredentialRefName(value: string): boolean;
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export declare function isCredentialKeySegment(value: string): boolean;
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export declare function credentialKey(scope: string, id: string): CredentialKey;
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export declare function parseCredentialKey(value: string): CredentialKey;
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export declare function credentialKeyScope(key: CredentialKey): string;
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export declare function credentialKeyId(key: CredentialKey): string;
+/** One resolved credential value and the source layer that supplied it. */
+export interface ResolvedCredential {
+    /** The non-empty secret value. */
+    value: string;
+    /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
+    source: string;
+}
+/** Presence and writability facts for one record, safe for configuration UIs — never the value. */
+export interface CredentialRecordInfo {
+    /**
+     * Whether a record is stored. Unlike a reference, presence alone answers
+     * this: an {@link ApiKeyRecord} carrying neither a key nor environment
+     * values states that its owner confirmed ambient authentication, which is
+     * configured, not blank.
+     */
+    configured: boolean;
+    /** Discriminant of the stored record; absent while none is stored. */
+    kind?: CredentialRecord['kind'];
+    /** Whether {@link CredentialProvider.modifyRecord} would currently succeed. */
+    writable: boolean;
+}
+/** One stored record's address and tag, for enumeration — never its value. */
+export interface CredentialRecordEntry {
+    /** The record's address. */
+    key: CredentialKey;
+    /** Discriminant of the stored record. */
+    kind: CredentialRecord['kind'];
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        credentials: CredentialProvider;
+    }
+}
+/**
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link 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 {@link 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 {@link 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).
+ */
+export declare abstract class CredentialProvider extends Service {
+    constructor(ctx: Context);
+    /**
+     * Resolve one reference to its current value. Resolution is per call:
+     * consumers re-resolve at each operation and must not cache across
+     * operations — that per-operation read is what makes a changed credential
+     * reach the next operation without a restart.
+     * @param ref - the reference to resolve.
+     * @returns the value and its source, or `undefined` while unconfigured.
+     */
+    abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>;
+    /**
+     * Describe one reference for configuration surfaces without exposing the
+     * value.
+     * @param ref - the reference to describe.
+     * @returns configured state, supplying source, and writability.
+     */
+    abstract describe(ref: CredentialRef): Promise<CredentialInfo>;
+    /**
+     * Durably store one value in the provider-managed writable source. Rejects
+     * while a read-only source shadows the reference — the write would appear
+     * to succeed while resolution keeps returning the shadowing value — and
+     * rejects an empty value (use {@link unset}).
+     * @param ref - the reference to store.
+     * @param value - the non-empty secret value.
+     */
+    abstract set(ref: CredentialRef, value: string): Promise<void>;
+    /**
+     * Remove one reference from the provider-managed writable source; removing
+     * an absent reference is a no-op. Rejects while a read-only source shadows
+     * the reference, like {@link set}.
+     * @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>;
+    /**
+     * Fan `credentials/reference-updated` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the committed operation's outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran (the rethrow reaches the
+     * caller only from synchronous listeners, so invariant checks on this event
+     * must not be async functions). Providers call this only after the write or
+     * reload actually committed, so a broken observer can never make a durable
+     * change look failed.
+     * @param ref - the reference whose stored value changed.
+     */
+    protected notifyUpdated(ref: CredentialRef): void;
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    protected notifyRecordUpdated(key: CredentialKey): void;
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    private fanOut;
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    private warnListenerFailure;
+}
+export default CredentialProvider;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,178 @@
+/**
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+ * *references* to secrets — environment-variable names — while providers own
+ * the actual values and their storage. Consumers resolve a reference once per
+ * operation, so a changed credential reaches the next operation without any
+ * plugin restart, and configuration surfaces describe a reference without
+ * ever seeing its value.
+ * @module @buddhilive/dsh-credentials
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { brandString } from '@buddhilive/dsh-brand';
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Brand a raw string as a {@link CredentialRef}.
+ * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+ * @returns the branded reference.
+ */
+export function credentialRef(value) {
+    if (!isCredentialRefName(value)) {
+        throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`);
+    }
+    return brandString(value);
+}
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export function isCredentialRefName(value) {
+    return REF_PATTERN.test(value);
+}
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export function isCredentialKeySegment(value) {
+    return KEY_SEGMENT_PATTERN.test(value);
+}
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export function credentialKey(scope, id) {
+    for (const segment of [scope, id]) {
+        if (!KEY_SEGMENT_PATTERN.test(segment)) {
+            throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+        }
+    }
+    return brandString(`${scope}/${id}`);
+}
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export function parseCredentialKey(value) {
+    const segments = value.split('/');
+    const [scope, id] = segments;
+    if (segments.length !== 2 || scope === undefined || id === undefined) {
+        throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`);
+    }
+    return credentialKey(scope, id);
+}
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export function credentialKeyScope(key) {
+    // The brand's only constructors both validate two segments, so the split
+    // cannot come back short here.
+    return key.slice(0, key.indexOf('/'));
+}
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export function credentialKeyId(key) {
+    return key.slice(key.indexOf('/') + 1);
+}
+/**
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link 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 {@link 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 {@link 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).
+ */
+export class CredentialProvider extends Service {
+    constructor(ctx) {
+        super(ctx, 'credentials');
+    }
+    /**
+     * Fan `credentials/reference-updated` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the committed operation's outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran (the rethrow reaches the
+     * caller only from synchronous listeners, so invariant checks on this event
+     * must not be async functions). Providers call this only after the write or
+     * reload actually committed, so a broken observer can never make a durable
+     * change look failed.
+     * @param ref - the reference whose stored value changed.
+     */
+    notifyUpdated(ref) {
+        this.fanOut('credentials/reference-updated', ref);
+    }
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    notifyRecordUpdated(key) {
+        this.fanOut('credentials/record-updated', key);
+    }
+    /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
+       fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
+       contract, and extracting it would couple the two seams' event semantics. */
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    fanOut(event, subject) {
+        let invariantFailure;
+        const args = [event, subject];
+        for (const listener of this.ctx.events.dispatch('emit', args)) {
+            try {
+                const returned = listener(subject);
+                if (returned != null && typeof returned.then === 'function') {
+                    void Promise.resolve(returned).then(undefined, (error) => {
+                        this.warnListenerFailure(event, subject, error);
+                    });
+                }
+            }
+            catch (error) {
+                if (error?.code === 'INVARIANT') {
+                    invariantFailure ??= error;
+                    continue;
+                }
+                this.warnListenerFailure(event, subject, error);
+            }
+        }
+        if (invariantFailure !== undefined)
+            throw invariantFailure;
+    }
+    /* jscpd:ignore-end */
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    warnListenerFailure(event, subject, error) {
+        this.ctx.logger.warn('credentials: a %s listener for "%s" failed', event, subject);
+        this.ctx.logger.warn(error);
+    }
+}
+export default CredentialProvider;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@buddhilive/dsh-credentials`.
+ * @module @buddhilive/dsh-credentials/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "credentials-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@buddhilive/dsh-credentials`.
+ * @module @buddhilive/dsh-credentials/invariant
+ */
+const PACKAGE_NAME = '@buddhilive/dsh-credentials';
+/** Cordis companion plugin name. */
+export const name = 'credentials-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Install the commit-event lifecycle contract: `credentials/reference-updated` names a
+ * committed provider-source change, so it can only fire while a credentials
+ * service is live — an emission after disposal means a provider leaked work
+ * past its teardown quiescence. The value relation itself (`describe`
+ * agreeing with `resolve`) is asynchronous provider I/O and stays pinned by
+ * each provider's own suite.
+ */
+const install = (ctx, fail) => {
+    ctx.on('credentials/reference-updated', (ref) => {
+        if (ctx.get('credentials') === undefined) {
+            fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`);
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, the reference view crossing the Remote wire, and the
+ * seam's Cordis event declarations. Types only — no runtime code, and nothing
+ * here reaches a Host-only symbol, so a Client compilation face reads exactly
+ * the signature the Host emits.
+ *
+ * @module @buddhilive/dsh-credentials/types
+ */
+import type { Branded } from '@buddhilive/dsh-brand';
+/** Nominal reference to one credential: a POSIX-style environment-variable name. */
+export type CredentialRef = Branded<'CredentialRef'>;
+/**
+ * Nominal address of one stored credential record: `<scope>/<id>`, where
+ * `scope` is the registered name of the plugin that owns the record and `id`
+ * is that plugin's own addressing unit (an LLM adapter uses its provider route
+ * key).
+ *
+ * The scope is the owner rather than the domain because a record's payload is
+ * written in its owner's format: two plugins serving the same provider name
+ * would otherwise read each other's payload, and a record left behind by an
+ * uninstalled plugin could not be told apart from a live one. The `/` also
+ * keeps this grammar disjoint from {@link CredentialRef}, so the two key
+ * spaces can never collide.
+ */
+export type CredentialKey = Branded<'CredentialKey'>;
+/**
+ * A credential the harness itself understands: an api key, provider
+ * environment values, or both. Either field may be absent — a record carrying
+ * neither states that the owner confirmed this route authenticates from its
+ * own ambient discovery, which is a different fact from having no record.
+ */
+export interface ApiKeyRecord {
+    /** Discriminant. */
+    readonly kind: 'api-key';
+    /** The non-empty secret value, when this credential is a key at all. */
+    readonly key?: string;
+    /** Provider environment values such as `AWS_PROFILE`; names are POSIX identifiers. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The product of one authorization grant, kept verbatim for its owner. The
+ * seam never reads, validates, or reshapes {@link payload}: it is written in
+ * the owning plugin's format and only that plugin can interpret it. The single
+ * constraint is that it survives a JSON round trip.
+ */
+export interface GrantRecord {
+    /** Discriminant. */
+    readonly kind: 'grant';
+    /** Owner-defined JSON value; opaque to the seam and to every other plugin. */
+    readonly payload: unknown;
+}
+/** One durable credential record, tagged by what the seam may do with it. */
+export type CredentialRecord = ApiKeyRecord | GrantRecord;
+/**
+ * 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.
+ */
+export interface CredentialInfo {
+    /** Whether resolving the reference would currently return a value. */
+    configured: boolean;
+    /** Source layer currently supplying the value; absent while unconfigured. */
+    source?: string;
+    /** Whether the active provider can write this reference. */
+    writable: boolean;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * 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.
+         * @param ref - the reference whose stored value changed.
+         * @mode emit
+         */
+        'credentials/reference-updated'(ref: CredentialRef): void;
+        /**
+         * 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;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,11 @@
+/**
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, the reference view crossing the Remote wire, and the
+ * seam's Cordis event declarations. Types only — no runtime code, and nothing
+ * here reaches a Host-only symbol, so a Client compilation face reads exactly
+ * the signature the Host emits.
+ *
+ * @module @buddhilive/dsh-credentials/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@buddhilive/dsh-credentials",
+  "description": "Abstract credential seam (ctx.credentials): settings carry references to secrets, providers own the values",
+  "version": "0.1.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Buddhilive/buddhi-ai-harness.git",
+    "directory": "packages/credentials/credentials"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3"
+  },
+  "dependencies": {
+    "@buddhilive/dsh-brand": "^0.1.2-alpha.3"
+  }
+}