@valerypopoff/rivet2-evaluations 2.4.0 → 2.6.0

package/dist/esm/index.js

@@ -9,3 +9,4 @@ export * from './suiteTransfer.js';
 export * from './dataTypes.js';
 export * from './normalization.js';
 export * from './library.js';
+export * from './librarySync.js';

package/dist/esm/librarySync.js

@@ -0,0 +1,118 @@
+import { canonicalStringify } from './canonical.js';
+import { normalizeEvaluationLibrary } from './library.js';
+/**
+ * Matches the server's canonical resource versioning while retaining the
+ * meaningful distinction between an absent resource and a present JSON value.
+ */
+export function evaluationLibraryValueEquals(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return canonicalStringify(left) === canonicalStringify(right);
+}
+export function getEvaluationSuiteBundle(library, id) {
+    const suite = library.data.suites.find((candidate) => candidate.id === id);
+    if (!suite)
+        return undefined;
+    return {
+        suite,
+        baselines: library.data.baselines.filter((baseline) => baseline.suiteId === id),
+    };
+}
+export function getEvaluationLibraryResource(library, kind, id) {
+    if (kind === 'suite')
+        return { kind, id, value: getEvaluationSuiteBundle(library, id) };
+    return { kind, id, value: library.datasets.find((dataset) => dataset.id === id) };
+}
+function resourceIds(library, kind) {
+    return new Set(kind === 'suite' ? library.data.suites.map((suite) => suite.id) : library.datasets.map((dataset) => dataset.id));
+}
+/**
+ * Builds the smallest resource batch between two already normalized library
+ * snapshots. Legacy migration metadata deliberately has its own explicit
+ * server operation and is not silently folded into an editor mutation.
+ */
+export function diffEvaluationLibraryMutation(previous, next, versions) {
+    const changes = [];
+    for (const kind of ['dataset', 'suite']) {
+        const ids = new Set([...resourceIds(previous, kind), ...resourceIds(next, kind)]);
+        for (const id of [...ids].sort()) {
+            if (kind === 'suite') {
+                const before = getEvaluationSuiteBundle(previous, id);
+                const after = getEvaluationSuiteBundle(next, id);
+                if (evaluationLibraryValueEquals(before, after))
+                    continue;
+                const currentVersion = versions.suites[id];
+                if (before !== undefined && currentVersion === undefined) {
+                    throw new Error(`The suite "${id}" has no synchronization version.`);
+                }
+                const expectedVersion = before === undefined ? null : currentVersion;
+                if (after === undefined) {
+                    changes.push({ kind: 'delete-suite', id, expectedVersion: expectedVersion });
+                }
+                else {
+                    changes.push({
+                        kind: 'put-suite',
+                        id,
+                        expectedVersion,
+                        suite: after.suite,
+                        baselines: after.baselines,
+                    });
+                }
+            }
+            else {
+                const before = previous.datasets.find((dataset) => dataset.id === id);
+                const after = next.datasets.find((dataset) => dataset.id === id);
+                if (evaluationLibraryValueEquals(before, after))
+                    continue;
+                const currentVersion = versions.datasets[id];
+                if (before !== undefined && currentVersion === undefined) {
+                    throw new Error(`The dataset "${id}" has no synchronization version.`);
+                }
+                const expectedVersion = before === undefined ? null : currentVersion;
+                if (after === undefined) {
+                    changes.push({ kind: 'delete-dataset', id, expectedVersion: expectedVersion });
+                }
+                else {
+                    changes.push({ kind: 'put-dataset', id, expectedVersion, dataset: after });
+                }
+            }
+        }
+    }
+    return changes.length === 0 ? undefined : { changes };
+}
+function replaceById(items, value) {
+    const index = items.findIndex((item) => item.id === value.id);
+    if (index === -1)
+        return [...items, value];
+    return items.map((item) => (item.id === value.id ? value : item));
+}
+/** Applies a server-validated resource batch while preserving unrelated resources. */
+export function applyEvaluationLibraryMutation(library, mutation) {
+    let suites = library.data.suites;
+    let baselines = library.data.baselines;
+    let datasets = library.datasets;
+    for (const change of mutation.changes) {
+        switch (change.kind) {
+            case 'put-suite':
+                suites = replaceById(suites, change.suite);
+                baselines = [...baselines.filter((baseline) => baseline.suiteId !== change.id), ...change.baselines];
+                break;
+            case 'delete-suite':
+                suites = suites.filter((suite) => suite.id !== change.id);
+                baselines = baselines.filter((baseline) => baseline.suiteId !== change.id);
+                break;
+            case 'put-dataset':
+                datasets = replaceById(datasets, change.dataset);
+                break;
+            case 'delete-dataset':
+                datasets = datasets.filter((dataset) => dataset.id !== change.id);
+                break;
+        }
+    }
+    return normalizeEvaluationLibrary({
+        version: 1,
+        data: { version: 1, suites, baselines },
+        datasets,
+        migratedLegacyProjectIds: library.migratedLegacyProjectIds,
+    });
+}

package/dist/types/index.d.ts

@@ -9,3 +9,4 @@ export * from './suiteTransfer.js';
 export * from './dataTypes.js';
 export * from './normalization.js';
 export * from './library.js';
+export * from './librarySync.js';

package/dist/types/librarySync.d.ts

@@ -0,0 +1,17 @@
+import type { EvaluationLibrary, EvaluationLibraryMutation, EvaluationLibraryResourceValue, EvaluationLibraryResourceVersions, EvaluationLibrarySuiteBundle } from './types.js';
+export type { EvaluationLibraryResourceValue, EvaluationLibrarySuiteBundle } from './types.js';
+/**
+ * Matches the server's canonical resource versioning while retaining the
+ * meaningful distinction between an absent resource and a present JSON value.
+ */
+export declare function evaluationLibraryValueEquals(left: unknown, right: unknown): boolean;
+export declare function getEvaluationSuiteBundle(library: EvaluationLibrary, id: string): EvaluationLibrarySuiteBundle | undefined;
+export declare function getEvaluationLibraryResource(library: EvaluationLibrary, kind: 'suite' | 'dataset', id: string): EvaluationLibraryResourceValue;
+/**
+ * Builds the smallest resource batch between two already normalized library
+ * snapshots. Legacy migration metadata deliberately has its own explicit
+ * server operation and is not silently folded into an editor mutation.
+ */
+export declare function diffEvaluationLibraryMutation(previous: EvaluationLibrary, next: EvaluationLibrary, versions: EvaluationLibraryResourceVersions): EvaluationLibraryMutation | undefined;
+/** Applies a server-validated resource batch while preserving unrelated resources. */
+export declare function applyEvaluationLibraryMutation(library: EvaluationLibrary, mutation: EvaluationLibraryMutation): EvaluationLibrary;

package/dist/types/types.d.ts

@@ -170,6 +170,113 @@ export type EvaluationLibrary = {
     /** Legacy project IDs whose embedded evaluation resources were imported. */
     migratedLegacyProjectIds: ProjectId[];
 };
+/**
+ * A collaboration boundary for the shared evaluation library. A suite owns
+ * its baselines because a baseline is only meaningful with that suite; a
+ * dataset is independently editable and reusable by many suites.
+ */
+export type EvaluationLibraryResourceKind = 'suite' | 'dataset';
+export type EvaluationLibraryResourceVersions = {
+    suites: Record<string, string>;
+    datasets: Record<string, string>;
+};
+/** A server-authoritative library snapshot used by collaborative hosts. */
+export type EvaluationLibrarySyncSnapshot = {
+    revision: number;
+    library: EvaluationLibrary;
+    resourceVersions: EvaluationLibraryResourceVersions;
+};
+/**
+ * A validated, external change token for the shared evaluation library.
+ * `epoch` identifies one SSE generation so reconnects can require a resync
+ * even when a server's revision counter has not advanced.
+ */
+export type EvaluationLibraryInvalidation = {
+    epoch: string;
+    revision: number;
+};
+/** The durable value for one independently synchronized library resource. */
+export type EvaluationLibrarySuiteBundle = {
+    suite: EvaluationSuite;
+    baselines: EvaluationBaselineSnapshot[];
+};
+export type EvaluationLibraryResourceValue = {
+    kind: 'suite';
+    id: string;
+    value: EvaluationLibrarySuiteBundle | undefined;
+} | {
+    kind: 'dataset';
+    id: string;
+    value: EvaluationDataset | undefined;
+};
+/**
+ * Every mutation is an all-or-nothing resource batch. Existing resources use
+ * their opaque version token; null means that creation requires the resource
+ * to remain absent.
+ */
+export type EvaluationLibraryMutationChange = {
+    kind: 'put-suite';
+    id: string;
+    expectedVersion: string | null;
+    suite: EvaluationSuite;
+    baselines: EvaluationBaselineSnapshot[];
+} | {
+    kind: 'delete-suite';
+    id: string;
+    expectedVersion: string;
+} | {
+    kind: 'put-dataset';
+    id: string;
+    expectedVersion: string | null;
+    dataset: EvaluationDataset;
+} | {
+    kind: 'delete-dataset';
+    id: string;
+    expectedVersion: string;
+};
+export type EvaluationLibraryMutation = {
+    changes: EvaluationLibraryMutationChange[];
+};
+export type EvaluationLibraryConflictResource = {
+    kind: EvaluationLibraryResourceKind;
+    id: string;
+    expectedVersion: string | null;
+    currentVersion: string | null;
+};
+/**
+ * A conflict is deliberately expressed with both values. Hosts use this to
+ * present an explicit choice instead of silently overwriting either editor.
+ */
+export type EvaluationLibraryConflictDraft = EvaluationLibraryConflictResource & {
+    local: EvaluationLibraryResourceValue;
+    server: EvaluationLibraryResourceValue;
+};
+export type EvaluationLibrarySyncIssue = {
+    id: string;
+    kind: 'conflict';
+    message: string;
+    conflicts: readonly EvaluationLibraryConflictDraft[];
+} | {
+    id: string;
+    kind: 'retryable' | 'failed';
+    message: string;
+};
+export type EvaluationLibraryConflictResolution = {
+    issueId: string;
+    kind: EvaluationLibraryResourceKind;
+    id: string;
+    action: 'use-server' | 'keep-mine-as-copy';
+};
+/** A host can expose this optional capability without changing local stores. */
+export type EvaluationLibrarySyncStore = {
+    getLibrarySyncSnapshot(): Promise<EvaluationLibrarySyncSnapshot>;
+    mutateLibrary(input: EvaluationLibraryMutation): Promise<EvaluationLibrarySyncSnapshot>;
+    subscribeLibraryInvalidation?(listener: (invalidation: EvaluationLibraryInvalidation) => void): () => void;
+    /** An unresolved hosted save requiring an explicit user decision. */
+    subscribeLibrarySyncIssue?(listener: (issue: EvaluationLibrarySyncIssue | undefined) => void): () => void;
+    resolveLibraryConflict?(input: EvaluationLibraryConflictResolution): Promise<EvaluationLibrary>;
+    retryLibrarySync?(): Promise<EvaluationLibrary>;
+};
 export type EvaluationObservationStatus = 'passed' | 'failed' | 'scored' | 'error' | 'skipped';
 export type EvaluationObservation = {
     id: string;
@@ -495,6 +602,13 @@ export type EvaluationStore = EvaluationRunStore & {
     initialize?(): Promise<EvaluationStoreInitialization | void>;
     getLibrary(): Promise<EvaluationLibrary>;
     putLibrary(library: EvaluationLibrary): Promise<void>;
+    /** Optional hosted capability for resource-scoped collaborative saves. */
+    getLibrarySyncSnapshot?: EvaluationLibrarySyncStore['getLibrarySyncSnapshot'];
+    mutateLibrary?: EvaluationLibrarySyncStore['mutateLibrary'];
+    subscribeLibraryInvalidation?: EvaluationLibrarySyncStore['subscribeLibraryInvalidation'];
+    subscribeLibrarySyncIssue?: EvaluationLibrarySyncStore['subscribeLibrarySyncIssue'];
+    resolveLibraryConflict?: EvaluationLibrarySyncStore['resolveLibraryConflict'];
+    retryLibrarySync?: EvaluationLibrarySyncStore['retryLibrarySync'];
 };
 export type EvaluationReporter = {
     report(run: EvaluationRun): Promise<void> | void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valerypopoff/rivet2-evaluations",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "license": "MIT",
   "main": "dist/cjs/bundle.cjs",
   "module": "dist/esm/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@valerypopoff/rivet2-core": "^2.4.0",
+    "@valerypopoff/rivet2-core": "^2.6.0",
     "yaml": "^2.9.0"
   }
 }