@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/security/time.ts

@@ -0,0 +1,30 @@
+import { dateKey } from "../../queries/date.js";
+import type { StoredItem } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+/** Membership dates use the same UTC and fractional precision rules as native AML date queries. */
+export function effective(record: StoredItem, now: Date): boolean {
+    const start = instant(record.properties.from_date);
+    const end = instant(record.properties.end_date);
+    const current = BigInt(dateKey(now.toISOString()));
+
+    return (start === undefined || start <= current) && (end === undefined || current <= end);
+}
+
+function instant(value: StoredItem["properties"][string] | undefined): bigint | undefined {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+
+    if (typeof value !== "string") {
+        throw new PlatformError("InvalidPermissionDate", "Permission dates must be date text.");
+    }
+
+    try {
+        return BigInt(dateKey(value));
+    } catch (cause) {
+        throw new PlatformError("InvalidPermissionDate", `Invalid permission date '${value}'.`, {
+            cause,
+        });
+    }
+}

package/src/platform/security/types.ts

@@ -0,0 +1,17 @@
+import type { Item } from "../../items/item.js";
+
+export enum AuthorizationMode {
+    Native = "native",
+    Unchecked = "unchecked",
+}
+
+export interface AuthorizationRequest {
+    readonly kind: "action" | "method" | "transition";
+    readonly name: string;
+    readonly item?: Item;
+}
+
+export type AuthorizationPolicy =
+    | AuthorizationMode
+    | "unchecked"
+    | ((request: AuthorizationRequest) => void | Promise<void>);

package/src/platform/trace.ts

@@ -0,0 +1,111 @@
+import { assertActiveContext } from "../core/context.js";
+import { cloneFrozenData } from "../core/data.js";
+import { traceBytesMax, traceEventsMax } from "../core/limits.js";
+import type { ExecutionContext, TransactionOutcome } from "../core/types.js";
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { ItemPayload } from "../items/item.js";
+import type { MockValue } from "../mocks/types.js";
+import type { StoredItem } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+
+export interface SourceDefinition {
+    readonly type: "Method" | "SQL";
+    readonly id: string;
+}
+
+export interface PlatformTraceEvent {
+    readonly sequence: number;
+    readonly requestId: string;
+    readonly executionId: string;
+    readonly parentExecutionId?: string;
+    readonly kind:
+        | "action"
+        | "event"
+        | "method"
+        | "execution"
+        | "result"
+        | "mock"
+        | "mutation"
+        | "seed"
+        | "authorization";
+    readonly name: string;
+    readonly source?: SourceLocation;
+    readonly sourceHash?: string;
+    readonly request?: Readonly<ItemPayload>;
+    readonly result?: Readonly<ItemPayload>;
+    readonly definition?: SourceDefinition;
+    readonly mock?: {
+        readonly definition: string;
+        readonly responseFile?: string;
+        readonly responseHash: string;
+        readonly parameters: Readonly<Record<string, MockValue>>;
+    };
+    readonly before?: StoredItem;
+    readonly after?: StoredItem;
+    readonly outcome?: TransactionOutcome;
+}
+
+export class PlatformTrace {
+    private readonly events: PlatformTraceEvent[] = [];
+    private bytes = 0;
+
+    constructor(private readonly observe?: (event: PlatformTraceEvent) => void) {}
+
+    record(
+        context: ExecutionContext,
+        event: Omit<PlatformTraceEvent, "sequence" | "requestId" | "executionId" | "outcome">,
+    ): void {
+        assertActiveContext(context);
+
+        if (this.events.length >= traceEventsMax) {
+            context.fail(
+                new PlatformError(
+                    "ProtocolLimit",
+                    "The platform trace event limit was reached. Reset the world.",
+                ),
+            );
+        }
+
+        const recorded = cloneFrozenData({
+            ...event,
+            sequence: this.events.length + 1,
+            requestId: context.requestId,
+            executionId: context.executionId,
+            ...(context.parentExecutionId ? { parentExecutionId: context.parentExecutionId } : {}),
+        });
+        const bytes = JSON.stringify(recorded).length * 3;
+
+        if (bytes > traceBytesMax - this.bytes) {
+            context.fail(
+                new PlatformError(
+                    "ProtocolLimit",
+                    "The platform trace byte limit was reached. Reset the world.",
+                ),
+            );
+        }
+
+        this.bytes += bytes;
+        this.events.push(recorded);
+        this.observe?.(recorded);
+    }
+
+    read(
+        outcome: (requestId: string) => TransactionOutcome | undefined,
+    ): readonly PlatformTraceEvent[] {
+        return Object.freeze(
+            this.events.map((event) => {
+                const status = outcome(event.requestId);
+
+                return Object.freeze({
+                    ...event,
+                    ...(status ? { outcome: status } : {}),
+                });
+            }),
+        );
+    }
+
+    reset(): void {
+        this.events.length = 0;
+        this.bytes = 0;
+    }
+}

package/src/platform/unlocking.ts

@@ -0,0 +1,295 @@
+import { assertActiveContext, spendContext } from "../core/context.js";
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import type { ExecutionContext } from "../core/types.js";
+import { Item } from "../items/item.js";
+import { Comparison } from "../queries/types.js";
+import type { Predicate, SelectQuery } from "../queries/types.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import type { RunEvents } from "./events/types.js";
+import { recordKey } from "./references/catalog.js";
+import type { ReferenceCatalog } from "./references/catalog.js";
+import type { PlatformTrace } from "./trace.js";
+import { manualVersioning } from "./version-policy.js";
+
+interface DependentRelationship {
+    readonly relationship: ItemTypeDefinition;
+    readonly related: ItemTypeDefinition;
+}
+
+interface UnlockBatch {
+    readonly definition: ItemTypeDefinition;
+    readonly records: readonly StoredItem[];
+    readonly event: Item;
+    readonly depth: number;
+}
+
+type UnlockTask =
+    | { readonly kind: "enter" | "after"; readonly batch: UnlockBatch }
+    | {
+          readonly kind: "related";
+          readonly parent: StoredItem;
+          readonly relationship: DependentRelationship;
+          readonly depth: number;
+      };
+
+/** Internal version/edit cleanup bypasses replacements while retaining native unlock hooks. */
+export class ItemUnlocks {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly trace: PlatformTrace,
+        private readonly events: RunEvents,
+        private readonly owner: () => string,
+        private readonly catalog: ReferenceCatalog,
+        private readonly select?: SelectQuery,
+    ) {}
+
+    async unlockVersionSources(
+        definition: ItemTypeDefinition,
+        sources: readonly StoredItem[],
+        context: ExecutionContext,
+        request?: Item,
+    ): Promise<void> {
+        const records = sources.filter((record) => Boolean(record.properties.locked_by_id));
+
+        if (records.length === 0) {
+            return;
+        }
+
+        const outgoing = this.relationships(context);
+        const active = new Set<string>();
+        const event = request?.clone() ?? Item.create(definition.name);
+        delete event.node.attributes.where;
+        delete event.node.attributes.idlist;
+        const pending: UnlockTask[] = [
+            {
+                kind: "enter",
+                batch: { definition, records, event, depth: 0 },
+            },
+        ];
+        let visited = 0;
+
+        while (pending.length > 0) {
+            const task = pending.pop();
+
+            if (!task || ++visited > dataNodesMax || pending.length > dataNodesMax) {
+                throw new PlatformError("ProtocolLimit", "Unlocks exceed their graph budget.");
+            }
+
+            spendContext(context);
+
+            if (task.kind === "enter") {
+                await this.enter(task.batch, active, context);
+                pending.push({ kind: "after", batch: task.batch });
+                this.scheduleChildren(task.batch, outgoing, pending, context);
+            } else if (task.kind === "related") {
+                const batch = this.related(task, context);
+
+                if (batch) {
+                    pending.push({ kind: "enter", batch });
+                }
+            } else {
+                await this.after(task.batch, active, context);
+            }
+        }
+    }
+
+    private async enter(
+        batch: UnlockBatch,
+        active: Set<string>,
+        context: ExecutionContext,
+    ): Promise<void> {
+        if (batch.depth > dataDepthMax || active.size + batch.records.length > dataNodesMax) {
+            throw new PlatformError(
+                "ProtocolLimit",
+                "Unlock ownership exceeds its depth or size limit.",
+            );
+        }
+
+        for (const record of batch.records) {
+            const key = recordKey(record);
+
+            if (active.has(key)) {
+                throw new PlatformError("RelationshipCycle", "Unlock ownership contains a cycle.");
+            }
+
+            active.add(key);
+            this.assertOwned(this.current(record));
+        }
+
+        for (const record of batch.records) {
+            batch.event.setProperty("id", record.id);
+            await this.events(batch.definition, "onBeforeUnlock", batch.event, true, context);
+        }
+
+        for (const record of batch.records) {
+            const before = this.current(record);
+            const changes =
+                batch.definition.isVersionable && !manualVersioning(this.storage, batch.definition)
+                    ? { locked_by_id: null, new_version: 0 }
+                    : { locked_by_id: null };
+            assertActiveContext(context);
+            this.storage.updateItem(batch.definition.name, record.id, changes);
+            this.trace.record(context, {
+                kind: "mutation",
+                name: "unlock",
+                before,
+                after: this.current(record),
+            });
+        }
+    }
+
+    private async after(
+        batch: UnlockBatch,
+        active: Set<string>,
+        context: ExecutionContext,
+    ): Promise<void> {
+        for (const record of batch.records) {
+            batch.event.setProperty("id", record.id);
+            await this.events(batch.definition, "onAfterUnlock", batch.event, true, context);
+            active.delete(recordKey(record));
+        }
+    }
+
+    private scheduleChildren(
+        batch: UnlockBatch,
+        outgoing: ReadonlyMap<string, readonly DependentRelationship[]>,
+        pending: UnlockTask[],
+        context: ExecutionContext,
+    ): void {
+        const relationships = outgoing.get(batch.definition.id.toLowerCase()) ?? [];
+
+        for (const parent of [...batch.records].reverse()) {
+            for (const relationship of [...relationships].reverse()) {
+                spendContext(context);
+
+                if (pending.length >= dataNodesMax) {
+                    throw new PlatformError(
+                        "ProtocolLimit",
+                        "Unlocks exceed their work queue limit.",
+                    );
+                }
+
+                pending.push({ kind: "related", parent, relationship, depth: batch.depth + 1 });
+            }
+        }
+    }
+
+    private related(
+        task: Extract<UnlockTask, { kind: "related" }>,
+        context: ExecutionContext,
+    ): UnlockBatch | undefined {
+        const { relationship, related } = task.relationship;
+
+        if (!this.catalog.dependent(related)) {
+            return undefined;
+        }
+
+        const records = new Map<string, StoredItem>();
+        const owner = this.owner().toLowerCase();
+
+        for (const link of this.relationshipRows(relationship, task.parent.id, context)) {
+            spendContext(context);
+            const id = link.properties.related_id;
+            const record =
+                typeof id === "string" ? this.storage.getItem(related.name, id) : undefined;
+
+            if (record && String(record.properties.locked_by_id ?? "").toLowerCase() === owner) {
+                records.set(record.id.toLowerCase(), record);
+            }
+        }
+
+        if (records.size === 0) {
+            return undefined;
+        }
+
+        return {
+            definition: related,
+            records: [...records.values()],
+            event: Item.create(related.name),
+            depth: task.depth,
+        };
+    }
+
+    private relationshipRows(
+        definition: ItemTypeDefinition,
+        sourceId: string,
+        context: ExecutionContext,
+    ): readonly StoredItem[] {
+        const predicate: Predicate = {
+            kind: "compare",
+            field: { name: "source_id", column: "source_id", kind: "identifier", path: [] },
+            operator: Comparison.Equal,
+            value: sourceId,
+        };
+        const candidates = this.select
+            ? this.select(definition.name, predicate, (units) => {
+                  spendContext(context, units);
+              })
+            : this.storage.listItems(definition.name);
+
+        return candidates.filter((record) => {
+            spendContext(context);
+
+            return (
+                String(record.properties.source_id ?? "").toLowerCase() === sourceId.toLowerCase()
+            );
+        });
+    }
+
+    private relationships(
+        context: ExecutionContext,
+    ): ReadonlyMap<string, readonly DependentRelationship[]> {
+        const definitions = this.storage.listItemTypes();
+        spendContext(context, definitions.length);
+        const types = new Map(
+            definitions.map((definition) => [definition.id.toLowerCase(), definition]),
+        );
+        const outgoing = new Map<string, DependentRelationship[]>();
+
+        for (const entry of this.storage.listCatalogEntries("RelationshipType")) {
+            spendContext(context);
+            const source = entry.properties.source_id;
+            const target = entry.properties.related_id;
+
+            if (typeof source !== "string" || !source || typeof target !== "string" || !target) {
+                continue;
+            }
+
+            const related = types.get(target.toLowerCase());
+            const relationship = types.get(String(entry.properties.relationship_id).toLowerCase());
+
+            if (!related || !relationship) {
+                continue;
+            }
+
+            const links = outgoing.get(source.toLowerCase()) ?? [];
+            links.push({ related, relationship });
+            outgoing.set(source.toLowerCase(), links);
+        }
+
+        return outgoing;
+    }
+
+    private current(record: StoredItem): StoredItem {
+        const current = this.storage.getItem(record.type, record.id);
+
+        if (!current) {
+            throw new PlatformError("MissingItem", "An unlock target disappeared in its event.");
+        }
+
+        return current;
+    }
+
+    private assertOwned(record: StoredItem): void {
+        if (
+            String(record.properties.locked_by_id ?? "").toLowerCase() !==
+            this.owner().toLowerCase()
+        ) {
+            throw new PlatformError(
+                "LockOwnership",
+                "An internal unlock requires the current User's lock.",
+            );
+        }
+    }
+}

package/src/platform/values.ts

@@ -0,0 +1,217 @@
+import { getOwn, setOwn } from "../core/data.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    PropertyDefinition,
+    StorageValue,
+    StoredItem,
+} from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import { projectedProperties } from "./query.js";
+
+export interface ItemReference {
+    readonly type: string;
+    readonly id: string;
+    readonly world: symbol;
+    readonly generation: number;
+}
+
+export type SeedValue = StorageValue | ItemReference;
+
+interface NormalizationOptions {
+    readonly creating: boolean;
+    readonly current?: StoredItem;
+    readonly id?: string;
+    readonly pendingReferences?: ReadonlySet<string>;
+}
+
+export function normalizeProperties(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    values: Readonly<Record<string, StorageValue>>,
+    options: NormalizationOptions,
+): Record<string, StorageValue> {
+    const normalized: Record<string, StorageValue> = {};
+    const inputs = { ...values };
+
+    if (options.creating) {
+        for (const property of definition.properties) {
+            if (inputs[property.name] === undefined && property.defaultValue !== undefined) {
+                setOwn(inputs, property.name, property.defaultValue);
+            }
+        }
+    }
+
+    for (const [name, value] of Object.entries(inputs)) {
+        const property = definition.properties.find((property) => property.name === name);
+
+        if (!property) {
+            throw new PlatformError(
+                "UnknownProperty",
+                `Unknown property '${definition.name}.${name}'.`,
+            );
+        }
+
+        if (isUnchangedComputedProperty(storage, definition, property, value, options)) {
+            continue;
+        }
+
+        const converted = normalizeValue(definition, property, value);
+        validateItemReference(storage, definition, property, converted, options);
+
+        if (property.isRequired && (converted === null || converted === "")) {
+            throw new PlatformError(
+                "RequiredProperty",
+                `Required property '${definition.name}.${name}' is missing.`,
+            );
+        }
+
+        setOwn(normalized, name, converted);
+    }
+
+    validateRequiredProperties(definition, normalized, options.creating);
+
+    return normalized;
+}
+
+function normalizeValue(
+    definition: ItemTypeDefinition,
+    property: PropertyDefinition,
+    value: StorageValue,
+): StorageValue {
+    let converted = value;
+
+    if (value === "" && ["integer", "boolean", "float", "decimal"].includes(property.dataType)) {
+        converted = null;
+    }
+
+    if (
+        converted !== null &&
+        typeof converted === "string" &&
+        ["integer", "boolean", "float"].includes(property.dataType)
+    ) {
+        const pattern =
+            property.dataType === "float"
+                ? /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/
+                : /^[+-]?\d+$/;
+
+        if (!pattern.test(converted.trim()) || !Number.isFinite(Number(converted))) {
+            throw new PlatformError(
+                "InvalidValue",
+                `Invalid ${property.dataType} value for '${definition.name}.${property.name}'.`,
+            );
+        }
+
+        converted = Number(converted);
+    }
+
+    return converted;
+}
+
+function validateItemReference(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    property: PropertyDefinition,
+    converted: StorageValue,
+    options: NormalizationOptions,
+): void {
+    if (
+        property.dataType === "item" &&
+        property.dataSource &&
+        converted !== null &&
+        converted !== ""
+    ) {
+        const target = storage
+            .listItemTypes()
+            .find((type) => type.id.toLowerCase() === property.dataSource?.toLowerCase());
+
+        if (!target) {
+            throw new PlatformError(
+                "MissingItemType",
+                `Missing target ItemType '${property.dataSource}' for '${definition.name}.${property.name}'.`,
+            );
+        }
+
+        const self = options.creating && target.id === definition.id && converted === options.id;
+        const familyIdentity = property.name === "config_id" && target.id === definition.id;
+        const pending =
+            typeof converted === "string" &&
+            options.pendingReferences?.has(
+                JSON.stringify([target.name.toLowerCase(), converted.toLowerCase()]),
+            );
+
+        if (
+            !self &&
+            !familyIdentity &&
+            !pending &&
+            (typeof converted !== "string" || !storage.getItem(target.name, converted))
+        ) {
+            throw new PlatformError(
+                "MissingReference",
+                `Missing '${target.name}' record '${converted}' referenced by '${definition.name}.${property.name}'.`,
+            );
+        }
+    }
+}
+
+function isUnchangedComputedProperty(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    property: PropertyDefinition,
+    value: StorageValue,
+    options: NormalizationOptions,
+): boolean {
+    if (property.dataType === "foreign" || property.isFederated) {
+        if (options.current) {
+            const computed = getOwn(
+                projectedProperties(storage, definition, options.current, [property.name]),
+                property.name,
+            );
+
+            if (
+                computed === value ||
+                (computed !== null &&
+                    computed !== undefined &&
+                    value !== null &&
+                    String(computed) === String(value))
+            ) {
+                return true;
+            }
+        }
+
+        throw new PlatformError(
+            "ReadOnlyProperty",
+            `Property '${definition.name}.${property.name}' is computed and cannot be written.`,
+        );
+    }
+
+    return false;
+}
+
+function validateRequiredProperties(
+    definition: ItemTypeDefinition,
+    normalized: Readonly<Record<string, StorageValue>>,
+    creating: boolean,
+): void {
+    if (!creating) {
+        return;
+    }
+
+    for (const property of definition.properties) {
+        if (property.dataType === "foreign" || property.isFederated || property.name === "id") {
+            continue;
+        }
+
+        if (
+            property.isRequired &&
+            (normalized[property.name] === undefined ||
+                normalized[property.name] === null ||
+                normalized[property.name] === "")
+        ) {
+            throw new PlatformError(
+                "RequiredProperty",
+                `Required property '${definition.name}.${property.name}' is missing.`,
+            );
+        }
+    }
+}

package/src/platform/version-policy.ts

@@ -0,0 +1,17 @@
+import type { HarnessStorage, ItemTypeDefinition } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+
+/** Manual versioning never starts a generation implicitly during an ordinary update. */
+export function manualVersioning(storage: HarnessStorage, definition: ItemTypeDefinition): boolean {
+    const metadata = storage.getCatalogEntry("ItemType", definition.id);
+    const value = String(metadata?.properties.manual_versioning ?? "0");
+
+    if (value !== "0" && value !== "1") {
+        throw new PlatformError(
+            "UnsupportedVersioningPolicy",
+            `Unknown manual_versioning '${value}' on '${definition.name}'.`,
+        );
+    }
+
+    return value === "1";
+}