@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/environment/contract.js

@@ -0,0 +1,761 @@
+import { dirname, isAbsolute, normalize } from 'node:path';
+import { isProxy } from 'node:util/types';
+import { isEntrypointKind } from '../entrypoint-kinds.js';
+import { exactKeys } from '../exact-keys.js';
+const JSON_LIMITS = { bytes: 1_048_576, nodes: 65_536, entries: 4_096, scalarBytes: 65_536, depth: 64 };
+function reserveBytes(state, bytes) {
+    if (state.bytes + bytes > state.byteLimit)
+        return false;
+    state.bytes += bytes;
+    return true;
+}
+function snapshotJsonValue(value, state, depth) {
+    if (state.nodes >= JSON_LIMITS.nodes || depth > JSON_LIMITS.depth)
+        return undefined;
+    state.nodes += 1;
+    if (value === null || typeof value === 'boolean' || typeof value === 'number') {
+        if (typeof value === 'number' && !Number.isFinite(value))
+            return undefined;
+        const encoded = JSON.stringify(value);
+        return reserveBytes(state, Buffer.byteLength(encoded)) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const bytes = Buffer.byteLength(value);
+        return bytes <= state.scalarLimit && reserveBytes(state, Buffer.byteLength(JSON.stringify(value))) ? value : undefined;
+    }
+    if (typeof value !== 'object' || isProxy(value) || state.ancestors.has(value))
+        return undefined;
+    if (!reserveBytes(state, 2))
+        return undefined;
+    const ancestors = state.ancestors;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const descriptors = Object.getOwnPropertyDescriptors(value);
+            const keys = Reflect.ownKeys(value);
+            const length = descriptors.length.value;
+            if (typeof length !== 'number' || length > state.entryLimit || keys.length !== length + 1
+                || keys.some((key) => typeof key !== 'string' || key !== 'length' && !/^(?:0|[1-9]\d*)$/.test(key))
+                || !reserveBytes(state, Math.max(0, length - 1)))
+                return undefined;
+            const result = [];
+            for (let index = 0; index < length; index += 1) {
+                const descriptor = descriptors[String(index)];
+                if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor))
+                    return undefined;
+                const item = snapshotJsonValue(descriptor.value, state, depth + 1);
+                if (item === undefined)
+                    return undefined;
+                result.push(item);
+            }
+            return result;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return undefined;
+        const result = Object.create(null);
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const ownKeys = Reflect.ownKeys(value);
+        if (ownKeys.some((key) => typeof key !== 'string'))
+            return undefined;
+        const keys = ownKeys.sort();
+        if (keys.length > state.entryLimit || !reserveBytes(state, Math.max(0, keys.length - 1)))
+            return undefined;
+        for (const key of keys) {
+            const descriptor = descriptors[key];
+            if (!descriptor.enumerable || !('value' in descriptor))
+                return undefined;
+            if (Buffer.byteLength(key) > JSON_LIMITS.scalarBytes || !reserveBytes(state, Buffer.byteLength(JSON.stringify(key)) + 1))
+                return undefined;
+            const item = snapshotJsonValue(descriptor.value, state, depth + 1);
+            if (item === undefined)
+                return undefined;
+            Object.defineProperty(result, key, { enumerable: true, value: item });
+        }
+        return result;
+    }
+    catch { // A throwing accessor or proxy trap makes the value unsnapshottable; the caller refuses it.
+        return undefined;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function snapshotJson(value) {
+    return snapshotJsonWithEntryLimit(value, JSON_LIMITS.entries);
+}
+function snapshotJsonWithEntryLimit(value, entryLimit) {
+    return snapshotJsonValue(value, {
+        bytes: 0, nodes: 0, entryLimit, byteLimit: JSON_LIMITS.bytes,
+        scalarLimit: JSON_LIMITS.scalarBytes, ancestors: new WeakSet(),
+    }, 0);
+}
+export function snapshotGeneratedJson(value) {
+    return snapshotJsonValue(value, {
+        bytes: 0, nodes: 0, entryLimit: JSON_LIMITS.entries, byteLimit: 33_554_432,
+        scalarLimit: 16_777_216, ancestors: new WeakSet(),
+    }, 0);
+}
+const OBSERVATION_LIFECYCLE_STAGES = ['bootstrap', 'steady'];
+const SETUP_ACTION_KINDS = ['clone', 'wire-remote', 'report'];
+// Build tools and tool servers resolve their caches and locale from these; none carries a credential.
+// Every other parent variable stays out of product test stages, verification commands and MCP servers,
+// because they run repository code and the environment of an agent session routinely holds tokens.
+export const INHERITED_TOOL_ENVIRONMENT = Object.freeze(['HOME', 'USER', 'LOGNAME', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TZ']);
+// The only parent variables a Docker or Compose step receives: where the client finds the daemon and
+// how it authenticates to it. Anything else could reconfigure Compose or the process it starts.
+export const DOCKER_CLIENT_ENVIRONMENT = new Set(['PATH', 'DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_TLS_VERIFY', 'DOCKER_CERT_PATH']);
+// Names that reconfigure the Docker client, the dynamic loader, Node or a shell; a stack-declared
+// variable may never take one of them.
+export const HOST_PROCESS_CONTROL_ENV = /^(?:DOCKER_|COMPOSE_|LD_|DYLD_|LIBPATH$|SHLIB_PATH$|NODE_OPTIONS$|NODE_PATH$|BASH_ENV$|ENV$|PATH$|IFS$)/;
+export const OBSERVATION_PRODUCER_BYTE_LIMIT = 256;
+export const OBSERVATION_REASON_BYTE_LIMIT = 1_024;
+export const ENVIRONMENT_CODES = Object.freeze({
+    CONFIG_NOT_FOUND: 'CONFIG_NOT_FOUND',
+    CONFIG_UNREADABLE: 'CONFIG_UNREADABLE',
+    CONFIG_ENCODING_INVALID: 'CONFIG_ENCODING_INVALID',
+    CONFIG_PARSE_INVALID: 'CONFIG_PARSE_INVALID',
+    CONFIG_SCHEMA_INVALID: 'CONFIG_SCHEMA_INVALID',
+    GENERATED_HOST_PATH_UNMOUNTED: 'GENERATED_HOST_PATH_UNMOUNTED',
+    STATE_ROOT_UNAVAILABLE: 'STATE_ROOT_UNAVAILABLE',
+    STATE_FORMAT_UNSUPPORTED: 'STATE_FORMAT_UNSUPPORTED',
+    STATE_RECORD_MALFORMED: 'STATE_RECORD_MALFORMED',
+    STATE_LOCKED: 'STATE_LOCKED',
+    STATE_DURABILITY_INDETERMINATE: 'STATE_DURABILITY_INDETERMINATE',
+    SETUP_CONFIG_REQUIRED: 'SETUP_CONFIG_REQUIRED',
+    SETUP_OPTION_DUPLICATE: 'SETUP_OPTION_DUPLICATE',
+    SETUP_POSITIONAL_UNSUPPORTED: 'SETUP_POSITIONAL_UNSUPPORTED',
+    SETUP_PATH_OUTSIDE_ROOT: 'SETUP_PATH_OUTSIDE_ROOT',
+    SETUP_PATH_SYMLINK: 'SETUP_PATH_SYMLINK',
+    SETUP_PATH_TYPE_INVALID: 'SETUP_PATH_TYPE_INVALID',
+    SETUP_PARENT_MISSING: 'SETUP_PARENT_MISSING',
+    SETUP_REMOTE_MISMATCH: 'SETUP_REMOTE_MISMATCH',
+    SETUP_REMOTE_UNRESOLVABLE: 'SETUP_REMOTE_UNRESOLVABLE',
+    SETUP_MANUAL_MISSING: 'SETUP_MANUAL_MISSING',
+    SETUP_CLONE_FAILED: 'SETUP_CLONE_FAILED',
+    SETUP_NONE_ABSENT: 'SETUP_NONE_ABSENT',
+    SETUP_NONE_DIRECTORY: 'SETUP_NONE_DIRECTORY',
+    SETUP_NONE_REPOSITORY: 'SETUP_NONE_REPOSITORY',
+    SETUP_POSTCHECK_FAILED: 'SETUP_POSTCHECK_FAILED',
+    SETUP_INSTRUCTION_POINTER_OFFERED: 'SETUP_INSTRUCTION_POINTER_OFFERED',
+    SETUP_INSTRUCTION_POINTER_INVALID: 'SETUP_INSTRUCTION_POINTER_INVALID',
+    SETUP_INSTRUCTION_FILES_OFFERED: 'SETUP_INSTRUCTION_FILES_OFFERED',
+    SETUP_INSTRUCTION_FILES_INVALID: 'SETUP_INSTRUCTION_FILES_INVALID',
+    CONFIG_CHANGED_DURING_EXECUTION: 'CONFIG_CHANGED_DURING_EXECUTION',
+    EXECUTION_SPAWN_FAILED: 'EXECUTION_SPAWN_FAILED',
+    EXECUTION_PRECONDITION_CHANGED: 'EXECUTION_PRECONDITION_CHANGED',
+    EXECUTION_STAGING_FAILED: 'EXECUTION_STAGING_FAILED',
+    EXECUTION_STAGING_CLEANUP_FAILED: 'EXECUTION_STAGING_CLEANUP_FAILED',
+    EXECUTION_TIMEOUT: 'EXECUTION_TIMEOUT',
+    EXECUTION_STDOUT_LIMIT: 'EXECUTION_STDOUT_LIMIT',
+    EXECUTION_STDERR_LIMIT: 'EXECUTION_STDERR_LIMIT',
+    EXECUTION_STEP_FAILED: 'EXECUTION_STEP_FAILED',
+    EXECUTION_ABORTED: 'EXECUTION_ABORTED',
+    EXECUTION_TERMINATION_UNCONFIRMED: 'EXECUTION_TERMINATION_UNCONFIRMED',
+    EXECUTION_COMPENSATION_TIMEOUT: 'EXECUTION_COMPENSATION_TIMEOUT',
+    EXECUTION_COMPENSATION_STEP_FAILED: 'EXECUTION_COMPENSATION_STEP_FAILED',
+    LIFECYCLE_EVIDENCE_INVALID: 'LIFECYCLE_EVIDENCE_INVALID',
+    LIFECYCLE_PROGRESS_INVALID: 'LIFECYCLE_PROGRESS_INVALID',
+    STACK_RECORDED_UNDER_EARLIER_NAME: 'STACK_RECORDED_UNDER_EARLIER_NAME',
+    PORT_FAMILY_COLLISION: 'PORT_FAMILY_COLLISION',
+    PORT_LISTENER_EVIDENCE_INVALID: 'PORT_LISTENER_EVIDENCE_INVALID',
+    PORT_FAMILY_OUT_OF_RANGE: 'PORT_FAMILY_OUT_OF_RANGE',
+    PORT_LEASE_EXHAUSTED: 'PORT_LEASE_EXHAUSTED',
+    PORT_LOCAL_VALUE_CORRECTED: 'PORT_LOCAL_VALUE_CORRECTED',
+    PORT_EXTERNAL_REGISTRATION_GAP: 'PORT_EXTERNAL_REGISTRATION_GAP',
+    CLAIM_CO_TENANT: 'CLAIM_CO_TENANT',
+    CLAIM_LIVENESS_UNKNOWN: 'CLAIM_LIVENESS_UNKNOWN',
+    DRAIN_ATTEMPT_REPAIR_REQUIRED: 'DRAIN_ATTEMPT_REPAIR_REQUIRED',
+    INSTALL_POLICY_OBSERVATION_UNAVAILABLE: 'INSTALL_POLICY_OBSERVATION_UNAVAILABLE',
+    INSTALL_POLICY_OBSERVATION_INVALID: 'INSTALL_POLICY_OBSERVATION_INVALID',
+    INSTALL_POLICY_MISSING: 'INSTALL_POLICY_MISSING',
+    INSTALL_POLICY_AMBIGUOUS: 'INSTALL_POLICY_AMBIGUOUS',
+    TEMPLATE_NOT_FOUND: 'TEMPLATE_NOT_FOUND',
+    TEMPLATE_NOT_TRACKED: 'TEMPLATE_NOT_TRACKED',
+    TEMPLATE_IGNORED: 'TEMPLATE_IGNORED',
+    TEMPLATE_PATH_OUTSIDE_ROOT: 'TEMPLATE_PATH_OUTSIDE_ROOT',
+    ENVIRONMENT_FILE_NOT_FOUND: 'ENVIRONMENT_FILE_NOT_FOUND',
+    ENVIRONMENT_FILE_UNREADABLE: 'ENVIRONMENT_FILE_UNREADABLE',
+    ENVIRONMENT_FILE_TOO_LARGE: 'ENVIRONMENT_FILE_TOO_LARGE',
+    ENVIRONMENT_FILE_MALFORMED: 'ENVIRONMENT_FILE_MALFORMED',
+    INSTANCE_NOT_IGNORED: 'INSTANCE_NOT_IGNORED',
+    ENVIRONMENT_SEED_PRECONDITION_CHANGED: 'ENVIRONMENT_SEED_PRECONDITION_CHANGED',
+    ENVIRONMENT_SEED_FAILED: 'ENVIRONMENT_SEED_FAILED',
+    RUNTIME_UNAVAILABLE: 'RUNTIME_UNAVAILABLE',
+    RUNTIME_IMAGE_UNAVAILABLE: 'RUNTIME_IMAGE_UNAVAILABLE',
+    RUNTIME_UNMEASURED: 'RUNTIME_UNMEASURED',
+    RUNTIME_COMPOSE_REMOTE: 'RUNTIME_COMPOSE_REMOTE',
+    RUNTIME_PROBE_TIMEOUT: 'RUNTIME_PROBE_TIMEOUT',
+    LOGS_TRUNCATED: 'LOGS_TRUNCATED',
+    RESET_CONFIRMATION_REQUIRED: 'RESET_CONFIRMATION_REQUIRED',
+    RESET_CONFIRMATION_MISMATCH: 'RESET_CONFIRMATION_MISMATCH',
+    RESET_CO_TENANT: 'RESET_CO_TENANT',
+    EVIDENCE_UNAVAILABLE: 'EVIDENCE_UNAVAILABLE',
+    RECLAIM_LABEL_ESCAPE: 'RECLAIM_LABEL_ESCAPE',
+    RECLAIM_ACCOUNTING_MISMATCH: 'RECLAIM_ACCOUNTING_MISMATCH',
+    DOWN_RESOURCES_KEPT: 'DOWN_RESOURCES_KEPT',
+    CONFIG_STALE: 'CONFIG_STALE',
+    SIBLING_MISSING: 'SIBLING_MISSING',
+    GUIDE_CAP_EXCEEDED: 'GUIDE_CAP_EXCEEDED',
+    SIBLING_GUIDE_MISSING: 'SIBLING_GUIDE_MISSING',
+    MACHINE_MEMORY_BELOW_FLOOR: 'MACHINE_MEMORY_BELOW_FLOOR',
+    MACHINE_CPU_BELOW_FLOOR: 'MACHINE_CPU_BELOW_FLOOR',
+    MACHINE_DISK_BELOW_FLOOR: 'MACHINE_DISK_BELOW_FLOOR',
+    MACHINE_COLD_START_EXCEEDED: 'MACHINE_COLD_START_EXCEEDED',
+    GIT_STATE_UNHEALTHY: 'GIT_STATE_UNHEALTHY',
+    CHECKOUT_ADJACENCY_UNHEALTHY: 'CHECKOUT_ADJACENCY_UNHEALTHY',
+    GIT_COMPARISON_REMOTE_MISMATCH: 'GIT_COMPARISON_REMOTE_MISMATCH',
+    RUNNING_CHECKOUT_MISMATCH: 'RUNNING_CHECKOUT_MISMATCH',
+    ENVIRONMENT_KEYS_STALE: 'ENVIRONMENT_KEYS_STALE',
+    ENV_SCHEMA_UNHEALTHY: 'ENV_SCHEMA_UNHEALTHY',
+    ENV_SCHEMA_TOOL_MISSING: 'ENV_SCHEMA_TOOL_MISSING',
+    GENERATED_ENVIRONMENT_UNAVAILABLE: 'GENERATED_ENVIRONMENT_UNAVAILABLE',
+    CLAIM_STATE_UNHEALTHY: 'CLAIM_STATE_UNHEALTHY',
+    MOUNT_POSTURE_UNAVAILABLE: 'MOUNT_POSTURE_UNAVAILABLE',
+    STATE_UNSEEDED: 'STATE_UNSEEDED',
+    STACK_NOT_RUNNING: 'STACK_NOT_RUNNING',
+    SKILL_BUDGET_UNAVAILABLE: 'SKILL_BUDGET_UNAVAILABLE',
+    HARNESS_SURFACE_UNAVAILABLE: 'HARNESS_SURFACE_UNAVAILABLE',
+    DIRECTORY_GRANTS_UNAVAILABLE: 'DIRECTORY_GRANTS_UNAVAILABLE',
+    TEAM_METADATA_UNAVAILABLE: 'TEAM_METADATA_UNAVAILABLE',
+    COCKPIT_VERSION_MISMATCH: 'COCKPIT_VERSION_MISMATCH',
+    MOUNT_MATERIALIZATION_UNAVAILABLE: 'MOUNT_MATERIALIZATION_UNAVAILABLE',
+    ENVIRONMENT_NOT_DECLARED: 'ENVIRONMENT_NOT_DECLARED',
+    SERVICE_NOT_DECLARED: 'SERVICE_NOT_DECLARED',
+    GUARD_HOSTS_UNDECLARED: 'GUARD_HOSTS_UNDECLARED',
+    TESTING_GATE_UNDECLARED: 'TESTING_GATE_UNDECLARED',
+    EVALUATOR_UNAVAILABLE: 'EVALUATOR_UNAVAILABLE',
+    EVALUATOR_RUN_FAILED: 'EVALUATOR_RUN_FAILED',
+    EVALUATOR_FELL_BACK_TO_RUNNING_TOOL: 'EVALUATOR_FELL_BACK_TO_RUNNING_TOOL',
+    EVALUATOR_ANSWER_INVALID: 'EVALUATOR_ANSWER_INVALID',
+    TEST_GATE_UNSATISFIED: 'TEST_GATE_UNSATISFIED',
+    WORK_GRADE_UNSATISFIED: 'WORK_GRADE_UNSATISFIED',
+    WORK_CHECK_FAILED: 'WORK_CHECK_FAILED',
+    WORK_VERIFY_FAILED: 'WORK_VERIFY_FAILED',
+    WORK_PERSON_REQUIRED: 'WORK_PERSON_REQUIRED',
+    AUTONOMY_PERSON_REQUIRED: 'AUTONOMY_PERSON_REQUIRED',
+    AUTONOMY_CI_ONLY: 'AUTONOMY_CI_ONLY',
+    POLICY_WEAKENING_UNCONFIRMED: 'POLICY_WEAKENING_UNCONFIRMED',
+    WORK_ORDER_CLOSED: 'WORK_ORDER_CLOSED',
+    CODEX_HOOK_UNTRUSTED: 'CODEX_HOOK_UNTRUSTED',
+    SELFTEST_CUSTOM_PROBE_UNSUPPORTED: 'SELFTEST_CUSTOM_PROBE_UNSUPPORTED',
+    DECLARATION_UNCONFIRMED: 'DECLARATION_UNCONFIRMED',
+    COCKPIT_NOT_INSTALLED: 'COCKPIT_NOT_INSTALLED',
+    COCKPIT_LAUNCHER_UNPROVEN: 'COCKPIT_LAUNCHER_UNPROVEN',
+    SIBLING_REMOTE_UNRECORDED: 'SIBLING_REMOTE_UNRECORDED',
+    SECRET_FILE_TRACKED: 'SECRET_FILE_TRACKED',
+    SIBLING_INSTRUCTIONS_AGENTS_ONLY: 'SIBLING_INSTRUCTIONS_AGENTS_ONLY',
+    SIBLING_INSTRUCTIONS_CLAUDE_ONLY: 'SIBLING_INSTRUCTIONS_CLAUDE_ONLY',
+    SIBLING_INSTRUCTIONS_UNLINKED: 'SIBLING_INSTRUCTIONS_UNLINKED',
+    SIBLING_INSTRUCTIONS_MISSING: 'SIBLING_INSTRUCTIONS_MISSING',
+    SIBLING_INSTRUCTIONS_TOOL_ONLY: 'SIBLING_INSTRUCTIONS_TOOL_ONLY',
+    GUARD_SEARCH_PATH_RELATIVE: 'GUARD_SEARCH_PATH_RELATIVE',
+    SESSION_STACK_RETAINED: 'SESSION_STACK_RETAINED',
+    UPGRADE_PACKAGE_MANAGER_UNKNOWN: 'UPGRADE_PACKAGE_MANAGER_UNKNOWN',
+    UPGRADE_REGISTRY_UNREACHABLE: 'UPGRADE_REGISTRY_UNREACHABLE',
+    UPGRADE_VERSION_INVALID: 'UPGRADE_VERSION_INVALID',
+    UPGRADE_ALREADY_CURRENT: 'UPGRADE_ALREADY_CURRENT',
+    UPGRADE_INSTALL_FAILED: 'UPGRADE_INSTALL_FAILED',
+    UPGRADE_SYNC_FAILED: 'UPGRADE_SYNC_FAILED',
+    DATA_SEED_FAILED: 'DATA_SEED_FAILED',
+    DATA_SEED_UNAVAILABLE: 'DATA_SEED_UNAVAILABLE',
+});
+export const EXECUTION_FAILURE_CODES = Object.freeze([
+    ENVIRONMENT_CODES.EXECUTION_SPAWN_FAILED,
+    ENVIRONMENT_CODES.EXECUTION_PRECONDITION_CHANGED,
+    ENVIRONMENT_CODES.EXECUTION_STAGING_FAILED,
+    ENVIRONMENT_CODES.EXECUTION_STAGING_CLEANUP_FAILED,
+    ENVIRONMENT_CODES.EXECUTION_TIMEOUT,
+    ENVIRONMENT_CODES.EXECUTION_STDOUT_LIMIT,
+    ENVIRONMENT_CODES.EXECUTION_STDERR_LIMIT,
+    ENVIRONMENT_CODES.EXECUTION_STEP_FAILED,
+    ENVIRONMENT_CODES.EXECUTION_ABORTED,
+    ENVIRONMENT_CODES.EXECUTION_TERMINATION_UNCONFIRMED,
+]);
+export const REFUSAL_CODES = Object.freeze([
+    ENVIRONMENT_CODES.CONFIG_NOT_FOUND,
+    ENVIRONMENT_CODES.CONFIG_UNREADABLE,
+    ENVIRONMENT_CODES.CONFIG_ENCODING_INVALID,
+    ENVIRONMENT_CODES.CONFIG_PARSE_INVALID,
+    ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID,
+    ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE,
+    ENVIRONMENT_CODES.STATE_FORMAT_UNSUPPORTED,
+    ENVIRONMENT_CODES.STATE_RECORD_MALFORMED,
+    ENVIRONMENT_CODES.STATE_LOCKED,
+    ENVIRONMENT_CODES.STATE_DURABILITY_INDETERMINATE,
+    ENVIRONMENT_CODES.SETUP_CONFIG_REQUIRED,
+    ENVIRONMENT_CODES.SETUP_OPTION_DUPLICATE,
+    ENVIRONMENT_CODES.SETUP_POSITIONAL_UNSUPPORTED,
+    ENVIRONMENT_CODES.SETUP_PATH_OUTSIDE_ROOT,
+    ENVIRONMENT_CODES.SETUP_PATH_SYMLINK,
+    ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID,
+    ENVIRONMENT_CODES.SETUP_PARENT_MISSING,
+    ENVIRONMENT_CODES.SETUP_REMOTE_MISMATCH,
+    ENVIRONMENT_CODES.SETUP_REMOTE_UNRESOLVABLE,
+    ENVIRONMENT_CODES.SETUP_MANUAL_MISSING,
+    ENVIRONMENT_CODES.SETUP_CLONE_FAILED,
+    ENVIRONMENT_CODES.SETUP_POSTCHECK_FAILED,
+    ENVIRONMENT_CODES.SETUP_INSTRUCTION_POINTER_INVALID,
+    ENVIRONMENT_CODES.SETUP_INSTRUCTION_FILES_INVALID,
+    ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION,
+    ...EXECUTION_FAILURE_CODES,
+    ENVIRONMENT_CODES.EXECUTION_COMPENSATION_TIMEOUT,
+    ENVIRONMENT_CODES.EXECUTION_COMPENSATION_STEP_FAILED,
+    ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID,
+    ENVIRONMENT_CODES.LIFECYCLE_PROGRESS_INVALID,
+    ENVIRONMENT_CODES.STACK_RECORDED_UNDER_EARLIER_NAME,
+    ENVIRONMENT_CODES.PORT_FAMILY_COLLISION,
+    ENVIRONMENT_CODES.PORT_LISTENER_EVIDENCE_INVALID,
+    ENVIRONMENT_CODES.PORT_FAMILY_OUT_OF_RANGE,
+    ENVIRONMENT_CODES.PORT_LEASE_EXHAUSTED,
+    ENVIRONMENT_CODES.CLAIM_CO_TENANT,
+    ENVIRONMENT_CODES.CLAIM_LIVENESS_UNKNOWN,
+    ENVIRONMENT_CODES.DRAIN_ATTEMPT_REPAIR_REQUIRED,
+    ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_UNAVAILABLE,
+    ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_INVALID,
+    ENVIRONMENT_CODES.INSTALL_POLICY_MISSING,
+    ENVIRONMENT_CODES.INSTALL_POLICY_AMBIGUOUS,
+    ENVIRONMENT_CODES.TEMPLATE_NOT_FOUND,
+    ENVIRONMENT_CODES.TEMPLATE_NOT_TRACKED,
+    ENVIRONMENT_CODES.TEMPLATE_IGNORED,
+    ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+    ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND,
+    ENVIRONMENT_CODES.ENVIRONMENT_FILE_UNREADABLE,
+    ENVIRONMENT_CODES.ENVIRONMENT_FILE_TOO_LARGE,
+    ENVIRONMENT_CODES.ENVIRONMENT_FILE_MALFORMED,
+    ENVIRONMENT_CODES.INSTANCE_NOT_IGNORED,
+    ENVIRONMENT_CODES.ENVIRONMENT_SEED_PRECONDITION_CHANGED,
+    ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+    ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE,
+    ENVIRONMENT_CODES.RUNTIME_IMAGE_UNAVAILABLE,
+    ENVIRONMENT_CODES.RUNTIME_UNMEASURED,
+    ENVIRONMENT_CODES.RUNTIME_COMPOSE_REMOTE,
+    ENVIRONMENT_CODES.RUNTIME_PROBE_TIMEOUT,
+    ENVIRONMENT_CODES.RESET_CONFIRMATION_REQUIRED,
+    ENVIRONMENT_CODES.RESET_CONFIRMATION_MISMATCH,
+    ENVIRONMENT_CODES.RESET_CO_TENANT,
+    ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+    ENVIRONMENT_CODES.RECLAIM_LABEL_ESCAPE,
+    ENVIRONMENT_CODES.RECLAIM_ACCOUNTING_MISMATCH,
+    ENVIRONMENT_CODES.DOWN_RESOURCES_KEPT,
+    ENVIRONMENT_CODES.GIT_COMPARISON_REMOTE_MISMATCH,
+]);
+// A refusal cockpit itself words. Its message is cockpit-authored text (fixed wording, paths and
+// identifiers, never parsed bytes or a child's output), so errorCause surfaces it.
+export class RefusalError extends Error {
+}
+// A refusal names its cause in one bounded line. A RefusalError is cockpit's own wording, and a system
+// error (errno code plus syscall) carries only the operation and the path, so their first line is
+// surfaced. Any other message can echo the bytes being parsed or a child's output, environment-file
+// values among them, so only its class is named. Only own data properties are read: a thrown value can
+// be hostile, and describing it must not throw again. A RefusalError gets the wider bound because its
+// wording often ends in the command that fixes it, which a cut would drop.
+export function errorCause(error) {
+    if (isProxy(error) || !(error instanceof Error))
+        return 'a non-error value was thrown';
+    const own = (key) => Object.getOwnPropertyDescriptor(error, key)?.value;
+    const message = own('message');
+    if (typeof message === 'string') {
+        const line = message.split(/\r?\n|\r/, 1)[0];
+        if (error instanceof RefusalError)
+            return line.slice(0, OBSERVATION_REASON_BYTE_LIMIT);
+        if (typeof own('code') === 'string' && typeof own('syscall') === 'string')
+            return line.slice(0, 240);
+    }
+    return error instanceof TypeError ? 'TypeError' : error instanceof SyntaxError ? 'SyntaxError'
+        : error instanceof RangeError ? 'RangeError' : 'Error';
+}
+// A JSON.parse error quotes the bytes where parsing stopped, and a refusal reaches an agent that may
+// not read that file; name the subject, where parsing stopped and the shape expected, never the bytes.
+export function parseJsonText(text, subject, expected) {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        const position = Number(/\bposition (\d+)\b/.exec(error.message)?.[1]);
+        const before = Number.isSafeInteger(position) ? text.slice(0, position) : undefined;
+        const where = before === undefined ? '' : ` at line ${before.split('\n').length}, column ${before.length - before.lastIndexOf('\n')}`;
+        return { refusal: `${subject} is not valid JSON${where}; expected ${expected}` };
+    }
+}
+// For callers that refuse malformed input in their own words: unparseable text is undefined, and the
+// parser's message, which quotes the bytes, is never read.
+export function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return undefined;
+    }
+}
+export function hasErrorCode(error, ...codes) {
+    if (isProxy(error) || !(error instanceof Error))
+        return false;
+    const code = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+    return typeof code === 'string' && codes.includes(code);
+}
+export function isMissing(error) {
+    return hasErrorCode(error, 'ENOENT', 'ENOTDIR');
+}
+const canonicalTimestamp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+export function isCanonicalTimestamp(value) {
+    if (typeof value !== 'string' || !canonicalTimestamp.test(value))
+        return false;
+    const milliseconds = Date.parse(value);
+    return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value;
+}
+// Device and inode alone do not name an object over time: ext4 hands the inode number a removal
+// just freed to the next object created, so a path removed and recreated between planning and
+// execution reproduces the recorded pair exactly. Birth time is fixed at creation, so it tells the
+// replacement apart while still admitting the content changes a cache or its parent legitimately
+// sees between planning and removal; change time would refuse those. A filesystem that records no
+// birth time reports 0 for both objects, and the comparison falls back to device and inode, which
+// leaves in-place recreation undetectable there.
+export function filesystemObjectIdentity(status) {
+    return { dev: Number(status.dev), ino: Number(status.ino), birthtimeNs: String(status.birthtimeNs) };
+}
+export function sameFilesystemObject(status, recorded) {
+    return Number(status.dev) === recorded.dev && Number(status.ino) === recorded.ino
+        && String(status.birthtimeNs) === recorded.birthtimeNs;
+}
+export function isFilesystemObjectIdentity(value) {
+    return Number.isSafeInteger(value.dev) && value.dev >= 0
+        && Number.isSafeInteger(value.ino) && value.ino >= 0
+        && typeof value.birthtimeNs === 'string' && /^(0|-?[1-9][0-9]{0,19})$/.test(value.birthtimeNs);
+}
+function stringTuple(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && !item.includes('\0'));
+}
+function stringRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.entries(value).every(([name, item]) => name.length > 0 && !name.includes('\0') && !name.includes('=')
+            && typeof item === 'string' && !item.includes('\0'));
+}
+function canonicalPaths(value) {
+    return Array.isArray(value) && new Set(value).size === value.length
+        && value.every((path) => typeof path === 'string' && isAbsolute(path) && normalize(path) === path && !path.includes('\0'));
+}
+function filesystemChecks(value) {
+    return Array.isArray(value) && value.every((candidate) => {
+        if (candidate === null || typeof candidate !== 'object')
+            return false;
+        const check = candidate;
+        const identity = check.identity;
+        const identityIsValid = identity === undefined || identity !== null && typeof identity === 'object'
+            && exactKeys(identity, ['dev', 'ino', 'birthtimeNs', 'ancestors'])
+            && isFilesystemObjectIdentity(identity)
+            && Array.isArray(identity.ancestors) && identity.ancestors.length >= 1 && identity.ancestors.length <= 64
+            && new Set(identity.ancestors.map((ancestor) => ancestor?.path)).size === identity.ancestors.length
+            && identity.ancestors.every((ancestor, index) => ancestor !== null && typeof ancestor === 'object'
+                && exactKeys(ancestor, ['path', 'dev', 'ino', 'birthtimeNs']) && canonicalPaths([ancestor.path])
+                && isFilesystemObjectIdentity(ancestor)
+                && (index === 0 || dirname(ancestor.path) === identity.ancestors[index - 1].path))
+            && typeof check.path === 'string' && dirname(check.path) === identity.ancestors.at(-1).path;
+        const keys = ['path', 'expected', ...(check.sha256 === undefined ? [] : ['sha256', 'maxBytes']), ...(identity === undefined ? [] : ['identity'])];
+        return exactKeys(candidate, keys)
+            && canonicalPaths([check.path]) && (check.expected === 'absent' || check.expected === 'directory' || check.expected === 'file')
+            && (check.sha256 === undefined
+                ? check.maxBytes === undefined
+                : check.expected === 'file' && typeof check.sha256 === 'string' && /^[a-f0-9]{64}$/.test(check.sha256)
+                    && Number.isSafeInteger(check.maxBytes) && check.maxBytes >= 1 && check.maxBytes <= 536_870_912)
+            && identityIsValid && (identity === undefined || check.expected !== 'absent');
+    });
+}
+function consumedFiles(value, argv) {
+    if (!Array.isArray(value))
+        return false;
+    const paths = new Set();
+    const indexes = new Set();
+    let executableCount = 0;
+    for (const candidate of value) {
+        if (candidate === null || typeof candidate !== 'object')
+            return false;
+        const file = candidate;
+        if (!exactKeys(candidate, file.executable
+            ? ['path', 'sha256', 'maxBytes', 'argvIndexes', 'executable', 'executionMode']
+            : ['path', 'sha256', 'maxBytes', 'argvIndexes', 'executable']) || !canonicalPaths([file.path])
+            || typeof file.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(file.sha256) || !Array.isArray(file.argvIndexes)
+            || !Number.isSafeInteger(file.maxBytes) || file.maxBytes < 1 || file.maxBytes > 536_870_912
+            || file.argvIndexes.length === 0 || typeof file.executable !== 'boolean' || paths.has(file.path)
+            || (file.executable && file.executionMode !== 'verified-path'))
+            return false;
+        paths.add(file.path);
+        if (file.executable)
+            executableCount += 1;
+        for (const index of file.argvIndexes) {
+            if (!Number.isSafeInteger(index) || index < 0 || index >= argv.length || indexes.has(index)
+                || argv[index] !== file.path || (index === 0) !== file.executable)
+                return false;
+            indexes.add(index);
+        }
+    }
+    return value.length === 0 || executableCount === 1;
+}
+function expectedObservations(value) {
+    return Array.isArray(value) && value.every((candidate) => {
+        if (candidate === null || typeof candidate !== 'object')
+            return false;
+        const expected = candidate;
+        if (expected.kind === 'path')
+            return exactKeys(candidate, ['kind', 'target', 'state']) && canonicalPaths([expected.target])
+                && ['absent', 'directory', 'repository'].includes(expected.state);
+        return expected.kind === 'remote' && exactKeys(candidate, ['kind', 'target', 'name', 'url']) && canonicalPaths([expected.target])
+            && typeof expected.name === 'string' && expected.name.length > 0 && !expected.name.includes('\0')
+            && typeof expected.url === 'string' && expected.url.length > 0 && !expected.url.includes('\0');
+    });
+}
+// Product test stages declare up to two hours; every other owner bounds its steps far lower itself.
+export const MAX_STEP_TIMEOUT_MS = 7_200_000;
+function executionStepSnapshot(snapshot, traversal) {
+    if (snapshot === undefined || snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot))
+        return undefined;
+    const item = snapshot;
+    const baseKeys = ['id', 'argv', 'argv0', 'cwd', 'env', 'timeoutMs', 'stdoutLimitBytes', 'stderrLimitBytes', 'paths', 'ports', 'labels', 'expected', 'consumedFiles', 'filesystemChecks', 'compensation'];
+    const optionalKeys = [item.spawnNotAfter === undefined ? undefined : 'spawnNotAfter', item.executionFence === undefined ? undefined : 'executionFence',
+        item.outputOverflow === undefined ? undefined : 'outputOverflow', item.failureOutput === undefined ? undefined : 'failureOutput']
+        .filter((key) => key !== undefined);
+    if (!exactKeys(snapshot, [...baseKeys, ...optionalKeys])
+        || typeof item.id !== 'string' || item.id.length === 0 || item.id.includes('\0') || traversal.count >= 256
+        || traversal.ids.has(item.id) || !stringTuple(item.argv) || typeof item.argv0 !== 'string' || item.argv0.length === 0 || item.argv0.includes('\0')
+        || item.argv[0].length === 0 || !canonicalPaths([item.cwd]) || !stringRecord(item.env)
+        || !Number.isSafeInteger(item.timeoutMs) || item.timeoutMs <= 0 || item.timeoutMs > MAX_STEP_TIMEOUT_MS
+        || item.outputOverflow !== undefined && item.outputOverflow !== 'retain-tail'
+        || item.failureOutput !== undefined && item.failureOutput !== 'stderr-tail'
+        || item.spawnNotAfter !== undefined && (!isCanonicalTimestamp(item.spawnNotAfter) || !Number.isFinite(Date.parse(item.spawnNotAfter)))
+        || !Number.isSafeInteger(item.stdoutLimitBytes) || item.stdoutLimitBytes < 0 || item.stdoutLimitBytes > 16_777_216
+        || !Number.isSafeInteger(item.stderrLimitBytes) || item.stderrLimitBytes < 0 || item.stderrLimitBytes > 16_777_216 || !canonicalPaths(item.paths)
+        || !Array.isArray(item.ports) || new Set(item.ports).size !== item.ports.length || item.ports.some((port) => !Number.isSafeInteger(port) || port < 1 || port > 65_535)
+        || !stringRecord(item.labels) || !expectedObservations(item.expected) || !consumedFiles(item.consumedFiles, item.argv)
+        || !filesystemChecks(item.filesystemChecks) || item.filesystemChecks.some((check) => item.consumedFiles.some((file) => file.path === check.path))
+        || item.executionFence !== undefined && (!exactKeys(item.executionFence, ['attemptId', 'markerPath', 'socketPath'])
+            || typeof item.executionFence.attemptId !== 'string' || !/^[a-f0-9]{64}$/.test(item.executionFence.attemptId)
+            || !canonicalPaths([item.executionFence.markerPath, item.executionFence.socketPath])
+            || item.executionFence.markerPath === item.executionFence.socketPath || Buffer.byteLength(item.executionFence.socketPath) > 103)
+        || !Array.isArray(item.compensation) || item.argv.length > 1_024 || Object.keys(item.env).length > 1_024 || Object.keys(item.labels).length > 1_024
+        || item.paths.length > 1_024 || item.ports.length > 1_024 || item.expected.length > 1_024
+        || item.consumedFiles.length > 1_024 || item.filesystemChecks.length > 1_024 || item.compensation.length > 1_024)
+        return undefined;
+    traversal.count += 1;
+    traversal.ids.add(item.id);
+    if (item.compensation.some((step) => executionStepSnapshot(step, traversal) === undefined))
+        return undefined;
+    return item;
+}
+export function snapshotExecutionStep(value) {
+    return executionStepSnapshot(snapshotJson(value), { count: 0, ids: new Set() });
+}
+export function snapshotExecutionPlan(value) {
+    const snapshot = snapshotJson(value);
+    if (snapshot === undefined || snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot) || !exactKeys(snapshot, ['steps']))
+        return undefined;
+    const plan = snapshot;
+    const traversal = { count: 0, ids: new Set() };
+    return Array.isArray(plan.steps) && plan.steps.length <= 256
+        && plan.steps.every((step) => executionStepSnapshot(step, traversal) !== undefined) ? plan : undefined;
+}
+export function snapshotLifecyclePlan(value) {
+    const snapshot = snapshotJsonWithEntryLimit(value, 16_384);
+    if (snapshot === undefined || snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)
+        || !exactKeys(snapshot, ['verb', 'progress', 'steps', 'resumeBoundary', 'compensation', 'diagnostics']))
+        return undefined;
+    const plan = snapshot;
+    if (!['up', 'sleep', 'down', 'reset'].includes(plan.verb))
+        return undefined;
+    const progress = plan.progress;
+    if (progress === null || typeof progress !== 'object' || Array.isArray(progress)
+        || !exactKeys(progress, ['workBasisSha256', 'operationGeneration', 'completedServices'])
+        || typeof progress.workBasisSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(progress.workBasisSha256)
+        || typeof progress.operationGeneration !== 'string' || !/^[a-f0-9]{64}$/.test(progress.operationGeneration)
+        || !Array.isArray(progress.completedServices) || progress.completedServices.length > 4_096)
+        return undefined;
+    const completedServices = new Set();
+    for (const completed of progress.completedServices) {
+        if (completed === null || typeof completed !== 'object' || Array.isArray(completed)
+            || !exactKeys(completed, ['service', 'containerId'])
+            || typeof completed.service !== 'string' || !/^[a-z0-9][a-z0-9_.-]*$/.test(completed.service)
+            || typeof completed.containerId !== 'string' || !/^[a-f0-9]{64}$/.test(completed.containerId)
+            || completedServices.has(completed.service))
+            return undefined;
+        completedServices.add(completed.service);
+    }
+    const stepIds = new Set();
+    const plannedServices = new Set();
+    const entrypointNames = new Set();
+    const captureStep = (candidate) => {
+        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate))
+            return false;
+        const step = candidate;
+        if (typeof step.id !== 'string' || step.id.length === 0 || Buffer.byteLength(step.id) > 512 || step.id.includes('\0')
+            || typeof step.kind !== 'string' || stepIds.has(step.id))
+            return false;
+        let valid = false;
+        if (step.kind === 'preflight') {
+            valid = exactKeys(candidate, ['id', 'kind']);
+        }
+        else if (step.kind === 'claim') {
+            valid = exactKeys(candidate, ['id', 'kind', 'action']) && (step.action === 'acquire' || step.action === 'release');
+        }
+        else if (step.kind === 'prepare') {
+            valid = exactKeys(candidate, ['id', 'kind', 'execution']) && snapshotExecutionStep(step.execution) !== undefined;
+        }
+        else if (step.kind === 'service') {
+            const service = step.service;
+            if (typeof service !== 'string')
+                return false;
+            valid = exactKeys(candidate, ['id', 'kind', 'service'])
+                && /^[a-z0-9][a-z0-9_.-]*$/.test(service)
+                && plannedServices.size < 4_096 && !plannedServices.has(service);
+            if (valid)
+                plannedServices.add(service);
+        }
+        else if (step.kind === 'publish-entrypoints') {
+            if (!exactKeys(candidate, ['id', 'kind', 'values']) || !Array.isArray(step.values) || step.values.length > 4_096)
+                return false;
+            valid = step.values.every((entrypoint) => {
+                if (entrypoint === null || typeof entrypoint !== 'object' || Array.isArray(entrypoint)
+                    || !exactKeys(entrypoint, ['name', 'kind', 'port', 'value']))
+                    return false;
+                const value = entrypoint;
+                if (typeof value.name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(value.name)
+                    || entrypointNames.has(value.name) || !isEntrypointKind(value.kind)
+                    || typeof value.port !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(value.port)
+                    || !boundedContractText(value.value, 4_096))
+                    return false;
+                entrypointNames.add(value.name);
+                return true;
+            });
+        }
+        if (!valid)
+            return false;
+        stepIds.add(step.id);
+        return true;
+    };
+    const captureSteps = (steps) => {
+        if (!Array.isArray(steps) || steps.length > 16_384)
+            return false;
+        return steps.every(captureStep);
+    };
+    if (!captureSteps(plan.steps) || !Array.isArray(plan.compensation) || plan.compensation.length > 256
+        || !plan.compensation.every((candidate) => {
+            if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)
+                || !exactKeys(candidate, ['step', 'ownership']))
+                return false;
+            const item = candidate;
+            const ownership = item.ownership;
+            return captureStep(item.step) && item.step.kind === 'claim' && item.step.action === 'release'
+                && ownership !== null && typeof ownership === 'object'
+                && !Array.isArray(ownership) && exactKeys(ownership, ['stackId', 'holderId', 'recordRevision', 'change'])
+                && typeof ownership.stackId === 'string' && /^stack:[a-f0-9]{64}$/.test(ownership.stackId)
+                && typeof ownership.holderId === 'string' && /^holder:[a-f0-9]{64}:session$/.test(ownership.holderId)
+                && Number.isSafeInteger(ownership.recordRevision) && ownership.recordRevision >= 0 && ownership.change === 'acquired';
+        }))
+        return undefined;
+    const boundary = plan.resumeBoundary;
+    if (boundary === null || typeof boundary !== 'object' || Array.isArray(boundary)
+        || !exactKeys(boundary, ['completedStepIds', 'nextStepId']) || !Array.isArray(boundary.completedStepIds)
+        || boundary.completedStepIds.length > 16_384 || new Set(boundary.completedStepIds).size !== boundary.completedStepIds.length
+        || boundary.completedStepIds.some((id) => typeof id !== 'string' || id.length === 0 || Buffer.byteLength(id) > 512 || !stepIds.has(id))
+        || boundary.nextStepId !== null && (typeof boundary.nextStepId !== 'string' || boundary.nextStepId.length === 0 || Buffer.byteLength(boundary.nextStepId) > 512 || !stepIds.has(boundary.nextStepId))
+        || boundary.completedStepIds.some((id, index) => plan.steps[index]?.id !== id)
+        || boundary.nextStepId !== (plan.steps[boundary.completedStepIds.length]?.id ?? null)
+        || !Array.isArray(plan.diagnostics) || plan.diagnostics.length > 256
+        || !plan.diagnostics.every((candidate) => {
+            if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate))
+                return false;
+            const item = candidate;
+            const keys = ['severity', 'code', 'message', ...(item.target === undefined ? [] : ['target']), ...(item.fix === undefined ? [] : ['fix'])];
+            return exactKeys(candidate, keys) && ['error', 'warning', 'info'].includes(item.severity)
+                && Object.values(ENVIRONMENT_CODES).includes(item.code) && boundedContractText(item.message, 4_096)
+                && (item.target === undefined || boundedContractText(item.target, 4_096))
+                && (item.fix === undefined || boundedContractText(item.fix, 4_096));
+        }))
+        return undefined;
+    const completedPlanServices = plan.steps.slice(0, boundary.completedStepIds.length)
+        .filter((step) => step.kind === 'service');
+    if (progress.completedServices.length !== completedPlanServices.length
+        || progress.completedServices.some((completed, index) => completed.service !== completedPlanServices[index]?.service))
+        return undefined;
+    return plan;
+}
+function boundedContractText(value, maximum = OBSERVATION_REASON_BYTE_LIMIT) {
+    return typeof value === 'string' && value.length > 0 && !value.includes('\0')
+        && Buffer.byteLength(value, 'utf8') <= maximum;
+}
+function validExpectation(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (candidate.kind === 'present')
+        return exactKeys(value, ['kind']);
+    if (candidate.kind === 'one-of') {
+        return exactKeys(value, ['kind', 'values']) && Array.isArray(candidate.values)
+            && candidate.values.length > 0 && candidate.values.length <= 4_096
+            && candidate.values.every((item) => snapshotJson(item) !== undefined);
+    }
+    if (candidate.kind === 'minimum' || candidate.kind === 'maximum') {
+        return exactKeys(value, ['kind', 'value']) && Number.isSafeInteger(candidate.value);
+    }
+    return candidate.kind === 'equal' && exactKeys(value, ['kind', 'value'])
+        && snapshotJson(candidate.value) !== undefined;
+}
+export function snapshotEnvironmentObservation(value) {
+    const snapshot = snapshotJson(value);
+    if (snapshot === undefined || snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)
+        || !exactKeys(snapshot, ['code', 'owner', 'stackId', 'source', 'observed', 'expectation', 'applicability', 'freshness', 'remedy']))
+        return undefined;
+    const candidate = snapshot;
+    if (!Object.values(ENVIRONMENT_CODES).includes(candidate.code) || !boundedContractText(candidate.owner, OBSERVATION_PRODUCER_BYTE_LIMIT)
+        || !/^stack:[a-f0-9]{64}$/.test(candidate.stackId) || !boundedContractText(candidate.source)
+        || !boundedContractText(candidate.remedy) || !validExpectation(candidate.expectation))
+        return undefined;
+    const observed = candidate.observed;
+    if (observed === null || typeof observed !== 'object' || Array.isArray(observed)
+        || !isCanonicalTimestamp(observed.observedAt))
+        return undefined;
+    if (observed.state === 'available') {
+        if (!exactKeys(observed, ['state', 'value', 'observedAt']) || snapshotJson(observed.value) === undefined)
+            return undefined;
+    }
+    else if ((observed.state === 'unavailable' || observed.state === 'failed')) {
+        if (!exactKeys(observed, ['state', 'reason', 'observedAt']) || !boundedContractText(observed.reason))
+            return undefined;
+    }
+    else
+        return undefined;
+    const applicability = candidate.applicability;
+    if (applicability === null || typeof applicability !== 'object' || Array.isArray(applicability)
+        || !boundedContractText(applicability.posture, OBSERVATION_PRODUCER_BYTE_LIMIT))
+        return undefined;
+    if (applicability.state === 'required') {
+        if (!exactKeys(applicability, ['state', 'posture']))
+            return undefined;
+    }
+    else if (applicability.state === 'not-applicable') {
+        if (!exactKeys(applicability, ['state', 'posture', 'reason']) || !boundedContractText(applicability.reason))
+            return undefined;
+    }
+    else
+        return undefined;
+    const freshness = candidate.freshness;
+    if (freshness === null || typeof freshness !== 'object' || Array.isArray(freshness))
+        return undefined;
+    if (freshness.state === 'current') {
+        if (!exactKeys(freshness, ['state']))
+            return undefined;
+    }
+    else if (freshness.state === 'stale' || freshness.state === 'missing') {
+        if (!exactKeys(freshness, ['state', 'reason']) || !boundedContractText(freshness.reason))
+            return undefined;
+    }
+    else
+        return undefined;
+    return snapshot;
+}
+/** A command refusal carrying the diagnostics an owner raised: exit status 2 and no result. */
+export function forwardedRefusal(diagnostics) {
+    return { kind: 'refusal', status: 2, result: null, diagnostics };
+}