diff --git a/src/doc.ts b/src/doc.ts index 214abb4..6dd7a98 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -207,9 +207,9 @@ export function linkStateMap(doc: Y.Doc): Y.Map { } /** - * 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. diff --git a/src/events.ts b/src/events.ts index 43e4508..ffb05f6 100644 --- a/src/events.ts +++ b/src/events.ts @@ -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 { diff --git a/src/limits.ts b/src/limits.ts index b22ba65..c3bdbf7 100644 --- a/src/limits.ts +++ b/src/limits.ts @@ -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; @@ -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; diff --git a/src/types.ts b/src/types.ts index 8b9cafb..66aa5f5 100644 --- a/src/types.ts +++ b/src/types.ts @@ -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" } @@ -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"; diff --git a/test/apply-result-helpers.ts b/test/apply-result-helpers.ts index 9425b58..2a4f145 100644 --- a/test/apply-result-helpers.ts +++ b/test/apply-result-helpers.ts @@ -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; } diff --git a/test/arrival-order-convergence.regression.test.ts b/test/arrival-order-convergence.regression.test.ts index 275e4c3..504efa3 100644 --- a/test/arrival-order-convergence.regression.test.ts +++ b/test/arrival-order-convergence.regression.test.ts @@ -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(); @@ -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"); @@ -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]); @@ -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])); @@ -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]); @@ -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"]]); @@ -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]); @@ -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])); @@ -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])); diff --git a/test/batch-policy.test.ts b/test/batch-policy.test.ts index b0dc9b5..d3d888c 100644 --- a/test/batch-policy.test.ts +++ b/test/batch-policy.test.ts @@ -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, @@ -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"]); @@ -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); }); }); diff --git a/test/bounded-writes-liveness.test.ts b/test/bounded-writes-liveness.test.ts index ac5e552..0838820 100644 --- a/test/bounded-writes-liveness.test.ts +++ b/test/bounded-writes-liveness.test.ts @@ -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] }; }; @@ -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), }; @@ -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); @@ -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)); } @@ -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, @@ -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); @@ -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]); diff --git a/test/events.test.ts b/test/events.test.ts index 21e6c84..ae3ea38 100644 --- a/test/events.test.ts +++ b/test/events.test.ts @@ -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(); @@ -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(); diff --git a/test/op-bounds.test.ts b/test/op-bounds.test.ts index 8041606..bc9edf4 100644 --- a/test/op-bounds.test.ts +++ b/test/op-bounds.test.ts @@ -8,7 +8,7 @@ */ import * as Y from "yjs"; import { describe, expect, it } from "vitest"; -import { appliedCount, appliedOpIds, noOpIds, rejectedOutcome } from "./apply-result-helpers.js"; +import { appliedOpIds, noOpIds, nonRejectedOutcomeCount, rejectedOutcome } from "./apply-result-helpers.js"; import { applyOps, MAX_COLLECTION_ENTRIES, @@ -107,7 +107,7 @@ describe("applyOps enforces the budget before any mutation", () => { const doc = mint(base, catalog); const result = applyOps(doc, [setWidget("c".repeat(32), wrap(30))], catalog); expect(rejectedOutcome(result)).toBeUndefined(); - expect(appliedCount(result)).toBe(1); + expect(nonRejectedOutcomeCount(result)).toBe(1); }); it(`rejects a batch of ${MAX_OPS_PER_BATCH + 1} ops before processing any`, () => { @@ -131,6 +131,6 @@ describe("applyOps enforces the budget before any mutation", () => { ); const result = applyOps(doc, ops, catalog); expect(rejectedOutcome(result)).toBeUndefined(); - expect(appliedCount(result)).toBe(MAX_OPS_PER_BATCH); + expect(nonRejectedOutcomeCount(result)).toBe(MAX_OPS_PER_BATCH); }); }); diff --git a/test/readonly-surface.test.ts b/test/readonly-surface.test.ts index 1bd6a58..2771556 100644 --- a/test/readonly-surface.test.ts +++ b/test/readonly-surface.test.ts @@ -401,9 +401,9 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { /** * The defect this block exists for: `project()` grew a schema-version read * gate in #60, and a surface that reads the SAME layout by the SAME key - * names without one is a way AROUND that gate — `readGraph` would hand back - * v1 key names for a v2 document, which is precisely the KA-11 - * mis-projection #60 refused. A guard a consumer can walk around is + * names without one is a way AROUND that gate — `readGraph` could hand back + * old-layout key names for a current-schema document, which is precisely the + * KA-11 mis-projection #60 refused. A guard a consumer can walk around is * decorative. * * The rule has TWO clauses and both are load-bearing: @@ -421,8 +421,9 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { * bump trigger — a name-keyed probe is blind to exactly the document the * gate exists to refuse. * - * `SCHEMA_VERSION` is 2, so a v1 document exercises the older-than-reader - * arm through the same `assertReadableSchema` comparison used by project(). + * `SCHEMA_VERSION` is 3, so a schema-v1 document exercises the + * older-than-reader arm through the same `assertReadableSchema` comparison + * used by project(). */ /** A document that carries real content, with `meta.schema_version` forced to `version`. */ diff --git a/test/schema.test.ts b/test/schema.test.ts index a32011f..b1bdeec 100644 --- a/test/schema.test.ts +++ b/test/schema.test.ts @@ -13,7 +13,7 @@ describe("schema", () => { expect(SCHEMA_VERSION).toBe(3); }); - it("initDoc creates the v1 layout: nodes/links/definitions/meta + bookkeeping", () => { + it("initDoc creates the schema v3 layout: nodes/links/definitions/meta + bookkeeping", () => { const doc = new Y.Doc(); initDoc(doc, "object_info@2026-08-01"); expect(nodesMap(doc)).toBeInstanceOf(Y.Map);