agentera 3.0.0-dev.7 → 3.0.0-dev.74

package/dist/state/progressGlossaryCaveat.js

@@ -0,0 +1,168 @@
+import { glossaryCaveatPairAllowed, glossaryCaveatContract, } from "../registries/glossaryCaveatContract.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boundedString(value, contract) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        Buffer.byteLength(value, "utf8") <= contract.maxStringUtf8Bytes);
+}
+function isProjectionSource(entity, contract) {
+    return entity.artifact === contract.primeSourceArtifact && entity.boundary === contract.primeSourceBoundary;
+}
+export function validateProgressGlossaryCaveat(record, contract = glossaryCaveatContract()) {
+    if (!Object.prototype.hasOwnProperty.call(record, "glossary_caveat")) {
+        return { status: "absent", caveat: null, violations: [] };
+    }
+    const value = record.glossary_caveat;
+    const violations = [];
+    if (!mapping(value)) {
+        return {
+            status: "invalid",
+            caveat: null,
+            violations: ["glossary_caveat must be one privacy-safe mapping"],
+        };
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== contract.fields.length ||
+        keys.some((field) => !contract.fields.includes(field))) {
+        violations.push("glossary_caveat must contain exactly the authority-declared fields");
+    }
+    if (contract.fields.some((field) => !(field in value))) {
+        violations.push("glossary_caveat requires every authority-declared field");
+    }
+    for (const field of ["caveat_id", "event", "capability", "reason", "ownership_state"])
+        if (!boundedString(value[field], contract))
+            violations.push("glossary_caveat string fields must be non-empty and bounded");
+    if (!contract.idPattern.test(typeof value.caveat_id === "string" ? value.caveat_id : ""))
+        violations.push("glossary_caveat caveat_id must be one opaque ID");
+    if (!contract.events.includes(typeof value.event === "string" ? value.event : ""))
+        violations.push("glossary_caveat event is outside the bounded vocabulary");
+    if (!contract.capabilities.includes(typeof value.capability === "string" ? value.capability : ""))
+        violations.push("glossary_caveat capability is outside the bounded vocabulary");
+    if (value.capability !== contract.primeSourceCapability)
+        violations.push("glossary_caveat capability does not own prime projection evidence");
+    if (!contract.reasons.includes(typeof value.reason === "string" ? value.reason : ""))
+        violations.push("glossary_caveat reason is outside the bounded vocabulary");
+    if (!contract.ownershipStates.includes(typeof value.ownership_state === "string" ? value.ownership_state : ""))
+        violations.push("glossary_caveat ownership_state is outside the bounded vocabulary");
+    if (typeof value.reason === "string" &&
+        typeof value.ownership_state === "string" &&
+        !glossaryCaveatPairAllowed(contract, value.reason, value.ownership_state))
+        violations.push("glossary_caveat reason and ownership_state pair is not allowed");
+    const transition = value.transition_id;
+    if (!(transition === null || boundedString(transition, contract)))
+        violations.push("glossary_caveat transition_id must be null or one bounded opaque ID");
+    if (typeof transition === "string" && !contract.idPattern.test(transition))
+        violations.push("glossary_caveat transition_id must be one opaque ID");
+    if ((value.event === "current" || value.event === "resolved") && transition !== null)
+        violations.push("current and resolved glossary_caveat events require null transition_id");
+    if (value.event === "superseded" &&
+        (typeof transition !== "string" || transition === value.caveat_id))
+        violations.push("superseded glossary_caveat requires one different successor ID");
+    if (violations.length)
+        return { status: "invalid", caveat: null, violations: [...new Set(violations)] };
+    return { status: "valid", caveat: value, violations: [] };
+}
+export function glossaryCaveatLifecycleInvalidEntities(entities, contract = glossaryCaveatContract()) {
+    const rows = entities.flatMap((entity) => {
+        if (entity.classification !== "valid" || !entity.record)
+            return [];
+        const result = validateProgressGlossaryCaveat(entity.record, contract);
+        return result.status === "valid" ? [{ entity, caveat: result.caveat }] : [];
+    });
+    const invalid = new Set();
+    const byId = new Map();
+    for (const row of rows)
+        byId.set(row.caveat.caveat_id, [...(byId.get(row.caveat.caveat_id) ?? []), row]);
+    const transitions = new Map();
+    for (const [id, matches] of byId) {
+        const current = matches.filter(({ caveat }) => caveat.event === "current");
+        const terminal = matches.filter(({ caveat }) => caveat.event !== "current");
+        if (current.length !== 1) {
+            matches.forEach(({ entity }) => invalid.add(entity));
+            continue;
+        }
+        if (terminal.length > 1) {
+            terminal.forEach(({ entity }) => invalid.add(entity));
+            continue;
+        }
+        if (terminal.length && current.length === 1) {
+            const base = current[0].caveat;
+            for (const row of terminal) {
+                if (row.caveat.capability !== base.capability ||
+                    row.caveat.reason !== base.reason ||
+                    row.caveat.ownership_state !== base.ownership_state) {
+                    invalid.add(row.entity);
+                    continue;
+                }
+                if (row.caveat.event === "superseded") {
+                    const target = byId.get(row.caveat.transition_id) ?? [];
+                    if (target.filter(({ caveat }) => caveat.event === "current").length !== 1) {
+                        invalid.add(row.entity);
+                    }
+                    else
+                        transitions.set(id, { target: row.caveat.transition_id, entity: row.entity });
+                }
+            }
+        }
+    }
+    for (const start of transitions.keys()) {
+        const seen = new Set();
+        let cursor = start;
+        while (cursor && !seen.has(cursor)) {
+            seen.add(cursor);
+            cursor = transitions.get(cursor)?.target;
+        }
+        if (cursor)
+            for (const id of seen) {
+                const transition = transitions.get(id);
+                if (transition)
+                    invalid.add(transition.entity);
+            }
+    }
+    return invalid;
+}
+/** Project only validated lifecycle state; opaque identities never leave this module. */
+export function projectCurrentGlossaryCaveats(entities, contract = glossaryCaveatContract()) {
+    const byId = new Map();
+    for (const entity of entities) {
+        if (entity.classification !== "valid" ||
+            !entity.record ||
+            !isProjectionSource(entity, contract))
+            continue;
+        const result = validateProgressGlossaryCaveat(entity.record, contract);
+        if (result.status !== "valid")
+            continue;
+        byId.set(result.caveat.caveat_id, [
+            ...(byId.get(result.caveat.caveat_id) ?? []),
+            result.caveat,
+        ]);
+    }
+    let currentCount = 0;
+    for (const events of byId.values()) {
+        if (events.some(({ event }) => event === "current") &&
+            !events.some(({ event }) => event !== "current"))
+            currentCount += 1;
+    }
+    return {
+        currentCount,
+        attention: currentCount > 0 && contract.primeAttentionText ? contract.primeAttentionText : null,
+        publicAttentionLimit: contract.primePublicAttentionLimit,
+        reservedGlossarySlots: contract.primeReservedGlossarySlots,
+    };
+}
+export function applyGlossaryCaveatLifecycleValidation(projectRoot, entities, issues, contract) {
+    for (const entity of glossaryCaveatLifecycleInvalidEntities(entities.filter((candidate) => isProjectionSource(candidate, contract)), contract)) {
+        entity.classification = "malformed";
+        issues.push({
+            code: "malformed_entity",
+            path: entity.relativePath,
+            id: entity.id ?? undefined,
+            artifact: entity.artifact ?? undefined,
+            boundary: entity.boundary ?? undefined,
+            message: `entity '${entity.relativePath}' has an invalid glossary caveat lifecycle relation`,
+            recovery: `repair '${entity.relativePath}' using the Build-owned progress glossary caveat lifecycle; rerun agentera check validate state --cwd ${JSON.stringify(projectRoot)}`,
+        });
+    }
+}

package/dist/state/progressPublicationOrder.js

@@ -0,0 +1,19 @@
+export const PROGRESS_PUBLICATION_ORDER_FIELD = "publication_order";
+export function progressPublicationOrder(record) {
+    const value = record?.[PROGRESS_PUBLICATION_ORDER_FIELD];
+    return Number.isSafeInteger(value) && Number(value) > 0 ? Number(value) : null;
+}
+export function progressPublicationOrderViolations(record) {
+    if (!(PROGRESS_PUBLICATION_ORDER_FIELD in record))
+        return [];
+    return progressPublicationOrder(record) === null
+        ? ["publication_order must be a positive safe integer when present"]
+        : [];
+}
+export function nextProgressPublicationOrder(records) {
+    const maximum = records.reduce((current, record) => Math.max(current, progressPublicationOrder(record) ?? 0), 0);
+    if (maximum >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("progress publication order is exhausted; preserve state and request repair before retrying");
+    }
+    return maximum + 1;
+}

package/dist/state/progressWritePolicy.js

@@ -0,0 +1,33 @@
+const APPEND_GUIDANCE = "Append progress only for durable project truth that future work needs, a required glossary_caveat lifecycle event, or a plan-completion sweep. Glossary caveats and plan-completion sweeps require a record; an ordinary build or release attempt with no durable project truth change, and an outcome future work does not need as a milestone, require no progress append.";
+const RECEIPT_GUIDANCE = "Qualification and publication receipts own timings, integrity, digests, retries, and replay; do not duplicate receipt detail in progress.";
+const PROGRESS_WRITE_POLICY = {
+    schemaVersion: "agentera.progressWritePolicy.v1",
+    append: {
+        mode: "conditional",
+        allowed_when: [
+            "durable_project_truth_needed_by_future_work",
+            "required_glossary_caveat",
+            "plan_completion_sweep",
+        ],
+        required_when: [
+            "required_glossary_caveat",
+            "plan_completion_sweep",
+        ],
+        no_append_required_when: [
+            "ordinary_build_or_release_attempt_without_durable_project_truth_change",
+            "durable_outcome_not_needed_by_future_work",
+        ],
+        guidance: APPEND_GUIDANCE,
+    },
+    receipt_detail: {
+        owners: ["qualification_receipt", "publication_receipt"],
+        fields: ["timings", "integrity", "digests", "retries", "replay"],
+        guidance: RECEIPT_GUIDANCE,
+    },
+};
+export function progressWritePolicy() {
+    return structuredClone(PROGRESS_WRITE_POLICY);
+}
+export function progressWriteGuidance() {
+    return [APPEND_GUIDANCE, RECEIPT_GUIDANCE];
+}

package/dist/state/projectRoot.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+function directoryPrefixes(absolute) {
+    const parsed = path.parse(absolute);
+    const segments = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+    return [parsed.root, ...segments.map((_, index) => path.join(parsed.root, ...segments.slice(0, index + 1)))];
+}
+export function assertValidatedProjectRoot(root) {
+    const stable = root.identities.every((identity) => {
+        try {
+            const current = fs.lstatSync(identity.absolute, { bigint: true });
+            return identity.type === "directory"
+                && current.isDirectory()
+                && !current.isSymbolicLink()
+                && current.dev === identity.dev
+                && current.ino === identity.ino;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!stable) {
+        throw new Error(`project root '${root.path}' changed after validation; restore the exact real directory and retry`);
+    }
+}
+export function validateRealProjectRoot(projectRoot) {
+    const root = path.resolve(projectRoot);
+    let stat;
+    try {
+        stat = fs.lstatSync(root, { bigint: true });
+    }
+    catch {
+        throw new Error(`project root '${root}' does not exist; choose an existing, real directory and retry`);
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error(`project root '${root}' is a symbolic link; choose an existing, real directory and retry`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`project root '${root}' is not a directory; choose an existing, real directory and retry`);
+    }
+    try {
+        if (fs.realpathSync(root) !== root) {
+            throw new Error(`project root '${root}' traverses a symbolic link; choose an existing, real directory and retry`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("project root '"))
+            throw error;
+        throw new Error(`project root '${root}' cannot be resolved safely; choose an existing, real directory and retry`);
+    }
+    const identities = directoryPrefixes(root).map((absolute) => {
+        const current = fs.lstatSync(absolute, { bigint: true });
+        return { absolute, dev: current.dev, ino: current.ino, type: "directory" };
+    });
+    const validated = { path: root, identities };
+    const rootIdentity = identities.at(-1);
+    if (rootIdentity.dev !== stat.dev || rootIdentity.ino !== stat.ino) {
+        throw new Error(`project root '${root}' changed during validation; restore the exact real directory and retry`);
+    }
+    assertValidatedProjectRoot(validated);
+    return validated;
+}

package/dist/state/projectionPolicy.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { loadYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { entityListFamily } from "./entityRetrievalHelp.js";
+const AUTHORITY_RELATIVE_PATH = "references/artifacts/state-storage-authority.yaml";
+const AUTHORITY_SCHEMA_VERSION = "agentera.stateStorageAuthority.v1";
+const NUMBERED_ARTIFACTS = new Set(["progress", "decisions", "health"]);
+function canonicalRetrieval(family) {
+    const list = `agentera state ${family.commandTokens.join(" ")} list --format json`;
+    return { available: true, command: list, list, get: family.get };
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function positiveInteger(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`state storage authority field '${field}' must be a positive integer`);
+    }
+    return value;
+}
+export function loadProjectionPolicy(sourceRoot = resolveSourceRoot()) {
+    const authorityPath = path.join(sourceRoot, AUTHORITY_RELATIVE_PATH);
+    const authority = loadYamlMapping(fs.readFileSync(authorityPath, "utf8"));
+    if (authority.schema_version !== AUTHORITY_SCHEMA_VERSION) {
+        throw new Error(`state storage authority schema_version must be ${AUTHORITY_SCHEMA_VERSION}`);
+    }
+    const capacity = mapping(mapping(authority.projections).current).default_capacity;
+    const activeEntries = positiveInteger(mapping(capacity).active_entries, "projections.current.default_capacity.active_entries");
+    const summaryEntries = positiveInteger(mapping(capacity).summary_entries, "projections.current.default_capacity.summary_entries");
+    const totalEntries = positiveInteger(mapping(capacity).total_entries, "projections.current.default_capacity.total_entries");
+    if (activeEntries + summaryEntries !== totalEntries) {
+        throw new Error("state storage authority projection capacity must equal active plus summary entries");
+    }
+    const maxUtf8Bytes = positiveInteger(mapping(mapping(authority.budgets).projection).max_utf8_bytes, "budgets.projection.max_utf8_bytes");
+    return { activeEntries, summaryEntries, totalEntries, maxUtf8Bytes };
+}
+export function projectionRetrieval(command) {
+    if (NUMBERED_ARTIFACTS.has(command)) {
+        return canonicalRetrieval(entityListFamily(command));
+    }
+    if (command === "plan") {
+        const tasks = entityListFamily("plan_tasks");
+        const plans = entityListFamily("plans");
+        return {
+            available: true,
+            list: `agentera state ${tasks.commandTokens.join(" ")} list --format json`,
+            get: tasks.get,
+            plans_list: `agentera state ${plans.commandTokens.join(" ")} list --format json`,
+            plans_get: plans.get,
+        };
+    }
+    return {
+        available: false,
+        reason: "unsupported_numbered_retrieval",
+        artifact_id: command,
+    };
+}
+export function projectionOmission(command, count, reason, options = {}) {
+    return {
+        omitted: options.forceOmitted ?? count > 0,
+        omitted_count: count,
+        omission_reason: reason,
+        retrieval: projectionRetrieval(command),
+        omission_provenance: options.provenance ?? null,
+    };
+}
+export function serializedProjectionBytes(value, format) {
+    const serialized = format === "yaml" ? YAML.stringify(value, { sortMapEntries: false }) : JSON.stringify(value, null, 2) + "\n";
+    return Buffer.byteLength(serialized, "utf8");
+}
+function entryNumber(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [Number.POSITIVE_INFINITY, index];
+    const object = value;
+    const candidates = [object.entry_number, object.number];
+    for (const candidate of candidates) {
+        if (typeof candidate === "number" && Number.isSafeInteger(candidate))
+            return [candidate, index];
+        if (typeof candidate === "string" && /^[1-9][0-9]*$/.test(candidate))
+            return [Number(candidate), index];
+    }
+    const stableId = object.stable_id;
+    if (typeof stableId === "string") {
+        const match = /:(\d+)$/.exec(stableId);
+        if (match)
+            return [Number(match[1]), index];
+    }
+    return [Number.POSITIVE_INFINITY, index];
+}
+function omissionCount(value) {
+    const count = value.omitted_count;
+    return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 0;
+}
+function boundedValue(value, itemKey, items, omittedCount, command) {
+    const result = { ...value, [itemKey]: items };
+    const existingCounts = result.counts;
+    if (itemKey === "entries" && existingCounts && typeof existingCounts === "object" && !Array.isArray(existingCounts)) {
+        result.counts = {
+            ...existingCounts,
+            entries: items.length + omittedCount,
+            returned_entries: items.length,
+        };
+    }
+    return {
+        ...result,
+        ...projectionOmission(command, omittedCount, "projection_byte_budget", { forceOmitted: true }),
+    };
+}
+function minimalBudgetedProjection(command, omittedCount, policy, format) {
+    const omission = projectionOmission(command, omittedCount, "projection_required_fields_exceed_budget", {
+        forceOmitted: true,
+        provenance: {
+            source: "current_projection",
+            detail_availability: "unavailable",
+            compatibility: "degraded",
+            archive_verified: false,
+            omitted_count: omittedCount,
+        },
+    });
+    const fallback = {
+        command,
+        status: "degraded",
+        entries: [],
+        counts: { entries: omittedCount, returned_entries: 0 },
+        source: { artifact: command, detail_availability: "unavailable", source: "current_projection" },
+        ...omission,
+        error: {
+            class: "projection_output_budget",
+            message: "optional projection detail was omitted because required output fields exceeded the authority byte budget",
+            syntax: `agentera state ${command} --format json`,
+            example: `agentera state ${command} --format json`,
+            recovery: omission.retrieval.available === true
+                ? String(omission.retrieval.command ?? omission.retrieval.list)
+                : "No direct retrieval route is declared for this artifact; use its supported state command.",
+        },
+    };
+    if (serializedProjectionBytes(fallback, format) <= policy.maxUtf8Bytes)
+        return fallback;
+    const minimal = {
+        command,
+        status: "degraded",
+        omitted: true,
+        omitted_count: omittedCount,
+        omission_reason: "projection_output_budget",
+        retrieval: omission.retrieval,
+    };
+    if (serializedProjectionBytes(minimal, format) > policy.maxUtf8Bytes) {
+        throw new Error(`projection output budget ${policy.maxUtf8Bytes} bytes is too small for required omission metadata`);
+    }
+    return minimal;
+}
+/**
+ * Bound a structured projection without truncating strings or splitting UTF-8.
+ * Entries are removed oldest-first by numeric identity; every removal is
+ * declared in the response and points at the future direct-get surface.
+ */
+export function boundStructuredProjection(value, command, format, policy = loadProjectionPolicy()) {
+    if (serializedProjectionBytes(value, format) <= policy.maxUtf8Bytes)
+        return value;
+    const itemKey = Array.isArray(value.entries)
+        ? "entries"
+        : Array.isArray(value.operations)
+            ? "operations"
+            : null;
+    if (itemKey === null)
+        return minimalBudgetedProjection(command, 0, policy, format);
+    const items = value[itemKey];
+    const removalOrder = items
+        .map((item, index) => ({ index, key: entryNumber(item, index) }))
+        .sort((left, right) => left.key[0] - right.key[0] || left.key[1] - right.key[1]);
+    let omitted = omissionCount(value);
+    let retained = [...items];
+    for (const candidate of removalOrder) {
+        if (serializedProjectionBytes(boundedValue(value, itemKey, retained, omitted, command), format) <= policy.maxUtf8Bytes) {
+            return boundedValue(value, itemKey, retained, omitted, command);
+        }
+        const retainedIndex = retained.indexOf(items[candidate.index]);
+        if (retainedIndex >= 0)
+            retained.splice(retainedIndex, 1);
+        omitted += 1;
+    }
+    let result = boundedValue(value, itemKey, retained, omitted, command);
+    if (serializedProjectionBytes(result, format) <= policy.maxUtf8Bytes)
+        return result;
+    return minimalBudgetedProjection(command, omitted, policy, format);
+}

package/dist/state/retrievalAuthority.js

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { validateEntityListHelp } from "./entityRetrievalHelp.js";
+import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
+export const STATE_RETRIEVAL_AUTHORITY_PATH = "references/artifacts/state-storage-authority.yaml";
+export const STATE_RETRIEVAL_SCHEMA_VERSION = "agentera.entityPublicRetrieval.v1";
+const POLICY_SCHEMA_VERSION = "agentera.entityPublicRetrievalPolicy.v1";
+const FAILURE_CLASSES = [
+    "invalid_request",
+    "unsupported_artifact",
+    "not_found",
+    "ambiguous",
+    "corrupt",
+    "incomplete",
+    "cursor_invalid",
+    "cursor_snapshot_unavailable",
+    "unsupported_state",
+];
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? value
+        : [];
+}
+function requireNonEmpty(record, field, prefix, errors) {
+    if (typeof record[field] !== "string" || String(record[field]).trim() === "") {
+        errors.push(`${prefix}.${field}`);
+    }
+}
+export function deriveLegacyPlanIdentity(canonicalJson) {
+    return `legacy-plan:${createHash("sha256").update(canonicalJson, "utf8").digest("hex")}`;
+}
+/** Validate the canonical archive projection against its owning archive contract. */
+export function validateExperimentPublicationParity(value) {
+    const errors = [];
+    const retrieval = mapping(mapping(value.entity_target).public_retrieval);
+    const archivePolicy = mapping(mapping(mapping(retrieval.policy).archive_policy).experiments);
+    const archive = mapping(value.experiment_archival);
+    const layout = mapping(archive.layout);
+    const publication = mapping(archive.publication);
+    const projection = mapping(archive.projection);
+    const prefix = "entity_target.public_retrieval.policy.archive_policy.experiments";
+    if (archivePolicy.owner !== "experiment_archival" || archive.status !== "implemented") {
+        errors.push(`${prefix}.owner`);
+    }
+    if (archivePolicy.storage_scope !== "objective_directory" || archivePolicy.storage_scope !== layout.ownership) {
+        errors.push(`${prefix}.storage_scope`);
+    }
+    if (archivePolicy.publication_order !== "archive_before_projection" || publication.archive_before_projection !== true) {
+        errors.push(`${prefix}.publication_order`);
+    }
+    if (archivePolicy.projection_policy !== "uniform_10_40_50" || archivePolicy.projection_policy !== projection.policy) {
+        errors.push(`${prefix}.projection_policy`);
+    }
+    return errors;
+}
+/** Validate the sole active public retrieval projection and its unique policy. */
+export function validateStateRetrievalAuthority(value) {
+    const errors = validateEntityListHelp(value);
+    const retrieval = mapping(mapping(value.entity_target).public_retrieval);
+    const policy = mapping(retrieval.policy);
+    const prefix = "entity_target.public_retrieval";
+    if (retrieval.schema_version !== STATE_RETRIEVAL_SCHEMA_VERSION)
+        errors.push(`${prefix}.schema_version`);
+    if (retrieval.status !== "final")
+        errors.push(`${prefix}.status`);
+    if (policy.schema_version !== POLICY_SCHEMA_VERSION)
+        errors.push(`${prefix}.policy.schema_version`);
+    const identity = mapping(mapping(value.entity_target).identity);
+    if (identity.accepted_pattern !== "^[a-z]{10}$")
+        errors.push(`${prefix}.identity.accepted_pattern`);
+    const envelope = mapping(policy.envelope);
+    for (const field of ["schemaVersion", "command", "status", "entries", "counts", "filters", "snapshot", "source", "source_contract"]) {
+        if (!strings(envelope.required_fields).includes(field))
+            errors.push(`${prefix}.policy.envelope.required_fields.${field}`);
+    }
+    const projection = mapping(envelope.bounded_summary_projection);
+    if (projection.cardinality_owner !== "summary_rows_after_filters_and_cursor") {
+        errors.push(`${prefix}.policy.envelope.bounded_summary_projection.cardinality_owner`);
+    }
+    const degradation = mapping(projection.optional_detail_degradation);
+    for (const field of ["reason", "detail_omitted_count", "omitted_fields", "recovery"]) {
+        if (!strings(degradation.required_metadata).includes(field)) {
+            errors.push(`${prefix}.policy.envelope.bounded_summary_projection.optional_detail_degradation.required_metadata.${field}`);
+        }
+    }
+    if (degradation.row_omission !== "forbidden" || degradation.scalar_truncation !== "forbidden") {
+        errors.push(`${prefix}.policy.envelope.bounded_summary_projection.optional_detail_degradation.loss`);
+    }
+    const cursor = mapping(policy.cursor);
+    for (const field of ["vocabulary", "response_field", "binding", "invalid_behavior", "unavailable_behavior"]) {
+        if (!(field in cursor))
+            errors.push(`${prefix}.policy.cursor.${field}`);
+    }
+    const omission = mapping(policy.omission);
+    for (const field of ["omitted", "omitted_count", "omission_reason", "retrieval"]) {
+        if (!strings(omission.required_when_candidates_remain).includes(field)) {
+            errors.push(`${prefix}.policy.omission.required_when_candidates_remain.${field}`);
+        }
+    }
+    requireNonEmpty(omission, "semantics", `${prefix}.policy.omission`, errors);
+    const output = mapping(policy.output_bounds);
+    if (!Number.isSafeInteger(output.maximum_limit) || Number(output.maximum_limit) < 1 || Number(output.maximum_limit) > 100) {
+        errors.push(`${prefix}.policy.output_bounds.maximum_limit`);
+    }
+    if (!Number.isSafeInteger(output.max_serialized_utf8_bytes) || Number(output.max_serialized_utf8_bytes) < 1_024) {
+        errors.push(`${prefix}.policy.output_bounds.max_serialized_utf8_bytes`);
+    }
+    if (output.scalar_truncation !== "forbidden")
+        errors.push(`${prefix}.policy.output_bounds.scalar_truncation`);
+    if (output.row_omission_under_byte_pressure !== "forbidden")
+        errors.push(`${prefix}.policy.output_bounds.row_omission_under_byte_pressure`);
+    const failures = mapping(policy.failures);
+    for (const field of ["class", "message", "syntax", "example", "recovery"]) {
+        if (!strings(failures.required_fields).includes(field))
+            errors.push(`${prefix}.policy.failures.required_fields.${field}`);
+    }
+    const classes = mapping(failures.classes);
+    for (const name of FAILURE_CLASSES)
+        requireNonEmpty(classes, name, `${prefix}.policy.failures.classes`, errors);
+    const planArchive = mapping(mapping(policy.archive_policy).plan);
+    for (const field of ["owner", "diagnostics", "unselected_diagnostics"]) {
+        requireNonEmpty(planArchive, field, `${prefix}.policy.archive_policy.plan`, errors);
+    }
+    errors.push(...validateExperimentPublicationParity(value));
+    return [...new Set(errors)];
+}
+export function loadStateRetrievalAuthority(sourceRoot = resolveSourceRoot()) {
+    const authority = loadStateStorageAuthority(sourceRoot);
+    const errors = validateStateRetrievalAuthority(authority.document);
+    if (errors.length > 0)
+        throw new Error(`invalid state retrieval authority: ${errors.join(", ")}`);
+    return {
+        authority: STATE_RETRIEVAL_AUTHORITY_PATH,
+        retrieval: mapping(mapping(authority.document.entity_target).public_retrieval),
+    };
+}
+export function stateRetrievalCommands(sourceRoot = resolveSourceRoot()) {
+    return mapping(loadStateRetrievalAuthority(sourceRoot).retrieval.commands);
+}
+export function entityPublicRetrieval(sourceRoot = resolveSourceRoot()) {
+    return loadStateRetrievalAuthority(sourceRoot).retrieval;
+}
+export function startupSurfaceBudget(surface, sourceRoot = resolveSourceRoot()) {
+    const authority = loadStateStorageAuthority(sourceRoot);
+    const surfaces = mapping(mapping(mapping(authority.document.budgets).startup).surfaces);
+    const budget = Number(mapping(surfaces[surface]).max_utf8_bytes);
+    if (!Number.isSafeInteger(budget) || budget < 1) {
+        throw new Error(`state storage authority '${authority.authorityPath}' has no positive startup budget for '${surface}'`);
+    }
+    return budget;
+}