doxum 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",

package/skills/doxum-runtime/SKILL.md

@@ -44,11 +44,12 @@ Follow these choices unless the requirement says otherwise:
 3. Use `read` for one synchronous document read and `select` for a document `Readable` with dynamic dependency tracking.
 4. Use `observe` to bring a document/readable/external source into the projection graph.
 5. Use named-object `derive` for pure aggregate values.
-6. Use `derive.keyed` when one keyed source owns output membership/order. Prefer its built-in `keys`, `values`, `entries`, `get`, `subset`, `filter`, `compact`, `groupBy`, and `singleton` primitives over hand-written incremental collection patches.
-7. Express per-output-key joins through `{ source, key }` or `{ source, keys }` dependencies. Let the Runtime own binding and reverse invalidation; do not maintain an application `Map` just to route dependency changes.
-8. Use `runtime.items(keyedProjection)` or `scope.items(...)` for stable per-membership item `Readable`s.
-9. Use `incremental.keyed` for independent retained state per driver key. Use `incremental.collection` or `incremental.group` only when direct incremental output patching or shared retained state is required.
-10. Use `ProjectionScope` only for lifecycle ownership. Define projections normally, then `scope.own(...)` before that definition is first materialized as a root.
+6. Use `derive.keyed.from` to turn an ordered scalar/static collection into a keyed projection. Use `derive.keyed.merge` to compose multiple keyed projections; for base + sparse overrides, use `{ conflict: 'last' }`.
+7. Use `derive.keyed` when one keyed source owns output membership/order. Prefer its built-in `keys`, `values`, `entries`, `get`, `from`, `merge`, `subset`, `filter`, `compact`, `groupBy`, and `singleton` primitives over hand-written incremental collection patches.
+8. Express per-output-key joins through `{ source, key }` or `{ source, keys }` dependencies. Let the Runtime own binding and reverse invalidation; do not maintain an application `Map` just to route dependency changes.
+9. Use `runtime.items(keyedProjection)` or `scope.items(...)` for stable per-membership item `Readable`s.
+10. Use `incremental.keyed` for independent retained state per driver key. Use `incremental.collection` or `incremental.group` only when direct incremental output patching or shared retained state is required.
+11. Use `ProjectionScope` only for lifecycle ownership. Define projections normally, then `scope.own(...)` before that definition is first materialized as a root.
 
 ## Failure and lifecycle rules
 

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)`       |
@@ -168,6 +170,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 +240,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,6 +358,16 @@ 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

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

@@ -287,6 +287,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 +333,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