agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/state/experimentIdentity.js

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+export const PERSISTED_OBJECTIVE_ID = /^objective:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const LEGACY_OBJECTIVE_ID = /^legacy-objective:[0-9a-f]{64}$/;
+export const OBJECTIVE_ID = /^(objective:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-objective:[0-9a-f]{64})$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry)) : [];
+}
+/** Identity inputs deliberately exclude title, lifecycle, closure, root, and slug. */
+export function canonicalObjectiveIdentityDocument(document) {
+    const objective = mapping(document.objective);
+    return {
+        baseline: mapping(document.baseline),
+        constraints: document.constraints ?? objective.constraints ?? [],
+        description: objective.description ?? document.description ?? "",
+        gates: mapping(document.gates),
+        measurement: objective.measurement ?? document.measurement ?? "",
+        metric: mapping(document.metric),
+        scope: mapping(document.scope),
+    };
+}
+export function resolveObjectiveIdentity(document) {
+    const canonicalJson = canonicalRecordJson(canonicalObjectiveIdentityDocument(document));
+    const persisted = mapping(document.header).id;
+    if (persisted !== undefined) {
+        if (typeof persisted !== "string" || !PERSISTED_OBJECTIVE_ID.test(persisted)) {
+            throw new Error("objective header.id is not a valid persisted objective identity");
+        }
+        return { stableId: persisted, persisted: true, canonicalJson, compatibility: "canonical" };
+    }
+    return {
+        stableId: `legacy-objective:${createHash("sha256").update(canonicalJson, "utf8").digest("hex")}`,
+        persisted: false,
+        canonicalJson,
+        compatibility: "legacy_derived_identity",
+    };
+}
+export function discoverObjectiveArtifacts(projectRoot) {
+    const inspected = [];
+    const diagnostics = [];
+    for (const root of ["optimize", "optimera"]) {
+        const directory = path.join(projectRoot, ".agentera", root);
+        let slugs = [];
+        try {
+            slugs = fs.readdirSync(directory).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const slug of slugs) {
+            const objectivePath = path.join(directory, slug, "objective.yaml");
+            if (!fs.existsSync(objectivePath))
+                continue;
+            try {
+                const identity = resolveObjectiveIdentity(loadYamlMapping(fs.readFileSync(objectivePath, "utf8")));
+                inspected.push({ ...identity, path: objectivePath, slug, root });
+            }
+            catch (error) {
+                diagnostics.push({
+                    class: "corrupt",
+                    message: error.message,
+                    candidate_paths: [objectivePath],
+                });
+            }
+        }
+    }
+    const objectives = [];
+    for (const stableId of [...new Set(inspected.map((candidate) => candidate.stableId))].sort()) {
+        const candidates = inspected.filter((candidate) => candidate.stableId === stableId);
+        const ambiguous = new Set(candidates.map((candidate) => candidate.canonicalJson)).size > 1;
+        if (ambiguous) {
+            diagnostics.push({
+                class: "ambiguous",
+                message: `objective identity ${stableId} resolves to conflicting documents`,
+                stable_id: stableId,
+                candidate_paths: candidates.map((candidate) => candidate.path).sort(),
+            });
+        }
+        objectives.push({
+            stableId,
+            persisted: candidates.every((candidate) => candidate.persisted),
+            canonicalJson: candidates[0].canonicalJson,
+            compatibility: candidates.every((candidate) => candidate.persisted) ? "canonical" : "legacy_derived_identity",
+            paths: candidates.map((candidate) => candidate.path).sort(),
+            slugs: [...new Set(candidates.map((candidate) => candidate.slug))].sort(),
+            roots: [...new Set(candidates.map((candidate) => candidate.root))].sort(),
+            ambiguous,
+        });
+    }
+    for (const slug of [...new Set(inspected.map((candidate) => candidate.slug))].sort()) {
+        const candidates = inspected.filter((candidate) => candidate.slug === slug);
+        const roots = new Set(candidates.map((candidate) => candidate.root));
+        const candidateIds = [...new Set(candidates.map((candidate) => candidate.stableId))].sort();
+        if (roots.size === 2 && candidateIds.length > 1) {
+            const candidatePaths = candidates.map((candidate) => candidate.path).sort();
+            diagnostics.push({
+                class: "ambiguous",
+                message: `canonical and legacy objective roots conflict for slug ${slug}`,
+                slug,
+                candidate_ids: candidateIds,
+                candidate_paths: candidatePaths,
+            });
+            for (const objective of objectives.filter((candidate) => candidateIds.includes(candidate.stableId)))
+                objective.ambiguous = true;
+        }
+    }
+    return { objectives, diagnostics };
+}
+export function inspectExperimentIdentities(objectiveId, document) {
+    if (!OBJECTIVE_ID.test(objectiveId))
+        throw new Error("objective identity is invalid");
+    const collections = [
+        ["experiments", list(document.experiments)],
+        ["archive", list(document.archive)],
+        ["archived_experiments", list(document.archived_experiments)],
+    ];
+    const counts = new Map();
+    for (const [, entries] of collections) {
+        for (const entry of entries) {
+            if (Number.isInteger(entry.number) && Number(entry.number) >= 0)
+                counts.set(Number(entry.number), (counts.get(Number(entry.number)) ?? 0) + 1);
+        }
+    }
+    const caveats = [];
+    const entries = collections.flatMap(([collection, values]) => values.map((data, index) => {
+        const number = Number.isInteger(data.number) && Number(data.number) >= 0 ? Number(data.number) : null;
+        let compatibility = "canonical";
+        const entryCaveats = [];
+        if (data.number === undefined || data.number === null) {
+            compatibility = "legacy_missing_identity";
+            entryCaveats.push(`legacy ${collection}[${index}] is missing experiment number and remains visible but unaddressable`);
+        }
+        else if (number === null) {
+            compatibility = "legacy_invalid_identity";
+            entryCaveats.push(`legacy ${collection}[${index}] has invalid experiment number and remains visible but unaddressable`);
+        }
+        else if ((counts.get(number) ?? 0) > 1) {
+            compatibility = "legacy_duplicate_identity";
+            entryCaveats.push(`duplicate experiment number ${number} remains visible but ambiguous and unaddressable`);
+        }
+        caveats.push(...entryCaveats);
+        return {
+            stableId: number === null ? null : `${objectiveId}/experiment:${number}`,
+            number,
+            addressable: compatibility === "canonical",
+            compatibility,
+            provenance: { collection, index },
+            data,
+            caveats: entryCaveats,
+        };
+    }));
+    return { objectiveId, entries, caveats: [...new Set(caveats)] };
+}
+export class ExperimentIdentityError extends Error {
+    className;
+    details;
+    constructor(className, message, details = {}) {
+        super(message);
+        this.className = className;
+        this.details = details;
+        this.name = "ExperimentIdentityError";
+    }
+}
+/** Pure preflight used by later publication work; this function never changes project state. */
+export function validateExperimentPublicationIdentity(discovery, projection, objectiveId, number) {
+    if (!OBJECTIVE_ID.test(objectiveId) || !Number.isInteger(number) || number < 0) {
+        throw new ExperimentIdentityError("invalid_request", "publication requires a valid objective identity and non-negative integer experiment number");
+    }
+    const objective = discovery.objectives.find((candidate) => candidate.stableId === objectiveId);
+    if (!objective)
+        throw new ExperimentIdentityError("not_found", `objective identity ${objectiveId} was not found`);
+    if (objective.ambiguous || projection.objectiveId !== objectiveId || projection.entries.some((entry) => !entry.addressable)) {
+        throw new ExperimentIdentityError("ambiguous", "experiment publication identity is ambiguous; no effects are allowed", {
+            stable_id: `${objectiveId}/experiment:${number}`,
+            candidate_paths: objective.paths,
+            compatibility_caveats: projection.caveats,
+        });
+    }
+    const stableId = `${objectiveId}/experiment:${number}`;
+    if (projection.entries.some((entry) => entry.stableId === stableId)) {
+        throw new ExperimentIdentityError("ambiguous", `experiment identity ${stableId} already exists; no effects are allowed`, { stable_id: stableId });
+    }
+    return stableId;
+}
+//# sourceMappingURL=experimentIdentity.js.map

package/dist/state/experimentIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experimentIdentity.js","sourceRoot":"","sources":["../../src/state/experimentIdentity.ts"],"names":[],"mappings":"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"}

package/dist/state/experimentRetrieval.js

@@ -0,0 +1,447 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+import YAML from "yaml";
+import { loadYamlMapping } from "../core/yaml.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { StateRetrievalFailure } from "./directRetrieval.js";
+import { OBJECTIVE_ID, discoverObjectiveArtifacts, inspectExperimentIdentities, } from "./experimentIdentity.js";
+const CURSOR_VERSION = 1;
+const ORDER = "experiment_number_desc";
+const MAX_LIST_BYTES = 32_768;
+const AUTHORITY = "references/artifacts/state-storage-authority.yaml";
+function hash(value) {
+    return createHash("sha256").update(canonicalRecordJson(value), "utf8").digest("hex");
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fail(exitCode, className, message, verb, details = {}) {
+    const list = verb === "list";
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: className,
+            message,
+            syntax: list
+                ? "agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json"
+                : "agentera state experiments get --objective OBJECTIVE_ID --number N --format json",
+            example: list
+                ? "agentera state experiments list --objective objective:123e4567-e89b-42d3-a456-426614174000 --limit 20 --format json"
+                : "agentera state experiments get --objective objective:123e4567-e89b-42d3-a456-426614174000 --number 0 --format json",
+            recovery: details.recovery ?? "Correct the objective-scoped experiment command and retry; no state was changed.",
+            valid_values: list
+                ? ["--objective OBJECTIVE_ID", "--limit 1..100", "--cursor TOKEN", "--format text|json|yaml"]
+                : ["--objective OBJECTIVE_ID", "--number 0|1|2|...", "--format text|json|yaml"],
+            ...details,
+        },
+    }, exitCode);
+}
+function selectedObjective(projectRoot, objectiveId, verb) {
+    if (!OBJECTIVE_ID.test(objectiveId)) {
+        throw fail(2, "invalid_request", `invalid objective identity '${objectiveId}'`, verb, {
+            valid_values: ["objective:<lowercase-rfc9562-uuid>", "legacy-objective:<64-lowercase-hex-digest>"],
+        });
+    }
+    const discovery = discoverObjectiveArtifacts(projectRoot);
+    const objective = discovery.objectives.find((candidate) => candidate.stableId === objectiveId);
+    if (!objective) {
+        throw fail(1, "not_found", `objective identity '${objectiveId}' was not found`, verb, {
+            stable_id: objectiveId,
+            recovery: "Use an objective identity returned by Agentera objective state, then retry.",
+            details: { compatibility_diagnostics: discovery.diagnostics },
+        });
+    }
+    if (objective.ambiguous) {
+        throw fail(1, "ambiguous", `objective identity '${objectiveId}' resolves to incompatible canonical or legacy candidates`, verb, {
+            stable_id: objectiveId,
+            recovery: "Repair the objective identity/root collision; Agentera will not choose by path or root preference.",
+            details: { candidate_paths: objective.paths, compatibility_diagnostics: discovery.diagnostics },
+        });
+    }
+    return objective;
+}
+function readProjection(objectiveId, objectivePath) {
+    const projectionPath = path.join(path.dirname(objectivePath), "experiments.yaml");
+    if (!fs.existsSync(projectionPath))
+        return { sources: [], diagnostics: [] };
+    try {
+        const projection = inspectExperimentIdentities(objectiveId, loadYamlMapping(fs.readFileSync(projectionPath, "utf8")));
+        return {
+            sources: projection.entries.map((entry) => ({
+                path: projectionPath,
+                collection: entry.provenance.collection,
+                index: entry.provenance.index,
+                record: entry.data,
+                addressable: entry.addressable,
+                compatibility: entry.compatibility,
+                caveats: entry.caveats,
+            })),
+            diagnostics: projection.caveats.map((message) => ({ class: "compatibility", path: projectionPath, message })),
+        };
+    }
+    catch (error) {
+        throw fail(1, "corrupt", `experiment projection '${projectionPath}' cannot be read safely`, "list", {
+            recovery: "Repair the selected objective's experiments.yaml, then retry.",
+            details: { path: projectionPath, message: error.message },
+        });
+    }
+}
+function archiveNumber(filename) {
+    if (!/^(0|[1-9][0-9]*)\.yaml$/.test(filename))
+        return undefined;
+    const number = Number(filename.slice(0, -5));
+    return Number.isSafeInteger(number) ? number : undefined;
+}
+function readArchives(objectiveId, objectivePath) {
+    const directory = path.join(path.dirname(objectivePath), "archive", "experiments");
+    let names;
+    try {
+        names = fs.readdirSync(directory).sort();
+    }
+    catch {
+        return { sources: [], diagnostics: [] };
+    }
+    const sources = [];
+    const diagnostics = [];
+    for (const name of names) {
+        const file = path.join(directory, name);
+        const number = archiveNumber(name);
+        try {
+            if (number === undefined || fs.lstatSync(file).isSymbolicLink() || !fs.lstatSync(file).isFile())
+                throw new Error("archive filename or file type is invalid");
+            const envelope = loadYamlMapping(fs.readFileSync(file, "utf8"));
+            const stableId = `${objectiveId}/experiment:${number}`;
+            if (envelope.schemaVersion !== "agentera.experimentArchive.v1")
+                throw new Error("unsupported experiment archive schemaVersion");
+            if (envelope.objective_id !== objectiveId || envelope.experiment_number !== number || envelope.stable_id !== stableId)
+                throw new Error("archive identity does not match its objective-scoped path");
+            if (!mapping(envelope.record) || envelope.record.number !== number)
+                throw new Error("archive record number does not match its envelope");
+            const digest = hash(envelope.record);
+            if (envelope.record_sha256 !== digest)
+                throw new Error("archive record_sha256 does not match its record");
+            if (!mapping(envelope.provenance) || envelope.provenance.authority !== AUTHORITY || envelope.provenance.objective_id !== objectiveId || envelope.provenance.experiment_id !== stableId) {
+                throw new Error("archive provenance does not match its authority and identity");
+            }
+            sources.push({ path: file, record: envelope.record, recordSha256: digest, provenance: envelope.provenance });
+        }
+        catch (error) {
+            diagnostics.push({ class: "corrupt", path: file, message: error.message, experiment_number: number ?? null });
+        }
+    }
+    return { sources, diagnostics };
+}
+function logicalExperiment(objectiveId, number, projection, archives) {
+    const stableId = `${objectiveId}/experiment:${number}`;
+    const projectionPaths = new Map();
+    for (const source of projection)
+        projectionPaths.set(source.path, [...(projectionPaths.get(source.path) ?? []), source]);
+    const duplicateProjection = [...projectionPaths.values()].some((sources) => sources.length > 1);
+    const projectionHashes = new Set(projection.map((source) => hash(source.record)));
+    const archiveHashes = new Set(archives.map((source) => source.recordSha256));
+    const fullProjection = projection.filter((source) => source.collection === "experiments");
+    const summaryProjection = projection.filter((source) => source.collection !== "experiments");
+    const summaryDetail = summaryProjection.some((source) => Object.keys(source.record).some((field) => field !== "number"));
+    const immutableConflict = archiveHashes.size > 1 || (archives.length > 0 && fullProjection.some((source) => !archiveHashes.has(hash(source.record))));
+    const duplicate = duplicateProjection || projectionHashes.size > 1 && projection.length > 1;
+    const detailAvailability = archives.length > 0 || fullProjection.length > 0 ? "full" : summaryDetail ? "summary" : "unavailable";
+    const compatibility = immutableConflict
+        ? "immutable_conflict"
+        : duplicate
+            ? "legacy_duplicate_identity"
+            : archives.length > 0
+                ? "canonical_archive"
+                : fullProjection.length > 0
+                    ? "legacy_full_without_archive"
+                    : summaryDetail ? "legacy_summary_only" : "legacy_detail_unavailable";
+    const source = archives.length > 0
+        ? projection.length > 0 ? "archive_and_projection" : "immutable_archive"
+        : fullProjection.length > 0 ? "retained_projection" : "legacy_summary_projection";
+    const fingerprint = hash(archives.length > 0
+        ? {
+            stable_id: stableId,
+            evidence: "immutable_archive",
+            record_hashes: [...archiveHashes].sort(),
+            compatibility,
+        }
+        : {
+            stable_id: stableId,
+            evidence: fullProjection.length > 0 ? "retained_full" : summaryDetail ? "legacy_summary" : "unavailable",
+            record_hashes: [...projectionHashes].sort(),
+            compatibility,
+        });
+    return { key: stableId, stableId, number, projection, archives, addressable: !immutableConflict && !duplicate, compatibility, detailAvailability, source, fingerprint };
+}
+function loadObjective(projectRoot, objectiveId, verb) {
+    const objective = selectedObjective(projectRoot, objectiveId, verb);
+    const projections = [];
+    const archives = [];
+    const diagnostics = [];
+    for (const objectivePath of objective.paths) {
+        const projection = readProjection(objectiveId, objectivePath);
+        projections.push(...projection.sources);
+        diagnostics.push(...projection.diagnostics);
+        const archive = readArchives(objectiveId, objectivePath);
+        archives.push(...archive.sources);
+        diagnostics.push(...archive.diagnostics);
+    }
+    const numbers = [...new Set([
+            ...projections.map((source) => Number(source.record.number)).filter((number) => Number.isSafeInteger(number) && number >= 0),
+            ...archives.map((source) => Number(source.record.number)),
+        ])].sort((left, right) => right - left);
+    const experiments = numbers.map((number) => logicalExperiment(objectiveId, number, projections.filter((source) => source.record.number === number), archives.filter((source) => source.record.number === number)));
+    for (const source of projections.filter((item) => !Number.isSafeInteger(item.record.number) || Number(item.record.number) < 0)) {
+        const fingerprint = hash({ path: source.path, collection: source.collection, index: source.index, record: source.record });
+        experiments.push({
+            key: `unaddressable:${fingerprint}`,
+            stableId: null,
+            number: null,
+            projection: [source],
+            archives: [],
+            addressable: false,
+            compatibility: source.compatibility,
+            detailAvailability: source.collection === "experiments" ? "full" : "summary",
+            source: "legacy_unaddressable_projection",
+            fingerprint,
+        });
+    }
+    return { objective, experiments, diagnostics };
+}
+function provenance(experiment, objective) {
+    return {
+        objective: {
+            stable_id: objective.stableId,
+            compatibility: objective.compatibility,
+            paths: objective.paths,
+            roots: objective.roots,
+            slugs: objective.slugs,
+        },
+        projection: experiment.projection.map((source) => ({ path: source.path, collection: source.collection, index: source.index })),
+        archive: experiment.archives.map((source) => ({ path: source.path, record_sha256: source.recordSha256, provenance: source.provenance })),
+    };
+}
+function summaryRecord(experiment) {
+    const source = experiment.archives[0]?.record ?? experiment.projection[0]?.record;
+    if (!source)
+        return undefined;
+    const summary = {};
+    for (const field of ["date", "label", "status", "summary", "conclusion"])
+        if (source[field] !== undefined)
+            summary[field] = source[field];
+    return Object.keys(summary).length > 0 ? summary : undefined;
+}
+function listEntry(experiment, objective) {
+    return {
+        stable_id: experiment.stableId,
+        artifact_id: "experiments",
+        experiment_number: experiment.number,
+        addressable: experiment.addressable,
+        detail_availability: experiment.detailAvailability,
+        compatibility: experiment.compatibility,
+        source: experiment.source,
+        provenance: provenance(experiment, objective),
+        retrieval: experiment.addressable
+            ? { get: `agentera state experiments get --objective ${objective.stableId} --number ${experiment.number} --format json` }
+            : { get: null, recovery: "Repair the legacy identity or immutable conflict before exact retrieval." },
+        ...(summaryRecord(experiment) ? { summary: summaryRecord(experiment) } : {}),
+    };
+}
+function snapshotId(experiments) {
+    return hash({ collection: "experiments.records", order: ORDER, candidates: experiments.map(({ key, fingerprint }) => ({ key, fingerprint })) });
+}
+function cursorKey(projectRoot) {
+    return createHash("sha256").update(`agentera-experiment-cursor\0${path.resolve(projectRoot)}`, "utf8").digest();
+}
+function sign(payload, projectRoot) {
+    return createHmac("sha256", cursorKey(projectRoot)).update(canonicalRecordJson(payload), "utf8").digest("hex");
+}
+function encodeCursor(payload, projectRoot) {
+    return deflateRawSync(Buffer.from(JSON.stringify({ ...payload, signature: sign(payload, projectRoot) }), "utf8")).toString("base64url");
+}
+function parseCursor(token, projectRoot, objectiveId) {
+    const invalid = (message) => {
+        throw fail(2, "cursor_invalid", message, "list", {
+            recovery: "Copy response.next_cursor exactly for the same objective, or omit --cursor to establish a new snapshot.",
+            details: { cursor: "opaque; do not parse or construct cursor tokens" },
+        });
+    };
+    if (!token || token.length > 100_000 || !/^[A-Za-z0-9_-]+$/.test(token))
+        invalid("cursor is not a valid opaque token");
+    let decoded;
+    try {
+        const compressed = Buffer.from(token, "base64url");
+        if (compressed.toString("base64url") !== token)
+            invalid("cursor is not a canonical opaque token");
+        decoded = JSON.parse(inflateRawSync(compressed, { maxOutputLength: 1_000_000 }).toString("utf8"));
+    }
+    catch {
+        invalid("cursor is not a valid opaque token");
+    }
+    if (!mapping(decoded))
+        invalid("cursor payload is invalid");
+    const { signature, ...unsigned } = decoded;
+    if (typeof signature !== "string" || !/^[0-9a-f]{64}$/.test(signature))
+        invalid("cursor signature is invalid");
+    const expected = sign(unsigned, projectRoot);
+    if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected)))
+        invalid("cursor signature is invalid");
+    if (unsigned.version !== CURSOR_VERSION || unsigned.collection !== "experiments.records" || unsigned.order !== ORDER || unsigned.objective_id !== objectiveId)
+        invalid("cursor is bound to a different collection, objective, or order");
+    if (!Number.isSafeInteger(unsigned.after) || Number(unsigned.after) < 1 || !Array.isArray(unsigned.candidate_keys) || unsigned.candidate_keys.some((key) => typeof key !== "string"))
+        invalid("cursor payload is invalid");
+    if (typeof unsigned.snapshot_id !== "string" || !/^[0-9a-f]{64}$/.test(unsigned.snapshot_id) || typeof unsigned.diagnostic_hash !== "string" || !/^[0-9a-f]{64}$/.test(unsigned.diagnostic_hash))
+        invalid("cursor snapshot is invalid");
+    return unsigned;
+}
+function snapshotExperiments(current, cursor) {
+    const byKey = new Map(current.experiments.map((experiment) => [experiment.key, experiment]));
+    const experiments = cursor.candidate_keys.map((key) => byKey.get(key));
+    if (experiments.some((experiment) => !experiment) || snapshotId(experiments) !== cursor.snapshot_id || hash(current.diagnostics) !== cursor.diagnostic_hash) {
+        throw fail(1, "cursor_snapshot_unavailable", "the objective experiment snapshot changed and cannot be resumed exactly", "list", {
+            recovery: "Start a new experiment listing without --cursor to establish a current objective snapshot.",
+            details: { snapshot_id: cursor.snapshot_id },
+        });
+    }
+    return experiments;
+}
+function withPage(loaded, experiments, start, retained, projectRoot, reason) {
+    const selected = experiments.slice(start, start + retained);
+    const remaining = experiments.length - start - selected.length;
+    const omitted = remaining > 0;
+    const snapshot = snapshotId(experiments);
+    const response = {
+        schemaVersion: "agentera.stateRetrieval.v1",
+        command: "state experiments list",
+        status: loaded.diagnostics.length > 0 || loaded.objective.compatibility !== "canonical" || experiments.some((entry) => !entry.addressable || entry.detailAvailability !== "full") ? "degraded" : "ok",
+        entries: selected.map((entry) => listEntry(entry, loaded.objective)),
+        counts: { total: experiments.length, returned: selected.length, remaining, omitted: remaining, diagnostics: loaded.diagnostics.length },
+        order: ORDER,
+        filters: { objective: loaded.objective.stableId },
+        snapshot: { id: snapshot, candidate_count: experiments.length, has_more: omitted },
+        source: {
+            artifact: "experiments",
+            storage: "objective_projection_and_immutable_objective_archive",
+            objective_paths: loaded.objective.paths,
+            compatibility_diagnostics: loaded.diagnostics,
+        },
+        source_contract: {
+            authority: AUTHORITY,
+            complete_for_experiment_list_retrieval: true,
+            storage_ownership: "objective_scoped_durable_records_and_bounded_10_40_50_projection",
+        },
+        retrieval: { get: `agentera state experiments get --objective ${loaded.objective.stableId} --number N --format json` },
+        omitted,
+        omitted_count: remaining,
+        omission_reason: omitted ? reason : null,
+    };
+    if (omitted) {
+        response.next_cursor = encodeCursor({
+            version: CURSOR_VERSION,
+            collection: "experiments.records",
+            objective_id: loaded.objective.stableId,
+            order: ORDER,
+            snapshot_id: snapshot,
+            candidate_keys: experiments.map((entry) => entry.key),
+            diagnostic_hash: hash(loaded.diagnostics),
+            after: start + selected.length,
+        }, projectRoot);
+        response.retrieval.continue = `agentera state experiments list --objective ${loaded.objective.stableId} --limit 20 --cursor ${response.next_cursor} --format json`;
+    }
+    return response;
+}
+function serializedBytes(response, format) {
+    const bytes = format === "yaml" ? YAML.stringify(response) : JSON.stringify(response, null, 2) + "\n";
+    return Buffer.byteLength(bytes, "utf8");
+}
+export function listExperiments(projectRoot, objectiveId, options) {
+    if (!Number.isSafeInteger(options.limit) || options.limit < 1 || options.limit > 100)
+        throw fail(2, "invalid_request", "experiment list limit must be an integer from 1 through 100", "list", { valid_values: ["1..100"] });
+    const loaded = loadObjective(projectRoot, objectiveId, "list");
+    const parsed = options.cursor ? parseCursor(options.cursor, projectRoot, objectiveId) : undefined;
+    const experiments = parsed ? snapshotExperiments(loaded, parsed) : loaded.experiments;
+    const start = parsed?.after ?? 0;
+    if (start > experiments.length)
+        throw fail(2, "cursor_invalid", "cursor position is outside its experiment snapshot", "list");
+    const requested = Math.min(options.limit, experiments.length - start);
+    let response = withPage(loaded, experiments, start, requested, projectRoot, "page_limit");
+    if (options.format !== "text") {
+        for (let retained = requested; retained > 0 && serializedBytes(response, options.format) > MAX_LIST_BYTES; retained -= 1)
+            response = withPage(loaded, experiments, start, retained - 1, projectRoot, "serialized_output_byte_budget");
+        if (serializedBytes(response, options.format) > MAX_LIST_BYTES || (experiments.length > start && response.entries.length === 0)) {
+            throw fail(1, "unsupported_state", `one experiment identity cannot fit within the ${MAX_LIST_BYTES}-byte ${options.format.toUpperCase()} list budget`, "list", {
+                recovery: `Fetch one known identity with agentera state experiments get --objective ${objectiveId} --number N --format json.`,
+            });
+        }
+    }
+    return response;
+}
+export function getExperiment(projectRoot, objectiveId, number) {
+    if (!Number.isSafeInteger(number) || number < 0)
+        throw fail(2, "invalid_request", "--number must be a non-negative integer without leading zeros", "get", { valid_values: ["0", "1", "2", "..."] });
+    const loaded = loadObjective(projectRoot, objectiveId, "get");
+    const corruptArchive = loaded.diagnostics.find((diagnostic) => diagnostic.class === "corrupt" && diagnostic.experiment_number === number);
+    if (corruptArchive)
+        throw fail(1, "corrupt", `experiment archive for '${objectiveId}/experiment:${number}' cannot be verified`, "get", {
+            stable_id: `${objectiveId}/experiment:${number}`,
+            entry_number: number,
+            recovery: "Preserve and repair the immutable archive envelope before retrying exact retrieval.",
+            details: { diagnostic: corruptArchive },
+        });
+    const experiment = loaded.experiments.find((candidate) => candidate.number === number);
+    if (!experiment)
+        throw fail(1, "not_found", `experiment '${objectiveId}/experiment:${number}' was not found`, "get", {
+            stable_id: `${objectiveId}/experiment:${number}`,
+            entry_number: number,
+            recovery: `List known identities with agentera state experiments list --objective ${objectiveId} --format json, then retry.`,
+        });
+    if (experiment.compatibility === "immutable_conflict")
+        throw fail(1, "immutable_conflict", `experiment '${experiment.stableId}' differs between immutable archive and retained projection`, "get", {
+            stable_id: experiment.stableId,
+            entry_number: number,
+            recovery: "Preserve the immutable archive and reconcile the conflicting projection before retrying.",
+            details: { provenance: provenance(experiment, loaded.objective) },
+        });
+    if (!experiment.addressable)
+        throw fail(1, "ambiguous", `experiment '${experiment.stableId}' has duplicate retained identities`, "get", {
+            stable_id: experiment.stableId,
+            entry_number: number,
+            recovery: "Repair duplicate projection identities; Agentera will not choose by array order.",
+            details: { provenance: provenance(experiment, loaded.objective) },
+        });
+    const archive = experiment.archives[0];
+    const retainedFull = experiment.projection.find((source) => source.collection === "experiments");
+    const summary = experiment.projection.find((source) => source.collection !== "experiments");
+    const record = archive?.record ?? retainedFull?.record ?? summary?.record;
+    if (!record || experiment.detailAvailability === "unavailable")
+        throw fail(1, "incomplete", `experiment '${experiment.stableId}' exists but detail is unavailable`, "get", {
+            stable_id: experiment.stableId, entry_number: number,
+            recovery: "Restore a retained or immutable experiment record; Agentera will not reconstruct dropped legacy detail.",
+        });
+    return {
+        schemaVersion: "agentera.stateRetrieval.v1",
+        command: "state experiments get",
+        status: experiment.detailAvailability === "full" ? "ok" : "degraded",
+        entry: listEntry(experiment, loaded.objective),
+        record,
+        source: {
+            artifact: "experiments",
+            objective_id: objectiveId,
+            experiment_number: number,
+            selected: archive ? "immutable_archive" : retainedFull ? "retained_projection" : "legacy_summary_projection",
+            archive_verified: Boolean(archive),
+            projection_verified_against_archive: Boolean(archive && retainedFull),
+            provenance: provenance(experiment, loaded.objective),
+        },
+        source_contract: {
+            authority: AUTHORITY,
+            complete_for_experiment_retrieval: true,
+            detail_availability: experiment.detailAvailability,
+            compatibility_truth: experiment.detailAvailability === "summary" ? "summary_only_legacy_detail_is_not_reconstructed" : "full_detail_available",
+            storage_ownership: archive ? "immutable_objective_archive" : "bounded_objective_projection",
+        },
+    };
+}
+//# sourceMappingURL=experimentRetrieval.js.map