Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -543,8 +543,10 @@ Rejection codes: `malformed_op`, `unknown_op`, `op_deferred`,
`catalog_required`, `invalid_node_payload`, `unknown_widget`,
`uncatalogued_widget_write`, `opaque_widgets`, `widget_out_of_range`,
`input_slot_missing`, `output_slot_missing`, `not_a_subgraph`,
`interior_node_not_found`, `shared_definition_unforked`, `batch_aborted`, and
`apply_failed` for anything unexpected. Match on `code`, never on `message`.
`interior_node_not_found`, `shared_definition_unforked`,
`dynamic_group_count_out_of_range`, `dynamic_group_form_mismatch`,
`batch_aborted`, and `apply_failed` for anything unexpected. Match on `code`,
never on `message`.

`uncatalogued_widget_write` means a NAME-KEYED widget write named a class the
pinned catalog does not describe. `add_node` and `set_widget` (and `connect`'s
Expand Down
4 changes: 2 additions & 2 deletions docs/dynamic-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ To regenerate `test/fixtures/dynamic-group.json` at that revision, load `tests/c

`dynamic_groups` maps a row-count controller to `min`, `max`, relative `widgets`, and field `defaults`. Each row expands immediately after its controller under `<controller>.<index>.<field>`. Remove any default rows already present in `widget_order` before expanding the saved count.

The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Catalog bounds must be integers with `0 <= min <= max`. Counts must be integers from `min` to the allocation bound, and row-field names must address a row below that bound. The bound is shared by every group of an entry: `MAX_OVERFLOW_WIDGETS` divided by the total number of row fields across those groups. So all of an entry's rows together stay within `MAX_OVERFLOW_WIDGETS` slots, however many controllers the entry has. A count below `min` is refused because the frontend raises it to `min`, which would leave the document and canvas with different row counts.
The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Catalog bounds must be integers with `0 <= min <= max`. Counts must be integers from `min` to the allocation bound, and row-field names must address a row below that bound. The bound is shared by every group of an entry: `MAX_OVERFLOW_WIDGETS` divided by the total number of row fields across those groups. So all of an entry's rows together stay within `MAX_OVERFLOW_WIDGETS` slots, however many controllers the entry has. A count below `min` is refused because the frontend raises it to `min`, which would leave the document and canvas with different row counts. A count outside this range is rejected `dynamic_group_count_out_of_range` on `set_widget` and on `add_node`/`insert_workflow` payloads, including their definitions; `mint` still throws a `TypeError`. A node with `widgets_values_form` keeps its declared values verbatim, so these payload and `mint` checks do not cover its counts. A catalog whose `min` exceeds the allocation bound is malformed and is rejected `apply_failed`. A row-field name beyond the allocation bound is `unknown_widget`, like any other name the node does not have.

Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Agent row changes use whole-group replacement instead: the producer writes the count and every visible row field in one batch, keeping linked or promoted rows in place, so this package needs no structural operation.

An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. A selector refresh of an array form keeps its declared row fields where the producer placed them. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms.
An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. A selector refresh of an array form keeps its declared row fields where the producer placed them. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is rejected `dynamic_group_form_mismatch` before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms.

No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10).

Expand Down
9 changes: 5 additions & 4 deletions docs/multiplayer-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -2392,9 +2392,10 @@ A node carrying the field is **self-described**, and for it:
statement for ARRAY forms only: a pinned dynamic-combo option child is also
legal and a winning selector persists the recomputed realized order.
Amendment A26 uses supplied `dynamic_groups` metadata only for count
validation: it checks the row-count bounds and refuses a change from the
addressed occurrence's stored count that would require replacing the
declaration;
validation: it refuses a count outside the row-count bounds
(`dynamic_group_count_out_of_range`) and a change from the addressed
occurrence's stored count that would require replacing the declaration
(`dynamic_group_form_mismatch`);
- `project()` rebuilds `widgets_values` in the shape the producer serialized —
an array of `order.length`, or the object in its original key order with each
declared widget taking its live value and every other key its verbatim
Expand Down Expand Up @@ -2600,4 +2601,4 @@ persists, so KA-11 does not require a layout bump or migration.

An opt-in `dynamic_groups` catalog entry expands a saved row-count controller into indexed widget identities. These use the existing name-keyed registers; no op kind or on-document key changes. The new catalog hash requires coordinated reader adoption. Existing documents retain their original catalog and are re-minted to adopt the new layout.

Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds row-count bound validation (`min` to the allocation bound) and rejects a count change requiring a new declaration before mutation. This validation applies to the addressed occurrence in top-level, interior, and promoted writes. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance.
Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds row-count bound validation (`min` to the allocation bound) and rejects a count change requiring a new declaration before mutation. This validation applies to the addressed occurrence in top-level, interior, and promoted writes. A count outside that range is rejected `dynamic_group_count_out_of_range`, whether it arrives as a `set_widget` value or as a saved count in an `add_node` or `insert_workflow` payload (including its definitions); a count change against a declared form is rejected `dynamic_group_form_mismatch`. Both are new rejection codes, so callers can count DynamicGroup refusals without parsing messages. A row-field name that no group row can address keeps `unknown_widget`, as any other unknown widget name does. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance.
12 changes: 8 additions & 4 deletions src/applier.ts
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ import {
type WireOp,
} from "./types.js";
import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js";
import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js";
import { DynamicGroupCountError, groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js";
import {
optionOwnedWidgets,
projectedLength,
Expand Down Expand Up @@ -279,7 +279,10 @@ export function applyOps(doc: Y.Doc, ops: Op[], catalog?: WidgetCatalog, context
});
}
} catch (err) {
rejectRemainder(err, op, index);
// Raised from the shared layout code, which also serves mint and project.
rejectRemainder(err instanceof DynamicGroupCountError
? new OpRejectedError("dynamic_group_count_out_of_range", err.message)
: err, op, index);
return false;
}
return true;
Expand Down Expand Up @@ -1150,6 +1153,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC
nodeWrites.push([String(node.id), node.id, createNodeMap(node,
declaresWidgetForm(node) ? undefined : widgetOrderForValues(entry, node.widgets_values))]);
} catch (err) {
if (err instanceof DynamicGroupCountError) throw err;
throw new OpRejectedError("invalid_node_payload", `insert_workflow(${node.type}): ${err instanceof Error ? err.message : String(err)}`);
}
}
Expand Down Expand Up @@ -2028,11 +2032,11 @@ function validateWidgetOp(op: SetWidgetOp) {
function validateDynamicGroupValue(node: Y.Map<unknown>, catalog: WidgetCatalog | undefined, widget: string, occurrence: number, value: unknown): void {
const entry = catalogEntry(catalog, String(node.get("type") ?? ""));
const refusal = groupCountRefusal(entry, widget, value);
if (refusal) throw new OpRejectedError("malformed_op", refusal);
if (refusal) throw new DynamicGroupCountError(refusal);
if (groupOf(entry, widget) && storedWidgetFormOf(node)) {
const widgets = node.get("widgets");
if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, occurrence)) !== value) {
throw new OpRejectedError("malformed_op", "row count changes require an updated widgets_values_form declaration");
throw new OpRejectedError("dynamic_group_form_mismatch", "row count changes require an updated widgets_values_form declaration");
}
}
}
Expand Down
4 changes: 2 additions & 2 deletions src/dynamic-combos.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
*/
import * as Y from "yjs";

import { assertDynamicGroupCatalog, fieldGroupOf, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js";
import { assertDynamicGroupCatalog, DynamicGroupCountError, fieldGroupOf, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js";
import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js";
import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js";

Expand Down Expand Up @@ -137,7 +137,7 @@ export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv:
for (const name of Object.keys(entry.dynamic_groups ?? {})) {
if (!Object.hasOwn(named, name)) continue;
const refusal = groupCountRefusal(entry, name, named[name]);
if (refusal) throw new TypeError(refusal);
if (refusal) throw new DynamicGroupCountError(refusal);
}
return expand(entry, combos ?? {}, (name) => (Object.hasOwn(named, name) ? named[name] : undefined)).order;
}
Expand Down
10 changes: 8 additions & 2 deletions src/dynamic-groups.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
import { MAX_OVERFLOW_WIDGETS } from "./limits.js";
import type { WidgetCatalogEntry } from "./types.js";

/** A row count outside `min` to the allocation bound; `applyOps` rejects it `dynamic_group_count_out_of_range`. */
export class DynamicGroupCountError extends TypeError {}

export function groupOf(entry: WidgetCatalogEntry | undefined, name: string) {
const groups = entry?.dynamic_groups;
return groups && Object.hasOwn(groups, name) ? groups[name] : undefined;
Expand Down Expand Up @@ -94,7 +97,10 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void {
throw new TypeError(`DynamicGroup '${name}' must declare integer row bounds with 0 <= min <= max`);
}
}
for (const [name] of groups) {
for (const [name, group] of groups) {
if (group.min > maxRows(entry)) {
throw new TypeError(`DynamicGroup '${name}' minimum exceeds the widget allocation bound`);
}
if (Object.hasOwn(entry.dynamic_combos ?? {}, name) || isDynamicGroupField(entry, name)) {
throw new TypeError(`DynamicGroup controller '${name}' collides with another dynamic widget`);
}
Expand Down Expand Up @@ -122,7 +128,7 @@ export function groupLayout(entry: WidgetCatalogEntry, name: string, value: unkn
if (!group) return undefined;
const count = value === undefined ? group.min : value;
const refusal = groupCountRefusal(entry, name, count);
if (refusal) throw new TypeError(refusal);
if (refusal) throw new DynamicGroupCountError(refusal);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
const order: string[] = [];
const defaults = new Map<string, unknown>();
defaults.set(name, group.min);
Expand Down
Loading
Loading