@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/errors.ts

@@ -0,0 +1,39 @@
+import { capabilityForError } from "../compatibility/capabilities.js";
+import type { CapabilityId } from "../compatibility/capabilities.js";
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { Item } from "../items/item.js";
+
+export class PlatformError extends Error {
+    override readonly name = "PlatformError";
+    readonly capability: CapabilityId | undefined;
+    readonly source: SourceLocation | undefined;
+
+    constructor(
+        readonly code: string,
+        message: string,
+        options?: ErrorOptions & {
+            readonly capability?: CapabilityId;
+            readonly source?: SourceLocation;
+        },
+    ) {
+        super(message, options);
+        this.capability = options?.capability ?? capabilityForError(code);
+        this.source = options?.source;
+    }
+}
+
+export class ApplicationError extends Error {
+    override readonly name = "ApplicationError";
+
+    constructor(readonly item: Item) {
+        super(item.getErrorString());
+    }
+}
+
+export function requireSuccess(item: Item): Item {
+    if (item.isError() && item.getErrorCode() !== "0") {
+        throw new ApplicationError(item);
+    }
+
+    return item;
+}

package/src/platform/events/after.ts

@@ -0,0 +1,149 @@
+import { spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import { MethodEventDataKind } from "../../methods/event-data.js";
+import type { MethodEventData } from "../../methods/event-data.js";
+import type { ItemTypeDefinition } from "../../storage/types.js";
+import { PlatformError, requireSuccess } from "../errors.js";
+import type { ApplyQueryItem } from "../queries/planner.js";
+import { ServerEventVersion } from "./types.js";
+import type { AfterEventItem, EventBinding } from "./types.js";
+
+type SelectEvents = (
+    definition: ItemTypeDefinition,
+    name: string,
+    enabled: boolean,
+    version: ServerEventVersion,
+) => readonly EventBinding[];
+
+type InvokeEvent = (
+    binding: EventBinding,
+    name: string,
+    item: Item,
+    context: ExecutionContext,
+    data: MethodEventData,
+) => Promise<void>;
+
+interface AfterSelection {
+    readonly bindings: readonly EventBinding[];
+    readonly needsItems: boolean;
+}
+
+/** After-event documents are loaded once and shared between bindings, independently of results. */
+export class AfterEvents {
+    constructor(
+        private readonly select: SelectEvents,
+        private readonly invoke: InvokeEvent,
+        private readonly apply: ApplyQueryItem,
+    ) {}
+
+    async run(
+        definition: ItemTypeDefinition,
+        name: string,
+        frames: readonly AfterEventItem[],
+        enabled: boolean,
+        context: ExecutionContext,
+    ): Promise<void> {
+        spendContext(context, frames.length);
+        const { bindings, needsItems } = this.selection(definition, name, enabled);
+
+        if (frames.length === 0 || (bindings.length === 0 && !needsItems)) {
+            return;
+        }
+
+        const items = needsItems
+            ? await this.load(definition, frames, enabled || name === "onAfterAdd", context)
+            : new Map<string, Item>();
+
+        for (const binding of bindings) {
+            spendContext(context);
+
+            if (binding.version === ServerEventVersion.Collection) {
+                const first = frames[0];
+
+                if (!first) {
+                    throw new Error("A nonempty after-event batch must retain its first frame.");
+                }
+
+                const data = this.batchData(first.data, needsItems);
+                await this.invoke(binding, name, Item.create(""), context, data);
+
+                continue;
+            }
+
+            for (const frame of frames) {
+                const item = items.get(frame.id.toLowerCase());
+
+                if (!item) {
+                    throw new PlatformError("MissingItem", "An after-event context is missing.");
+                }
+
+                await this.invoke(binding, name, item, context, frame.data);
+            }
+        }
+    }
+
+    private selection(
+        definition: ItemTypeDefinition,
+        name: string,
+        enabled: boolean,
+    ): AfterSelection {
+        const itemBindings = this.select(definition, name, enabled, ServerEventVersion.Item);
+        const bindings = [
+            ...itemBindings,
+            ...this.select(definition, name, enabled, ServerEventVersion.Collection),
+        ].sort(
+            (left, right) =>
+                Number(left.entry.properties.sort_order ?? 0) -
+                Number(right.entry.properties.sort_order ?? 0),
+        );
+        // Native after-update prepares its contexts before optional bindings are suppressed.
+        const needsItems =
+            itemBindings.length > 0 ||
+            (name === "onAfterUpdate" &&
+                !enabled &&
+                this.select(definition, name, true, ServerEventVersion.Item).length > 0);
+
+        return { bindings, needsItems };
+    }
+
+    private async load(
+        definition: ItemTypeDefinition,
+        frames: readonly AfterEventItem[],
+        enabled: boolean,
+        context: ExecutionContext,
+    ): Promise<ReadonlyMap<string, Item>> {
+        const request = Item.create(definition.name, "get");
+        request.setAttribute("idlist", frames.map((frame) => frame.id).join(","));
+        request.setAttribute("serverEvents", enabled ? "1" : "0");
+        const result = requireSuccess(await this.apply(request, context));
+        const items = new Map(
+            result.payload.items.map((node) => [
+                (node.attributes.id ?? "").toLowerCase(),
+                new Item({ items: [node] }),
+            ]),
+        );
+
+        if (result.isError() || frames.some((frame) => !items.has(frame.id.toLowerCase()))) {
+            throw new PlatformError("MissingItem", "An after-event Get omitted a required Item.");
+        }
+
+        return items;
+    }
+
+    private batchData(data: MethodEventData, hasItemBindings: boolean): MethodEventData {
+        if (hasItemBindings) {
+            return data;
+        }
+
+        if (data.kind === MethodEventDataKind.AfterVersion) {
+            return { ...data, newItemId: "" };
+        }
+
+        if (data.kind === MethodEventDataKind.AfterUpdate) {
+            return { ...data, id: null };
+        }
+
+        return data;
+    }
+}

package/src/platform/events/base-updates.ts

@@ -0,0 +1,68 @@
+import { assertActiveContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { Item, ItemNode } from "../../items/item.js";
+import { PlatformError } from "../errors.js";
+
+interface CapturedMutation {
+    readonly ids: readonly string[];
+    readonly enabled: boolean;
+    readonly fetch: boolean;
+}
+
+/** Target selection and execution flags survive changes to replacement-owned XML. */
+export class BaseUpdates {
+    private readonly active = new WeakMap<Item, CapturedMutation>();
+
+    enter(
+        item: Item,
+        id: string,
+        attributes: Readonly<Record<string, string>>,
+        context: ExecutionContext,
+    ): Disposable {
+        assertActiveContext(context);
+
+        if (this.active.has(item)) {
+            throw new PlatformError(
+                "InvalidServerEvent",
+                "Overlapping base updates cannot share the same pending input.",
+            );
+        }
+
+        this.active.set(item, {
+            ids: [id],
+            enabled: attributes.serverEvents !== "0",
+            fetch: attributes.doGetItem !== "0",
+        });
+
+        return {
+            [Symbol.dispose]: () => {
+                this.active.delete(item);
+            },
+        };
+    }
+
+    targets(item: Item): readonly string[] | undefined {
+        return this.active.get(item)?.ids;
+    }
+
+    enabled(item: Item): boolean | undefined {
+        return this.active.get(item)?.enabled;
+    }
+
+    response(item: Item): ItemNode {
+        const captured = this.active.get(item);
+
+        if (!captured) {
+            return item.node;
+        }
+
+        return {
+            ...item.node,
+            attributes: {
+                ...item.node.attributes,
+                serverEvents: captured.enabled ? "1" : "0",
+                doGetItem: captured.fetch ? "1" : "0",
+            },
+        };
+    }
+}

package/src/platform/events/bindings.ts

@@ -0,0 +1,129 @@
+import { metadataEpoch } from "../../storage/metadata-epoch.js";
+import type { HarnessStorage, ItemTypeDefinition } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { eventOwners } from "./inheritance.js";
+import { ServerEventVersion } from "./types.js";
+import type { EventBinding } from "./types.js";
+import { eventVersion } from "./version.js";
+
+export class EventBindings {
+    private epoch: number | undefined;
+    private readonly selections = new Map<string, readonly EventBinding[]>();
+
+    constructor(private readonly storage: HarnessStorage) {}
+
+    select(
+        definition: ItemTypeDefinition,
+        name: string,
+        enabled = true,
+        version = ServerEventVersion.Item,
+    ): readonly EventBinding[] {
+        const epoch = metadataEpoch(this.storage);
+
+        if (epoch === undefined || this.epoch !== epoch) {
+            this.selections.clear();
+            this.epoch = epoch;
+        }
+
+        const key = JSON.stringify([
+            definition.id.toLowerCase(),
+            name.toLowerCase(),
+            enabled,
+            version,
+        ]);
+        const cached = this.selections.get(key);
+
+        if (cached) {
+            return cached;
+        }
+
+        const bindings = this.collect(definition, name, enabled, version);
+
+        if (epoch !== undefined) {
+            this.selections.set(key, bindings);
+        }
+
+        return bindings;
+    }
+
+    private collect(
+        definition: ItemTypeDefinition,
+        name: string,
+        enabled: boolean,
+        version: ServerEventVersion,
+    ): readonly EventBinding[] {
+        const owners = eventOwners(this.storage, definition.id);
+        const bindings: EventBinding[] = [];
+
+        for (const entry of this.storage.listCatalogEntries("Server Event")) {
+            const properties = entry.properties;
+            const required = String(properties.is_required ?? "0") === "1";
+
+            if (
+                !owners.has(String(properties.source_id).toLowerCase()) ||
+                String(properties.server_event).toLowerCase() !== name.toLowerCase() ||
+                (!enabled && !required)
+            ) {
+                continue;
+            }
+
+            const declared = eventVersion(name, properties.event_version, entry.source);
+
+            if (declared !== version) {
+                continue;
+            }
+
+            const methodId = properties.related_id;
+
+            if (
+                typeof methodId !== "string" ||
+                !Number.isSafeInteger(Number(properties.sort_order ?? 0))
+            ) {
+                throw new PlatformError(
+                    "InvalidEvent",
+                    `Event '${entry.id}' needs a Method and a safe integer sort order.`,
+                    { source: entry.source },
+                );
+            }
+
+            bindings.push({ entry, methodId, required, version: declared });
+        }
+
+        bindings.sort(
+            (left, right) =>
+                Number(left.entry.properties.sort_order ?? 0) -
+                Number(right.entry.properties.sort_order ?? 0),
+        );
+        this.assertOrder(definition, name, bindings);
+
+        return Object.freeze(bindings);
+    }
+
+    private assertOrder(
+        definition: ItemTypeDefinition,
+        name: string,
+        bindings: readonly EventBinding[],
+    ): void {
+        for (let index = 1; index < bindings.length; index += 1) {
+            const previous = bindings[index - 1];
+            const current = bindings[index];
+
+            if (!previous || !current) {
+                throw new Error(
+                    "Adjacent event bindings must exist before their collection boundary.",
+                );
+            }
+
+            if (
+                Number(previous.entry.properties.sort_order ?? 0) ===
+                Number(current.entry.properties.sort_order ?? 0)
+            ) {
+                throw new PlatformError(
+                    "AmbiguousEventOrder",
+                    `Events for '${definition.name}.${name}' have the same sort order within '${current.version}'.`,
+                    { source: current.entry.source },
+                );
+            }
+        }
+    }
+}

package/src/platform/events/data.ts

@@ -0,0 +1,26 @@
+import { MethodEventDataKind } from "../../methods/event-data.js";
+import type { AfterEventItem } from "./types.js";
+
+export function afterAddFrames(typeId: string, id: string): readonly AfterEventItem[] {
+    return [{ id, data: { kind: MethodEventDataKind.AfterAdd, typeId, id, idList: [id] } }];
+}
+
+export function afterUpdateFrames(
+    typeId: string,
+    oldIdsNewIdsMap: Readonly<Record<string, string>>,
+): readonly AfterEventItem[] {
+    return Object.values(oldIdsNewIdsMap).map((id) => ({
+        id,
+        data: { kind: MethodEventDataKind.AfterUpdate, typeId, id, oldIdsNewIdsMap },
+    }));
+}
+
+export function afterVersionFrames(
+    typeId: string,
+    oldIdsNewIdsMap: Readonly<Record<string, string>>,
+): readonly AfterEventItem[] {
+    return Object.entries(oldIdsNewIdsMap).map(([id, newItemId]) => ({
+        id,
+        data: { kind: MethodEventDataKind.AfterVersion, typeId, newItemId, oldIdsNewIdsMap },
+    }));
+}

package/src/platform/events/inheritance.ts

@@ -0,0 +1,98 @@
+import { dataDepthMax, dataNodesMax } from "../../core/limits.js";
+import type { SourceLocation } from "../../diagnostics/source-location.js";
+import type { HarnessStorage } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+interface Parent {
+    readonly id: string;
+    readonly source: SourceLocation;
+}
+
+interface Frame {
+    readonly id: string;
+    readonly depth: number;
+    readonly exit: boolean;
+    readonly source?: SourceLocation;
+}
+
+/** Morphae inheritance affects event dispatch without requiring polymorphic record storage. */
+export function eventOwners(storage: HarnessStorage, typeId: string): ReadonlySet<string> {
+    const parents = parentBindings(storage);
+    const owners = new Set<string>();
+    const active = new Set<string>();
+    const pending: Frame[] = [{ id: typeId.toLowerCase(), depth: 0, exit: false }];
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame || frame.depth > dataDepthMax || ++visited > dataNodesMax) {
+            throw new PlatformError("ProtocolLimit", "Event inheritance exceeds its graph budget.");
+        }
+
+        if (frame.exit) {
+            active.delete(frame.id);
+            continue;
+        }
+
+        if (active.has(frame.id)) {
+            throw new PlatformError(
+                "EventInheritanceCycle",
+                `Cyclic Morphae inheritance at '${frame.id}'.`,
+                frame.source ? { source: frame.source } : undefined,
+            );
+        }
+
+        if (owners.has(frame.id)) {
+            continue;
+        }
+
+        owners.add(frame.id);
+        active.add(frame.id);
+        pending.push({ ...frame, exit: true });
+
+        for (const parent of parents.get(frame.id) ?? []) {
+            if (pending.length >= dataNodesMax) {
+                throw new PlatformError("ProtocolLimit", "Event inheritance queue is too large.");
+            }
+
+            pending.push({ ...parent, depth: frame.depth + 1, exit: false });
+        }
+    }
+
+    return owners;
+}
+
+function parentBindings(storage: HarnessStorage): ReadonlyMap<string, readonly Parent[]> {
+    const parents = new Map<string, Parent[]>();
+
+    for (const entry of storage.listCatalogEntries("Morphae")) {
+        const owner = entry.properties.source_id;
+        const related = entry.properties.related_id;
+
+        if (typeof owner !== "string" || typeof related !== "string") {
+            throw new PlatformError(
+                "InvalidEventInheritance",
+                "Morphae requires source and related ItemTypes.",
+                { source: entry.source },
+            );
+        }
+
+        const metadata = storage.getCatalogEntry("ItemType", owner);
+
+        if (String(metadata?.properties.implementation_type).toLowerCase() !== "polymorphic") {
+            throw new PlatformError(
+                "InvalidEventInheritance",
+                "Morphae must be owned by a polymorphic ItemType.",
+                { source: entry.source },
+            );
+        }
+
+        const key = related.toLowerCase();
+        const values = parents.get(key) ?? [];
+        values.push({ id: owner.toLowerCase(), source: entry.source });
+        parents.set(key, values);
+    }
+
+    return parents;
+}

package/src/platform/events/input.ts

@@ -0,0 +1,12 @@
+import type { Item } from "../../items/item.js";
+
+const documents = new WeakMap<Item, Item>();
+
+/** A base action can hold an older request while callbacks receive its current document. */
+export function bindRequestDocument(request: Item, document: Item): void {
+    documents.set(request, document);
+}
+
+export function requestDocument(request: Item): Item {
+    return documents.get(request) ?? request;
+}

package/src/platform/events/replacement.ts

@@ -0,0 +1,109 @@
+import { assertActiveContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { Item } from "../../items/item.js";
+import type { MethodServerEvent } from "../../methods/types.js";
+import { PlatformError } from "../errors.js";
+import type { EventBinding } from "./types.js";
+
+export type ApplyEventBase = (request: Item, context: ExecutionContext) => Promise<Item>;
+
+interface Frame {
+    readonly owner: ExecutionContext;
+    readonly binding: EventBinding;
+    readonly name: string;
+    readonly type: string;
+    readonly action: string;
+    readonly apply: ApplyEventBase;
+}
+
+/** A base delegate belongs to one replacement invocation, never to nested ordinary Methods. */
+export class EventReplacements {
+    private readonly frames = new Map<string, Frame>();
+
+    async invoke(
+        binding: EventBinding,
+        name: string,
+        item: Item,
+        context: ExecutionContext,
+        apply: ApplyEventBase,
+        execute: () => Promise<Item>,
+    ): Promise<Item> {
+        const key = this.key(context.requestId, context.executionId);
+
+        if (this.frames.has(key)) {
+            throw new PlatformError("InvalidServerEvent", "Replacement frames cannot overlap.");
+        }
+
+        this.frames.set(key, {
+            owner: context,
+            binding,
+            name,
+            type: item.getType(),
+            action: item.getAction(),
+            apply,
+        });
+
+        try {
+            return await execute();
+        } finally {
+            this.frames.delete(key);
+        }
+    }
+
+    scope(
+        methodId: string,
+        context: ExecutionContext,
+    ): (MethodServerEvent & Disposable) | undefined {
+        const key = this.key(context.requestId, context.parentExecutionId ?? "");
+        const frame = this.frames.get(key);
+
+        if (!frame || frame.binding.methodId.toLowerCase() !== methodId.toLowerCase()) {
+            return undefined;
+        }
+
+        let closed = false;
+
+        return {
+            name: frame.name,
+
+            applyBase: (request) => {
+                assertActiveContext(context);
+
+                if (closed || this.frames.get(key) !== frame) {
+                    throw new PlatformError(
+                        "ExpiredServerEvent",
+                        "The replacement event has completed.",
+                    );
+                }
+
+                assertActiveContext(frame.owner);
+                this.assertRequest(frame, request, context);
+
+                return frame.apply(request, context);
+            },
+
+            [Symbol.dispose]: () => {
+                closed = true;
+            },
+        };
+    }
+
+    private key(requestId: string, executionId: string): string {
+        return JSON.stringify([requestId, executionId]);
+    }
+
+    private assertRequest(frame: Frame, request: Item, context: ExecutionContext): void {
+        if (
+            request.getItemCount() !== 1 ||
+            request.getType().toLowerCase() !== frame.type.toLowerCase() ||
+            request.getAction() !== frame.action
+        ) {
+            context.fail(
+                new PlatformError(
+                    "InvalidServerEventContext",
+                    "A base action must retain the replacement ItemType and action.",
+                ),
+            );
+        }
+    }
+}

package/src/platform/events/types.ts

@@ -0,0 +1,56 @@
+import type { ExecutionContext } from "../../core/types.js";
+import type { Item } from "../../items/item.js";
+import type { MethodEventData } from "../../methods/event-data.js";
+import type { CatalogEntry, ItemTypeDefinition } from "../../storage/types.js";
+
+export enum ServerEventVersion {
+    Item = "version_1",
+    Collection = "version_2",
+}
+
+export interface EventBinding {
+    readonly entry: CatalogEntry;
+    readonly methodId: string;
+    readonly required: boolean;
+    readonly version: ServerEventVersion;
+}
+
+export type RunEvents = (
+    definition: ItemTypeDefinition,
+    name: string,
+    item: Item,
+    enabled: boolean,
+    context: ExecutionContext,
+    data?: MethodEventData,
+) => Promise<void>;
+
+export interface AfterEventItem {
+    readonly id: string;
+    readonly data: MethodEventData;
+}
+
+export type RunAfterEvents = (
+    definition: ItemTypeDefinition,
+    name: string,
+    items: readonly AfterEventItem[],
+    enabled: boolean,
+    context: ExecutionContext,
+) => Promise<void>;
+
+export interface UpdateResult {
+    readonly response: Item;
+    readonly completed: boolean;
+}
+
+export type ApplyUpdateBase = (request: Item, context: ExecutionContext) => Promise<UpdateResult>;
+
+export interface EventRunners {
+    readonly item: RunEvents;
+    readonly after: RunAfterEvents;
+    readonly update: (
+        definition: ItemTypeDefinition,
+        request: Item,
+        context: ExecutionContext,
+        applyBase: ApplyUpdateBase,
+    ) => Promise<Item>;
+}