@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/methods/csharp/origins.ts

@@ -0,0 +1,126 @@
+import { assertDataTree } from "../../core/data.js";
+import { dataNodesMax } from "../../core/limits.js";
+import { decodePayload, object } from "../../items/codec.js";
+import type { ItemPayload } from "../../items/item.js";
+import { bindItemOrigin, itemNodes, itemOrigin } from "../../items/origins.js";
+import { PlatformError } from "../../platform/errors.js";
+
+export interface OriginFrame {
+    readonly scope: string;
+    readonly tokens: readonly string[];
+}
+
+/** Tokens are local to one managed invocation; opaque Item origins survive ordinary clones. */
+export class ManagedOrigins {
+    private readonly scope = crypto.randomUUID();
+    private readonly tokens = new Map<symbol, string>();
+    private readonly origins = new Map<string, symbol>();
+    private nextToken = 0;
+
+    capture(payload: ItemPayload): OriginFrame {
+        assertDataTree(payload);
+        const result: string[] = [];
+        const used = new Set<symbol>();
+
+        for (const node of itemNodes(payload)) {
+            const origin = itemOrigin(node) ?? Symbol("pending Item");
+
+            if (used.has(origin)) {
+                throw new PlatformError("InvalidProtocol", "An Item origin occurs more than once.");
+            }
+
+            used.add(origin);
+            bindItemOrigin(node, origin);
+            let token = this.tokens.get(origin);
+
+            if (token === undefined) {
+                token = `b${++this.nextToken}`;
+                this.remember(token, origin);
+            }
+
+            result.push(token);
+        }
+
+        return { scope: this.scope, tokens: result };
+    }
+
+    decode(value: unknown, frame: unknown): ItemPayload {
+        const payload = decodePayload(value);
+        this.bind(payload, frame);
+
+        return payload;
+    }
+
+    bind(payload: ItemPayload, frame: unknown): void {
+        if (!object(frame) || frame.scope !== this.scope) {
+            throw new PlatformError(
+                "InvalidProtocol",
+                "Managed Item origins belong to another invocation.",
+            );
+        }
+
+        const tokens = frame.tokens;
+
+        if (!Array.isArray(tokens) || tokens.length > dataNodesMax) {
+            throw new PlatformError(
+                "InvalidProtocol",
+                "Managed Item origins must be a bounded list.",
+            );
+        }
+
+        const used = new Set<string>();
+        let index = 0;
+
+        for (const node of itemNodes(payload)) {
+            const token: unknown = tokens[index++];
+
+            if (
+                typeof token !== "string" ||
+                !/^[bm][1-9]\d{0,6}$/.test(token) ||
+                Number(token.slice(1)) > dataNodesMax ||
+                used.has(token)
+            ) {
+                throw new PlatformError(
+                    "InvalidProtocol",
+                    "Managed Item origins are missing or duplicated.",
+                );
+            }
+
+            used.add(token);
+            let origin = this.origins.get(token);
+
+            if (origin === undefined) {
+                if (token.startsWith("b")) {
+                    throw new PlatformError(
+                        "InvalidProtocol",
+                        "Managed Item origin belongs to another invocation.",
+                    );
+                }
+
+                origin = Symbol("managed Item");
+                this.remember(token, origin);
+            }
+
+            bindItemOrigin(node, origin);
+        }
+
+        if (index !== tokens.length) {
+            throw new PlatformError(
+                "InvalidProtocol",
+                "Managed Item origins do not match the payload.",
+            );
+        }
+    }
+
+    private remember(token: string, origin: symbol): void {
+        if (this.origins.size >= dataNodesMax) {
+            throw new PlatformError(
+                "ProtocolLimit",
+                "Managed Item origins exceed their invocation limit.",
+            );
+        }
+
+        this.tokens.set(origin, token);
+        this.origins.set(token, origin);
+    }
+}

package/src/methods/csharp/protocol.ts

@@ -0,0 +1,104 @@
+import type { ReadableStreamDefaultReader } from "node:stream/web";
+
+import { assertDataTree, parseFrozenJson } from "../../core/data.js";
+import { object } from "../../items/codec.js";
+import { PlatformError } from "../../platform/errors.js";
+
+export const messageBytesMax = 8 * 1024 * 1024;
+export const pendingCallsMax = 128;
+const encoder = new TextEncoder();
+
+export function encodeMessage(message: unknown): Uint8Array {
+    assertDataTree(message);
+    const bytes = encoder.encode(`${JSON.stringify(message)}\n`);
+
+    if (bytes.length > messageBytesMax) {
+        throw new PlatformError("ProtocolLimit", "C# message exceeds the 8 MiB limit.");
+    }
+
+    return bytes;
+}
+
+/** The byte budget applies to each frame, including when one pipe chunk contains many frames. */
+export async function readMessages(
+    stream: ReadableStream<Uint8Array>,
+    receive: (message: Record<string, unknown>) => void,
+    readWhenActive?: () => boolean | Promise<boolean>,
+): Promise<void> {
+    const decoder = new MessageDecoder();
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+
+    try {
+        while (true) {
+            const active = readWhenActive?.() ?? true;
+
+            if (typeof active !== "boolean") {
+                reader?.releaseLock();
+                reader = undefined;
+
+                if (!(await active)) {
+                    break;
+                }
+            } else if (!active) {
+                break;
+            }
+
+            reader ??= stream.getReader();
+            const chunk = await reader.read();
+
+            if (chunk.done) {
+                break;
+            }
+
+            decoder.push(chunk.value, receive);
+        }
+
+        decoder.finish();
+    } finally {
+        reader?.releaseLock();
+    }
+}
+
+class MessageDecoder {
+    private readonly decoder = new TextDecoder("utf-8", { fatal: true });
+    private buffer = "";
+
+    push(bytes: Uint8Array, receive: (message: Record<string, unknown>) => void): void {
+        this.buffer += this.decoder.decode(bytes, { stream: true });
+        let newline = this.buffer.indexOf("\n");
+
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline);
+            assertMessageSize(line);
+            const message = parseFrozenJson(line);
+
+            if (
+                !object(message) ||
+                typeof message.kind !== "string" ||
+                typeof message.id !== "string"
+            ) {
+                throw new PlatformError("InvalidProtocol", "Invalid C# worker message.");
+            }
+
+            receive(message);
+            this.buffer = this.buffer.slice(newline + 1);
+            newline = this.buffer.indexOf("\n");
+        }
+
+        assertMessageSize(this.buffer);
+    }
+
+    finish(): void {
+        this.buffer += this.decoder.decode();
+
+        if (this.buffer.length > 0) {
+            throw new PlatformError("InvalidProtocol", "C# worker stopped inside a message.");
+        }
+    }
+}
+
+function assertMessageSize(value: string): void {
+    if (value.length > messageBytesMax || encoder.encode(value).length > messageBytesMax) {
+        throw new PlatformError("ProtocolLimit", "C# worker message exceeds the 8 MiB limit.");
+    }
+}

package/src/methods/csharp/relationship-order.ts

@@ -0,0 +1,76 @@
+import { dataNodesMax } from "../../core/limits.js";
+import type { ItemNode } from "../../items/item.js";
+import { itemOrigin } from "../../items/origins.js";
+import { PlatformError } from "../../platform/errors.js";
+
+export interface RelationshipPosition {
+    readonly before?: number;
+    readonly after?: number;
+}
+
+/** Only pending node origins establish XML identity; business IDs and values can repeat. */
+export function relationshipOrder(
+    before: readonly ItemNode[],
+    after: readonly ItemNode[],
+): readonly RelationshipPosition[] {
+    if (before.length > dataNodesMax || after.length > dataNodesMax) {
+        throw new PlatformError("ProtocolLimit", "Relationship origins exceed their node limit.");
+    }
+
+    const origins = originalPositions(before);
+    const seen = new Set<symbol>();
+    const used = new Set<number>();
+    const result: RelationshipPosition[] = [];
+
+    for (const [index, node] of after.entries()) {
+        const origin = itemOrigin(node);
+
+        if (origin !== undefined) {
+            if (seen.has(origin)) {
+                throw new PlatformError("InvalidProtocol", "A relationship origin is duplicated.");
+            }
+
+            seen.add(origin);
+        }
+
+        const previous = origin === undefined ? undefined : origins.get(origin);
+
+        if (previous === undefined) {
+            result.push({ after: index });
+        } else {
+            used.add(previous);
+            result.push({ before: previous, after: index });
+        }
+    }
+
+    for (let index = 0; index < before.length; index += 1) {
+        if (!used.has(index)) {
+            result.push({ before: index });
+        }
+    }
+
+    return result;
+}
+
+function originalPositions(before: readonly ItemNode[]): ReadonlyMap<symbol, number> {
+    const result = new Map<symbol, number>();
+
+    for (const [index, node] of before.entries()) {
+        const origin = itemOrigin(node);
+
+        if (origin === undefined) {
+            throw new PlatformError(
+                "UnsupportedRequestIdentity",
+                "Untracked relationship requests require native node identity.",
+            );
+        }
+
+        if (result.has(origin)) {
+            throw new PlatformError("InvalidProtocol", "A relationship origin is duplicated.");
+        }
+
+        result.set(origin, index);
+    }
+
+    return result;
+}

package/src/methods/csharp/request-change.ts

@@ -0,0 +1,349 @@
+import { getOwn, setOwn } from "../../core/data.js";
+import { dataDepthMax, dataNodesMax } from "../../core/limits.js";
+import type { ItemNode } from "../../items/item.js";
+import { itemOrigin } from "../../items/origins.js";
+import { PlatformError } from "../../platform/errors.js";
+import { relationshipOrder } from "./relationship-order.js";
+import type { RelationshipPosition } from "./relationship-order.js";
+
+interface RequestNode {
+    readonly type: string;
+    attributes?: ItemNode["attributes"];
+    properties?: ItemNode["properties"];
+    propertyAttributes?: ItemNode["propertyAttributes"];
+    propertyItems?: Record<string, RequestNode>;
+    relationships?: RequestNode[];
+    logical?: ItemNode["logical"];
+}
+
+export interface RequestChange {
+    readonly before: RequestNode;
+    readonly after: RequestNode;
+    readonly alignment?: RequestAlignment;
+}
+
+interface RequestAlignment {
+    replaceItem?: true;
+    properties?: Record<string, RequestAlignment>;
+    relationships?: readonly (RelationshipPosition & { readonly alignment?: RequestAlignment })[];
+}
+
+interface Difference {
+    readonly before: RequestNode;
+    readonly after: RequestNode;
+    alignment?: RequestAlignment;
+    changed: boolean;
+}
+
+interface Frame {
+    readonly before: ItemNode;
+    readonly after: ItemNode;
+    readonly result: Difference;
+    readonly properties: { readonly name: string; readonly result: Difference }[];
+    readonly relationships: Difference[];
+    readonly depth: number;
+    order?: readonly RelationshipPosition[];
+    finish: boolean;
+}
+
+/** Carry changes only: unchanged business values must not multiply the callback byte budget. */
+export function requestDifference(before: ItemNode, after: ItemNode): RequestChange | undefined {
+    assertPreservedOrigin(before, after, "request root");
+    const root = createFrame(before, after, 0);
+    const pending = [root];
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const current = pending.pop();
+
+        if (
+            !current ||
+            (!current.finish && ++visited > dataNodesMax) ||
+            current.depth > dataDepthMax ||
+            pending.length > dataNodesMax
+        ) {
+            throw new PlatformError(
+                "ProtocolLimit",
+                "Native request changes exceed their tree budget.",
+            );
+        }
+
+        if (current.finish) {
+            completeFrame(current);
+            continue;
+        }
+
+        compareFields(current);
+        current.finish = true;
+        pending.push(current);
+        comparePropertyItems(current, pending);
+        compareRelationships(current, pending);
+    }
+
+    return root.result.changed
+        ? {
+              before: root.result.before,
+              after: root.result.after,
+              ...(root.result.alignment ? { alignment: root.result.alignment } : {}),
+          }
+        : undefined;
+}
+
+function createFrame(before: ItemNode, after: ItemNode, depth: number): Frame {
+    return {
+        before,
+        after,
+        depth,
+        result: {
+            before: { type: before.type },
+            after: { type: after.type },
+            changed: before.type !== after.type,
+        },
+        properties: [],
+        relationships: [],
+        finish: false,
+    };
+}
+
+function compareFields(current: Frame): void {
+    const { before, after, result } = current;
+    const attributes = compareValues(before.attributes, after.attributes);
+    const properties = compareValues(before.properties, after.properties);
+    const propertyAttributes = compareValues(before.propertyAttributes, after.propertyAttributes);
+    result.before.attributes = attributes.before;
+    result.after.attributes = attributes.after;
+    result.before.properties = properties.before;
+    result.after.properties = properties.after;
+    result.before.propertyAttributes = propertyAttributes.before;
+    result.after.propertyAttributes = propertyAttributes.after;
+    result.changed ||= attributes.changed || properties.changed || propertyAttributes.changed;
+
+    for (const name of new Set([
+        ...Object.keys(propertyAttributes.before),
+        ...Object.keys(propertyAttributes.after),
+    ])) {
+        const previous = getOwn(before.properties, name);
+        const next = getOwn(after.properties, name);
+
+        if (previous !== undefined) {
+            setOwn(properties.before, name, previous);
+        }
+
+        if (next !== undefined) {
+            setOwn(properties.after, name, next);
+        }
+    }
+
+    if (!Bun.deepEquals(before.logical, after.logical)) {
+        result.before.logical = before.logical;
+        result.after.logical = after.logical;
+        // Implicit logical groups can repeat scalar and Item-valued property names.
+        result.before.properties = { ...before.properties };
+        result.after.properties = { ...after.properties };
+        result.before.propertyAttributes = { ...before.propertyAttributes };
+        result.after.propertyAttributes = { ...after.propertyAttributes };
+        result.before.propertyItems = { ...before.propertyItems };
+        result.after.propertyItems = { ...after.propertyItems };
+        result.changed = true;
+    }
+}
+
+function compareValues<Value>(
+    before: Readonly<Record<string, Value>>,
+    after: Readonly<Record<string, Value>>,
+) {
+    const previous: Record<string, Value> = {};
+    const next: Record<string, Value> = {};
+    let changed = false;
+
+    for (const name of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const left = getOwn(before, name);
+        const right = getOwn(after, name);
+
+        if (Bun.deepEquals(left, right)) {
+            continue;
+        }
+
+        if (left !== undefined) {
+            setOwn(previous, name, left);
+        }
+
+        if (right !== undefined) {
+            setOwn(next, name, right);
+        }
+
+        changed = true;
+    }
+
+    return { before: previous, after: next, changed };
+}
+
+function comparePropertyItems(current: Frame, pending: Frame[]): void {
+    const { before, after, result } = current;
+
+    for (const name of new Set([
+        ...Object.keys(before.propertyItems),
+        ...Object.keys(after.propertyItems),
+    ])) {
+        const previous = getOwn(before.propertyItems, name);
+        const next = getOwn(after.propertyItems, name);
+
+        if (previous && next) {
+            const origin = itemOrigin(previous);
+
+            if (origin !== undefined && origin !== itemOrigin(next)) {
+                replacePropertyItem(current, name, previous, next);
+                continue;
+            }
+
+            const child = createFrame(previous, next, current.depth + 1);
+            current.properties.push({ name, result: child.result });
+            pending.push(child);
+        } else {
+            if (previous) {
+                result.before.propertyItems ??= {};
+                setOwn(result.before.propertyItems, name, { type: previous.type });
+            }
+
+            if (next) {
+                result.after.propertyItems ??= {};
+                setOwn(result.after.propertyItems, name, next);
+            }
+
+            result.changed = true;
+        }
+    }
+}
+
+function replacePropertyItem(
+    { result }: Frame,
+    name: string,
+    before: ItemNode,
+    after: ItemNode,
+): void {
+    result.before.propertyItems ??= {};
+    result.after.propertyItems ??= {};
+    setOwn(result.before.propertyItems, name, { type: before.type });
+    setOwn(result.after.propertyItems, name, after);
+    result.alignment ??= {};
+    result.alignment.properties ??= {};
+    setOwn(result.alignment.properties, name, { replaceItem: true });
+    result.changed = true;
+}
+
+function assertPreservedOrigin(before: ItemNode, after: ItemNode, location: string): void {
+    const origin = itemOrigin(before);
+
+    if (origin !== undefined && origin !== itemOrigin(after)) {
+        throw new PlatformError(
+            "UnsupportedRequestIdentity",
+            `Replacing the native ${location} requires a qualified DOM replacement profile.`,
+        );
+    }
+}
+
+function compareRelationships(current: Frame, pending: Frame[]): void {
+    const { before, after, result } = current;
+    const previous: RequestNode[] = before.relationships.map((node) => ({ type: node.type }));
+    const next: RequestNode[] = [...after.relationships];
+    const order = relationshipOrder(before.relationships, after.relationships);
+    current.order = order;
+
+    for (const position of order) {
+        const left =
+            position.before === undefined ? undefined : before.relationships[position.before];
+        const right =
+            position.after === undefined ? undefined : after.relationships[position.after];
+
+        if (left && right && position.before !== undefined && position.after !== undefined) {
+            const child = createFrame(left, right, current.depth + 1);
+            current.relationships.push(child.result);
+            previous[position.before] = child.result.before;
+            next[position.after] = child.result.after;
+            pending.push(child);
+        } else {
+            result.changed = true;
+        }
+    }
+
+    result.before.relationships = previous;
+    result.after.relationships = next;
+
+    if (Object.hasOwn(before.propertyAttributes, "Relationships")) {
+        result.before.propertyAttributes ??= {};
+        setOwn(result.before.propertyAttributes, "Relationships", {});
+    }
+
+    if (Object.hasOwn(after.propertyAttributes, "Relationships")) {
+        result.after.propertyAttributes ??= {};
+        setOwn(result.after.propertyAttributes, "Relationships", {});
+    }
+}
+
+function completeFrame(current: Frame): void {
+    const { result } = current;
+
+    for (const child of current.properties) {
+        if (
+            child.result.changed ||
+            Object.hasOwn(result.before.propertyAttributes ?? {}, child.name) ||
+            Object.hasOwn(result.after.propertyAttributes ?? {}, child.name)
+        ) {
+            result.before.propertyItems ??= {};
+            result.after.propertyItems ??= {};
+            setOwn(result.before.propertyItems, child.name, child.result.before);
+            setOwn(result.after.propertyItems, child.name, child.result.after);
+            result.changed = true;
+
+            if (child.result.alignment) {
+                result.alignment ??= {};
+                result.alignment.properties ??= {};
+                setOwn(result.alignment.properties, child.name, child.result.alignment);
+            }
+        }
+    }
+
+    if (
+        current.relationships.some((child) => child.changed) ||
+        current.order?.some((position) => position.before !== position.after)
+    ) {
+        result.changed = true;
+        result.alignment ??= {};
+        let matched = 0;
+        result.alignment.relationships = (current.order ?? []).map((position) => {
+            const child =
+                position.before === undefined || position.after === undefined
+                    ? undefined
+                    : current.relationships[matched++];
+
+            return child?.alignment ? { ...position, alignment: child.alignment } : position;
+        });
+    } else if (current.before.relationships.length === current.after.relationships.length) {
+        delete result.before.relationships;
+        delete result.after.relationships;
+    }
+
+    compactNode(result.before);
+    compactNode(result.after);
+}
+
+function compactNode(node: RequestNode): void {
+    const fields: readonly (
+        | "attributes"
+        | "properties"
+        | "propertyAttributes"
+        | "propertyItems"
+    )[] = ["attributes", "properties", "propertyAttributes", "propertyItems"];
+
+    for (const name of fields) {
+        const values = node[name];
+
+        if (values && Object.keys(values).length === 0) {
+            delete node[name];
+        }
+    }
+
+    if (node.relationships?.length === 0) {
+        delete node.relationships;
+    }
+}