Skip to content
31 changes: 21 additions & 10 deletions docs/multiplayer-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -581,20 +581,31 @@ node/link arrays are **not** sorted at projection — the §7 sorted-by-id rule
applies to the top-level arrays only. Python's `canonical` sorts
`definitions.subgraphs` by id but leaves each definition's interior arrays
in authored order, and the fixtures pin that (`session-subgraph`'s def lists
node 27 before node 3). Since only `set_widget` is subgraph-scoped, interior
membership and order are static after mint; the def Y.Map therefore stores
plain `node_order`/`link_order` registers (written once at mint) and
projection emits interior arrays in that order. Definitions themselves
project sorted by definition id.
node 27 before node 3). The def Y.Map stores plain scalar
`node_order`/`link_order` registers, and projection emits interior arrays in
that order. Interior `connect` preserves surviving imported links as an
authored-order prefix and sorts op-added links after them by winning stamp.
The scalar `link_order` itself is updated to that canonical order; projection
does not depend on an object marker hidden inside the array. Definitions
themselves project sorted by definition id.

Added-link ordering stamps use the internal `__stamps` key
`["interior_link_order", String(definition_id), String(link_id)]`. A winning
same-ID rewrite refreshes that stamp; rewriting a still-present imported link
does not reclassify it as an addition. Definition IDs identify unique
definitions. These are additional internal stamp entries, not a new root or
scalar-array layout; as with Amendment A18, `SCHEMA_VERSION` remains 2.

### 5.2 Addressing: three forms, one write target

Only `set_widget` is subgraph-scoped in the frozen vocabulary (spike Q6;
error strings captured verbatim in `fixtures/findings.json`):
The frozen spike supported only subgraph-scoped `set_widget` (spike Q6;
historical error strings remain in `fixtures/findings.json`). The current
package also supports `connect` with a non-empty instance `path`:

- `connect` structurally refuses interior endpoints ("a link cannot cross
the subgraph boundary") and promoted-widget targets ("promoted widget (a
value), not a link input").
- Interior `connect` resolves both endpoints within one definition and rejects
interior autogrow and writes to shared, unforked definitions. Input stamps
include the path; normalized link identity stamps do too. This does not
enable cross-boundary wiring or an interior `disconnect` operation.
- `add_node`/`delete_node` cannot address interior nodes at all.

`set_widget` accepts three address forms — flat promoted (`57.text`, routed
Expand Down
164 changes: 159 additions & 5 deletions src/applier.ts
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ import {
type WidgetCatalog,
type WireOp,
} from "./types.js";
import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js";
import { NODE_INCARNATION_KEY } from "./types.js";

/**
Expand Down Expand Up @@ -1226,6 +1227,15 @@ function requireOutputSlot(src: Y.Map<unknown>, op: ConnectOp): Y.Array<unknown>
function requireOpOnlyValid(op: ConnectOp): void {
requireOutputSlotDomain(op);

if (op.path !== undefined) {
if (!Array.isArray(op.path) || op.path.length === 0) {
throw new OpRejectedError("malformed_op", "connect: path must be a non-empty array when present");
}
if (op.grow != null) {
throw new OpRejectedError("malformed_op", "connect: interior autogrow is not supported");
}
}

if (op.node_incarnation !== undefined && (typeof op.node_incarnation !== "string" || op.node_incarnation.length === 0)) {
throw new OpRejectedError("malformed_op", "connect: node_incarnation must be a non-empty string");
}
Expand Down Expand Up @@ -1273,11 +1283,134 @@ function requireOpOnlyValid(op: ConnectOp): void {
}
}

interface InteriorConnectScope {
nodes: Y.Map<Y.Map<unknown>>;
links: Y.Map<unknown>;
definition: Y.Map<unknown>;
}

/** Resolve the definition owned by the instance at an interior connect path. */
function resolveInteriorConnectScope(
doc: Y.Doc,
op: ConnectOp,
catalog?: WidgetCatalog,
): InteriorConnectScope | null {
if (!op.path || op.path.length === 0) return null;
const host = resolveInteriorNode(doc, op.path.map(String), catalog);
if (host === null) return null;
const hostType = String(host.get("type") ?? "");
const definition = resolveDefinition(doc, hostType);
if (!definition) {
throw new OpRejectedError(
"not_a_subgraph",
`node ${String(host.get("id"))} is not a subgraph; cannot connect inside it`,
);
}
const definitionId = String(definition.get("id") ?? hostType);
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 nodes = definition.get("nodes");
const links = definition.get("links");
if (!(nodes instanceof Y.Map) || !(links instanceof Y.Map)) {
throw new OpRejectedError("malformed_op", `subgraph definition ${definitionId} has malformed graph storage`);
}
return { nodes: nodes as Y.Map<Y.Map<unknown>>, links, definition };
}

function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectScope): SuccessfulOutcome {
const linkRefusal = arrayItemRefusal(op.link_id) ?? mapValueRefusal(op.link_id);
if (linkRefusal !== null) {
throw new OpRejectedError("malformed_op", `connect: link_id: ${linkRefusal}`);
}

const src = scope.nodes.get(String(op.from_node));
const dst = scope.nodes.get(String(op.to_node));
if (!dst) return "no-op";
const sourceOutputs = src ? requireOutputSlot(src, op) : null;
const toIdx = op.to_slot as number;
const inputs = dst.get("inputs");
if (!(inputs instanceof Y.Array) || toIdx >= inputs.length) {
throw new OpRejectedError(
"input_slot_missing",
`connect: input slot ${String(toIdx)} not found on node ${String(op.to_node)}`,
);
}
const input = inputs.get(toIdx);
if (!(input instanceof Y.Map)) {
throw new OpRejectedError("input_slot_missing", `connect: input slot ${toIdx} is not a slot record`);
}

if (!claimLinkIdentity(doc, op, scope)) return "lww-dropped";
const stamps = stampsMap(doc);
const targetKey = stampTargetKey(op);
const prior = stamps.get(targetKey) as StampKey | undefined;
const key = stampKey(op);
if (prior != null && compareStampKeys(key, prior) <= 0) return "lww-dropped";
mset(stamps, targetKey, key);

const previous = input.get("link");
if (previous != null && previous !== op.link_id) removeLinkInScope(scope, previous);
if (!src || !sourceOutputs) return "no-op";

const linkKey = String(op.link_id);
if (!scope.links.has(linkKey)) {
mset(scope.links, linkKey, {
id: op.link_id,
origin_id: op.from_node,
origin_slot: op.from_slot,
target_id: op.to_node,
target_slot: toIdx,
type: op.link_type,
});
}
const linkOrder = scope.definition.get("link_order");
const orderedIds: unknown[] = Array.isArray(linkOrder) ? [...linkOrder] : [];
const definitionId = String(scope.definition.get("id") ?? "");
const orderStampKey = (candidate: string) =>
JSON.stringify(["interior_link_order", definitionId, candidate]);
const additions: Record<string, StampKey> = Object.create(null) as Record<string, StampKey>;
for (const candidate of orderedIds.map(String)) {
const addedStamp = stamps.get(orderStampKey(candidate));
if (Array.isArray(addedStamp)) additions[candidate] = addedStamp as StampKey;
}
const wasAdded = Object.hasOwn(additions, linkKey);
const wasPresent = orderedIds.some((candidate) => String(candidate) === linkKey);
const nextOrder = addInteriorLinkOrder(orderedIds, linkKey, key, additions);
if (!wasPresent || wasAdded) {
mset(stamps, orderStampKey(linkKey), key);
}
if (nextOrder.some((candidate, index) => candidate !== orderedIds[index]) || nextOrder.length !== orderedIds.length) {
mset(scope.definition, "link_order", nextOrder);
}
mset(input, "link", op.link_id);
const output = sourceOutputs.get(op.from_slot) as Y.Map<unknown>;
let outputLinks = output.get("links");
if (!(outputLinks instanceof Y.Array)) {
outputLinks = new Y.Array<unknown>();
mset(output, "links", outputLinks);
}
if (!(outputLinks as Y.Array<unknown>).toArray().includes(op.link_id)) {
apush(outputLinks as Y.Array<unknown>, op.link_id);
}
return "applied";
}

function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): SuccessfulOutcome {
// OP-ONLY validation first, before ANY document read decides the outcome
// (KA-4, Amendment A6).
requireOpOnlyValid(op);

if (op.path && op.path.length > 0) {
const scope = resolveInteriorConnectScope(doc, op, catalog);
if (scope === null) return "no-op";
return applyInteriorConnect(doc, op, scope);
}

const nodes = nodesMap(doc);
const dst = nodes.get(String(op.to_node));
// The destination is gone → the target slot does not exist and never will
Expand Down Expand Up @@ -1418,17 +1551,21 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe
}

/** Claim the normalized complete-tuple link register (schema Amendment A18). */
function claimLinkIdentity(doc: Y.Doc, op: ConnectOp): boolean {
function claimLinkIdentity(doc: Y.Doc, op: ConnectOp, scope?: InteriorConnectScope): boolean {
const stamps = stampsMap(doc);
const normalizedId = String(op.link_id);
const targetKey = JSON.stringify(["link", normalizedId]);
const targetKey = JSON.stringify(["link", ...(scope && op.path ? [op.path.map(String)] : []), normalizedId]);
const prior = stamps.get(targetKey) as StampKey | undefined;
const key = stampKey(op);
if (prior != null && compareStampKeys(key, prior) <= 0) return false;

const links = linksMap(doc);
const links = scope?.links ?? linksMap(doc);
if (links.has(normalizedId)) mdel(links, normalizedId);
scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === normalizedId);
if (scope) {
scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === normalizedId);
} else {
scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === normalizedId);
}
mset(stamps, targetKey, key);
return true;
}
Expand Down Expand Up @@ -1762,9 +1899,26 @@ function removeLink(doc: Y.Doc, linkId: unknown): void {
scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === key);
}

function removeLinkInScope(scope: InteriorConnectScope, linkId: unknown): void {
const key = String(linkId);
if (scope.links.has(key)) mdel(scope.links, key);
scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === key);
const linkOrder = scope.definition.get("link_order");
if (Array.isArray(linkOrder)) {
mset(scope.definition, "link_order", removeInteriorLinkOrder(linkOrder, key));
}
}

/** Scrub input/output references selected by one shared link-id predicate. */
function scrubLinkRefs(doc: Y.Doc, shouldRemove: (linkId: unknown) => boolean): void {
nodesMap(doc).forEach((node) => {
scrubNodeLinkRefs(nodesMap(doc), shouldRemove);
}

function scrubNodeLinkRefs(
nodes: Y.Map<Y.Map<unknown>>,
shouldRemove: (linkId: unknown) => boolean,
): void {
nodes.forEach((node) => {
const ins = node.get("inputs");
if (ins instanceof Y.Array) {
ins.forEach((slot: unknown) => {
Expand Down
28 changes: 28 additions & 0 deletions src/interior-link-order.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import { compareStampKeys } from "./stamps.js";
import type { StampKey } from "./types.js";

export function addInteriorLinkOrder(
order: unknown[],
id: string,
stamp: StampKey,
priorAdditions: Record<string, StampKey>,
): string[] {
const ids = order.map(String);
const wasAdded = Object.hasOwn(priorAdditions, id);
if (ids.includes(id) && !wasAdded) return ids;
const additions = { ...priorAdditions, [id]: stamp };
const withId = ids.includes(id) ? ids : [...ids, id];
const imported = withId.filter((candidate) => !Object.hasOwn(additions, candidate));
const added = withId.filter((candidate) => Object.hasOwn(additions, candidate));
added.sort((a, b) => compareStampKeys(additions[a]!, additions[b]!));
return [...imported, ...added];
}

/** The stored scalar order is already canonical for unchanged-schema readers. */
export function projectInteriorLinkOrder(order: unknown[]): string[] {
return order.map(String);
}

export function removeInteriorLinkOrder(order: unknown[], id: string): unknown[] {
return order.filter((entry) => String(entry) !== id);
}
6 changes: 3 additions & 3 deletions src/mint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ interface SubgraphDef {
* map through `catalog` — schema §1.2);
* - `definitions.subgraphs` into the first-class `definitions` root map
* (schema §5.1), with interior node/link mint order preserved in plain
* `node_order`/`link_order` registers (interior order is static in v1 —
* only `set_widget` is subgraph-scoped); non-`subgraphs` keys of the
* definitions container are kept in the internal `__definitions_extra`
* `node_order`/`link_order` registers; later interior links retain this
* imported prefix and project in deterministic stamp order;
* non-`subgraphs` keys of the definitions container are kept in the internal `__definitions_extra`
* meta key and merged back at projection;
* - every other top-level key into meta as opaque passthrough (schema §6);
* - `schema_version` + the pinned `catalogVersion` into meta.
Expand Down
12 changes: 8 additions & 4 deletions src/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
*
* Subgraph definitions project as `{...extra, subgraphs: [...]}` with
* definitions sorted by id and each definition's interior nodes/links in
* mint order (`node_order`/`link_order` — interior order is static in v1
* because only `set_widget` is subgraph-scoped).
* mint order (`node_order`/`link_order`); links added by semantic ops follow
* imported links in deterministic stamp order.
*/

import * as Y from "yjs";
Expand All @@ -33,6 +33,7 @@ import {
widgetStorageOf,
} from "./doc.js";
import { assertNever } from "./exhaustive.js";
import { projectInteriorLinkOrder } from "./interior-link-order.js";
import { assertReadableSchema } from "./schema-version.js";
import { NODE_INCARNATION_KEY, type WidgetCatalog, type WorkflowJSON, type WorkflowNode } from "./types.js";

Expand Down Expand Up @@ -221,7 +222,7 @@ function tryProjectNode(value: unknown, catalog: WidgetCatalog): WorkflowNode |
return projectNode(value, catalog);
}

/** Definition Y.Map → subgraph definition JSON, interior nodes/links in mint order. */
/** Definition Y.Map → subgraph JSON, preserving mint order before deterministic additions. */
function projectDefinition(dm: Y.Map<unknown>, catalog: WidgetCatalog): Record<string, unknown> {
const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
dm.forEach((v, k) => {
Expand All @@ -233,7 +234,10 @@ function projectDefinition(dm: Y.Map<unknown>, catalog: WidgetCatalog): Record<s
.map((id) => tryProjectNode(v.get(id), catalog))
.filter((node): node is WorkflowNode => node !== null);
} else if (k === "links" && v instanceof Y.Map) {
const order = (dm.get("link_order") as string[] | undefined) ?? [...v.keys()].sort();
const storedOrder = dm.get("link_order");
const order = Array.isArray(storedOrder)
? projectInteriorLinkOrder(storedOrder)
: [...v.keys()].sort();
out[k] = order.filter((id) => v.has(id)).map((id) => structuredClone(v.get(id)));
} else {
out[k] = structuredClone(v);
Expand Down
3 changes: 3 additions & 0 deletions src/stamps.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,9 @@ export function writeTarget(op: WireOp): unknown[] {
}
return ["input", String(op.to_node), "grow", String(op.grow.name).split(".", 1)[0]];
}
if (op.path && op.path.length > 0) {
return ["input", op.path.map(String), String(op.to_node), op.to_slot];
}
return ["input", String(op.to_node), op.to_slot];
case "disconnect":
return ["input", String(op.to_node), op.to_slot];
Expand Down
2 changes: 2 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,8 @@ export interface PromotedHostWrite {
/** Fields every `connect` carries, whichever way its destination slot is addressed. */
interface ConnectOpBase extends OpBase {
op: "connect";
/** Non-empty subgraph-instance path for a connect inside its definition. */
path?: [NodeId, ...NodeId[]];
/** Link identity, minted at op-mint time (int in comfy-cli). */
link_id: NodeId;
from_node: NodeId;
Expand Down
Loading