types

type APIToken struct {
	ID              uuid.UUID  `json:"id"`
	Principal       string     `json:"principal"`
	Email           string     `json:"email,omitempty"`
	Role            string     `json:"role"`
	Groups          []string   `json:"groups,omitempty"`
	GroupsTruncated *bool      `json:"groups_truncated,omitempty"`
	Name            string     `json:"name"`
	CreatedAt       time.Time  `json:"created_at"`
	LastUsedAt      *time.Time `json:"last_used_at,omitempty"`
	RevokedAt       *time.Time `json:"revoked_at,omitempty"`
	Token           string     `json:"token,omitempty"` // plaintext, create response ONLY
}

type ActorType string

type AgentRun struct {
	ID        uuid.UUID `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	CreatedBy string    `json:"created_by"` // human principal (token `sub`)
	Agent     string    `json:"agent"`      // e.g. "claude-code", "codex-cli"
	Repo      string    `json:"repo"`       // e.g. "org/name"
	Task      string    `json:"task"`       // human task description
	// Title is the run's human NAME. Runs that share a title are grouped in the
	// console's run list. Empty for legacy rows and for system runs (scan,
	// harness login, workspace record/verify) — the console falls back to Task,
	// which is the only identity an untitled run has ever had.
	Title string `json:"title,omitempty"`
	// Description is optional free-text context: why this run exists. Never
	// interpreted by the control plane, only displayed.
	Description      string           `json:"description,omitempty"`
	PolicyID         *uuid.UUID       `json:"policy_id,omitempty"`
	ConfinementClass ConfinementClass `json:"confinement_class"`
	State            RunState         `json:"state"`
	SPIFFEID         string           `json:"spiffe_id"`     // spiffe://<trust-domain>/agent-run/<id>
	RunnerTarget     string           `json:"runner_target"` // "docker"
	SandboxRef       string           `json:"sandbox_ref,omitempty"`
	// Image is the RESOLVED sandbox image this run dispatched with (convention
	// image, devcontainer build, workspace-built, or BYOI-wrapped), persisted
	// for provenance. Written by a scoped update after image resolution; empty
	// for legacy rows and runs that never reached resolution.
	Image string `json:"image,omitempty"`
	// Interactive marks a run created for human-driven use: the sandbox is brought
	// up RUNNING but no agent task is exec'd and no completion watcher is started
	// (the human drives via `wardyn attach`). A non-interactive run execs the agent
	// with the task and is watched to completion. This is a first-class,
	// sandbox-determining choice — see internal/api dispatch.
	Interactive bool `json:"interactive"`
	// WorkspacePath is the primary host directory this run operates in (the first
	// local WorkspaceMount source resolved from its policy), denormalized here so
	// the control plane can DISCOURAGE — warn, never block — launching a second
	// independent agent against a host directory another active run already uses.
	// Empty for runs with no local host workspace (git-clone / ephemeral).
	WorkspacePath string `json:"workspace_path,omitempty"`
	// WorkspaceID, when set, marks this run as a governed SCAN run for that
	// onboarded workspace: the driver runs wardyn-scan after cloning instead of the
	// agent, and the scan-result endpoint persists the derived profile onto this
	// workspace from this TRUSTED linkage (not sandbox input). Nil for ordinary runs.
	WorkspaceID *uuid.UUID `json:"workspace_id,omitempty"`
	// WorkspaceIDs is the READ-ONLY denormalization of the onboarded workspaces
	// this run's RESOLVED policy spec referenced at create time
	// (referencedWorkspaces over spec.WorkspaceMounts + spec.WorkspaceRepos).
	// Set only by handleCreateRun (internal/api/runs.go); the four internal
	// step-run call sites (record/verify, scan, harness login, probe) leave it
	// nil. Distinct from WorkspaceID above, which stays the scan/verify/
	// record-only TRUSTED linkage a sandbox upload authorizes on: this column
	// grants nothing, is never sandbox input, and exists only to answer "which
	// workspace(s) does an `always` egress-approval decision persist to". Nil
	// for a run that references no onboarded workspace.
	WorkspaceIDs []uuid.UUID `json:"workspace_ids,omitempty"`
	// SourceID is the TRUSTED run→library-source linkage for a per-source scan
	// run (the three-tier retarget): the scan-facts upload authorizes on it the
	// way workspace runs authorize on WorkspaceID. Never set by user runs.
	SourceID *uuid.UUID `json:"source_id,omitempty"`
	// AutoStopAfterSec is the run's EFFECTIVE idle auto-stop cap, captured from the
	// resolved RunPolicySpec at creation (frozen for the run's life). The idle
	// reaper reads it from the run row so a run launched with an inline/default
	// policy — which has no stored policy_id to JOIN — is reaped like any other.
	// 0 = never auto-stop; <0 = explicitly never (interactive). See adapters.go.
	AutoStopAfterSec int `json:"auto_stop_after_sec,omitempty"`
	// AgentExecID is the docker exec id of the agent process for exec-based runs
	// (the default idle-container + `docker exec` path). Empty for exec-less /
	// main-process substrates (krun) and before Exec runs. Persisted so the crash
	// reconciler can observe AGENT liveness via ExecInspect across a wardynd
	// restart: for an idle-container run the container is `sleep infinity`, so
	// container liveness != agent liveness, and the exec id otherwise lived only in
	// the driver's in-memory map — lost on restart, stranding the run.
	AgentExecID string `json:"agent_exec_id,omitempty"`
	// FailureHint is an operator-facing one-line reason a run FAILED, stamped by
	// the dispatch/create failure paths (failAndRevoke). Precedent:
	// record.go RecordResult.FailureHint. Without it a run that dies BEFORE the
	// agent starts (an image that resolves control-plane-side but not on the
	// daemon, a lost sandbox ref, an opaque-LLM inspection refusal) is just a
	// reason-less FAILED badge — the real reason lived only in an audit row. Empty
	// for every run that did not fail this way (a clean FAILED-by-nonzero-exit
	// carries its exit code instead, and success/terminal-by-kill carry nothing).
	// Display-only; never interpreted by the control plane.
	FailureHint string `json:"failure_hint,omitempty"`
}

type ApprovalDecision struct {
	State     ApprovalState
	DecidedBy string
	Reason    string
	// Scope and ExpiresAt are meaningful only for an egress_domain approval;
	// every other kind leaves them at the zero value. See ApprovalScope.
	Scope     ApprovalScope
	ExpiresAt *time.Time
}

type ApprovalKind string

type ApprovalRequest struct {
	ID             uuid.UUID       `json:"id"`
	RunID          uuid.UUID       `json:"run_id"`
	GrantID        *uuid.UUID      `json:"grant_id,omitempty"`
	Kind           ApprovalKind    `json:"kind"`
	RequestedScope json.RawMessage `json:"requested_scope"`
	State          ApprovalState   `json:"state"`
	RequestedAt    time.Time       `json:"requested_at"`
	DecidedAt      *time.Time      `json:"decided_at,omitempty"`
	DecidedBy      string          `json:"decided_by,omitempty"`
	MintedJTI      string          `json:"minted_jti,omitempty"`
	Reason         string          `json:"reason,omitempty"`
	// DecisionScope is how far the human's decision reaches: once (one
	// connection), run (rest of this run — the default and the legacy meaning),
	// until (this run, until DecisionExpiresAt), or always (persisted onto the
	// workspace so future runs inherit it). Empty on a PENDING row — a decision
	// nobody has made yet has no scope — which is why the column is
	// NOT NULL DEFAULT ” rather than DEFAULT 'run'.
	//
	// Named decision_scope, NOT scope: RequestedScope above is the unrelated
	// host JSON, and it is part of the PENDING dedup unique index.
	DecisionScope ApprovalScope `json:"decision_scope,omitempty"`
	// DecisionExpiresAt is set only when DecisionScope is until. Nullable, so it
	// scans into a pointer the way DecidedAt does. NOT the same clock as the
	// EXPIRED state / approval.expire sweeper, which ages out stale PENDING
	// requests — this bounds a GRANT that was actually made.
	DecisionExpiresAt *time.Time `json:"decision_expires_at,omitempty"`
}

type ApprovalScope string

type ApprovalState string

type AuditEvent struct {
	ID        uuid.UUID       `json:"id"`
	Time      time.Time       `json:"time"`
	RunID     *uuid.UUID      `json:"run_id,omitempty"`
	ActorType ActorType       `json:"actor_type"`
	Actor     string          `json:"actor"`  // human sub, agent SPIFFE ID, or component name
	Action    string          `json:"action"` // dotted verb, e.g. "credential.mint", "egress.deny", "kernel.process.exec"
	Target    string          `json:"target,omitempty"`
	Outcome   string          `json:"outcome"` // "success" | "failure" | "denied"
	SourceIP  string          `json:"source_ip,omitempty"`
	Data      json.RawMessage `json:"data,omitempty"`

	// PrevHash/RowHash are the tamper-evidence chain (migration 0047):
	// RowHash = SHA-256(PrevHash || canonical serialization of the fields
	// above), hex, computed BY POSTGRES in the audit_events BEFORE INSERT
	// trigger — never by the caller, who therefore cannot choose them.
	//
	// They are populated on the WRITE path only (InsertAuditEvent fills them
	// from RETURNING), which is what carries the current head hash out to the
	// audit sinks so a SIEM can detect a later truncation. The paginated READ
	// paths deliberately do not select them, so both are empty on anything
	// served by GET /audit — hence omitempty. The chain is verified through
	// GET /api/v1/audit/chain/verify, not by reading rows back.
	PrevHash string `json:"prev_hash,omitempty"`
	RowHash  string `json:"row_hash,omitempty"`
}

type BaseImageEntry struct {
	ID   uuid.UUID `json:"id"`
	Kind string    `json:"kind"` // "registry" | "custom" | "byo"
	Name string    `json:"name"`
	// Image is the ref: the image itself (registry/byo) or the FROM (custom).
	Image string `json:"image"`
	// Steps are Dockerfile lines attached to a "custom" Image. NOT CURRENTLY
	// APPLIED at build time — see WorkspaceBaseImage.Steps's doc (workspace.go)
	// for why (host-side build RCE, outside every confinement tier). Stored so
	// the catalog row round-trips; never layered onto Image today.
	Steps     []string  `json:"steps,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type CapabilityEffect string

type CapabilityGrant struct {
	ID          uuid.UUID             `json:"id"`
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	Capability  string                `json:"capability"`
	Value       string                `json:"value"`
	Effect      CapabilityEffect      `json:"effect"`
	CreatedAt   time.Time             `json:"created_at"`
	CreatedBy   string                `json:"created_by,omitempty"`
}

type CapabilitySubjectType string

type ConfinementClass string

type CredentialGrant struct {
	ID        uuid.UUID `json:"id"`
	RunID     uuid.UUID `json:"run_id"`
	CreatedAt time.Time `json:"created_at"`
	Spec      GrantSpec `json:"spec"`
}

type DriveBackend string

type DriveKind string

type DriveMount struct {
	// DriveID is the user_drives row this mount came from. Labels and reclaim
	// sweeps group by it: an object name is per-PRINCIPAL, so it cannot answer
	// "every object this drive allocated" — the question an offboarding sweep
	// and a `kubectl get pvc -l` both ask.
	DriveID uuid.UUID    `json:"drive_id"`
	Backend DriveBackend `json:"backend"`
	// ObjectName is what the substrate is asked for: a Docker volume name, a
	// PVC name, or the absolute host path of this principal's subdirectory.
	// Derived once by the resolver (DriveObjectName) so no runner re-computes a
	// hash.
	ObjectName string `json:"object_name"`
	// HostRoot is THIS drive's own share root (UserDrive.HostRoot), carried on a
	// host_path mount so the driver can assert the bind stays inside the tree
	// this drive was authored against. Empty on every other backend, which has
	// no host tree at all.
	//
	// It does not replace the deployment's WARDYN_USER_DRIVE_HOST_ROOTS ceiling
	// and is not redundant with it. The ceiling is the OPERATOR's outer bound
	// over every drive at once, so on a deployment with two share drives it
	// cannot tell one drive's tree from the other's: a home replaced host-side
	// by a link to the same-named home under the OTHER drive's root is inside
	// the ceiling, is not a root, and still carries this principal's name. Only
	// the drive's own root refuses that — and only the ceiling stops an
	// admin-authored row from naming a tree the operator never allowed. The
	// driver asserts BOTH (runner.UserDriveHomeWithinItsRoot).
	HostRoot string `json:"host_root,omitempty"`
	// DriveName is the drive object's human name (UserDrive.Name), carried for
	// the AUDIT row alone: run.drive.mount's Target is "<drive>/<home>" on a
	// share, so the member reading their own run's rows learns which drive and
	// which directory without being handed the operator's absolute host path —
	// which stays in the payload's `object`, where an operator reads it.
	DriveName string `json:"drive_name,omitempty"`
	// StorageClass is the provisioner a managed k8s_pvc claim asks for; "" means
	// the cluster default, and it is meaningless on every other backend. Carried
	// here because a substrate never reads the database — the resolver hands it
	// everything a mount needs (UserDrive.StorageClass).
	StorageClass string `json:"storage_class,omitempty"`
	// HomeName is the per-user segment ObjectName was built from, carried for
	// labels and for the audit row an operator reads when reclaiming.
	HomeName string `json:"home_name"`
	// SubjectHash is the non-PII fingerprint of the principal this mount was
	// resolved for (types.DriveSubjectHash). It is DEFENCE IN DEPTH over the
	// managed-backend collision the write boundary already refuses: an object
	// name is per-HOME, so a stored row that predates that refusal can still
	// resolve two principals onto one volume, and the driver stamps this on the
	// object it creates so the second one is refused instead of adopted.
	//
	// A digest, never the claim: a Docker label is echoed by `docker volume
	// inspect` to anybody who can reach the daemon, so the subject itself must
	// not be written there.
	SubjectHash string
	// Target is the reserved in-container path (runner.DriveTarget). Carried
	// rather than assumed so a runner never hard-codes the string, and so the
	// reserved-target refusal and the mount agree by construction.
	Target      string             `json:"target"`
	ReadOnly    bool               `json:"read_only,omitempty"`
	SizeMiB     int                `json:"size_mib,omitempty"`
	Enforcement StorageEnforcement `json:"enforcement"`
}

type DriveReclaim string

type EgressRedirect struct {
	// From is the public/upstream URL or host being redirected away from.
	From string `json:"from"`
	// To is the corporate-internal URL or host every matching run's egress is
	// substituted to. For an Ecosystem row this is also the value emitted into
	// that ecosystem's config file (the old ArtifactOverride.BaseURL).
	To string `json:"to"`
	// TokenSecretRef optionally names a secret whose value is injected
	// proxy-side as a Bearer token for To's host (the sandbox never holds it).
	// Mutually exclusive with TokenIntegrationRef — validateSiteConfig rejects a
	// row that sets both, since they answer the same question two ways.
	TokenSecretRef string `json:"token_secret_ref,omitempty"`
	// TokenIntegrationRef optionally names an Integration (SiteConfig.
	// Integrations[i].ID) to take this redirect's token FROM, instead of naming
	// a bare secret in TokenSecretRef.
	//
	// This is the seam between the two surfaces, and it exists because a private
	// registry is genuinely both things: a SYSTEM you authenticate to, and
	// sometimes the DESTINATION a public endpoint is rerouted to. The rule that
	// keeps them from duplicating each other — the integration owns the system
	// and its credential; the redirect owns rerouting a public endpoint to it.
	// So a redirect points AT the integration rather than restating its secret.
	//
	// It carries more than the secret name: the integration's Header and Format
	// come with it, so a feed that authenticates with something other than
	// "Authorization: Bearer" finally can (the bare-secret path below is
	// hardcoded to that shape). A ref naming nothing, a disabled row, or one with
	// no header credential degrades to redirect-WITHOUT-token, exactly as a
	// dangling TokenSecretRef already does — a redirect that still reroutes is
	// more useful than a run that fails.
	TokenIntegrationRef string `json:"token_integration_ref,omitempty"`
	// Ecosystem, when set, is one of the six package-manager ecosystems
	// ("npm"|"pip"|"cargo"|"maven"|"go"|"nuget") this redirect ALSO emits a
	// per-tool config file for, in addition to the egress substitution and
	// token injection every redirect gets. Empty means NETWORK-ONLY: no config
	// file is emitted (see SiteConfig.EgressRedirects).
	Ecosystem string `json:"ecosystem,omitempty"`
}

type FirstUseMode string

type GovernanceAssignment struct {
	ID          uuid.UUID             `json:"id"`
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	ProfileID   uuid.UUID             `json:"profile_id"`
	Priority    int                   `json:"priority"`
	CreatedAt   time.Time             `json:"created_at"`
	CreatedBy   string                `json:"created_by,omitempty"`
}

type GovernanceLimits struct {
	// DenyTaskModeExec refuses task_mode=exec for a member under this profile.
	DenyTaskModeExec bool `json:"deny_task_mode_exec,omitempty"`
	// DenyInteractive refuses an interactive run for a member under this
	// profile. Evaluated against POST-COERCION interactivity by its enforcement
	// site: a request that simply OMITS the task coerces to interactive later in
	// validation, so a raw "did the caller ask for interactive" read is evaded
	// by leaving a field out.
	DenyInteractive bool `json:"deny_interactive,omitempty"`
	// MaxConcurrentRuns caps how many NON-TERMINAL runs a member under this
	// profile may hold at once. 0 is unlimited — the same zero-value rule the
	// two booleans follow, so limits authored before this field existed keep
	// meaning what they meant.
	MaxConcurrentRuns int `json:"max_concurrent_runs,omitempty"`
	// DenyUserDrive refuses a USER DRIVE mount for a member under this profile:
	// their run may not carry drive.enabled at all, whatever an admin has
	// allocated them.
	//
	// A DOOR, NOT A QUOTA, which is why it is a bool beside the other two
	// rather than a size beside MaxConcurrentRuns. A drive is a writable tree
	// that OUTLIVES the run — the one piece of state an agent can leave behind
	// — so "how big" is the wrong question for a ceiling to ask; "may this
	// principal persist anything at all" is the right one, and it is the same
	// shape as the two refusals above (403 with an authz.denied row, not a 422
	// quota answer).
	//
	// Zero means unrestricted, like every other field here: a profile written
	// before drives existed keeps meaning exactly what it meant, and a
	// deployment that never allocates a drive is unaffected either way.
	DenyUserDrive bool `json:"deny_user_drive,omitempty"`
}

type GovernanceProfile struct {
	ID        uuid.UUID        `json:"id"`
	Name      string           `json:"name"`
	Ceiling   RunPolicySpec    `json:"ceiling"`
	Limits    GovernanceLimits `json:"limits"`
	CreatedAt time.Time        `json:"created_at"`
	UpdatedAt time.Time        `json:"updated_at"`
	CreatedBy string           `json:"created_by,omitempty"`
}

type GrantKind string

type GrantSpec struct {
	Kind GrantKind `json:"kind"`
	// Scope is kind-specific: for github_token {"repos":[...],"permissions":{...}},
	// for api_key {"host":"...","header":"..."}, for git_pat
	// {"host":"...","secret_name":"...","username":"<optional>"} — the stored
	// secret_name's PAT value is returned to the git credential helper as the
	// password for host, with username resolved by convention (ADO=pat,
	// GitLab=oauth2) unless overridden — and for ssh_key
	// {"host":"...","key_secret_ref":"...","username":"<optional, default git>",
	// "known_hosts_secret_ref":"<optional>"} — the stored key_secret_ref's private
	// key VALUE is returned to agent-run, which writes it to a 0400 file for the
	// SSH-over-443 clone and wipes it after (see GrantSSHKey).
	Scope json.RawMessage `json:"scope"`
	// TTL of the minted credential. Max (and default) 1h.
	TTLSeconds int `json:"ttl_seconds,omitempty"`
	// RequiresApproval forces a human approval to mint (vs auto-mint on policy).
	RequiresApproval bool `json:"requires_approval"`
}

type HomeTemplate string

type Integration struct {
	// ID is an operator-chosen stable slug, unique within SiteConfig.Integrations
	// (this is a config sub-object inside the SiteConfig singleton, not its own
	// table, so there is no generated uuid — the operator names it, and
	// WorkspaceLLMCred.IntegrationRef / DefaultFor point at this ID).
	ID   string `json:"id"`
	Name string `json:"name"`
	// Kind is the ONE field that says what this connects to: a closed-set kind
	// (ClosedIntegrationKinds) with bespoke behavior, or any other slug — a
	// generic connection whose row carries its whole contract.
	Kind string `json:"kind"`
	// Disabled turns the integration off without deleting its configuration.
	Disabled bool `json:"disabled,omitempty"`
	// Secrets are the required secrets, each with its delivery. Refs/names only.
	Secrets []IntegrationSecret `json:"secrets,omitempty"`
	// Egress is WHERE THE SYSTEM LIVES: the host entries a run granted this
	// integration may reach. This is the reason a host is on a run's egress
	// allowlist, instead of being hand-listed in every workspace that needs it.
	// Entries use the policy allowlist's own syntax (proxy.ValidDomainEntry):
	// an exact host, a leading-"*." wildcard, either optionally ":port".
	//
	// A WILDCARD OPENS THE PATH BUT NEVER CARRIES THE CREDENTIAL: proxy-side
	// injection requires an EXACT allowlist entry (Policy.AllowedExactHost), so
	// a secret can never leak to a wildcard-matched host. An integration with a
	// proxy_header-delivered secret is therefore rejected at write time if any
	// of its egress entries is a wildcard or carries a port — the alternative
	// is a row that looks credentialed and silently isn't.
	Egress []string `json:"egress,omitempty"`
	// Config is non-secret, kind-validated configuration. Closed kinds accept
	// only their known keys (bedrock ⇒ region/model/auth_lane, github_app ⇒
	// app_id/installation_id/host, anthropic_subscription ⇒ lane — an unknown
	// key 400s by name at write); generic kinds take any string keys.
	Config map[string]any `json:"config,omitempty"`
	// Docs optionally points at whatever documents this system, so whoever
	// comes after the operator who added it can find out what it is.
	Docs string `json:"docs,omitempty"`
	// DisabledCapabilities lists capability names this integration does NOT
	// support, so callers don't need a hardcoded per-provider capability matrix.
	DisabledCapabilities []string `json:"disabled_capabilities,omitempty"`
	// DefaultFor lists what this integration is the operator-chosen default
	// for: "agent_runs" (a new run picks this absent an explicit choice) and/or
	// "wardyn_features" (Wardyn's own internal usage, e.g. scan/record runs).
	DefaultFor []string  `json:"default_for,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	// contains filtered or unexported fields
}

type IntegrationDelivery struct {
	Mode string `json:"mode"` // proxy_header | resident_file | resident_env
	// Header/Format apply to proxy_header: the HTTP field name the proxy adds,
	// and the value template it wraps the secret in (exactly one %s; empty
	// means the raw secret IS the value, i.e. "%s").
	Header string `json:"header,omitempty"`
	Format string `json:"format,omitempty"`
	// Path applies to resident_file: the in-sandbox path the secret lands at.
	Path string `json:"path,omitempty"`
	// Var applies to resident_env: the environment variable name.
	Var string `json:"var,omitempty"`
}

type IntegrationList []Integration

type IntegrationSecret struct {
	Role       string               `json:"role"`
	SecretName string               `json:"secret_name"`
	Delivery   *IntegrationDelivery `json:"delivery,omitempty"`
}

type InternalHost struct {
	// HostSuffix matches a request host by label suffix: HostSuffix itself, or
	// any host ending in "."+HostSuffix (never a substring/mid-label match).
	HostSuffix string `json:"host_suffix"`
	// CIDRs scopes the lift to these ranges only. Each must lie entirely inside
	// RFC1918, fc00::/7, or 100.64.0.0/10 (ipguard.Liftable) — never loopback/
	// link-local/metadata/multicast/NAT64. Empty means the lift applies to the
	// full Liftable set for a matching host.
	CIDRs []string `json:"cidrs,omitempty"`
}

type LLMInspectionSpec struct {
	// Mode is "off" (default), "alert" (scan + audit, forward unchanged), or
	// "block" (a qualifying finding refuses the request). "" == "off".
	Mode string `json:"mode"`
	// WorkspaceSecretNames are operator-declared secret NAMES, resolved against
	// the at-rest secret store — the field an operator/admin actually AUTHORS
	// (on a stored policy or an inline_policy). This is the storable form of the
	// detection corpus: a name is not sensitive the way a value is, so it may
	// freely appear in a stored policy row, a policy read, or a compose/profile
	// proposal returned to a caller. Resolved to WorkspaceSecretValues ONLY at
	// dispatch (resolveLLMInspectionSecrets, internal/api/runs_dispatch.go), in
	// memory, on the per-dispatch policy copy handed to the proxy sidecar.
	WorkspaceSecretNames []string `json:"workspace_secret_names,omitempty"`
	// WorkspaceSecretValues are the RESOLVED secret VALUES (e.g. the contents of
	// a mounted .env) the run must not leak into a prompt — the v1 detection
	// corpus the proxy sidecar actually matches against. NOT an authoring
	// field: validatePolicySpec refuses a non-empty value here on every policy
	// write (stored, inline, or WARDYN_DEFAULT_POLICY) — author
	// WorkspaceSecretNames instead. Populated ONLY by dispatch, in memory, on
	// the ephemeral copy of the spec sent to the proxy; every other copy (the
	// stored row, a policy read DTO, a compose/profile proposal, the
	// run.policy.effective audit event) carries names only, values redacted to
	// a count. NEVER logged. Values shorter than the masking floor are ignored.
	WorkspaceSecretValues []string `json:"workspace_secret_values,omitempty"`
	// DetectSecrets enables the known-secret detector (exact match against the
	// resolved WorkspaceSecretValues corpus). At least one Detect* must be true
	// when Mode != off.
	DetectSecrets bool `json:"detect_secrets,omitempty"`
	// DetectSecretPatterns enables the regex catalog of well-known secret FORMATS
	// (AWS/GitHub/Slack/Google keys, PEM private keys, JWTs, Stripe). Higher
	// precision than entropy but can false-positive on example/test keys in code.
	DetectSecretPatterns bool `json:"detect_secret_patterns,omitempty"`
	// DetectEntropy enables the Shannon-entropy detector (high FP in code; medium
	// severity so a strict block_min_severity can exclude it). Off by default.
	DetectEntropy bool `json:"detect_entropy,omitempty"`
	// DetectPII enables the regex/Luhn PII detector (best-effort, high false-
	// negative recall; a visibility signal, never a control). Off by default.
	DetectPII bool `json:"detect_pii,omitempty"`
	// DetectorSidecarURL, when set, adds an out-of-process detection sidecar
	// (e.g. a Presidio / Protect-AI LLM-Guard wrapper) the proxy POSTs each span
	// to. Trusted operator config (not agent-chosen). A sidecar error/timeout/non-200
	// is treated as a scanner error and respects on_scanner_error like any other:
	// fail-OPEN by default (the request still flows), fail-CLOSED (the request is
	// blocked in block mode) when on_scanner_error=block — so block mode with the
	// sidecar as the SOLE detector DOES guarantee a block on sidecar failure.
	DetectorSidecarURL string `json:"detector_sidecar_url,omitempty"`
	// ClassifiedMarkers are operator-defined literal markers (e.g. "INTERNAL ONLY",
	// "CONFIDENTIAL//NOFORN") whose presence in outbound content flags a
	// classified-content leak (the "proprietary content shouldn't leave" sense of
	// the walled garden). Case-insensitive substring match; category "classified".
	ClassifiedMarkers []string `json:"classified_markers,omitempty"`
	// ScanAttachments opts into decoding+scanning base64 image/document attachment
	// bytes in a prompt (off by default — binary, large, high-FP).
	ScanAttachments bool `json:"scan_attachments,omitempty"`
	// InspectForwardEgress extends inspection from the LLM routes to the GENERIC
	// plaintext-HTTP forward path, so a custom (non-LLM) HTTP connector's POST/PUT
	// body is scanned too. Off by default. (HTTPS connectors tunnel via opaque
	// CONNECT and remain uninspected unless MITM'd — see threatmodel §5.1a.)
	InspectForwardEgress bool `json:"inspect_forward_egress,omitempty"`
	// MaxScanBytes caps the size of a single extracted span scanned; 0 => a
	// built-in default. A larger span is skipped (fail-open) and recorded.
	MaxScanBytes int `json:"max_scan_bytes,omitempty"`
	// OnScannerError selects behavior when the scanner ERRORS (e.g. an
	// unparseable body): "pass" (default, fail-open) or "block".
	OnScannerError string `json:"on_scanner_error,omitempty"`
	// RequireInspectableLLM, when true, refuses to schedule a run whose resolved
	// LLM transport is opaque (subscription-OAuth/Bedrock CONNECT) and therefore
	// cannot be inspected — fail-closed, like MinConfinementClass. Default false
	// only WARNS (the common subscription user is not punished).
	RequireInspectableLLM bool `json:"require_inspectable_llm,omitempty"`
	// InterceptTLS opts the run into TLS-MITM of opaque CONNECT tunnels to known
	// LLM hosts (Anthropic/OpenAI), making the subscription-OAuth path inspectable.
	// The control plane provisions a per-run CA: the PRIVATE key goes only to the
	// proxy sidecar; the sandbox trusts only the CA's PUBLIC cert. Adds a CA trust
	// dependency inside the sandbox — see threatmodel §5.1a. Off by default.
	InterceptTLS bool `json:"intercept_tls,omitempty"`
	// BlockMinSeverity is the minimum finding severity that triggers a block in
	// "block" mode ("low"|"medium"|"high"|"critical"; "" => low).
	BlockMinSeverity string `json:"block_min_severity,omitempty"`
}

type ResolvedDrive struct {
	Drive UserDrive
	Grant UserDriveGrant
	Tier  CapabilitySubjectType
	// HomeName is the per-user segment: the subdirectory of a share, or the
	// suffix of a managed object's name.
	HomeName string
	// SubjectHash fingerprints the principal HomeName was derived FROM
	// (DriveSubjectHash), which the home itself cannot answer for: a managed
	// object's name carries the home and nothing else, so two principals whose
	// template collapses onto one home produce one object name and no way to
	// tell them apart. Carried here so the runner can stamp it on the object it
	// allocates and refuse one stamped for somebody else.
	SubjectHash string `json:"subject_hash,omitempty"`
	// ObjectName is what the runner asks the substrate for — a volume name, a
	// PVC name, or an absolute host path.
	ObjectName  string
	SizeMiB     int
	Writable    bool
	Enforcement StorageEnforcement
	// Paused is set when the grant that WON is disabled: Drive and Grant are
	// that row, the size and mode folds still ran, nothing is derived (no
	// HomeName, no ObjectName) and nothing may be mounted. A paused row wins
	// its tier rather than falling through to the wider row beneath it
	// (DESIGN §2.2), so an admin turning one off cannot silently hand that
	// member the everyone drive instead.
	Paused bool
}

type ResolvedInjection struct {
	Host      string `json:"host"`
	Header    string `json:"header"`
	Value     string `json:"value"`
	JTI       string `json:"jti"`
	ExpiresAt int64  `json:"expires_at,omitempty"`
}

type ResourceLimits struct {
	CPUMillis int `json:"cpu_millis,omitempty"` // milli-CPU; 2000 = 2 vCPU
	MemoryMiB int `json:"memory_mib,omitempty"` // hard memory cap in MiB
	PidsLimit int `json:"pids_limit,omitempty"` // max processes/threads (fork-bomb guard)
	DiskMiB   int `json:"disk_mib,omitempty"`   // writable storage cap in MiB (best-effort)
}

type RoleMapping struct {
	ID        uuid.UUID `json:"id"`
	Value     string    `json:"value"`
	Role      string    `json:"role"`
	CreatedAt time.Time `json:"created_at"`
	CreatedBy string    `json:"created_by,omitempty"`
}

type RunLayout struct {
	Preset    string            `json:"preset"`
	Layout    []RunLayoutWidget `json:"layout"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type RunLayoutWidget struct {
	Widget string `json:"widget"`
	X      int    `json:"x"`
	Y      int    `json:"y"`
	W      int    `json:"w"`
	H      int    `json:"h"`
}

type RunPolicy struct {
	ID        uuid.UUID     `json:"id"`
	Name      string        `json:"name"`
	CreatedAt time.Time     `json:"created_at"`
	UpdatedAt time.Time     `json:"updated_at"`
	Spec      RunPolicySpec `json:"spec"`
}

type RunPolicySpec struct {
	// AllowedDomains is the L2 egress allowlist (exact hosts or "*." wildcards).
	AllowedDomains []string `json:"allowed_domains"`
	// DeniedDomains always wins over AllowedDomains.
	DeniedDomains []string `json:"denied_domains,omitempty"`
	// AllowAllEgress switches L2 egress from default-deny (allowlist only) to
	// "allow all (deny-list only)" mode: when true the proxy allows ANY
	// non-denied PUBLIC host, and AllowedDomains may be empty. denied_domains
	// STILL wins. The SSRF/private-IP guard (VetHost/isBlockedIP) is unaffected
	// — allow-all is public hosts only; a host that resolves to a private/
	// loopback/link-local/metadata range is still unconditionally denied. And
	// credential injection STILL requires an EXACT allowlist entry (AllowedExactHost),
	// so allow-all never widens where a secret may be injected — a secret must
	// never leak to an arbitrary host. first_use_approval is inert under allow-all.
	AllowAllEgress bool `json:"allow_all_egress,omitempty"`
	// FirstUseApproval controls how an unknown domain is handled: always_deny
	// (hard-deny, no approval), deny_with_review (raise approval, deny now, retry
	// passes once approved), or wait_for_review (raise approval and hold the
	// connection until decided). Accepts the legacy boolean on the wire. Inert
	// under allow-all.
	FirstUseApproval FirstUseMode `json:"first_use_approval"`
	// FirstUseHoldSeconds bounds how long a wait_for_review connection is HELD
	// open awaiting a decision before the proxy refuses it. 0/absent keeps the
	// built-in 30s default (back-compat); a positive value overrides it. Only
	// wait_for_review holds; the other first-use modes never hold. See
	// internal/egress/proxy configureHold.
	FirstUseHoldSeconds int `json:"first_use_hold_seconds,omitempty"`
	// MaxHolds caps concurrent wait_for_review holds (one held goroutine per
	// held connection). 0/absent keeps the built-in 16 default; a positive value
	// overrides it. The (N+1)th concurrent held connection fails fast rather than
	// consuming an unbounded goroutine.
	MaxHolds int `json:"max_holds,omitempty"`
	// AllowedMethods optionally restricts HTTP methods (empty = all).
	AllowedMethods []string `json:"allowed_methods,omitempty"`
	// MinConfinementClass refuses to launch below this class.
	MinConfinementClass ConfinementClass `json:"min_confinement_class"`
	// EligibleGrants is the ceiling of credential scopes a run may request.
	EligibleGrants []GrantSpec `json:"eligible_grants,omitempty"`
	// AutoStopAfter stops idle sandboxes after this many seconds. 0 — which is
	// also what an ABSENT field coalesces to — means never reaped, identical to
	// an explicit negative (see internal/lifecycle: the reaper skips <= 0). A
	// negative value exists only to state never-reap intent explicitly.
	AutoStopAfterSec int `json:"auto_stop_after_sec,omitempty"`
	// WorkspaceMounts are OPERATOR/ADMIN-controlled host bind mounts injected
	// into the sandbox (e.g. a host repo at ~/work that edits persist to). They
	// are admin-gated: a mount may be authored on a stored policy (via the
	// admin-gated policy CRUD) OR INLINE on a create-run request by an admin /
	// SSO-gated human operator (createRunRequest.InlinePolicy) — both flow
	// through this same RunPolicySpec. A mount is NEVER chosen by the in-sandbox
	// agent: the agent-run entrypoint has no access to either authoring surface,
	// so a prompt-injected agent or a malicious in-sandbox actor can never pick
	// what host paths get mounted. validatePolicySpec runs runner.ValidateMount
	// (the same deny-list the docker driver enforces: absolute cleaned Source not
	// under a dangerous host path; Target under an allowed in-container prefix;
	// default read-only) so a bad mount is rejected at policy-write / inline-
	// validate time (HTTP 400) AND again defense-in-depth in the driver at
	// sandbox-create time.
	WorkspaceMounts []WorkspaceMount `json:"workspace_mounts,omitempty"`
	// WorkspaceRepos are additional git repos attached to a run, paralleling
	// WorkspaceMounts for git-cloned (rather than bind-mounted) sources — the
	// multi-workspace run model. Same admin/inline authoring
	// surface and trust boundary as WorkspaceMounts: never agent-chosen.
	// validatePolicySpec validates each set Target via runner.ValidateTarget and
	// enforces a unique-target invariant across ALL WorkspaceMounts +
	// WorkspaceRepos dests, so a clone can never land on a bind target (or
	// shadow another repo's checkout). Rejecting a repo whose Source is not an
	// ONBOARDED workspace is a later, security-critical wave — this
	// type only adds the structural shape.
	WorkspaceRepos []WorkspaceRepo `json:"workspace_repos,omitempty"`
	// LLMInspection optionally enables OUTBOUND content inspection at the proxy
	// for brokered LLM routes (the "inadvertent-leak guardrail"). Nil/omitted =>
	// OFF (no scanning) — the safe default, mirroring WorkspaceMount.ReadOnly's
	// pointer-means-unset idiom. It is a guardrail + visibility layer, NOT
	// exfiltration prevention (see internal/contentscan + threatmodel §5.1).
	LLMInspection *LLMInspectionSpec `json:"llm_inspection,omitempty"`
	// UIApps declares the in-sandbox loopback HTTP apps the UI gateway may relay
	// to a browser (a code editor, a dev server). OPERATOR-AUTHORED, the same
	// trust boundary as WorkspaceMounts: an app is a NAME, a loopback PORT and a
	// PATH — never a command string, so a policy can never choose what runs
	// inside the sandbox (the launcher is a convention,
	// /usr/local/bin/wardyn-ui-<name>). The gateway serves ONLY a declared port
	// and refuses anything else naming this field; `ssh -L` stays the
	// undeclared-port escape hatch. Empty (the default) = this run has no UI
	// apps, which is what every policy authored before this field said.
	UIApps []UIApp `json:"ui_apps,omitempty"`
	// Resources caps sandbox CPU/memory/PIDs/disk. Nil, or a zero field, means
	// "use the platform default": the dispatch path fills conservative defaults so
	// EVERY run is capped even when a policy sets nothing. These are the basic
	// multi-tenant safety controls that let a FLEET of independent agents coexist —
	// without them one runaway or prompt-injected agent can OOM-kill the host,
	// fork-bomb the host PID space, or fill host storage and take down sibling runs.
	Resources *ResourceLimits `json:"resources,omitempty"`
	// ToolRules narrows an autonomous run's tool use from a BINARY to a policy.
	//
	// `tool_approvals` alone has exactly two settings and no middle: `auto` runs
	// every tool with no gate at all, and `hold` routes EVERY gated call to a
	// human. On a real task the first is more autonomy than an operator wants and
	// the second is more interruptions than a human answers — which is how
	// approval fatigue starts, and an operator who tires of approving picks
	// `auto` for everything.
	//
	// A rule names a TOOL and an effect: allow it outright, hold it for a human,
	// or deny it outright. So "read freely, ask before shell, never fetch the
	// web" becomes expressible, and the human is asked only about the calls that
	// warrant asking.
	//
	// OPERATOR-AUTHORED and evaluated OUTSIDE the sandbox — proxy-side, on the
	// same brokered route the approval already travels — so a compromised agent
	// cannot rewrite its own rules. Empty (the default) preserves today's exact
	// behaviour: every gated call under `hold` goes to a human.
	//
	// It narrows; it never widens. A rule is consulted ONLY for a run that is
	// already in `hold`, so adding one cannot turn a supervised run autonomous —
	// the worst a bad rule can do is ask a human more often, or refuse a call the
	// agent wanted.
	ToolRules []ToolRule `json:"tool_rules,omitempty"`
	// GitPushAnyBranch turns OFF branch-namespace confinement for THIS run's
	// brokered GitHub pushes. By default the proxy git-broker forwards a push
	// only when every ref it updates lives under refs/heads/wardyn/<run-id>/
	// (ARCHITECTURE.md "Git egress"), so an agent cannot rewrite main. That is
	// the right default for an autonomous run and the wrong one for a sandbox
	// a HUMAN drives through an external tool (an IDE or agent workbench over
	// the SSH gateway) that names its own branches — the push is refused and
	// the tool cannot explain why.
	//
	// true = forward pushes to any branch the granted token may write. The
	// audit stream distinguishes the posture per push (rule_source
	// brokered:git:branch-ns-off) and the grant's own GitHub ruleset still
	// bounds what the token can touch (docs/POLICIES.md "Bound the token
	// itself"). Operator-authored, never agent-settable; false/absent keeps
	// today's behaviour exactly.
	//
	// ponytail: whole-namespace off, not a per-run allowed-prefix list — add a
	// prefix list when someone needs an external tool AND confinement at once.
	GitPushAnyBranch bool `json:"git_push_any_branch,omitempty"`
}

type RunState string

type SSHPublicKey struct {
	Fingerprint   string     `json:"fingerprint"`
	Principal     string     `json:"principal"`
	Name          string     `json:"name"`
	PublicKey     string     `json:"public_key"` // authorized_keys line; never a secret
	Role          string     `json:"role"`
	RoleCheckedAt *time.Time `json:"role_checked_at,omitempty"`
	CreatedAt     time.Time  `json:"created_at"`
}

type SiteConfig struct {
	// UpstreamProxySecretRef names a secret holding the corporate upstream proxy
	// URL (optionally with embedded user:pass), or "" when no upstream proxy is
	// configured. Mutually exclusive in PRACTICE with UpstreamProxyURL (either
	// may be set; UpstreamProxyURL wins when both are — see
	// resolveUpstreamProxyURL) but not rejected as a validation error, since an
	// operator migrating from one to the other may round-trip both briefly.
	UpstreamProxySecretRef string `json:"upstream_proxy_secret_ref,omitempty"`
	// UpstreamProxyURL is the corporate upstream proxy URL written IN THE CLEAR
	// (http only — see resolveUpstreamProxyURL). A proxy URL is topology, not a
	// credential, and forcing every operator through the write-only secret store
	// means a mistyped URL can never be read back to debug. It MUST NOT embed a
	// userinfo (user:pass@) — validateSiteConfig rejects that at write time with
	// a 400 telling the caller to use UpstreamProxySecretRef instead, which
	// exists precisely for a proxy that DOES need an embedded credential.
	UpstreamProxyURL string `json:"upstream_proxy_url,omitempty"`
	// UpstreamProxyNoProxy is the corporate upstream proxy's BYPASS list: the
	// destinations wardyn-proxy must dial DIRECTLY instead of CONNECTing through
	// the upstream. It is the operator-hop equivalent of the NO_PROXY every
	// sandbox already honours INSIDE itself, and it follows that convention's
	// spelling so nothing new has to be learned: each entry is either
	//
	//   - a HOST or DOMAIN SUFFIX ("vpce.amazonaws.com", ".corp.internal",
	//     "registry.corp.internal") matched by label suffix — the entry itself,
	//     or any host ending in "."+entry, never a mid-label substring; or
	//   - a CIDR ("100.64.0.0/10", "10.40.0.0/16") matched against a literal-IP
	//     destination.
	//
	// It exists because a corporate forward proxy will not CONNECT to an
	// internal address, so on a private-endpoint (PrivateLink) estate EVERY
	// private endpoint times out while the upstream takes every dial. WHAT IT
	// DOES NOT DO, and the reason it is safe: a bypassed dial falls through to
	// the proxy's own unconditional private/reserved-IP SSRF guard exactly as an
	// unproxied dial does, so bypassing a host does NOT make a private address
	// reachable — InternalHosts (above) is still the one and only lift, and the
	// two compose: the bypass routes the dial direct, InternalHosts lets that
	// address through. It also grants no policy allow; allowed_domains/
	// denied_domains decide reachability exactly as before.
	//
	// The NO_PROXY "*" wildcard is REFUSED at write time: "bypass everything" is
	// spelled by clearing upstream_proxy_url, and accepting it here would let one
	// character silently un-chain an estate's whole egress. Empty (the default)
	// => every forward dial keeps chaining through the upstream, byte-identical
	// to before this field existed.
	UpstreamProxyNoProxy []string `json:"upstream_proxy_no_proxy,omitempty"`
	// ArtifactOverrides maps an ecosystem ("npm"|"pip"|"cargo"|"maven"|"go"|
	// "nuget") to its corporate artifact-registry redirect.
	//
	// Deprecated: superseded by EgressRedirects, which generalizes this from
	// package registries to any outbound URL/host. Kept ONLY so the PUT
	// /site-config request decoder and `wardyn site-config apply` keep accepting
	// a document saved before this release — decodeStrict rejects unknown JSON
	// fields, so removing this field would turn every such legacy body into a
	// hard 400 instead of a fold. handlePutSiteConfig folds a non-empty value
	// into EgressRedirects (rejecting a body that sets both) and never persists
	// this field again; migration 0030 performs the same rewrite once, in place,
	// on the one already-stored document. Never populated by a read from
	// storage post-migration — treat a non-empty value outside the fold as
	// legacy request input only.
	ArtifactOverrides map[string]ArtifactOverride `json:"artifact_overrides,omitempty"`
	// EgressRedirects is the operator's outbound redirect list: FROM a public/
	// upstream URL or host, TO a corporate-internal replacement, generalizing
	// ArtifactOverride from package registries to any destination (a container
	// registry, a telemetry/SDK callback host, ...). Each entry is one of two
	// tiers, discriminated by Ecosystem:
	//
	//   - Ecosystem set (one of the ArtifactOverride closed set): FULL behavior,
	//     unchanged from the old ArtifactOverride — a per-tool config file
	//     (.npmrc/pip.conf/.cargo/config.toml/.m2/settings.xml/NuGet.Config/
	//     GOPROXY+GOSUMDB) via workspacescan.EmitArtifactConfig, PLUS egress
	//     substitution, PLUS token injection.
	//   - Ecosystem "" (NETWORK-ONLY): egress substitution (To's host allowed,
	//     From's host dropped) PLUS token injection for To's host, but NO config
	//     file — there is no ".npmrc equivalent" for an arbitrary host (a
	//     container registry, a telemetry endpoint, ...), and inventing one
	//     would be a lie about what Wardyn actually configures.
	EgressRedirects []EgressRedirect `json:"egress_redirects,omitempty"`
	// ScmHosts are the operator's default SCM hosts (e.g. "dev.azure.com",
	// "github.example.com") the SCM Provider step / egress bundling consult.
	ScmHosts []string `json:"scm_hosts,omitempty"`
	// Integrations are the operator-configured external connections (AI
	// providers, SCM hosts, generic connections) — the generalized replacement
	// UpstreamProxySecretRef/EgressRedirects are migrating toward. Both the
	// legacy fields and this one are read; nothing here removes the legacy
	// fields yet. IntegrationList folds pre-base-component rows forward at
	// decode and drops legacy artifact_mirror/host_proxy topology rows.
	Integrations IntegrationList `json:"integrations,omitempty"`
	// InternalHosts declares an internal hostname (an in-cluster service, a
	// corporate registry, the internal model gateway) the proxy's unconditional
	// private/reserved-IP SSRF guard would otherwise refuse regardless of
	// policy. Each entry LIFTS that guard for addresses matching its
	// host_suffix, scoped to its own CIDRs (or the full RFC1918/ULA/CGNAT set
	// when CIDRs is empty) — never loopback/link-local/metadata/unspecified/
	// multicast/NAT64, which stay denied unconditionally. The policy verdict
	// (allowed_domains/denied_domains) still has to allow the host separately —
	// this only lifts the SSRF builtin. Admin-only; validated at write time
	// (validateInternalHosts) so every declared CIDR lies inside
	// ipguard.Liftable. Empty (the default) => no lift, byte-identical to today.
	InternalHosts []InternalHost `json:"internal_hosts,omitempty"`
	// OnboardingCompletedAt records when an operator finished (or deliberately
	// left) the Getting Started funnel on THIS INSTALL. Nil until then.
	//
	// It lives here, server-side, because it is a fact about the install and
	// every previous attempt to keep it in the browser was wrong in a way that
	// shipped: a localStorage flag outlives the install it describes (a wiped
	// database kept skipping its own funnel) and is scoped to an ORIGIN, so the
	// same console reached at 127.0.0.1 and at localhost disagreed about
	// whether onboarding had happened.
	//
	// NOT settable through PUT /site-config: the handler IGNORES a
	// client-supplied value and carries the stored one forward, exactly as it
	// does for Integrations — otherwise a naive GET-then-PUT round-trip by an
	// older client would silently erase it. Ignored, never REFUSED: GET emits
	// this key, so the documented capture/apply round-trip and the
	// MDM-delivered /etc/wardyn/site-config.json echo it back on every write,
	// and the carry-forward already makes a submitted value inert. A dropped
	// value is reported instead — onboarding_completed_at_ignored in PUT's
	// response body, which `wardyn site-config apply` prints as a warning.
	OnboardingCompletedAt *time.Time `json:"onboarding_completed_at,omitempty"`
}

type Source struct {
	ID   uuid.UUID  `json:"id"`
	Kind SourceKind `json:"kind"`
	// Locator is the identity: a host directory path (local_dir, trailing
	// slashes trimmed) or the canonical repo slug/clone URL (repo, lowercased).
	// Together with Ref it is UNIQUE in the store — the dedupe rule.
	Locator string `json:"locator"`
	// Ref is an optional git ref (repo only; "" otherwise). Part of identity:
	// the same repo at two refs is two sources with two contracts.
	Ref  string `json:"ref,omitempty"`
	Name string `json:"name"`
	// Requirements is this source's OWN contract. See the type doc above.
	Requirements map[string]WorkspaceRequirement `json:"requirements,omitempty"`
	// Profile is this source's scan result (workspacescan.WorkspaceProfile),
	// opaque here — this type never interprets it, only persists/returns it
	// (matching Workspace.Profile's own doc). json.RawMessage, not a plain
	// []byte: encoding/json base64-encodes a bare []byte, which shipped a
	// tier-1 source's scan profile to GET /sources as an opaque base64 string
	// instead of real JSON (WIRE-2) — the one other place a source's profile
	// crossed the wire (source_scan.go) already worked around this by hand
	// (json.RawMessage(fresh.Profile)).
	Profile json.RawMessage `json:"profile,omitempty"`
	// Status is the source's scan lifecycle — the same one-word states the
	// workspace used to own: pending_scan | scanning | scanned | error.
	Status WorkspaceStatus `json:"status"`
	// ActiveRunID fences this source's in-flight scan run, exactly as the
	// workspace's own field fenced whole-workspace scans before the retarget.
	ActiveRunID *uuid.UUID `json:"active_run_id,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
}

type SourceKind string

type StorageEnforcement string

type ToolEffect string

type ToolRule struct {
	Tool   string     `json:"tool"`
	Effect ToolEffect `json:"effect"`
}

type UIApp struct {
	Name string `json:"name"`
	Port int    `json:"port"`
	Path string `json:"path,omitempty"`
}

type UserDrive struct {
	ID      uuid.UUID    `json:"id"`
	Name    string       `json:"name"`
	Backend DriveBackend `json:"backend"`
	// HostRoot is the operator-mounted tree a host_path drive binds a
	// subdirectory of. Absolute and cleaned, empty for every other backend. It
	// is authored in the DB by an admin and bound into OTHER PEOPLE's
	// sandboxes, so the security ceiling over it is the env allowlist
	// (UserDriveHostRootCheck), never this column alone.
	HostRoot string `json:"host_root,omitempty"`
	// StorageClass is the k8s_pvc provisioner to request; "" means the
	// cluster default. Meaningless for every other backend (a static PVC was
	// provisioned by someone else, and Docker has no such concept).
	StorageClass string       `json:"storage_class,omitempty"`
	HomeTemplate HomeTemplate `json:"home_template"`
	// SizeMiB is the ALLOCATION, not a guarantee — see StorageEnforcement. 0
	// means "no allocation shown" on every backend but k8s_pvc, where the value
	// IS the PVC's resources.requests.storage and 0 is therefore refused at the
	// write boundary rather than stored as a claim no cluster would bind.
	SizeMiB   int          `json:"size_mib,omitempty"`
	Writable  bool         `json:"writable,omitempty"`
	Reclaim   DriveReclaim `json:"reclaim"`
	CreatedAt time.Time    `json:"created_at"`
	UpdatedAt time.Time    `json:"updated_at"`
	CreatedBy string       `json:"created_by,omitempty"`
}

type UserDriveGrant struct {
	ID          uuid.UUID             `json:"id"`
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	DriveID     uuid.UUID             `json:"drive_id"`
	// Priority breaks ties WITHIN a tier (higher wins) — the group tier's
	// working lever, since a member is typically in several groups at once. It
	// does NOT cross tiers.
	Priority int `json:"priority"`
	// SizeMiBOverride replaces the drive's allocation for this subject. 0 means
	// "use the drive's".
	SizeMiBOverride int `json:"size_mib_override,omitempty"`
	// WritableOverride is TRI-STATE on purpose: nil is "use the drive's
	// posture", and an explicit false is an admin saying "this subject reads
	// only" even on a writable drive. A plain bool could not tell the two
	// apart, so an unset override would silently mean read-only.
	WritableOverride *bool `json:"writable_override,omitempty"`
	// HomeOverride names this subject's directory verbatim (Bob's NAS home is
	// `bsmith`, whatever the template would derive). USER TIER ONLY: on a group
	// or all row it would give every member of the group ONE home, which is the
	// opposite of the isolation binding a per-user subdirectory buys.
	HomeOverride string `json:"home_override,omitempty"`
	// Enabled is the admin's off switch that keeps the row (and its overrides)
	// intact. A disabled row is IN the resolver's query and can win its tier:
	// the winner's bit is what folds to ResolvedDrive.Paused, so an admin
	// turning one off tells that member "your allocation is paused" instead of
	// silently dropping them through to the wider row beneath it.
	Enabled   bool      `json:"enabled"`
	CreatedAt time.Time `json:"created_at"`
	CreatedBy string    `json:"created_by,omitempty"`
}

type UserDriveHostRootCheck func(hostRoot string) error

type UserDriveListItem struct {
	UserDrive
	GrantCount int `json:"grant_count"`
}

type Workspace struct {
	ID   uuid.UUID `json:"id"`
	Name string    `json:"name"`
	// Sources is the workspace's composition: one-or-more local_dir/repo/
	// ephemeral sources.
	Sources []WorkspaceSource `json:"sources"`
	// BaseImage is the workspace's base-image choice. Nil means the platform
	// default convention image for the detected/scanned stack.
	BaseImage *WorkspaceBaseImage `json:"base_image,omitempty"`
	// Requirements is the workspace's declared requirements contract: what
	// secrets/egress/write-access/integrations a run against this workspace
	// needs, keyed by a fixed grammar of "<type>:<key>" where type is one of:
	//
	//	secret:NAME       a named secret must be resolvable (the store secret
	//	                  NAME), e.g. "secret:acme-anthropic-key"
	//	egress:host       the host must be reachable from the sandbox (a bare
	//	                  host or "*."-wildcard, matching RunPolicySpec.
	//	                  AllowedDomains grammar), e.g. "egress:api.github.com" —
	//	                  unioned into a run's allowlist alongside ApprovedEgress
	//	write:/host/path  the given HOST path must be mounted writable, e.g.
	//	                  "write:/home/user/repo" — matches a Sources[] entry
	//	                  whose Path equals /host/path and Writable=true
	//	integration:ID    the named Integration (SiteConfig.Integrations[i].ID)
	//	                  must be granted — its hosts opened and its credential
	//	                  (if any) presented, e.g. "integration:git_host:
	//	                  github.com" (ID itself may contain colons; see the
	//	                  split rule below)
	//
	// The map key is exactly "<type>:<key>", type and key joined by ONE colon.
	// A key parser MUST split on the FIRST colon only (never the last): the
	// type prefix is always one of the four fixed tokens above, so splitting
	// on the first colon unambiguously separates it from the key even though a
	// host path (a write: key) or an adopted legacy id (an integration: key)
	// may itself legally contain colons.
	//
	// THREE-TIER SPLIT: this map is now the workspace's OVERLAY — what this
	// workspace additionally declares or restates on top of what its attached
	// sources' own contracts contribute. EffectiveRequirements below is the
	// folded result a run actually consumes.
	Requirements map[string]WorkspaceRequirement `json:"requirements,omitempty"`

	// Attachments is the tier-3 composition: ordered source references and
	// inline ephemeral rows, each with per-attachment target/writable and the
	// workspace's requirement OVERRIDES for that source (workspace_contract.go).
	// Empty on a pre-split row that hasn't migrated its embedded Sources yet —
	// the store's hydrate pass falls back to the embedded column then.
	Attachments []WorkspaceAttachment `json:"attachments,omitempty"`
	// BaseImageID references the shared base-image catalog (tier 2). Nil means
	// "recommended" — the per-workspace derived build — by design, not absence.
	BaseImageID *uuid.UUID `json:"base_image_id,omitempty"`
	// EffectiveRequirements is DERIVED, read-only, never persisted: the
	// FoldWorkspaceContract result over attachments + attached source
	// contracts + the overlay above. This is the map run-create and preflight
	// consume. Populated by the store's hydrate pass; on a pre-split row it
	// equals Requirements verbatim (the fold's zero-source identity).
	EffectiveRequirements map[string]WorkspaceRequirement `json:"effective_requirements,omitempty"`

	// Kind mirrors Sources[0].Type (single-source only).
	Kind WorkspaceKind `json:"kind"`
	// Source mirrors Sources[0]'s host path (local_dir) or repo slug/URL (repo)
	// (single-source only).
	Source string `json:"source"`
	// Ref mirrors Sources[0].Ref (single-source repo only).
	Ref string `json:"ref,omitempty"`
	// DefaultTarget mirrors Sources[0].Target (single-source only).
	DefaultTarget string `json:"default_target,omitempty"`

	// Profile is internal/workspacescan's WorkspaceProfile, opaque here. Nil/empty
	// until scanned.
	Profile json.RawMessage `json:"profile,omitempty"`
	// ImageRef is the resolved/generated image for this workspace's profile
	// empty until scanned/built.
	ImageRef string `json:"image_ref,omitempty"`
	// BuiltProfileHash is the profile hash ImageRef was built from — the
	// build-once/reuse-many cache key (rebuild only when the profile hash changes).
	BuiltProfileHash string `json:"built_profile_hash,omitempty"`
	// ApprovedEgress is the OPERATOR-owned list of egress hosts explicitly
	// promoted for this workspace (typically from the scanner's content-derived
	// SuggestedEgress, which is advisory and never auto-allowed). Unioned into a
	// run's allowlist alongside the scanned profile's EgressDomains. Never
	// written by a scan; cleared when the composition changes.
	ApprovedEgress []string `json:"approved_egress,omitempty"`
	// DeniedEgress is the OPERATOR-owned mirror of ApprovedEgress: hosts
	// explicitly blocked for this workspace, written by a `deny · always`
	// approval decision (AddWorkspaceEgressDecision) or the denied-egress PUT
	// (SetWorkspaceDeniedEgress). Folded into a run's denied_domains at
	// create time, where deny beats allow, allow_all_egress, and a runtime
	// first-use approval alike. UNLIKE ApprovedEgress, this is NOT cleared
	// when the workspace's sources change (see migration 0040): that reset
	// rule is right for a WIDENING (a stale allow should fail closed), but
	// applying it to a NARROWING would silently drop an operator's permanent
	// deny the moment content changed — a deny needs no re-review against new
	// content.
	DeniedEgress []string `json:"denied_egress,omitempty"`
	// EgressEditedAt is when an operator last REPLACED one of the two lists
	// above through the approved-egress/denied-egress PUTs — the documented
	// undo for an `always` decision. Nil on a workspace whose lists have only
	// ever been written by decisions (or never written at all).
	//
	// It exists for exactly one reader, the boot heal
	// (ReconcileWorkspaceEgressDecisions), which re-applies decided `always`
	// approvals and would otherwise put back a host the operator had just
	// removed: the approval row still says APPROVED/always forever, so without
	// a "the operator has spoken more recently than that" mark the undo is
	// re-widened at every restart. Stamped ONLY by those two scoped setters —
	// never by AddWorkspaceEgressDecision (a decision is not an override of
	// itself) and never by UpdateWorkspace (a composition edit restates every
	// column, so stamping there would suppress the heal for unrelated edits).
	EgressEditedAt *time.Time `json:"egress_edited_at,omitempty"`
	// ActiveRunID is the in-flight scan/record run for this workspace, so the
	// import panel can poll "is my step still running" without scanning all
	// runs. Nil when no import step is executing.
	ActiveRunID *uuid.UUID `json:"active_run_id,omitempty"`
	// RecordResults is the per-task Record Mode state (taskKey → result: run
	// pointer, mode, status, observations captured server-side from the run's
	// audit events). Opaque map[string]api-owned JSON; written only via the
	// scoped SetWorkspaceRecordResult; cleared when the composition changes
	// (recordings were reviewed against the OLD sources).
	RecordResults json.RawMessage `json:"record_results,omitempty"`
	// LLMCred is the OPERATOR-owned model/harness credential binding: a run that
	// picks this workspace inherits it (refs/names only). Nil => no binding.
	// Folded into the run policy at create (applyWorkspaceCreds); written only
	// via the scoped SetWorkspaceLLMCred, mirroring ApprovedEgress.
	LLMCred *WorkspaceLLMCred `json:"llm_cred,omitempty"`
	// OwnedBy is the MEMBER who created this workspace (their lowercased OIDC
	// sub or email — the same dual-key identity a capability_grants `user`
	// subject carries). EMPTY means OPERATOR-OWNED, which is every workspace an
	// admin creates and every workspace that existed before migration 0048: an
	// operator-owned row stays member-READABLE and admin-writable exactly as it
	// always was, so an upgrade changes nothing until a member creates their
	// first owned workspace.
	//
	// A non-empty value is the ownership relation ownsWorkspaceOrAdmin keys on:
	// only that member (or an admin) may read or write the row, and a foreign
	// member gets the byte-identical 404 a missing workspace gets — no existence
	// oracle, the posture AgentRun.CreatedBy already has for runs. Set ONLY by
	// handleCreateWorkspace from the authenticated session; never accepted from
	// a request body, and never rewritten by an edit (UpdateWorkspace does not
	// carry the column).
	OwnedBy   string          `json:"owned_by,omitempty"`
	Status    WorkspaceStatus `json:"status"`
	CreatedAt time.Time       `json:"created_at"`
	UpdatedAt time.Time       `json:"updated_at"`
}

type WorkspaceAttachment struct {
	SourceID *uuid.UUID `json:"source_id,omitempty"`
	// Ephemeral marks an inline scratch row (never a library entity).
	Ephemeral bool `json:"ephemeral,omitempty"`
	// Target is the in-sandbox mount/clone/scratch path for THIS attachment.
	Target string `json:"target,omitempty"`
	// Writable opts a local_dir attachment into read-write (per-attachment,
	// not per-source: the same dir can be writable in one workspace and
	// read-only in another).
	Writable bool `json:"writable,omitempty"`
	// Overrides is this workspace's stance on requirement keys the attached
	// source declares: reqKey -> off|optional|required. "off" means THIS
	// workspace refuses that requirement (mount the repo read-only to read
	// code, without its build secrets/egress) — it never edits the shared
	// source. Keys the source doesn't declare are ignored harmlessly.
	Overrides map[string]string `json:"overrides,omitempty"`
}

type WorkspaceBaseImage struct {
	// Kind is "recommended" (Wardyn's own convention image for the detected
	// stack), "registry" (an operator-picked published image, named by Image),
	// "custom" (Image is a base; see Steps below for what actually happens to
	// it), or "byo" (Image is used verbatim).
	Kind string `json:"kind"`
	// Image is the base image reference. Meaning depends on Kind: the FROM for
	// "custom", the image itself for "registry"/"byo", unused for "recommended".
	Image string `json:"image,omitempty"`
	// Steps is CATALOG IDENTITY ONLY. It is never applied to an image, and it
	// must not be — this is a deliberate refusal, not an unfinished feature.
	//
	// Running operator-authored RUN lines would execute on the HOST Docker daemon
	// during the wrap (resolveWorkspaceImage wraps Image verbatim), outside every
	// confinement tier — the same host-RCE class assertWrapSafeBase refuses a
	// hostile ONBUILD trigger for. So a "custom" image builds and runs
	// identically to "byo": Image verbatim.
	//
	// The FIELD stays, and deleting it would be a live bug rather than a
	// cleanup: it participates in the base_images UNIQUE identity index
	// alongside (kind, image). Stop writing it and every upsert records NULL,
	// so a pre-existing row carrying non-empty steps stops conflict-matching and
	// the next passthrough resolve mints a DUPLICATE catalog row for the same
	// (kind, image). The user-facing surface that pretended these did something
	// was removed in 0.7 (D3); the identity component was not.
	Steps []string `json:"steps,omitempty"`
}

type WorkspaceBedrockRef struct {
	Region string `json:"region,omitempty"`
	Model  string `json:"model,omitempty"`
}

type WorkspaceKind string

type WorkspaceLLMCred struct {
	// IntegrationRef names the Integration (SiteConfig.Integrations[i].ID) this
	// workspace's model/harness access resolves through.
	IntegrationRef string `json:"integration_ref,omitempty"`
}

type WorkspaceMount struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly *bool  `json:"read_only,omitempty"`
}

type WorkspaceRepo struct {
	Repo   string `json:"repo"`
	Target string `json:"target,omitempty"`
	Ref    string `json:"ref,omitempty"`
}

type WorkspaceRequirement struct {
	// Level is "required" (a run against this workspace cannot proceed without
	// it) or "optional" (a run may proceed without it, degraded).
	Level string `json:"level"`
	// Provenance is "scan_seeded" (the workspace scanner detected the need) or
	// "operator_set" (an operator declared it directly).
	Provenance string `json:"provenance"`
}

type WorkspaceSource struct {
	Type WorkspaceSourceType `json:"type"`
	// Path is the host directory path. local_dir only.
	Path string `json:"path,omitempty"`
	// Source is the repo slug/URL. repo only.
	Source string `json:"source,omitempty"`
	// Ref is an optional git ref (branch/tag/sha). repo only.
	Ref string `json:"ref,omitempty"`
	// Target is the mount/clone/scratch-dir path inside the sandbox.
	Target string `json:"target,omitempty"`
	// Writable opts a local_dir source into read-write (default false =
	// read-only, matching WorkspaceMount.ReadOnly's safe default — this field is
	// a plain bool rather than a *bool because false already IS the safe
	// default, so there is no unsafe zero value to guard against). local_dir
	// only.
	Writable bool `json:"writable,omitempty"`
	// Overrides is this attachment's stance on requirement keys ITS SOURCE
	// declares: reqKey -> off|optional|required (workspace_contract.go's
	// AttachmentOverride* constants); local_dir/repo only (ephemeral has no
	// library contract to override). nil (the field omitted) means "say
	// nothing here" — the server carries forward whatever this source's
	// attachment already had (upsertAndAttach), so a plain composition edit
	// (e.g. a rename) can never silently wipe an override set on an earlier
	// PUT; an explicit map, empty or not, REPLACES it outright.
	Overrides map[string]string `json:"overrides,omitempty"`
}

type WorkspaceSourceType string

type WorkspaceStatus string