dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.i18n.yaml

@@ -1,6 +1,31 @@
-# 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:
+# Bilingual-pair consistency record for reviewing-persistence-type-changes.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/reviewing-persistence-type-changes.md
-reviewing-persistence-type-changes.md: 881bc689af656f0c4976e909a49848e38d53c453
-reviewing-persistence-type-changes.zh.md: f1961013886cfab1abdbd7e2cd7e09bcfce2101d
+/:
+  en: 81db5d0ea2dbd0e2
+  zh: 2eb04cd5b470fd53
+/cookbook-reviewing-persistence-type-changes:
+  en: 50fa0e1367687c7d
+  zh: cd76f6e9649351c9
+/cookbook-reviewing-persistence-type-changes/summary:
+  en: 58040d6422d9ef9d
+  zh: 7deda8fc45752e8c
+/cookbook-reviewing-persistence-type-changes/table-of-contents:
+  en: 5fca19ac2bb1ddac
+  zh: 00d78fe7e80ba4f7
+/cookbook-reviewing-persistence-type-changes/optional-inspect-the-change:
+  en: 3f85edb803afe870
+  zh: 545c651b9e5ccb56
+/cookbook-reviewing-persistence-type-changes/1-record-the-change:
+  en: 342bd49412db070e
+  zh: a8d14958e9a637d9
+/cookbook-reviewing-persistence-type-changes/2-check-commit-and-push:
+  en: 91d39719ec40b0f7
+  zh: 405116ae4c91b100
+/cookbook-reviewing-persistence-type-changes/update-an-unaccepted-record:
+  en: 4fd3f48761f7909f
+  zh: 69af35c41656fa17
+/cookbook-reviewing-persistence-type-changes/dev-note:
+  en: 5de1d6304e00c58f
+  zh: 8d8225361cfa29e5

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.md

@@ -33,9 +33,21 @@ Use `--silent` when consuming JSON: pnpm otherwise appends lifecycle failure tex
 
 Read the reported root, path, change kind, and version requirement. A referenced type can affect several event digests; inspect every affected root. Until the history covers the new schemas, verification fails. A stale generated inventory also fails verification; the recording command refreshes it. If `changes` is empty after reordering fields or union alternatives, run `pnpm run gen-persistence-catalog` and repeat the check. An unchanged digest needs no new acknowledgement even when copied declarations or source locations produce a catalog diff.
 
+To review a PR independently of its acknowledgement history, save the base and head inventories as local JSON files and run:
+
+```sh
+pnpm --silent run persistence-review --before .artifacts/base.schema.json --after docs/persistence-schema.json
+```
+
+Record the commits supplying those files with the report. Add `--json` for structured output. This read-only comparison groups shared changes with their affected roots and uses actual literal `kind`/`form` values instead of union positions. Ambiguous alternatives remain separate additions and removals. Its compatibility section copies every root's authoritative classifier result; the structural explanation does not replace acknowledgement checks. Current catalog labels and declaration names are descriptive metadata; structural anchors and fingerprints identify types.
+
+The current machine inventory stores complete graphs in `roots`. A `types` entry contains `digest`, `names`, and `sources`, plus an explicit `schema` when roots cannot reconstruct that graph exactly. Readers resolve omitted graphs from root subgraphs by digest and validate explicit graphs directly, preserving every type and its metadata. Historical full entries remain readable. `formatVersion` identifies normalization rules; storage compaction does not change root fingerprints or require an acknowledgement.
+
 <a id="acknowledge"></a>
 ## 1. Record the change
 
+Check the [accepted baseline](../session-format-status.md#finalization-record) first. Preserve its locked records. Record backward-compatible evolution in a new same-version acknowledgement; implement a higher writer version before recording a breaking change.
+
 Write a local JSON file containing `en` and `zh`, each with `summary`, `compatibility`, and `verification` strings. The following input describes an exercised required-to-optional hook audit field change. Replace the explanation and test evidence with facts about your change; the CLI does not establish these claims.
 
 Save the input as `.artifacts/persistence-change.prose.json`, creating the ignored directory if needed:
@@ -87,7 +99,7 @@ If source changes after recording, review the compatibility explanation and refr
 pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
 ```
 
-The command refreshes the machine declaration, schemas, catalogs, and pairing. Without `--prose`, it preserves the existing explanation. Update refuses the initial baseline and records that another record depends on. The tree cannot identify which records were accepted in review: preserve accepted history and create a successor instead.
+The command refreshes the machine declaration, schemas, catalogs, and pairing. Without `--prose`, it preserves the existing explanation. Update refuses the initial baseline, records that another record depends on, and finalized checkpoint records. Outside finalized checkpoints, the tree does not infer review acceptance: preserve accepted history and create a successor instead.
 
 When integration creates competing terminal records, update the unaccepted record against the remaining history, then reassess the resulting diff. An unrelated root's acknowledgement does not need refreshing. The [mechanism decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) explains why complete snapshots and per-root predecessors are retained.
 

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.zh.md

@@ -33,9 +33,21 @@ pnpm --silent run verify-persistence-changes --json
 
 阅读报告中的根、路径、变更种类和版本要求。被引用类型可能影响多个事件摘要；检查每个受影响的根。在历史覆盖新 schema 之前，验证会失败。陈旧生成清单也会导致验证失败；记录命令会刷新它。若重排字段或联合类型分支后 `changes` 为空，运行 `pnpm run gen-persistence-catalog` 并重新检查。即使复制的声明或源码位置产生目录 diff，未变的摘要也无需新增确认记录。
 
+要独立于确认历史评审 PR，先将 base 和 head 的目录保存为本地 JSON 文件，再运行：
+
+```sh
+pnpm --silent run persistence-review --before .artifacts/base.schema.json --after docs/persistence-schema.json
+```
+
+在报告旁记录这些文件对应的 commit。添加 `--json` 可获取结构化输出。此只读比较将共享变更与受影响的根类型归组，使用实际字面量 `kind`/`form` 值代替联合类型位置。无法唯一匹配的候选项保留为独立的新增与删除。兼容性部分复制每个根类型的权威分类结果；结构说明不替代确认检查。当前目录标签和声明名称是描述元数据；结构锚点和指纹标识类型。
+
+当前机器清单在 `roots` 中保存完整图。每个 `types` 条目包含 `digest`、`names` 和 `sources`；若根无法精确重建该图，条目还会保存显式 `schema`。读取器按摘要从根的子图恢复省略的图，并直接验证显式图，保留每个类型及其元数据。历史完整条目仍然可读。`formatVersion` 标识规范化规则；存储压缩不改变根指纹，也不需要确认记录。
+
 <a id="acknowledge"></a>
 ## 1. 记录变更
 
+先检查[已接受基线](../session-format-status.zh.md#finalization-record)，保留其锁定记录。向后兼容的演进使用新的同版本确认记录；记录破坏性变更之前，先实现更高的写入器版本。
+
 编写包含 `en` 和 `zh` 的本地 JSON 文件，两者分别包含 `summary`、`compatibility` 和 `verification` 字符串。以下输入描述一个经过验证的钩子审计字段从必选改为可选的变更。用你所做变更的事实替换说明和测试证据；CLI（命令行界面）不会证明这些声明。
 
 将输入保存为 `.artifacts/persistence-change.prose.json`，必要时创建该被忽略的目录：
@@ -87,7 +99,7 @@ pnpm run doc-sync
 pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
 ```
 
-命令刷新机器声明、schema、目录和配对。没有 `--prose` 时，它保留已有说明。更新会拒绝初始基线和被其他记录依赖的记录。目录本身无法识别哪些记录已获审阅接受：保留已接受历史，并创建后继。
+命令刷新机器声明、schema、目录和配对。没有 `--prose` 时，它保留已有说明。更新会拒绝初始基线、其他记录所依赖的记录，以及已被定稿检查点锁定的记录。定稿检查点之外，目录不会推断审阅接受状态：保留已接受历史，并创建后继。
 
 集成产生竞争末端记录时，根据剩余历史更新尚未接受的记录，再重新评估最终差异。无关根的确认无需刷新。[机制决策](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)解释为何保留完整快照和逐根前驱。
 

package/references/official-docs/docs/cordis-api/context.i18n.yaml

@@ -1,6 +1,73 @@
-# 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:
+# Bilingual-pair consistency record for context.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/context.md
-context.md: 320b23de1c8d19e2dacdf0ec9f2361037bcf8048
-context.zh.md: b97fe51eb8afdd5c2235ac9cf8586c3ff68830d4
+/:
+  en: d2c0c5bce430d1be
+  zh: a317d7ff7fc9f112
+/context:
+  en: fc6fd9ae25b8e9e5
+  zh: 1a2407d299404ace
+/context/ctx-extend-meta:
+  en: 2c407cb9589b001f
+  zh: 70dc8650250cd4c5
+/context/ctx-isolate-name-label:
+  en: ab77052c3bf31e2b
+  zh: 686ca829ea5b8170
+/context/ctx-intercept-name-config:
+  en: 1bd1e349f5c8687d
+  zh: 7634b27d2c9bade4
+/context/ctx-root:
+  en: eb89a7f0d2bc1753
+  zh: 263219126a310d3b
+/context/ctx-baseurl:
+  en: 29c28e7558cea0ad
+  zh: 9b591e449c1bfd72
+/context/ctx-events:
+  en: 6ce1e444e9dc3c48
+  zh: d4ca16ff2aeaa9f4
+/context/ctx-logger:
+  en: da8400d2e8dac772
+  zh: 8dd6fea850dd3b90
+/context/ctx-reflect:
+  en: 31e86abee38e9040
+  zh: 77ab752a7e69ccfe
+/context/ctx-registry:
+  en: d2f27d281bbf9f56
+  zh: 9193074fac7e9bfc
+/context/static-members:
+  en: ceb197529207a8ed
+  zh: 7d444c03f8be0f0d
+/context/static-members/context-effect:
+  en: 19f4aaef44a7e8eb
+  zh: 2179cf28a7ee3f6a
+/context/static-members/context-filter:
+  en: e8ca384b9a1ea98b
+  zh: 82189892bf0afcb0
+/context/static-members/context-isolate:
+  en: b8673b719837ce51
+  zh: 83892f9f96c3ac28
+/context/static-members/context-intercept:
+  en: f3ebe6568cc9a863
+  zh: bb51ab61a4e47d33
+/context/static-members/context-is-value:
+  en: 7425e0ee4bc1ada7
+  zh: 93dee27133ded9e0
+/context/service-store-and-mixins:
+  en: 9f7ca8a6a0f80512
+  zh: 05e8cbc30e5709fc
+/context/service-store-and-mixins/ctx-get-name-strict:
+  en: 5a9a1212850a136f
+  zh: 2b6f287c8bbcc0c6
+/context/service-store-and-mixins/ctx-set-name-value:
+  en: a04668f00e1cbe91
+  zh: 8e8444e6b393358e
+/context/service-store-and-mixins/ctx-provide-name-value:
+  en: 5887dc4233a37a5b
+  zh: 810dcde64664170b
+/context/service-store-and-mixins/ctx-accessor-name-options:
+  en: 82ccb33229d3cf32
+  zh: d969904f023380b4
+/context/service-store-and-mixins/ctx-mixin-name-mixins:
+  en: 777f36aed85fa512
+  zh: 47b809ad5f799134

package/references/official-docs/docs/cordis-api/events.i18n.yaml

@@ -1,6 +1,37 @@
-# 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:
+# Bilingual-pair consistency record for events.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/events.md
-events.md: 8b8eb2358e10a250f581aecc725ba32360d338d3
-events.zh.md: 60b0580496926e56c1d2f803d84fbf649f37d972
+/:
+  en: d2c0c5bce430d1be
+  zh: af1ac3203cdfdad2
+/events:
+  en: 9d809e3de33dd783
+  zh: b965aee4a65c6c1a
+/events/ctx-parallel-name-args:
+  en: e583c71acb606915
+  zh: 0560679b20f8d7f0
+/events/ctx-emit-name-args:
+  en: ff6f4023b66f8164
+  zh: af16d24d663a7eb7
+/events/ctx-serial-name-args:
+  en: c431c0e3ac72e854
+  zh: c43b7d899ea8161c
+/events/ctx-bail-name-args:
+  en: 85b8b2178c3e3c33
+  zh: ad8af3e0743e231c
+/events/ctx-waterfall-name-args:
+  en: 3b32d0511b7da48b
+  zh: e0ac62e59d8e2152
+/events/ctx-on-name-listener-options:
+  en: 74a1fe55f4a47ec8
+  zh: 87d37038af3bab0e
+/events/ctx-once-name-listener-options:
+  en: 64802f0580705984
+  zh: 3f6ce2d7ce1e760d
+/events/eventoptions:
+  en: 937453f689836c80
+  zh: ebf0cc0f28127245
+/events/dispatchmode:
+  en: 1c8548fb249ed794
+  zh: 86b92a28f39b2a12

package/references/official-docs/docs/cordis-api/fiber.i18n.yaml

@@ -1,6 +1,76 @@
-# 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:
+# Bilingual-pair consistency record for fiber.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md
-fiber.md: 3044301effde267bf580c3a5138481b10513f755
-fiber.zh.md: bee2f523f1fa2a2add2afc3a3fc322903f1ef6f0
+/:
+  en: d2c0c5bce430d1be
+  zh: 2173e2f1a2a3a13a
+/fiber:
+  en: b5b3510f4b6dd13a
+  zh: a0c70471b6d779b5
+/fiber/ctx-effect-execute-label:
+  en: ef3418fd5ffbe86d
+  zh: c98935435da8bc7e
+/fiber/ctx-fiber:
+  en: a10e38bf26b4ecfe
+  zh: 7c91817984c95c99
+/fiber/the-fiber-class:
+  en: 0e0fcb134ed44957
+  zh: 326f4232aa0e65d1
+/fiber/the-fiber-class/fiber-uid:
+  en: 2f0eb3658bb8497e
+  zh: 65d3c17ca8bd4f95
+/fiber/the-fiber-class/fiber-ctx:
+  en: 1b527d85759324f9
+  zh: 54aa40db2705b95c
+/fiber/the-fiber-class/fiber-config:
+  en: ee804c03c39e7806
+  zh: 4353ba7817ec61ec
+/fiber/the-fiber-class/fiber-state:
+  en: 999ad29dfc29661b
+  zh: 20245d11c338e3f1
+/fiber/the-fiber-class/fiber-dispose:
+  en: 29e304d183eb9104
+  zh: 9ac5023f518e06c4
+/fiber/the-fiber-class/fiber-store:
+  en: c4185e5d051136a2
+  zh: 5714d9e4f5461ca3
+/fiber/the-fiber-class/fiber-inertia:
+  en: 2a3b1d3bc37bf986
+  zh: 83bd257ee685d38b
+/fiber/the-fiber-class/fiber-name:
+  en: e5c2ecca13167a32
+  zh: 284a461f0f1cd35b
+/fiber/the-fiber-class/fiber-assertactive:
+  en: cceb503899634d09
+  zh: a8381af1a23436f3
+/fiber/the-fiber-class/fiber-effect-execute-label:
+  en: 55dcfacf295bbcf2
+  zh: 6e3ec27bb8da5a3d
+/fiber/the-fiber-class/fiber-geteffects:
+  en: 4d739a9c186fd9c2
+  zh: f80fd3b87e79b004
+/fiber/the-fiber-class/fiber-await:
+  en: 1d6258cbea61cd18
+  zh: 2f10dda8918dadc5
+/fiber/the-fiber-class/fiber-restart:
+  en: 62d68dedb20b4fa9
+  zh: 5a735ae0ff1266f4
+/fiber/the-fiber-class/fiber-update-config-nosave:
+  en: b57ce0f6260c2cb8
+  zh: 3bfb6c5bc252a2c2
+/fiber/effect:
+  en: 007d5b214e8a8610
+  zh: d74c26fbb1b8aeb6
+/fiber/disposable:
+  en: 56e4218392fa7234
+  zh: 8fea671180cacf6f
+/fiber/effectmeta:
+  en: 849aa91b8e67809f
+  zh: 4b31d7e2acd2a008
+/fiber/cordiserror:
+  en: d276771958d3c05f
+  zh: 0141656ade938d55
+/fiber/validationerror:
+  en: 178782124cc15210
+  zh: 2b226f43f48af555

package/references/official-docs/docs/cordis-api/inherited.md

@@ -21,16 +21,18 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 
 ## Inherited events (cordis core + loader/hmr/timer)
 
-- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
-- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
-- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
-- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
-- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
-- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
-- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
-- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
-- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
-- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
-- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
-- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
-- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
+- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:331`](../../vendor/cordis/src/events.ts))
+- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:333`](../../vendor/cordis/src/events.ts))
+- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:341`](../../vendor/cordis/src/events.ts))
+- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:343`](../../vendor/cordis/src/events.ts))
+- `internal/config` — Waterfall: a fiber config is being resolved before validation. ([`vendor/cordis/src/events.ts:339`](../../vendor/cordis/src/events.ts))
+- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:345`](../../vendor/cordis/src/events.ts))
+- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:347`](../../vendor/cordis/src/events.ts))
+- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:349`](../../vendor/cordis/src/events.ts))
+- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:351`](../../vendor/cordis/src/events.ts))
+- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
+- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
+- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
+- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:28`](../../vendor/loader/src/index.ts))
+- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:41`](../../vendor/loader/src/index.ts))
+- `loader/volatile-update` — Volatile config values committed into the running fiber without a remount; dispatched to the owning fiber only. ([`vendor/loader/src/index.ts:34`](../../vendor/loader/src/index.ts))

package/references/official-docs/docs/cordis-api/registry.i18n.yaml

@@ -1,6 +1,22 @@
-# 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:
+# Bilingual-pair consistency record for registry.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/registry.md
-registry.md: e6ddce5700ab071c2a4fedae19d99e2cb6e994ec
-registry.zh.md: d928ff20c9d764a36d84ce0d0aec0af7f41b630f
+/:
+  en: d2c0c5bce430d1be
+  zh: 24c4f62d45c2be68
+/registry:
+  en: 002c10f39db567b7
+  zh: 4bfdc14c16c43162
+/registry/ctx-inject-deps-callback:
+  en: 3e7b7ded1bf8ddf0
+  zh: 41d9e9dcd32df991
+/registry/ctx-plugin-plugin-args:
+  en: 9963e1dac2483850
+  zh: c56bfa38d1802a0e
+/registry/plugin:
+  en: 403f61a503ccf2ab
+  zh: 8c31f71930e984e2
+/registry/inject:
+  en: 6e730d459d7d5663
+  zh: f7ce147d927c83ad

package/references/official-docs/docs/cordis-api/service.i18n.yaml

@@ -1,6 +1,37 @@
-# 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:
+# Bilingual-pair consistency record for service.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/service.md
-service.md: d4b0f06da16decf31e0d348a88e0360b46ee9d35
-service.zh.md: ec0b443a0eae2787e0a3db919583d8092414c52d
+/:
+  en: d2c0c5bce430d1be
+  zh: 124ab2656ea6d044
+/service:
+  en: a163fe605c4a8045
+  zh: 060a6f4ce086c5c2
+/service/service-name:
+  en: 32a75e66b17c0b79
+  zh: 0a5ff9fc45b3bea0
+/service/static-members:
+  en: ceb197529207a8ed
+  zh: 7d444c03f8be0f0d
+/service/static-members/service-init:
+  en: ade1a1c4543fac8c
+  zh: b7a4b616ee930b5b
+/service/static-members/service-check:
+  en: 111351ada5972a9a
+  zh: 1537da7793a6a02c
+/service/static-members/service-config:
+  en: 93d8ff69722f9b46
+  zh: 9ba1532d164c2231
+/service/static-members/service-invoke:
+  en: 6d87f35f8cf52b05
+  zh: 278dbce6025b2834
+/service/static-members/service-extend:
+  en: 5b78b68d8de8cef9
+  zh: 6df27f37da11a104
+/service/static-members/service-tracker:
+  en: 52071ebded7ec026
+  zh: 4647fa3f989b5deb
+/service/static-members/service-resolveconfig:
+  en: ad62f59468d1a765
+  zh: 4a31b52f61e1af6e

package/references/official-docs/docs/cordis-primer.i18n.yaml

@@ -1,6 +1,22 @@
-# 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:
+# Bilingual-pair consistency record for cordis-primer.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-primer.md
-cordis-primer.md: 2e5a48745cf96068bec9e31b0c6f1bf9d84b0e34
-cordis-primer.zh.md: 3706173ddb6b097a59d7b85d08f04df7d0bd372f
+/cordis-primer:
+  en: 065178153a059ae3
+  zh: d1c5c429a8c35ac2
+/cordis-primer/cordis-in-five-ideas:
+  en: c11cc0f2927f7bad
+  zh: 4fc01f41da6b1c3e
+/cordis-primer/dispatch-modes:
+  en: 7adc1e4cc7a7a471
+  zh: 879bf8afcd8f7c9f
+/cordis-primer/cordis-waterfall-semantics:
+  en: 34055815ef4034ee
+  zh: a7e0c9c8cf12959a
+/cordis-primer/loader-configuration:
+  en: affe2b40ba1aa67d
+  zh: 34ed011226c6488b
+/cordis-primer/practical-rules:
+  en: 94846dacd018f8a1
+  zh: 2bae19522ab2e33f

package/references/official-docs/docs/cordis-tutorial/01-first-plugin.i18n.yaml

@@ -1,6 +1,22 @@
-# 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:
+# Bilingual-pair consistency record for 01-first-plugin.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/01-first-plugin.md
-01-first-plugin.md: 79df2f42df1f34a7ef32cc81607e1b926a1854ae
-01-first-plugin.zh.md: b7cfce290e86cebb12d99bcc438a281d4a988b4b
+/1-your-first-plugin:
+  en: 2b4f2febdeebdc74
+  zh: 98bc166d6cfd188a
+/1-your-first-plugin/write-the-plugin:
+  en: e2ec9e26bfd71d59
+  zh: 7c0d2b90a711ae4b
+/1-your-first-plugin/compose-the-app:
+  en: 529a55fb5ee74567
+  zh: f4b447fc0a68c0dd
+/1-your-first-plugin/run-it:
+  en: 7c55b7ecb982e94e
+  zh: dec70eb3ef18faec
+/1-your-first-plugin/the-two-other-plugin-shapes:
+  en: 39b0764924d85146
+  zh: 801fb0297e282df1
+/1-your-first-plugin/try-breaking-it:
+  en: 127d7a0916de2b66
+  zh: 86d4616c7a6aa82a

package/references/official-docs/docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml

@@ -1,6 +1,16 @@
-# 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:
+# Bilingual-pair consistency record for 02-lifecycle-and-effects.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/02-lifecycle-and-effects.md
-02-lifecycle-and-effects.md: 8e75708eb0cba1aceb7fa3dae5ae334995eb113f
-02-lifecycle-and-effects.zh.md: b5f8bc18ed242784528574a861c57bedae6fa880
+/2-lifecycle-and-effects:
+  en: d8936e9239303f91
+  zh: ee5a15bead15f7fa
+/2-lifecycle-and-effects/effects:
+  en: 2405133f23696f0e
+  zh: 30bcd69cba560176
+/2-lifecycle-and-effects/the-fiber-state-machine:
+  en: fe65d99ee289a273
+  zh: ee5cc95f67a2bc4c
+/2-lifecycle-and-effects/what-is-already-an-effect:
+  en: e986a639aac5eaff
+  zh: 8f907581f5725119

package/references/official-docs/docs/cordis-tutorial/03-services.i18n.yaml

@@ -1,6 +1,22 @@
-# 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:
+# Bilingual-pair consistency record for 03-services.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/03-services.md
-03-services.md: ebfc400dbbc701a3c164c7d30c371dec879d7d73
-03-services.zh.md: 8a4881eb41a9be09f531a58b528a2b64500b209a
+/3-services:
+  en: 15915c1948e99dcd
+  zh: 769f50dcd06a1c6e
+/3-services/provide-a-service:
+  en: dafc130ada001863
+  zh: 820921c32e8ce5fe
+/3-services/consume-a-service-with-inject:
+  en: 1b4faa79ebc5e3d7
+  zh: 5170a8291e4aaf34
+/3-services/dependencies-are-tracked-after-load:
+  en: 5cadb845bd8ebdb3
+  zh: cce559c73d7bda66
+/3-services/optional-dependencies:
+  en: f765739ab1e2061a
+  zh: 71ddc054022b66a9
+/3-services/naming:
+  en: 11dfa5c4f8aed0e0
+  zh: d28f7c86f58cdf3e

package/references/official-docs/docs/cordis-tutorial/04-events.i18n.yaml

@@ -1,6 +1,16 @@
-# 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:
+# Bilingual-pair consistency record for 04-events.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/04-events.md
-04-events.md: db911b9a06d7304d73030a2020de3d465fde2f9c
-04-events.zh.md: 0125f81c5521ed62da790ee7033ca4b715311ee1
+/4-events:
+  en: c0d426252aeee143
+  zh: a9d91f2ef46e2d3b
+/4-events/declare-emit-listen:
+  en: a5b9207a435caf1f
+  zh: 3e06d12249fb712e
+/4-events/dispatch-modes:
+  en: 24799f579b04b2d4
+  zh: 97d4d82dc3a02c75
+/4-events/waterfall-transform-or-short-circuit:
+  en: 8309aea415b395c3
+  zh: 480ee4a163543dd0

package/references/official-docs/docs/cordis-tutorial/05-config.i18n.yaml

@@ -1,6 +1,19 @@
-# 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:
+# Bilingual-pair consistency record for 05-config.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/05-config.md
-05-config.md: 17cccce2ec43be65477ce527800ee6a636ee5d96
-05-config.zh.md: e19dcb3ab0082cdc6ba2457158491ba47223409d
+/5-configuration:
+  en: 6867b9ed15839cf1
+  zh: 97425aab3396a458
+/5-configuration/a-configurable-plugin:
+  en: 1fcc4b1a64c6e6bb
+  zh: 85444447b593f18f
+/5-configuration/fail-loud:
+  en: 261253c9d96b0fc1
+  zh: 3f4ea5f34aa2637d
+/5-configuration/volatile-fields:
+  en: ee367f4db7e8598c
+  zh: c1f17caebad9cc0a
+/5-configuration/computed-config-values:
+  en: dbd47e8aa99fb2e0
+  zh: dc441f610416909d

package/references/official-docs/docs/cordis-tutorial/05-config.md

@@ -67,6 +67,33 @@ ValidationError: invalid config:
 
 The plugin's fiber goes to FAILED, and this tutorial's launcher exits with status 1 after printing the error. A plugin should also reject schema-valid config that names an unavailable resource or provider as soon as it can resolve that reference.
 
+<a id="volatile-fields"></a>
+## Volatile fields
+
+Use `.volatile()` for a field that the plugin reads during each operation. A change to that field updates its stable reference without remounting the plugin. Read it with `.get()`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import Schema from '@deepseek-ai/schemastery'
+
+export const Config = Schema.object({
+  greeting: Schema.string().default('Hello').volatile(),
+})
+
+export function apply(ctx: Context, config: ReturnType<typeof Config>) {
+  ctx.on('loader/volatile-update', () => {
+    console.log(config.greeting.get())
+  })
+}
+```
+
+A direct `Config(raw)` call also returns references. An optional field without a default still has a reference; `.get()` returns `undefined` when it is absent. Keep the reference, or capture its value for one operation, including across `await`. Do not retain that value for later operations. Object and array values are detached, recursively frozen snapshots of plain data; functions, class instances, and cycles are rejected.
+
+Loader compares raw config while ignoring schema-declared volatile fields. A volatile-only change is parsed through the plugin’s `internal/config` hook and validated; when every ordinary effective value still matches, Loader commits the new values into the running references and emits one instance-local `loader/volatile-update` with the changed paths as arrays of keys, bypassing the target plugin’s `internal/update`. Equal values do not notify. An invalid candidate is logged and leaves the running references unchanged until the next activation. A changed ordinary effective value, including a changed expression result, and simultaneous ordinary-field changes retain the existing update flow, leaving old references unchanged and unnotified. Group/Include still dispatch child updates. Direct `fiber.update()`, code replacement, and dependency replacement retain their lifecycle; `noSave` still controls direct-update persistence. Notifications use ordinary `emit` without awaiting resource reconfiguration.
+
+Declare volatile fields at fixed object paths, or mark an entire object or array volatile. Independent references inside arrays, dictionaries, union or intersect branches, lazy schemas, transforms, or another volatile value are rejected. Configuration files store ordinary values; `simplify()` unwraps references. Serialized schemas preserve their field types, defaults, roles, and volatile marker for schema-driven forms. Existing settings consumers continue to use their own settings interfaces.
+
 ## Computed config values
 
 The loader used in this repo supports a `!!js` tag for config values that must be computed at load time: