doxum 0.1.26 → 0.1.28

package/skills/doxum-runtime/references/projections.en.md

@@ -70,6 +70,39 @@ Only affected driver entries execute the selector. Per-entry equality suppresses
 `updated` output transition when the selected value is unchanged. Added, removed and
 order transitions retain their normal collection meaning.
 
+Standard keyed structure reads use the same family:
+
+```ts
+const ids = derive.keyed.keys(records);
+const all = derive.keyed.values(records);
+const entries = derive.keyed.entries(records);
+const active = derive.keyed.get(records, activeRecordId);
+```
+
+`keys` changes only for add/remove/order/reset and keeps its published array reference
+on value-only updates. `values` and `entries` follow the keyed collection's formal order;
+`entries` reuses unchanged tuple references. `get` binds exactly to the selected key,
+including a currently missing key so a later add invalidates the scalar result.
+
+Membership-changing derives are first-class rather than application-side incremental
+collection patch loops:
+
+```ts
+const visible = derive.keyed.filter(fields, field => field.visible);
+const ordered = derive.keyed.subset(fields, visibleFieldIds);
+const content = derive.keyed.compact(cards, card => card.content);
+const bySection = derive.keyed.groupBy(records, record => record.sectionId);
+const activeCollection = derive.keyed.singleton(activeRecord, record => record.id);
+```
+
+`filter` preserves source values and source-relative order. `subset` uses
+`orderedKeys ∩ source.keys` with orderedKeys order; missing requested keys remain latent,
+and duplicate ordered keys are invalid. `compact` treats selected `undefined` as output
+absence and uses optional per-entry equality for present values. `filter` and `compact`
+accept the same named global/dynamic keyed dependencies as ordinary `derive.keyed`.
+`groupBy` is the one-to-many reverse-index primitive and preserves source order inside
+each bucket; `singleton` converts an optional scalar to a zero-or-one keyed projection.
+
 Dynamic keyed lookups stay in the same API:
 
 ```ts
@@ -77,17 +110,22 @@ const cardContent = derive.keyed(
   items,
   {
     record: { source: records, key: item => item.recordId },
+    related: { source: records, keys: item => item.relatedRecordIds },
     view: activeView,
     fields: visibleFields,
   },
-  (item, itemId, { record, view, fields }) => renderCard(itemId, item, record, view, fields)
+  (item, itemId, { record, related, view, fields }) =>
+    renderCard(itemId, item, record, related, view, fields)
 );
 ```
 
 A plain Projection dependency invalidates the driver key set when it changes.
 `{ source, key }` declares an output-key → dynamic source-key dependency. The Runtime
 owns forward bindings and reverse invalidation. Missing selected entries remain bound,
-so adding that source key later invalidates its dependents.
+so adding that source key later invalidates its dependents. `{ source, keys }` binds one
+driver key to an ordered duplicate-free set of source keys and resolves to a readonly map
+of currently present selected entries. Source order-only changes do not invalidate keyed
+lookup dependencies.
 
 This is the keyed join protocol. Do not add a second join abstraction, wildcard
 document-path grammar, or processor-side imperative dependency discovery.
@@ -98,6 +136,8 @@ document-path grammar, or processor-side imperative dependency discovery.
 const value = runtime.read(visible);
 const selected = runtime.select(visible, rows => rows.get(rowId), equality);
 const stop = selected.subscribe(listener);
+const itemFamily = runtime.items(records);
+const record = itemFamily.get(rowId);
 
 runtime.update(filter, 'open');
 runtime.update(selection, draft => {
@@ -111,6 +151,12 @@ runtime.batch(run, { cause });
 `select` returns the standard `Readable`. Keyed selectors track relevant key/structure
 reads; equality filters the result only after a related invalidation.
 
+`runtime.items(keyedProjection)` returns one Runtime-owned keyed Readable family with
+ordered `keys` and `get(key)`. An item's Readable identity is stable for one published
+membership generation. Remove retires that generation; a later re-add creates a new
+identity. Subscribed missing items remain latent and can activate on a future add. The
+same API exists on `ProjectionScope` and follows that scope's disposal lifetime.
+
 `CollectionInputDraft` exposes `get`, `has`, `set`, `remove` and expires with the
 synchronous edit callback. A throwing callback applies none of that edit. Collection
 input equality is per entry and defaults to `Object.is`; it runs before accepted local
@@ -155,14 +201,18 @@ type CollectionChange<K extends string, V> =
 Import `CollectionChange` from `doxum/advanced` when an advanced processor signature
 needs it. Root projection consumers do not import this transport type.
 
+`collectionChange.keys(change)` from `doxum/advanced` accepts an incremental change and
+lazily yields added, updated and removed keys in that order. It does not interpret reset
+or turn order changes into entry changes; callers decide those semantics explicitly.
+
 Initial materialization and source reset report `reset` to advanced processors.
 Incremental transitions are exact net changes across the settled Runtime batch.
 
 ## Advanced processors
 
 Import `incremental` from `doxum/advanced` only when retained state, cross-key indexes,
-or direct incremental output patching cannot be expressed cleanly with `derive` or
-`derive.keyed`.
+or direct incremental output patching cannot be expressed cleanly with `derive` or the
+`derive.keyed` family.
 
 All advanced processors use named dependencies plus a required `process`. Add `state()`
 only when the processor needs retained state:
@@ -195,6 +245,29 @@ const weights = incremental.collection(
 collection change metadata. Collection processors additionally expose keyed
 `previous`, `next`, and a borrowed `output` draft.
 
+For independent retained state per driver key, use `incremental.keyed`:
+
+```ts
+const totals = incremental.keyed(
+  sections,
+  { records: { source: records, keys: section => section.recordIds } },
+  {
+    state: () => ({ runs: 0 }),
+    process: ({ dependencies, state }) => {
+      state.runs++;
+      return [...dependencies.records.values()].reduce((sum, record) => sum + record.score, 0);
+    },
+  }
+);
+```
+
+The driver owns output membership/order. Ordinary dependencies invalidate every current
+driver key; singular/plural keyed dependencies reverse-route only affected keys. Order-only
+driver changes do not execute `process`. Remove releases that key's state, re-add creates
+a new membership lifecycle, reset intersections retain state, and processor recovery
+recreates all per-key state. The process returns only its own output value and does not
+receive a collection draft.
+
 Multi-output processors use one closed group definition:
 
 ```ts

package/skills/doxum-runtime/references/projections.zh-CN.md

@@ -68,6 +68,39 @@ const fieldValues = derive.keyed(records, record => record.values[fieldId]);
 只有受影响 driver entry 会执行 selector。per-entry equality 判定 selected value 相等时，
 该 key 不发布 `updated`；added、removed、order 语义保持不变。
 
+标准 keyed structure read 仍属于同一个 family：
+
+```ts
+const ids = derive.keyed.keys(records);
+const all = derive.keyed.values(records);
+const entries = derive.keyed.entries(records);
+const active = derive.keyed.get(records, activeRecordId);
+```
+
+`keys` 只在 add/remove/order/reset 时变化，value-only update 保持已发布 array 的引用与
+revision；`values` / `entries` 始终遵循 keyed collection 的正式顺序，`entries` 会复用
+未变化 entry 的 tuple 引用。`get` 只绑定当前 scalar-selected key；即使 key 当前缺失，
+binding 仍保留，因此以后 add 会正确触发 scalar result。
+
+membership-changing derive 也作为正式 primitive，而不是让应用手写 incremental
+collection patch：
+
+```ts
+const visible = derive.keyed.filter(fields, field => field.visible);
+const ordered = derive.keyed.subset(fields, visibleFieldIds);
+const content = derive.keyed.compact(cards, card => card.content);
+const bySection = derive.keyed.groupBy(records, record => record.sectionId);
+const activeCollection = derive.keyed.singleton(activeRecord, record => record.id);
+```
+
+`filter` 保留 source value 与 source-relative order。`subset` 使用
+`orderedKeys ∩ source.keys`，顺序由 orderedKeys 决定；当前缺失的 requested key 保持
+latent，后续 source add 时自动出现，duplicate ordered keys 非法。`compact` 将 selected
+`undefined` 解释为 output absence，对 present value 使用可选 per-entry equality。
+`filter` / `compact` 与普通 `derive.keyed` 共用 named global/dynamic keyed dependencies。
+`groupBy` 是通用一对多 reverse-index primitive，bucket member 遵循 source 正式顺序；
+`singleton` 将 optional scalar 转成 0/1 keyed projection。
+
 Dynamic keyed lookup 仍使用同一个 API：
 
 ```ts
@@ -75,17 +108,21 @@ const cardContent = derive.keyed(
   items,
   {
     record: { source: records, key: item => item.recordId },
+    related: { source: records, keys: item => item.relatedRecordIds },
     view: activeView,
     fields: visibleFields,
   },
-  (item, itemId, { record, view, fields }) => renderCard(itemId, item, record, view, fields)
+  (item, itemId, { record, related, view, fields }) =>
+    renderCard(itemId, item, record, related, view, fields)
 );
 ```
 
 普通 Projection dependency 变化时使 driver key set 失效。`{ source, key }` 声明
 output-key → dynamic source-key dependency；Runtime 拥有 forward binding 和 reverse
 invalidation。selected source entry 缺失时仍保留 binding，因此以后新增该 source key
-会正确触发 dependent output key。
+会正确触发 dependent output key。`{ source, keys }` 将一个 driver key 绑定到一个有序、
+无重复的 source-key 集合，dependency value 是按声明顺序包含当前存在 entry 的 readonly
+map；source 仅 order 变化不会使 keyed lookup 失效。
 
 这就是 keyed join 协议。不要再添加第二套 join abstraction、wildcard document path
 grammar 或 processor 内 imperative dependency discovery。
@@ -96,6 +133,8 @@ grammar 或 processor 内 imperative dependency discovery。
 const value = runtime.read(visible);
 const selected = runtime.select(visible, rows => rows.get(rowId), equality);
 const stop = selected.subscribe(listener);
+const itemFamily = runtime.items(records);
+const record = itemFamily.get(rowId);
 
 runtime.update(filter, 'open');
 runtime.update(selection, draft => {
@@ -109,6 +148,12 @@ runtime.batch(run, { cause });
 `select` 返回标准 `Readable`。keyed selector 追踪相关 key/structure 读取；只有发生
 相关 invalidation 后才执行 selector，随后 equality 决定是否发布结果。
 
+`runtime.items(keyedProjection)` 返回一个 Runtime-owned keyed Readable family：`keys`
+表示正式有序 membership，`get(key)` 在一次 published membership generation 内保持
+Readable identity。remove 会结束这一 generation；同 key 以后 re-add 会得到新 identity。
+已订阅的 missing item 可以保持 latent，并在未来 add 时激活。`ProjectionScope.items`
+使用相同语义，并随 scope disposal 一起结束。
+
 `CollectionInputDraft` 提供 `get`、`has`、`set`、`remove`，同步 edit callback 返回后
 失效。callback throw 时该次 edit 不应用。collection input equality 按 entry 比较，
 默认 `Object.is`，并在接受的本地状态安装前完成；equality 抛错时，published value 与
@@ -152,13 +197,17 @@ type CollectionChange<K extends string, V> =
 advanced processor 需要显式标注该 transport type 时，从 `doxum/advanced` 导入
 `CollectionChange`；root projection consumer 不需要从 package root 导入它。
 
+`doxum/advanced` 的 `collectionChange.keys(change)` 接受 incremental change，按
+added → updated → removed 惰性遍历 entry-transition keys。它不解释 reset，也不会把
+order change 转成 entry change；这些语义由调用方显式决定。
+
 initial materialization 和 source reset 对 advanced processor 报告 `reset`。
 incremental transition 是 settle 后 batch 边界上的 exact net change。
 
 ## Advanced processor
 
 只有 retained state、cross-key index 或直接 incremental output patch 无法用
-`derive` / `derive.keyed` 清晰表达时，才从 `doxum/advanced` 引入 `incremental`。
+`derive` / `derive.keyed` family 清晰表达时，才从 `doxum/advanced` 引入 `incremental`。
 
 所有 advanced processor 都使用 named dependencies，并且 `process` 必需。只有确实需要
 retained state 时才声明 `state()`：
@@ -191,6 +240,28 @@ const weights = incremental.collection(
 metadata。collection processor 额外提供 keyed `previous`、`next` 和 borrowed
 `output` draft。
 
+每个 driver key 需要独立 retained state 时使用 `incremental.keyed`：
+
+```ts
+const totals = incremental.keyed(
+  sections,
+  { records: { source: records, keys: section => section.recordIds } },
+  {
+    state: () => ({ runs: 0 }),
+    process: ({ dependencies, state }) => {
+      state.runs++;
+      return [...dependencies.records.values()].reduce((sum, record) => sum + record.score, 0);
+    },
+  }
+);
+```
+
+driver 独占 output membership/order。普通 dependency 变化会 invalidate 当前所有 driver
+key；singular/plural keyed dependency 通过 reverse routing 只运行真正受影响的 key。
+driver 仅 order 变化不会执行 `process`。remove 释放该 key 的 state，re-add 建立新的
+membership lifecycle；reset intersection 保留 state，processor fault recovery 重建全部
+per-key state。process 只返回自身 output value，不暴露 collection draft。
+
 多输出 processor 使用一个 closed group definition：
 
 ```ts