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: 3 additions & 3 deletions src/doc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,9 @@ export function linkStateMap(doc: Y.Doc): Y.Map<unknown> {
}

/**
* Initialize the v1 layout on a fresh doc (idempotent). Creates the root maps
* (including bookkeeping) and seeds meta with schema_version, the pinned
* catalog_version, and the id high-water marks.
* Initialize the current layout on a fresh doc (idempotent). Creates the root
* maps (including bookkeeping) and seeds meta with `SCHEMA_VERSION`, the
* pinned catalog_version, and the id high-water marks.
*
* NOTE: initializing a doc is not the bootstrap path for replicas — replicas
* fork from one common mint() snapshot (schema §9), never re-seed.
Expand Down
2 changes: 1 addition & 1 deletion src/events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ export interface CmpEvent {
}

/** A synchronous, best-effort observer owned by the caller. */
export type CmpEventSink = (event: CmpEvent) => undefined;
export type CmpEventSink = (event: CmpEvent) => void;

/** Optional caller-owned context for a single package entry-point call. */
export interface CmpCallContext {
Expand Down
21 changes: 13 additions & 8 deletions src/limits.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,14 @@
* units here and are then refused (or accepted) by the storability gates,
* which own that boundary.
*
* Termination is a hard invariant, not a hope: every visited value adds at
* least 1 unit, so the walk performs at most {@link MAX_OP_COST} iterations
* regardless of input shape — a DAG of shared references (billion-laughs) is
* re-walked per reference and trips the budget; a lazily-infinite getter tree
* runs out of budget the same way.
* This budget covers inert decoded wire data and trusted in-process values.
* Every visited value adds at least 1 unit, so repeated shared references
* (billion-laughs) consume the budget too. The bound assumes enumeration,
* iteration, and property access terminate: a caller-created getter, Proxy,
* or custom iterator can execute arbitrary code before the next budget check.
* This function is not an execution sandbox. Hosts must decode untrusted
* wire bytes before calling the package; copying an arbitrary JavaScript
* object here cannot guarantee trap-free traversal.
*/
/** Ops per `applyOps` batch. Checked before ANY op is processed (#14). */
export const MAX_OPS_PER_BATCH = 1024;
Expand Down Expand Up @@ -58,9 +61,11 @@ type Frame =
/**
* Why an op exceeds the untrusted-payload budget, or `null` to accept it.
* Iterative (no recursion on hostile depth), cycle-tolerant (back-edges are
* skipped and left to A8's canonicalizer), and O({@link MAX_OP_COST}) in all
* cases. Called by A8's canonicalizer on the whole op object, so envelope
* fields are inside the budget too. Depth and cycles remain canonicalizer-owned.
* skipped and left to A8's canonicalizer). The budget limits visited payload
* values, not time spent executing caller-defined accessors or enumerating
* an object's keys. Called by A8's canonicalizer on the whole op object, so
* envelope fields are inside the budget too. Depth and cycles remain
* canonicalizer-owned.
*/
export function opBoundsRefusal(op: unknown): string | null {
let cost = 0;
Expand Down
17 changes: 9 additions & 8 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -657,12 +657,12 @@ export interface ApplyFailure {
/**
* Outcome of `applyOps` — per-op accounting, never a throw for a rejected op.
*
* `applied` counts every op that consumed its `op_id` in this call — including
* LWW-dropped writes and delete-wins no-ops, which are protocol-level applies
* (comfy-cli records their op_id too). `skipped` is idempotency only: op_ids
* already applied before this call. On failure, `failed` is set, ops after
* `failed.index` are NOT applied (abort-remainder), and the applied prefix is
* retained — a retried batch converges via the op_id gate.
* Each submitted op receives an ordered discriminated outcome. A refused op
* has `outcome: "rejected"` and a machine-readable and human-readable
* `reason`. On rejection while processing a batch, later operations receive
* `batch_aborted` rejection reasons and are not applied (abort-remainder);
* the processed prefix is retained, so a retried batch converges via the
* op_id gate. An oversized batch is refused before processing any operation.
*/
export type ApplyOutcome =
| { op_id: string; outcome: "applied" }
Expand Down Expand Up @@ -701,8 +701,9 @@ export interface CanonicalOpInspection {

/**
* A rejected op (unknown/deferred kind, malformed payload, unknown widget,
* missing slot, …). `applyOps` converts this into `ApplyResult.failed` —
* rejection is loud but never a throw at the batch surface.
* missing slot, …). `applyOps` converts this into an `ApplyOutcome` whose
* `outcome` is `"rejected"` and whose `reason` carries this error's code and
* message. Rejection is loud but never a throw at the batch surface.
*/
export class OpRejectedError extends Error {
override name = "OpRejectedError";
Expand Down
2 changes: 1 addition & 1 deletion test/apply-result-helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,6 @@ export function noOpIds(result: ApplyResult): string[] {
return result.outcomes.filter((outcome) => outcome.outcome === "no-op").map((outcome) => outcome.op_id);
}

export function appliedCount(result: ApplyResult): number {
export function nonRejectedOutcomeCount(result: ApplyResult): number {
return result.outcomes.filter((outcome) => outcome.outcome !== "rejected").length;
}
66 changes: 39 additions & 27 deletions test/arrival-order-convergence.regression.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,18 @@
import * as Y from "yjs";
import { describe, expect, it } from "vitest";
import { applyOps, mint, project, type Op, type WorkflowJSON, type WorkflowNode } from "../src/index.js";
import {
applyOps,
mint,
project,
type AddNodeOp,
type ClearOp,
type ConcreteConnectOp,
type DeleteNodeOp,
type GrowConnectOp,
type Op,
type WorkflowJSON,
type WorkflowNode,
} from "../src/index.js";
import { canonicalize, loadCatalog } from "./helpers.js";

const catalog = loadCatalog();
Expand Down Expand Up @@ -32,14 +44,14 @@ describe("regression: structural operations resolve by stamp, not arrival order
it("node delete and re-add converge to the higher-stamped presence", () => {
const original = source(500);
const replacement = { ...source(500), title: "replacement" };
const del = {
const del: DeleteNodeOp = {
op: "delete_node", op_id: id("delete"), actor: "human:z", base_version: 5,
stamp: [5, "human:z"], node_id: 500, removed_links: [],
} as Op;
const add = {
};
const add: AddNodeOp = {
op: "add_node", op_id: id("readd"), actor: "agent:a", base_version: 9,
stamp: [9, "agent:a"], node_id: 500, class_type: "LoadImage", pos: [], node: replacement,
} as Op;
};

expect(run(base([original]), [del, add])).toEqual(run(base([original]), [add, del]));
expect(run(base([original]), [add, del]).nodes[0]?.title).toBe("replacement");
Expand All @@ -53,11 +65,11 @@ describe("regression: structural operations resolve by stamp, not arrival order
outputs: [{ name: "IMAGE", type: "IMAGE", links: [] }],
widgets_values: [],
};
const grow = (tag: string, actor: string, version: number, link: number, from: number): Op => ({
const grow = (tag: string, actor: string, version: number, link: number, from: number): GrowConnectOp => ({
op: "connect", op_id: id(tag), actor, base_version: version, stamp: [version, actor],
link_id: link, from_node: from, from_slot: 0, to_node: 700, to_slot: null,
link_type: "IMAGE", grow: { name: "images.image0", type: "IMAGE" },
} as Op);
});
const low = grow("grow-low", "agent:a", 5, 9701, 500);
const high = grow("grow-high", "human:z", 9, 9702, 510);
const workflow = base([source(500), source(510), destination]);
Expand All @@ -67,14 +79,14 @@ describe("regression: structural operations resolve by stamp, not arrival order

it("clear and a concurrent add converge to the higher-stamped node presence", () => {
const added = source(600);
const clear = {
const clear: ClearOp = {
op: "clear", op_id: id("clear"), actor: "agent:a", base_version: 5,
stamp: [5, "agent:a"], removed_nodes: [500, 600],
} as Op;
const add = {
};
const add: AddNodeOp = {
op: "add_node", op_id: id("after-clear"), actor: "human:z", base_version: 9,
stamp: [9, "human:z"], node_id: 600, class_type: "LoadImage", pos: [], node: added,
} as Op;
};
const workflow = base([source(500)]);

expect(run(workflow, [clear, add])).toEqual(run(workflow, [add, clear]));
Expand All @@ -99,15 +111,15 @@ describe("regression: structural operations resolve by stamp, not arrival order
links: [[9000, 500, 0, 600, 0, "IMAGE"]],
groups: [], extra: {}, last_node_id: 600, last_link_id: 9000,
} as unknown as WorkflowJSON;
const del = {
const del: DeleteNodeOp = {
op: "delete_node", op_id: id("del-links"), actor: "human:z", base_version: 5,
stamp: [5, "human:z"], node_id: 500, removed_links: [9000],
} as Op;
const add = {
};
const add: AddNodeOp = {
op: "add_node", op_id: id("readd-links"), actor: "agent:a", base_version: 9,
stamp: [9, "agent:a"], node_id: 500, class_type: "LoadImage", pos: [],
node: { ...source(500), outputs: [{ name: "IMAGE", type: "IMAGE", links: [9000] }], title: "re" },
} as Op;
};

expect(run(wired, [del, add])).toEqual(run(wired, [add, del]));
const settled = run(wired, [add, del]);
Expand All @@ -134,11 +146,11 @@ describe("regression: structural operations resolve by stamp, not arrival order
links: [[9000, 500, 0, 600, 0, "IMAGE"]],
groups: [], extra: {}, last_node_id: 600, last_link_id: 9000,
} as unknown as WorkflowJSON;
const add = {
const add: AddNodeOp = {
op: "add_node", op_id: id("clobber"), actor: "agent:a", base_version: 1,
stamp: [1, "agent:a"], node_id: 500, class_type: "LoadImage", pos: [],
node: { ...source(500), outputs: [{ name: "IMAGE", type: "IMAGE", links: [] }] },
} as Op;
};

const after = run(wired, [add]);
expect(after.links).toEqual([[9000, 500, 0, 600, 0, "IMAGE"]]);
Expand All @@ -157,11 +169,11 @@ describe("regression: structural operations resolve by stamp, not arrival order
outputs: [{ name: "IMAGE", type: "IMAGE", links: [] }],
widgets_values: [],
};
const grow = (tag: string, actor: string, version: number, link: number, from: number, name: string): Op => ({
const grow = (tag: string, actor: string, version: number, link: number, from: number, name: string): GrowConnectOp => ({
op: "connect", op_id: id(tag), actor, base_version: version, stamp: [version, actor],
link_id: link, from_node: from, from_slot: 0, to_node: 700, to_slot: null,
link_type: "IMAGE", grow: { name, type: "IMAGE" },
} as Op);
});
const low = grow("diff-low", "agent:a", 5, 9701, 500, "images.image0");
const high = grow("diff-high", "human:z", 9, 9702, 510, "images.image7");
const workflow = base([source(500), source(510), destination]);
Expand All @@ -181,14 +193,14 @@ describe("regression: structural operations resolve by stamp, not arrival order
// OUTRANKS the concurrent add, [add, clear] deleted the add while
// [clear, add] kept it. `removed_nodes` is now authoritative (FC-8).
const added = source(600);
const clear = {
const clear: ClearOp = {
op: "clear", op_id: id("empty-clear"), actor: "agent:a", base_version: 9,
stamp: [9, "agent:a"], removed_nodes: [],
} as Op;
const add = {
};
const add: AddNodeOp = {
op: "add_node", op_id: id("low-add"), actor: "human:z", base_version: 3,
stamp: [3, "human:z"], node_id: 600, class_type: "LoadImage", pos: [], node: added,
} as Op;
};
const workflow = base([source(500)]);

expect(run(workflow, [clear, add])).toEqual(run(workflow, [add, clear]));
Expand All @@ -209,15 +221,15 @@ describe("regression: structural operations resolve by stamp, not arrival order
outputs: [],
widgets_values: [],
};
const clear = {
const clear: ClearOp = {
op: "clear", op_id: id("scoped-clear"), actor: "agent:a", base_version: 9,
stamp: [9, "agent:a"], removed_nodes: [510],
} as Op;
const connect = {
};
const connect: ConcreteConnectOp = {
op: "connect", op_id: id("survivor-link"), actor: "human:z", base_version: 3,
stamp: [3, "human:z"], link_id: 9800, from_node: 500, from_slot: 0,
to_node: 700, to_slot: 0, link_type: "IMAGE",
} as Op;
};
const workflow = base([source(500), source(510), destination]);

expect(run(workflow, [clear, connect])).toEqual(run(workflow, [connect, clear]));
Expand Down
6 changes: 3 additions & 3 deletions test/batch-policy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import { appliedCount, appliedOpIds, rejectedOutcome, rejectedOutcomeWithIndex } from "./apply-result-helpers.js";
import { appliedOpIds, nonRejectedOutcomeCount, rejectedOutcome, rejectedOutcomeWithIndex } from "./apply-result-helpers.js";
import {
BATCHABLE_OPS,
DEFERRED_OPS,
Expand Down Expand Up @@ -105,7 +105,7 @@ describe("batch policy — the replay surface deliberately does not gate on it (
// the replay surface (`apply_op`) has no kind restriction, and enforcing it
// here breaks the golden-vector parity contract. See issue #19.
expect(rejectedOutcome(result)).toBeUndefined();
expect(appliedCount(result)).toBe(3);
expect(nonRejectedOutcomeCount(result)).toBe(3);
expect(appliedOpIds(result)).toEqual(ops.map((o) => o.op_id));
// The clear really ran: only the post-clear node survives.
expect(project(doc, catalog).nodes.map((n) => String(n.id))).toEqual(["2"]);
Expand Down Expand Up @@ -163,6 +163,6 @@ describe("batch policy — the conformance corpus is the compatibility constrain
const doc = mint(session!.header.base_workflow, catalogFixture);
const result = applyOps(doc, session!.ops, catalogFixture);
expect(rejectedOutcome(result)).toBeUndefined();
expect(appliedCount(result)).toBe(session!.ops.length);
expect(nonRejectedOutcomeCount(result)).toBe(session!.ops.length);
});
});
17 changes: 8 additions & 9 deletions test/bounded-writes-liveness.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,8 @@ import { _getMutationCount, _resetMutationCount, stampsMap } from "../src/doc.js

const catalog: WidgetCatalog = { types: { Hub: { widget_order: ["text"] }, Peer: { widget_order: [] } } };

let seq = 0;
const env = () => {
const op_id = ("b" + String(seq++).padStart(4, "0")).padEnd(32, "0");
const env = (sequence: number) => {
const op_id = ("b" + String(sequence).padStart(4, "0")).padEnd(32, "0");
return { op_id, actor: "a", base_version: 1, stamp: [1, "a"] as [number, string] };
};

Expand Down Expand Up @@ -129,7 +128,7 @@ function deleteHubCost(degree: number): number {
const doc = mint(hubWorkflow(degree), catalog);
const op: DeleteNodeOp = {
op: "delete_node",
...env(),
...env(degree),
node_id: 1,
removed_links: Array.from({ length: degree }, (_, i) => i + 1),
};
Expand Down Expand Up @@ -177,7 +176,7 @@ describe("schema §11: the counter measures the applier's real writes", () => {
// through raw Y instead of `mset` would drop below three; anything that
// writes more would rise above it. Both are the gate losing its meaning.
const doc = mint(hubWorkflow(1), catalog);
const op = { op: "set_widget", ...env(), node_id: 1, widget: "text", value: "z" } as SetWidgetOp;
const op = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" } as SetWidgetOp;
_resetMutationCount(doc);
expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false);
expect(_getMutationCount(doc)).toBe(3);
Expand All @@ -190,7 +189,7 @@ describe("schema §11: the counter measures the applier's real writes", () => {
_resetMutationCount(doc);
const running: number[] = [];
for (let i = 0; i < 4; i++) {
const op = { op: "set_widget", ...env(), node_id: 1, widget: "text", value: "v" + String(i) } as SetWidgetOp;
const op = { op: "set_widget", ...env(i), node_id: 1, widget: "text", value: "v" + String(i) } as SetWidgetOp;
expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false);
running.push(_getMutationCount(doc));
}
Expand All @@ -208,7 +207,7 @@ describe("schema §11: the counter measures the applier's real writes", () => {
const doc = mint(chainWorkflow(), catalog);
const op = {
op: "connect",
...env(),
...env(0),
link_id: 9,
from_node: 3,
from_slot: 0,
Expand All @@ -230,7 +229,7 @@ describe("schema §11: the counter measures the applier's real writes", () => {
// deletes, two descriptor retirements, one array delete, one input-slot
// scrub, one presence stamp, one applied set.
const doc = mint(chainWorkflow(), catalog);
const op: DeleteNodeOp = { op: "delete_node", ...env(), node_id: 2, removed_links: [1, 2] };
const op: DeleteNodeOp = { op: "delete_node", ...env(0), node_id: 2, removed_links: [1, 2] };
_resetMutationCount(doc);
expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false);
expect(_getMutationCount(doc)).toBe(9);
Expand All @@ -241,7 +240,7 @@ describe("schema §11: the counter measures the applier's real writes", () => {
// cost zero Y-writes — if a skipped op still wrote, the ceiling would be
// absorbing work that the idempotency gate is supposed to have removed.
const doc = mint(hubWorkflow(1), catalog);
const op = { op: "set_widget", ...env(), node_id: 1, widget: "text", value: "z" } as SetWidgetOp;
const op = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" } as SetWidgetOp;
const first = applyOps(doc, [op], catalog);
expect(first.outcomes.some((o) => o.outcome === "rejected")).toBe(false);
expect(first.outcomes.filter((o) => o.outcome === "applied").map((o) => o.op_id)).toEqual([op.op_id]);
Expand Down
23 changes: 23 additions & 0 deletions test/events.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,15 @@ import {
} from "../src/index.js";
import { loadCatalog, loadLwwVectors } from "./helpers.js";

// Compile-time regression: ordinary callbacks, including one already typed as
// returning void, must be assignable to the public sink type.
const pretypedVoidCallback: (event: CmpEvent) => void = (_event) => {};
const ordinaryCallback = (event: CmpEvent) => event.type;
const compatibleSinks: import("../src/index.js").CmpEventSink[] = [
pretypedVoidCallback,
ordinaryCallback,
];

const catalog: WidgetCatalog = { types: {} };
const lwwCatalog = loadCatalog();
const lww = loadLwwVectors();
Expand Down Expand Up @@ -62,6 +71,20 @@ const goldenEvents = readFileSync(new URL("../fixtures/cmp-events/v1.jsonl", imp
.map((line) => JSON.parse(line) as CmpEvent);

describe("caller-owned cmp event sink", () => {
it("accepts ordinary and pretyped void callbacks", () => {
const event = goldenEvents[0]!;
expect(compatibleSinks.map((sink) => sink(event))).toEqual([
undefined,
event.type,
]);
});

it("emits the void sink return in the public declaration", () => {
const declaration = readFileSync(new URL("../dist/events.d.ts", import.meta.url), "utf8");
expect(declaration).toMatch(/CmpEventSink = \(event: CmpEvent\) => void;/);
expect(declaration).not.toMatch(/CmpEventSink = \(event: CmpEvent\) => undefined;/);
});

it("isolates a throwing sink from applier results and document bytes", () => {
const baselineDoc = mint({ nodes: [], links: [] }, catalog);
const observedDoc = new Y.Doc();
Expand Down
Loading
Loading