agentera 3.0.0-dev.4 → 3.0.0-dev.41

package/dist/cli/commands/prime/briefOrientation.js

@@ -0,0 +1,808 @@
+import { truncateCodePoints } from "../../../core/text.js";
+import { entityListFamily } from "../../../state/entityRetrievalHelp.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "../../capabilityContext/types.js";
+/**
+ * Bounded default decision brief for the bare `agentera prime --format json`
+ * emission (Plan Task 3).
+ *
+ * The bare default projects the full orientation payload
+ * ({@link buildOrientationJsonPayload}) to a bounded decision brief: every
+ * required top-level field stays PRESENT (the compatibility boundary asserts
+ * the key set), but rich diagnostic/writer detail within those fields is
+ * projected to routing-essential leaves plus a named authoritative recovery
+ * command for each omitted sub-detail. Dashboard startup independently omits
+ * duplicated ordinary history entries; explicit fields and capability contexts
+ * retain their separately governed projections.
+ *
+ * The byte gate is deterministic pretty-JSON UTF-8 measurement
+ * (Buffer.byteLength(JSON.stringify(brief, null, 2) + "\n", "utf8")); an
+ * over-budget brief is rejected in favor of a bounded degraded envelope.
+ * Diagnostics (the `issues` deprecation warning) stay on stderr and are
+ * measured separately. See references/cli/prime-consumer-compatibility.yaml
+ * brief_omission_contract and references/artifacts/state-storage-authority.yaml
+ * budgets.startup.surfaces.prime_briefing.
+ */
+/** Authoritative byte budget for the default bare prime decision brief.
+ *  Mirrors references/artifacts/state-storage-authority.yaml
+ *  budgets.startup.surfaces.prime_briefing.max_utf8_bytes and
+ *  scripts/json_output_surface_manifest.yaml prime-briefing byte_budget.
+ *  archiveAuthority.test.ts binds the authority to the manifest; the
+ *  primeProjectionContract.test.ts suite binds this constant to the authority
+ *  so the contract and implementation cannot drift apart. */
+export const PRIME_BRIEF_MAX_UTF8_BYTES = 12000;
+/** Deterministic pretty-JSON UTF-8 byte length (including the trailing newline)
+ *  used by the brief byte gate. Identical to the projection-policy serializer
+ *  (serializedProjectionBytes) so measurement is consistent across surfaces. */
+export function briefUtf8Bytes(value) {
+    const serialized = JSON.stringify(value, null, 2);
+    if (serialized === undefined)
+        throw new TypeError("brief value is not JSON serializable");
+    return Buffer.byteLength(serialized + "\n", "utf8");
+}
+/** Byte-gate primitive: deterministic UTF-8 measurement + budget comparison.
+ *  AC5: a passing fixture (bytes <= budget) is accepted; an over-budget fixture
+ *  (bytes > budget) is rejected. */
+export function briefByteGate(value, budget = PRIME_BRIEF_MAX_UTF8_BYTES) {
+    const bytes = briefUtf8Bytes(value);
+    return { accepted: bytes <= budget, bytes };
+}
+/** Rich-state sub-detail projected out of the default brief, each with a named
+ *  authoritative recovery command (AC4). Mirrors brief_omission_contract in
+ *  references/cli/prime-consumer-compatibility.yaml. */
+const planTaskFamily = entityListFamily("plan_tasks");
+const planTaskListRecovery = `agentera state ${planTaskFamily.commandTokens.join(" ")} list --format json`;
+const OMITTED_RICH_STATE = [
+    { field: "startup.path_diagnostics", reason: "startup_path_diagnostics", recovery: "agentera doctor --format json" },
+    { field: "plan.tasks", reason: "plan_task_detail", recovery: planTaskListRecovery },
+    { field: "plan.archived_plans", reason: "archive_catalog", recovery: STATE_FAMILY_FALLBACK_COMMANDS.plan },
+    { field: "plan.diagnostics", reason: "plan_diagnostics", recovery: STATE_FAMILY_FALLBACK_COMMANDS.plan },
+    { field: "history.progress.entries", reason: "startup_history_entries", recovery: STATE_FAMILY_FALLBACK_COMMANDS.progress },
+    { field: "history.decisions.entries", reason: "startup_history_entries", recovery: STATE_FAMILY_FALLBACK_COMMANDS.decisions },
+    { field: "history.health.entries", reason: "startup_history_entries", recovery: STATE_FAMILY_FALLBACK_COMMANDS.health },
+    { field: "project_integration.phases", reason: "phase_blockers", recovery: "agentera doctor --format json" },
+    { field: "source_contract.artifact_writes.artifacts", reason: "writer_contract_detail", recovery: "agentera schema --format json" },
+    { field: "docs.source_contract", reason: "docs_state_families", recovery: STATE_FAMILY_FALLBACK_COMMANDS.docs },
+    { field: "profile.bounded_signals", reason: "profile_signal_detail", recovery: "agentera profile --format json" },
+];
+/** Maximum number of ranked next_action alternatives retained in the brief.
+ *  The recommended entry is always kept; overflow alternatives recover via the
+ *  state-derived readiness cascade rather than raw artifact access. */
+const BRIEF_NEXT_ACTION_ALTERNATIVES = 3;
+const PATH_DIAGNOSTICS_RECOVERY = "agentera doctor --format json";
+/** Code-point cap for routing-essential free-text scalars retained in the brief
+ *  (e.g. progress.latest.what/next). Matches the boundStartupValue 200-cp
+ *  limit already applied to context payloads so the brief never lets a single
+ *  pathological scalar blow the budget; the full value recovers via the named
+ *  state command. */
+const BRIEF_SCALAR_MAX_CHARS = 200;
+function projectionMaxChars(projection) {
+    return projection === "normal" ? BRIEF_SCALAR_MAX_CHARS : projection === "compact" ? 120 : 80;
+}
+function projectionMaxItems(projection) {
+    return projection === "normal" ? 10 : projection === "compact" ? 6 : 3;
+}
+/** Keys owned by the state-presence contract. Unknown keys are caller data, not
+ * routing signals, so the brief never copies them into a fallback envelope. */
+const STATE_PRESENCE_ACTIVE_KEYS = ["plan", "objective"];
+const STATE_PRESENCE_AVAILABLE_KEYS = ["plan", "docs", "progress", "health", "objective"];
+const STATE_PRESENCE_ABSENCE_KEYS = ["plan", "docs", "progress"];
+const BRIEF_SOURCE_FIELDS_MAX = 64;
+const BRIEF_SOURCE_STRING_MAX_CHARS = 256;
+const BRIEF_COMPACT_SOURCE_FIELDS_MAX = 32;
+const BRIEF_COMPACT_SOURCE_STRING_MAX_CHARS = 96;
+const BRIEF_IRREDUCIBLE_SOURCE_FIELDS_MAX = 32;
+const BRIEF_IRREDUCIBLE_SOURCE_STRING_MAX_CHARS = 64;
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Copy only the listed keys that exist on `source`. Keeps the brief stable when
+ *  a conditional field is absent (e.g. plan.first_pending on an empty plan). */
+function pick(source, keys) {
+    if (!isObject(source))
+        return {};
+    const out = {};
+    for (const key of keys) {
+        if (key in source)
+            out[key] = source[key];
+    }
+    return out;
+}
+function boundedString(value, maxChars) {
+    return typeof value === "string" ? truncateCodePoints(value, maxChars, "…") : undefined;
+}
+function boundedStringList(value, maxItems, maxChars) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .filter((entry) => typeof entry === "string")
+        .slice(0, maxItems)
+        .map((entry) => truncateCodePoints(entry, maxChars, "…"));
+}
+function boundedBooleanMap(value, keys) {
+    if (!isObject(value))
+        return undefined;
+    const out = {};
+    for (const key of keys) {
+        if (typeof value[key] === "boolean")
+            out[key] = value[key];
+    }
+    return out;
+}
+function boundedStringMap(value, keys, maxChars) {
+    if (!isObject(value))
+        return undefined;
+    const out = {};
+    for (const key of keys) {
+        const bounded = boundedString(value[key], maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    return out;
+}
+/** Project the presence authority to its finite, contract-owned shape. This is
+ * deliberately not a generic object trim: unknown caller keys cannot change
+ * routing, and therefore must not be allowed to consume the fallback budget. */
+function briefStatePresence(value, maxChars = BRIEF_SCALAR_MAX_CHARS) {
+    if (value === null || value === undefined)
+        return value === null ? null : {};
+    if (!isObject(value))
+        return {};
+    const out = {};
+    const active = boundedBooleanMap(value.active, STATE_PRESENCE_ACTIVE_KEYS);
+    const available = boundedBooleanMap(value.available, STATE_PRESENCE_AVAILABLE_KEYS);
+    const absence = boundedStringMap(value.absence, STATE_PRESENCE_ABSENCE_KEYS, maxChars);
+    if (active !== undefined)
+        out.active = active;
+    if (available !== undefined)
+        out.available = available;
+    if (typeof value.any_active === "boolean")
+        out.any_active = value.any_active;
+    if (typeof value.absence_explained === "boolean")
+        out.absence_explained = value.absence_explained;
+    if (absence !== undefined)
+        out.absence = absence;
+    return out;
+}
+function briefSelectedPlanTask(task, projection) {
+    if (task === null)
+        return null;
+    if (!isObject(task))
+        return {};
+    const maxChars = projectionMaxChars(projection);
+    const maxItems = projectionMaxItems(projection);
+    const out = pick(task, [
+        "id",
+        "artifact",
+        "status",
+        "dependency_count",
+        "omitted_dependency_count",
+        "acceptance_count",
+        "omitted_acceptance_count",
+    ]);
+    const name = boundedString(task.name ?? task.title, maxChars);
+    if (name !== undefined)
+        out.name = name;
+    const dependencies = boundedStringList(task.depends_on, maxItems, maxChars);
+    if (dependencies !== undefined)
+        out.depends_on = dependencies;
+    const acceptance = boundedStringList(task.acceptance, maxItems, maxChars);
+    if (acceptance !== undefined)
+        out.acceptance = acceptance;
+    if (isObject(task.retrieval)) {
+        out.retrieval = pick(task.retrieval, ["get"]);
+    }
+    return out;
+}
+function briefPlan(plan, projection = "normal") {
+    // Keep canonical plan/task identity and the routing-essential summary consumers
+    // read plus the selected task's dependencies, acceptance, and exact retrieval.
+    // Drop the optional task catalog, archive catalog, diagnostics, and
+    // lifecycle_state — each recovers via OMITTED_RICH_STATE.
+    const out = pick(plan, [
+        "exists",
+        "id",
+        "artifact",
+        "active",
+        "status",
+        "complete",
+        "total",
+        "complete_plan",
+        "task_count",
+        "omitted_task_count",
+    ]);
+    if (isObject(plan)) {
+        const title = boundedString(plan.title, projectionMaxChars(projection));
+        if (title !== undefined)
+            out.title = title;
+        if (isObject(plan.source_contract)) {
+            out.source_contract = pick(plan.source_contract, ["detail_availability", "retrieval", "raw_archive_records"]);
+        }
+    }
+    if (isObject(plan) && "first_pending" in plan) {
+        out.first_pending = briefSelectedPlanTask(plan.first_pending, projection);
+    }
+    return out;
+}
+function briefHistoryRetrieval(value) {
+    return pick(value, ["list", "get"]);
+}
+function briefHistoryCaveats(value, maxChars) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.slice(0, 4).map((caveat) => {
+        if (typeof caveat === "string")
+            return truncateCodePoints(caveat, maxChars, "…");
+        if (!isObject(caveat))
+            return {};
+        const out = {};
+        for (const key of [
+            "class",
+            "kind",
+            "state",
+            "confidence",
+            "satisfaction_state",
+            "message",
+            "reason",
+            "detail_availability",
+            "compatibility",
+            "recovery",
+        ]) {
+            const bounded = boundedString(caveat[key], maxChars);
+            if (bounded !== undefined)
+                out[key] = bounded;
+        }
+        if (typeof caveat.review_needed === "boolean")
+            out.review_needed = caveat.review_needed;
+        return out;
+    });
+}
+function briefHistory(history, projection = "normal") {
+    if (!isObject(history))
+        return {};
+    const out = {};
+    const maxChars = projectionMaxChars(projection);
+    for (const [artifactId, entry] of Object.entries(history)) {
+        // Entity startup history owns canonical full/summary counts. Entry detail
+        // remains omitted and recovers through exact list/get commands.
+        const entryObj = isObject(entry) ? entry : {};
+        const counts = isObject(entryObj.counts) ? entryObj.counts : {};
+        const projected = {
+            ...pick(entryObj, [
+                "artifact",
+                "status",
+                "compatibility",
+                "detail_availability",
+                "omitted",
+                "omitted_count",
+                "omission_reason",
+            ]),
+            counts: pick(counts, ["total", "returned", "remaining", "full", "summary"]),
+            retrieval: briefHistoryRetrieval(entryObj.retrieval),
+        };
+        const caveats = briefHistoryCaveats(entryObj.caveats, maxChars);
+        if (caveats !== undefined)
+            projected.caveats = caveats;
+        if (isObject(entryObj.degraded_history)) {
+            const degraded = pick(entryObj.degraded_history, ["summary_count", "returned_count", "omitted_count"]);
+            degraded.retrieval = briefHistoryRetrieval(entryObj.degraded_history.retrieval);
+            const degradedCaveats = briefHistoryCaveats(entryObj.degraded_history.caveats, maxChars);
+            if (degradedCaveats !== undefined)
+                degraded.caveats = degradedCaveats;
+            projected.degraded_history = degraded;
+        }
+        if (isObject(entryObj.source_contract)) {
+            projected.source_contract = pick(entryObj.source_contract, ["authority", "detail", "cursor"]);
+        }
+        out[artifactId] = projected;
+    }
+    return out;
+}
+function briefProjectIntegration(integration) {
+    // Keep the routing recommendation, message, pending counts, channel,
+    // aggregate status, and any major-boundary block (which overrides
+    // next_action). Upgrade commands are part of the executable upgrade route;
+    // preserve them only for that recommendation. Phase blockers and guidance
+    // detail recover via doctor.
+    const fields = [
+        "recommendation",
+        "message",
+        "update_channel",
+        "pending_artifacts",
+        "aggregate_status",
+        "major_boundary_block",
+    ];
+    if (isObject(integration) && integration.recommendation === "upgrade") {
+        fields.push("dry_run_command", "apply_command");
+    }
+    return pick(integration, fields);
+}
+function briefProfile(profile) {
+    // opencode reads profile.status; the dashboard glyph reads profile.status.
+    // bounded_signals (a legacy recovery blob) is omitted and recovers via
+    // `agentera profile --format json`.
+    return pick(profile, [
+        "status",
+        "validity",
+        "freshness",
+        "days_since_generated",
+        "stale",
+        "stale_threshold_days",
+        "generated_date",
+        "validated_date",
+        "suggested_action",
+    ]);
+}
+function briefApp(app) {
+    // `app` is required for app/v1/profile safety, but no default-bare consumer
+    // reads its verbose path list (the packaging gate reads app_home.source).
+    // Keep safety identity; path diagnostics recover through doctor so checkout
+    // depth cannot displace routing or canonical history evidence.
+    return pick(app, [
+        "status",
+        "expectedVersion",
+        "updateChannel",
+    ]);
+}
+function briefAppHome(appHome) {
+    return pick(appHome, ["install_track", "status", "source"]);
+}
+function briefSharedSkill(sharedSkill) {
+    if (!isObject(sharedSkill))
+        return {};
+    const out = pick(sharedSkill, ["name", "status", "source", "gap"]);
+    const message = boundedString(sharedSkill.message, BRIEF_SCALAR_MAX_CHARS);
+    if (message !== undefined)
+        out.message = message;
+    const details = boundedStringList(sharedSkill.details, 3, BRIEF_SCALAR_MAX_CHARS);
+    if (details !== undefined)
+        out.details = details;
+    return out;
+}
+function briefSource(source) {
+    return pick(source, ["artifacts_present"]);
+}
+function briefAttention(attention) {
+    // opencode reads the attention array for routing hints, but each entry is an
+    // advisory string. Cap each at BRIEF_SCALAR_MAX_CHARS so a pathological
+    // lifecycle procedure text cannot blow the budget; the full detail recovers
+    // via the named recovery commands in omitted_rich_state.
+    if (!Array.isArray(attention))
+        return attention ?? [];
+    return attention.map((entry) => typeof entry === "string" ? truncateCodePoints(entry, BRIEF_SCALAR_MAX_CHARS, "…") : entry);
+}
+function briefDecisionAttention(attention) {
+    if (attention === null)
+        return null;
+    if (!isObject(attention))
+        return {};
+    const out = pick(attention, ["type", "count", "states", "max_entries", "bounded"]);
+    const summary = boundedString(attention.attention, BRIEF_SCALAR_MAX_CHARS);
+    if (summary !== undefined)
+        out.attention = summary;
+    out.entries = Array.isArray(attention.entries)
+        ? attention.entries.slice(0, 3).map((entry) => {
+            if (!isObject(entry))
+                return {};
+            const projected = pick(entry, ["id", "artifact", "state"]);
+            const title = boundedString(entry.title, BRIEF_SCALAR_MAX_CHARS);
+            if (title !== undefined)
+                projected.title = title;
+            return projected;
+        })
+        : [];
+    return out;
+}
+function briefDocs(docs) {
+    // No default-bare consumer reads the docs projection detail. Keep the
+    // availability signal and mapping count; the verbose source_contract with
+    // state_families recovers via the canonical docs list fallback.
+    return pick(docs, ["exists", "status", "mapping_entries", "indexed_documents"]);
+}
+function briefProgress(progress) {
+    // opencode reads progress.latest.number/what/next; the brief keeps the
+    // latest cycle but caps free-text scalars at BRIEF_SCALAR_MAX_CHARS so a
+    // pathological value cannot blow the budget. Full detail recovers via
+    // `agentera state progress get --id ID --format json`.
+    if (!isObject(progress))
+        return {};
+    const out = pick(progress, ["exists", "status", "latest_verification", "cycle_count", "degraded_history"]);
+    const latest = progress.latest;
+    if (isObject(latest)) {
+        const boundedLatest = {};
+        for (const [key, value] of Object.entries(latest)) {
+            boundedLatest[key] = typeof value === "string" ? truncateCodePoints(value, BRIEF_SCALAR_MAX_CHARS, "…") : value;
+        }
+        out.latest = boundedLatest;
+    }
+    else {
+        out.latest = latest;
+    }
+    return out;
+}
+function briefHealth(health) {
+    return pick(health, ["exists", "id", "artifact", "date", "trajectory", "grade", "degraded_history"]);
+}
+function briefAction(action, maxChars) {
+    if (!isObject(action))
+        return {};
+    const out = pick(action, ["id", "artifact", "outcome", "eligible"]);
+    for (const key of ["object", "capability", "reason", "phase"]) {
+        const bounded = boundedString(action[key], maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    if (isObject(action.retrieval))
+        out.retrieval = pick(action.retrieval, ["exact", "get"]);
+    return out;
+}
+function briefNextAction(nextAction, projection = "normal") {
+    if (!isObject(nextAction))
+        return {};
+    const maxChars = projectionMaxChars(projection);
+    const alternativeLimit = projection === "normal"
+        ? BRIEF_NEXT_ACTION_ALTERNATIVES
+        : projection === "compact"
+            ? 1
+            : 0;
+    const alternatives = Array.isArray(nextAction.alternatives)
+        ? nextAction.alternatives.slice(0, alternativeLimit).map((entry) => briefAction(entry, maxChars))
+        : [];
+    return {
+        ...briefAction(nextAction, maxChars),
+        alternatives,
+    };
+}
+function briefCapabilityContext(value, maxChars) {
+    if (!isObject(value))
+        return {};
+    const out = {};
+    for (const key of ["capability", "fetch_command", "note"]) {
+        const bounded = boundedString(value[key], maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    if (typeof value.required_before_rendering === "boolean") {
+        out.required_before_rendering = value.required_before_rendering;
+    }
+    return out;
+}
+function briefCapabilityStartup(startup, maxChars) {
+    if (!isObject(startup))
+        return {};
+    const out = {};
+    if (typeof startup.complete_for_capability_startup === "boolean") {
+        out.complete_for_capability_startup = startup.complete_for_capability_startup;
+    }
+    if (typeof startup.raw_artifact_reads_required === "boolean") {
+        out.raw_artifact_reads_required = startup.raw_artifact_reads_required;
+    }
+    const policy = boundedString(startup.raw_artifact_read_policy, maxChars);
+    if (policy !== undefined)
+        out.raw_artifact_read_policy = policy;
+    for (const [key, maxItems] of [
+        ["available_state", 64],
+        ["missing_state", 16],
+        ["confidence_caveats", 8],
+        ["cli_fallback", 8],
+    ]) {
+        const bounded = boundedStringList(startup[key], maxItems, maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    return out;
+}
+function briefArtifactWrites(writes, maxChars) {
+    // Keep the discovery pointer (required by the compatibility boundary test)
+    // and schema identity; the full writer-operation matrix recovers via schema.
+    if (!isObject(writes))
+        return {};
+    const out = {};
+    for (const key of ["schemaVersion", "discovery_command"]) {
+        const bounded = boundedString(writes[key], maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    return out;
+}
+function briefSourceContract(sourceContract, projection = "normal") {
+    if (!isObject(sourceContract))
+        return {};
+    const maxItems = projection === "normal"
+        ? BRIEF_SOURCE_FIELDS_MAX
+        : projection === "compact"
+            ? BRIEF_COMPACT_SOURCE_FIELDS_MAX
+            : BRIEF_IRREDUCIBLE_SOURCE_FIELDS_MAX;
+    const maxChars = projection === "normal"
+        ? BRIEF_SOURCE_STRING_MAX_CHARS
+        : projection === "compact"
+            ? BRIEF_COMPACT_SOURCE_STRING_MAX_CHARS
+            : BRIEF_IRREDUCIBLE_SOURCE_STRING_MAX_CHARS;
+    const out = {};
+    const fields = boundedStringList(sourceContract.fields, maxItems, maxChars);
+    if (fields !== undefined)
+        out.fields = fields;
+    for (const key of ["render", "access", "empty_state"]) {
+        const bounded = boundedString(sourceContract[key], maxChars);
+        if (bounded !== undefined)
+            out[key] = bounded;
+    }
+    if (projection !== "irreducible" && isObject(sourceContract.capability_context)) {
+        out.capability_context = briefCapabilityContext(sourceContract.capability_context, maxChars);
+    }
+    else if (projection === "irreducible" && isObject(sourceContract.capability_context)) {
+        const capabilityContext = briefCapabilityContext(sourceContract.capability_context, maxChars);
+        if ("fetch_command" in capabilityContext) {
+            out.capability_context = { fetch_command: capabilityContext.fetch_command };
+        }
+    }
+    if (isObject(sourceContract.capability_startup)) {
+        if (projection === "irreducible") {
+            const startup = sourceContract.capability_startup;
+            const minimalStartup = {};
+            if (typeof startup.complete_for_capability_startup === "boolean") {
+                minimalStartup.complete_for_capability_startup = startup.complete_for_capability_startup;
+            }
+            if (typeof startup.raw_artifact_reads_required === "boolean") {
+                minimalStartup.raw_artifact_reads_required = startup.raw_artifact_reads_required;
+            }
+            out.capability_startup = minimalStartup;
+        }
+        else {
+            out.capability_startup = briefCapabilityStartup(sourceContract.capability_startup, maxChars);
+        }
+    }
+    if (isObject(sourceContract.artifact_writes)) {
+        if (projection !== "irreducible") {
+            out.artifact_writes = briefArtifactWrites(sourceContract.artifact_writes, maxChars);
+        }
+    }
+    return out;
+}
+/** Project the full orientation payload to a bounded decision brief. The brief
+ *  keeps every required top-level field present (content projected to
+ *  routing-essential leaves) plus a `brief` meta block that records the budget,
+ *  measured bytes, status, and omitted rich-state recovery commands.
+ *
+ *  Measurement uses deterministic pretty-JSON UTF-8 byte length including the
+ *  trailing newline. The reported `utf8_bytes` is settled to a fixed point so
+ *  it equals the actual emitted byte count (self-measurement otherwise changes
+ *  its own digit count); the gate then decides on the final form. */
+export function briefOrientationPayload(payload, options = {}) {
+    const budget = options.budgetBytes ?? PRIME_BRIEF_MAX_UTF8_BYTES;
+    if (!Number.isSafeInteger(budget) || budget < 0) {
+        throw new RangeError("brief budget must be a non-negative safe integer");
+    }
+    const projected = projectBriefBody(payload);
+    const finalPayload = withBriefMeta(projected, "ok", budget, null);
+    const gate = briefByteGate(finalPayload, budget);
+    if (gate.accepted) {
+        return finalPayload;
+    }
+    // Over-budget brief: reject the projected payload and emit a bounded degraded
+    // envelope (never emit an over-budget payload). The envelope keeps bounded
+    // plan/next-action/history/decision routing evidence, state presence, a brief
+    // source contract, and the byte-budget error with a recovery command.
+    return degradedBriefEnvelope(payload, budget, gate.bytes, options.degradedMode ?? "minimal");
+}
+/** Attach the brief meta block and settle `utf8_bytes` to a fixed point so the
+ *  reported size equals the actual emitted byte count (otherwise the digits of
+ *  `utf8_bytes` itself would change the measurement). */
+function withBriefMeta(body, status, budget, error) {
+    const meta = {
+        budget_utf8_bytes: budget,
+        status,
+        path_diagnostics_recovery: PATH_DIAGNOSTICS_RECOVERY,
+        omitted_rich_state: OMITTED_RICH_STATE.map((entry) => ({ ...entry })),
+    };
+    if (error)
+        meta.error = error;
+    return settledBriefEnvelope(body, meta);
+}
+function projectBriefBody(payload) {
+    const out = {};
+    for (const [key, value] of Object.entries(payload)) {
+        switch (key) {
+            case "plan":
+                out[key] = briefPlan(value);
+                break;
+            case "history":
+                out[key] = briefHistory(value);
+                break;
+            case "project_integration":
+                out[key] = briefProjectIntegration(value);
+                break;
+            case "profile":
+                out[key] = briefProfile(value);
+                break;
+            case "app":
+                out[key] = briefApp(value);
+                break;
+            case "app_home":
+                out[key] = briefAppHome(value);
+                break;
+            case "shared_skill":
+                out[key] = briefSharedSkill(value);
+                break;
+            case "progress":
+                out[key] = briefProgress(value);
+                break;
+            case "health":
+                out[key] = briefHealth(value);
+                break;
+            case "next_action":
+                out[key] = briefNextAction(value);
+                break;
+            case "attention":
+                out[key] = briefAttention(value);
+                break;
+            case "decision_attention":
+                out[key] = briefDecisionAttention(value);
+                break;
+            case "docs":
+                out[key] = briefDocs(value);
+                break;
+            case "source_contract":
+                out[key] = briefSourceContract(value);
+                break;
+            case "state_presence":
+                out[key] = briefStatePresence(value);
+                break;
+            case "source":
+                out[key] = briefSource(value);
+                break;
+            default:
+                // Command/status/mode, bounded ordinary state, shared-skill diagnosis,
+                // bespoke context pointers, and active conditional fields pass through
+                // at full fidelity.
+                out[key] = value;
+                break;
+        }
+    }
+    return out;
+}
+function boundedEnvelopeScalar(value, fallback) {
+    return boundedString(value, BRIEF_SCALAR_MAX_CHARS) ?? fallback;
+}
+function degradedBody(payload, projection) {
+    const out = {
+        command: boundedEnvelopeScalar(payload.command, "prime"),
+        status: boundedEnvelopeScalar(payload.status, "ok"),
+        mode: boundedEnvelopeScalar(payload.mode, "unknown"),
+        state_presence: briefStatePresence(payload.state_presence),
+        source_contract: briefSourceContract(payload.source_contract, projection),
+    };
+    if ("app_home" in payload)
+        out.app_home = briefAppHome(payload.app_home);
+    if ("app" in payload)
+        out.app = briefApp(payload.app);
+    if ("profile" in payload)
+        out.profile = briefProfile(payload.profile);
+    if ("shared_skill" in payload)
+        out.shared_skill = briefSharedSkill(payload.shared_skill);
+    if ("project_integration" in payload)
+        out.project_integration = briefProjectIntegration(payload.project_integration);
+    if ("health" in payload)
+        out.health = briefHealth(payload.health);
+    if ("todo" in payload)
+        out.todo = payload.todo;
+    if ("issues" in payload)
+        out.issues = payload.issues;
+    if ("progress" in payload)
+        out.progress = briefProgress(payload.progress);
+    if ("attention" in payload)
+        out.attention = briefAttention(payload.attention);
+    if ("source" in payload)
+        out.source = briefSource(payload.source);
+    for (const conditional of ["v1_migration", "docs", "objective"]) {
+        if (conditional in payload)
+            out[conditional] = payload[conditional];
+    }
+    if (isObject(payload.plan))
+        out.plan = briefPlan(payload.plan, projection);
+    if (isObject(payload.next_action))
+        out.next_action = briefNextAction(payload.next_action, projection);
+    if (isObject(payload.history))
+        out.history = briefHistory(payload.history, projection);
+    if (payload.decision_attention === null)
+        out.decision_attention = null;
+    else if (isObject(payload.decision_attention))
+        out.decision_attention = briefDecisionAttention(payload.decision_attention);
+    return out;
+}
+function statusRoutingDegradedBody(payload, projection) {
+    return {
+        ...degradedBody(payload, projection),
+        todo: payload.todo,
+        attention: briefAttention(payload.attention),
+    };
+}
+/** Settle the self-measuring byte field and return only at a fixed point. The
+ * serialized value and the reported value therefore use the same pretty UTF-8
+ * plus newline accounting as emitStructured. */
+function settledBriefEnvelope(body, meta) {
+    let brief = { ...meta, utf8_bytes: 0 };
+    let envelope = { ...body, brief };
+    for (let guard = 0; guard < 32; guard += 1) {
+        const bytes = briefUtf8Bytes(envelope);
+        if (brief.utf8_bytes === bytes)
+            return envelope;
+        brief = { ...brief, utf8_bytes: bytes };
+        envelope = { ...body, brief };
+    }
+    throw new Error("brief UTF-8 byte measurement did not settle");
+}
+export class BriefBudgetError extends Error {
+    budgetBytes;
+    minimumBytes;
+    constructor(budgetBytes, minimumBytes) {
+        super(`brief budget ${budgetBytes} bytes cannot contain the minimum routing envelope (${minimumBytes} bytes); increase the budget or use --dashboard`);
+        this.name = "BriefBudgetError";
+        this.budgetBytes = budgetBytes;
+        this.minimumBytes = minimumBytes;
+    }
+}
+function degradedBriefEnvelope(payload, budget, attemptedBytes, mode) {
+    const detailedMeta = {
+        budget_utf8_bytes: budget,
+        status: "degraded",
+        attempted_utf8_bytes: attemptedBytes,
+        path_diagnostics_recovery: PATH_DIAGNOSTICS_RECOVERY,
+        omitted_rich_state: OMITTED_RICH_STATE.map((entry) => ({ ...entry })),
+        error: {
+            class: "brief_output_budget",
+            message: "the projected decision brief exceeded the authority byte budget; a bounded degraded envelope was emitted instead of the over-budget payload",
+            recovery: "Run `agentera prime --dashboard --format json` for the full orientation payload, or `agentera state <artifact> list --format json` for a specific record family.",
+        },
+    };
+    const body = (projection) => mode === "status_routing"
+        ? statusRoutingDegradedBody(payload, projection)
+        : degradedBody(payload, projection);
+    const detailed = settledBriefEnvelope(body("normal"), detailedMeta);
+    if (briefByteGate(detailed, budget).accepted)
+        return detailed;
+    // A smaller deterministic fallback drops the recovery catalog but retains the
+    // bounded state-presence and source-contract projections plus one recovery
+    // command. This is what lets a configured 7KB gate remain enforceable even
+    // when caller data would make the detailed degraded envelope too large.
+    const compactMeta = {
+        budget_utf8_bytes: budget,
+        status: "degraded",
+        attempted_utf8_bytes: attemptedBytes,
+        path_diagnostics_recovery: PATH_DIAGNOSTICS_RECOVERY,
+        error: {
+            class: "brief_output_budget",
+            message: "the projected decision brief exceeded the authority byte budget; compact recovery metadata was emitted",
+            recovery: "Run `agentera prime --dashboard --format json` for full orientation detail.",
+        },
+    };
+    const compact = settledBriefEnvelope(body("compact"), compactMeta);
+    if (briefByteGate(compact, budget).accepted)
+        return compact;
+    if (mode === "status_routing") {
+        const minimum = settledBriefEnvelope(body("irreducible"), compactMeta);
+        const minimumBytes = briefUtf8Bytes(minimum);
+        if (minimumBytes <= budget)
+            return minimum;
+        throw new BriefBudgetError(budget, minimumBytes);
+    }
+    // The irreducible form is intentionally finite and contains only the routing
+    // contract. If even this cannot fit, throwing is explicit: returning an
+    // over-budget JSON document would violate the public output contract.
+    const minimumMeta = {
+        budget_utf8_bytes: budget,
+        status: "degraded",
+        attempted_utf8_bytes: attemptedBytes,
+        path_diagnostics_recovery: PATH_DIAGNOSTICS_RECOVERY,
+        error: {
+            class: "brief_output_budget",
+            message: "the configured budget cannot contain the detailed recovery envelope",
+            recovery: "Increase the budget or run `agentera prime --dashboard --format json`.",
+        },
+    };
+    const minimum = settledBriefEnvelope(body("irreducible"), minimumMeta);
+    const minimumBytes = briefUtf8Bytes(minimum);
+    if (minimumBytes <= budget)
+        return minimum;
+    throw new BriefBudgetError(budget, minimumBytes);
+}
+//# sourceMappingURL=briefOrientation.js.map