@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/packages/candidates.ts

@@ -0,0 +1,55 @@
+import type { DraftEntry } from "./draft.js";
+import type { ActionChange, ImportRead } from "./plan.js";
+
+/** One planning pass owns these indexes; selectors still decide whether candidates match. */
+export class ImportCandidates {
+    private readonly byKey = new Map<string, ActionChange[]>();
+    private readonly byType = new Map<string, ActionChange[]>();
+    private readonly initialByType = new Map<string, DraftEntry[]>();
+
+    constructor(
+        changes: readonly ActionChange[],
+        private readonly initial: ReadonlyMap<string, DraftEntry>,
+    ) {
+        for (const entry of initial.values()) {
+            const type = entry.type.toLowerCase();
+            const entries = this.initialByType.get(type) ?? [];
+            entries.push(entry);
+            this.initialByType.set(type, entries);
+        }
+
+        for (const candidate of changes) {
+            const entry = candidate.change.after ?? candidate.change.before;
+
+            if (!entry) {
+                continue;
+            }
+
+            const type = entry.type.toLowerCase();
+            const typed = this.byType.get(type) ?? [];
+            const keyed = this.byKey.get(candidate.change.key) ?? [];
+            typed.push(candidate);
+            keyed.push(candidate);
+            this.byType.set(type, typed);
+            this.byKey.set(candidate.change.key, keyed);
+        }
+    }
+
+    changes(read: ImportRead): readonly ActionChange[] {
+        if (read.key !== undefined) {
+            return this.byKey.get(read.key) ?? [];
+        }
+
+        return this.byType.get(read.type.toLowerCase()) ?? [];
+    }
+
+    initialEntries(read: ImportRead): readonly DraftEntry[] {
+        if (read.key !== undefined) {
+            const entry = this.initial.get(read.key);
+
+            return entry ? [entry] : [];
+        }
+
+        return this.initialByType.get(read.type.toLowerCase()) ?? [];
+    }
+}

package/src/packages/defaults.ts

@@ -0,0 +1,145 @@
+import { baselineEntries } from "../baseline/catalog.js";
+import { isBaselineSource } from "../baseline/source.js";
+import { setOwn, getOwn } from "../core/data.js";
+import { entryKey } from "./draft.js";
+import type { ImportDraft, DraftEntry } from "./draft.js";
+
+const baselineTypes = new Map(
+    baselineEntries
+        .filter((entry) => entry.type === "ItemType")
+        .map((entry) => [entry.id, scalarKey(entry.properties.name)]),
+);
+const baselineTypeIds = new Map([...baselineTypes].map(([id, name]) => [name.toLowerCase(), id]));
+const baselinePropertyIds = new Map(
+    baselineEntries
+        .filter((entry) => entry.type === "Property")
+        .map((entry) => {
+            const owner = baselineTypes.get(scalarKey(entry.properties.source_id));
+
+            if (owner === undefined) {
+                throw new Error(`Built-in Property '${entry.id}' must have a declared ItemType.`);
+            }
+
+            return [propertyKey(owner, scalarKey(entry.properties.name)), entry.id];
+        }),
+);
+
+/** Built-in records are defaults; explicit package definitions take precedence. */
+export class PackageDefaults {
+    constructor(private readonly draft: ImportDraft) {}
+
+    initialize(): void {
+        // Later imports must not resurrect defaults a package changed or deleted.
+        const initialized = [...this.draft.entries.values()].some(
+            (entry) => entry.type === "ItemType" && entry.properties.name === "ItemType",
+        );
+
+        if (initialized) {
+            return;
+        }
+
+        for (const entry of baselineEntries) {
+            const key = entryKey(entry.type, entry.id);
+
+            if (!this.draft.entries.has(key)) {
+                this.draft.put({ ...entry, properties: { ...entry.properties } });
+            }
+        }
+    }
+
+    replaceItemType(name: string, nativeId: string): void {
+        const previousId = baselineTypeIds.get(name.toLowerCase());
+        const existing = previousId
+            ? this.draft.entries.get(entryKey("ItemType", previousId))
+            : undefined;
+
+        if (
+            !existing ||
+            !isBaselineSource(existing.source) ||
+            existing.id.toLowerCase() === nativeId.toLowerCase()
+        ) {
+            return;
+        }
+
+        this.retargetReferences("ItemType", existing.id, nativeId);
+        this.draft.remove(entryKey("ItemType", existing.id), existing);
+    }
+
+    replaceProperty(entry: DraftEntry): void {
+        const sourceId = scalarKey(entry.properties.source_id);
+        const owner = this.draft.entries.get(entryKey("ItemType", sourceId));
+        const key = propertyKey(
+            scalarKey(owner?.properties.name),
+            scalarKey(entry.properties.name),
+        );
+        const previousId = baselinePropertyIds.get(key);
+        const previous = previousId
+            ? this.draft.entries.get(entryKey("Property", previousId))
+            : undefined;
+
+        if (
+            previous &&
+            previous.id !== entry.id &&
+            isBaselineSource(previous.source) &&
+            scalarKey(previous.properties.source_id).toLowerCase() === sourceId.toLowerCase()
+        ) {
+            this.retargetReferences("Property", previous.id, entry.id);
+            this.draft.remove(entryKey("Property", previous.id), previous);
+        }
+    }
+
+    private retargetReferences(type: string, previousId: string, nextId: string): void {
+        const entries = [...this.draft.entries.values()];
+        const target = entries.find(
+            (entry) => entry.type === "ItemType" && entry.properties.name === type,
+        );
+
+        if (!target) {
+            return;
+        }
+
+        const references = entries.filter(
+            (entry) =>
+                entry.type === "Property" &&
+                entry.properties.data_type === "item" &&
+                entry.properties.data_source === target.id,
+        );
+        const types = new Map(
+            entries
+                .filter((entry) => entry.type === "ItemType")
+                .map((entry) => [entry.id, entry.properties.name]),
+        );
+
+        // Explicit package references remain authoritative and are validated after import.
+        for (const reference of references) {
+            const owner = reference.properties.source_id;
+            const name = reference.properties.name;
+
+            if (typeof owner !== "string" || typeof name !== "string") {
+                continue;
+            }
+
+            for (const entry of entries) {
+                const value = getOwn(entry.properties, name);
+
+                if (
+                    entry.type === types.get(owner) &&
+                    isBaselineSource(entry.source) &&
+                    typeof value === "string" &&
+                    value.toLowerCase() === previousId.toLowerCase()
+                ) {
+                    this.draft.touch(entry, [name]);
+                    setOwn(entry.properties, name, nextId);
+                }
+            }
+        }
+    }
+}
+
+function scalarKey(value: unknown): string {
+    return typeof value === "string" || typeof value === "number" ? String(value) : "";
+}
+
+function propertyKey(type: string, name: string): string {
+    return JSON.stringify([type.toLowerCase(), name.toLowerCase()]);
+}

package/src/packages/diagnostics.ts

@@ -0,0 +1,47 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { AmlElement } from "./types.js";
+
+export interface PackageReference {
+    readonly type: string;
+    readonly id?: string;
+    readonly name?: string;
+    readonly selector?: AmlElement;
+}
+
+interface PackageErrorOptions extends ErrorOptions {
+    readonly relatedSources?: readonly SourceLocation[];
+    readonly reference?: PackageReference;
+}
+
+export class PackageImportError extends Error {
+    readonly relatedSources: readonly SourceLocation[];
+    readonly reference?: PackageReference;
+
+    constructor(
+        readonly code: string,
+        message: string,
+        readonly source: SourceLocation,
+        options?: PackageErrorOptions,
+    ) {
+        super(`${source.file}:${source.line}:${source.column} ${source.path}: ${message}`, options);
+        this.name = "PackageImportError";
+        this.relatedSources = Object.freeze([...(options?.relatedSources ?? [])]);
+
+        if (options?.reference) {
+            this.reference = Object.freeze({ ...options.reference });
+        }
+    }
+}
+
+export function throwImportErrors(errors: readonly PackageImportError[]): void {
+    if (errors.length === 1 && errors[0]) {
+        throw errors[0];
+    }
+
+    if (errors.length > 1) {
+        throw new AggregateError(
+            errors,
+            `Package import has ${errors.length} problems:\n${errors.map((error) => error.message).join("\n")}`,
+        );
+    }
+}

package/src/packages/draft.ts

@@ -0,0 +1,280 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { StorageValue } from "../storage/types.js";
+import type { AmlElement } from "./types.js";
+
+interface ItemReference {
+    readonly kind: "reference";
+    readonly element: AmlElement;
+}
+
+interface TypedReference {
+    readonly kind: "typed-reference";
+    readonly type: string;
+    readonly id: string;
+    readonly source: SourceLocation;
+}
+
+export type PendingValue = StorageValue | ItemReference | TypedReference;
+
+export interface DraftEntry {
+    readonly id: string;
+    readonly type: string;
+    attributes: Readonly<Record<string, string>>;
+    properties: Record<string, PendingValue>;
+    source: SourceLocation;
+}
+
+export interface DraftChange {
+    readonly key: string;
+    readonly before: DraftEntry | undefined;
+    readonly after: DraftEntry | undefined;
+    readonly properties: ReadonlySet<string>;
+    readonly replacesItem: boolean;
+    readonly previousCreator: number | undefined;
+}
+
+interface SavedEntry {
+    readonly entry: DraftEntry | undefined;
+    readonly changed: boolean;
+    readonly deleted: DraftEntry | undefined;
+    readonly creator: number | undefined;
+    readonly properties: Set<string>;
+    replacesItem: boolean;
+}
+
+interface DraftCheckpoint {
+    readonly entries: ReadonlyMap<string, DraftEntry>;
+    readonly changed: ReadonlySet<string>;
+    readonly deleted: ReadonlyMap<string, DraftEntry>;
+    readonly creators: ReadonlyMap<string, number>;
+}
+
+export function entryKey(type: string, id: string): string {
+    return JSON.stringify([type.toLowerCase(), id.toLowerCase()]);
+}
+
+function copy(entry: DraftEntry): DraftEntry {
+    return { ...entry, properties: { ...entry.properties } };
+}
+
+/** In-memory import state. Failed action attempts restore only the records they touched. */
+export class ImportDraft {
+    private readonly records = new Map<string, DraftEntry>();
+    private readonly recordsByType = new Map<string, Map<string, DraftEntry>>();
+    private readonly changedKeys = new Set<string>();
+    private readonly deletions = new Map<string, DraftEntry>();
+    private readonly creators = new Map<string, number>();
+    private journal: Map<string, SavedEntry> | undefined;
+    private action: number | undefined;
+
+    constructor(entries: ReadonlyMap<string, DraftEntry>) {
+        for (const [key, entry] of entries) {
+            this.setRecord(key, entry);
+        }
+    }
+
+    get entries(): ReadonlyMap<string, DraftEntry> {
+        return this.records;
+    }
+
+    ofType(type: string): Iterable<DraftEntry> {
+        return this.recordsByType.get(type.toLowerCase())?.values() ?? [];
+    }
+
+    get changed(): ReadonlySet<string> {
+        return this.changedKeys;
+    }
+
+    get deleted(): ReadonlyMap<string, DraftEntry> {
+        return this.deletions;
+    }
+
+    put(entry: DraftEntry): void {
+        const key = entryKey(entry.type, entry.id);
+        this.capture(key).replacesItem = true;
+        this.setRecord(key, entry);
+        this.changedKeys.add(key);
+
+        if (this.action !== undefined) {
+            this.creators.set(key, this.action);
+        }
+    }
+
+    touch(entry: DraftEntry, properties: readonly string[]): void {
+        const key = entryKey(entry.type, entry.id);
+        const saved = this.capture(key);
+
+        for (const name of properties) {
+            saved.properties.add(name);
+        }
+
+        this.changedKeys.add(key);
+    }
+
+    remove(key: string, deletion?: DraftEntry): void {
+        this.capture(key).replacesItem = true;
+        this.removeRecord(key);
+        this.changedKeys.delete(key);
+        this.creators.delete(key);
+
+        if (deletion) {
+            this.deletions.set(key, deletion);
+        }
+    }
+
+    begin(action: number): void {
+        if (this.journal) {
+            throw new Error("An import action attempt is already active.");
+        }
+
+        this.action = action;
+        this.journal = new Map();
+    }
+
+    changes(): readonly DraftChange[] {
+        const changes: DraftChange[] = [];
+
+        for (const [key, saved] of this.journal ?? []) {
+            const after = this.records.get(key);
+
+            if (!saved.entry && !after) {
+                continue;
+            }
+
+            changes.push({
+                key,
+                before: saved.entry,
+                after: after ? copy(after) : undefined,
+                properties: new Set(saved.properties),
+                replacesItem: saved.replacesItem,
+                previousCreator: saved.creator,
+            });
+        }
+
+        return changes;
+    }
+
+    commit(): void {
+        this.journal = undefined;
+        this.action = undefined;
+    }
+
+    rollback(): void {
+        for (const [key, saved] of this.journal ?? []) {
+            if (saved.entry) {
+                this.setRecord(key, saved.entry);
+            } else {
+                this.removeRecord(key);
+            }
+
+            this.restoreEntry(key, saved.deleted, this.deletions);
+
+            if (saved.changed) {
+                this.changedKeys.add(key);
+            } else {
+                this.changedKeys.delete(key);
+            }
+
+            if (saved.creator === undefined) {
+                this.creators.delete(key);
+            } else {
+                this.creators.set(key, saved.creator);
+            }
+        }
+
+        this.commit();
+    }
+
+    checkpoint(): DraftCheckpoint {
+        return {
+            entries: new Map([...this.records].map(([key, entry]) => [key, copy(entry)])),
+            changed: new Set(this.changedKeys),
+            deleted: new Map(this.deletions),
+            creators: new Map(this.creators),
+        };
+    }
+
+    restore(checkpoint: DraftCheckpoint): void {
+        this.records.clear();
+        this.recordsByType.clear();
+        this.changedKeys.clear();
+        this.deletions.clear();
+        this.creators.clear();
+
+        for (const [key, entry] of checkpoint.entries) {
+            this.setRecord(key, copy(entry));
+        }
+
+        for (const key of checkpoint.changed) {
+            this.changedKeys.add(key);
+        }
+
+        for (const [key, entry] of checkpoint.deleted) {
+            this.deletions.set(key, entry);
+        }
+
+        for (const [key, action] of checkpoint.creators) {
+            this.creators.set(key, action);
+        }
+
+        this.commit();
+    }
+
+    private setRecord(key: string, entry: DraftEntry): void {
+        this.records.set(key, entry);
+        const type = entry.type.toLowerCase();
+        const records = this.recordsByType.get(type) ?? new Map<string, DraftEntry>();
+        records.set(key, entry);
+        this.recordsByType.set(type, records);
+    }
+
+    private removeRecord(key: string): void {
+        const entry = this.records.get(key);
+
+        if (!entry) {
+            return;
+        }
+
+        this.records.delete(key);
+        const type = entry.type.toLowerCase();
+        const records = this.recordsByType.get(type);
+        records?.delete(key);
+
+        if (records?.size === 0) {
+            this.recordsByType.delete(type);
+        }
+    }
+
+    private capture(key: string): SavedEntry {
+        const existing = this.journal?.get(key);
+
+        if (existing) {
+            return existing;
+        }
+
+        const entry = this.records.get(key);
+        const saved: SavedEntry = {
+            entry: entry ? copy(entry) : undefined,
+            changed: this.changedKeys.has(key),
+            deleted: this.deletions.get(key),
+            creator: this.creators.get(key),
+            properties: new Set(),
+            replacesItem: false,
+        };
+        this.journal?.set(key, saved);
+
+        return saved;
+    }
+
+    private restoreEntry(
+        key: string,
+        entry: DraftEntry | undefined,
+        target: Map<string, DraftEntry>,
+    ): void {
+        if (entry) {
+            target.set(key, entry);
+        } else {
+            target.delete(key);
+        }
+    }
+}

package/src/packages/elements.ts

@@ -0,0 +1,88 @@
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import { PackageImportError } from "./diagnostics.js";
+import type { AmlElement } from "./types.js";
+
+export function childElements(element: AmlElement): readonly AmlElement[] {
+    return element.children.filter((child) => child.kind === "element");
+}
+
+export function textContent(element: AmlElement): string {
+    return element.children
+        .filter((child) => child.kind !== "element")
+        .map((child) => child.value)
+        .join("");
+}
+
+export function itemType(element: AmlElement): string {
+    const type = element.attributes.type?.trim();
+
+    if (element.name !== "Item" || !type) {
+        throw new PackageImportError(
+            "INVALID_ITEM",
+            "Expected an Item with a type.",
+            element.source,
+        );
+    }
+
+    return type;
+}
+
+export function itemProperties(element: AmlElement): readonly AmlElement[] {
+    const properties = childElements(element).filter((child) => child.name !== "Relationships");
+    const names = new Set<string>();
+
+    for (const property of properties) {
+        if (names.has(property.name)) {
+            throw new PackageImportError(
+                "REPEATED_PROPERTY",
+                `Repeated property '${property.name}' requires a multi-value or multilingual adapter.`,
+                property.source,
+            );
+        }
+
+        names.add(property.name);
+    }
+
+    return properties;
+}
+
+/**
+ * Preorder traversal preserves declaration order without consuming the JavaScript call stack.
+ * @yields {AmlElement} Each element in its original declaration order.
+ */
+export function* walkElements(roots: readonly AmlElement[]): Generator<AmlElement, void, void> {
+    const pending = roots.map((element) => ({ element, depth: 0 })).reverse();
+    const visited = new Set<AmlElement>();
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("An AML frame must exist while traversal is pending.");
+        }
+
+        if (
+            visited.size >= dataNodesMax ||
+            frame.depth > dataDepthMax ||
+            visited.has(frame.element)
+        ) {
+            throw new PackageImportError(
+                "INVALID_ITEM",
+                "AML exceeds its traversal bounds or contains a cycle.",
+                frame.element.source,
+            );
+        }
+
+        visited.add(frame.element);
+        yield frame.element;
+        const children = childElements(frame.element);
+
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const element = children[index];
+
+            if (element) {
+                pending.push({ element, depth: frame.depth + 1 });
+            }
+        }
+    }
+}

package/src/packages/evaluation.ts

@@ -0,0 +1,89 @@
+import { importFramesMax, dataNodesMax } from "../core/limits.js";
+
+export interface ImportWork {
+    advance(): ImportWork | null;
+    abort(error: unknown): void;
+}
+
+/** A suspended metadata operation. Only the evaluator advances nested operations. */
+export class ImportTask<Value> implements ImportWork {
+    private result: { readonly value: Value } | undefined;
+
+    constructor(private readonly program: Generator<ImportWork, Value, void>) {}
+
+    advance(): ImportWork | null {
+        const step = this.program.next();
+
+        if (step.done) {
+            this.result = { value: step.value };
+
+            return null;
+        }
+
+        return step.value;
+    }
+
+    value(): Value {
+        if (!this.result) {
+            throw new Error("An import task cannot be read before it completes.");
+        }
+
+        return this.result.value;
+    }
+
+    abort(error: unknown): void {
+        this.program.throw(error);
+    }
+}
+
+/** Explicit interpreter stack preserves AML action order and unwinds selector guards on failure. */
+export function evaluateImport<Value>(root: ImportTask<Value>): Value {
+    const pending: ImportWork[] = [root];
+    let steps = 0;
+
+    try {
+        while (pending.length > 0) {
+            steps += 1;
+
+            if (steps > dataNodesMax || pending.length > importFramesMax) {
+                throw new TypeError("Package evaluation exceeded its work or nesting limit.");
+            }
+
+            const current = pending.at(-1);
+
+            if (!current) {
+                throw new Error("An import task must exist while evaluation is pending.");
+            }
+
+            const child = current.advance();
+
+            if (child === null) {
+                pending.pop();
+            } else {
+                pending.push(child);
+            }
+        }
+    } catch (error) {
+        const failures = [error];
+
+        for (const task of pending.reverse()) {
+            try {
+                task.abort(error);
+            } catch (cleanupError) {
+                if (cleanupError !== error) {
+                    failures.push(cleanupError);
+                }
+            }
+        }
+
+        if (failures.length > 1) {
+            throw new AggregateError(failures, "Package evaluation and unwinding failed.", {
+                cause: error,
+            });
+        }
+
+        throw error;
+    }
+
+    return root.value();
+}