@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/packages/selector.ts

@@ -0,0 +1,104 @@
+import type { StorageValue } from "../storage/types.js";
+import { PackageImportError } from "./diagnostics.js";
+import type { AmlElement } from "./types.js";
+
+export function matchesImportValue(
+    actual: StorageValue | undefined,
+    expected: StorageValue,
+    name: string,
+    dataType: string | undefined,
+): boolean {
+    if (actual === expected) {
+        return true;
+    }
+
+    if (actual === undefined || actual === null || expected === null) {
+        return false;
+    }
+
+    if (dataType === "integer" || dataType === "boolean" || dataType === "float") {
+        const normalizedActual = String(actual).trim();
+        const normalizedExpected = String(expected).trim();
+
+        if (!normalizedActual || !normalizedExpected) {
+            return false;
+        }
+
+        const actualNumber = Number(normalizedActual);
+        const expectedNumber = Number(normalizedExpected);
+
+        return (
+            Number.isFinite(actualNumber) &&
+            Number.isFinite(expectedNumber) &&
+            actualNumber === expectedNumber
+        );
+    }
+
+    if (name === "id" || dataType === "item") {
+        return (
+            typeof actual === "string" &&
+            typeof expected === "string" &&
+            actual.toLowerCase() === expected.toLowerCase()
+        );
+    }
+
+    return false;
+}
+
+export interface EqualityFilter {
+    readonly name: string;
+    readonly value: string;
+}
+
+export function parseWhere(element: AmlElement): readonly EqualityFilter[] {
+    const where = element.attributes.where;
+
+    if (where === undefined) {
+        return [];
+    }
+
+    const filters: EqualityFilter[] = [];
+    let remaining = where.trim();
+
+    while (remaining.length > 0) {
+        const match = /^(?:\[([a-zA-Z_][\w]*)\]|([a-zA-Z_][\w]*))\s*=\s*'((?:[^']|'')*)'\s*/.exec(
+            remaining,
+        );
+
+        if (!match) {
+            break;
+        }
+
+        const name = match[1] ?? match[2];
+        const value = match[3];
+
+        if (!name || value === undefined) {
+            break;
+        }
+
+        filters.push({ name, value: value.replaceAll("''", "'") });
+        remaining = remaining.slice(match[0].length);
+
+        if (remaining.length === 0) {
+            return filters;
+        }
+
+        const conjunction = /^and\s+/i.exec(remaining);
+
+        if (!conjunction) {
+            break;
+        }
+
+        remaining = remaining.slice(conjunction[0].length);
+
+        if (remaining.length === 0) {
+            break;
+        }
+    }
+
+    throw new PackageImportError(
+        "UNSUPPORTED_SELECTOR",
+        "Package selectors support equality to quoted strings joined with AND. Supply an explicit ID for other selectors.",
+        element.source,
+    );
+}

package/src/packages/state.ts

@@ -0,0 +1,82 @@
+import { freezeData } from "../core/data.js";
+import { metadataEpoch } from "../storage/metadata-epoch.js";
+import type { HarnessStorage } from "../storage/types.js";
+import { bootstrapSource } from "./bootstrap.js";
+import { entryKey } from "./draft.js";
+import type { DraftEntry } from "./draft.js";
+
+const baselineViews = new WeakMap<Uint8Array, readonly DraftEntry[]>();
+const activeBaselines = new WeakMap<HarnessStorage, readonly DraftEntry[]>();
+
+/** A freshly restored built-in database has the same initial records in every configured setup. */
+export function withImportBaseline<Result>(
+    storage: HarnessStorage,
+    image: Uint8Array,
+    run: () => Result,
+): Result {
+    if (metadataEpoch(storage) === undefined) {
+        return run();
+    }
+
+    let entries = baselineViews.get(image);
+
+    if (!entries) {
+        entries = freezeData([...readImportState(storage).values()]);
+        baselineViews.set(image, entries);
+    }
+
+    if (activeBaselines.has(storage)) {
+        throw new Error("A built-in import baseline cannot be entered twice.");
+    }
+
+    activeBaselines.set(storage, entries);
+
+    try {
+        return run();
+    } finally {
+        activeBaselines.delete(storage);
+    }
+}
+
+export function readImportState(storage: HarnessStorage): Map<string, DraftEntry> {
+    const entries = new Map<string, DraftEntry>();
+    const initial = activeBaselines.get(storage);
+
+    if (initial) {
+        for (const entry of initial) {
+            entries.set(entryKey(entry.type, entry.id), {
+                ...entry,
+                properties: { ...entry.properties },
+            });
+        }
+
+        return entries;
+    }
+
+    const definitions = storage.listItemTypes();
+    const physicalTypes = new Set(definitions.map((definition) => definition.name.toLowerCase()));
+    const catalog = new Map(
+        storage.listCatalogEntries().map((entry) => [entryKey(entry.type, entry.id), entry]),
+    );
+
+    for (const [key, entry] of catalog) {
+        if (!physicalTypes.has(entry.type.toLowerCase())) {
+            entries.set(key, { ...entry, properties: { ...entry.properties } });
+        }
+    }
+
+    for (const definition of definitions) {
+        for (const item of storage.listItems(definition.name)) {
+            const key = entryKey(item.type, item.id);
+            const metadata = catalog.get(key);
+            entries.set(key, {
+                ...item,
+                properties: { ...item.properties },
+                attributes: metadata?.attributes ?? {},
+                source: metadata?.source ?? bootstrapSource(`/database/${item.type}/${item.id}`),
+            });
+        }
+    }
+
+    return entries;
+}

package/src/packages/types.ts

@@ -0,0 +1,25 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+
+export interface AmlText {
+    readonly kind: "text" | "cdata";
+    readonly value: string;
+}
+
+export interface AmlElement {
+    readonly kind: "element";
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly children: readonly (AmlElement | AmlText)[];
+    readonly source: SourceLocation;
+}
+
+export interface AmlDocument {
+    readonly file: string;
+    readonly sha256: string;
+    readonly xml: string;
+    readonly items: readonly AmlElement[];
+}
+
+export interface PackageSource {
+    readonly path: string;
+}

package/src/platform/action-responses.ts

@@ -0,0 +1,127 @@
+import { spendContext } from "../core/context.js";
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import type { ExecutionContext } from "../core/types.js";
+import { Item, itemNode } from "../items/item.js";
+import type { ItemNode } from "../items/item.js";
+import { ApplicationError, PlatformError } from "./errors.js";
+import type { ApplyQueryItem } from "./queries/planner.js";
+
+const fetchedActions = new Set(["add", "edit", "update", "lock", "unlock"]);
+
+/** Return retrieval is an action phase, distinct from persistence and its mutation hooks. */
+export class ActionResponses {
+    constructor(
+        private readonly apply: ApplyQueryItem,
+        private readonly hasAfterEvents: (type: string) => boolean,
+    ) {}
+
+    prepare(request: ItemNode, context: ExecutionContext): void {
+        if (request.attributes.doGetItem === undefined || request.attributes.doGetItem === "") {
+            request.attributes.doGetItem = "1";
+        }
+
+        const pending = [{ node: request, depth: 0 }];
+        let visited = 0;
+
+        while (pending.length > 0) {
+            spendContext(context);
+            const frame = pending.pop();
+
+            if (!frame || ++visited > dataNodesMax || frame.depth > dataDepthMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Action responses exceed their input limit.",
+                );
+            }
+
+            const node = frame.node;
+
+            if (frame.depth > 0 && !node.attributes.doGetItem) {
+                node.attributes.doGetItem = this.hasAfterEvents(node.type) ? "1" : "0";
+            }
+
+            for (const child of [...Object.values(node.propertyItems), ...node.relationships]) {
+                pending.push({ node: child, depth: frame.depth + 1 });
+            }
+        }
+    }
+
+    async complete(request: ItemNode, response: Item, context: ExecutionContext): Promise<Item> {
+        const action = request.attributes.action ?? "get";
+
+        if (response.isError() || response.payload.result !== undefined) {
+            return response;
+        }
+
+        if (action === "delete") {
+            return new Item({ items: [], result: "Ok" });
+        }
+
+        if (!fetchedActions.has(action)) {
+            return response;
+        }
+
+        if (request.attributes.doGetItem === "0") {
+            if (action === "lock" || action === "unlock") {
+                return new Item({ items: [], result: "Ok." });
+            }
+
+            return new Item({ items: response.payload.items.map(identityNode) });
+        }
+
+        return await this.fetch(request, response, context);
+    }
+
+    private async fetch(
+        request: ItemNode,
+        response: Item,
+        context: ExecutionContext,
+    ): Promise<Item> {
+        const query = Item.create(request.type, "get");
+        const ids = response.payload.items.map((node) => node.attributes.id ?? "");
+
+        if (ids.length === 0 || ids.some((id) => !id)) {
+            throw new PlatformError(
+                "InvalidActionResult",
+                "A default action must retain its target IDs.",
+            );
+        }
+
+        query.setAttribute("idlist", ids.join(","));
+
+        if (request.attributes.select) {
+            query.setAttribute("select", request.attributes.select);
+        }
+
+        const action = request.attributes.action;
+
+        if (request.attributes.serverEvents === "0" && action !== "lock" && action !== "unlock") {
+            query.setAttribute("serverEvents", "0");
+        }
+
+        const result = await this.apply(query, context);
+
+        if (result.isError()) {
+            throw new ApplicationError(result);
+        }
+
+        const positions = new Map(ids.map((id, index) => [id.toLowerCase(), index]));
+        result.payload.items.sort(
+            (left, right) =>
+                (positions.get((left.attributes.id ?? "").toLowerCase()) ?? ids.length) -
+                (positions.get((right.attributes.id ?? "").toLowerCase()) ?? ids.length),
+        );
+
+        return result;
+    }
+}
+
+function identityNode(node: ItemNode): ItemNode {
+    const id = node.attributes.id;
+
+    if (!id) {
+        throw new PlatformError("InvalidActionResult", "A minimal response requires its Item ID.");
+    }
+
+    return { ...itemNode(node.type), attributes: { id } };
+}

package/src/platform/actions.ts

@@ -0,0 +1,11 @@
+export enum ItemAction {
+    Get = "get",
+    Add = "add",
+    Edit = "edit",
+    Update = "update",
+    Delete = "delete",
+    Version = "version",
+    Lock = "lock",
+    Unlock = "unlock",
+    PromoteItem = "promoteItem",
+}

package/src/platform/catalog.ts

@@ -0,0 +1,220 @@
+import { CapabilityId } from "../compatibility/capabilities.js";
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { MethodDefinition } from "../methods/types.js";
+import { presentationTypes } from "../packages/bootstrap.js";
+import { walkElements } from "../packages/elements.js";
+import { parseAml } from "../packages/parser.js";
+import { findDocument } from "../storage/documents.js";
+import { metadataEpoch } from "../storage/metadata-epoch.js";
+import type { CatalogEntry, HarnessStorage, ItemTypeDefinition } from "../storage/types.js";
+import { Classifications } from "./classifications.js";
+import { PlatformError } from "./errors.js";
+import { EventBindings } from "./events/bindings.js";
+import { ServerEventVersion } from "./events/types.js";
+
+const definitionTypes = new Set([
+    "itemtype",
+    "property",
+    "relationshiptype",
+    "morphae",
+    "revision",
+    "method",
+    "sql",
+    "server event",
+    "life cycle map",
+    "life cycle state",
+    "life cycle transition",
+    "itemtype life cycle",
+]);
+
+const sourceLocationsMax = 512;
+const sourceLocations = new Map<string, SourceLocation>();
+
+/** Source coordinates depend on original XML bytes, independently of a world's database. */
+function methodCodeSource(storage: HarnessStorage, original: SourceLocation): SourceLocation {
+    const document = findDocument(storage, original.file);
+
+    if (!document) {
+        return original;
+    }
+
+    const path = `${original.path}/method_code[1]`;
+    const key = JSON.stringify([
+        document.path,
+        new Bun.CryptoHasher("sha256").update(document.xml).digest("hex"),
+        path,
+    ]);
+    const cached = sourceLocations.get(key);
+
+    if (cached) {
+        return cached;
+    }
+
+    for (const element of walkElements(parseAml(document.xml, document.path).items)) {
+        if (element.source.path === path) {
+            if (sourceLocations.size >= sourceLocationsMax) {
+                sourceLocations.clear();
+            }
+
+            const source = Object.freeze({ ...element.source });
+            sourceLocations.set(key, source);
+
+            return source;
+        }
+    }
+
+    return original;
+}
+
+export class PlatformCatalog {
+    readonly classifications: Classifications;
+    private readonly bindings: EventBindings;
+    private epoch: number | undefined;
+    private methods: Map<string, CatalogEntry[]> | undefined;
+    private readonly definitions = new Map<string, MethodDefinition>();
+
+    constructor(private readonly storage: HarnessStorage) {
+        this.classifications = new Classifications(storage);
+        this.bindings = new EventBindings(storage);
+    }
+
+    assertMutable(definition: ItemTypeDefinition): void {
+        if (presentationTypes.has(definition.name)) {
+            throw new PlatformError(
+                "UnsupportedPresentation",
+                `Presentation metadata '${definition.name}' is retained from its package; changing it requires a presentation adapter.`,
+            );
+        }
+
+        if (definitionTypes.has(definition.name.toLowerCase())) {
+            throw new PlatformError(
+                "UnsupportedDefinitionMutation",
+                `Changes to '${definition.name}' definitions must be loaded through packages. Runtime definition mutation is not implemented.`,
+            );
+        }
+    }
+
+    itemType(name: string): ItemTypeDefinition {
+        const definition = this.storage.getItemType(name);
+
+        if (!definition) {
+            const metadata = this.storage
+                .listCatalogEntries("ItemType")
+                .find(
+                    (entry) => String(entry.properties.name).toLowerCase() === name.toLowerCase(),
+                );
+
+            if (metadata && metadata.properties.implementation_type !== "table") {
+                throw new PlatformError(
+                    "UnsupportedImplementation",
+                    `ItemType '${name}' uses '${metadata.properties.implementation_type}' storage and requires an adapter. Its metadata is available through ItemType queries.`,
+                    {
+                        capability:
+                            String(metadata.properties.implementation_type).toLowerCase() ===
+                            "polymorphic"
+                                ? CapabilityId.Polymorphism
+                                : CapabilityId.Federation,
+                    },
+                );
+            }
+
+            throw new PlatformError("MissingItemType", `ItemType '${name}' has not been imported.`);
+        }
+
+        return definition;
+    }
+
+    methodEntry(nameOrId: string) {
+        this.refreshMethods();
+        const candidates = this.methods?.get(nameOrId.toLowerCase()) ?? [];
+        const current = candidates.filter(
+            (entry) => entry.properties.is_current !== 0 && entry.properties.is_current !== "0",
+        );
+
+        if (current.length > 1) {
+            throw new PlatformError(
+                "MethodResolution",
+                `Method '${nameOrId}' resolved to ${current.length} current definitions.`,
+            );
+        }
+
+        return current[0];
+    }
+
+    private refreshMethods(): void {
+        const epoch = metadataEpoch(this.storage);
+
+        if (epoch !== undefined && this.methods && this.epoch === epoch) {
+            return;
+        }
+
+        this.epoch = epoch;
+        this.methods = new Map();
+        this.definitions.clear();
+
+        for (const entry of this.storage.listCatalogEntries("Method")) {
+            const keys = new Set([entry.id, entry.properties.name, entry.properties.config_id]);
+
+            for (const key of keys) {
+                if (typeof key !== "string") {
+                    continue;
+                }
+
+                const normalized = key.toLowerCase();
+                const entries = this.methods.get(normalized) ?? [];
+
+                if (!entries.includes(entry)) {
+                    entries.push(entry);
+                }
+
+                this.methods.set(normalized, entries);
+            }
+        }
+    }
+
+    method(nameOrId: string): MethodDefinition {
+        const method = this.methodEntry(nameOrId);
+
+        if (!method) {
+            throw new PlatformError("MethodResolution", `Missing Method '${nameOrId}'.`);
+        }
+
+        const cached = this.definitions.get(method.id);
+
+        if (cached) {
+            return cached;
+        }
+
+        const name = method.properties.name;
+        const language = method.properties.method_type;
+        const code = method.properties.method_code;
+
+        if (typeof name !== "string" || typeof language !== "string" || typeof code !== "string") {
+            throw new PlatformError(
+                "InvalidMethod",
+                `Method '${nameOrId}' is missing its name, language or source.`,
+            );
+        }
+
+        const definition = Object.freeze({
+            id: method.id,
+            name,
+            language,
+            code,
+            source: Object.freeze({ ...methodCodeSource(this.storage, method.source) }),
+            hash: new Bun.CryptoHasher("sha256").update(code).digest("hex"),
+        });
+        this.definitions.set(method.id, definition);
+
+        return definition;
+    }
+
+    events(
+        definition: ItemTypeDefinition,
+        name: string,
+        enabled = true,
+        version = ServerEventVersion.Item,
+    ) {
+        return this.bindings.select(definition, name, enabled, version);
+    }
+}