@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/controls/ids.ts

@@ -0,0 +1,87 @@
+export interface IdSettings {
+    readonly seed: string;
+}
+
+export interface IdPosition {
+    readonly fixtures: number;
+    readonly items: number;
+}
+
+const seedCharactersMax = 1024;
+
+/** Seeded IDs retain the native 32-character uppercase hexadecimal format. */
+export function seededIds(seed: string): IdSettings {
+    if (typeof seed !== "string" || seed.length === 0 || seed.length > seedCharactersMax) {
+        throw new TypeError(`An ID seed must contain 1–${seedCharactersMax} characters.`);
+    }
+
+    return Object.freeze({ seed });
+}
+
+export function idSettings(value: unknown): IdSettings | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    if (
+        value === null ||
+        typeof value !== "object" ||
+        !("seed" in value) ||
+        typeof value.seed !== "string" ||
+        Object.keys(value).some((key) => key !== "seed")
+    ) {
+        throw new TypeError("Harness ids must be configured with seededIds().");
+    }
+
+    return seededIds(value.seed);
+}
+
+export class WorldIds {
+    private counters = { fixtures: 0, items: 0 };
+    private baseline = { ...this.counters };
+
+    constructor(private readonly settings?: IdSettings) {}
+
+    fixture(): string {
+        return this.next("fixtures");
+    }
+
+    item(): string {
+        return this.next("items");
+    }
+
+    checkpoint(): void {
+        this.baseline = { ...this.counters };
+    }
+
+    capture(): IdPosition {
+        return { ...this.counters };
+    }
+
+    restore(position: IdPosition): void {
+        this.counters = { ...position };
+        this.checkpoint();
+    }
+
+    reset(): void {
+        this.counters = { ...this.baseline };
+    }
+
+    private next(stream: keyof WorldIds["counters"]): string {
+        if (this.counters[stream] >= Number.MAX_SAFE_INTEGER) {
+            throw new RangeError("The world ID sequence is exhausted.");
+        }
+
+        this.counters[stream] += 1;
+
+        if (!this.settings) {
+            return crypto.randomUUID().replaceAll("-", "").toUpperCase();
+        }
+
+        return new Bun.CryptoHasher("sha256")
+            .update(JSON.stringify([this.settings.seed, stream, this.counters[stream]]))
+            .digest("hex")
+            .slice(0, 32)
+            .toUpperCase();
+    }
+}

package/src/controls/observers.ts

@@ -0,0 +1,107 @@
+import type { ExecutionOutcome, ExecutionReport } from "../instrumentation/types.js";
+
+export type ExecutionObserver = (execution: ExecutionReport) => void;
+
+export interface Observation extends Disposable {}
+
+const observersMax = 128;
+
+export class ObserverError extends AggregateError {
+    override readonly name = "ObserverError";
+
+    constructor(
+        errors: readonly unknown[],
+        readonly requestId: string,
+        readonly outcome: ExecutionOutcome,
+    ) {
+        super(
+            errors,
+            `Execution observers failed after request '${requestId}' settled (${outcome}).`,
+        );
+    }
+}
+
+/** Callbacks observe settled reports; their failures never change the business transaction. */
+export class ExecutionObservers {
+    private readonly listeners = new Map<symbol, ExecutionObserver>();
+    private notifying = false;
+
+    get isNotifying(): boolean {
+        return this.notifying;
+    }
+
+    add(callback: ExecutionObserver): Observation {
+        if (
+            typeof callback !== "function" ||
+            Object.prototype.toString.call(callback) === "[object AsyncFunction]"
+        ) {
+            throw new TypeError("Execution observers must be synchronous functions.");
+        }
+
+        if (this.listeners.size >= observersMax) {
+            throw new RangeError("The world execution-observer limit was reached.");
+        }
+
+        const id = Symbol("observer");
+        this.listeners.set(id, callback);
+
+        return Object.freeze({
+            [Symbol.dispose]: () => {
+                this.listeners.delete(id);
+            },
+        });
+    }
+
+    notify(report: ExecutionReport): void {
+        if (this.notifying) {
+            throw new Error("Execution observer notification cannot reenter itself.");
+        }
+
+        const failures: unknown[] = [];
+        this.notifying = true;
+
+        try {
+            const listeners = [...this.listeners];
+
+            for (const [id, listener] of listeners) {
+                if (!this.listeners.has(id)) {
+                    continue;
+                }
+
+                try {
+                    // JavaScript callbacks can violate the synchronous TypeScript contract.
+                    // oxlint-disable-next-line typescript/no-confusing-void-expression
+                    const result: unknown = listener(report);
+                    assertSynchronousResult(result);
+                } catch (error) {
+                    failures.push(error);
+                }
+            }
+        } finally {
+            this.notifying = false;
+        }
+
+        if (failures.length > 0) {
+            throw new ObserverError(failures, report.requestId, report.outcome);
+        }
+    }
+
+    close(): void {
+        this.listeners.clear();
+    }
+}
+
+function assertSynchronousResult(value: unknown): void {
+    if (
+        value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        "then" in value &&
+        typeof value.then === "function"
+    ) {
+        void Promise.resolve(value).catch(() => {
+            // The invalid asynchronous callback is reported synchronously to the request owner.
+        });
+
+        throw new TypeError("Execution observers cannot return Promises.");
+    }
+}

package/src/controls/state.ts

@@ -0,0 +1,91 @@
+import { assertDataTree, cloneFrozenData } from "../core/data.js";
+import { workUnitsMax } from "../core/limits.js";
+import { PlatformError } from "../platform/errors.js";
+import { matches } from "../platform/query.js";
+import type { HarnessStorage, StorageValue, StoredItem } from "../storage/types.js";
+
+type Selector = Readonly<Record<string, StorageValue>>;
+
+export interface StateReader {
+    get(type: string, selector?: Selector): readonly StoredItem[];
+    getOne(type: string, selector: Selector): StoredItem;
+}
+
+/** Read persisted columns without entering the action pipeline or deriving response properties. */
+export function createStateReader(
+    storage: HarnessStorage,
+    assertReadable: () => void,
+): StateReader {
+    const get = (type: string, selector: Selector = {}): readonly StoredItem[] => {
+        assertReadable();
+
+        return readState(storage, type, selector);
+    };
+
+    return Object.freeze({
+        get,
+
+        getOne(type: string, selector: Selector): StoredItem {
+            const records = get(type, selector);
+            const record = records[0];
+
+            if (records.length !== 1 || !record) {
+                throw new PlatformError(
+                    "ItemResolution",
+                    `Expected one stored '${type}' record; found ${records.length}.`,
+                );
+            }
+
+            return record;
+        },
+    });
+}
+
+function readState(
+    storage: HarnessStorage,
+    type: string,
+    selector: Selector,
+): readonly StoredItem[] {
+    assertDataTree(selector, { allowArrays: false, allowUndefined: false });
+
+    if (selector === null || typeof selector !== "object" || typeof type !== "string" || !type) {
+        throw new TypeError("State reads require an ItemType and an object of stored values.");
+    }
+
+    const definition = storage.getItemType(type);
+
+    if (!definition) {
+        throw new PlatformError("MissingItemType", `ItemType '${type}' is not imported.`);
+    }
+
+    const predicates = Object.entries(selector).map(([name, value]) => {
+        if (value !== null && typeof value !== "string" && typeof value !== "number") {
+            throw new TypeError(`State selector '${name}' must be a stored scalar value.`);
+        }
+
+        const property = definition.properties.find((property) => property.name === name);
+
+        if (
+            name !== "id" &&
+            (!property || property.dataType === "foreign" || property.isFederated)
+        ) {
+            throw new PlatformError(
+                "InvalidStateSelector",
+                `'${type}.${name}' is not a stored property.`,
+            );
+        }
+
+        return { name, value };
+    });
+    const records = storage.listItems(definition.name);
+
+    if (records.length * Math.max(1, predicates.length) > workUnitsMax) {
+        throw new PlatformError("StateReadLimit", "The state query exceeds its work limit.");
+    }
+
+    const selected = records.filter((record) =>
+        predicates.every((predicate) => matches(storage, definition, record, predicate)),
+    );
+
+    return cloneFrozenData(selected);
+}

package/src/controls/targets.ts

@@ -0,0 +1,123 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import { object } from "../items/codec.js";
+import { Item } from "../items/item.js";
+import { validateParameters } from "../mocks/parameters.js";
+import { properties } from "../mocks/registry.js";
+import type { MockValue } from "../mocks/types.js";
+import { PlatformCatalog } from "../platform/catalog.js";
+import { appliedItem } from "../platform/request.js";
+import type { SourceDefinition } from "../platform/trace.js";
+import type { CatalogEntry, HarnessStorage } from "../storage/types.js";
+
+export interface InjectionDetails {
+    readonly kind: "action" | "method" | "sql";
+    readonly name: string;
+    readonly source?: SourceLocation;
+    readonly definition?: SourceDefinition;
+    readonly sourceHash?: string;
+}
+
+export interface InjectionTarget extends InjectionDetails {
+    readonly aliases: readonly (string | true)[];
+    readonly action?: string;
+    readonly values: Readonly<Record<string, MockValue>>;
+}
+
+/** Resolve invocation metadata without compiling or running the selected implementation. */
+export function injectionTarget(
+    storage: HarnessStorage,
+    operation: string,
+    input: unknown,
+): InjectionTarget | undefined {
+    const item = appliedItem(operation, input);
+
+    if (item && item.getItemCount() === 1) {
+        return actionTarget(storage, item);
+    }
+
+    if (
+        operation === "platform.method" &&
+        object(input) &&
+        typeof input.name === "string" &&
+        input.context instanceof Item
+    ) {
+        const entry = new PlatformCatalog(storage).methodEntry(input.name);
+        const name =
+            typeof entry?.properties.name === "string" ? entry.properties.name : input.name;
+
+        return {
+            kind: "method",
+            name,
+            aliases: [input.name, name, ...(entry ? [entry.id] : [])],
+            values: properties(input.context),
+            ...sourceDetails(entry, "Method", "method_code"),
+        };
+    }
+
+    if (
+        operation === "platform.sql" &&
+        object(input) &&
+        typeof input.method === "string" &&
+        typeof input.query === "string" &&
+        object(input.values)
+    ) {
+        return {
+            kind: "sql",
+            name: `SQL: ${input.method}`,
+            aliases: [true],
+            values: inlineValues(input.values, input.method, input.query),
+        };
+    }
+
+    return undefined;
+}
+
+function actionTarget(storage: HarnessStorage, item: Item): InjectionTarget {
+    const type = item.getType();
+    const action = item.getAction() || "get";
+
+    if (type.toLowerCase() === "sql" && /^sql\s+process$/iu.test(action)) {
+        const name = item.getProperty("name");
+        const entry = storage
+            .listCatalogEntries("SQL")
+            .find((entry) => entry.properties.name === name);
+
+        return {
+            kind: "sql",
+            name,
+            aliases: [name],
+            values: properties(item),
+            ...sourceDetails(entry, "SQL", "sqlserver_body"),
+        };
+    }
+
+    return {
+        kind: "action",
+        name: `${type}.${action}`,
+        aliases: [type],
+        action,
+        values: properties(item),
+    };
+}
+
+function sourceDetails(entry: CatalogEntry | undefined, type: "Method" | "SQL", body: string) {
+    if (!entry) {
+        return {};
+    }
+
+    const code = entry.properties[body];
+
+    return {
+        source: entry.source,
+        definition: { type, id: entry.id },
+        ...(typeof code === "string"
+            ? { sourceHash: new Bun.CryptoHasher("sha256").update(code).digest("hex") }
+            : {}),
+    };
+}
+
+function inlineValues(values: Record<string, unknown>, method: string, query: string) {
+    validateParameters(values, "SQL invocation parameters");
+
+    return { ...values, method, query };
+}

package/src/controls/values.ts

@@ -0,0 +1,44 @@
+import { WorldClock, clockSettings } from "./clock.js";
+import type { ClockSettings } from "./clock.js";
+import { WorldIds, idSettings } from "./ids.js";
+import type { IdPosition, IdSettings } from "./ids.js";
+
+export interface ValueSettings {
+    readonly clock?: ClockSettings;
+    readonly ids?: IdSettings;
+}
+
+export interface ValuePosition {
+    readonly clock: number | undefined;
+    readonly ids: IdPosition;
+}
+
+/** Own only generated values. Transaction rollback does not rewind already-issued identities. */
+export class WorldValues {
+    readonly clock: WorldClock;
+    readonly ids: WorldIds;
+
+    constructor(settings: ValueSettings) {
+        this.clock = new WorldClock(clockSettings(settings.clock));
+        this.ids = new WorldIds(idSettings(settings.ids));
+    }
+
+    checkpoint(): void {
+        this.clock.checkpoint();
+        this.ids.checkpoint();
+    }
+
+    capture(): ValuePosition {
+        return { clock: this.clock.capture(), ids: this.ids.capture() };
+    }
+
+    restore(position: ValuePosition): void {
+        this.clock.restore(position.clock);
+        this.ids.restore(position.ids);
+    }
+
+    reset(): void {
+        this.clock.reset();
+        this.ids.reset();
+    }
+}

package/src/controls/world.ts

@@ -0,0 +1,31 @@
+import type { RuntimeObserver } from "../core/types.js";
+import { ExecutionRecorder } from "../instrumentation/recorder.js";
+import type { HarnessStorage } from "../storage/types.js";
+import { executionObserver } from "./execution.js";
+import { FailureRegistry } from "./failures.js";
+import { ExecutionObservers } from "./observers.js";
+import { WorldValues } from "./values.js";
+import type { ValueSettings } from "./values.js";
+
+/** Each world owns its controls, report retention and subscription lifetimes. */
+export class WorldControls {
+    readonly values: WorldValues;
+    readonly recorder: ExecutionRecorder;
+    readonly failures: FailureRegistry;
+    readonly observers = new ExecutionObservers();
+    readonly observer: RuntimeObserver;
+
+    constructor(storage: HarnessStorage, settings: ValueSettings) {
+        this.values = new WorldValues(settings);
+        this.recorder = new ExecutionRecorder({}, () => this.values.clock.now());
+        this.failures = new FailureRegistry((execution, evidence, target) => {
+            this.recorder.injected(execution, evidence, target);
+        });
+        this.observer = executionObserver(storage, this.recorder, this.failures, this.observers);
+    }
+
+    close(): void {
+        this.failures.reset();
+        this.observers.close();
+    }
+}

package/src/core/budget.ts

@@ -0,0 +1,25 @@
+/** A shared owner charges related phases against one finite work allowance. */
+export class WorkBudget {
+    private used = 0;
+
+    constructor(
+        private readonly maximum: number,
+        private readonly exceeded: () => Error,
+    ) {
+        if (!Number.isSafeInteger(maximum) || maximum < 1) {
+            throw new TypeError("A work budget must be a positive safe integer.");
+        }
+    }
+
+    spend(units = 1): void {
+        if (!Number.isSafeInteger(units) || units < 0) {
+            throw new Error("Work charges must be nonnegative safe integers.");
+        }
+
+        if (units > this.maximum - this.used) {
+            throw this.exceeded();
+        }
+
+        this.used += units;
+    }
+}

package/src/core/context.ts

@@ -0,0 +1,68 @@
+import { RuntimeError } from "./errors.js";
+import { requestDepthMax } from "./limits.js";
+import type { ExecutionContext } from "./types.js";
+
+interface ContextOwner {
+    readonly assertActive: () => void;
+    readonly spend: (units: number) => void;
+    readonly parent: ExecutionContext | undefined;
+}
+
+const contexts = new WeakMap<ExecutionContext, ContextOwner>();
+
+export function registerContext(
+    context: ExecutionContext,
+    assertActive: () => void,
+    spend: (units: number) => void,
+    parent?: ExecutionContext,
+): void {
+    contexts.set(context, { assertActive, spend, parent });
+}
+
+/** Internal scopes follow the runtime's actual ancestry, including extension operations. */
+export function hasContextAncestor(
+    context: ExecutionContext,
+    matches: (ancestor: ExecutionContext) => boolean,
+): boolean {
+    assertActiveContext(context);
+    let current: ExecutionContext | undefined = context;
+
+    for (let depth = 0; current && depth <= requestDepthMax; depth += 1) {
+        if (matches(current)) {
+            return true;
+        }
+
+        current = contexts.get(current)?.parent;
+    }
+
+    if (current) {
+        throw new RuntimeError("InvalidOperation", "Execution ancestry exceeds its depth limit.");
+    }
+
+    return false;
+}
+
+/** Internal ports must reject late callbacks before they touch data or instrumentation. */
+export function assertActiveContext(context: ExecutionContext): void {
+    const owner = contexts.get(context);
+
+    if (!owner) {
+        throw new RuntimeError(
+            "InvalidOperation",
+            "The execution context does not belong to a runtime.",
+        );
+    }
+
+    owner.assertActive();
+}
+
+export function spendContext(context: ExecutionContext, units = 1): void {
+    assertActiveContext(context);
+    const owner = contexts.get(context);
+
+    if (!owner) {
+        throw new Error("An active context must have an owner.");
+    }
+
+    owner.spend(units);
+}