doxum 0.1.30 → 0.1.32

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

@@ -32,6 +32,8 @@ Use the simplest public primitive that owns the required semantics:
 | Ordered values as scalar array                      | `derive.keyed.values(source)`                  |
 | Ordered `[key,value]` tuples as scalar array        | `derive.keyed.entries(source)`                 |
 | Current scalar key selects one keyed entry          | `derive.keyed.get(source, keyProjection)`      |
+| Ordered scalar/static collection becomes keyed      | `derive.keyed.from(source, keyOf)`             |
+| Multiple keyed sources become one keyed union       | `derive.keyed.merge(sources, options)`         |
 | Select requested ordered subset                     | `derive.keyed.subset(source, orderedKeys)`     |
 | Preserve source values but filter membership        | `derive.keyed.filter(source, predicate)`       |
 | Map entry and drop `undefined` results              | `derive.keyed.compact(source, selector)`       |
@@ -113,22 +115,25 @@ const cards = derive.keyed(
   items,
   {
     density,
+    metadata: { source: metadataByItemId },
     record: { source: records, key: item => item.recordId },
     related: { source: records, keys: item => item.relatedRecordIds },
   },
-  (item, itemId, { density, record, related }) => renderCard(itemId, item, density, record, related)
+  (item, itemId, { density, metadata, record, related }) =>
+    renderCard(itemId, item, density, metadata, record, related)
 );
 ```
 
 Dependency forms:
 
 - ordinary `Projection<T>`: global dependency; when it changes, relevant driver work is invalidated as a whole;
+- `{ source }`: same-key lookup; driver key directly selects the source key and resolves to `V | undefined`;
 - `{ source, key }`: singular driver-key → source-key binding; resolved value is `V | undefined`;
 - `{ source, keys }`: ordered duplicate-free driver-key → source-keys binding; resolved value is `ReadonlyMap<K,V>` in requested-key order, containing currently present entries only.
 
-The Runtime owns forward binding and reverse invalidation. A missing selected source entry still keeps the binding, so a later source add invalidates the dependent driver key correctly.
+The same-key form requires `DriverKey extends SourceKey`; this preserves branded-key safety while allowing a narrower driver domain to read a broader source domain. It has no selector or relation map: source entry changes invalidate the driver entry with the same key directly. The Runtime owns forward binding and reverse invalidation for mapped forms. A missing selected source entry still keeps the binding, so a later source add invalidates the dependent driver key correctly.
 
-Source-only order change does not invalidate singular/plural keyed lookup because dependency identity is by selected key, not by source-global order.
+Source-only order change does not invalidate same/singular/plural keyed lookup because dependency identity is by selected key, not by source-global order.
 
 `keys(...)` selectors must return duplicate-free key arrays. Treat duplicate keys as invalid input rather than as a hidden deduplication feature.
 
@@ -168,6 +173,40 @@ const active = derive.keyed.get(rows, activeId);
 
 Use this for active entity, editor target, selected record, or current-cell lookups.
 
+## Keyed construction and composition
+
+### `from`
+
+```ts
+const rows = derive.keyed.from(rowArray, row => row.id);
+const projectedRows = derive.keyed.from(rowsProjection, row => row.id);
+```
+
+`source` is either a static readonly array or `Projection<readonly V[]>`. `keyOf(value)` defines stable member identity and must return a unique string key. The output formal order is exactly the input array order. Duplicate keys are processor errors; Doxum never silently overwrites or deduplicates them.
+
+Static outer arrays are shallow-snapshotted when the definition is created, while `keyOf` remains lazy until materialization. A scalar array projection has no per-entry delta, so every scalar publication is scanned. Output publication is still exact: same-key equality-equivalent values retain the previous published value identity, and reorder-only updates publish order without inventing value updates.
+
+### `merge`
+
+```ts
+const effective = derive.keyed.merge([base, overrides], {
+  conflict: 'last',
+});
+```
+
+`merge` accepts a fixed definition-time list of `KeyedProjection<K,V>` sources. Membership is their union. Conflict policy is required:
+
+- `error`: overlapping keys are processor errors;
+- `first`: earliest source wins;
+- `last`: latest source wins;
+- `resolve`: for true conflicts only, call `resolve(contributions, key)` with source-priority `{ sourceIndex, value }` contributions.
+
+A single contribution always passes through without invoking the resolver. Equality compares the final effective value and defaults to `Object.is`.
+
+Formal merged order is always the stable first occurrence from concatenated source orders: `stableUnique(S0.ids() ++ S1.ids() ++ ... ++ Sn.ids())`. Value winner and position are therefore independent. For base + sparse overrides, `{ conflict: 'last' }` changes shared values without moving their base positions; override-only keys are also valid union members. If an override disappears while base still contains the key, the merged membership lifecycle remains continuous and `runtime.items(merged).get(key)` keeps the same current membership identity.
+
+Value-only source changes only recompute affected keys. Structural or source-order changes may rebuild merged formal order. Present `undefined` remains a valid value because membership is determined by `has(key)`, not by `get(key) !== undefined`.
+
 ## Membership-changing keyed primitives
 
 ### `subset`
@@ -204,6 +243,8 @@ const recordsBySection = derive.keyed.groupBy(records, record => record.sectionI
 
 Selector returns one group key or a readonly group-key array. Output is `KeyedProjection<GroupKey, readonly SourceKey[]>`. Each group's members follow source formal order. The Runtime incrementally maintains reverse membership for added/updated/removed/order/reset.
 
+Group-key output order is also defined. Rank each group by the pair `(firstSourceIndex, selectorIndex)`: `firstSourceIndex` is the position of the earliest current source member that belongs to the group, and `selectorIndex` is that group's position in the selector result for that earliest member. Groups therefore follow first appearance in formal source order; when several groups first appear on the same source member, they follow the selector's returned group-key order for that member. If source order or membership changes, group keys may reorder according to the newly computed ranks.
+
 Use this for domain-neutral reverse indexing such as record→sections, node→edges, group→item ids. Keep domain names outside Doxum itself.
 
 ### `singleton`

package/skills/doxum-runtime/references/public-api.md

@@ -318,6 +318,24 @@ derive({ dependencyName: projection, ... }, values => result, equality?): Projec
 
 The keyed family:
 
+<!-- family:derive.keyed:start -->
+
+| Member      | Purpose                                                          |
+| ----------- | ---------------------------------------------------------------- |
+| `keys`      | Formal ordered membership as a scalar readonly array             |
+| `values`    | Formal ordered values as a scalar readonly array                 |
+| `entries`   | Formal ordered readonly `[key,value]` tuples                     |
+| `get`       | Scalar dynamic lookup into one current keyed entry               |
+| `from`      | Ordered scalar/static collection → keyed projection              |
+| `merge`     | Multiple keyed projections → union with explicit conflict policy |
+| `groupBy`   | One-to-many reverse index                                        |
+| `singleton` | Optional scalar → zero-or-one keyed projection                   |
+| `subset`    | Externally ordered keyed subset                                  |
+| `filter`    | Predicate-controlled membership preserving source values         |
+| `compact`   | Map values while dropping `undefined` results                    |
+
+<!-- family:derive.keyed:end -->
+
 ```ts
 derive.keyed(source, (value, key) => result, equality?): KeyedProjection<K,T>
 derive.keyed(source, dependencies, (value, key, dependencies) => result, equality?): KeyedProjection<K,T>
@@ -326,6 +344,10 @@ derive.keyed.keys(source): Projection<readonly K[]>
 derive.keyed.values(source): Projection<readonly V[]>
 derive.keyed.entries(source): Projection<readonly (readonly [K,V])[]>
 derive.keyed.get(source, keyProjection, equality?): Projection<V | undefined>
+derive.keyed.from(source: Projection<readonly V[]>, keyOf, equality?): KeyedProjection<K,V>
+derive.keyed.from(source: readonly V[], keyOf, equality?): KeyedProjection<K,V>
+derive.keyed.merge(sources, { conflict: 'error' | 'first' | 'last', equality? }): KeyedProjection<K,V>
+derive.keyed.merge(sources, { conflict: 'resolve', resolve, equality? }): KeyedProjection<K,V>
 derive.keyed.subset(source, orderedKeysOrProjection): KeyedProjection<K,V>
 derive.keyed.filter(source, predicate): KeyedProjection<K,V>
 derive.keyed.filter(source, dependencies, predicate): KeyedProjection<K,V>
@@ -336,14 +358,25 @@ derive.keyed.groupBy(source, dependencies, selector): KeyedProjection<GroupKey,
 derive.keyed.singleton(sourceProjection, keyOf, equality?): KeyedProjection<K,V>
 ```
 
+`from` uses `keyOf(value)` as member identity and preserves the input array's formal order. Duplicate keys are processor errors; there is no silent first/last overwrite. Static arrays are shallow-snapshotted at definition creation while `keyOf` remains lazy. For a scalar array projection, each scalar publication is scanned because the source has no per-entry delta. Equality defaults to `Object.is`; an equality-equivalent value under the same key retains the previous published value identity.
+
+`merge` has union membership and requires an explicit conflict policy. `first` and `last` use source-list priority. `error` rejects overlapping keys. `resolve` calls `resolve(contributions, key)` only for keys with two or more current contributions; contributions are ordered by source priority and have `{ sourceIndex, value }`. A single contribution passes through unchanged. The source list is fixed at definition time.
+
+Merged formal order is always `stableUnique(S0.ids() ++ S1.ids() ++ ... ++ Sn.ids())`, independent of which source supplies the effective value. Therefore `derive.keyed.merge([base, overrides], { conflict: 'last' })` is the standard base + sparse-override composition: override values win for shared keys without moving their base positions; override-only keys are included after earlier-source first occurrences. Removing an override does not end the merged membership lifecycle while another source still contains the key.
+
+`merge` equality compares the final effective value. Value-only changes only recompute affected keys; source membership/order changes may rebuild formal merged order. Present `undefined` is valid in both `from` and `merge`; membership is never inferred from `get(key) !== undefined`.
+
+`groupBy` has deterministic order on both axes. Every bucket value contains source keys in formal source order. Output group keys are ordered by the earliest current source member that belongs to each group; if multiple groups first occur on the same source member, their order is the selector's group-key order for that member. Source membership/order changes can therefore reorder group keys even when the set of groups is unchanged.
+
 Dynamic keyed dependency entries are either ordinary global `Projection`s or:
 
 ```ts
+{ source: keyedProjection }
 { source: keyedProjection, key: (driverValue, driverKey) => sourceKey | undefined }
 { source: keyedProjection, keys: (driverValue, driverKey) => readonly sourceKey[] }
 ```
 
-The singular resolved value is `V | undefined`; plural resolves to `ReadonlyMap<K,V>` in the requested key order, including only currently present entries.
+`{ source }` is a same-key dependency: the current driver key directly selects the source entry. It is allowed only when `DriverKey extends SourceKey`, so branded key domains remain type-safe. `{ source, key }` is a mapped singular lookup. Both singular forms resolve to `V | undefined`. `{ source, keys }` resolves to `ReadonlyMap<K,V>` in the requested key order, including only currently present entries. Selector callbacks remain value-first: `(driverValue, driverKey)`.
 
 ### Projection runtime and scope
 

package/skills/doxum-runtime/references/recipes.md

@@ -269,15 +269,17 @@ Use projection input for Runtime-local UI/application state. Keep it out of the
 const cards = derive.keyed(
   items,
   {
+    metadata: { source: metadataByItemId },
     record: { source: records, key: item => item.recordId },
     related: { source: records, keys: item => item.relatedRecordIds },
     density,
   },
-  (item, itemId, { record, related, density }) => buildCard(itemId, item, record, related, density)
+  (item, itemId, { metadata, record, related, density }) =>
+    buildCard(itemId, item, metadata, record, related, density)
 );
 ```
 
-The Runtime owns reverse invalidation. Do not subscribe to `records` and manually maintain `recordId -> itemIds` just for dependency routing.
+Use `{ source }` when the dependency uses the same key as the driver; it replaces identity selectors such as `key: (_value, id) => id`. Use `{ source, key }` for one mapped key and `{ source, keys }` for several mapped keys. The Runtime owns invalidation routing. Do not subscribe to sources and manually maintain reverse maps just for dependency routing.
 
 ## Ordered keyed entries as a scalar value
 
@@ -287,6 +289,35 @@ const entries = derive.keyed.entries(records);
 
 Use this instead of a two-stage `derive.keyed(records, (value,key) => [key,value])` followed by `values`.
 
+## Ordered scalar/static collection to keyed
+
+```ts
+const visibleFields = derive.keyed.from(visibleFieldArray, field => field.id);
+```
+
+Use `from` when the source shape is an ordered scalar array and downstream work needs formal keyed membership/order. `keyOf` must produce unique stable keys. For high-frequency single-key edits, keep the source keyed instead of repeatedly flattening it to a scalar array first.
+
+## Synthetic fixed entry plus dynamic keyed source
+
+```ts
+const titleFields = derive.keyed.from<FieldId, Field>([titleField], field => field.id);
+const allFields = derive.keyed.merge([titleFields, fields], {
+  conflict: 'error',
+});
+```
+
+Use this instead of an application-maintained `Set`/`Map` plus manual output ordering. `conflict: 'error'` makes an accidental collision between the synthetic entry and dynamic source explicit.
+
+## Base plus sparse overrides
+
+```ts
+const effectiveRows = derive.keyed.merge([baseRows, rowOverrides], {
+  conflict: 'last',
+});
+```
+
+Shared keys use override values while keeping the first formal position from `baseRows`. Keys that exist only in `rowOverrides` are also included because merge membership is a union. Removing an override falls back to the base value without ending the merged key's membership lifecycle while the base key remains present.
+
 ## Active keyed lookup
 
 ```ts
@@ -304,6 +335,8 @@ const recordIdsBySection = derive.keyed.groupBy(records, record => record.sectio
 
 Output is keyed by section id; each value is ordered source record ids. Use this instead of maintaining a global reverse-index Map in application code.
 
+Group keys follow first appearance in the source's formal order. If one source record returns several groups, those groups use the selector's returned order for that record when they first appear together.
+
 ## Optional scalar to keyed singleton
 
 ```ts