@velum-labs/routekit-eval-store 1.0.26 → 1.1.0

package/dist/effect-api.d.ts

@@ -1,3 +1,5 @@
 export type { RoutingActivationPublication } from "./routing-activation.js";
-export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingActivationStore } from "./routing-activation.js";
+export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingDeploymentConflictError, RoutingActivationStore } from "./routing-activation.js";
 export { EvalStore, makeEvalStore } from "./store.js";
+export * from "./experiment-artifacts.js";
+export * from "./services/experiment-artifacts/service.js";

package/dist/effect-api.js

@@ -1,2 +1,4 @@
-export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingActivationStore } from "./routing-activation.js";
+export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingDeploymentConflictError, RoutingActivationStore } from "./routing-activation.js";
 export { EvalStore, makeEvalStore } from "./store.js";
+export * from "./experiment-artifacts.js";
+export * from "./services/experiment-artifacts/service.js";

package/dist/experiment-artifacts.d.ts

@@ -0,0 +1,19 @@
+import { RouteKitFailure } from "@velum-labs/routekit-runtime/effect";
+import { Effect, FileSystem, Path } from "effect";
+export declare const EXPERIMENT_ARTIFACT_MAX_BYTES: number;
+export type ExperimentArtifactVisibility = "ordinary" | "private";
+export type ExperimentArtifactReference = Readonly<{
+    runId: string;
+    name: string;
+    visibility: ExperimentArtifactVisibility;
+    path: string;
+}>;
+export declare class ExperimentArtifactError extends RouteKitFailure {
+}
+export declare class FileExperimentArtifactStore {
+    readonly root: string;
+    constructor(root: string);
+    write(runId: string, name: string, value: unknown, visibility?: ExperimentArtifactVisibility): Effect.Effect<ExperimentArtifactReference, Error, FileSystem.FileSystem | Path.Path>;
+    read(runId: string, name: string, visibility?: ExperimentArtifactVisibility): Effect.Effect<string | undefined, Error, FileSystem.FileSystem | Path.Path>;
+}
+export declare function makeFileExperimentArtifactStore(root: string): FileExperimentArtifactStore;

package/dist/experiment-artifacts.js

@@ -0,0 +1,61 @@
+import { RouteKitFailure, writeFileAtomicEffect } from "@velum-labs/routekit-runtime/effect";
+import { Effect, FileSystem, Path } from "effect";
+export const EXPERIMENT_ARTIFACT_MAX_BYTES = 16 * 1024 * 1024;
+const SEGMENT = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u;
+export class ExperimentArtifactError extends RouteKitFailure {
+}
+function validateSegment(value, label) {
+    if (!SEGMENT.test(value) || value === "." || value === "..")
+        throw new ExperimentArtifactError({ message: `${label} is not a valid artifact path segment` });
+}
+export class FileExperimentArtifactStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    write(runId, name, value, visibility = "ordinary") {
+        const root = this.root;
+        return Effect.gen(function* () {
+            validateSegment(runId, "run ID");
+            validateSegment(name, "artifact name");
+            const raw = typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`;
+            if (Buffer.byteLength(raw, "utf8") > EXPERIMENT_ARTIFACT_MAX_BYTES)
+                return yield* new ExperimentArtifactError({
+                    message: "experiment artifact exceeds the size limit"
+                });
+            const fs = yield* FileSystem.FileSystem;
+            const paths = yield* Path.Path;
+            const directory = paths.join(root, visibility, runId);
+            const path = paths.join(directory, name);
+            yield* fs.makeDirectory(directory, { recursive: true, mode: 0o700 });
+            yield* fs.chmod(directory, 0o700).pipe(Effect.ignore);
+            if (yield* fs.exists(path))
+                return yield* new ExperimentArtifactError({
+                    message: `experiment artifact ${runId}/${name} is immutable and already exists`
+                });
+            yield* writeFileAtomicEffect(path, raw, { mode: 0o600 });
+            return { runId, name, visibility, path };
+        });
+    }
+    read(runId, name, visibility = "ordinary") {
+        const root = this.root;
+        return Effect.gen(function* () {
+            validateSegment(runId, "run ID");
+            validateSegment(name, "artifact name");
+            const fs = yield* FileSystem.FileSystem;
+            const paths = yield* Path.Path;
+            const path = paths.join(root, visibility, runId, name);
+            if (!(yield* fs.exists(path)))
+                return undefined;
+            const info = yield* fs.stat(path);
+            if (Number(info.size) > EXPERIMENT_ARTIFACT_MAX_BYTES)
+                return yield* new ExperimentArtifactError({
+                    message: "experiment artifact exceeds the size limit"
+                });
+            return yield* fs.readFileString(path);
+        });
+    }
+}
+export function makeFileExperimentArtifactStore(root) {
+    return new FileExperimentArtifactStore(root);
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export type { RoutingActivationPublication } from "./routing-activation.js";
-export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingActivationStore } from "./routing-activation.js";
+export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingDeploymentConflictError, RoutingActivationStore } from "./routing-activation.js";
 export { EvalStore, makeEvalStore } from "./store.js";
+export * from "./experiment-artifacts.js";
+export * from "./services/experiment-artifacts/service.js";

package/dist/index.js

@@ -1,2 +1,4 @@
-export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingActivationStore } from "./routing-activation.js";
+export { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingDeploymentConflictError, RoutingActivationStore } from "./routing-activation.js";
 export { EvalStore, makeEvalStore } from "./store.js";
+export * from "./experiment-artifacts.js";
+export * from "./services/experiment-artifacts/service.js";

package/dist/routing-activation.d.ts

@@ -1,23 +1,28 @@
-import { PublishedRoutingActivation } from "@velum-labs/routekit-eval-contracts";
+import { type AnyPublishedRoutingActivation as AnyPublishedRoutingActivationType, type PublishedRoutingActivation as PublishedRoutingActivationType, type RoutingDeploymentStateV1 as RoutingDeploymentStateV1Type } from "@velum-labs/routekit-eval-contracts";
 import { Effect, FileSystem, Path } from "effect";
 export declare const ROUTING_ACTIVATION_MAX_BYTES: number;
-export type RoutingActivationPublication = Omit<PublishedRoutingActivation, "version" | "generatedAt">;
+export type RoutingActivationPublication = Omit<PublishedRoutingActivationType, "version" | "generatedAt">;
 export declare class RoutingActivationConflictError extends Error {
     readonly expectedEvidenceDigest: string | undefined;
     readonly actualEvidenceDigest: string | undefined;
     constructor(expectedEvidenceDigest: string | undefined, actualEvidenceDigest: string | undefined);
 }
+export declare class RoutingDeploymentConflictError extends Error {
+    readonly slot: "authoritative" | "previousAuthoritative";
+    readonly expectedRevisionDigest: string | null;
+    readonly actualRevisionDigest: string | null;
+    constructor(slot: "authoritative" | "previousAuthoritative", expectedRevisionDigest: string | null, actualRevisionDigest: string | null);
+}
 export declare class RoutingActivationStore {
     #private;
     readonly root: string;
     constructor(root: string);
-    read(): Effect.Effect<PublishedRoutingActivation | undefined, Error, FileSystem.FileSystem | Path.Path>;
-    readPrevious(): Effect.Effect<PublishedRoutingActivation | undefined, Error, FileSystem.FileSystem | Path.Path>;
-    publish(publication: RoutingActivationPublication): Effect.Effect<PublishedRoutingActivation, Error, FileSystem.FileSystem | Path.Path>;
-    /**
-     * Publish only if the active evidence generation still matches the caller's
-     * view. `undefined` means the caller expects no active publication.
-     */
-    publishIfCurrent(publication: RoutingActivationPublication, expectedEvidenceDigest: string | undefined): Effect.Effect<PublishedRoutingActivation, Error, FileSystem.FileSystem | Path.Path>;
+    read(): Effect.Effect<PublishedRoutingActivationType | undefined, Error, FileSystem.FileSystem | Path.Path>;
+    readPrevious(): Effect.Effect<PublishedRoutingActivationType | undefined, Error, FileSystem.FileSystem | Path.Path>;
+    readDeployment(): Effect.Effect<RoutingDeploymentStateV1Type, Error, FileSystem.FileSystem | Path.Path>;
+    publish(publication: RoutingActivationPublication): Effect.Effect<PublishedRoutingActivationType, Error, FileSystem.FileSystem | Path.Path>;
+    publishIfCurrent(publication: RoutingActivationPublication, expectedEvidenceDigest: string | undefined): Effect.Effect<PublishedRoutingActivationType, Error, FileSystem.FileSystem | Path.Path>;
+    installAuthoritative(activation: AnyPublishedRoutingActivationType, expectedAuthoritativeRevisionDigest: string | null, expectedPreviousAuthoritativeRevisionDigest: string | null): Effect.Effect<RoutingDeploymentStateV1Type, Error, FileSystem.FileSystem | Path.Path>;
+    rollbackAuthoritative(expectedAuthoritativeRevisionDigest: string, expectedPreviousAuthoritativeRevisionDigest: string): Effect.Effect<RoutingDeploymentStateV1Type, Error, FileSystem.FileSystem | Path.Path>;
 }
 export declare function makeRoutingActivationStore(root: string): RoutingActivationStore;

package/dist/routing-activation.js

@@ -1,22 +1,33 @@
-import { assertPublishedRoutingActivation, COMPOSITIONAL_ROUTING_VERSION, PublishedRoutingActivation } from "@velum-labs/routekit-eval-contracts";
+import { activationRevisionDigest, assertPublishedRoutingActivation, assertPublishedRoutingActivationV3, assertRoutingDeploymentStateV1, COMPOSITIONAL_ROUTING_VERSION, PublishedRoutingActivation, RoutingDeploymentStateV1, routingActivationRevision } from "@velum-labs/routekit-eval-contracts";
 import { RouteKitFailure, writeFileAtomicEffect } from "@velum-labs/routekit-runtime/effect";
 import { Clock, Effect, FileSystem, Path, Schema } from "effect";
 const SNAPSHOT_FILE = "published-routing.json";
 const PREVIOUS_SNAPSHOT_FILE = "published-routing.previous.json";
+const DEPLOYMENT_FILE = "routing-deployment.v1.json";
 export const ROUTING_ACTIVATION_MAX_BYTES = 2 * 1024 * 1024;
 const publicationTails = new Map();
 export class RoutingActivationConflictError extends Error {
     expectedEvidenceDigest;
     actualEvidenceDigest;
     constructor(expectedEvidenceDigest, actualEvidenceDigest) {
-        super(`published routing activation changed: expected ${expectedEvidenceDigest === undefined
-            ? "no activation"
-            : JSON.stringify(expectedEvidenceDigest)}, found ${actualEvidenceDigest === undefined ? "no activation" : JSON.stringify(actualEvidenceDigest)}`);
+        super(`published routing activation changed: expected ${expectedEvidenceDigest === undefined ? "no activation" : JSON.stringify(expectedEvidenceDigest)}, found ${actualEvidenceDigest === undefined ? "no activation" : JSON.stringify(actualEvidenceDigest)}`);
         this.name = "RoutingActivationConflictError";
         this.expectedEvidenceDigest = expectedEvidenceDigest;
         this.actualEvidenceDigest = actualEvidenceDigest;
     }
 }
+export class RoutingDeploymentConflictError extends Error {
+    slot;
+    expectedRevisionDigest;
+    actualRevisionDigest;
+    constructor(slot, expectedRevisionDigest, actualRevisionDigest) {
+        super(`routing deployment ${slot} changed: expected ${expectedRevisionDigest === null ? "no revision" : JSON.stringify(expectedRevisionDigest)}, found ${actualRevisionDigest === null ? "no revision" : JSON.stringify(actualRevisionDigest)}`);
+        this.slot = slot;
+        this.expectedRevisionDigest = expectedRevisionDigest;
+        this.actualRevisionDigest = actualRevisionDigest;
+        this.name = "RoutingDeploymentConflictError";
+    }
+}
 export class RoutingActivationStore {
     root;
     constructor(root) {
@@ -37,44 +48,89 @@ export class RoutingActivationStore {
                 publicationTails.delete(this.root);
         };
     }
+    #withPublicationLock(operation) {
+        return Effect.uninterruptibleMask((restore) => Effect.promise(() => this.#acquirePublication()).pipe(Effect.flatMap((release) => restore(operation).pipe(Effect.ensuring(Effect.sync(release))))));
+    }
     read() {
         const root = this.root;
         return Effect.gen(function* () {
-            const paths = yield* Path.Path;
-            return yield* readActivation(paths.join(root, SNAPSHOT_FILE));
+            const deployment = yield* readOrMigrateDeployment(root);
+            const activation = deployment.authoritative?.activation;
+            return activation?.version === 2 ? activation : undefined;
         });
     }
     readPrevious() {
         const root = this.root;
         return Effect.gen(function* () {
             const paths = yield* Path.Path;
-            return yield* readActivation(paths.join(root, PREVIOUS_SNAPSHOT_FILE));
+            return yield* readOrMigrateDeployment(root).pipe(Effect.map((deployment) => {
+                const activation = deployment.previousAuthoritative?.activation;
+                return activation?.version === 2 ? activation : undefined;
+            }), Effect.catch(() => readLegacyActivation(paths.join(root, PREVIOUS_SNAPSHOT_FILE))));
         });
     }
+    readDeployment() {
+        return readOrMigrateDeployment(this.root);
+    }
     publish(publication) {
-        return this.#withPublicationLock(this.#publish(publication));
+        return this.#withPublicationLock(this.#publishLegacy(publication));
     }
-    /**
-     * Publish only if the active evidence generation still matches the caller's
-     * view. `undefined` means the caller expects no active publication.
-     */
     publishIfCurrent(publication, expectedEvidenceDigest) {
-        const root = this.root;
         const store = this;
         return this.#withPublicationLock(Effect.gen(function* () {
-            const paths = yield* Path.Path;
-            const current = yield* readActivation(paths.join(root, SNAPSHOT_FILE));
-            if (current?.evidenceDigest !== expectedEvidenceDigest) {
-                return yield* Effect.fail(new RoutingActivationConflictError(expectedEvidenceDigest, current?.evidenceDigest));
-            }
-            return yield* store.#publish(publication);
+            const current = yield* readOrMigrateDeployment(store.root);
+            const activation = current.authoritative?.activation;
+            const actual = activation?.version === 2 ? activation.evidenceDigest : undefined;
+            if (actual !== expectedEvidenceDigest)
+                return yield* Effect.fail(new RoutingActivationConflictError(expectedEvidenceDigest, actual));
+            return yield* store.#publishLegacy(publication);
         }));
     }
-    #withPublicationLock(operation) {
-        return Effect.uninterruptibleMask((restore) => Effect.promise(() => this.#acquirePublication()).pipe(Effect.flatMap((release) => restore(operation).pipe(Effect.ensuring(Effect.sync(release))))));
+    installAuthoritative(activation, expectedAuthoritativeRevisionDigest, expectedPreviousAuthoritativeRevisionDigest) {
+        const store = this;
+        return this.#withPublicationLock(Effect.gen(function* () {
+            yield* validateAnyActivation(activation, "routing activation is invalid");
+            const current = yield* readOrMigrateDeployment(store.root);
+            assertSlot("authoritative", expectedAuthoritativeRevisionDigest, current.authoritative?.activationRevisionDigest ?? null);
+            assertSlot("previousAuthoritative", expectedPreviousAuthoritativeRevisionDigest, current.previousAuthoritative?.activationRevisionDigest ?? null);
+            if (current.authoritative === null && current.previousAuthoritative !== null)
+                return yield* new RouteKitFailure({
+                    message: "cannot install authority into an empty slot while a previous authoritative revision exists"
+                });
+            const state = {
+                version: 1,
+                stateRevision: current.stateRevision + 1,
+                authoritative: routingActivationRevision(activation),
+                previousAuthoritative: current.authoritative,
+                updatedAt: new Date(yield* Clock.currentTimeMillis).toISOString()
+            };
+            yield* writeDeployment(store.root, state);
+            return state;
+        }));
     }
-    #publish(publication) {
-        const root = this.root;
+    rollbackAuthoritative(expectedAuthoritativeRevisionDigest, expectedPreviousAuthoritativeRevisionDigest) {
+        const store = this;
+        return this.#withPublicationLock(Effect.gen(function* () {
+            const current = yield* readOrMigrateDeployment(store.root);
+            assertSlot("authoritative", expectedAuthoritativeRevisionDigest, current.authoritative?.activationRevisionDigest ?? null);
+            assertSlot("previousAuthoritative", expectedPreviousAuthoritativeRevisionDigest, current.previousAuthoritative?.activationRevisionDigest ?? null);
+            if (current.authoritative === null || current.previousAuthoritative === null)
+                return yield* new RouteKitFailure({
+                    message: "routing rollback requires both authoritative slots"
+                });
+            const state = {
+                version: 1,
+                stateRevision: current.stateRevision + 1,
+                authoritative: current.previousAuthoritative,
+                previousAuthoritative: current.authoritative,
+                updatedAt: new Date(yield* Clock.currentTimeMillis).toISOString()
+            };
+            yield* writeDeployment(store.root, state);
+            return state;
+        }));
+    }
+    #publishLegacy(publication) {
+        const store = this;
         return Effect.gen(function* () {
             const snapshot = {
                 version: COMPOSITIONAL_ROUTING_VERSION,
@@ -84,62 +140,136 @@ export class RoutingActivationStore {
             const decoded = yield* Schema.decodeEffect(PublishedRoutingActivation)(snapshot).pipe(Effect.mapError((cause) => new RouteKitFailure({
                 message: `published routing activation is invalid: ${String(cause)}`
             })));
-            yield* Effect.try({
-                try: () => assertPublishedRoutingActivation(decoded),
-                catch: (cause) => new RouteKitFailure({
-                    message: `published routing activation is invalid: ${detailOf(cause)}`
-                })
-            });
-            // Check the final representation before rotating the current known-good
-            // document. An oversized publication must leave both generations intact.
-            const serialized = `${JSON.stringify(decoded, null, 2)}\n`;
-            assertBoundedSnapshot(serialized);
-            const fs = yield* FileSystem.FileSystem;
-            const paths = yield* Path.Path;
-            yield* fs.makeDirectory(root, { recursive: true, mode: 0o700 });
-            yield* fs.chmod(root, 0o700).pipe(Effect.ignore);
-            const path = paths.join(root, SNAPSHOT_FILE);
-            const previousPath = paths.join(root, PREVIOUS_SNAPSHOT_FILE);
-            const current = yield* readActivation(path);
-            if (current !== undefined) {
-                const previous = `${JSON.stringify(current, null, 2)}\n`;
-                assertBoundedSnapshot(previous);
-                yield* writeFileAtomicEffect(previousPath, previous, { mode: 0o600 });
-            }
-            yield* writeFileAtomicEffect(path, serialized, { mode: 0o600 });
+            yield* validateAnyActivation(decoded, "published routing activation is invalid");
+            const current = yield* readOrMigrateDeployment(store.root);
+            const state = {
+                version: 1,
+                stateRevision: current.stateRevision + 1,
+                authoritative: routingActivationRevision(decoded),
+                previousAuthoritative: current.authoritative,
+                updatedAt: decoded.generatedAt
+            };
+            yield* writeLegacyCompatibilitySnapshots(store.root, decoded, current.authoritative);
+            yield* writeDeployment(store.root, state);
             return decoded;
         });
     }
 }
+function writeLegacyCompatibilitySnapshots(root, current, displaced) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const paths = yield* Path.Path;
+        yield* fs.makeDirectory(root, { recursive: true, mode: 0o700 });
+        yield* fs.chmod(root, 0o700).pipe(Effect.ignore);
+        if (displaced?.activation.version === 2) {
+            const previous = `${JSON.stringify(displaced.activation, null, 2)}\n`;
+            assertBoundedSnapshot(previous);
+            yield* writeFileAtomicEffect(paths.join(root, PREVIOUS_SNAPSHOT_FILE), previous, {
+                mode: 0o600
+            });
+        }
+        const serialized = `${JSON.stringify(current, null, 2)}\n`;
+        assertBoundedSnapshot(serialized);
+        yield* writeFileAtomicEffect(paths.join(root, SNAPSHOT_FILE), serialized, { mode: 0o600 });
+    });
+}
+function assertSlot(slot, expected, actual) {
+    if (expected !== actual)
+        throw new RoutingDeploymentConflictError(slot, expected, actual);
+}
 function detailOf(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
 function assertBoundedSnapshot(raw) {
-    if (Buffer.byteLength(raw, "utf8") > ROUTING_ACTIVATION_MAX_BYTES) {
+    if (Buffer.byteLength(raw, "utf8") > ROUTING_ACTIVATION_MAX_BYTES)
         throw new RouteKitFailure({
             message: `published routing activation exceeds the ${String(ROUTING_ACTIVATION_MAX_BYTES)} byte limit`
         });
-    }
 }
-function readActivation(path) {
+function validateAnyActivation(activation, prefix) {
+    return Effect.try({
+        try: () => {
+            if (activation.version === 2)
+                assertPublishedRoutingActivation(activation);
+            else
+                assertPublishedRoutingActivationV3(activation);
+            activationRevisionDigest(activation);
+        },
+        catch: (cause) => new RouteKitFailure({ message: `${prefix}: ${detailOf(cause)}` })
+    });
+}
+function emptyDeployment(updatedAt) {
+    return {
+        version: 1,
+        stateRevision: 0,
+        authoritative: null,
+        previousAuthoritative: null,
+        updatedAt
+    };
+}
+function readOrMigrateDeployment(root) {
     return Effect.gen(function* () {
-        const fs = yield* FileSystem.FileSystem;
-        if (!(yield* fs.exists(path)))
-            return undefined;
-        const info = yield* fs.stat(path);
-        if (Number(info.size) > ROUTING_ACTIVATION_MAX_BYTES) {
+        const paths = yield* Path.Path;
+        const existing = yield* readDeployment(paths.join(root, DEPLOYMENT_FILE));
+        if (existing !== undefined)
+            return existing;
+        const current = yield* readLegacyActivation(paths.join(root, SNAPSHOT_FILE));
+        const previous = yield* readLegacyActivation(paths.join(root, PREVIOUS_SNAPSHOT_FILE));
+        if (current === undefined && previous === undefined)
+            return emptyDeployment("1970-01-01T00:00:00.000Z");
+        if (current === undefined && previous !== undefined)
             return yield* new RouteKitFailure({
-                message: `published routing activation exceeds the ${String(ROUTING_ACTIVATION_MAX_BYTES)} byte limit`
+                message: "legacy routing deployment is corrupt: previous activation exists without current activation"
             });
-        }
-        const raw = yield* fs.readFileString(path);
-        assertBoundedSnapshot(raw);
-        const json = yield* Effect.try({
-            try: () => JSON.parse(raw),
+        const state = {
+            version: 1,
+            stateRevision: 0,
+            authoritative: routingActivationRevision(current),
+            previousAuthoritative: previous === undefined ? null : routingActivationRevision(previous),
+            updatedAt: current.generatedAt
+        };
+        yield* writeDeployment(root, state);
+        return state;
+    });
+}
+function writeDeployment(root, state) {
+    return Effect.gen(function* () {
+        yield* Effect.try({
+            try: () => assertRoutingDeploymentStateV1(state),
+            catch: (cause) => new RouteKitFailure({ message: `routing deployment is invalid: ${detailOf(cause)}` })
+        });
+        const decoded = yield* Schema.decodeEffect(RoutingDeploymentStateV1)(state).pipe(Effect.mapError((cause) => new RouteKitFailure({ message: `routing deployment is invalid: ${String(cause)}` })));
+        const serialized = `${JSON.stringify(decoded, null, 2)}\n`;
+        assertBoundedSnapshot(serialized);
+        const fs = yield* FileSystem.FileSystem;
+        const paths = yield* Path.Path;
+        yield* fs.makeDirectory(root, { recursive: true, mode: 0o700 });
+        yield* fs.chmod(root, 0o700).pipe(Effect.ignore);
+        yield* writeFileAtomicEffect(paths.join(root, DEPLOYMENT_FILE), serialized, { mode: 0o600 });
+    });
+}
+function readDeployment(path) {
+    return Effect.gen(function* () {
+        const json = yield* readJsonDocument(path, "routing deployment is corrupt");
+        if (json === undefined)
+            return undefined;
+        const decoded = yield* Schema.decodeUnknownEffect(RoutingDeploymentStateV1)(json).pipe(Effect.mapError((cause) => new RouteKitFailure({
+            message: `routing deployment is corrupt: ${String(cause)}`
+        })));
+        yield* Effect.try({
+            try: () => assertRoutingDeploymentStateV1(decoded),
             catch: (cause) => new RouteKitFailure({
-                message: `published routing activation is corrupt: ${detailOf(cause)}`
+                message: `routing deployment is corrupt: ${detailOf(cause)}`
             })
         });
+        return decoded;
+    });
+}
+function readLegacyActivation(path) {
+    return Effect.gen(function* () {
+        const json = yield* readJsonDocument(path, "published routing activation is corrupt");
+        if (json === undefined)
+            return undefined;
         const decoded = yield* Schema.decodeUnknownEffect(PublishedRoutingActivation)(json).pipe(Effect.mapError((cause) => new RouteKitFailure({
             message: `published routing activation is corrupt: ${String(cause)}`
         })));
@@ -152,6 +282,25 @@ function readActivation(path) {
         return decoded;
     });
 }
+function readJsonDocument(path, prefix) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        if (!(yield* fs.exists(path)))
+            return undefined;
+        const info = yield* fs.stat(path);
+        if (Number(info.size) > ROUTING_ACTIVATION_MAX_BYTES)
+            return yield* new RouteKitFailure({
+                message: `published routing activation exceeds the ${String(ROUTING_ACTIVATION_MAX_BYTES)} byte limit`
+            });
+        const raw = yield* fs.readFileString(path);
+        assertBoundedSnapshot(raw);
+        const json = yield* Effect.try({
+            try: () => JSON.parse(raw),
+            catch: (cause) => new RouteKitFailure({ message: `${prefix}: ${detailOf(cause)}` })
+        });
+        return json;
+    });
+}
 export function makeRoutingActivationStore(root) {
     return new RoutingActivationStore(root);
 }

package/dist/services/experiment-artifacts/service.d.ts

@@ -0,0 +1,12 @@
+import { Context, Effect } from "effect";
+import type { FileSystem, Path } from "effect";
+import type { ExperimentArtifactReference, ExperimentArtifactVisibility } from "../../experiment-artifacts.js";
+export interface ExperimentArtifactStoreShape {
+    readonly write: (runId: string, name: string, value: unknown, visibility?: ExperimentArtifactVisibility) => Effect.Effect<ExperimentArtifactReference, Error, FileSystem.FileSystem | Path.Path>;
+    readonly read: (runId: string, name: string, visibility?: ExperimentArtifactVisibility) => Effect.Effect<string | undefined, Error, FileSystem.FileSystem | Path.Path>;
+}
+declare const ExperimentArtifactStore_base: Context.ServiceClass<ExperimentArtifactStore, "routekit/ExperimentArtifactStore", ExperimentArtifactStoreShape>;
+/** @effect-expect-leaking FileSystem | Path */
+export declare class ExperimentArtifactStore extends ExperimentArtifactStore_base {
+}
+export {};

package/dist/services/experiment-artifacts/service.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+/** @effect-expect-leaking FileSystem | Path */
+export class ExperimentArtifactStore extends Context.Service()("routekit/ExperimentArtifactStore") {
+}

package/dist/test/routing-activation.test.js

@@ -1,10 +1,11 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
+import { activationRevisionDigest } from "@velum-labs/routekit-eval-contracts";
 import { runRouteKitEffect } from "@velum-labs/routekit-runtime/effect";
-import { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError } from "../routing-activation.js";
+import { makeRoutingActivationStore, ROUTING_ACTIVATION_MAX_BYTES, RoutingActivationConflictError, RoutingDeploymentConflictError } from "../routing-activation.js";
 const dimensions = [
     "gateway-protocol",
     "eval-routing",
@@ -131,3 +132,50 @@ test("concurrent routing activation publishers serialize complete generations",
         rmSync(root, { recursive: true, force: true });
     }
 });
+test("legacy V2 files migrate idempotently into cross-version deployment state", async () => {
+    const root = mkdtempSync(join(tmpdir(), "routekit-routing-deployment-migrate-"));
+    try {
+        const current = {
+            version: 2,
+            generatedAt: "2026-08-23T00:00:00.000Z",
+            ...publication("current")
+        };
+        const previous = {
+            version: 2,
+            generatedAt: "2026-08-22T00:00:00.000Z",
+            ...publication("previous")
+        };
+        writeFileSync(join(root, "published-routing.json"), `${JSON.stringify(current)}\n`);
+        writeFileSync(join(root, "published-routing.previous.json"), `${JSON.stringify(previous)}\n`);
+        const store = makeRoutingActivationStore(root);
+        const first = await runRouteKitEffect(store.readDeployment());
+        const second = await runRouteKitEffect(store.readDeployment());
+        assert.deepEqual(second, first);
+        assert.equal(first.authoritative?.activationRevisionDigest, activationRevisionDigest(current));
+        assert.equal(first.previousAuthoritative?.activationRevisionDigest, activationRevisionDigest(previous));
+        assert.equal(statSync(join(root, "routing-deployment.v1.json")).mode & 0o777, 0o600);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("V3 authority installation and rollback compare and swap both exact slots", async () => {
+    const root = mkdtempSync(join(tmpdir(), "routekit-routing-deployment-rollback-"));
+    try {
+        const store = makeRoutingActivationStore(root);
+        const v2 = await runRouteKitEffect(store.publish(publication("v2")));
+        const v2Revision = activationRevisionDigest(v2);
+        const v3 = JSON.parse(readFileSync(new URL("../../../../test/fixtures/routing-v3/examples/published-routing-activation-v3.example.json", import.meta.url), "utf8"));
+        const installed = await runRouteKitEffect(store.installAuthoritative(v3, v2Revision, null));
+        assert.equal(installed.authoritative?.activation.version, 3);
+        assert.equal(installed.previousAuthoritative?.activationRevisionDigest, v2Revision);
+        await assert.rejects(runRouteKitEffect(store.installAuthoritative(v3, v2Revision, null)), (error) => error instanceof RoutingDeploymentConflictError && error.slot === "authoritative");
+        const rolledBack = await runRouteKitEffect(store.rollbackAuthoritative(v3.activationDigest, v2Revision));
+        assert.equal(rolledBack.authoritative?.activation.version, 2);
+        assert.equal(rolledBack.previousAuthoritative?.activation.version, 3);
+    }
+    finally {
+        chmodSync(root, 0o700);
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-eval-store",
   "private": false,
-  "version": "1.0.26",
+  "version": "1.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "effect": "4.0.0-rc.108",
-    "@velum-labs/routekit-eval-contracts": "1.0.26",
-    "@velum-labs/routekit-runtime": "1.0.26"
+    "@velum-labs/routekit-eval-contracts": "1.1.0",
+    "@velum-labs/routekit-runtime": "1.1.0"
   },
   "keywords": [
     "routekit",