@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/relationship-copy.ts

@@ -0,0 +1,218 @@
+import { assertActiveContext, spendContext } from "../core/context.js";
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import type { ExecutionContext } from "../core/types.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import { relationshipKey } from "./graph-actions.js";
+import type { LifeCycles } from "./lifecycle.js";
+import { recordKey } from "./references/catalog.js";
+import type { ReferenceMaintenance } from "./references/maintenance.js";
+import { VersionCopyPolicy } from "./relationship-copy-policy.js";
+import { isReleased } from "./revisions/policy.js";
+import type { NativeSecurity } from "./security/policy.js";
+import type { PlatformTrace } from "./trace.js";
+import { manualVersioning } from "./version-policy.js";
+
+interface CopyGroup {
+    readonly definition: ItemTypeDefinition;
+    readonly records: StoredItem[];
+    readonly parentId: string;
+    readonly depth: number;
+    readonly resetBehavior: boolean;
+}
+
+type CopyTask =
+    | {
+          readonly kind: "owner";
+          readonly source: StoredItem;
+          readonly targetId: string;
+          readonly depth: number;
+          readonly resetBehavior: boolean;
+      }
+    | { readonly kind: "leave"; readonly key: string }
+    | { readonly kind: "group"; readonly group: CopyGroup };
+
+/** Parent versions copy stored relationships without invoking business copy or mutation hooks. */
+export class RelationshipCopy {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly trace: PlatformTrace,
+        private readonly nextId: () => string,
+        private readonly references: ReferenceMaintenance,
+        private readonly security: NativeSecurity,
+        private readonly lifeCycles: LifeCycles,
+    ) {}
+
+    copy(
+        source: StoredItem,
+        target: StoredItem,
+        copies: Map<string, string>,
+        context: ExecutionContext,
+    ): void {
+        let policy: VersionCopyPolicy | undefined;
+        const pending: CopyTask[] = [
+            {
+                kind: "owner",
+                source,
+                targetId: target.id,
+                depth: 0,
+                resetBehavior: isReleased(source),
+            },
+        ];
+        const active = new Set<string>();
+        const created: StoredItem[] = [];
+        let visited = 0;
+
+        while (pending.length > 0) {
+            const task = pending.pop();
+
+            if (!task || ++visited > dataNodesMax || pending.length > dataNodesMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Relationship copies exceed their graph budget.",
+                );
+            }
+
+            spendContext(context);
+
+            if (task.kind === "leave") {
+                active.delete(task.key);
+            } else if (task.kind === "owner") {
+                this.enter(task, pending, active, context);
+            } else {
+                policy ??= new VersionCopyPolicy(this.storage);
+                this.copyGroup(task.group, copies, pending, policy, created, context);
+            }
+        }
+
+        this.lifeCycles.resetCopies(created, context);
+    }
+
+    private enter(
+        task: Extract<CopyTask, { kind: "owner" }>,
+        pending: CopyTask[],
+        active: Set<string>,
+        context: ExecutionContext,
+    ): void {
+        const key = recordKey(task.source);
+
+        if (active.has(key) || task.depth > dataDepthMax) {
+            throw new PlatformError(
+                "RelationshipCycle",
+                "Relationship ownership is cyclic or too deep to copy.",
+            );
+        }
+
+        active.add(key);
+        pending.push({ kind: "leave", key });
+        const groups = new Map<string, CopyGroup>();
+
+        for (const record of this.references.catalog.owned(task.source, context)) {
+            const definition = this.storage.getItemType(record.type);
+
+            if (!definition) {
+                throw new PlatformError(
+                    "MissingItemType",
+                    `Relationship '${record.type}' has no schema.`,
+                );
+            }
+
+            if (
+                definition.isVersionable &&
+                this.references.catalog.current(record).id !== record.id
+            ) {
+                continue;
+            }
+
+            const group = groups.get(definition.id) ?? {
+                definition,
+                records: [],
+                parentId: task.targetId,
+                depth: task.depth,
+                resetBehavior: task.resetBehavior,
+            };
+            group.records.push(record);
+            groups.set(definition.id, group);
+        }
+
+        for (const group of [...groups.values()].reverse()) {
+            pending.push({ kind: "group", group });
+        }
+    }
+
+    private copyGroup(
+        group: CopyGroup,
+        copies: Map<string, string>,
+        pending: CopyTask[],
+        policy: VersionCopyPolicy,
+        created: StoredItem[],
+        context: ExecutionContext,
+    ): void {
+        policy.assertSupported(group.definition, group.records);
+        const records: StoredItem[] = [];
+
+        for (const source of group.records) {
+            spendContext(context);
+            const copied = this.insert(group, source, context);
+            copies.set(relationshipKey(source.type, source.id), copied.id);
+            records.push(copied);
+            created.push(copied);
+        }
+
+        for (let index = records.length - 1; index >= 0; index -= 1) {
+            const source = group.records[index];
+            const target = records[index];
+
+            if (!source || !target) {
+                throw new Error("Each copied relationship must retain its source pairing.");
+            }
+
+            pending.push({
+                kind: "owner",
+                source,
+                targetId: target.id,
+                depth: group.depth + 1,
+                resetBehavior: group.resetBehavior,
+            });
+        }
+    }
+
+    private insert(group: CopyGroup, source: StoredItem, context: ExecutionContext): StoredItem {
+        const id = this.nextId();
+        const properties = this.references.copied(
+            group.definition,
+            source,
+            group.parentId,
+            group.resetBehavior,
+        );
+        const record: StoredItem = {
+            type: group.definition.name,
+            id,
+            properties: {
+                ...properties,
+                ...this.security.copied(group.definition, properties, context),
+                config_id: id,
+                generation: 1,
+                is_current: 1,
+                new_version:
+                    group.definition.isVersionable &&
+                    !manualVersioning(this.storage, group.definition)
+                        ? 0
+                        : 1,
+                locked_by_id: null,
+            },
+        };
+        assertActiveContext(context);
+        this.storage.insertItem(record);
+        this.references.sessions.created(record, context);
+        this.trace.record(context, {
+            kind: "mutation",
+            name: "copy",
+            before: source,
+            after: record,
+        });
+        this.references.freeze(source, context);
+
+        return record;
+    }
+}

package/src/platform/relationship-type.ts

@@ -0,0 +1,23 @@
+import type { HarnessStorage, ItemTypeDefinition } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+
+export function relationshipType(
+    storage: HarnessStorage,
+    parent: ItemTypeDefinition,
+    type: string,
+): ItemTypeDefinition {
+    const definition = storage.getItemType(type);
+    const source = definition?.properties.find((property) => property.name === "source_id");
+
+    if (
+        !definition?.isRelationship ||
+        source?.dataSource?.toLowerCase() !== parent.id.toLowerCase()
+    ) {
+        throw new PlatformError(
+            "RelationshipSource",
+            `'${type}' is not an imported relationship of '${parent.name}'.`,
+        );
+    }
+
+    return definition;
+}

package/src/platform/request.ts

@@ -0,0 +1,139 @@
+import { setOwn } from "../core/data.js";
+import { Item } from "../items/item.js";
+import type { ItemNode } from "../items/item.js";
+import { PlatformError } from "./errors.js";
+
+const attributes = new Set([
+    "id",
+    "action",
+    "select",
+    "orderBy",
+    "where",
+    "serverEvents",
+    "version",
+    "idlist",
+    "page",
+    "pagesize",
+    "maxRecords",
+    "isCriteria",
+    "isNew",
+    "isTemp",
+    "doGetItem",
+]);
+
+/** Action instrumentation must also recognize trusted delegation to a native base action. */
+export function appliedItem(operation: string, input: unknown): Item | undefined {
+    if (operation === "platform.apply" && input instanceof Item) {
+        return input;
+    }
+
+    if (operation !== "platform.event-base" || input === null || typeof input !== "object") {
+        return undefined;
+    }
+
+    const item: unknown = Object.getOwnPropertyDescriptor(input, "item")?.value;
+
+    return item instanceof Item ? item : undefined;
+}
+
+/** Validate again after before events, which may change the request. */
+export function validateRequest(request: ItemNode, action: string): void {
+    for (const [name, attributes] of Object.entries(request.propertyAttributes)) {
+        if (
+            action !== "get" &&
+            attributes.condition !== undefined &&
+            attributes.condition !== "eq"
+        ) {
+            throw new PlatformError(
+                "UnsupportedCondition",
+                `Property condition '${attributes.condition}' on '${name}' is not implemented.`,
+            );
+        }
+
+        if (attributes.is_null === "1") {
+            setOwn(request.properties, name, null);
+        }
+    }
+
+    validateCriteria(request, action);
+
+    for (const key of Object.keys(request.attributes)) {
+        if (!attributes.has(key)) {
+            throw new PlatformError(
+                "UnsupportedAttribute",
+                `AML attribute '${key}' is not implemented.`,
+            );
+        }
+    }
+
+    if (
+        request.attributes.serverEvents !== undefined &&
+        !["0", "1"].includes(request.attributes.serverEvents)
+    ) {
+        throw new PlatformError("InvalidServerEvents", "serverEvents must be '0' or '1'.");
+    }
+
+    if (
+        request.attributes.version !== undefined &&
+        (!["edit", "update"].includes(action) || !["0", "1"].includes(request.attributes.version))
+    ) {
+        throw new PlatformError(
+            "InvalidVersion",
+            "version must be '0' or '1' on an edit or update request.",
+        );
+    }
+
+    if (
+        !["get", "add", "edit", "update"].includes(action) &&
+        Object.keys(request.propertyItems).length
+    ) {
+        throw new PlatformError(
+            "UnsupportedPropertyMutation",
+            "Nested property Item mutations are not implemented. Pass a resolved record reference instead.",
+        );
+    }
+
+    if (!["add", "get", "edit", "update"].includes(action) && request.relationships.length) {
+        throw new PlatformError(
+            "UnsupportedRelationships",
+            `Nested relationship requests on '${action}' are not implemented. Apply relationship actions separately.`,
+        );
+    }
+}
+
+function validateCriteria(request: ItemNode, action: string): void {
+    if (action !== "get") {
+        for (const name of ["page", "pagesize", "maxRecords", "isCriteria"]) {
+            if (request.attributes[name] !== undefined) {
+                throw new PlatformError(
+                    "UnsupportedAttribute",
+                    `AML attribute '${name}' is only supported on get requests.`,
+                );
+            }
+        }
+
+        if ((request.logical?.length ?? 0) > 0) {
+            throw new PlatformError(
+                "UnsupportedCondition",
+                "Logical groups require a get request; use where or idlist for mutations.",
+            );
+        }
+    }
+
+    if (
+        !["get", "add"].includes(action) &&
+        !["id", "where", "idlist"].some((name) => request.attributes[name]?.trim())
+    ) {
+        throw new PlatformError(
+            "InvalidSelector",
+            "Mutations require id, idlist or where criteria.",
+        );
+    }
+
+    if (
+        request.attributes.isCriteria !== undefined &&
+        !["0", "1"].includes(request.attributes.isCriteria)
+    ) {
+        throw new PlatformError("InvalidSelector", "isCriteria must be '0' or '1'.");
+    }
+}

package/src/platform/revisions/policy.ts

@@ -0,0 +1,126 @@
+import { Item } from "../../items/item.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    StorageValue,
+    StoredItem,
+} from "../../storage/types.js";
+import { ApplicationError, PlatformError } from "../errors.js";
+import { RevisionSequences } from "./sequences.js";
+
+/** Generations share a revision until the released generation starts a new cycle. */
+export class Revisions {
+    private readonly sequences: RevisionSequences;
+
+    constructor(storage: HarnessStorage) {
+        this.sequences = new RevisionSequences(storage);
+    }
+
+    initial(
+        definition: ItemTypeDefinition,
+        values: Readonly<Record<string, StorageValue>>,
+    ): Readonly<Record<string, StorageValue>> {
+        if (!definition.isVersionable || values.major_rev !== undefined) {
+            return {};
+        }
+
+        const first = this.sequences.resolve(definition)?.values[0];
+
+        return first === undefined ? {} : { major_rev: first };
+    }
+
+    assertValue(definition: ItemTypeDefinition, value: StorageValue | undefined): void {
+        if (!definition.isVersionable || value === undefined) {
+            return;
+        }
+
+        const sequence = this.sequences.resolve(definition);
+
+        if (sequence && !sequence.values.includes(String(value ?? ""))) {
+            throw new ApplicationError(
+                Item.error(
+                    `Revision '${value}' is not in the sequence for '${definition.name}'.`,
+                    "InvalidRevision",
+                ),
+            );
+        }
+    }
+
+    next(definition: ItemTypeDefinition, previous: StoredItem): string {
+        const sequence = this.sequences.resolve(definition);
+
+        if (!sequence) {
+            throw new PlatformError(
+                "MissingRevisionSequence",
+                `Revising released '${definition.name}' requires its exported Revision sequence.`,
+                definition.source ? { source: definition.source } : undefined,
+            );
+        }
+
+        const index = sequence.values.indexOf(String(previous.properties.major_rev ?? ""));
+
+        if (index === -1) {
+            throw new ApplicationError(
+                Item.error(
+                    `Current revision '${previous.properties.major_rev}' is not in the sequence for '${definition.name}'.`,
+                    "InvalidRevision",
+                ),
+            );
+        }
+
+        const next = sequence.values[index + 1];
+
+        if (next === undefined) {
+            throw new ApplicationError(
+                Item.error(
+                    `Revision sequence exceeded for '${definition.name}'. Extend its exported Revision sequence.`,
+                    "RevisionSequenceExceeded",
+                ),
+            );
+        }
+
+        return next;
+    }
+}
+
+export function isReleased(record: StoredItem): boolean {
+    return String(record.properties.is_released ?? "0") === "1";
+}
+
+export function removeRevisionProperties(
+    request: Item,
+    previous: StoredItem,
+    current: StoredItem,
+): void {
+    const managed = [
+        "major_rev",
+        "permission_id",
+        "state",
+        "current_state",
+        "is_released",
+        "not_lockable",
+        "release_date",
+        "effective_date",
+        "superseded_date",
+    ];
+
+    for (const name of managed) {
+        const value = request.node.properties[name];
+
+        if (value === undefined) {
+            continue;
+        }
+
+        if (
+            String(value ?? "") !== String(previous.properties[name] ?? "") &&
+            String(value ?? "") !== String(current.properties[name] ?? "")
+        ) {
+            throw new PlatformError(
+                "ReadOnlyProperty",
+                `Revision property '${previous.type}.${name}' is managed by the new lifecycle cycle.`,
+            );
+        }
+
+        delete request.node.properties[name];
+    }
+}

package/src/platform/revisions/sequences.ts

@@ -0,0 +1,67 @@
+import type { CatalogEntry, HarnessStorage, ItemTypeDefinition } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+const sequenceCharactersMax = 1024 * 1024;
+const sequenceValuesMax = 100_000;
+
+export interface RevisionSequence {
+    readonly entry: CatalogEntry;
+    readonly values: readonly string[];
+}
+
+/** Resolve the exported sequence; the baseline supplies the native ItemType default. */
+export class RevisionSequences {
+    constructor(private readonly storage: HarnessStorage) {}
+
+    resolve(definition: ItemTypeDefinition): RevisionSequence | undefined {
+        const metadata = this.storage.getCatalogEntry("ItemType", definition.id);
+        let id = metadata?.properties.revisions;
+
+        if (id === undefined) {
+            id = this.storage
+                .getItemType("ItemType")
+                ?.properties.find((property) => property.name === "revisions")?.defaultValue;
+        }
+
+        if (id === undefined || id === null || id === "") {
+            return undefined;
+        }
+
+        const entry =
+            typeof id === "string" ? this.storage.getCatalogEntry("Revision", id) : undefined;
+
+        if (!entry) {
+            throw new PlatformError(
+                "MissingRevisionSequence",
+                `Import the Revision referenced by '${definition.name}.revisions'.`,
+                definition.source ? { source: definition.source } : undefined,
+            );
+        }
+
+        const text = entry.properties.revision;
+
+        if (typeof text !== "string" || text.length > sequenceCharactersMax) {
+            throw new PlatformError(
+                "InvalidRevisionSequence",
+                `Revision '${entry.id}' needs a bounded whitespace-separated sequence.`,
+                { source: entry.source },
+            );
+        }
+
+        const values = text.trim().split(/\s+/u);
+
+        if (
+            !values[0] ||
+            values.length > sequenceValuesMax ||
+            new Set(values).size !== values.length
+        ) {
+            throw new PlatformError(
+                "InvalidRevisionSequence",
+                `Revision '${entry.id}' needs a nonempty sequence without duplicate values.`,
+                { source: entry.source },
+            );
+        }
+
+        return { entry, values };
+    }
+}

package/src/platform/security/grants.ts

@@ -0,0 +1,116 @@
+import { assertActiveContext } from "../../core/context.js";
+import { requestOperationsMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { MethodSecurity } from "../../methods/types.js";
+import { PlatformError } from "../errors.js";
+import type { PlatformTrace } from "../trace.js";
+import type { Identities } from "./identities.js";
+
+export class IdentityGrants {
+    private readonly requests = new Map<string, Map<symbol, string>>();
+
+    constructor(
+        private readonly identities: Identities,
+        private readonly trace: PlatformTrace,
+    ) {}
+
+    current(context: ExecutionContext): readonly string[] {
+        assertActiveContext(context);
+        const grants = this.requests.get(context.requestId);
+
+        return this.identities.current(grants?.values() ?? [], context);
+    }
+
+    scope(context: ExecutionContext): MethodSecurity & Disposable {
+        const owned = new Set<Disposable>();
+        let closed = false;
+        let issued = 0;
+        const active = () => {
+            assertActiveContext(context);
+
+            if (closed) {
+                throw new PlatformError(
+                    "ExpiredSecurityScope",
+                    "The Method identity scope has completed.",
+                );
+            }
+        };
+
+        return {
+            getIdentities: () => {
+                active();
+
+                return this.current(context);
+            },
+
+            getIdentityByName: (name) => {
+                active();
+
+                return this.identities.byName(name, context);
+            },
+
+            grantIdentity: (id) => {
+                active();
+
+                if (++issued > requestOperationsMax) {
+                    throw new PlatformError(
+                        "ProtocolLimit",
+                        "Identity grants exceed their invocation budget.",
+                    );
+                }
+
+                const grant = this.grant(id, context);
+                owned.add(grant);
+
+                return grant;
+            },
+
+            [Symbol.dispose]: () => {
+                closed = true;
+
+                for (const grant of owned) {
+                    grant[Symbol.dispose]();
+                }
+
+                owned.clear();
+            },
+        };
+    }
+
+    private grant(id: string, context: ExecutionContext): Disposable {
+        this.identities.user();
+        const identity = this.identities.byId(id);
+        const grants = this.requests.get(context.requestId) ?? new Map<symbol, string>();
+
+        if (grants.size >= requestOperationsMax) {
+            throw new PlatformError(
+                "ProtocolLimit",
+                "Identity grants exceed their request budget.",
+            );
+        }
+
+        const token = Symbol(identity.id);
+        grants.set(token, identity.id);
+        this.requests.set(context.requestId, grants);
+        this.trace.record(context, {
+            kind: "authorization",
+            name: `Grant Identity '${identity.name}'`,
+        });
+        let active = true;
+
+        return {
+            [Symbol.dispose]: () => {
+                if (!active) {
+                    return;
+                }
+
+                active = false;
+                grants.delete(token);
+
+                if (grants.size === 0 && this.requests.get(context.requestId) === grants) {
+                    this.requests.delete(context.requestId);
+                }
+            },
+        };
+    }
+}