@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/platform/references/maintenance.ts

@@ -0,0 +1,175 @@
+import { assertActiveContext, spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    StorageValue,
+    StoredItem,
+} from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import type { PlatformTrace } from "../trace.js";
+import { ReferenceBehavior, floats } from "./behavior.js";
+import { ReferenceCatalog } from "./catalog.js";
+import { ReferencePolicies } from "./policy.js";
+import { ReferenceSessions } from "./sessions.js";
+
+/** Reference maintenance is a platform write, sharing its caller's transaction and trace. */
+export class ReferenceMaintenance {
+    readonly catalog: ReferenceCatalog;
+    readonly policies: ReferencePolicies;
+    readonly sessions: ReferenceSessions;
+
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly trace: PlatformTrace,
+    ) {
+        this.catalog = new ReferenceCatalog(storage);
+        this.policies = new ReferencePolicies(storage, this.catalog);
+        this.sessions = new ReferenceSessions(storage, this.catalog);
+    }
+
+    initialize(definition: ItemTypeDefinition, record: StoredItem): StoredItem {
+        if (!definition.isRelationship) {
+            return record;
+        }
+
+        return {
+            ...record,
+            properties: {
+                ...record.properties,
+                behavior: this.policies.relationship(definition, record),
+            },
+        };
+    }
+
+    versioned(previous: StoredItem, current: StoredItem, context: ExecutionContext): void {
+        if (this.storage.getItemType(previous.type)?.isRelationship) {
+            this.freeze(previous, context);
+        }
+
+        const ids = new Set(this.catalog.family(previous).map((record) => record.id.toLowerCase()));
+
+        for (const incoming of this.catalog.incoming(previous, context, ids)) {
+            const { definition, property, record } = incoming;
+
+            if (this.policies.historical(definition, record) || property.name === "source_id") {
+                continue;
+            }
+
+            const behavior =
+                definition.isRelationship && property.name === "related_id"
+                    ? this.policies.relationship(definition, record)
+                    : this.policies.property(property);
+
+            if (floats(behavior)) {
+                this.change(record, { [property.name]: current.id }, "float", context);
+            }
+        }
+    }
+
+    copied(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        parentId: string,
+        resetBehavior = false,
+    ): Readonly<Record<string, StorageValue>> {
+        const properties: Record<string, StorageValue> = {
+            ...record.properties,
+            source_id: parentId,
+        };
+
+        if (resetBehavior) {
+            properties.behavior = null;
+        }
+
+        const related = definition.properties.find((property) => property.name === "related_id");
+        const target = related ? this.catalog.target(related) : undefined;
+        const id = properties.related_id;
+
+        if (target && typeof id === "string" && id !== "") {
+            const existing = this.storage.getItem(target.name, id);
+
+            if (!existing) {
+                throw new PlatformError(
+                    "MissingReference",
+                    `Copied relationship '${record.type}:${record.id}' points to missing '${target.name}:${id}'.`,
+                );
+            }
+
+            properties.related_id = this.catalog.current(existing).id;
+        }
+
+        return this.initialize(definition, { ...record, properties }).properties;
+    }
+
+    freeze(record: StoredItem, context: ExecutionContext): void {
+        this.change(record, { behavior: ReferenceBehavior.HardFixed }, "freeze", context);
+    }
+
+    promoted(parent: StoredItem, context: ExecutionContext): void {
+        for (const record of this.catalog.owned(parent, context)) {
+            spendContext(context);
+            const definition = this.storage.getItemType(record.type);
+
+            if (!definition) {
+                throw new PlatformError(
+                    "MissingItemType",
+                    `Relationship '${record.type}' has no schema.`,
+                );
+            }
+
+            const behavior = this.policies.relationship(definition, record);
+            const changes: Record<string, StorageValue> = { behavior };
+            const property = definition.properties.find(
+                (property) => property.name === "related_id",
+            );
+            const target = property ? this.catalog.target(property) : undefined;
+            const id = record.properties.related_id;
+
+            if (floats(behavior) && target && typeof id === "string" && id !== "") {
+                const referenced = this.storage.getItem(target.name, id);
+
+                if (!referenced) {
+                    throw new PlatformError(
+                        "MissingReference",
+                        `Relationship '${record.type}:${record.id}' has a missing related Item.`,
+                    );
+                }
+
+                changes.related_id = this.catalog.current(referenced).id;
+            }
+
+            this.change(record, changes, "reference-policy", context);
+        }
+    }
+
+    private change(
+        record: StoredItem,
+        values: Readonly<Record<string, StorageValue>>,
+        name: string,
+        context: ExecutionContext,
+    ): void {
+        const before = this.storage.getItem(record.type, record.id);
+
+        if (!before) {
+            throw new PlatformError(
+                "MissingItem",
+                `Reference source '${record.type}:${record.id}' disappeared.`,
+            );
+        }
+
+        if (Object.entries(values).every(([name, value]) => before.properties[name] === value)) {
+            return;
+        }
+
+        assertActiveContext(context);
+        this.storage.updateItem(record.type, record.id, values);
+        const after = this.storage.getItem(record.type, record.id);
+
+        if (!after) {
+            throw new Error("Reference maintenance must retain its source record.");
+        }
+
+        this.trace.record(context, { kind: "mutation", name, before, after });
+    }
+}

package/src/platform/references/policy.ts

@@ -0,0 +1,115 @@
+import { dataDepthMax } from "../../core/limits.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    PropertyDefinition,
+    StoredItem,
+} from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { ReferenceBehavior, hardBehavior, referenceBehavior } from "./behavior.js";
+import { recordKey } from "./catalog.js";
+import type { ReferenceCatalog } from "./catalog.js";
+
+/** Metadata controls reference behavior; no consumer policy configuration is required. */
+export class ReferencePolicies {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly catalog: ReferenceCatalog,
+    ) {}
+
+    property(property: PropertyDefinition): ReferenceBehavior {
+        if (property.name === "config_id" || property.name === "source_id" || !property.id) {
+            return ReferenceBehavior.Fixed;
+        }
+
+        const metadata = this.storage.getCatalogEntry("Property", property.id);
+        const configured = referenceBehavior(metadata?.properties.item_behavior);
+
+        if (configured !== undefined) {
+            return configured;
+        }
+
+        const defaults = this.storage
+            .getItemType("Property")
+            ?.properties.find((property) => property.name === "item_behavior")?.defaultValue;
+
+        return referenceBehavior(defaults) ?? ReferenceBehavior.Float;
+    }
+
+    relationship(definition: ItemTypeDefinition, record: StoredItem): ReferenceBehavior {
+        const template = referenceBehavior(
+            this.catalog.relationship(definition)?.properties.behavior,
+        );
+        const instance = referenceBehavior(record.properties.behavior);
+
+        if (template !== undefined && hardBehavior(template)) {
+            return template;
+        }
+
+        if (instance !== undefined && hardBehavior(instance)) {
+            return instance;
+        }
+
+        const source = this.source(definition, record);
+        const state = this.storage.getCatalogEntry(
+            "Life Cycle State",
+            String(source?.properties.current_state ?? ""),
+        );
+        const configured = referenceBehavior(state?.properties.item_behavior);
+
+        return configured ?? instance ?? template ?? ReferenceBehavior.Fixed;
+    }
+
+    historical(definition: ItemTypeDefinition, record: StoredItem): boolean {
+        const visited = new Set<string>();
+        let current: StoredItem | undefined = record;
+        let type: ItemTypeDefinition | undefined = definition;
+
+        while (current && type) {
+            const key = recordKey(current);
+
+            if (visited.has(key) || visited.size >= dataDepthMax) {
+                throw new PlatformError(
+                    "RelationshipCycle",
+                    "Reference ownership is cyclic or too deep.",
+                );
+            }
+
+            visited.add(key);
+
+            if (type.isVersionable && String(current.properties.is_current) === "0") {
+                return true;
+            }
+
+            if (!type.isRelationship) {
+                return false;
+            }
+
+            current = this.source(type, current);
+            type = current ? this.storage.getItemType(current.type) : undefined;
+        }
+
+        return false;
+    }
+
+    private source(definition: ItemTypeDefinition, record: StoredItem): StoredItem | undefined {
+        const property = definition.properties.find((property) => property.name === "source_id");
+        const target = property ? this.catalog.target(property) : undefined;
+        const id = record.properties.source_id;
+
+        if (typeof id !== "string" || !target) {
+            return undefined;
+        }
+
+        const source = this.storage.getItem(target.name, id);
+
+        if (!source) {
+            throw new PlatformError(
+                "MissingReference",
+                `Relationship '${record.type}:${record.id}' has no source '${id}'.`,
+            );
+        }
+
+        return source;
+    }
+}

package/src/platform/references/sessions.ts

@@ -0,0 +1,148 @@
+import { spendContext } from "../../core/context.js";
+import { dataNodesMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import type { HarnessStorage, StoredItem } from "../../storage/types.js";
+import { ApplicationError, PlatformError } from "../errors.js";
+import { recordKey } from "./catalog.js";
+import type { ReferenceCatalog } from "./catalog.js";
+
+interface ReferenceSession {
+    readonly created: Map<string, StoredItem>;
+    readonly scheduled: Set<string>;
+    readonly active: Set<string>;
+    readonly deleted: Map<string, StoredItem>;
+}
+
+/** A Method or AML batch may construct several linked Items before the transaction is checked. */
+export class ReferenceSessions {
+    private readonly sessions = new Map<string, ReferenceSession>();
+
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly catalog: ReferenceCatalog,
+    ) {}
+
+    async run<T>(context: ExecutionContext, work: () => Promise<T>): Promise<T> {
+        if (this.sessions.has(context.requestId)) {
+            return await work();
+        }
+
+        const session: ReferenceSession = {
+            created: new Map(),
+            scheduled: new Set(),
+            active: new Set(),
+            deleted: new Map(),
+        };
+        this.sessions.set(context.requestId, session);
+
+        try {
+            const result = await work();
+            this.validate(session, context);
+
+            return result;
+        } finally {
+            this.sessions.delete(context.requestId);
+        }
+    }
+
+    created(record: StoredItem, context: ExecutionContext): void {
+        this.session(context).created.set(recordKey(record), record);
+    }
+
+    schedule(record: StoredItem, context: ExecutionContext): void {
+        const session = this.session(context);
+
+        if (session.scheduled.size >= dataNodesMax) {
+            throw new PlatformError("ProtocolLimit", "Deletion exceeds its record budget.");
+        }
+
+        session.scheduled.add(recordKey(record));
+    }
+
+    scheduled(record: StoredItem, context: ExecutionContext): boolean {
+        return this.session(context).scheduled.has(recordKey(record));
+    }
+
+    active(record: StoredItem, context: ExecutionContext): boolean {
+        return this.session(context).active.has(recordKey(record));
+    }
+
+    async deleting<T>(
+        record: StoredItem,
+        context: ExecutionContext,
+        work: () => Promise<T>,
+    ): Promise<T> {
+        const session = this.session(context);
+        const key = recordKey(record);
+
+        if (session.active.has(key)) {
+            throw new PlatformError(
+                "RelationshipCycle",
+                `Cyclic deletion of '${record.type}:${record.id}'.`,
+            );
+        }
+
+        session.active.add(key);
+
+        try {
+            return await work();
+        } finally {
+            session.active.delete(key);
+        }
+    }
+
+    deleted(record: StoredItem, context: ExecutionContext): void {
+        this.session(context).deleted.set(recordKey(record), record);
+    }
+
+    private session(context: ExecutionContext): ReferenceSession {
+        spendContext(context);
+        const session = this.sessions.get(context.requestId);
+
+        if (!session) {
+            throw new Error("Platform reference changes require an active request scope.");
+        }
+
+        return session;
+    }
+
+    private validate(session: ReferenceSession, context: ExecutionContext): void {
+        for (const record of session.deleted.values()) {
+            if (this.storage.getItem(record.type, record.id)) {
+                continue;
+            }
+
+            const incoming = this.catalog.incoming(record, context).next();
+
+            if (!incoming.done) {
+                const source = incoming.value;
+
+                throw new ApplicationError(
+                    Item.error(
+                        `Deletion left '${source.definition.name}.${source.property.name}' referencing '${record.type}:${record.id}'.`,
+                        "ReferencedItem",
+                    ),
+                );
+            }
+        }
+
+        for (const record of session.created.values()) {
+            const definition = this.storage.getItemType(record.type);
+
+            if (
+                definition &&
+                this.catalog.dependent(definition) &&
+                this.storage.getItem(record.type, record.id) &&
+                !this.catalog.hasOwner(record, context)
+            ) {
+                throw new ApplicationError(
+                    Item.error(
+                        `Dependent '${record.type}:${record.id}' requires an owning reference in the same request.`,
+                        "DependentItem",
+                    ),
+                );
+            }
+        }
+    }
+}

package/src/platform/relationship-copy-policy.ts

@@ -0,0 +1,66 @@
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import { eventOwners } from "./events/inheritance.js";
+import { isReleased } from "./revisions/policy.js";
+
+const fileContainerTypeId = "41EF49EFD2ED4F6EAB04C047681F33AC";
+const fileTypeId = "8052A558B9084D41B9F11805E464F443";
+
+/** Suppressed business hooks do not replace native revision or vault services. */
+export class VersionCopyPolicy {
+    private readonly hasFileContainer: boolean;
+    private readonly checked = new Set<string>();
+
+    constructor(private readonly storage: HarnessStorage) {
+        this.hasFileContainer =
+            storage.getCatalogEntry("ItemType", fileContainerTypeId) !== undefined;
+    }
+
+    assertSupported(definition: ItemTypeDefinition, records: readonly StoredItem[]): void {
+        if (definition.isVersionable && records.some((record) => isReleased(record))) {
+            throw new PlatformError(
+                "UnsupportedRevision",
+                "Cloning released relationships requires a revision and lifecycle reset policy.",
+            );
+        }
+
+        const id = definition.id.toLowerCase();
+
+        if (this.checked.has(id)) {
+            return;
+        }
+
+        const owners = eventOwners(this.storage, definition.id);
+
+        if (
+            id === fileTypeId.toLowerCase() ||
+            definition.name.toLowerCase() === "file" ||
+            (this.hasFileContainer && owners.has(fileContainerTypeId.toLowerCase()))
+        ) {
+            throw new PlatformError(
+                "UnsupportedFileCopy",
+                `Copying '${definition.name}' during versioning requires native file-container and vault services, which are unavailable.`,
+                definition.source ? { source: definition.source } : undefined,
+            );
+        }
+
+        const reset = this.storage.listCatalogEntries("Server Event").find((entry) => {
+            const properties = entry.properties;
+
+            return (
+                owners.has(String(properties.source_id).toLowerCase()) &&
+                String(properties.server_event).toLowerCase() === "onafterresetlifecycle"
+            );
+        });
+
+        if (reset) {
+            throw new PlatformError(
+                "UnsupportedLifecycleResetEvent",
+                `Copying '${definition.name}' requires onAfterResetLifecycle event metadata, which is unavailable.`,
+                { source: reset.source },
+            );
+        }
+
+        this.checked.add(id);
+    }
+}