diff --git a/README.md b/README.md index 20d0faf7..280a974a 100644 --- a/README.md +++ b/README.md @@ -334,11 +334,12 @@ Every op carries the same envelope, minted by its creator before dispatch: } ``` -Six kinds, frozen: +Seven kinds, frozen: | Kind | Payload beyond the envelope | Batchable (authoring) | |---|---|---| | `add_node` | `node_id`, `class_type`, `pos`, `node` (the complete node object, inserted verbatim) | yes | +| `define_subgraph` | `subgraph_id`, `subgraph_definition` (the complete initial definition, inserted once) | yes | | `connect` | `link_id`, `from_node`, `from_slot`, `to_node`, `link_type`, then EITHER a numeric `to_slot` (`ConcreteConnectOp`) OR a `grow` payload with `to_slot` null/absent (`GrowConnectOp`); `grow.promoted: true` names a subgraph instance's DECLARED input, materialized on the instance and LWW-gated as one register (schema Amendment A15) | yes | | `disconnect` | `link_id`, `to_node`, `to_slot`; claims the same concrete input register as `connect` and removes the winning slot occupant | yes | | `set_widget` | `node_id`, `widget` (name, never index), `value`, optional `old`; an interior write adds `path` AND `inner_widget` together (`InteriorSetWidgetOp`); a promoted HOST write adds `promoted: {value_index, instance_path, host_widgets_values}` instead — a positional write into a subgraph instance's opaque array (schema Amendment A15) | yes | diff --git a/src/applier.ts b/src/applier.ts index 2cf4f110..90634e5d 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -88,6 +88,7 @@ import { arrayItemRefusal, countDefinitionInstances, createNodeMap, + definitionsMap, linksMap, mapValueRefusal, mdel, @@ -107,6 +108,8 @@ import { MAX_PAYLOAD_DEPTH, opBoundsRefusal, } from "./limits.js"; +import { mintDefinition } from "./mint.js"; +import { projectDefinition } from "./project.js"; import { codePointCompare, compareStampKeys, stampKey, stampTargetKey, widgetTargetKey } from "./stamps.js"; import { DEFERRED_OPS, @@ -118,6 +121,7 @@ import { type ApplyResult, type ConnectOp, type DeleteNodeOp, + type DefineSubgraphOp, type DisconnectOp, type GrowConnectOp, type GrowSpec, @@ -273,11 +277,11 @@ function opIdentity(op: unknown): string { * NOT stored — see {@link opDigest}. Exposed to tests as the definition of * what the digest is taken over. */ -export function canonicalOp(op: Op): string { +function canonicalJson(value: unknown): string { // BigInt classification takes precedence over the generic depth/cost gates. // Keep this walk iterative and bounded so even a hostile envelope cannot // turn the diagnostic into unbounded work. - const bigintStack: Array<{ value: unknown; path: string }> = [{ value: op, path: "$" }]; + const bigintStack: Array<{ value: unknown; path: string }> = [{ value, path: "$" }]; const bigintVisited = new Set(); let bigintVisits = 0; while (bigintStack.length > 0 && bigintVisits++ <= MAX_OP_COST) { @@ -312,7 +316,7 @@ export function canonicalOp(op: Op): string { // Amendment A11 extends A8's whole-envelope, pre-idempotency gate with a // breadth/size budget. Its iterative depth check keeps A8's // `payload_too_deep` vocabulary while avoiding hostile recursion. - const bounds = opBoundsRefusal(op); + const bounds = opBoundsRefusal(value); if (bounds !== null) { throw new OpRejectedError( bounds.includes("nests deeper") ? "payload_too_deep" : "malformed_op", @@ -344,7 +348,11 @@ export function canonicalOp(op: Op): string { } return value; }; - return JSON.stringify(normalize(op, 0, "$")); + return JSON.stringify(normalize(value, 0, "$")); +} + +export function canonicalOp(op: Op): string { + return canonicalJson(op); } /** @@ -406,6 +414,12 @@ function validateEnvelope(op: WireOp): void { if (!(FROZEN_OPS as readonly string[]).includes(op.op)) { throw new OpRejectedError("unknown_op", `unknown op '${op.op}'`); } + if (op.op !== "define_subgraph") { + const ordinary = op as WireOp & Record; + if ("subgraph_definition" in ordinary || "definitions" in ordinary || "subgraph_id" in ordinary) { + throw new OpRejectedError("malformed_op", `${op.op}: definition payloads and subgraph_id targets are only valid on define_subgraph`); + } + } if (typeof op.op_id !== "string" || op.op_id.length === 0) { throw new OpRejectedError("malformed_op", `${op.op}: missing op_id`); } @@ -459,6 +473,8 @@ function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcom return applyDeleteNode(doc, op); case "clear": return applyClear(doc, op); + case "define_subgraph": + return applyDefineSubgraph(doc, op, catalog); default: // Exhaustiveness guard (issue #21): with every `Op` member cased above, // `op` is `never` here. Add a sixth IMPLEMENTED kind to `Op` and this @@ -477,6 +493,311 @@ function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcom } } +function applyDefineSubgraph( + doc: Y.Doc, + op: DefineSubgraphOp, + catalog?: WidgetCatalog, +): SuccessfulOutcome { + if (!isUuid(op.subgraph_id) || !isPlainRecord(op.subgraph_definition) || op.subgraph_definition.id !== op.subgraph_id) { + throw new OpRejectedError( + "malformed_op", + "define_subgraph: subgraph_id must be a UUID matching subgraph_definition.id", + ); + } + validateSubgraphDefinition(op.subgraph_definition, "subgraph_definition"); + if (!catalog) { + throw new OpRejectedError("catalog_required", "define_subgraph: the pinned catalog is required to encode interior nodes"); + } + const digest = sha256Hex(canonicalJson(op.subgraph_definition)); + validateDefinitionWidgets(op.subgraph_definition, catalog); + const definitions = definitionsMap(doc); + const existing = definitions.get(op.subgraph_id); + if (existing !== undefined) { + const digests = definitionDigests(doc); + const existingDigest = digests[op.subgraph_id] ?? sha256Hex(canonicalJson(projectDefinition(existing, catalog))); + if (existingDigest === digest) return "no-op"; + if (digest > existingDigest) { + assertDefinitionIdsAvailable(doc, op.subgraph_definition, op.subgraph_id); + let replacement: Y.Map; + try { + replacement = mintDefinition(op.subgraph_definition, catalog); + } catch (error) { + throw new OpRejectedError("malformed_op", `define_subgraph(${op.subgraph_id}): ${error instanceof Error ? error.message : String(error)}`); + } + const widgetEdits = definitionWidgetEdits(doc, existing); + mset(definitions, op.subgraph_id, replacement); + restoreDefinitionWidgetEdits(doc, replacement, widgetEdits); + setDefinitionDigest(doc, op.subgraph_id, digest); + return "applied"; + } + return "no-op"; + } + const existingNested = resolveDefinition(doc, op.subgraph_id); + if (existingNested !== null) { + throw new OpRejectedError( + "definition_conflict", + `define_subgraph: definition id '${op.subgraph_id}' is already registered`, + ); + } + assertDefinitionIdsAvailable(doc, op.subgraph_definition); + let definition: Y.Map; + try { + definition = mintDefinition(op.subgraph_definition, catalog); + } catch (error) { + throw new OpRejectedError( + "malformed_op", + `define_subgraph(${op.subgraph_id}): ${error instanceof Error ? error.message : String(error)}`, + ); + } + mset(definitions, op.subgraph_id, definition); + setDefinitionDigest(doc, op.subgraph_id, digest); + return "applied"; +} + +function definitionDigests(doc: Y.Doc): Record { + const value = metaMap(doc).get("__definition_digests"); + if (!isPlainRecord(value)) return {}; + return Object.fromEntries( + Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string"), + ); +} + +function setDefinitionDigest(doc: Y.Doc, id: string, digest: string): void { + mset(metaMap(doc), "__definition_digests", { ...definitionDigests(doc), [id]: digest }); +} + +type DefinitionWidgetEdit = { + targetKey: string; + definitionId: string; + nodeId: string; + widget: string; + value: unknown; +}; + +function definitionWidgetEdits( + doc: Y.Doc, + existing: Y.Map, +): DefinitionWidgetEdit[] { + const edits: DefinitionWidgetEdit[] = []; + for (const targetKey of stampsMap(doc).keys()) { + let target: unknown; + try { + target = JSON.parse(targetKey); + } catch { + continue; + } + if (!Array.isArray(target) || target[0] !== "widget" || !Array.isArray(target[1])) continue; + const path = target[1].map(String); + const widget = target[3]; + if (path.length < 2 || typeof widget !== "string") continue; + const resolved = definitionNodeAtPath(doc, existing, path); + if (!resolved) continue; + const oldWidgets = resolved.node.get("widgets"); + if (oldWidgets instanceof Y.Map && oldWidgets.has(widget)) { + edits.push({ + targetKey, + definitionId: resolved.definitionId, + nodeId: path.at(-1)!, + widget, + value: structuredClone(oldWidgets.get(widget)), + }); + } + } + return edits; +} + +function definitionNodeAtPath( + doc: Y.Doc, + root: Y.Map, + path: string[], +): { definitionId: string; node: Y.Map } | null { + let definitionId = path[0]!; + let node = definitionNode(root, definitionId, path[1]!); + if (!node) { + const instance = nodesMap(doc).get(definitionId); + if (!(instance instanceof Y.Map) || String(instance.get("type")) !== String(root.get("id"))) return null; + definitionId = String(root.get("id")); + node = definitionNode(root, definitionId, path[1]!); + } + if (!node) return null; + for (const nodeId of path.slice(2)) { + definitionId = String(node.get("type")); + node = definitionNode(root, definitionId, nodeId); + if (!node) return null; + } + return { definitionId, node }; +} + +function restoreDefinitionWidgetEdits( + doc: Y.Doc, + replacement: Y.Map, + edits: DefinitionWidgetEdit[], +): void { + for (const edit of edits) { + const newNode = definitionNode(replacement, edit.definitionId, edit.nodeId); + const newWidgets = newNode?.get("widgets"); + if (!(newWidgets instanceof Y.Map)) { + mdel(stampsMap(doc), edit.targetKey); + continue; + } + mset(newWidgets, edit.widget, edit.value); + } +} + +function definitionNode( + root: Y.Map, + definitionId: string, + nodeId: string, +): Y.Map | null { + if (String(root.get("id")) === definitionId) { + const nodes = root.get("nodes"); + const node = nodes instanceof Y.Map ? nodes.get(nodeId) : undefined; + return node instanceof Y.Map ? node : null; + } + const container = root.get("definitions"); + const nested = container instanceof Y.Map ? container.get("subgraphs") : undefined; + if (!(nested instanceof Y.Map)) return null; + for (const child of nested.values()) { + if (child instanceof Y.Map) { + const node = definitionNode(child, definitionId, nodeId); + if (node) return node; + } + } + return null; +} + +function assertDefinitionIdsAvailable( + doc: Y.Doc, + definition: Record, + excludedRootId?: string, +): void { + const submitted = new Set(); + const visit = (candidate: Record, path: string): void => { + const id = String(candidate.id); + if (submitted.has(id)) throw new OpRejectedError("malformed_op", `define_subgraph: duplicate definition id '${id}' at ${path}`); + submitted.add(id); + const nested = candidate.definitions; + if (isPlainRecord(nested) && Array.isArray(nested.subgraphs)) nested.subgraphs.forEach((child, index) => { + if (isPlainRecord(child)) visit(child, `${path}.definitions.subgraphs[${index}]`); + }); + }; + visit(definition, "subgraph_definition"); + for (const id of submitted) { + if (definitionIdExistsOutsideRoot(doc, id, excludedRootId)) { + throw new OpRejectedError("definition_conflict", `define_subgraph: definition id '${id}' is already registered`); + } + } +} + +function definitionIdExistsOutsideRoot( + doc: Y.Doc, + id: string, + excludedRootId?: string, +): boolean { + const containsId = (definition: Y.Map): boolean => { + if (String(definition.get("id")) === id) return true; + const container = definition.get("definitions"); + const nested = container instanceof Y.Map ? container.get("subgraphs") : undefined; + if (!(nested instanceof Y.Map)) return false; + for (const child of nested.values()) { + if (child instanceof Y.Map && containsId(child)) return true; + } + return false; + }; + + for (const [rootId, definition] of definitionsMap(doc)) { + if (rootId !== excludedRootId && definition instanceof Y.Map && containsId(definition)) return true; + } + return false; +} + +function isUuid(value: unknown): value is string { + return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value); +} + +function isPlainRecord(value: unknown): value is Record { + if (typeof value !== "object" || value === null || Array.isArray(value)) return false; + const prototype = Object.getPrototypeOf(value); + return prototype === Object.prototype || prototype === null; +} + +function validateSubgraphDefinition(definition: Record, path: string): void { + if (!isUuid(definition.id) || !Array.isArray(definition.nodes) || !Array.isArray(definition.links)) { + throw new OpRejectedError("malformed_op", `define_subgraph: ${path} needs a UUID id plus nodes and links arrays`); + } + for (const key of ["node_order", "link_order", "__definition_digest"]) { + if (Object.hasOwn(definition, key)) { + throw new OpRejectedError("malformed_op", `define_subgraph: ${path} contains reserved key '${key}'`); + } + } + assertUniqueNormalizedIds(definition.nodes, `${path}.nodes`, true); + assertUniqueNormalizedIds(definition.links, `${path}.links`); + validateSerializableValue(definition, path); + + const nested = definition.definitions; + if (nested === undefined) return; + if (!isPlainRecord(nested) || !Array.isArray(nested.subgraphs)) { + throw new OpRejectedError("malformed_op", `define_subgraph: ${path}.definitions.subgraphs must be an array`); + } + const nestedIds = new Set(); + nested.subgraphs.forEach((candidate, index) => { + const nestedPath = `${path}.definitions.subgraphs[${index}]`; + if (!isPlainRecord(candidate) || !isUuid(candidate.id)) { + throw new OpRejectedError("malformed_op", `define_subgraph: ${nestedPath} must be a definition with a UUID id`); + } + if (nestedIds.has(candidate.id)) { + throw new OpRejectedError("malformed_op", `define_subgraph: duplicate definition id '${candidate.id}' at ${nestedPath}`); + } + nestedIds.add(candidate.id); + validateSubgraphDefinition(candidate, nestedPath); + }); +} + +function assertUniqueNormalizedIds(values: unknown[], path: string, required = false): void { + const ids = new Set(); + values.forEach((value, index) => { + const id = Array.isArray(value) ? value[0] : isPlainRecord(value) ? value.id : undefined; + if (id === undefined || id === null) { + if (required) throw new OpRejectedError("malformed_op", `define_subgraph: missing id at ${path}[${index}]`); + return; + } + const normalized = String(id); + if (ids.has(normalized)) { + throw new OpRejectedError("malformed_op", `define_subgraph: duplicate normalized id '${normalized}' at ${path}[${index}]`); + } + ids.add(normalized); + }); +} + +function validateDefinitionWidgets(definition: Record, catalog: WidgetCatalog): void { + (definition.nodes as unknown[]).forEach((candidate) => { + if (!isPlainRecord(candidate)) { + throw new OpRejectedError("malformed_op", "define_subgraph: every interior node must be an object"); + } + rejectUnprojectableWidgets(candidate.type, candidate.widgets_values, catalogEntry(catalog, candidate.type)); + }); + const nested = definition.definitions; + if (isPlainRecord(nested) && Array.isArray(nested.subgraphs)) { + nested.subgraphs.forEach((child) => { + if (isPlainRecord(child)) validateDefinitionWidgets(child, catalog); + }); + } +} + +function validateSerializableValue(value: unknown, path: string): void { + if (value === null || typeof value === "string" || typeof value === "boolean") return; + if (typeof value === "number" && Number.isFinite(value)) return; + if (Array.isArray(value)) { + value.forEach((child, index) => validateSerializableValue(child, `${path}[${index}]`)); + return; + } + if (isPlainRecord(value)) { + Object.entries(value).forEach(([key, child]) => validateSerializableValue(child, `${path}.${key}`)); + return; + } + throw new OpRejectedError("malformed_op", `define_subgraph: ${path} is not JSON-serializable`); +} + // --------------------------------------------------------------------------- // add_node // --------------------------------------------------------------------------- @@ -899,8 +1220,9 @@ function applyPromotedHostWrite( key: StampKey, catalog?: WidgetCatalog, ): SuccessfulOutcome { - const target = resolveInteriorNode(doc, promoted.instancePath, catalog); - if (target === null) return "no-op"; // head instance concurrently deleted → no-op (delete wins) + const resolution = resolveInteriorNode(doc, promoted.instancePath, catalog); + if (resolution === null) return "no-op"; // head instance concurrently deleted → no-op (delete wins) + const target = resolution.node; const storage = hostWriteStorage(target, catalog); switch (storage) { case "named": @@ -951,12 +1273,23 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S throw new OpRejectedError("malformed_op", "set_widget: a promoted host write carries no interior path"); } + // Interior paths have several legal spellings (definition id and instance + // id), but all of them can resolve to the same node. Resolve first + // so that node owns one register rather than letting each raw alias claim a + // separate stamp key. `writeTarget` remains the public op-only identity. + const interiorResolution = interior === null + ? null + : resolveInteriorNode(doc, interior.path.map(String), catalog); + if (interior !== null && interiorResolution === null) return "no-op"; + // LWW gate next (comfy-cli `_apply_set_widget`): a lower-or-equal stamp is // dropped — a protocol-level apply that still consumes its op_id. It is no // longer literally FIRST: the op-only checks above it must precede it so // their verdict cannot depend on which stamp is in the document (A6). const stamps = stampsMap(doc); - const targetKey = stampTargetKey(op); + const targetKey = interiorResolution === null + ? stampTargetKey(op) + : JSON.stringify(["widget", interiorResolution.canonicalPath, op.node_incarnation ?? LEGACY_NODE_INCARNATION, interior!.inner_widget]); const prior = stamps.get(targetKey) as StampKey | undefined; const key = stampKey(op); if (prior != null && compareStampKeys(key, prior) <= 0) return "lww-dropped"; @@ -966,8 +1299,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S } if (interior !== null) { - const target = resolveInteriorNode(doc, interior.path.map(String), catalog); - if (target === null) return "no-op"; // head instance concurrently deleted → no-op (delete wins) + const target = interiorResolution!.node; if (nodeIncarnation(target) !== (op.node_incarnation ?? LEGACY_NODE_INCARNATION)) return "no-op"; const nodeType = String(target.get("type") ?? ""); const widget = interior.inner_widget; @@ -1032,11 +1364,53 @@ function projectedWidgetsLength(node: Y.Map, order: readonly string[]): * not forked: schema §5.3 pins that a conforming applier must reject interior * writes to shared definitions until forking is specced and fixtured. */ -function resolveInteriorNode(doc: Y.Doc, path: string[], catalog?: WidgetCatalog): Y.Map | null { +interface InteriorResolution { + node: Y.Map; + canonicalPath: string[]; +} + +function resolveInteriorNode(doc: Y.Doc, path: string[], catalog?: WidgetCatalog): InteriorResolution | null { const head = nodesMap(doc).get(path[0]!); - if (!head) return null; + if (!head) { + const definition = resolveDefinition(doc, path[0]!); + if (!definition || String(definition.get("id")) !== path[0]) return null; + const definitionId = String(definition.get("id")); + const instances = countDefinitionInstances(doc, definitionId, catalog); + if (instances > 1) { + throw new OpRejectedError( + "shared_definition_unforked", + `definition ${definitionId} is instantiated ${instances} times; interior writes to shared definitions are rejected until forking is specced (schema §5.3)`, + ); + } + const innerNodes = definition.get("nodes"); + const inner = innerNodes instanceof Y.Map ? innerNodes.get(path[1]!) : undefined; + if (!(inner instanceof Y.Map)) { + throw new OpRejectedError( + "interior_node_not_found", + `interior node ${path[1]} not found in subgraph ${path[0]}`, + ); + } + const canonicalPath = [definitionId, path[1]!]; + if (path.length === 2) return { node: inner, canonicalPath }; + return resolveInteriorDescendants(doc, inner, path.slice(2), canonicalPath, catalog); + } + const definition = resolveDefinition(doc, String(head.get("type") ?? "")); + const canonicalPath = definition === null + ? [path[0]!] + : [String(definition.get("id") ?? head.get("type"))]; + if (path.length === 1) return { node: head, canonicalPath }; + return resolveInteriorDescendants(doc, head, path.slice(1), canonicalPath, catalog); +} + +function resolveInteriorDescendants( + doc: Y.Doc, + head: Y.Map, + path: string[], + canonicalPath: string[], + catalog?: WidgetCatalog, +): InteriorResolution { let cur: Y.Map = head; - for (const seg of path.slice(1)) { + for (const seg of path) { const curType = String(cur.get("type") ?? ""); const def = resolveDefinition(doc, curType); if (!def) { @@ -1062,8 +1436,12 @@ function resolveInteriorNode(doc: Y.Doc, path: string[], catalog?: WidgetCatalog ); } cur = inner; + // Identity is the final owning definition and node, not the route used to + // reach it. This aliases [outerDef, nestedInstance, leaf] with + // [innerDef, leaf] while keeping equal leaf IDs in other definitions apart. + canonicalPath.splice(0, canonicalPath.length, defId, seg); } - return cur; + return { node: cur, canonicalPath }; } // --------------------------------------------------------------------------- diff --git a/src/collab-trace.ts b/src/collab-trace.ts index 2189a995..b4802837 100644 --- a/src/collab-trace.ts +++ b/src/collab-trace.ts @@ -414,6 +414,9 @@ function assertOpPayload(value: unknown, context: string) { assertNodeIdArray(required(payload, "removed_links", context), `${context}.removed_links`); } else if (op === "clear") { assertNodeIdArray(required(payload, "removed_nodes", context), `${context}.removed_nodes`); + } else if (op === "define_subgraph") { + asString(required(payload, "subgraph_id", context), `${context}.subgraph_id`); + asRecord(required(payload, "subgraph_definition", context), `${context}.subgraph_definition`); } else { // Exhaustiveness guard (issue #21), matching `dispatch` in `applier.ts`: // `op` is narrowed from `FROZEN_OPS`, so with every kind enumerated above diff --git a/src/doc.ts b/src/doc.ts index ca1d6eb4..d6612d8e 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -805,11 +805,21 @@ export function createNodeMap(node: WorkflowNode, widgetOrder?: readonly string[ */ export function resolveDefinition(doc: Y.Doc, key: string): Y.Map | null { const defs = definitionsMap(doc); - const byId = defs.get(key); + const all: Y.Map[] = []; + const visit = (definition: Y.Map): void => { + all.push(definition); + const container = definition.get("definitions"); + const nested = container instanceof Y.Map ? container.get("subgraphs") : undefined; + if (nested instanceof Y.Map) nested.forEach((child) => { + if (child instanceof Y.Map) visit(child); + }); + }; + defs.forEach(visit); + const byId = all.find((definition) => String(definition.get("id")) === key); if (byId) return byId; let found: Y.Map | null = null; let count = 0; - defs.forEach((dm) => { + all.forEach((dm) => { if (String(dm.get("name") ?? "") === key) { count++; found = dm; @@ -893,6 +903,21 @@ function definitionAliases(doc: Y.Doc, defId: string, catalog?: WidgetCatalog): export function countDefinitionInstances(doc: Y.Doc, defId: string, catalog?: WidgetCatalog): number { const aliases = definitionAliases(doc, defId, catalog); let count = 0; + const visitDefinition = (definition: Y.Map): void => { + const inner = definition.get("nodes"); + if (inner instanceof Y.Map) { + inner.forEach((node: unknown) => { + if (node instanceof Y.Map && aliases.has(String(node.get("type") ?? ""))) count++; + }); + } + const container = definition.get("definitions"); + const nested = container instanceof Y.Map ? container.get("subgraphs") : undefined; + if (nested instanceof Y.Map) { + nested.forEach((child: unknown) => { + if (child instanceof Y.Map) visitDefinition(child); + }); + } + }; nodesMap(doc).forEach((node, key) => { if (!(node instanceof Y.Map)) { throw new TypeError( @@ -902,12 +927,7 @@ export function countDefinitionInstances(doc: Y.Doc, defId: string, catalog?: Wi if (aliases.has(String(node.get("type") ?? ""))) count++; }); definitionsMap(doc).forEach((dm) => { - const inner = dm.get("nodes"); - if (inner instanceof Y.Map) { - inner.forEach((node: unknown) => { - if (node instanceof Y.Map && aliases.has(String(node.get("type") ?? ""))) count++; - }); - } + visitDefinition(dm); }); return count; } diff --git a/src/mint.ts b/src/mint.ts index b5cb95e0..4f69a8d8 100644 --- a/src/mint.ts +++ b/src/mint.ts @@ -138,14 +138,19 @@ function definitionLinkKey(ln: unknown, index: number): string { return `#${String(index)}`; } -function mintDefinition(sg: SubgraphDef, catalog: WidgetCatalog): Y.Map { +export function mintDefinition(sg: SubgraphDef, catalog: WidgetCatalog): Y.Map { + for (const key of ["node_order", "link_order", "__definition_digest"]) { + if (Object.hasOwn(sg, key)) throw new TypeError(`mint: definition key '${key}' is reserved`); + } const dm = new Y.Map(); for (const [k, v] of Object.entries(sg)) { if (k === "nodes" && Array.isArray(v)) { const nm = new Y.Map>(); const order: string[] = []; for (const n of v as WorkflowNode[]) { + if (n.id === undefined || n.id === null) throw new TypeError("mint: definition node is missing id"); const key = String(n.id); + if (order.includes(key)) throw new TypeError(`mint: duplicate definition node id '${key}'`); order.push(key); nm.set(key, createNodeMap(n, widgetOrderFor(catalog, n.type))); } @@ -167,6 +172,24 @@ function mintDefinition(sg: SubgraphDef, catalog: WidgetCatalog): Y.Map }); dm.set("links", lm); dm.set("link_order", order); + } else if (k === "definitions" && typeof v === "object" && v !== null && !Array.isArray(v)) { + const container = new Y.Map(); + const { subgraphs, ...extra } = v as { subgraphs?: unknown; [key: string]: unknown }; + Object.entries(extra).forEach(([key, value]) => container.set(key, cloneForMap(value, `mint: definition.definitions.${key}`))); + if (Array.isArray(subgraphs)) { + const nested = new Y.Map>(); + const order: string[] = []; + for (const child of subgraphs as SubgraphDef[]) { + if (child.id === undefined || child.id === null) throw new TypeError("mint: nested definition is missing id"); + const key = String(child.id); + if (order.includes(key)) throw new TypeError(`mint: duplicate nested definition id '${key}'`); + order.push(key); + nested.set(key, mintDefinition(child, catalog)); + } + container.set("subgraphs", nested); + container.set("subgraph_order", order); + } + dm.set("definitions", container); } else { dm.set(k, cloneForMap(v, `mint: definition.${k}`)); } diff --git a/src/project.ts b/src/project.ts index 1052926b..d0c3c983 100644 --- a/src/project.ts +++ b/src/project.ts @@ -214,10 +214,10 @@ function tryProjectNode(value: unknown, catalog: WidgetCatalog): WorkflowNode | } /** Definition Y.Map → subgraph definition JSON, interior nodes/links in mint order. */ -function projectDefinition(dm: Y.Map, catalog: WidgetCatalog): Record { +export function projectDefinition(dm: Y.Map, catalog: WidgetCatalog): Record { const out: Record = Object.create(null) as Record; dm.forEach((v, k) => { - if (k === "node_order" || k === "link_order") return; // internal order registers + if (k === "node_order" || k === "link_order" || k.startsWith("__")) return; // internal registers if (k === "nodes" && v instanceof Y.Map) { const order = (dm.get("node_order") as string[] | undefined) ?? [...v.keys()].sort(); out[k] = order @@ -227,10 +227,36 @@ function projectDefinition(dm: Y.Map, catalog: WidgetCatalog): Record v.has(id)).map((id) => structuredClone(v.get(id))); + } else if (k === "definitions" && v instanceof Y.Map) { + const nestedOut: Record = Object.create(null) as Record; + v.forEach((nestedValue, nestedKey) => { + if (nestedKey === "subgraph_order") return; + if (nestedKey === "subgraphs" && nestedValue instanceof Y.Map) { + const order = (v.get("subgraph_order") as string[] | undefined) ?? [...nestedValue.keys()].sort(); + nestedOut.subgraphs = order + .filter((id) => nestedValue.has(id)) + .map((id) => nestedValue.get(id)) + .filter((definition): definition is Y.Map => definition instanceof Y.Map) + .map((definition) => projectDefinition(definition, catalog)); + } else { + nestedOut[nestedKey] = structuredClone(nestedValue); + } + }); + out[k] = nestedOut; } else { out[k] = structuredClone(v); } }); + return scrubPrivateKeys(out) as Record; +} + +function scrubPrivateKeys(value: unknown): unknown { + if (Array.isArray(value)) return value.map(scrubPrivateKeys); + if (typeof value !== "object" || value === null) return value; + const out: Record = Object.create(null) as Record; + for (const [key, child] of Object.entries(value)) { + if (!key.startsWith("__")) out[key] = scrubPrivateKeys(child); + } return out; } diff --git a/src/stamps.ts b/src/stamps.ts index f3064cf1..1e661057 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -119,6 +119,8 @@ export function writeTarget(op: WireOp): unknown[] { // made the arm look like a catch-all for future kinds as well; they are // now named, and the arm below is a guard rather than a fallback. return [op.op]; + case "define_subgraph": + return ["definition", op.subgraph_id]; default: // Exhaustiveness guard (issue #21): with every `WireOp` member cased // above — the five `Op` kinds plus the deferred `reset_doc` — `op` is diff --git a/src/types.ts b/src/types.ts index 4ac9e737..45538f0a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -33,7 +33,7 @@ export const LEGACY_NODE_INCARNATION = "0"; // --------------------------------------------------------------------------- /** The implemented op kinds. `apply` rejects anything else loudly. */ -export const FROZEN_OPS = ["add_node", "connect", "disconnect", "set_widget", "delete_node", "clear"] as const; +export const FROZEN_OPS = ["add_node", "connect", "disconnect", "set_widget", "delete_node", "clear", "define_subgraph"] as const; /** Defined by the vocabulary but deferred (§1.6): rejected until un-deferred by amendment. */ export const DEFERRED_OPS = ["reset_doc"] as const; @@ -60,7 +60,7 @@ export const DEFERRED_OPS = ["reset_doc"] as const; * belongs. `test/batch-policy.test.ts` pins the list, the README table, and * the deliberate non-enforcement together. */ -export const BATCHABLE_OPS = ["add_node", "connect", "disconnect", "set_widget", "delete_node"] as const; +export const BATCHABLE_OPS = ["add_node", "connect", "disconnect", "set_widget", "delete_node", "define_subgraph"] as const; /** Every kind the vocabulary defines — implemented ({@link Op}) plus deferred ({@link DeferredOp}). */ export type OpKind = WireOp["op"]; @@ -394,6 +394,12 @@ export interface ClearOp extends OpBase { removed_nodes: NodeId[]; } +export interface DefineSubgraphOp extends OpBase { + op: "define_subgraph"; + subgraph_id: string; + subgraph_definition: SubgraphDefinition; +} + /** * Replace the entire document with a workflow snapshot. * @@ -427,7 +433,8 @@ export type Op = | DisconnectOp | SetWidgetOp | DeleteNodeOp - | ClearOp; + | ClearOp + | DefineSubgraphOp; /** * A kind the vocabulary declares but this package refuses to apply @@ -548,6 +555,12 @@ export interface WorkflowJSON { [key: string]: unknown; } +export interface SubgraphDefinition extends Record { + id: string; + nodes: unknown[]; + links: unknown[]; +} + // --------------------------------------------------------------------------- // Apply result // --------------------------------------------------------------------------- diff --git a/test/convergence.test.ts b/test/convergence.test.ts index 1a17d4ee..56852a7c 100644 --- a/test/convergence.test.ts +++ b/test/convergence.test.ts @@ -56,6 +56,7 @@ function touchedNodes(op: WireOp): string[] { case "clear": case "delete_node": case "reset_doc": + case "define_subgraph": // Graph-wide / unbounded ops. `reorderableWindows` treats them as window // breakers and never calls this helper for them; listed explicitly so // the guard below is a guard and not a catch-all (#21). diff --git a/test/define-subgraph.test.ts b/test/define-subgraph.test.ts new file mode 100644 index 00000000..0235219d --- /dev/null +++ b/test/define-subgraph.test.ts @@ -0,0 +1,713 @@ +import * as Y from "yjs" +import { createHash } from "node:crypto" +import { describe, expect, it } from "vitest" + +import { + applyOps, + mint, + project, + type DefineSubgraphOp, + type Op, + type SubgraphDefinition, + type WidgetCatalog, + type WorkflowJSON, +} from "../src/index.js" +import { definitionsMap, metaMap, stampsMap } from "../src/doc.js" +import { stampKey } from "../src/stamps.js" + +const catalog: WidgetCatalog = { + types: { + Inner: { widget_order: ["value"] }, + Other: { widget_order: [] }, + }, +} + +let sequence = 0 +const envelope = () => { + const op_id = String(++sequence).padStart(32, "0") + return { op_id, actor: "agent:test", base_version: sequence, stamp: [sequence, "agent:test"] as [number, string] } +} + +const subgraphId = "12345678-1234-4123-8123-123456789abc" +const definition = (id = subgraphId, value = 1) => ({ + id, + name: "One", + inputs: [], + outputs: [], + nodes: [{ id: 10, type: "Inner", inputs: [], outputs: [], widgets_values: [value] }], + links: [], +}) + +const define = (id = subgraphId, value = 1): DefineSubgraphOp => ({ + op: "define_subgraph", + ...envelope(), + subgraph_id: id, + subgraph_definition: definition(id, value), +}) + +const empty = () => mint({ nodes: [], links: [] } as unknown as WorkflowJSON, catalog) +const rejectionCode = (doc: Y.Doc, op: Op) => + applyOps(doc, [op], catalog).outcomes.find((outcome) => outcome.outcome === "rejected")?.reason.code + +const winningReplacement = (incumbent: SubgraphDefinition, replacement: SubgraphDefinition) => { + const canonical = (value: unknown): string => JSON.stringify(value, (_key, child: unknown) => + child && typeof child === "object" && !Array.isArray(child) + ? Object.fromEntries(Object.entries(child).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) + : child) + const digest = (value: unknown) => createHash("sha256").update(canonical(value)).digest("hex") + const incumbentDigest = digest(incumbent) + for (let nonce = 0; nonce < 1000; nonce++) { + const candidate: SubgraphDefinition = { ...replacement, name: `replacement-${nonce}` } + if (digest(candidate) > incumbentDigest) return candidate + } + throw new Error("independent test oracle could not construct a winning replacement") +} + +describe("define_subgraph schema", () => { + const forbidden = [ + ["add_node with subgraph_definition", { op: "add_node", node_id: 1, class_type: "Inner", pos: [0, 0], node: { id: 1, type: "Inner" }, subgraph_definition: definition() }], + ["add_node with definitions", { op: "add_node", node_id: 1, class_type: "Inner", pos: [0, 0], node: { id: 1, type: "Inner" }, definitions: { subgraphs: [] } }], + ["node-property op with definition payload", { op: "set_widget", node_id: 1, widget: "value", value: 2, subgraph_definition: definition() }], + ["widget op with definitions payload", { op: "set_widget", node_id: 1, widget: "value", value: 2, definitions: {} }], + ["connect with definition payload", { op: "connect", link_id: 1, from_node: 1, from_slot: 0, to_node: 2, to_slot: 0, link_type: "X", subgraph_definition: definition() }], + ["disconnect with definition payload", { op: "disconnect", link_id: 1, subgraph_definition: definition() }], + ["layout op with definition payload", { op: "add_node", node_id: 1, class_type: "Inner", pos: [0, 0], node: { id: 1, type: "Inner" }, layout: {}, subgraph_definition: definition() }], + ["remove-node with definition payload", { op: "delete_node", node_id: 1, removed_links: [], subgraph_definition: definition() }], + ["subgraph_id cannot substitute for a node target", { op: "set_widget", subgraph_id: subgraphId, widget: "value", value: 2 }], + ] as const + + it.each(forbidden)("rejects %s", (_name, fields) => { + const op = { ...fields, ...envelope() } as unknown as Op + expect(rejectionCode(empty(), op)).toBeDefined() + }) +}) + +describe("define_subgraph application", () => { + it("matches the independently derived fixed definition digest and winner vector", () => { + const seed = Y.encodeStateAsUpdate(empty()) + const winner = define(subgraphId, 1) + const loser = define(subgraphId, 2) + // Derived with Python 3 json.dumps(sort_keys=True,separators=(',',':')) + // and hashlib.sha256, not the production canonicalizer or digest helper. + // value=2 hashes to 1872feea7ddb573ff68e47b7be0c5b369863cfa2262f6d23d18ae15ecadb9e62. + for (const ops of [[winner, loser], [loser, winner]]) { + const doc = new Y.Doc() + Y.applyUpdate(doc, seed) + applyOps(doc, ops, catalog) + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([definition()]) + expect((metaMap(doc).get("__definition_digests") as Record)[subgraphId]).toBe( + "3a0b0a3e10f67853f62d5b56ed2d505449cccd161cca63bfcbd3187d32523eb3", + ) + } + }) + it("projects a newly defined subgraph", () => { + const doc = empty() + expect(applyOps(doc, [define()], catalog).outcomes[0]?.outcome).toBe("applied") + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([definition()]) + }) + + it("is byte-idempotent on exact replay", () => { + const doc = empty() + const op = define() + applyOps(doc, [op], catalog) + const before = Y.encodeStateAsUpdate(doc) + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("no-op") + expect(Y.encodeStateAsUpdate(doc)).toEqual(before) + }) + + it("does not revert an intervening interior edit when the definition is replayed with a new envelope", () => { + const doc = empty() + const op = define() + applyOps(doc, [op], catalog) + applyOps(doc, [ + { op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 2 }, + ], catalog) + const before = Y.encodeStateAsUpdate(doc) + + expect(applyOps(doc, [{ ...op, ...envelope() }], catalog).outcomes[0]?.outcome).toBe("no-op") + expect(Y.encodeStateAsUpdate(doc)).not.toEqual(before) // the new op_id is consumed + const projected = (project(doc, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]! + expect(projected.nodes[0]!.widgets_values).toEqual([2]) + }) + + it("replays an identical definition imported without a private digest and continues the batch", () => { + const imported = { + nodes: [], + links: [], + definitions: { subgraphs: [definition()] }, + } as unknown as WorkflowJSON + const doc = mint(imported, catalog) + const storedDefinition = definitionsMap(doc).get(subgraphId)! + const storedWidgets = (storedDefinition.get("nodes") as Y.Map>).get("10")!.get("widgets") + const before = project(doc, catalog) + const replay = define() + const suffix = { + op: "add_node", ...envelope(), node_id: 99, class_type: "Other", pos: [0, 0], + node: { id: 99, type: "Other", inputs: [], outputs: [] }, + } as Op + + expect(storedDefinition.get("__definition_digest")).toBeUndefined() + expect(metaMap(doc).get("__definition_digests")).toBeUndefined() + expect(applyOps(doc, [replay, suffix], catalog).outcomes).toEqual([ + { op_id: replay.op_id, outcome: "no-op" }, + { op_id: suffix.op_id, outcome: "applied" }, + ]) + expect(definitionsMap(doc).get(subgraphId)).toBe(storedDefinition) + expect((storedDefinition.get("nodes") as Y.Map>).get("10")!.get("widgets")).toBe(storedWidgets) + expect((project(doc, catalog).definitions as unknown)).toEqual(before.definitions) + expect(project(doc, catalog).nodes.map((node) => node.id)).toContain(99) + }) + + it("treats instance-ID and definition-ID widget paths as one LWW register", () => { + const seeded = mint({ + nodes: [{ id: 1, type: subgraphId, inputs: [], outputs: [] }], + links: [], + definitions: { subgraphs: [definition()] }, + } as unknown as WorkflowJSON, catalog) + const snapshot = Y.encodeStateAsUpdate(seeded) + const lower = { + op: "set_widget", op_id: "10000000000000000000000000000000", actor: "agent:low", + base_version: 10, stamp: [10, "agent:low"], node_id: 10, + path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: "lower-definition-path", + } as Op + const higher = { + op: "set_widget", op_id: "20000000000000000000000000000000", actor: "agent:high", + base_version: 20, stamp: [20, "agent:high"], node_id: 10, + path: ["1", "10"], inner_widget: "value", widget: "value", value: "higher-instance-path", + } as Op + + const results = [[lower, higher], [higher, lower]].map((ops) => { + const doc = new Y.Doc() + Y.applyUpdate(doc, snapshot) + const outcomes = ops.flatMap((op) => applyOps(doc, [op], catalog).outcomes) + expect(outcomes).toHaveLength(2) + expect(outcomes.every(({ outcome }) => outcome === "applied" || outcome === "lww-dropped")).toBe(true) + const projected = (project(doc, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]! + const beforeReplay = Y.encodeStateAsUpdate(doc) + expect(ops.map((op) => applyOps(doc, [op], catalog).outcomes[0]?.outcome)).toEqual(["no-op", "no-op"]) + expect(Y.encodeStateAsUpdate(doc)).toEqual(beforeReplay) + return { value: projected.nodes[0]!.widgets_values, stamps: [...stampsMap(doc).values()] } + }) + + expect(results.map(({ value }) => value)).toEqual([ + ["higher-instance-path"], + ["higher-instance-path"], + ]) + expect(results.map(({ stamps }) => stamps)).toEqual([[stampKey(higher)], [stampKey(higher)]]) + }) + + it("uses the final owning definition and node as nested alias identity without conflating equal leaf IDs", () => { + const innerId = "22345678-1234-4123-8123-123456789abc" + const nestedWorkflow = { + nodes: [{ id: 1, type: subgraphId, inputs: [], outputs: [] }], + links: [], + definitions: { subgraphs: [ + { + id: subgraphId, name: "Outer", inputs: [], outputs: [], links: [], + nodes: [ + { id: 10, type: "Inner", inputs: [], outputs: [], widgets_values: ["outer-leaf"] }, + { id: 20, type: innerId, inputs: [], outputs: [] }, + ], + }, + { + id: innerId, name: "Nested", inputs: [], outputs: [], links: [], + nodes: [{ id: 10, type: "Inner", inputs: [], outputs: [], widgets_values: ["nested-leaf"] }], + }, + ] }, + } as unknown as WorkflowJSON + const snapshot = Y.encodeStateAsUpdate(mint(nestedWorkflow, catalog)) + const lower = { + op: "set_widget", op_id: "30000000000000000000000000000000", actor: "agent:low", + base_version: 30, stamp: [30, "agent:low"], node_id: 10, + path: [subgraphId, "20", "10"], inner_widget: "value", widget: "value", value: "lower-outer-history", + } as Op + const higher = { + op: "set_widget", op_id: "40000000000000000000000000000000", actor: "agent:high", + base_version: 40, stamp: [40, "agent:high"], node_id: 10, + path: [innerId, "10"], inner_widget: "value", widget: "value", value: "higher-final-owner", + } as Op + + for (const ops of [[lower, higher], [higher, lower]]) { + const doc = new Y.Doc() + Y.applyUpdate(doc, snapshot) + const outcomes = ops.map((op) => applyOps(doc, [op], catalog).outcomes[0]?.outcome) + expect(outcomes.every((outcome) => outcome === "applied" || outcome === "lww-dropped")).toBe(true) + const definitions = (project(doc, catalog).definitions as { + subgraphs: Array<{ id: string; nodes: Array<{ id: unknown; widgets_values?: unknown[] }> }> + }).subgraphs + const inner = definitions.find(({ id }) => id === innerId)! + const outer = definitions.find(({ id }) => id === subgraphId)! + expect(inner.nodes.find(({ id }) => id === 10)!.widgets_values).toEqual(["higher-final-owner"]) + expect(outer.nodes.find(({ id }) => id === 10)!.widgets_values).toEqual(["outer-leaf"]) + expect([...stampsMap(doc).values()]).toEqual([stampKey(higher)]) + } + + const isolated = new Y.Doc() + Y.applyUpdate(isolated, snapshot) + const outerLeaf = { + ...lower, op_id: "50000000000000000000000000000000", base_version: 50, + stamp: [50, "agent:low"], path: [subgraphId, "10"], value: "changed-outer-leaf", + } as Op + expect(applyOps(isolated, [higher, outerLeaf], catalog).outcomes.map(({ outcome }) => outcome)).toEqual(["applied", "applied"]) + expect(stampsMap(isolated).size).toBe(2) + }) + + it("converges when a definition replay and an interior edit arrive in either legal order", () => { + const seed = empty() + const original = define() + applyOps(seed, [original], catalog) + const snapshot = Y.encodeStateAsUpdate(seed) + const replay = { ...original, ...envelope() } + const edit = { + op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 7, + } as Op + + const projections = [[replay, edit], [edit, replay]].map((ops) => { + const doc = new Y.Doc() + Y.applyUpdate(doc, snapshot) + for (const op of ops) applyOps(doc, [op], catalog) + return project(doc, catalog) + }) + + expect(projections[0]).toEqual(projections[1]) + expect((projections[0]!.definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]!.nodes[0]!.widgets_values).toEqual([7]) + }) + + it("consumes a losing definition conflict without changing the winner", () => { + const doc = empty() + applyOps(doc, [define()], catalog) + expect(applyOps(doc, [define(subgraphId, 2)], catalog).outcomes[0]?.outcome).toBe("no-op") + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([definition()]) + }) + + it("projects the same deterministic winner for conflicting definitions in either delivery order", () => { + const a = define(subgraphId, 1) + const b = define(subgraphId, 2) + const projections = [[a, b], [b, a]].map((ops) => { + const doc = empty() + for (const op of ops) applyOps(doc, [op], catalog) + return project(doc, catalog) + }) + + expect(projections[0]).toEqual(projections[1]) + }) + + it("preserves edits to the deterministic winner and consumes the same conflict in either legal order", () => { + const a = define(subgraphId, 1) + const b = define(subgraphId, 2) + const edit = { + op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 9, + } as Op + + const results = [[a, edit, b], [b, edit, a]].map((ops) => { + const doc = empty() + const outcomes = ops.map((op) => applyOps(doc, [op], catalog).outcomes[0]) + return { outcomes, projection: project(doc, catalog) } + }) + + expect(results[0]!.projection).toEqual(results[1]!.projection) + expect(results[0]!.outcomes.find((outcome) => outcome?.outcome === "no-op")?.op_id).toBe(b.op_id) + const projected = (results[0]!.projection.definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]! + expect(projected.nodes[0]!.widgets_values).toEqual([9]) + }) + + it("preserves nested widget edits across a digest-winning replacement in either legal order", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const incumbent = { + ...definition(), + nodes: [{ id: 20, type: nestedId, inputs: [], outputs: [], widgets_values: [] }], + definitions: { subgraphs: [definition(nestedId, 1)] }, + } + const replacement = winningReplacement(incumbent, { + ...incumbent, + definitions: { subgraphs: [definition(nestedId, 2)] }, + }) + const first = { ...define(), subgraph_definition: incumbent } + const second = { ...define(), subgraph_definition: replacement } + const edit = { + op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "20", "10"], inner_widget: "value", widget: "value", value: 80, + } as Op + + const projections = [[first, edit, second], [second, edit, first]].map((ops) => { + const doc = empty() + for (const op of ops) applyOps(doc, [op], catalog) + return project(doc, catalog) + }) + + expect(projections[0]).toEqual(projections[1]) + const projected = (projections[0]!.definitions as { subgraphs: Array<{ definitions: { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> } }> }).subgraphs[0]! + expect(projected.definitions.subgraphs[0]!.nodes[0]!.widgets_values).toEqual([80]) + }) + + it("restores an instance-ID-addressed widget edit after a digest-winning replacement", () => { + const incumbent = definition(subgraphId, 1) + const replacement = winningReplacement(incumbent, definition(subgraphId, 2)) + const doc = empty() + applyOps(doc, [{ ...define(), subgraph_definition: incumbent }], catalog) + applyOps(doc, [{ + op: "add_node", ...envelope(), node_id: 1, class_type: subgraphId, pos: [0, 0], + node: { id: 1, type: subgraphId, inputs: [], outputs: [] }, + }], catalog) + applyOps(doc, [{ + op: "set_widget", ...envelope(), node_id: 10, path: ["1", "10"], + inner_widget: "value", widget: "value", value: 9, + }], catalog) + + expect(applyOps(doc, [{ ...define(), subgraph_definition: replacement }], catalog).outcomes[0]?.outcome).toBe("applied") + const projected = (project(doc, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]! + expect(projected.nodes[0]!.widgets_values).toEqual([9]) + }) + + it("rejects an edit to a node that exists only in the replaced definition", () => { + const first = { + ...definition(subgraphId, 2), + nodes: [{ id: 11, type: "Inner", inputs: [], outputs: [], widgets_values: [2] }], + } + const second = { + ...definition(subgraphId, 1), + nodes: [{ id: 12, type: "Inner", inputs: [], outputs: [], widgets_values: [1] }], + } + const doc = empty() + applyOps(doc, [{ ...define(subgraphId, 2), subgraph_definition: first }], catalog) + applyOps(doc, [{ ...define(subgraphId, 1), subgraph_definition: second }], catalog) + const winnerNodes = (project(doc, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ id: number }> }> }).subgraphs[0]!.nodes + const losingNodeId = winnerNodes[0]!.id === 11 ? 12 : 11 + + const outcome = applyOps(doc, [{ + op: "set_widget", ...envelope(), node_id: losingNodeId, path: [subgraphId, String(losingNodeId)], inner_widget: "value", widget: "value", value: 9, + }], catalog).outcomes[0] + + expect(outcome?.outcome).toBe("rejected") + expect(outcome?.outcome === "rejected" ? outcome.reason.code : undefined).toBe("interior_node_not_found") + }) + + it("keeps applying a batch suffix after the deterministic conflict loser", () => { + const a = define(subgraphId, 1) + const b = define(subgraphId, 2) + const suffix = { op: "add_node", ...envelope(), node_id: 99, class_type: "Other", pos: [0, 0], node: { id: 99, type: "Other", inputs: [], outputs: [] } } as Op + const projections = [[a, b], [b, a]].map((ops) => { + const doc = empty() + applyOps(doc, [ops[0]!, ops[1]!, suffix], catalog) + return project(doc, catalog) + }) + expect(projections[0]).toEqual(projections[1]) + expect(projections[0]!.nodes.some((node) => node.id === 99)).toBe(true) + }) + + it.each([ + ["missing nodes", { ...definition(), nodes: undefined }], + ["invalid definition id", definition("not-a-uuid")], + ["duplicate normalized node ids", { ...definition(), nodes: [{ id: 1, type: "Inner" }, { id: "1", type: "Inner" }] }], + ["missing interior node id", { ...definition(), nodes: [{ type: "Inner" }] }], + ["reserved structural key", { ...definition(), node_order: [] }], + ["duplicate normalized nested definition ids", { + ...definition(), + definitions: { + subgraphs: [ + definition("abcdefab-cdef-4abc-8def-abcdefabcdef"), + definition("abcdefab-cdef-4abc-8def-abcdefabcdef"), + ], + }, + }], + ])("rejects %s without creating a partial definition", (_name, malformed) => { + const doc = empty() + const before = Y.encodeStateAsUpdate(doc) + const op = { ...define(), subgraph_id: String(malformed.id), subgraph_definition: malformed } as DefineSubgraphOp + + expect(rejectionCode(doc, op)).toBe("malformed_op") + expect(Y.encodeStateAsUpdate(doc)).toEqual(before) + expect(definitionsMap(doc).size).toBe(0) + }) + + it("projects nested definitions", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const nested = definition(nestedId, 4) + const outer = { ...definition(), definitions: { subgraphs: [nested] } } + const doc = empty() + + expect(applyOps(doc, [{ ...define(), subgraph_definition: outer }], catalog).outcomes[0]?.outcome).toBe("applied") + const projected = (project(doc, catalog).definitions as { subgraphs: Array> }).subgraphs[0]! + expect(projected.definitions).toEqual({ subgraphs: [nested] }) + }) + + it("rejects fresh reuse of an identical nested definition id while exact replay stays idempotent", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const nested = definition(nestedId, 4) + const outer = { ...definition(), definitions: { subgraphs: [nested] } } + const op = { ...define(), subgraph_definition: outer } + const doc = empty() + + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied") + const afterCreate = Y.encodeStateAsUpdate(doc) + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("no-op") + expect(Y.encodeStateAsUpdate(doc)).toEqual(afterCreate) + + const freshReuse = { ...define(nestedId, 4), subgraph_definition: nested } + expect(rejectionCode(doc, freshReuse)).toBe("definition_conflict") + expect(Y.encodeStateAsUpdate(doc)).toEqual(afterCreate) + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([outer]) + }) + + it("applies an id-addressed widget edit to a nested definition", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const outer = { ...definition(), definitions: { subgraphs: [definition(nestedId, 4)] } } + const doc = empty() + applyOps(doc, [{ ...define(), subgraph_definition: outer }], catalog) + + const outcome = applyOps(doc, [{ + op: "set_widget", ...envelope(), node_id: 10, path: [nestedId, "10"], inner_widget: "value", widget: "value", value: 9, + }], catalog).outcomes[0]?.outcome + const projected = (project(doc, catalog).definitions as { subgraphs: Array<{ definitions: { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> } }> }).subgraphs[0]! + + expect(outcome).toBe("applied") + expect(projected.definitions.subgraphs[0]!.nodes[0]!.widgets_values).toEqual([9]) + }) + + it("rejects a new root definition whose id collides with an existing nested definition", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const doc = empty() + applyOps(doc, [{ ...define(), subgraph_definition: { + ...definition(), definitions: { subgraphs: [definition(nestedId, 4)] }, + } }], catalog) + + expect(rejectionCode(doc, define(nestedId, 9))).toBe("definition_conflict") + expect(rejectionCode(doc, define(nestedId, 4))).toBe("definition_conflict") + }) + + it("rejects a nested definition whose id collides with an existing root definition", () => { + const newRootId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const doc = empty() + applyOps(doc, [define()], catalog) + const colliding = { + ...definition(newRootId), definitions: { subgraphs: [definition(subgraphId, 9)] }, + } + + expect(rejectionCode(doc, { ...define(newRootId), subgraph_definition: colliding })).toBe("definition_conflict") + }) + + it("rejects a winning replacement whose nested id collides with another root and preserves the incumbent", () => { + const otherRootId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const incumbent = definition() + const replacement = winningReplacement(incumbent, { + ...definition(), definitions: { subgraphs: [definition(otherRootId, 9)] }, + }) + const doc = empty() + applyOps(doc, [define(), define(otherRootId, 4)], catalog) + + expect(rejectionCode(doc, { ...define(), subgraph_definition: replacement })).toBe("definition_conflict") + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([ + incumbent, + definition(otherRootId, 4), + ]) + }) + + it.each(["ancestor", "sibling"])("rejects a winning replacement whose nested id collides with an %s branch", (collision) => { + const branchId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const siblingId = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + const incumbent = definition() + const otherRootId = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" + const otherRoot = { ...definition(otherRootId), definitions: { subgraphs: [ + { ...definition(branchId, 2), definitions: { subgraphs: [definition(siblingId, 3)] } }, + ] } } + const collidingId = collision === "ancestor" ? branchId : siblingId + const replacement = winningReplacement(incumbent, { + ...definition(), definitions: { subgraphs: [definition(collidingId, 6)] }, + }) + const doc = empty() + applyOps(doc, [ + { ...define(), subgraph_definition: incumbent }, + { ...define(otherRootId), subgraph_definition: otherRoot }, + ], catalog) + + expect(rejectionCode(doc, { ...define(), subgraph_definition: replacement })).toBe("definition_conflict") + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([incumbent, otherRoot]) + }) + + it("accepts a winning replacement that reuses only ids owned by the incumbent", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const incumbent = { ...definition(), definitions: { subgraphs: [definition(nestedId, 2)] } } + const replacement = winningReplacement(incumbent, { + ...definition(), nodes: [{ id: 11, type: "Inner", inputs: [], outputs: [], widgets_values: [7] }], + definitions: { subgraphs: [definition(nestedId, 8)] }, + }) + const doc = empty() + applyOps(doc, [{ ...define(), subgraph_definition: incumbent }], catalog) + + expect(applyOps(doc, [{ ...define(), subgraph_definition: replacement }], catalog).outcomes[0]?.outcome).toBe("applied") + expect((project(doc, catalog).definitions as { subgraphs: unknown[] }).subgraphs).toEqual([replacement]) + }) + + it("projects a rejected colliding winner identically in both op orders", () => { + const otherRootId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const incumbent = definition() + const replacement = winningReplacement(incumbent, { + ...definition(), definitions: { subgraphs: [definition(otherRootId, 9)] }, + }) + const incumbentOp = define() + const replacementOp = { ...define(), subgraph_definition: replacement } + const seed = empty() + applyOps(seed, [define(otherRootId, 4)], catalog) + const snapshot = Y.encodeStateAsUpdate(seed) + + const projections = [[incumbentOp, replacementOp], [replacementOp, incumbentOp]].map((ops) => { + const doc = new Y.Doc() + Y.applyUpdate(doc, snapshot) + for (const op of ops) applyOps(doc, [op], catalog) + return project(doc, catalog) + }) + + expect(projections[0]).toEqual(projections[1]) + const projected = (projections[0]!.definitions as { subgraphs: Array<{ id: string }> }).subgraphs + expect(projected.find(({ id }) => id === subgraphId)).toEqual(incumbent) + expect(projected.find(({ id }) => id === otherRootId)).toEqual(definition(otherRootId, 4)) + }) + + it("rejects a direct edit to a definition with multiple live instances", () => { + const doc = empty() + applyOps(doc, [define()], catalog) + applyOps(doc, [ + { op: "add_node", ...envelope(), node_id: 1, class_type: subgraphId, pos: [0, 0], node: { id: 1, type: subgraphId, inputs: [], outputs: [] } }, + { op: "add_node", ...envelope(), node_id: 2, class_type: subgraphId, pos: [0, 0], node: { id: 2, type: subgraphId, inputs: [], outputs: [] } }, + ], catalog) + expect(rejectionCode(doc, { op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 9 })).toBe("shared_definition_unforked") + }) + + it("rejects an edit when instances occur recursively three definition levels down", () => { + const middleId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const leafId = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + const leaf = definition(leafId, 3) + const middle = { + ...definition(middleId), + nodes: [ + { id: 21, type: leafId, inputs: [], outputs: [], widgets_values: [] }, + { id: 22, type: leafId, inputs: [], outputs: [], widgets_values: [] }, + ], + definitions: { subgraphs: [leaf] }, + } + const outer = { ...definition(), definitions: { subgraphs: [middle] } } + const doc = empty() + applyOps(doc, [{ ...define(), subgraph_definition: outer }], catalog) + const before = Y.encodeStateAsUpdate(doc) + + expect(rejectionCode(doc, { + op: "set_widget", ...envelope(), node_id: 10, path: [leafId, "10"], + inner_widget: "value", widget: "value", value: 9, + })).toBe("shared_definition_unforked") + expect(Y.encodeStateAsUpdate(doc)).toEqual(before) + }) + + it("rejects an unprojectable named widget in an interior node atomically", () => { + const doc = empty() + const malformed = { ...definition(), nodes: [{ id: 10, type: "Inner", inputs: [], outputs: [], widgets_values: { missing: 1 } }] } + const before = Y.encodeStateAsUpdate(doc) + expect(rejectionCode(doc, { ...define(), subgraph_definition: malformed })).toBe("unknown_widget") + expect(Y.encodeStateAsUpdate(doc)).toEqual(before) + }) + + it.each([ + ["ancestor", () => ({ ...definition(), definitions: { subgraphs: [definition(subgraphId)] } })], + ["cross-branch", () => { + const duplicate = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const left = { ...definition("aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"), definitions: { subgraphs: [definition(duplicate)] } } + const right = { ...definition("bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"), definitions: { subgraphs: [definition(duplicate)] } } + return { ...definition(), definitions: { subgraphs: [left, right] } } + }], + ])("rejects a duplicate definition id against an %s atomically", (_name, makeDefinition) => { + const doc = empty() + const before = Y.encodeStateAsUpdate(doc) + expect(rejectionCode(doc, { ...define(), subgraph_definition: makeDefinition() } as DefineSubgraphOp)).toBe("malformed_op") + expect(Y.encodeStateAsUpdate(doc)).toEqual(before) + }) + + it("never projects internal definition digests, including sender-supplied nested keys", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const nested = { ...definition(nestedId), __definition_digest: "sender-value" } + const outer = { ...definition(), definitions: { subgraphs: [nested] } } + const doc = empty() + + expect(rejectionCode(doc, { ...define(), subgraph_definition: outer } as DefineSubgraphOp)).toBe("malformed_op") + applyOps(doc, [{ ...define(), subgraph_definition: { + ...definition(), definitions: { subgraphs: [definition(nestedId)] }, + } }], catalog) + expect(JSON.stringify(project(doc, catalog))).not.toContain("__definition_digest") + }) + + it("never projects arbitrary private definition keys at any depth", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const doc = empty() + const privateDefinition = { + ...definition(), + __other: "root-secret", + definitions: { + subgraphs: [{ ...definition(nestedId), __private_marker: { nested: "secret" } }], + }, + } + + expect(applyOps(doc, [{ ...define(), subgraph_definition: privateDefinition }], catalog).outcomes[0]?.outcome).toBe("applied") + const serialized = JSON.stringify(project(doc, catalog)) + expect(serialized).not.toContain("__other") + expect(serialized).not.toContain("__private_marker") + expect(serialized).not.toContain("secret") + }) + + it("uses the same unknown-node outcome for UUID and non-UUID interior targets", () => { + const outcomes = ["abcdefab-cdef-4abc-8def-abcdefabcdef", "missing"].map((target) => { + const doc = empty() + return applyOps(doc, [{ + op: "set_widget", ...envelope(), node_id: 10, path: [target, "10"], inner_widget: "value", widget: "value", value: 2, + }], catalog).outcomes[0] + }) + + expect(outcomes.map((outcome) => outcome?.outcome)).toEqual(["no-op", "no-op"]) + }) + + it("uses a key-order-independent definition digest", () => { + const doc = empty() + const first = definition() + const reordered = { + links: first.links, + nodes: first.nodes, + outputs: first.outputs, + inputs: first.inputs, + name: first.name, + id: first.id, + } + + expect(applyOps(doc, [{ ...define(), subgraph_definition: first }], catalog).outcomes[0]?.outcome).toBe("applied") + const digest = definitionsMap(doc).get(subgraphId)?.get("__definition_digest") + expect(applyOps(doc, [{ ...define(), subgraph_definition: reordered }], catalog).outcomes[0]?.outcome).toBe("no-op") + expect(definitionsMap(doc).get(subgraphId)?.get("__definition_digest")).toBe(digest) + }) + + it("applies define, interior edit, then instance in one batch", () => { + const doc = empty() + const ops: Op[] = [ + define(), + { op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 2 }, + { op: "add_node", ...envelope(), node_id: 1, class_type: subgraphId, pos: [0, 0], node: { id: 1, type: subgraphId, inputs: [], outputs: [] } }, + ] + expect(applyOps(doc, ops, catalog).outcomes.map((outcome) => outcome.outcome)).toEqual(["applied", "applied", "applied"]) + const subgraph = (project(doc, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]! + expect(subgraph.nodes[0]!.widgets_values).toEqual([2]) + }) + + it("accepts an opaque UUID-shaped node type before its definition arrives", () => { + const doc = empty() + const missing = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const instance = { op: "add_node", ...envelope(), node_id: 1, class_type: missing, pos: [0, 0], node: { id: 1, type: missing, inputs: [], outputs: [] } } as Op + expect(applyOps(doc, [instance], catalog).outcomes[0]?.outcome).toBe("applied") + }) + + it("has root/interior widget-edit parity", () => { + const root = mint({ nodes: [{ id: 10, type: "Inner", inputs: [], outputs: [], widgets_values: [1] }], links: [] } as unknown as WorkflowJSON, catalog) + const nested = empty() + applyOps(nested, [define()], catalog) + const rootOp = { op: "set_widget", ...envelope(), node_id: 10, widget: "value", value: 3 } as Op + const nestedOp = { op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "10"], inner_widget: "value", widget: "value", value: 3 } as Op + expect(applyOps(root, [rootOp], catalog).outcomes[0]?.outcome).toBe("applied") + expect(applyOps(nested, [nestedOp], catalog).outcomes[0]?.outcome).toBe("applied") + expect(project(root, catalog).nodes[0]!.widgets_values).toEqual( + (project(nested, catalog).definitions as { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }).subgraphs[0]!.nodes[0]!.widgets_values, + ) + }) +}) diff --git a/test/ka4-rejection-byte-identity.test.ts b/test/ka4-rejection-byte-identity.test.ts index 309a3bfa..3237fd86 100644 --- a/test/ka4-rejection-byte-identity.test.ts +++ b/test/ka4-rejection-byte-identity.test.ts @@ -592,11 +592,35 @@ function sharedDefinitionCase(): { doc: Y.Doc; op: Op; catalog?: WidgetCatalog; }; } +function definitionConflictCase(): { doc: Y.Doc; op: Op; catalog?: WidgetCatalog; code: string } { + const id = "12345678-1234-4123-8123-123456789abc"; + const nested = "abcdefab-cdef-4abc-8def-abcdefabcdef"; + const doc = mint({ + nodes: [], + links: [], + definitions: { subgraphs: [{ id, name: "outer", nodes: [], links: [], definitions: { + subgraphs: [{ id: nested, name: "nested", nodes: [], links: [] }], + } }] }, + } as unknown as WorkflowJSON, catalog); + return { + doc, + op: { + op: "define_subgraph", + ...env(), + subgraph_id: nested, + subgraph_definition: { id: nested, name: "different", nodes: [], links: [] }, + } as unknown as Op, + catalog, + code: "definition_conflict", + }; +} + const FIXTURE_CASES = [ ["add_node without a catalog", catalogRequiredCase], ["promoted host write without a catalog", promotedCatalogRequiredCase], ["interior set_widget past the positional length", widgetOutOfRangeCase], ["interior set_widget into a definition two nodes instantiate", sharedDefinitionCase], + ["define_subgraph whose root id collides with a nested definition", definitionConflictCase], ] as const; describe("KA-4: the rejection codes that need their own fixture", () => { @@ -642,6 +666,7 @@ const ALL_REJECTION_CODES = [ "not_a_subgraph", "interior_node_not_found", "shared_definition_unforked", + "definition_conflict", ] as const; // These require an already-consumed op_id or an intentionally deep payload; diff --git a/test/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index ffe50d6b..cc31bc77 100644 --- a/test/permutation/full-op-pool.permutation.test.ts +++ b/test/permutation/full-op-pool.permutation.test.ts @@ -2,9 +2,10 @@ * Full declared-op-vocabulary permutation matrix (perm-4). * * The vocabulary is read from FROZEN_OPS and DEFERRED_OPS rather than copied - * into the matrix. Pair coverage is exhaustive across kind pairs, eight - * salient document preconditions, stamp relations, arrival orders, and batch - * boundaries. Longer streams are fixed-seed fast-check samples with shrinking + * into the matrix. Pair coverage is exhaustive across kind pairs and eight + * salient document preconditions, with named representative actor/stamp + * equivalence classes, both arrival orders, and both batch boundaries. + * Longer streams are fixed-seed fast-check samples with shrinking * left enabled. * * Amendment A6 / docs/decisions/EXCEPTIONS.md and schema §2.5 item 2 are the @@ -34,7 +35,11 @@ import { canonicalize } from "../helpers.js"; const KINDS = [...FROZEN_OPS, ...DEFERRED_OPS]; const ACTORS = ["agent:perm4:0", "agent:perm4:1", "human:perm4:0", "human:perm4:1"] as const; -const VERSION_PAIRS = [[0, 0], [0, 1], [1, 0], [1, 1], [0, 9], [9, 0], [4, 4], [4, 5]] as const; +const VERSION_PAIRS = [[0, 0], [0, 1], [1, 0], [9, 0]] as const; +const ACTOR_PAIRS = [ + ["agent:perm4:0", "agent:perm4:1"], + ["agent:perm4:0", "human:perm4:0"], +] as const; const PRECONDITIONS = [ "present-valid", "source-missing", @@ -45,8 +50,10 @@ const PRECONDITIONS = [ "interior-or-inputcount", "promoted-or-autogrow", ] as const; -const PAIR_EXECUTIONS = 150_528; -const SAMPLED_RUNS = 24_736; +// 8² kind pairs × 8 preconditions × 2 actor classes × 4 stamp relations × +// 2 batch modes × 2 arrival orders = 16,384 executions (<20,000). +const PAIR_EXECUTIONS = 16_384; +const SAMPLED_RUNS = 1_696; const SAMPLED_EXECUTIONS = SAMPLED_RUNS * 2; const TOTAL_EXECUTIONS = PAIR_EXECUTIONS + SAMPLED_EXECUTIONS; const SAMPLE_SEED = 0x4f70504; @@ -215,6 +222,19 @@ function makeOp( return { ...env, op: "delete_node", node_id: side === 0 ? 10 : 20, removed_links: [80, 100, 101] }; case "clear": return { ...env, op: "clear", removed_nodes: side === 0 ? [10, 40, 57] : [20, 40, 57] }; + case "define_subgraph": + const id = "12345678-1234-4123-8123-123456789abc"; + return { + ...env, + op: "define_subgraph", + subgraph_id: id, + subgraph_definition: { + id, + name: `side-${side}`, + nodes: [], + links: [], + }, + }; case "reset_doc": return { ...env, op: "reset_doc", workflow: { nodes: [], links: [] } }; } @@ -422,16 +442,12 @@ function classify( throw new Error(`unexpected divergence ${stable({ precondition, mode, ops, left, right })}`); } -function actorPairs(): Array { - return ACTORS.flatMap((left) => ACTORS.filter((right) => right !== left).map((right) => [left, right] as const)); -} - function kindPairs(): Array { return KINDS.flatMap((left) => KINDS.map((right) => [left, right] as const)); } describe("full op-pool permutation equivalence", () => { - it("exhausts every declared op-kind pair across state, stamp, order, and batch dimensions", () => { + it("covers every declared op-kind pair across representative state, stamp, actor, order, and batch dimensions", () => { let executions = 0; let serial = 1; const taxonomy: Taxonomy = { @@ -444,7 +460,7 @@ describe("full op-pool permutation equivalence", () => { for (const kinds of kindPairs()) { for (const precondition of PRECONDITIONS) { - for (const actors of actorPairs()) { + for (const actors of ACTOR_PAIRS) { for (const versions of VERSION_PAIRS) { const pair = kinds.map((kind, side) => makeOp(kind, precondition, side as 0 | 1, serial++, actors[side]!, versions[side]!)); for (const mode of ["together", "split"] as const) { @@ -529,7 +545,7 @@ describe("full op-pool permutation equivalence", () => { expect(runs).toBe(SAMPLED_RUNS); expect(executions).toBe(SAMPLED_EXECUTIONS); - expect(TOTAL_EXECUTIONS).toBe(200_000); + expect(TOTAL_EXECUTIONS).toBe(19_776); for (const [kind, count] of Object.entries(hits)) expect(count, `${kind} was not sampled`).toBeGreaterThan(0); expect(Object.values(taxonomy).reduce((sum, count) => sum + count, 0)).toBe(SAMPLED_RUNS); console.info("perm-4 sampled taxonomy", { diff --git a/test/set-widget-interior-incarnation.test.ts b/test/set-widget-interior-incarnation.test.ts index 87b12730..805ff15e 100644 --- a/test/set-widget-interior-incarnation.test.ts +++ b/test/set-widget-interior-incarnation.test.ts @@ -88,7 +88,7 @@ describe("set_widget interior incarnation guard (current-behavior characterizati { op_id: op.op_id, outcome: "applied" }, ]); expect(interiorValue(doc)).toBe("value-1"); - expect(readStamps(doc)[stampTargetKey(op)]).toEqual(stampKey(op)); + expect(Object.values(readStamps(doc))).toEqual([stampKey(op)]); }); it("makes a mismatched-incarnation write a graph no-op without recording a stamp", () => { @@ -125,7 +125,7 @@ describe("set_widget interior incarnation guard (current-behavior characterizati { op_id: op.op_id, outcome: "applied" }, ]); expect(interiorValue(doc)).toBe("value-3"); - expect(readStamps(doc)[stampTargetKey(op)]).toEqual(stampKey(op)); + expect(Object.values(readStamps(doc))).toEqual([stampKey(op)]); }); it("makes an absent-incarnation write a no-op for a non-legacy target", () => {