agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/state/exactReplacementRecovery.js

@@ -0,0 +1,18 @@
+export class ExactReplacementConflictError extends Error {
+    retainedPaths;
+    constructor(message, retainedPaths = []) {
+        super(message);
+        this.retainedPaths = retainedPaths;
+        this.name = "ExactReplacementConflictError";
+    }
+}
+export class FileReplacementError extends Error {
+    code;
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = "FileReplacementError";
+        const code = cause?.code;
+        if (typeof code === "string")
+            this.code = code;
+    }
+}

package/dist/state/experimentArchive.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { dumpYamlMapping } from "../core/yaml.js";
+import { assertRealpathBoundary } from "../registries/artifactRegistry.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+const AUTHORITY = "references/artifacts/state-storage-authority.yaml";
+export function prepareExperimentArchive(projectRoot, objectivePath, objectiveId, experimentNumber, record) {
+    if (record.number !== experimentNumber)
+        throw new Error(`experiment archive record number must equal ${experimentNumber}`);
+    const stableId = `${objectiveId}/experiment:${experimentNumber}`;
+    const target = path.join(path.dirname(objectivePath), "archive", "experiments", `${experimentNumber}.yaml`);
+    assertRealpathBoundary(projectRoot, target, "experiment archive");
+    const canonical = canonicalRecordJson(record);
+    const recordSha256 = createHash("sha256").update(canonical, "utf8").digest("hex");
+    const provenance = {
+        authority: AUTHORITY,
+        objective_id: objectiveId,
+        experiment_id: stableId,
+        storage_scope: "objective_directory",
+        publication_order: "archive_before_projection",
+    };
+    const envelope = {
+        schemaVersion: "agentera.experimentArchive.v1",
+        stable_id: stableId,
+        objective_id: objectiveId,
+        experiment_number: experimentNumber,
+        record,
+        record_sha256: recordSha256,
+        provenance,
+    };
+    return {
+        target,
+        directoryDurabilityRoot: path.dirname(objectivePath),
+        bytes: dumpYamlMapping(envelope),
+        stableId,
+        recordSha256,
+        provenance,
+    };
+}
+export function assertExperimentArchiveReplay(publication) {
+    let existing;
+    try {
+        existing = fs.readFileSync(publication.target);
+    }
+    catch {
+        reject({
+            class: "conflict",
+            message: `immutable experiment archive '${publication.target}' could not be read; existing state was preserved`,
+            violations: [`immutable archive identity: ${publication.stableId}`],
+            recovery: "Repair the unreadable archive record before retrying publication.",
+        });
+    }
+    if (existing.equals(Buffer.from(publication.bytes, "utf8")))
+        return;
+    reject({
+        class: "conflict",
+        message: `immutable experiment archive '${publication.target}' already exists with different bytes; existing archive and projection were preserved`,
+        violations: [`immutable archive identity: ${publication.stableId}`],
+        recovery: "Retry only with the byte-equivalent experiment record for this stable identity.",
+    });
+}

package/dist/state/experimentIdentity.js

@@ -0,0 +1,202 @@
+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, sourceBytes) {
+    const inspected = [];
+    const diagnostics = [];
+    for (const root of ["optimize", "optimera"]) {
+        const directory = path.join(projectRoot, ".agentera", root);
+        let sources = [];
+        if (sourceBytes) {
+            sources = [...sourceBytes.entries()].flatMap(([objectivePath, bytes]) => {
+                const candidate = path.relative(directory, objectivePath).split(path.sep);
+                return candidate.length === 2 && candidate[1] === "objective.yaml"
+                    ? [{ slug: candidate[0], objectivePath, bytes }]
+                    : [];
+            }).sort((left, right) => left.slug.localeCompare(right.slug));
+        }
+        else {
+            let slugs = [];
+            try {
+                slugs = fs.readdirSync(directory).sort();
+            }
+            catch {
+                continue;
+            }
+            sources = slugs.flatMap((slug) => {
+                const objectivePath = path.join(directory, slug, "objective.yaml");
+                return fs.existsSync(objectivePath) ? [{ slug, objectivePath }] : [];
+            });
+        }
+        for (const { slug, objectivePath, bytes } of sources) {
+            try {
+                const identity = resolveObjectiveIdentity(loadYamlMapping(bytes !== undefined ? bytes.toString("utf8") : 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;
+}

package/dist/state/healthEntities.js

@@ -0,0 +1,262 @@
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { StateRetrievalFailure } from "./directRetrieval.js";
+import { allocateAndPublishEntity, allocateEntityId, assertEntityDiscoveryOrigin, discoverEntities, publishEntity, } from "./entityStorage.js";
+import { healthEntityViolations } from "./healthEntityValidation.js";
+import { detailMetadata, detailProvenance, isSummaryEntity } from "./summaryEntityRead.js";
+import { decodeListCursor, encodeListCursor, projectedListSnapshot } from "./listCursor.js";
+import { localDate } from "./write/assign.js";
+import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
+import { entityListSelectorFlags, entityListSelectorKey, projectEntityList, resolveEntityListSelector } from "./entityListProjection.js";
+import { shellQuoteArgument } from "../core/shell.js";
+const ARTIFACT = "health";
+const BOUNDARY = "health_audit";
+const SUMMARY = "health_summary";
+const ORDER = "appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc";
+const ID_PATTERN = /^[a-z]{10}$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positive(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error(`invalid health entity ${field} authority`);
+    return result;
+}
+function contract(sourceRoot = resolveSourceRoot()) {
+    const { authorityPath, document: authority } = loadStateStorageAuthority(sourceRoot);
+    const target = mapping(authority.entity_target) ? authority.entity_target : {};
+    const storage = mapping(target.storage_boundary) && mapping(target.storage_boundary.shared_primitives)
+        ? target.storage_boundary.shared_primitives
+        : {};
+    const entities = Array.isArray(target.entities) ? target.entities : [];
+    const health = entities.find((value) => mapping(value) && value.boundary === BOUNDARY && value.artifact === ARTIFACT);
+    const retrieval = mapping(health) && mapping(health.retrieval) ? health.retrieval : {};
+    if (typeof storage.canonical_root !== "string")
+        throw new Error(`invalid health entity contract in '${authorityPath}'`);
+    return {
+        authorityPath,
+        entityRoot: storage.canonical_root,
+        defaultLimit: positive(retrieval.default_limit, "default_limit"),
+        maximumLimit: positive(retrieval.maximum_limit, "maximum_limit"),
+        maxUtf8Bytes: positive(retrieval.max_utf8_bytes, "max_utf8_bytes"),
+    };
+}
+function failure(kind, message, recovery, id, exitCode = 1) {
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: kind,
+            message,
+            syntax: "agentera state health get --id ID --format json",
+            example: `agentera state health get --id ${id ?? "qjtrmnpvka"} --format json`,
+            recovery,
+            artifact: ARTIFACT,
+            ...(id ? { id } : {}),
+        },
+    }, exitCode);
+}
+function listFailure(kind, message, recovery, exitCode = 1) {
+    const result = failure(kind, message, recovery, undefined, exitCode);
+    result.body.error.syntax = "agentera state health list [--limit N] [--cursor TOKEN] --format json";
+    result.body.error.example = "agentera state health list --limit 20 --format json";
+    return result;
+}
+function healthRecord(values) {
+    for (const field of ["id", "artifact", "number", "stable_id", "artifact_id", "entry_number", "appended_at"]) {
+        if (field in values)
+            throw new Error(`health entity record forbids identity field '${field}'`);
+    }
+    const record = structuredClone(values);
+    if (typeof record.date !== "string")
+        record.date = localDate();
+    record.appended_at = new Date().toISOString();
+    const violations = healthEntityViolations(record);
+    if (violations.length)
+        throw new Error(`health entity violates the canonical audit schema: ${violations.join("; ")}`);
+    return record;
+}
+function envelope(published, record, dryRun) {
+    return {
+        schemaVersion: "agentera.stateWrite.v1",
+        command: "state health append",
+        status: "pass",
+        path: published.path,
+        id: published.id,
+        artifact: published.artifact,
+        record,
+        operation: { verb: "append", dry_run: dryRun, idempotent_replay: published.replay },
+        validation: { status: "pass", violations: [] },
+    };
+}
+function withoutAppendTimestamp(record) {
+    const copy = structuredClone(record);
+    delete copy.appended_at;
+    return copy;
+}
+function existingReplay(root, sourceRoot, id, record) {
+    const existing = discoverEntities(root, sourceRoot).entities.find((entity) => entity.id === id
+        && entity.artifact === ARTIFACT
+        && entity.boundary === BOUNDARY
+        && entity.classification === "valid"
+        && entity.record !== null
+        && healthEntityViolations(entity.record).length === 0);
+    if (!existing || canonicalRecordJson(withoutAppendTimestamp(existing.record)) !== canonicalRecordJson(withoutAppendTimestamp(record)))
+        return null;
+    return existing;
+}
+export function appendHealthEntity(req, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const declared = contract(sourceRoot);
+    const record = healthRecord(req.input ?? req.values);
+    if (req.dryRun) {
+        options.publicationContext?.assertValid();
+        const id = options.id ?? allocateEntityId(options.publicationContext?.pinnedPath() ?? req.projectRoot, options.candidate, sourceRoot);
+        options.publicationContext?.assertValid();
+        return envelope({ path: path.join(path.resolve(req.projectRoot), declared.entityRoot, ARTIFACT, BOUNDARY, `${id}.yaml`), id, artifact: ARTIFACT, replay: false }, record, true);
+    }
+    if (options.id) {
+        const replay = existingReplay(req.projectRoot, sourceRoot, options.id, record);
+        if (replay)
+            return envelope({ path: replay.path, id: options.id, artifact: ARTIFACT, replay: true }, replay.record, false);
+    }
+    const published = options.id
+        ? publishEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: BOUNDARY, id: options.id, record })
+        : allocateAndPublishEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: BOUNDARY, record }, options.candidate);
+    return envelope(published, record, false);
+}
+function relative(root, candidate) {
+    return path.relative(path.resolve(root), candidate).split(path.sep).join("/");
+}
+function healthEntities(root, sourceRoot, supplied) {
+    if (supplied)
+        assertEntityDiscoveryOrigin(root, sourceRoot, supplied);
+    const discovery = supplied ?? discoverEntities(root, sourceRoot);
+    const relevant = discovery.entities.filter((entity) => entity.artifact === ARTIFACT || entity.boundary === BOUNDARY);
+    const bad = relevant.find((entity) => entity.classification !== "valid" || !entity.id || !entity.record || (entity.boundary === BOUNDARY && healthEntityViolations(entity.record).length > 0));
+    if (bad)
+        throw listFailure(bad.classification === "duplicate" ? "ambiguous" : "corrupt", `health entity '${bad.relativePath}' is not canonical`, "Run agentera check validate state, preserve conflicting evidence, and repair the canonical entity files.");
+    return relevant;
+}
+function entry(root, entity) {
+    const id = entity.id;
+    return {
+        id,
+        artifact: ARTIFACT,
+        record: entity.record,
+        ...detailMetadata(entity),
+        provenance: detailProvenance(relative(root, entity.path), entity),
+        retrieval: { get: `agentera state health get --id ${id} --format json` },
+    };
+}
+export function getHealthEntity(root, id, sourceRoot = resolveSourceRoot()) {
+    if (!ID_PATTERN.test(id))
+        throw failure("invalid_request", `health ID '${id}' must be ten lowercase letters`, "Use a bare ID returned by health append or list.", id, 2);
+    const all = discoverEntities(root, sourceRoot).entities;
+    const matches = all.filter((entity) => entity.id === id);
+    if (matches.length > 1 || matches.some((entity) => entity.classification === "duplicate"))
+        throw failure("ambiguous", `health entity ID '${id}' has multiple canonical candidates`, "Run agentera check validate state, preserve conflicting evidence, and assign unique IDs.", id);
+    const selected = matches[0];
+    const expectedPath = path.join(path.resolve(root), contract(sourceRoot).entityRoot, ARTIFACT, selected?.boundary === SUMMARY ? SUMMARY : BOUNDARY, `${id}.yaml`);
+    const canonical = all.find((entity) => entity.path === expectedPath);
+    if (!selected && canonical)
+        throw failure("corrupt", `health entity '${canonical.relativePath}' does not match its canonical ID envelope`, "Run agentera check validate state and repair the canonical entity file.", id);
+    if (!selected || selected.artifact !== ARTIFACT || ![BOUNDARY, SUMMARY].includes(selected.boundary ?? ""))
+        throw failure("not_found", `no health entity exists with ID '${id}'`, "Copy an ID from agentera state health list --format json and retry.", id);
+    if (selected.classification !== "valid" || !selected.record || (selected.boundary === BOUNDARY && healthEntityViolations(selected.record).length > 0))
+        throw failure("corrupt", `health entity '${selected.relativePath}' is corrupt or violates the audit contract`, "Run agentera check validate state, preserve its evidence, and repair the canonical entity file.", id);
+    return {
+        schemaVersion: "agentera.stateRetrieval.v1",
+        command: "state health get",
+        status: isSummaryEntity(selected) ? "degraded" : "ok",
+        entry: entry(root, selected),
+        source: { artifact: ARTIFACT, authority: "canonical_entity_file" },
+        source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: isSummaryEntity(selected) ? "summary" : "full" },
+    };
+}
+function appendTimestamp(entity) {
+    return typeof entity.record?.appended_at === "string" ? entity.record.appended_at : null;
+}
+function compareHealthEntities(left, right) {
+    const leftTimestamp = appendTimestamp(left);
+    const rightTimestamp = appendTimestamp(right);
+    if (leftTimestamp !== null && rightTimestamp !== null) {
+        return rightTimestamp.localeCompare(leftTimestamp) || left.id.localeCompare(right.id);
+    }
+    if (leftTimestamp !== null)
+        return -1;
+    if (rightTimestamp !== null)
+        return 1;
+    return String(right.record.date ?? "").localeCompare(String(left.record.date ?? "")) || left.id.localeCompare(right.id);
+}
+function key(entity) {
+    return `${appendTimestamp(entity) ?? String(entity.record.date ?? "")}\0${entity.id}`;
+}
+function snapshot(root, entities, dimension, entityRoot) {
+    return projectedListSnapshot({
+        schemaVersion: "agentera.stateList.v1",
+        command: "state health list",
+        order: ORDER,
+        filters: { dimension: dimension ?? null },
+        source: { artifact: ARTIFACT, authority: "canonical_entity_files", root: entityRoot },
+        source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: entities.some(isSummaryEntity) ? "mixed" : "full", cursor: "opaque_snapshot_cursor" },
+        entries: entities.map((entity) => entry(root, entity)),
+    });
+}
+function encode(payload, root, authorityPath) {
+    return encodeListCursor(payload, root, authorityPath);
+}
+function decode(token, root, authorityPath) {
+    try {
+        return decodeListCursor(token, root, authorityPath);
+    }
+    catch {
+        throw listFailure("cursor_invalid", "health cursor is malformed or belongs to another project", "Copy next_cursor exactly, or omit --cursor to restart.");
+    }
+}
+export function listHealthEntities(root, limit, dimension, cursor, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const declared = contract(sourceRoot);
+    const effectiveLimit = limit ?? declared.defaultLimit;
+    if (!Number.isSafeInteger(effectiveLimit) || effectiveLimit < 1 || effectiveLimit > declared.maximumLimit)
+        throw listFailure("invalid_request", `health list limit must be 1..${declared.maximumLimit}`, "Use a limit in the declared range.", 2);
+    const all = healthEntities(root, sourceRoot, options.discovery);
+    let filtered = [...all].sort(compareHealthEntities);
+    if (dimension) {
+        const needle = dimension.toLowerCase();
+        filtered = filtered.filter((entity) => canonicalRecordJson(entity.record).toLowerCase().includes(needle));
+    }
+    const format = options.format ?? "json";
+    const projectionOptions = { family: "health", artifact: ARTIFACT, boundary: BOUNDARY, format, maxUtf8Bytes: declared.maxUtf8Bytes, selector: options.selector };
+    const selector = resolveEntityListSelector(options.selector, filtered.map((entity) => entry(root, entity)), projectionOptions);
+    const selectorKey = entityListSelectorKey(selector);
+    const snap = snapshot(root, filtered, dimension, declared.entityRoot);
+    let start = 0;
+    if (cursor) {
+        const value = decode(cursor, root, declared.authorityPath);
+        if (value.selector !== selectorKey)
+            throw listFailure("cursor_invalid", "health cursor selectors do not match this request", "Repeat the original selector, or omit --cursor to restart from the current snapshot.");
+        if (value.version !== 1 || value.artifact !== ARTIFACT || value.order !== ORDER || value.snapshot_id !== snap || value.dimension !== (dimension ?? null))
+            throw listFailure("cursor_snapshot_unavailable", "health state or filters changed after this cursor snapshot", "Repeat the original filters, or omit --cursor to restart from the current snapshot.");
+        const found = filtered.findIndex((entity) => key(entity) === value.after_key);
+        if (found < 0)
+            throw listFailure("cursor_snapshot_unavailable", "health cursor continuation is unavailable", "Omit --cursor to restart.");
+        start = found + 1;
+    }
+    const selected = filtered.slice(start, start + effectiveLimit);
+    const response = () => {
+        const remaining = filtered.length - start - selected.length;
+        const next = remaining && selected.length ? encode({ version: 1, artifact: ARTIFACT, order: ORDER, snapshot_id: snap, selector: selectorKey, dimension: dimension ?? null, after_key: key(selected.at(-1)) }, root, declared.authorityPath) : undefined;
+        const selectorFlags = entityListSelectorFlags(selector);
+        return {
+            schemaVersion: "agentera.stateList.v1", command: "state health list", status: remaining || filtered.some(isSummaryEntity) ? "degraded" : "ok", entries: selected.map((entity) => entry(root, entity)),
+            counts: { total: filtered.length, returned: selected.length, remaining }, filters: { dimension: dimension ?? null }, snapshot: { id: snap, first_page: !cursor, order: ORDER, has_more: Boolean(remaining), candidate_count: filtered.length },
+            source: { artifact: ARTIFACT, authority: "canonical_entity_files", root: declared.entityRoot }, source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: filtered.some(isSummaryEntity) ? "mixed" : "full", cursor: "opaque_snapshot_cursor" },
+            retrieval: { ...(next ? { continue: `agentera state health list${dimension ? ` --dimension ${shellQuoteArgument(dimension)}` : ""}${selectorFlags} --limit ${effectiveLimit} --cursor ${next} --format json` } : {}) },
+            ...(remaining ? { omitted: true, omitted_count: remaining, omission_reason: "page_limit", next_cursor: next } : {}),
+        };
+    };
+    return projectEntityList(response(), selector, projectionOptions);
+}

package/dist/state/healthEntityValidation.js

@@ -0,0 +1,18 @@
+import { dumpYamlMapping } from "../core/yaml.js";
+import { validateArtifactBytes } from "./write/validate.js";
+export function healthEntityViolations(record) {
+    const violations = validateArtifactBytes("health", dumpYamlMapping({ audits: [{ number: 1, ...record }] }));
+    if (record.appended_at !== undefined) {
+        const value = record.appended_at;
+        let canonical = false;
+        if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+            try {
+                canonical = new Date(value).toISOString() === value;
+            }
+            catch { /* invalid timestamp */ }
+        }
+        if (!canonical)
+            violations.push("appended_at must be a canonical UTC ISO-8601 timestamp");
+    }
+    return violations;
+}

package/dist/state/healthRepair.js

@@ -0,0 +1,69 @@
+import YAML from "yaml";
+function healthIdentityNumber(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const mapping = value;
+        const number = mapping.number;
+        if (Number.isSafeInteger(number) && Number(number) > 0)
+            return Number(number);
+        return healthIdentityNumber(mapping.summary);
+    }
+    if (typeof value !== "string")
+        return null;
+    const match = /^Audit\s+([1-9][0-9]*)\b/.exec(value.trim());
+    return match ? Number(match[1]) : null;
+}
+export function repairHealthDuplicates(doc, number, keep) {
+    const candidate = structuredClone(doc);
+    let removed = 0;
+    for (const key of ["audits", "archive"]) {
+        const values = Array.isArray(candidate[key]) ? candidate[key] : [];
+        const matches = values.flatMap((value, index) => (healthIdentityNumber(value) === number ? [index] : []));
+        if (matches.length < 2)
+            continue;
+        const retained = keep === "last" ? matches.at(-1) : matches[0];
+        candidate[key] = values.filter((_, index) => !matches.includes(index) || index === retained);
+        removed += matches.length - 1;
+    }
+    return { candidate, removed };
+}
+export function repairHealthProjectionBytes(bytes, number, keep) {
+    const document = YAML.parseDocument(bytes);
+    const removals = [];
+    let removed = 0;
+    for (const key of ["audits", "archive"]) {
+        const sequence = document.get(key, true);
+        const items = sequence?.items ?? [];
+        const sequenceEnd = sequence?.range?.[1];
+        const matches = items.flatMap((item, index) => {
+            const value = typeof item?.toJSON === "function"
+                ? item.toJSON()
+                : item;
+            return healthIdentityNumber(value) === number ? [index] : [];
+        });
+        if (matches.length < 2)
+            continue;
+        const retained = keep === "last" ? matches.at(-1) : matches[0];
+        for (const index of matches) {
+            if (index === retained)
+                continue;
+            const range = items[index]?.range;
+            if (!range || range.length < 2)
+                throw new Error(`health ${key} row ${index} has no stable YAML range`);
+            const lineStart = bytes.lastIndexOf("\n", range[0] - 1) + 1;
+            const nextRange = items[index + 1]?.range;
+            const rawEnd = nextRange?.[0] ?? sequenceEnd ?? bytes.length;
+            const lineEnd = nextRange
+                ? bytes.lastIndexOf("\n", rawEnd - 1) + 1
+                : (() => {
+                    const newline = bytes.indexOf("\n", Math.max(range[1], rawEnd));
+                    return newline < 0 ? bytes.length : newline + 1;
+                })();
+            removals.push([lineStart, Math.max(lineStart, lineEnd)]);
+            removed += 1;
+        }
+    }
+    for (const [start, end] of removals.sort((left, right) => right[0] - left[0])) {
+        bytes = bytes.slice(0, start) + bytes.slice(end);
+    }
+    return { bytes, removed };
+}