design

var AgentAttachPayload = Type("AgentAttachPayload", func() {
	Description("Payload for attaching a controller to a workspace's guest agent session")
	Attribute("namespace", String, "Workspace namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("name", String, "Workspace name", func() {
		Example("my-workspace")
	})
	Attribute("participant", String, "Viewer-chosen participant label, echoed in session records. Not an authorization boundary", func() {
		Example("chris-laptop")
	})
	Required("name")
})

var AgentReleaseResult = ResultType("application/vnd.agent-release+json", func() {
	Description("Result of releasing a workspace guest agent session")
	Attributes(func() {
		Attribute("ok", Boolean, "Whether the session is gone (unknown ids report ok: best-effort release)", func() {
			Example(true)
		})
	})
	Required("ok")
})

var AgentRenewResult = ResultType("application/vnd.agent-renew+json", func() {
	Description("Result of renewing a workspace guest agent session")
	Attributes(func() {
		Attribute("ttl_ms", Int, "Renewed lifetime in milliseconds", func() {
			Example(60000)
		})
		Attribute("protocol", Int, "Agent ticket/API revision", func() {
			Example(1)
		})
	})
	Required("ttl_ms", "protocol")
})

var AgentStatusResult = ResultType("application/vnd.agent-status+json", func() {
	Description("Live agent session state for a workspace: whether any unexpired attach session exists")
	Attributes(func() {
		Attribute("active", Boolean, "Whether at least one live agent session is bound to this workspace", func() {
			Example(true)
		})
		Attribute("sessions", Int, "Live (unexpired) session count for this workspace", func() {
			Example(1)
		})
		Attribute("protocol", Int, "Agent ticket/API revision", func() {
			Example(1)
		})
	})
	Required("active", "sessions", "protocol")
})

var AgentTicketResult = ResultType("application/vnd.agent-ticket+json", func() {
	Description("Short-lived attach ticket for a workspace guest agent session")
	Attributes(func() {
		Attribute("id", String, "Opaque server-side session identifier for renew/release correlation. Never sent to the guest", func() {
			Example("8ec18121f4c2409aa7c025487f4e310c")
		})
		Attribute("ticket", String, "Signed bearer ticket (id.payload.signature) to present in the agent attach message", func() {
			Example("8ec18121f4c2409aa7c025487f4e310c.eyJ3b3Jrc3BhY2VVaWQiOiJ3cy0xIn0.c2ln")
		})
		Attribute("ttl_ms", Int, "Ticket/session lifetime in milliseconds; renew at half of it", func() {
			Example(60000)
		})
		Attribute("protocol", Int, "Agent ticket/API revision", func() {
			Example(1)
		})
	})
	Required("id", "ticket", "ttl_ms", "protocol")
})

var AgentUpgradeAttemptResult = ResultType("application/vnd.agent-upgrade-attempt+json", func() {
	Description("Admitted agent upgrade attempt with phase progress and outcome")
	Attributes(func() {
		Attribute("attempt_id", String, "Server-minted attempt identifier", func() {
			Pattern(`^upg_[0-9a-f]{24}$`)
			Example("upg_9f82c1a0b3d4e5f60718293a")
		})
		Attribute("namespace", String, func() { Example("team-a") })
		Attribute("workspace_name", String, func() { Example("vm-1") })
		Attribute("workspace_uid", String, func() { Example("abc123") })
		Attribute("vm_uid", String, "Controller-owned VM UID the reservation is bound to", func() {
			Example("0d3f9a7e-6b1c-4f2a-9e8d-1a2b3c4d5e6f")
		})
		Attribute("actor_id", String, "UID of the administrator that admitted the attempt", func() { Example("user-uid-1") })
		Attribute("state", String, "Attempt lifecycle state", func() {
			Enum(
				"admitted", "staging", "prepared", "installing", "verifying", "succeeded",
				"awaiting_reboot", "rollback_pending", "rolling_back", "rolled_back",
				"cancelled", "failed", "manual_recovery_required", "unknown", "recording_lost",
			)
			Example("admitted")
		})
		Attribute("target_id", String, func() { Example("windows11-amd64-v2") })
		Attribute("target_manifest_sha256", String, func() {
			Pattern(`^[0-9a-f]{64}$`)
			Example("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
		})
		Attribute("expected_installed_inventory_sha256", String, func() {
			Pattern(`^[0-9a-f]{64}$`)
			Example("810151abf0615815b24e01967ec665e0eb583500f1eb5fa456361935b22b183b")
		})
		Attribute("allow_reboot", Boolean, "Whether the admitted attempt may run the bounded reboot sequence", func() { Example(false) })
		Attribute("cancel_requested", Boolean, "An administrator requested safe-boundary cancellation", func() { Example(false) })
		Attribute("execution_id", String, "Linked execution admission record (recording authorization)", func() {
			Example("exec_9f82")
		})
		Attribute("recording_id", String, "Protected attempt recording", func() { Example("rec_9f82") })
		Attribute("recording_url", String, "Independently authorized recording link", func() {
			Example("/v1/executions/exec_9f82/recording")
		})
		Attribute("status_url", String, "Canonical status URL for this attempt", func() {
			Example("/v1/workspaces/vm-1/agent-upgrades/upg_9f82c1a0b3d4e5f60718293a?namespace=team-a")
		})
		Attribute("journal_sequence", UInt64, "Last reconciled guest journal sequence", func() { Example(0) })
		Attribute("predecessor_target_id", String, "Pinned rollback predecessor target", func() { Example("windows11-amd64-v1") })
		Attribute("predecessor_manifest_sha256", String, "Pinned rollback predecessor manifest digest", func() {
			Pattern(`^[0-9a-f]{64}$`)
		})
		Attribute("error_code", String, "Bounded machine-readable failure code", func() { Example("") })
		Attribute("admitted_at", String, "RFC3339 admission timestamp", func() {
			Format(FormatDateTime)
			Example("2026-10-19T00:00:00Z")
		})
		Attribute("staging_at", String, func() { Format(FormatDateTime) })
		Attribute("prepared_at", String, func() { Format(FormatDateTime) })
		Attribute("installing_at", String, func() { Format(FormatDateTime) })
		Attribute("awaiting_reboot_at", String, func() { Format(FormatDateTime) })
		Attribute("verifying_at", String, func() { Format(FormatDateTime) })
		Attribute("rollback_requested_at", String, func() { Format(FormatDateTime) })
		Attribute("rolling_back_at", String, func() { Format(FormatDateTime) })
		Attribute("terminal_at", String, func() { Format(FormatDateTime) })
		Attribute("updated_at", String, func() { Format(FormatDateTime) })
	})
	Required(
		"attempt_id", "namespace", "workspace_name", "workspace_uid", "vm_uid", "actor_id",
		"state", "target_id", "target_manifest_sha256", "expected_installed_inventory_sha256",
		"allow_reboot", "cancel_requested", "execution_id", "recording_id", "recording_url",
		"status_url", "journal_sequence", "admitted_at", "updated_at",
	)
})

var AgentUpgradeAvailability = ResultType("application/vnd.agent-upgrade-availability+json", func() {
	Description("Fresh agent-upgrade availability for one workspace")
	Attributes(func() {
		Attribute("policy_enabled", Boolean, "Platform policy admits agent upgrades", func() { Example(false) })
		Attribute("storage_available", Boolean, "Durable attempt/recording storage is ready", func() { Example(false) })
		Attribute("workspace_eligible", Boolean, "Workspace resolves as an eligible running Windows VM", func() { Example(false) })
		Attribute("inventory_available", Boolean, "Fresh authenticated guest inventory is available (guest integration)", func() {
			Example(false)
		})
		Attribute("admissible", Boolean, "A start request would be admitted right now", func() { Example(false) })
		Attribute("deny_reason", String, "Why start would be denied; empty when admissible", func() {
			Enum("", "policy_disabled", "storage_unavailable", "eligibility_unavailable", "workspace_not_eligible", "attempt_active")
			Example("policy_disabled")
		})
		Attribute("active_attempt_id", String, "Reservation-holding attempt for this VM, when present", func() {
			Example("upg_9f82c1a0b3d4e5f60718293a")
		})
		Attribute("vm_uid", String, "Resolved controller-owned VM UID, when eligible", func() {
			Example("0d3f9a7e-6b1c-4f2a-9e8d-1a2b3c4d5e6f")
		})
	})
	Required("policy_enabled", "storage_available", "workspace_eligible", "inventory_available", "admissible", "deny_reason")
})

var AgentUpgradeStartPayload = Type("AgentUpgradeStartPayload", func() {
	Description("Admit a single explicit agent upgrade. Clients cannot submit URLs, hashes of payloads, install directories or installer flags.")
	Attribute("namespace", String, func() {
		Pattern("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
		MaxLength(63)
		Default("workspaces")
		Example("team-a")
	})
	Attribute("name", String, func() {
		Pattern("^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$")
		MaxLength(253)
		Example("vm-1")
	})
	Attribute("target_id", String, "Operator-approved immutable target", func() {
		Pattern(`^[a-z0-9][a-z0-9._-]{0,127}$`)
		Example("windows11-amd64-v2")
	})
	Attribute("target_manifest_sha256", String, "Expected signed manifest digest for the target", func() {
		Pattern(`^[0-9a-f]{64}$`)
		Example("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
	})
	Attribute("expected_vm_uid", String, "Client-observed VM UID; must match the current controller-owned UID", func() {
		Pattern(`^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$`)
		Example("0d3f9a7e-6b1c-4f2a-9e8d-1a2b3c4d5e6f")
	})
	Attribute("expected_revocation_epoch", UInt64, "Client-observed execution revocation epoch", func() { Example(4) })
	Attribute("expected_installed_inventory_sha256", String, "Client-observed installed inventory digest (re-verified before install)", func() {
		Pattern(`^[0-9a-f]{64}$`)
		Example("810151abf0615815b24e01967ec665e0eb583500f1eb5fa456361935b22b183b")
	})
	Attribute("idempotency_key", String, "Client-chosen key; an identical replay returns the original attempt", func() {
		Pattern(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
		Example("run-2026-10-19-001")
	})
	Attribute("allow_reboot", Boolean, "Permit the recorded bounded reboot sequence", func() {
		Default(false)
		Example(false)
	})
	Required(
		"namespace", "name", "target_id", "target_manifest_sha256", "expected_vm_uid",
		"expected_revocation_epoch", "expected_installed_inventory_sha256", "idempotency_key", "allow_reboot",
	)
})

var ContainerState = Type("ContainerState", func() {
	Description("State of the workspace container")
	Attribute("state", String, "Current state: running, waiting, terminated", func() {
		Enum("running", "waiting", "terminated", "unknown")
		Example("running")
	})
	Attribute("reason", String, "Reason for the state", func() {
		Example("Started")
	})
	Attribute("message", String, "Details about the state", func() {
		Example("Container started successfully")
	})
	Attribute("started_at", String, "Time the container started", func() {
		Example("2025-01-02T15:04:05Z")
	})
})

var ControlResult = ResultType("application/vnd.display-control+json", func() {
	Description("Result of a control transition")
	Attributes(func() {
		Attribute("controller", Participant, "Controller after the transition, if any")
		Attribute("was_held", Boolean, "Whether a controller was present before the transition", func() {
			Example(true)
		})
		Attribute("released", Boolean, "True when release cleared the controller", func() {
			Example(false)
		})
	})
	Required("was_held", "released")
})

var CreateImagePayload = Type("CreateImagePayload", func() {
	Description("Payload for creating a new image")
	Attribute("name", String, "Display name", func() {
		Example("Code Server (VS Code)")
	})
	Attribute("image", String, "Container image reference", func() {
		Example("codercom/code-server:latest")
	})
	Attribute("description", String, "Description of the image", func() {
		Example("Code editor in the browser")
	})
	Attribute("category", String, "Category for grouping (e.g. Desktop, IDE, Tool, Game)", func() {
		Example("IDE")
	})
	Attribute("tags", ArrayOf(String), "Tags for filtering/searching images", func() {
		Example([]string{"development", "vscode"})
	})
	Attribute("default_port", Int, "Default container port", func() {
		Example(8080)
	})
	Attribute("default_path", String, "Default URL path for connecting", func() {
		Example("/")
	})
	Attribute("icon", String, "Icon identifier", func() {
		Example("code")
	})
	Attribute("default_args", ArrayOf(String), "Default command-line args", func() {
		Example([]string{"--bind-addr", "0.0.0.0:8080"})
	})
	Attribute("default_env", ArrayOf(ImageEnvVar), "Default environment variables", func() {
		Example([]map[string]interface{}{{"name": "PASSWORD", "value": "changeme"}})
	})
	Attribute("privileged", Boolean, "Run container in privileged mode", func() {
		Default(false)
		Example(false)
	})
	Attribute("homepage_url", String, "Project homepage or documentation URL", func() {
		Example("https://github.com/coder/code-server")
	})
	Attribute("source_url", String, "Source code repository URL", func() {
		Example("https://github.com/coder/code-server")
	})
	Attribute("image_homepage_url", String, "Container image registry page (e.g. Docker Hub)", func() {
		Example("https://hub.docker.com/r/codercom/code-server")
	})
	Attribute("default_user", String, "Default user for this image", func() {
		Example("coder")
	})
	Attribute("default_password", String, "Known default password for DefaultUser. Only set when the image has a known default password; leave unset when the guest uses no password", func() {
		Example("changeme")
	})
	Attribute("default_cloud_init", Boolean, "Set to true when the image has cloud-init baked in, allowing user-data (e.g. a user/password) to be seeded into the guest at first boot", func() {
		Example(false)
	})
	Attribute("default_user_data", String, "Reserved user-data for the guest (cloud-init). Empty by default; later used to seed first-boot configuration when cloud-init is supported. Not yet consumed", func() {
		Example("")
	})
	Attribute("default_homedir", String, "Default home directory for the default user", func() {
		Example("/home/coder")
	})
	Attribute("default_shell", String, "Default shell for exec/console sessions (e.g. /bin/bash)", func() {
		Example("/bin/bash")
	})
	Attribute("links", ArrayOf(ImageLink), "Additional relevant URLs for this image", func() {
		Example([]map[string]interface{}{{"title": "GitHub", "url": "https://github.com/coder/code-server"}, {"title": "Docker Hub", "url": "https://hub.docker.com/r/codercom/code-server"}})
	})
	Attribute("default_credentials", ImageCredentials, "Default login credentials for this image")
	Attribute("proxy_config", ImageProxyConfig, "Proxy behavior configuration")
	Attribute("remote_desktop", ImageRemoteDesktop, "Remote desktop agent configuration (Tier 1)")
	Attribute("default_uid", Int64, "UID that the main container runs as (sets runAsUser and fsGroup)", func() {
		Example(1000)
	})
	Attribute("default_shared_memory", Boolean, "Automatically mount /dev/shm as emptyDir with medium=Memory (required for Selkies streaming, Chrome, ML frameworks)", func() {
		Example(false)
	})
	Attribute("workspace_types", ArrayOf(String), "Workspace types this image supports (container, vm, scratch). Empty means container-only", func() {
		Example([]string{"container"})
	})
	Attribute("vm_profile", String, "Controller-supported VM guest profile", func() { Enum("windows11-amd64-v1") })
	Attribute("persistent_root_disk", Boolean, "Import a per-workspace persistent root disk")
	Attribute("persistent_root_disk_size", String, "Persistent root capacity")
	Attribute("memory_limit", String, "Guest memory default")
	Attribute("memory_request", String, "Guest memory request default")
	Required("name", "image", "default_port")
})

var CreateSshKeyPayload = Type("CreateSshKeyPayload", func() {
	Description("Payload for storing a user's SSH public key")
	Attribute("name", String, "Resource name for the SshKey CR", func() {
		Pattern(`^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$`)
		MaxLength(63)
		Example("laptop-2025")
	})
	Attribute("namespace", String, "Target namespace (defaults to the user's personal namespace)", func() {
		Example("chris-at-fordham-id-au")
	})
	Attribute("key_name", String, "Human-friendly label for the key", func() {
		Example("Laptop 2025")
	})
	Attribute("public_key", String, "SSH public key line (e.g. ssh-ed25519 AAAA... user@host)", func() {
		Example("ssh-ed25519 AAAA... user@host")
	})
	Required("name", "public_key")
})

var CreateVolumePayload = Type("CreateVolumePayload", func() {
	Description("Payload for creating a new PVC")
	Attribute("type", String, "Volume type: container PVC or reusable CDI blank VM disk", func() {
		Enum("pvc", "vm-disk")
		Default("pvc")
	})
	Attribute("name", String, "PVC name", func() {
		Pattern(`^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$`)
		MaxLength(63)
		Example("my-data")
	})
	Attribute("namespace", String, "Target namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("size", String, "Storage size", func() {
		Default("5Gi")
		Example("10Gi")
	})
	Attribute("storage_class", String, "Storage class name", func() {
		Example("standard")
	})
	Attribute("access_mode", String, "Access mode", func() {
		Default("ReadWriteOnce")
		Enum("ReadWriteOnce", "ReadWriteMany", "ReadOnlyMany")
		Example("ReadWriteOnce")
	})
	Required("name", "size")
})

var CreateWorkspacePayload = Type("CreateWorkspacePayload", func() {
	Description("Payload for creating a new workspace")
	Attribute("name", String, "Workspace name", func() {
		Pattern(`^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$`)
		MaxLength(63)
		Example("my-workspace")
	})
	Attribute("namespace", String, "Target namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("type", String, "Workspace type: 'container' (default, runs as a StatefulSet), 'vm' (KubeVirt VirtualMachine booting a containerDisk image), or 'scratch' (plain Deployment)", func() {
		Enum("container", "vm", "scratch")
		Default("container")
		Example("container")
	})
	Attribute("container", WorkspaceContainer, "Main container spec")
	Attribute("vm_options", VMOptions, "Windows private root import settings")
	Attribute("volume_mounts", ArrayOf(VolumeMount), "Volumes to mount", func() {
		Example([]map[string]interface{}{{"name": "my-workspace-data", "mount_path": "/home/coder"}})
	})
	Attribute("env", ArrayOf(EnvVar), "Custom environment variables to inject into the workspace container", func() {
		Example([]map[string]interface{}{{"name": "PASSWORD", "value": "changeme"}})
	})
	Attribute("tolerations", ArrayOf(Toleration), "Pod tolerations for scheduling", func() {
		Example([]map[string]interface{}{{"key": "nvidia.com/gpu", "operator": "Equal", "value": "true", "effect": "NoSchedule"}})
	})
	Attribute("node_selector", MapOf(String, String), "Node selector labels for scheduling", func() {
		Example(map[string]string{"nvidia.com/gpu": "true"})
	})
	Attribute("shared_memory", Boolean, "Mount /dev/shm as an emptyDir with medium=Memory (required for Chrome, ML frameworks)", func() {
		Default(false)
		Example(true)
	})
	Attribute("image_pull_policy", String, "Image pull policy for the workspace container (Always, IfNotPresent, Never)", func() {
		Enum("Always", "IfNotPresent", "Never")
		Default("IfNotPresent")
		Example("IfNotPresent")
	})
	Required("name", "container")
})

var DisplayCapabilityResult = ResultType("application/vnd.display-capability+json", func() {
	Description("Capability advertisement for a workspace's shared display session. Absence of this resource, or enabled=false, means the workspace uses the legacy exclusive display mode")
	Attributes(func() {
		Attribute("enabled", Boolean, "Whether shared display sessions are available for this workspace", func() {
			Example(false)
		})
		Attribute("protocol", Int, "Display protocol/API revision", func() {
			Example(1)
		})
		Attribute("transports", ArrayOf(String), "Supported display transports", func() {
			Example([]string{"rfb", "tier1"})
		})
		Attribute("max_participants", Int, "Maximum simultaneous participants (controller + observers)", func() {
			Example(8)
		})
		Attribute("max_width", Int, "Maximum advertised guest framebuffer width", func() {
			Example(4096)
		})
		Attribute("max_height", Int, "Maximum advertised guest framebuffer height", func() {
			Example(2160)
		})
		Attribute("handshake_timeout_ms", Int, "Display stream handshake timeout in milliseconds", func() {
			Example(10000)
		})
		Attribute("participant_ttl_ms", Int, "Idle membership lifetime in milliseconds", func() {
			Example(900000)
		})
		Attribute("participants", Int, "Current participant count", func() {
			Example(2)
		})
		Attribute("controller_present", Boolean, "Whether a controller is currently attached", func() {
			Example(true)
		})
	})
	Required("enabled", "protocol")
})

var DisplayControlPayload = Type("DisplayControlPayload", func() {
	Description("Payload for a control transition (acquire, release or transfer)")
	Attribute("namespace", String, "Workspace namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("name", String, "Workspace name", func() {
		Example("my-workspace")
	})
	Attribute("participant_id", String, "Participant performing the transition. Release requires the current controller; acquire may be any participant; transfer requires the current controller", func() {
		Example("97f8c4b7a2")
	})
	Attribute("force", Boolean, "Explicit human consent to take or transfer control, demoting the current controller to observer. There is no silent takeover without this", func() {
		Default(false)
		Example(true)
	})
	Attribute("to", String, "Target observer participant identifier for a transfer", func() {
		Example("3a2d5f8c7f")
	})
	Required("name", "participant_id")
})

var DisplayStatusResult = ResultType("application/vnd.display-status+json", func() {
	Description("Live membership and control state of a workspace's shared display session")
	Attributes(func() {
		Attribute("enabled", Boolean, "Whether shared display sessions are available for this workspace", func() {
			Example(false)
		})
		Attribute("protocol", Int, "Display protocol/API revision", func() {
			Example(1)
		})
		Attribute("epoch", String, "Capture/broker generation. Changes when a new capture owner is elected", func() {
			Example("8f2ac64d91")
		})
		Attribute("controller", Participant, "Current controller, if any")
		Attribute("observers", ArrayOf(Participant), "Current observers")
		Attribute("participants", Int, "Total participant count (controller + observers)", func() {
			Example(3)
		})
	})
	Required("enabled", "protocol", "epoch", "participants")
})

var EnvVar = Type("EnvVar", func() {
	Description("Custom environment variable for a workspace")
	Attribute("name", String, "Environment variable name", func() {
		Example("MY_VAR")
	})
	Attribute("value", String, "Environment variable value", func() {
		Example("my-value")
	})
	Required("name", "value")
})

var ExecutionCommandResult = ResultType("application/vnd.execution-command+json", func() {
	Description("Synchronous outcome of one pilot command execution")
	Attributes(func() {
		Attribute("execution_id", String, "Execution identifier", func() { Example("exec_9f82") })
		Attribute("recording_id", String, "Recording identifier", func() { Example("rec_9f82") })
		Attribute("namespace", String, func() { Example("team-a") })
		Attribute("workspace_name", String, func() { Example("vm-1") })
		Attribute("workspace_uid", String, func() { Example("abc123") })
		Attribute("admission_time", String, "RFC3339 timestamp", func() { Format(FormatDateTime); Example("2026-10-17T00:00:00Z") })
		Attribute("mode", String, "Storage mode: ephemeral|external|bundled", func() { Enum("ephemeral", "external", "bundled"); Example("ephemeral") })
		Attribute("durability", String, "none|durable", func() { Enum("none", "durable"); Example("none") })
		Attribute("outcome", String, "Final command outcome", func() {
			Enum("succeeded", "failed", "timed_out", "unknown")
			Example("succeeded")
		})
		Attribute("state", String, "Final lifecycle state", func() {
			Enum("succeeded", "failed", "cancelled", "timed_out", "revoked", "unknown", "recording_lost")
			Example("succeeded")
		})
		Attribute("exit_code", Int, "Guest process exit code when known", func() { Example(0) })
		Attribute("stdout", Bytes, "Standard output, truncated to the pilot output bound")
		Attribute("stderr", Bytes, "Standard error, truncated to the pilot output bound")
		Attribute("truncated", Boolean, "Output was truncated at the 16 KiB bound", func() { Example(false) })
		Attribute("duration_ms", UInt64, "Guest-measured duration in milliseconds", func() { Example(120) })
		Attribute("denial", String, "Runner denial or transport-loss note", func() { Example("transport lost; do not rerun") })
	})
	Required("execution_id", "recording_id", "namespace", "workspace_name", "outcome", "state")
})

var ExecutionGrantPayload = Type("ExecutionGrantPayload", func() {
	Description("Signed, short-lived grant used to admit an execution request (placeholder)")
	Attribute("grant", String, "Opaque, versioned, guest-verified grant token", func() {
		MinLength(10)
		Example("eyJ2IjoiMS4wIn0....")
	})
	Attribute("os_identity", String, "Target OS identity (e.g. 'root', 'SYSTEM')", func() {
		Example("root")
	})
	Required("grant")
})

var ExecutionRecordResult = ResultType("application/vnd.execution-record+json", func() {
	Description("Execution admission record and last known outcome")
	Attributes(func() {
		Attribute("execution_id", String, "Execution identifier", func() { Example("exec_9f82") })
		Attribute("actor_id", String, "Actor identifier", func() { Example("user@example.com") })
		Attribute("operation", String, "command|script|shell", func() { Enum("command", "script", "shell"); Example("shell") })
		Attribute("namespace", String, func() { Example("team-a") })
		Attribute("workspace_name", String, func() { Example("vm-1") })
		Attribute("workspace_uid", String, func() { Example("abc123") })
		Attribute("workspace_generation", Int64, func() { Example(3) })
		Attribute("grant_version", String, func() { Example("1.0") })
		Attribute("os_identity", String, func() { Example("root") })
		Attribute("elevated", Boolean, func() { Example(false) })
		Attribute("recording_id", String, func() { Example("rec_9f82") })
		Attribute("mode", String, "Storage mode: ephemeral|external|bundled", func() { Enum("ephemeral", "external", "bundled"); Example("ephemeral") })
		Attribute("durability", String, "none|durable", func() { Enum("none", "durable"); Example("none") })
		Attribute("admitted", Boolean, func() { Example(true) })
		Attribute("admission_time", String, "RFC3339 timestamp", func() { Format(FormatDateTime); Example("2026-10-17T00:00:00Z") })
		Attribute("deny_reason", String, func() { Example("") })
		Attribute("state", String, "lifecycle state", func() {
			Enum("admitted", "running", "succeeded", "failed", "cancelled", "timed_out", "revoked", "unknown", "recording_lost")
			Example("succeeded")
		})
		Attribute("start_time", String, "RFC3339 timestamp", func() { Format(FormatDateTime) })
		Attribute("end_time", String, "RFC3339 timestamp", func() { Format(FormatDateTime) })
		Attribute("exit_code", Int, func() { Example(0) })
		Attribute("termination", String, func() { Example("graceful") })
		Attribute("recording_lost", Boolean, func() { Example(false) })
	})
	Required("execution_id", "operation", "namespace", "workspace_name", "recording_id", "mode", "durability", "admitted", "admission_time")
})

var ExecutionRecordingChunk = Type("ExecutionRecordingChunk", func() {
	Description("Verified, decrypted recording chunk; sensitive playback content")
	Attribute("index", UInt64, "Chunk index starting at 0", func() { Example(0) })
	Attribute("data", Bytes, "Base64-encoded plaintext recording data")
	Required("index", "data")
})

var ExecutionRecordingManifest = Type("ExecutionRecordingManifest", func() {
	Attribute("recording_id", String)
	Attribute("chunks", UInt64)
	Attribute("plaintext_bytes", Int64)
	Attribute("verified", Boolean)
	Required("recording_id", "chunks", "plaintext_bytes", "verified")
})

var ExecutionStatusResult = ResultType("application/vnd.execution-status+json", func() {
	Description("Execution management status")
	Attributes(func() {
		Attribute("enabled", Boolean, "Whether VM execution is enabled by policy", func() { Example(false) })
		Attribute("allow_elevated", Boolean, "Whether elevated execution is allowed by policy", func() { Example(false) })
		Attribute("storage_mode", String, "Storage mode: disabled|ephemeral|external|bundled", func() { Enum("disabled", "ephemeral", "external", "bundled"); Example("disabled") })
		Attribute("durable", Boolean, "Metadata and recordings are durable (not ephemeral)", func() { Example(false) })
		Attribute("storage_available", Boolean, "Store is Ready and can admit work", func() { Example(false) })
		Attribute("issuer_ready", Boolean, "Opt-in management issuer prerequisites and initial bootstrap sync are ready; not a guest execution capability", func() { Example(false) })
	})
	Required("enabled", "allow_elevated", "storage_mode", "durable", "storage_available", "issuer_ready")
})

var ImageCredentials = Type("ImageCredentials", func() {
	Description("Default login credentials for a workspace image")
	Attribute("username", String, "Default username", func() {
		Example("coder")
	})
	Attribute("password", String, "Default password", func() {
		Example("changeme")
	})
})

var ImageEnvVar = Type("ImageEnvVar", func() {
	Description("Environment variable with optional placeholder support")
	Attribute("name", String, "Name of the environment variable", func() {
		Example("PASSWORD")
	})
	Attribute("value", String, "Value (supports {{namespace}} and {{name}} placeholders)", func() {
		Example("changeme")
	})
	Required("name", "value")
})

var ImageLink = Type("ImageLink", func() {
	Description("A named URL link for an image")
	Attribute("title", String, "Display label for the link", func() {
		Example("GitHub")
	})
	Attribute("url", String, "Link target URL", func() {
		Example("https://github.com/coder/code-server")
	})
	Required("title", "url")
})

var ImageProxyConfig = Type("ImageProxyConfig", func() {
	Description("Proxy configuration hints for a workspace image")
	Attribute("needs_noop_sw", Boolean, "Serve a no-op ServiceWorker at /sw.js to prevent SW registration errors", func() {
		Default(false)
	})
	Attribute("websocket_paths", ArrayOf(String), "Paths that use WebSocket (informational, all paths support WS transparently)", func() {
		Example([]string{"/websockify"})
	})
	Attribute("rewrite_host_absolute_paths", Boolean, "Rewrite requests with absolute paths that escape the proxy prefix using Referer header", func() {
		Default(false)
	})
	Attribute("custom_request_headers", MapOf(String, String), "Additional headers to inject into proxied requests", func() {
		Example(map[string]string{"x-tenant": "workspaces"})
	})
	Attribute("inject_base_tag", Boolean, "Inject a <base> tag into HTML responses to fix relative path resolution", func() {
		Default(false)
	})
	Attribute("tls_insecure", Boolean, "Connect to backend over HTTPS with skip-verify (for self-signed certs)", func() {
		Default(false)
	})
	Attribute("preserve_path_prefix", Boolean, "Forward the full proxy path (including /proxy/{ns}/{name}) to the pod instead of stripping it. Required for apps configured with a base URL matching the proxy prefix.", func() {
		Default(false)
	})
})

var ImageRemoteDesktop = Type("ImageRemoteDesktop", func() {
	Description("In-guest remote desktop agent configuration")
	Attribute("protocol", String, "Protocol name: \"selkies\" (Linux in-guest agent) or \"agent\" (cross-platform kw-agent)", func() {
		Enum("selkies", "agent")
	})
	Attribute("port", Int, "Guest port the agent listens on", func() {
		Example(8080)
	})
	Attribute("path", String, "Path relative to the agent's base URL", func() {
		Default("/")
		Example("/")
	})
	Required("protocol", "port")
})

var ImageResult = ResultType("application/vnd.image+json", func() {
	Description("An available workspace image")
	Attributes(func() {
		Attribute("cr_name", String, "Kubernetes resource name (metadata.name)", func() {
			Example("code-server")
		})
		Attribute("name", String, "Display name", func() {
			Example("Code Server (VS Code)")
		})
		Attribute("image", String, "Full image reference", func() {
			Example("codercom/code-server:latest")
		})
		Attribute("description", String, "Description of the image", func() {
			Example("Code editor in the browser")
		})
		Attribute("category", String, "Category for grouping (e.g. Desktop, IDE, Tool, Game)", func() {
			Example("IDE")
		})
		Attribute("tags", ArrayOf(String), "Tags for filtering/searching images", func() {
			Example([]string{"development", "vscode"})
		})
		Attribute("default_port", Int, "Default container port", func() {
			Example(8080)
		})
		Attribute("default_path", String, "Default URL path for connecting (e.g. /vnc.html?resize=remote)", func() {
			Example("/")
		})
		Attribute("proxy_config", ImageProxyConfig, "Proxy behavior configuration for this image")
		Attribute("icon", String, "Icon identifier", func() {
			Example("code")
		})
		Attribute("default_args", ArrayOf(String), "Default command-line args injected at workspace creation", func() {
			Example([]string{"--bind-addr", "0.0.0.0:8080"})
		})
		Attribute("default_env", ArrayOf(ImageEnvVar), "Default environment variables injected at workspace creation", func() {
			Example([]map[string]interface{}{{"name": "PASSWORD", "value": "changeme"}})
		})
		Attribute("default_uid", Int64, "UID that the main container runs as (sets runAsUser and fsGroup)", func() {
			Example(1000)
		})
		Attribute("default_shared_memory", Boolean, "Automatically mount /dev/shm as emptyDir with medium=Memory (required for Selkies streaming, Chrome, ML frameworks)", func() {
			Example(false)
		})
		Attribute("privileged", Boolean, "Run container in privileged mode", func() {
			Example(false)
		})
		Attribute("homepage_url", String, "Project homepage or documentation URL", func() {
			Example("https://github.com/coder/code-server")
		})
		Attribute("source_url", String, "Source code repository URL", func() {
			Example("https://github.com/coder/code-server")
		})
		Attribute("image_homepage_url", String, "Container image registry page (e.g. Docker Hub)", func() {
			Example("https://hub.docker.com/r/codercom/code-server")
		})
		Attribute("default_user", String, "Default user for this image", func() {
			Example("coder")
		})
		Attribute("default_password", String, "Known default password for DefaultUser. Only set when the image has a known default password; leave unset when the guest uses no password", func() {
			Example("changeme")
		})
		Attribute("default_cloud_init", Boolean, "Set to true when the image has cloud-init baked in, allowing user-data (e.g. a user/password) to be seeded into the guest at first boot", func() {
			Example(false)
		})
		Attribute("default_user_data", String, "Reserved user-data for the guest (cloud-init). Empty by default; later used to seed first-boot configuration when cloud-init is supported. Not yet consumed", func() {
			Example("")
		})
		Attribute("default_homedir", String, "Default home directory for the default user", func() {
			Example("/home/coder")
		})
		Attribute("default_shell", String, "Default shell for exec/console sessions (e.g. /bin/bash)", func() {
			Example("/bin/bash")
		})
		Attribute("links", ArrayOf(ImageLink), "Additional relevant URLs for this image", func() {
			Example([]map[string]interface{}{{"title": "GitHub", "url": "https://github.com/coder/code-server"}, {"title": "Docker Hub", "url": "https://hub.docker.com/r/codercom/code-server"}})
		})
		Attribute("default_credentials", ImageCredentials, "Default login credentials for this image")
		Attribute("remote_desktop", ImageRemoteDesktop, "Remote desktop agent configuration (Tier 1)")
		Attribute("workspace_types", ArrayOf(String), "Workspace types this image supports (container, vm, scratch). Empty means container-only", func() {
			Example([]string{"container"})
		})
		Attribute("vm_profile", String, "Controller-supported guest profile")
		Attribute("persistent_root_disk", Boolean)
		Attribute("persistent_root_disk_size", String)
		Attribute("memory_limit", String)
		Attribute("memory_request", String)
	})
	Required("cr_name", "name", "image", "default_port")
})

var JoinDisplayPayload = Type("JoinDisplayPayload", func() {
	Description("Payload for joining a workspace's shared display session")
	Attribute("namespace", String, "Workspace namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("name", String, "Workspace name", func() {
		Example("my-workspace")
	})
	Attribute("role", String, "Initial role. Defaults to observer", func() {
		Default("observer")
		Enum("observer", "controller")
	})
	Required("name")
})

var JoinResult = ResultType("application/vnd.display-join+json", func() {
	Description("Result of joining a shared display session")
	Attributes(func() {
		Attribute("participant", Participant, "The joined participant record")
		Attribute("capability", DisplayCapabilityResult, "Current capability state, including the live participant count")
	})
	Required("participant")
})

var LeaveDisplayPayload = Type("LeaveDisplayPayload", func() {
	Description("Payload for leaving a workspace's shared display session")
	Attribute("namespace", String, "Workspace namespace", func() {
		Default("workspaces")
		Example("workspaces")
	})
	Attribute("name", String, "Workspace name", func() {
		Example("my-workspace")
	})
	Attribute("participant_id", String, "Participant identifier to remove", func() {
		Example("97f8c4b7a2")
	})
	Required("name", "participant_id")
})

var NamespaceResult = ResultType("application/vnd.namespace+json", func() {
	Description("A Kubernetes namespace")
	Attributes(func() {
		Attribute("name", String, "Namespace name", func() {
			Example("workspaces")
		})
		Attribute("phase", String, "Namespace phase", func() {
			Example("Active")
		})
		Attribute("created_at", String, "Creation timestamp", func() {
			Example("2025-01-02T15:04:05Z")
		})
	})
	Required("name", "phase")
})

var Participant = Type("Participant", func() {
	Description("A participant in a shared display session")
	Attribute("id", String, "Opaque server-side participant identifier. A capability, not a credential; never sent to the guest or logged", func() {
		Example("97f8c4b7a2")
	})
	Attribute("role", String, "Current role: observer (view-only) or controller. Server-enforced; a client-side viewOnly flag is not an authorization boundary", func() {
		Enum("observer", "controller")
		Example("observer")
	})
	Attribute("connected", Boolean, "Whether the participant is attached to a display stream", func() {
		Example(false)
	})
	Attribute("joined_at", String, "RFC 3339 timestamp when the participant joined", func() {
		Example("2026-09-19T15:04:05Z")
	})
	Required("id", "role", "connected", "joined_at")
})

var SshKeyResult = ResultType("application/vnd.sshkey+json", func() {
	Description("A stored SSH public key")
	Attributes(func() {
		Attribute("name", String, "Resource name of the SshKey CR", func() {
			Example("laptop-2025")
		})
		Attribute("namespace", String, "Kubernetes namespace", func() {
			Example("chris-at-fordham-id-au")
		})
		Attribute("key_name", String, "Human-friendly label", func() {
			Example("Laptop 2025")
		})
		Attribute("public_key", String, "SSH public key line", func() {
			Example("ssh-rsa AAAAB3Nza... user@example.com")
		})
		Attribute("fingerprint", String, "SHA256 fingerprint of the key", func() {
			Example("SHA256:aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789")
		})
		Attribute("created_at", String, "Creation timestamp", func() {
			Example("2025-01-02T15:04:05Z")
		})
	})
	Required("name", "namespace", "public_key")
})

var Toleration = Type("Toleration", func() {
	Description("Kubernetes pod toleration")
	Attribute("key", String, "Toleration key", func() {
		Example("nvidia.com/gpu")
	})
	Attribute("operator", String, "Operator: Exists or Equal", func() {
		Enum("Exists", "Equal")
		Default("Equal")
		Example("Equal")
	})
	Attribute("value", String, "Toleration value", func() {
		Example("true")
	})
	Attribute("effect", String, "Taint effect: NoSchedule, PreferNoSchedule, or NoExecute", func() {
		Enum("NoSchedule", "PreferNoSchedule", "NoExecute", "")
		Example("NoSchedule")
	})
	Required("key")
})

var VMOptions = Type("VMOptions", func() {
	Description("Namespaced Windows root import settings; credentials remain in Kubernetes Secrets")
	Attribute("import_secret_name", String, "Same-namespace CDI accessKeyId/secretKey Secret")
	Attribute("import_cert_config_map_name", String, "Same-namespace registry CA ConfigMap")
	Attribute("storage_class_name", String, "Persistent root StorageClass; empty uses cluster default")
	Attribute("root_disk_size", String, "Persistent Windows root capacity, at least 80Gi")
})

var VolumeMount = Type("VolumeMount", func() {
	Description("Container PVC mount, or reusable CDI VM data disk with an absolute guest mount path")
	Attribute("name", String, "Volume/PVC name", func() {
		Example("my-workspace-data")
	})
	Attribute("mount_path", String, "Mount path in container", func() {
		Example("/home/coder")
	})
	Attribute("type", String, "Volume mount type for VMs: 'disk' (virtio disk) or 'cdrom' (optical disc). Empty/omitted defaults to 'disk' for VM volume mounts.", func() {
		Enum("disk", "cdrom")
		Example("disk")
	})
	Attribute("bus", String, "Disk bus type for VMs when type is 'cdrom' (e.g. 'sata', 'ide'). Ignored for 'disk' type.", func() {
		Enum("sata", "ide", "virtio", "scsi", "usb")
		Example("sata")
	})
	Attribute("readonly", Boolean, "Whether the disk is read-only (for CD-ROMs, typically true).", func() {
		Default(true)
		Example(true)
	})
	Required("name", "mount_path")
})

var VolumeResult = ResultType("application/vnd.volume+json", func() {
	Description("A persistent volume claim")
	Attributes(func() {
		Attribute("type", String, "Volume type: pvc or vm-disk", func() {
			Enum("pvc", "vm-disk")
			Default("pvc")
		})
		Attribute("name", String, "PVC name", func() {
			Example("my-workspace-data")
		})
		Attribute("namespace", String, "Kubernetes namespace", func() {
			Example("workspaces")
		})
		Attribute("size", String, "Storage size", func() {
			Example("10Gi")
		})
		Attribute("storage_class", String, "Storage class", func() {
			Example("standard")
		})
		Attribute("access_mode", String, "Access mode", func() {
			Example("ReadWriteOnce")
		})
		Attribute("phase", String, "PVC phase (Bound, Pending, etc.)", func() {
			Example("Bound")
		})
		Attribute("created_at", String, "Creation timestamp", func() {
			Example("2025-01-02T15:04:05Z")
		})
		Attribute("labels", MapOf(String, String), "Kubernetes labels on the PVC", func() {
			Example(map[string]string{"managed-by": "kube-workspaces", "workspace": "my-workspace"})
		})
	})
	Required("name", "namespace", "size", "phase")
})

var WorkspaceCondition = Type("WorkspaceCondition", func() {
	Description("Condition of a workspace")
	Attribute("type", String, "Condition type", func() {
		Example("Ready")
	})
	Attribute("status", String, "Condition status", func() {
		Example("True")
	})
	Attribute("reason", String, "Brief reason", func() {
		Example("MinimumReplicasAvailable")
	})
	Attribute("message", String, "Detailed message", func() {
		Example("StatefulSet my-workspace is available")
	})
	Attribute("last_transition_time", String, "Last transition time", func() {
		Example("2025-01-02T15:04:05Z")
	})
})

var WorkspaceContainer = Type("WorkspaceContainer", func() {
	Description("Container specification for a workspace")
	Attribute("name", String, "Container name", func() {
		Example("code-server")
	})
	Attribute("image", String, "Container image", func() {
		Example("codercom/code-server:latest")
	})
	Attribute("port", Int, "Container port", func() {
		Default(8080)
		Example(8080)
	})
	Attribute("cpu_request", String, "CPU request", func() {
		Default("500m")
		Example("500m")
	})
	Attribute("memory_request", String, "Memory request", func() {
		Default("512Mi")
		Example("512Mi")
	})
	Attribute("cpu_limit", String, "CPU limit", func() {
		Default("2")
		Example("2")
	})
	Attribute("memory_limit", String, "Memory limit", func() {
		Default("2Gi")
		Example("2Gi")
	})
	Attribute("gpu_request", String, "GPU resource request count (e.g. \"1\")", func() {
		Example("1")
	})
	Attribute("gpu_vendor", String, "GPU vendor resource name (e.g. nvidia.com/gpu, amd.com/gpu)", func() {
		Default("nvidia.com/gpu")
		Example("nvidia.com/gpu")
	})
	Required("name", "image")
})

var WorkspaceInitialCredentials = Type("WorkspaceInitialCredentials", func() {
	Description("Per-workspace initial Windows account, visible only to namespace editors/admins")
	Attribute("username", String)
	Attribute("password", String)
	Attribute("cache_control", String)
	Required("username", "password", "cache_control")
})

var WorkspaceResult = ResultType("application/vnd.workspace+json", func() {
	Description("A workspace resource")
	Attributes(func() {
		Attribute("name", String, "Workspace name", func() {
			Example("my-workspace")
		})
		Attribute("namespace", String, "Kubernetes namespace", func() {
			Example("workspaces")
		})
		Attribute("type", String, "Workspace type: container, vm, or scratch", func() {
			Enum("container", "vm", "scratch")
			Default("container")
			Example("container")
		})
		Attribute("image", String, "Container image", func() {
			Example("codercom/code-server:latest")
		})
		Attribute("port", Int, "Container port", func() {
			Example(8080)
		})
		Attribute("cpu_request", String, "CPU request", func() {
			Example("500m")
		})
		Attribute("memory_request", String, "Memory request", func() {
			Example("512Mi")
		})
		Attribute("cpu_limit", String, "CPU limit", func() {
			Example("1")
		})
		Attribute("memory_limit", String, "Memory limit", func() {
			Example("2Gi")
		})
		Attribute("ready_replicas", Int, "Number of ready replicas", func() {
			Example(1)
		})
		Attribute("container_state", ContainerState, "Container state")
		Attribute("conditions", ArrayOf(WorkspaceCondition), "Workspace conditions", func() {
			Example([]map[string]interface{}{{
				"type":                 "Ready",
				"status":               "True",
				"reason":               "MinimumReplicasAvailable",
				"message":              "StatefulSet my-workspace is available",
				"last_transition_time": "2025-01-02T15:04:05Z",
			}})
		})
		Attribute("stopped", Boolean, "Whether the workspace is stopped", func() {
			Example(false)
		})
		Attribute("created_at", String, "Creation timestamp", func() {
			Example("2025-01-02T15:04:05Z")
		})
		Attribute("volume_mounts", ArrayOf(VolumeMount), "Attached volumes", func() {
			Example([]map[string]interface{}{{"name": "my-workspace-data", "mount_path": "/home/coder"}})
		})
		Attribute("remote_desktop", ImageRemoteDesktop, "Remote desktop agent configuration (Tier 1)")
		Attribute("vm_profile", String, "Resolved guest profile; windows11-amd64-v1 uses display-only native provisioning")
		Attribute("provisioned", Boolean, "Windows native setup and bootstrap removal have completed")
	})
	Required("name", "namespace", "image", "type", "ready_replicas", "stopped")
})