@openprose/reactor-cradle 0.1.0-rc.1

package/dist/world/synthetic-world.js

@@ -0,0 +1,449 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyntheticWorldConnectorV0 = exports.STATIC_SURPRISE_PROFILE_V0 = exports.SYNTHETIC_WORLD_VERSION_V0 = exports.SYNTHETIC_WORLD_SCHEMA_V0 = void 0;
+exports.createSyntheticWorldV0 = createSyntheticWorldV0;
+exports.createSyntheticWorldConnectorV0 = createSyntheticWorldConnectorV0;
+const node_crypto_1 = require("node:crypto");
+exports.SYNTHETIC_WORLD_SCHEMA_V0 = "openprose.reactor.synthetic-world";
+exports.SYNTHETIC_WORLD_VERSION_V0 = 0;
+const ISO_INSTANT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+exports.STATIC_SURPRISE_PROFILE_V0 = Object.freeze({ kind: "static" });
+class SyntheticWorldConnectorV0 {
+    #profile;
+    #sources = new Map();
+    #history = [];
+    #asOf;
+    #asOfEpochMs;
+    constructor(input) {
+        const profile = cloneProfile(input.profile);
+        if (profile.kind === "adversarial-silent") {
+            throw new Error(`synthetic world surprise profile ${profile.kind} is typed but not implemented in C2`);
+        }
+        this.#profile = profile;
+        this.#asOfEpochMs = parseReplayableInstant(input.initial_as_of, "initial_as_of");
+        this.#asOf = canonicalizeInstant(input.initial_as_of, this.#asOfEpochMs);
+        for (const source of input.sources) {
+            this.#addSource(source);
+        }
+    }
+    read(request) {
+        const asOfEpochMs = parseReplayableInstant(request.as_of, "as_of");
+        const asOf = canonicalizeInstant(request.as_of, asOfEpochMs);
+        assertNotAfter(asOfEpochMs, this.#asOfEpochMs, "read as_of", "world time");
+        const source = this.#readSource(request.source_id);
+        const revision = readRevisionAt(source, asOfEpochMs, asOf);
+        const surprise = createZeroSurpriseReport({
+            profile: this.#profile.kind,
+            as_of: asOf,
+            event_index: this.#history.length,
+        });
+        const readPayload = this.#readPayload({
+            source,
+            revision,
+            as_of: asOf,
+            surprise,
+        });
+        return {
+            payload: deepFreezeJsonObject(readPayload),
+        };
+    }
+    advance(input) {
+        const nextEpochMs = parseReplayableInstant(input.as_of, "as_of");
+        const asOf = canonicalizeInstant(input.as_of, nextEpochMs);
+        assertNotBefore(nextEpochMs, this.#asOfEpochMs, "advance as_of", "world time");
+        this.#asOf = asOf;
+        this.#asOfEpochMs = nextEpochMs;
+        if (input.kind === "time") {
+            const advanceInput = input.event_id === undefined
+                ? {
+                    kind: "time",
+                    as_of: asOf,
+                }
+                : {
+                    kind: "time",
+                    as_of: asOf,
+                    event_id: input.event_id,
+                };
+            return this.#recordAdvance(advanceInput);
+        }
+        const source = this.#readSource(input.source_id);
+        let materialChange = false;
+        if (input.payload !== undefined) {
+            const payload = createPayloadSnapshot(input.payload);
+            const current = latestRevision(source);
+            if (payload.canonical !== current.payload_canonical) {
+                materialChange = true;
+                assertMaterialChangeAllowed({
+                    profile: this.#profile,
+                    source_event_ordinal: nextSourceEventOrdinal(this.#history),
+                });
+                source.revisions.push(createSourceRevision({
+                    material_version: current.material_version + 1,
+                    materialized_at: asOf,
+                    materialized_at_epoch_ms: nextEpochMs,
+                    payload,
+                    payload_hash: payloadContentHash(payload.canonical),
+                }));
+            }
+        }
+        const advanceInput = input.event_id === undefined
+            ? {
+                kind: "source-event",
+                as_of: asOf,
+                source_id: source.source_id,
+            }
+            : {
+                kind: "source-event",
+                as_of: asOf,
+                event_id: input.event_id,
+                source_id: source.source_id,
+            };
+        return this.#recordAdvance({
+            ...advanceInput,
+            material_change: materialChange,
+        });
+    }
+    currentAsOf() {
+        return this.#asOf;
+    }
+    history() {
+        return Object.freeze(this.#history.map((record) => cloneAdvanceRecord(record)));
+    }
+    #addSource(seed) {
+        assertNonEmptyString(seed.source_id, "source_id");
+        if (this.#sources.has(seed.source_id)) {
+            throw new Error(`duplicate synthetic world source_id ${seed.source_id}`);
+        }
+        if (seed.payload_hash !== undefined) {
+            assertNonEmptyString(seed.payload_hash, "payload_hash");
+        }
+        const sourceAsOfRaw = seed.materialized_at ?? this.#asOf;
+        const sourceEpochMs = parseReplayableInstant(sourceAsOfRaw, `source ${seed.source_id} materialized_at`);
+        assertNotAfter(sourceEpochMs, this.#asOfEpochMs, `source ${seed.source_id} materialized_at`, "initial_as_of");
+        const payload = createPayloadSnapshot(seed.payload);
+        const revisionBase = {
+            material_version: 0,
+            materialized_at: canonicalizeInstant(sourceAsOfRaw, sourceEpochMs),
+            materialized_at_epoch_ms: sourceEpochMs,
+            payload: payload.value,
+            payload_canonical: payload.canonical,
+        };
+        const revision = seed.payload_hash === undefined
+            ? revisionBase
+            : { ...revisionBase, payload_hash: seed.payload_hash };
+        this.#sources.set(seed.source_id, {
+            source_id: seed.source_id,
+            revisions: [revision],
+        });
+    }
+    #readSource(sourceId) {
+        assertNonEmptyString(sourceId, "source_id");
+        const source = this.#sources.get(sourceId);
+        if (source === undefined) {
+            throw new Error(`unknown synthetic world source_id ${sourceId}`);
+        }
+        return source;
+    }
+    #recordAdvance(input) {
+        const eventIndex = this.#history.length;
+        const eventId = input.event_id ?? `synthetic-world-event-${eventIndex}`;
+        assertNonEmptyString(eventId, "event_id");
+        const surpriseEvents = createSurpriseEvents({
+            profile: this.#profile.kind,
+            as_of: input.as_of,
+            event_id: eventId,
+            material_change: input.material_change ?? false,
+            ...(input.source_id === undefined ? {} : { source_id: input.source_id }),
+        });
+        const base = {
+            kind: input.kind,
+            event_id: eventId,
+            event_index: eventIndex,
+            as_of: input.as_of,
+            surprise: createSurpriseReport({
+                profile: this.#profile.kind,
+                as_of: input.as_of,
+                event_index: eventIndex,
+                surprise_events: surpriseEvents,
+            }),
+        };
+        const record = input.source_id === undefined
+            ? base
+            : { ...base, source_id: input.source_id };
+        this.#history.push(record);
+        return cloneAdvanceRecord(record);
+    }
+    #readPayload(input) {
+        const base = {
+            schema: exports.SYNTHETIC_WORLD_SCHEMA_V0,
+            v: exports.SYNTHETIC_WORLD_VERSION_V0,
+            profile: this.#profile.kind,
+            source_id: input.source.source_id,
+            as_of: input.as_of,
+            materialized_at: input.revision.materialized_at,
+            material_version: input.revision.material_version,
+            state: cloneJsonValue(input.revision.payload),
+            surprise: input.surprise,
+        };
+        return input.revision.payload_hash === undefined
+            ? base
+            : {
+                ...base,
+                payload_hash: input.revision.payload_hash,
+            };
+    }
+}
+exports.SyntheticWorldConnectorV0 = SyntheticWorldConnectorV0;
+function createSyntheticWorldV0(input) {
+    return new SyntheticWorldConnectorV0({
+        initial_as_of: input.initial_instant,
+        profile: normalizeProfile(input.profile),
+        sources: input.sources.map((source) => normalizeCreateSource(source)),
+    });
+}
+function createSyntheticWorldConnectorV0(input) {
+    if (input instanceof SyntheticWorldConnectorV0) {
+        return input;
+    }
+    return new SyntheticWorldConnectorV0(input);
+}
+function normalizeProfile(profile) {
+    if (typeof profile !== "string") {
+        return profile;
+    }
+    switch (profile) {
+        case "static":
+            return exports.STATIC_SURPRISE_PROFILE_V0;
+        case "periodic-surprise":
+            throw new Error("periodic-surprise profile requires an explicit every_events config");
+        case "adversarial-silent":
+            throw new Error("adversarial-silent profile requires an explicit silent_after_events config");
+    }
+}
+function normalizeCreateSource(source) {
+    const base = {
+        source_id: source.id,
+        payload: source.payload,
+    };
+    const withPayloadHash = source.payload_hash === undefined
+        ? base
+        : { ...base, payload_hash: source.payload_hash };
+    return source.materialized_at === undefined
+        ? withPayloadHash
+        : { ...withPayloadHash, materialized_at: source.materialized_at };
+}
+function createZeroSurpriseReport(input) {
+    return createSurpriseReport({ ...input, surprise_events: [] });
+}
+function createSurpriseReport(input) {
+    return deepFreezeJsonObject({
+        profile: input.profile,
+        as_of: input.as_of,
+        event_index: input.event_index,
+        surprise_count: input.surprise_events.length,
+        material_change: input.surprise_events.some((event) => event.kind === "material-change"),
+        surprise_events: input.surprise_events.map((event) => ({ ...event })),
+    });
+}
+function createSurpriseEvents(input) {
+    if (!input.material_change || input.source_id === undefined) {
+        return [];
+    }
+    return Object.freeze([
+        {
+            kind: "material-change",
+            source_id: input.source_id,
+            as_of: input.as_of,
+            event_id: input.event_id,
+            profile: input.profile,
+        },
+    ]);
+}
+function cloneAdvanceRecord(record) {
+    const base = {
+        kind: record.kind,
+        event_id: record.event_id,
+        event_index: record.event_index,
+        as_of: record.as_of,
+        surprise: cloneSurpriseReport(record.surprise),
+    };
+    return Object.freeze(record.source_id === undefined
+        ? base
+        : { ...base, source_id: record.source_id });
+}
+function cloneSurpriseReport(report) {
+    return deepFreezeJsonObject({
+        profile: report.profile,
+        as_of: report.as_of,
+        event_index: report.event_index,
+        surprise_count: report.surprise_count,
+        material_change: report.material_change,
+        surprise_events: report.surprise_events.map((event) => ({ ...event })),
+    });
+}
+function readRevisionAt(source, asOfEpochMs, asOf) {
+    for (let index = source.revisions.length - 1; index >= 0; index -= 1) {
+        const revision = source.revisions[index];
+        if (revision !== undefined &&
+            revision.materialized_at_epoch_ms <= asOfEpochMs) {
+            return revision;
+        }
+    }
+    throw new Error(`source_id ${source.source_id} has no synthetic world state at ${asOf}`);
+}
+function latestRevision(source) {
+    const revision = source.revisions[source.revisions.length - 1];
+    if (revision === undefined) {
+        throw new Error(`source_id ${source.source_id} has no revisions`);
+    }
+    return revision;
+}
+function createSourceRevision(input) {
+    const base = {
+        material_version: input.material_version,
+        materialized_at: input.materialized_at,
+        materialized_at_epoch_ms: input.materialized_at_epoch_ms,
+        payload: input.payload.value,
+        payload_canonical: input.payload.canonical,
+    };
+    return input.payload_hash === undefined
+        ? base
+        : { ...base, payload_hash: input.payload_hash };
+}
+function nextSourceEventOrdinal(history) {
+    return history.filter((record) => record.kind === "source-event").length + 1;
+}
+function assertMaterialChangeAllowed(input) {
+    switch (input.profile.kind) {
+        case "static":
+            throw new Error("static surprise profile cannot apply material source changes");
+        case "periodic-surprise":
+            if (input.source_event_ordinal % input.profile.every_events !== 0) {
+                throw new Error(`periodic-surprise material changes are only allowed on every ${input.profile.every_events} source events`);
+            }
+            return;
+    }
+}
+function cloneProfile(profile) {
+    switch (profile.kind) {
+        case "static":
+            return exports.STATIC_SURPRISE_PROFILE_V0;
+        case "periodic-surprise":
+            if (!Number.isSafeInteger(profile.every_events) ||
+                profile.every_events <= 0) {
+                throw new RangeError("periodic-surprise every_events must be a positive safe integer");
+            }
+            return Object.freeze({
+                kind: "periodic-surprise",
+                every_events: profile.every_events,
+            });
+        case "adversarial-silent":
+            return Object.freeze({
+                kind: "adversarial-silent",
+                silent_after_events: Object.freeze([...profile.silent_after_events]),
+            });
+    }
+}
+function createPayloadSnapshot(payload) {
+    const canonical = renderCanonical(payload);
+    return {
+        value: cloneJsonValue(payload),
+        canonical,
+    };
+}
+function payloadContentHash(canonical) {
+    const digest = (0, node_crypto_1.createHash)("sha256").update(canonical).digest("hex");
+    return `sha256:${digest}`;
+}
+function cloneJsonValue(value) {
+    return deepFreezeJsonValue(JSON.parse(renderCanonical(value)));
+}
+function deepFreezeJsonObject(value) {
+    return deepFreezeJsonValue(value);
+}
+function deepFreezeJsonValue(value) {
+    if (value !== null && typeof value === "object") {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                deepFreezeJsonValue(item);
+            }
+        }
+        else {
+            for (const item of Object.values(value)) {
+                deepFreezeJsonValue(item);
+            }
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+function parseReplayableInstant(instant, label) {
+    if (!ISO_INSTANT_PATTERN.test(instant)) {
+        throw new RangeError(`${label} must be an ISO-8601 UTC instant`);
+    }
+    const epochMs = Date.parse(instant);
+    if (!Number.isFinite(epochMs)) {
+        throw new RangeError(`${label} must be a valid ISO-8601 UTC instant`);
+    }
+    const canonical = new Date(epochMs).toISOString();
+    if (instant !== canonical && instant !== canonical.replace(".000Z", "Z")) {
+        throw new RangeError(`${label} must be a valid ISO-8601 UTC instant`);
+    }
+    return epochMs;
+}
+function canonicalizeInstant(instant, epochMs) {
+    const canonical = new Date(epochMs).toISOString();
+    return instant === canonical ? instant : canonical;
+}
+function assertNotBefore(actualEpochMs, minimumEpochMs, actualLabel, minimumLabel) {
+    if (actualEpochMs < minimumEpochMs) {
+        throw new RangeError(`${actualLabel} must not be before ${minimumLabel}`);
+    }
+}
+function assertNotAfter(actualEpochMs, maximumEpochMs, actualLabel, maximumLabel) {
+    if (actualEpochMs > maximumEpochMs) {
+        throw new RangeError(`${actualLabel} must not be after ${maximumLabel}`);
+    }
+}
+function assertNonEmptyString(value, label) {
+    if (value.length === 0) {
+        throw new Error(`${label} must be non-empty`);
+    }
+}
+function renderCanonical(value) {
+    if (value === null) {
+        return "null";
+    }
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value)) {
+                throw new TypeError("Cannot canonicalize non-finite numbers");
+            }
+            return JSON.stringify(value);
+        case "string":
+            return JSON.stringify(value);
+        case "object":
+            if (Array.isArray(value)) {
+                return `[${value.map((item) => renderCanonical(item)).join(",")}]`;
+            }
+            return renderCanonicalObject(value);
+        case "undefined":
+        case "bigint":
+        case "function":
+        case "symbol":
+            throw new TypeError(`Cannot canonicalize ${typeof value}`);
+    }
+}
+function renderCanonicalObject(value) {
+    const fields = [];
+    for (const key of Object.keys(value).sort()) {
+        const item = value[key];
+        if (item === undefined) {
+            throw new TypeError(`Cannot canonicalize undefined field ${key}`);
+        }
+        fields.push(`${JSON.stringify(key)}:${renderCanonical(item)}`);
+    }
+    return `{${fields.join(",")}}`;
+}

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@openprose/reactor-cradle",
+  "version": "0.1.0-rc.1",
+  "description": "Deterministic Cradle test harness for the OpenProse Reactor.",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./assert": {
+      "types": "./dist/assert/index.d.ts",
+      "default": "./dist/assert/index.js"
+    },
+    "./eval": {
+      "types": "./dist/eval/index.d.ts",
+      "default": "./dist/eval/index.js"
+    },
+    "./spikes": {
+      "types": "./dist/spikes/index.d.ts",
+      "default": "./dist/spikes/index.js"
+    },
+    "./spikes/live-refresh": {
+      "types": "./dist/spikes/live-refresh.d.ts",
+      "default": "./dist/spikes/live-refresh.js"
+    },
+    "./spikes/k1-ensemble-spread": {
+      "types": "./dist/spikes/k1-ensemble-spread.d.ts",
+      "default": "./dist/spikes/k1-ensemble-spread.js"
+    },
+    "./spikes/k2-policy-author": {
+      "types": "./dist/spikes/k2-policy-author.d.ts",
+      "default": "./dist/spikes/k2-policy-author.js"
+    },
+    "./doubles/clock": {
+      "types": "./dist/doubles/clock.d.ts",
+      "default": "./dist/doubles/clock.js"
+    },
+    "./doubles/storage": {
+      "types": "./dist/doubles/storage.d.ts",
+      "default": "./dist/doubles/storage.js"
+    },
+    "./policy-author": {
+      "types": "./dist/policy-author/index.d.ts",
+      "default": "./dist/policy-author/index.js"
+    },
+    "./policy-drift": {
+      "types": "./dist/policy-drift/index.d.ts",
+      "default": "./dist/policy-drift/index.js"
+    },
+    "./policy-replay": {
+      "types": "./dist/policy-replay/index.d.ts",
+      "default": "./dist/policy-replay/index.js"
+    },
+    "./recompile": {
+      "types": "./dist/recompile/index.d.ts",
+      "default": "./dist/recompile/index.js"
+    },
+    "./release-parity": {
+      "types": "./dist/release-parity/index.d.ts",
+      "default": "./dist/release-parity/index.js"
+    },
+    "./release-candidate": {
+      "types": "./dist/release-candidate/index.d.ts",
+      "default": "./dist/release-candidate/index.js"
+    },
+    "./rollback": {
+      "types": "./dist/rollback/index.d.ts",
+      "default": "./dist/rollback/index.js"
+    },
+    "./replay/model-gateway": {
+      "types": "./dist/replay/model-gateway.d.ts",
+      "default": "./dist/replay/model-gateway.js"
+    },
+    "./replay/parity": {
+      "types": "./dist/replay/parity.d.ts",
+      "default": "./dist/replay/parity.js"
+    },
+    "./scenario/parser": {
+      "types": "./dist/scenario/parser.d.ts",
+      "default": "./dist/scenario/parser.js"
+    },
+    "./scenario/runner": {
+      "types": "./dist/scenario/runner.d.ts",
+      "default": "./dist/scenario/runner.js"
+    },
+    "./scenario/time": {
+      "types": "./dist/scenario/time.d.ts",
+      "default": "./dist/scenario/time.js"
+    },
+    "./scenario/types": {
+      "types": "./dist/scenario/types.d.ts",
+      "default": "./dist/scenario/types.js"
+    },
+    "./world": {
+      "types": "./dist/world/index.d.ts",
+      "default": "./dist/world/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openprose/prose.git",
+    "directory": "packages/reactor-cradle"
+  },
+  "dependencies": {
+    "@openprose/reactor": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "pnpm --dir ../.. --filter @openprose/reactor build && tsc -p tsconfig.build.json",
+    "typecheck": "pnpm --dir ../.. --filter @openprose/reactor build && tsc --noEmit -p tsconfig.json",
+    "test:runtime": "pnpm build && node --test $(find dist -name '*.test.js' -type f | sort)",
+    "test": "pnpm typecheck && pnpm test:runtime"
+  }
+}