zebflow 0.9.1

//! Platform domain models and configuration.

use std::collections::{BTreeMap, HashMap};
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::infra::cluster::config::ClusterSettings;
use crate::infra::cluster::registry::WorkerHeartbeat;
use crate::infra::execution::placement::ProjectRuntimeProfile;
use crate::infra::execution::runner::RunnerCapabilities;
use crate::zebfs::{FileBackend, FileStore, ZebFs, ZebFsError};

/// Data adapter selection.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum DataAdapterKind {
    /// SQLite-backed platform catalog (WAL mode, bundled SQLite 3.47).
    #[default]
    Sqlite,
    /// Placeholder adapter.
    DynamoDb,
    /// Placeholder adapter.
    Firebase,
}

/// File adapter selection.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum FileAdapterKind {
    /// Local filesystem tree. Git-sync friendly.
    #[default]
    Filesystem,
}

/// Platform bootstrap/runtime config.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PlatformConfig {
    /// Root data directory where platform metadata + project files are stored.
    ///
    /// Defaults to `ZEBFLOW_PLATFORM_DATA_DIR` when it is set and to the OS
    /// user-data path otherwise (`platform::boot`); never to a path relative to
    /// the working directory, which `interface.md` §5 says identifies nothing.
    pub data_root: PathBuf,
    /// Selected metadata adapter.
    pub data_adapter: DataAdapterKind,
    /// Selected file adapter.
    pub file_adapter: FileAdapterKind,
    /// Default superadmin username created on first bootstrap.
    pub default_owner: String,
    /// Optional initial superadmin password created on first bootstrap.
    ///
    /// When empty, Zebflow generates a random password and stores it in a
    /// private file under the platform data root.
    pub default_password: String,
    /// Default project slug created on first bootstrap.
    pub default_project: String,
    /// Unix timestamp seconds; platform-issued secrets created before this time
    /// are invalidated on startup/lookup.
    #[serde(default)]
    pub secret_rotation_epoch: i64,
    /// Cluster/controller-office role and connectivity settings.
    pub cluster: ClusterSettings,
}

impl Default for PlatformConfig {
    fn default() -> Self {
        Self {
            // Not a literal: `boot::default_data_root` is the one place the
            // two cases live, so every construction of this struct that does
            // not name a root gets the same one a server mode would open.
            data_root: crate::platform::boot::default_data_root(),
            data_adapter: DataAdapterKind::Sqlite,
            file_adapter: FileAdapterKind::Filesystem,
            default_owner: "superadmin".to_string(),
            default_password: String::new(),
            default_project: "default".to_string(),
            secret_rotation_epoch: 0,
            cluster: ClusterSettings::default(),
        }
    }
}

/// User profile stored by platform metadata adapter.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformUser {
    /// Stable internal user id.
    #[serde(default)]
    pub user_id: String,
    /// User identifier.
    pub owner: String,
    /// Role string (`superadmin`, `member`, ...).
    pub role: String,
    /// Display name for git commits (e.g. "Alice Smith").
    #[serde(default)]
    pub git_name: String,
    /// Email for git commits (e.g. "alice@example.com").
    #[serde(default)]
    pub git_email: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// User record with auth secret, used internally by auth service.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct StoredUser {
    /// Public profile fields.
    pub profile: PlatformUser,
    /// Local platform auth material.
    pub auth: PlatformUserLocalAuth,
}

/// Credential state: the current password was generated by the platform and
/// never chosen by a person. A browser login on such an account is forced to
/// the change-password screen until the state becomes [`CREDENTIAL_STATE_CHOSEN`].
pub const CREDENTIAL_STATE_GENERATED: &str = "generated";

/// Credential state: the current password was chosen by an operator or user.
pub const CREDENTIAL_STATE_CHOSEN: &str = "chosen";

fn default_credential_state() -> String {
    CREDENTIAL_STATE_CHOSEN.to_string()
}

/// Local auth record for one user.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformUserLocalAuth {
    /// Stable internal user id.
    pub user_id: String,
    /// Stored password hash.
    pub password_hash: String,
    /// Password hash algorithm identifier.
    pub password_alg: String,
    /// Unix timestamp seconds.
    pub password_updated_at: i64,
    /// `generated` while the password is a platform-generated one nobody has
    /// replaced; `chosen` once a person set it. See [`CREDENTIAL_STATE_GENERATED`].
    #[serde(default = "default_credential_state")]
    pub credential_state: String,
}

/// Project profile stored by metadata adapter.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformProject {
    /// Stable internal project id.
    #[serde(default)]
    pub project_id: String,
    /// Stable internal owner user id.
    #[serde(default)]
    pub owner_user_id: String,
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Display title.
    pub title: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

// ---------------------------------------------------------------------------
// Credential type definitions
// ---------------------------------------------------------------------------

/// Defines a credential type (e.g. `postgres`, `telegram_bot`).
/// Same format for official (built-in) and custom (from composite/WASM packages).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct CredentialTypeDef {
    /// Unique kind identifier, e.g. `"postgres"`, `"telegram_bot"`.
    pub kind: String,
    /// Human-readable title shown in UI.
    pub title: String,
    /// Short description of this credential type.
    #[serde(default)]
    pub description: String,
    /// Form fields for creating/editing a credential of this type.
    pub fields: Vec<CredentialFieldDef>,
    /// Placeholder mappings for composite nodes.
    /// Maps placeholder name → secret field key.
    /// Only used by composite/WASM packages. Empty for built-in types.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub placeholders: HashMap<String, String>,
    /// Config key in the composite node that holds the credential ID.
    /// E.g. `"credential_id"` — the composite's `config.credential_id` value is
    /// used to look up the credential at runtime.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub config_key: String,
}

/// One field in a credential type definition form.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct CredentialFieldDef {
    /// Secret JSON key this field writes to.
    pub key: String,
    /// Display label.
    pub label: String,
    /// Field type: `"text"`, `"password"`, `"select"`, `"textarea"`, `"number"`, `"tags"`.
    #[serde(default = "default_field_type", rename = "type")]
    pub field_type: String,
    /// Whether this field is required.
    #[serde(default)]
    pub required: bool,
    /// Input placeholder text.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub placeholder: Option<String>,
    /// Help text shown below the field.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub help: Option<String>,
    /// Default value.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
    /// Auto-generation hint, e.g. `"random_hex_32"`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub generate: Option<String>,
    /// Options for `select` field type.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub options: Vec<CredentialFieldOption>,
    /// Whether this field should span full width in UI.
    #[serde(default, rename = "fullWidth")]
    pub full_width: bool,
    /// Number of rows for `textarea` field type.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rows: Option<u32>,
}

/// Option for a `select` credential field.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct CredentialFieldOption {
    pub value: String,
    pub label: String,
}

fn default_field_type() -> String {
    "text".to_string()
}

/// Stored project credential record used by runtime nodes and management APIs.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProjectCredential {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Stable credential id.
    pub credential_id: String,
    /// Display title.
    pub title: String,
    /// Driver/kind (`postgres`, `openai`, ...).
    pub kind: String,
    /// Secret payload owned by the project.
    pub secret: serde_json::Value,
    /// Optional freeform notes.
    pub notes: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One project credential summary row safe to return in list responses.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectCredentialListItem {
    /// Stable credential id.
    pub credential_id: String,
    /// Display title.
    pub title: String,
    /// Driver/kind (`postgres`, `openai`, ...).
    pub kind: String,
    /// Whether the credential currently stores a secret payload.
    pub has_secret: bool,
    /// Optional freeform notes.
    pub notes: String,
    /// Roles registered in this credential (JWT only). Non-sensitive — safe to expose in list responses.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub auth_roles: Vec<String>,
    /// Safe variable definitions exposed by `secure_request` credentials.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub secure_request_vars: Vec<SecureRequestVariableDefinition>,
    /// OAuth2 token status. Derived at list-time, not stored.
    /// Values: "" (non-oauth2), "not_configured", "authorized", "expired".
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub oauth2_status: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Safe variable definition exposed from a `secure_request` credential.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SecureRequestVariableDefinition {
    /// Stable variable name used in the request template.
    pub name: String,
    /// Human-readable label displayed in UI surfaces.
    pub label: String,
    /// Value kind hint such as `string`, `secret`, or `header`.
    #[serde(default)]
    pub value_type: String,
    /// Whether this variable is required at request time.
    #[serde(default)]
    pub required: bool,
    /// Optional default expression evaluated client-side or by later request tooling.
    #[serde(default)]
    pub default_expr: String,
    /// Optional human-readable explanation.
    #[serde(default)]
    pub description: String,
}

/// Stored project DB connection record used by DB suite and runtime nodes.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProjectDbConnection {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Stable connection id.
    pub connection_id: String,
    /// Stable route slug.
    pub connection_slug: String,
    /// Display label.
    pub connection_label: String,
    /// Database kind (`sqlite`, `postgresql`, ...).
    pub database_kind: String,
    /// Optional linked credential id.
    pub credential_id: Option<String>,
    /// Optional kind-specific config payload.
    pub config: serde_json::Value,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One project DB connection summary row safe to return in list responses.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectDbConnectionListItem {
    /// Stable connection id.
    pub connection_id: String,
    /// Stable route slug.
    pub connection_slug: String,
    /// Display label.
    pub connection_label: String,
    /// Database kind (`sqlite`, `postgresql`, ...).
    pub database_kind: String,
    /// Optional linked credential id.
    pub credential_id: Option<String>,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One project-scoped hub repository source.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectHubRepository {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Stable repository id.
    pub repository_id: String,
    /// Display title.
    pub title: String,
    /// Base URL of the remote hub, e.g. `http://127.0.0.1:10612`.
    pub base_url: String,
    /// Remote owner slug on the target hub.
    pub remote_owner: String,
    /// Remote project slug on the target hub.
    pub remote_project: String,
    /// Optional bearer token for read access.
    pub read_token: String,
    /// Whether this repository should be queried in Packs.
    pub enabled: bool,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One platform-scoped hub repository source used from Home.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformHubRepository {
    /// Stable internal source id.
    #[serde(default)]
    pub source_id: String,
    /// Stable internal owner user id.
    #[serde(default)]
    pub owner_user_id: String,
    /// Owner identifier for the local platform user who manages this source.
    pub owner: String,
    /// Stable repository id.
    pub repository_id: String,
    /// Display title.
    pub title: String,
    /// Base URL of the remote hub, e.g. `http://127.0.0.1:10612/api/projects/superadmin/default/hub`.
    pub base_url: String,
    /// Remote owner slug on the target hub when using a proxy base.
    pub remote_owner: String,
    /// Remote project slug on the target hub when using a proxy base.
    pub remote_project: String,
    /// Optional bearer token for read access.
    pub read_token: String,
    /// Which channel serves this source: `api` or `static`.
    ///
    /// Absent means `api`, which is what every row written before static
    /// repositories existed is. A kind this build does not implement refuses
    /// rather than being fetched from as though it were an API hub.
    #[serde(default)]
    pub kind: String,
    /// Where this source sits in resolution order. Lower is consulted first.
    ///
    /// This is where the order in `distribution.md` is configured: the official
    /// sources are seeded at 10 and 20, and anything added later defaults to
    /// 100 so it is consulted after them.
    #[serde(default)]
    pub priority: i64,
    /// Source visibility in Platform Home hub explorer: public or private.
    #[serde(default)]
    pub visibility: String,
    /// Whether this repository should be queried in Home hub.
    pub enabled: bool,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One explicit grant from a platform-owned Hub access source to projects.
///
/// Registering a Hub source only records where the Hub lives. A grant is the
/// separate policy row that lets projects use that access for read/publish/manage
/// workflows. This keeps internal/private Hubs explicit instead of inherited.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAccessGrant {
    /// Stable grant id.
    pub grant_id: String,
    /// Platform owner that owns the Hub source.
    pub source_owner: String,
    /// Stable platform Hub source id.
    pub source_id: String,
    /// Human-facing repository id for the Hub source.
    pub repository_id: String,
    /// Grant scope: `all_projects` or `selected_project`.
    pub grant_scope: String,
    /// Target owner for selected-project grants. Empty for all-project grants.
    pub target_owner: String,
    /// Target project for selected-project grants. Empty for all-project grants.
    pub target_project: String,
    /// Whether this grant allows browsing/installing from the source.
    pub can_read: bool,
    /// Whether this grant allows publishing through the access.
    pub can_publish: bool,
    /// Whether this grant allows managing the access.
    pub can_manage: bool,
    /// Whether the grant is active.
    pub enabled: bool,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One explicit hub authority row.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAuthority {
    /// Stable authority id.
    pub authority_id: String,
    /// Host project id.
    pub host_project_id: String,
    /// Hub authority owner slug.
    pub owner: String,
    /// Hub authority project slug.
    pub project: String,
    /// Whether producer mode is currently enabled.
    pub enabled: bool,
    /// Public hub API base URL when exposed.
    pub public_base_url: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One durable office row in the platform control plane.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOffice {
    /// Stable office id.
    pub office_id: String,
    /// Human-readable / URL-safe office slug.
    pub office_slug: String,
    /// Display label.
    pub label: String,
    /// Office kind (`controller`, `office`, `standalone`).
    pub office_kind: String,
    /// Base URL advertised for control/runtime traffic.
    pub base_url: String,
    /// Current status summary.
    pub status: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Status word of one issued join token.
pub const JOIN_TOKEN_STATUS_ACTIVE: &str = "active";
/// Status word of one revoked join token.
pub const JOIN_TOKEN_STATUS_REVOKED: &str = "revoked";

/// One join token the controller issued to one office.
///
/// The secret itself is never held here: only `secret_digest`, which is what
/// the controller compares a presented token against (`offices.md` §8).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOfficeJoinToken {
    /// Office the token was issued to. One row per office.
    pub office_id: String,
    /// `sha256(secret)`, hex. Never the secret, and never serialised.
    ///
    /// `skip_serializing` because this struct is both the stored row and the
    /// shape returned by `GET /api/platform/cluster/join-tokens` and by the mint
    /// response. The digest used to travel in both, which put an office's
    /// stored material into HTTP responses, browser memory, and every proxy log
    /// on the way. It no longer keys anything a forger could use — the
    /// controller signs with a private key it never publishes — but a value
    /// that identifies one office's membership still has no business leaving
    /// the controller's storage, and the API never needed it.
    #[serde(skip_serializing, default)]
    pub secret_digest: String,
    /// `active` or `revoked`. Revoking one row locks out exactly one office.
    pub status: String,
    /// Operator note recorded at mint time.
    #[serde(default)]
    pub note: String,
    /// Unix timestamp seconds when the token was minted.
    pub created_at: i64,
    /// Unix timestamp seconds of the last accepted presentation, or `0`.
    #[serde(default)]
    pub last_used_at: i64,
}

impl PlatformOfficeJoinToken {
    /// Whether this token may still be presented.
    pub fn is_active(&self) -> bool {
        self.status.trim() == JOIN_TOKEN_STATUS_ACTIVE
    }
}

/// One vouch this office has already redeemed.
///
/// `offices.md` §2's vouch verb is a hand-off, and a hand-off happens once. The
/// row exists so a second presentation of the same vouch is refused — without
/// it, a value that leaks from a URL bar, a proxy log, or a `Referer` header is
/// a reusable key for as long as it lives.
///
/// It lives in the *office's* own catalog, because the office is the party that
/// must refuse, and §3's whole point is that it can do so without the
/// controller. `instance-directory.md` puts `platform/catalog.db` in the STORE
/// tier beside sessions, which is the same lifetime and the same durability
/// requirement: a record kept only in memory would let a restart reopen every
/// unspent vouch.
///
/// It is bounded by its own subject. A vouch past `expires_at` is refused by
/// the expiry check whatever this table says, so the row can be deleted the
/// moment it outlives the vouch it records, and it is
/// ([`crate::platform::services::ClusterJoinTokenService::redeem_vouch`] prunes
/// on every redemption). The table's ceiling is therefore the number of
/// vouches redeemed inside one TTL window, not the number ever redeemed.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOfficeVouchRedemption {
    /// The vouch's nonce. One row per vouch, and the reason it is spendable once.
    pub nonce: String,
    /// Office the vouch named.
    pub office_id: String,
    /// Identity the vouch carried.
    pub identity: String,
    /// The vouch's own expiry; the row is prunable once it passes.
    pub expires_at: i64,
    /// Unix timestamp seconds the vouch was spent.
    pub redeemed_at: i64,
}

/// A vouch resolved to a local account that already existed.
pub const IDENTITY_WRITE_ACTION_LINKED: &str = "linked";
/// A vouch created a local account that did not exist.
pub const IDENTITY_WRITE_ACTION_CREATED: &str = "created";

/// One thing the controller put into this office's accounts.
///
/// `offices.md` §8: "Anything the controller pushes into an office's accounts
/// is logged where the office's operator can read it." *Where the office's
/// operator can read it* is the load-bearing half — a record only the
/// controller can read would be the controller auditing itself.
///
/// So it is a row in the office's own `platform/catalog.db`, read over the
/// office's own API by the office's own superadmin, with the controller
/// unreachable and uninvolved. On the tier question `instance-directory.md`
/// leaves one answer: STORE, "machine-written, cannot be regenerated, back it
/// up". Not CACHE, which may be deleted with no loss. Not BOUNDED, which is
/// "disposable after a retention window" — the record of who was inserted into
/// your accounts is the last thing that should quietly expire. And not a
/// project's `data/logs/`, which is BOUNDED, 30-day, and scoped to a project an
/// identity write does not belong to.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOfficeIdentityWrite {
    /// Stable row id.
    pub write_id: String,
    /// Office whose accounts were written.
    pub office_id: String,
    /// Local owner slug that was created or resolved.
    pub owner: String,
    /// [`IDENTITY_WRITE_ACTION_CREATED`] or [`IDENTITY_WRITE_ACTION_LINKED`].
    pub action: String,
    /// Role the local account holds after the write.
    pub role: String,
    /// What caused the write, e.g. `controller-vouch`.
    pub source: String,
    /// Human-readable detail an operator reads without a decoder.
    pub detail: String,
    /// Unix timestamp seconds.
    pub written_at: i64,
}

/// A host command re-enabled this office's local authority (`offices.md` §6).
pub const LOCAL_AUTHORITY_EVENT_BREAK_GLASS: &str = "break-glass";
/// A host command detached this office from its controller (`offices.md` §7).
pub const LOCAL_AUTHORITY_EVENT_DETACH: &str = "detach";

/// One act on this office's own local authority.
///
/// `offices.md` §6 asks for two things at once: break-glass "re-enables local
/// authority", and "its use is recorded locally and reported to the controller
/// on reconnect". §7 then makes detaching a *separate* act. Both are acts by
/// somebody with host access on the office, both change whether local login
/// works, and both are things the office's operator must be able to read back
/// later — so they are one append-only log rather than two.
///
/// The log is also the **state**. Nothing else records whether local authority
/// has been re-enabled, and that is deliberate: a flag stored beside the log
/// could disagree with it, and after a restore or a copy one of the two would
/// be wrong with no way to tell which. The rule is stated once, in
/// [`crate::platform::services::OfficeLocalAuthorityService`], and derived from
/// these rows every time it is asked.
///
/// It lives in the office's own `platform/catalog.db`, STORE tier, for exactly
/// the reason [`PlatformOfficeIdentityWrite`] does: the record of who opened
/// this instance's front door is the last thing that should quietly expire, and
/// it must be readable by the office's operator with the controller absent or
/// gone for good.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOfficeLocalAuthorityEvent {
    /// Stable row id.
    pub event_id: String,
    /// Office this act was performed on.
    pub office_id: String,
    /// [`LOCAL_AUTHORITY_EVENT_BREAK_GLASS`] or [`LOCAL_AUTHORITY_EVENT_DETACH`].
    pub event: String,
    /// Fingerprint of the join token held when the act happened.
    ///
    /// `sha256(sha256(secret))` — one hash further than the digest the mutual
    /// proof is keyed by, so a row that identifies *which* membership was
    /// broken out of still carries nothing that could be used as that key.
    ///
    /// This is what stops a break-glass silently outliving the join it was
    /// performed against. A re-issued token has a different fingerprint, so the
    /// old row no longer matches and local login is disabled again on the new
    /// join, with nobody having to remember to clear anything.
    #[serde(default)]
    pub join_fingerprint: String,
    /// Local account whose password was rotated in the same act, or empty.
    #[serde(default)]
    pub owner: String,
    /// Human-readable detail an operator reads without a decoder.
    #[serde(default)]
    pub detail: String,
    /// Unix timestamp seconds the act was performed.
    pub acted_at: i64,
    /// Unix timestamp seconds the controller acknowledged it, or `0`.
    ///
    /// Only a break-glass is ever reported. A detach gives up the credential
    /// that would authenticate the report, so a detach row stays `0` for good
    /// and says so rather than pretending a delivery is pending.
    #[serde(default)]
    pub reported_at: i64,
}

impl PlatformOfficeLocalAuthorityEvent {
    /// Whether this row is a break-glass rather than a detach.
    pub fn is_break_glass(&self) -> bool {
        self.event.trim() == LOCAL_AUTHORITY_EVENT_BREAK_GLASS
    }
}

/// One minted vouch, as the controller hands it over.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ClusterOfficeVouch {
    /// Office the vouch opens, and no other.
    pub office_id: String,
    /// Identity the controller vouched for.
    pub identity: String,
    /// Unix timestamp seconds after which the office refuses it.
    pub expires_at: i64,
    /// Seconds the vouch lives, so a caller need not subtract clocks.
    pub ttl_seconds: i64,
    /// The vouch itself.
    pub vouch: String,
    /// Where to redeem it, when the office record advertises a base URL.
    #[serde(default)]
    pub redeem_url: String,
}

/// One accepted vouch, after the office verified and spent it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AcceptedOfficeVouch {
    /// Office that accepted it.
    pub office_id: String,
    /// Identity the controller vouched for.
    pub identity: String,
    /// The vouch's expiry, kept for the redemption record.
    pub expires_at: i64,
}

/// One platform-level service instance hosted by an office.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformServiceInstance {
    /// Stable service instance id, e.g. `hub-default`.
    pub service_instance_id: String,
    /// Service kind, e.g. `hub`.
    pub service_kind: String,
    /// Display label.
    pub display_label: String,
    /// Office that serves this service runtime.
    pub host_office_id: String,
    /// Office that owns this service's operational state.
    pub state_office_id: String,
    /// Public API/base URL for this service, when exposed.
    pub public_base_url: String,
    /// Whether the service is enabled.
    pub enabled: bool,
    /// Current service status summary.
    pub status: String,
    /// Monotonic placement/config generation.
    pub placement_generation: i64,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One registered runtime node under an office.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PlatformOfficeNode {
    /// Stable office id.
    pub office_id: String,
    /// Stable node id.
    pub node_id: String,
    /// Display label.
    pub label: String,
    /// Advertised base URL.
    pub base_url: String,
    /// Current status summary.
    pub status: String,
    /// Declared capabilities.
    #[serde(default)]
    pub capabilities: RunnerCapabilities,
    /// Unix timestamp seconds.
    pub registered_at: i64,
    /// Unix timestamp seconds.
    pub last_heartbeat_at: i64,
}

/// One stable publisher identity inside one hub service authority.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubPublisher {
    /// Stable authority id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub authority_id: String,
    /// Stable publisher row id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub publisher_pk: String,
    /// Internal hub scope owner.
    pub owner: String,
    /// Internal hub scope project.
    pub project: String,
    /// Stable immutable public publisher identity.
    pub publisher_id: String,
    /// Human-facing publisher name.
    pub display_name: String,
    /// Stable public publisher URL.
    pub publisher_url: String,
    /// Publisher contact email.
    pub email: String,
    /// Optional human-readable description.
    pub description: String,
    /// Optional icon URL.
    pub icon_url: String,
    /// Optional website URL.
    pub website_url: String,
    /// Whether the publisher is active.
    pub enabled: bool,
    /// Whether this publisher may read private hub artifacts.
    #[serde(default = "default_true")]
    pub can_read: bool,
    /// Whether this publisher may publish package versions.
    #[serde(default = "default_true")]
    pub can_publish: bool,
    /// Whether this publisher may manage publisher-scoped settings/tokens.
    #[serde(default)]
    pub can_manage: bool,
    /// Maximum number of package ids this publisher may own. Zero means default.
    #[serde(default)]
    pub max_packages: i64,
    /// Maximum raw artifact bytes per package version. Zero means default.
    #[serde(default)]
    pub max_package_bytes: i64,
    /// Maximum media files per package version. Zero means default.
    #[serde(default)]
    pub max_media_files: i64,
    /// Maximum bytes per image media file. Zero means default.
    #[serde(default)]
    pub max_image_bytes: i64,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One presentation image kept beside a hub package, as an artifact digest.
///
/// The bytes live in this instance's content-addressed Hub artifact store, not
/// inside any release document: a cover is something a human looks at while
/// choosing, and the release is the thing an installer parses to reach files.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAssetMedia {
    /// Plain file name this image is served as, unique within the package.
    pub name: String,
    /// Role this image plays, for example `cover`.
    pub role: String,
    /// Media type of the stored bytes.
    pub content_type: String,
    /// Size of the stored bytes.
    pub size_bytes: usize,
    /// Lowercase hex SHA-256 naming the bytes in the Hub artifact store.
    pub artifact_sha256: String,
}

/// Presentation for a package listing, mutable beside its releases.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAssetGallery {
    /// The one image shown for a package before it is opened.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cover: Option<HubAssetGalleryImage>,
    #[serde(default)]
    pub items: Vec<HubAssetGalleryItem>,
}

/// The cover image a listing shows.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAssetGalleryImage {
    pub kind: String,
    /// A name in the package's `media`.
    pub media_name: String,
    #[serde(default)]
    pub alt: String,
}

/// One gallery entry: a stored image or an external video.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAssetGalleryItem {
    pub kind: String,
    /// Image form: a name in the package's `media`.
    #[serde(default)]
    pub media_name: String,
    #[serde(default)]
    pub alt: String,
    /// Video form: the external URL.
    #[serde(default)]
    pub url: String,
    #[serde(default)]
    pub title: String,
}

/// One published hub asset package stored by the hub service.
///
/// This is the **mutable** side of a published package. A release
/// (`HubAssetVersion` plus its `HubPackage` document) is immutable and carries
/// only what installing it requires; everything a human reads while choosing —
/// summary, long-form description, gallery, cover — lives here, so correcting
/// a typo costs an update rather than a version bump.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubAssetPackage {
    /// Stable package row id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub package_pk: String,
    /// Stable authority id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub authority_id: String,
    /// Stable publisher row id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub publisher_pk: String,
    /// Stable package id, unique inside one hub instance.
    pub package_id: String,
    /// Internal hub authority owner. Public APIs must not expose this.
    pub authority_owner: String,
    /// Internal hub authority project. Public APIs must not expose this.
    pub authority_project: String,
    /// Publisher owner id.
    pub publisher_owner: String,
    /// Stable public publisher identity inside this hub authority.
    pub publisher_id: String,
    /// Human-facing publisher name.
    pub publisher_display_name: String,
    /// Stable public publisher URL for attribution and discovery.
    pub publisher_url: String,
    /// Publisher contact email.
    pub publisher_email: String,
    /// Asset kind (`pipeline`, `template_pack`, ...).
    pub asset_kind: String,
    /// Display title.
    pub title: String,
    /// Optional human-readable description.
    pub description: String,
    /// One-line listing summary. Falls back to `description` when empty.
    #[serde(default)]
    pub summary: String,
    /// Long-form markdown shown on the package page.
    #[serde(default)]
    pub description_md: String,
    /// Public package image URL resolved from Hub artifact media.
    #[serde(default)]
    pub image_url: String,
    /// Presentation images, each addressed by its digest in the artifact store.
    #[serde(default)]
    pub media: Vec<HubAssetMedia>,
    /// Cover and gallery entries referencing `media` by name.
    #[serde(default)]
    pub gallery: HubAssetGallery,
    /// Visibility (`public`, `private`, `unlisted`).
    pub visibility: String,
    /// Search tags.
    pub tags: Vec<String>,
    /// When every release of this package was retracted, if it was.
    ///
    /// Retraction destroys the bytes and keeps the coordinates, so this row
    /// outlives the releases it describes and the package id can never be
    /// claimed by different content.
    #[serde(default)]
    pub retracted_at: Option<i64>,
    /// Why it was retracted, shown wherever the coordinate is still listed.
    #[serde(default)]
    pub retracted_reason: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One immutable version of a hub asset package.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct HubAssetVersion {
    /// Stable package row id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub package_pk: String,
    /// Stable package id.
    pub package_id: String,
    /// Version string.
    pub version: String,
    /// Internal hub authority owner. Public APIs must not expose this.
    pub authority_owner: String,
    /// Internal hub authority project. Public APIs must not expose this.
    pub authority_project: String,
    /// Publisher owner id.
    pub publisher_owner: String,
    /// Stable public publisher identity.
    pub publisher_id: String,
    /// Source owner from which the asset was exported.
    ///
    /// Provenance is the publishing instance's own record of where a release
    /// came from. It describes that instance's internal project structure, so
    /// it stays in this row and never travels inside a published document.
    pub source_owner: String,
    /// Source project from which the asset was exported. Local, never published.
    pub source_project: String,
    /// Source kind (`pipeline` for v1). Local, never published.
    pub source_kind: String,
    /// Source ref such as `pipelines/foo.zf.json`. Local, never published.
    pub source_ref: String,
    /// Artifact relative path under platform storage.
    pub artifact_rel_path: String,
    /// SHA-256 of artifact bytes.
    pub artifact_sha256: String,
    /// Serialized manifest/payload metadata.
    pub manifest: serde_json::Value,
    /// When this release was retracted, if it was.
    ///
    /// A retracted release keeps its row so `package@version` stays taken
    /// forever: the artifact bytes are gone, but the coordinate still means
    /// this release and nothing else.
    #[serde(default)]
    pub retracted_at: Option<i64>,
    /// Why it was retracted, served wherever the release is still explorable.
    #[serde(default)]
    pub retracted_reason: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
}

/// One hub access token used for publish/read/manage operations.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HubToken {
    /// Stable token id.
    pub token_id: String,
    /// Stable authority id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub authority_id: String,
    /// Stable publisher row id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub publisher_pk: String,
    /// Owner id.
    pub owner: String,
    /// Client project slug that owns this token/profile.
    pub project: String,
    /// Stable public publisher identity this token acts as.
    pub publisher_id: String,
    /// Human-facing publisher name.
    pub publisher_display_name: String,
    /// Stable public publisher URL.
    pub publisher_url: String,
    /// Publisher contact email.
    pub publisher_email: String,
    /// Display title.
    pub title: String,
    /// SHA-256 hash of the secret, never returned to clients.
    pub secret_hash: String,
    /// Granted scopes.
    pub scopes: Vec<String>,
    /// Whether this token grants hub read access.
    #[serde(default, skip_serializing)]
    pub scope_read: bool,
    /// Whether this token grants hub publish access.
    #[serde(default, skip_serializing)]
    pub scope_publish: bool,
    /// Whether this token grants hub manage access.
    #[serde(default, skip_serializing)]
    pub scope_manage: bool,
    /// Optional unix timestamp seconds.
    pub expires_at: Option<i64>,
    /// Optional unix timestamp seconds.
    pub last_used_at: Option<i64>,
    /// Optional unix timestamp seconds.
    pub revoked_at: Option<i64>,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

impl HubToken {
    /// Returns whether the token grants the required hub scope.
    pub fn grants_scope(&self, required_scope: &str) -> bool {
        match required_scope.trim() {
            "hub:read" => self.scope_read,
            "hub:publish" => self.scope_publish,
            "hub:manage" => self.scope_manage,
            _ => false,
        }
    }
}

/// Request to create one hub token.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CreateHubTokenRequest {
    /// Stable public publisher identity.
    pub publisher_id: String,
    /// Display title.
    pub title: String,
    /// Granted scopes.
    #[serde(default)]
    pub scopes: Vec<String>,
    /// Optional unix timestamp seconds.
    pub expires_at: Option<i64>,
}

/// Project-scoped assistant runtime configuration (used by Zebtune/chat assistant).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectAssistantConfig {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Credential id for high-level reasoning/planning model.
    pub llm_high_credential_id: Option<String>,
    /// Credential id for general/cheap model.
    pub llm_general_credential_id: Option<String>,
    /// Max execution steps per request.
    pub max_steps: u32,
    /// Max replan attempts.
    pub max_replans: u32,
    /// Whether assistant is enabled for this project.
    pub enabled: bool,
    /// Number of user+assistant pairs to persist as server-side chat history (default 10).
    pub chat_history_pairs: u32,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Atomic project-scoped permission used by REST, MCP, and internal assistants.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[serde(rename_all = "snake_case")]
pub enum ProjectCapability {
    ProjectRead,
    /// Destroying the project itself.
    ///
    /// The one thing an Owner has that a Maintainer does not. Without it the
    /// two roles resolved to exactly the same 29 capabilities, and deletion was
    /// guarded by comparing the session's name to the namespace owner — a
    /// string check outside the policy system, which no binding could grant and
    /// no role could describe.
    ProjectDelete,
    MembersRead,
    MembersWrite,
    CredentialsRead,
    CredentialsWrite,
    TemplatesRead,
    TemplatesWrite,
    TemplatesCreate,
    TemplatesDelete,
    TemplatesMove,
    TemplatesDiagnostics,
    PipelinesRead,
    PipelinesWrite,
    PipelinesCreate,
    PipelinesDelete,
    PipelinesMove,
    PipelinesExecute,
    FilesRead,
    FilesWrite,
    FilesDelete,
    TablesRead,
    TablesWrite,
    LibrariesRead,
    LibrariesInstall,
    LibrariesRemove,
    SettingsRead,
    SettingsWrite,
    McpSessionCreate,
    McpSessionRevoke,
}

impl ProjectCapability {
    /// Stable string id used by policy payloads and UI.
    pub fn key(self) -> &'static str {
        match self {
            Self::ProjectRead => "project.read",
            Self::ProjectDelete => "project.delete",
            Self::MembersRead => "members.read",
            Self::MembersWrite => "members.write",
            Self::CredentialsRead => "credentials.read",
            Self::CredentialsWrite => "credentials.write",
            Self::TemplatesRead => "templates.read",
            Self::TemplatesWrite => "templates.write",
            Self::TemplatesCreate => "templates.create",
            Self::TemplatesDelete => "templates.delete",
            Self::TemplatesMove => "templates.move",
            Self::TemplatesDiagnostics => "templates.diagnostics",
            Self::PipelinesRead => "pipelines.read",
            Self::PipelinesWrite => "pipelines.write",
            Self::PipelinesCreate => "pipelines.create",
            Self::PipelinesDelete => "pipelines.delete",
            Self::PipelinesMove => "pipelines.move",
            Self::PipelinesExecute => "pipelines.execute",
            Self::FilesRead => "files.read",
            Self::FilesWrite => "files.write",
            Self::FilesDelete => "files.delete",
            Self::TablesRead => "tables.read",
            Self::TablesWrite => "tables.write",
            Self::LibrariesRead => "libraries.read",
            Self::LibrariesInstall => "libraries.install",
            Self::LibrariesRemove => "libraries.remove",
            Self::SettingsRead => "settings.read",
            Self::SettingsWrite => "settings.write",
            Self::McpSessionCreate => "mcp.session.create",
            Self::McpSessionRevoke => "mcp.session.revoke",
        }
    }

    /// Parse from stable string key.
    pub fn from_key(key: &str) -> Option<Self> {
        match key {
            "project.read" => Some(Self::ProjectRead),
            "members.read" => Some(Self::MembersRead),
            "members.write" => Some(Self::MembersWrite),
            "credentials.read" => Some(Self::CredentialsRead),
            "credentials.write" => Some(Self::CredentialsWrite),
            "templates.read" => Some(Self::TemplatesRead),
            "templates.write" => Some(Self::TemplatesWrite),
            "templates.create" => Some(Self::TemplatesCreate),
            "templates.delete" => Some(Self::TemplatesDelete),
            "templates.move" => Some(Self::TemplatesMove),
            "templates.diagnostics" => Some(Self::TemplatesDiagnostics),
            "pipelines.read" => Some(Self::PipelinesRead),
            "pipelines.write" => Some(Self::PipelinesWrite),
            "pipelines.create" => Some(Self::PipelinesCreate),
            "pipelines.delete" => Some(Self::PipelinesDelete),
            "pipelines.move" => Some(Self::PipelinesMove),
            "pipelines.execute" => Some(Self::PipelinesExecute),
            "files.read" => Some(Self::FilesRead),
            "files.write" => Some(Self::FilesWrite),
            "files.delete" => Some(Self::FilesDelete),
            "tables.read" => Some(Self::TablesRead),
            "tables.write" => Some(Self::TablesWrite),
            "libraries.read" => Some(Self::LibrariesRead),
            "libraries.install" => Some(Self::LibrariesInstall),
            "libraries.remove" => Some(Self::LibrariesRemove),
            "settings.read" => Some(Self::SettingsRead),
            "settings.write" => Some(Self::SettingsWrite),
            "mcp.session.create" => Some(Self::McpSessionCreate),
            "mcp.session.revoke" => Some(Self::McpSessionRevoke),
            _ => None,
        }
    }

    /// All capabilities — used when auto-creating an MCP session on first activation.
    pub fn all() -> Vec<Self> {
        vec![
            Self::ProjectRead,
            Self::ProjectDelete,
            Self::MembersRead,
            Self::MembersWrite,
            Self::CredentialsRead,
            Self::CredentialsWrite,
            Self::TemplatesRead,
            Self::TemplatesWrite,
            Self::TemplatesCreate,
            Self::TemplatesDelete,
            Self::TemplatesMove,
            Self::TemplatesDiagnostics,
            Self::PipelinesRead,
            Self::PipelinesWrite,
            Self::PipelinesCreate,
            Self::PipelinesDelete,
            Self::PipelinesMove,
            Self::PipelinesExecute,
            Self::FilesRead,
            Self::FilesWrite,
            Self::FilesDelete,
            Self::TablesRead,
            Self::TablesWrite,
            Self::LibrariesRead,
            Self::LibrariesInstall,
            Self::LibrariesRemove,
            Self::SettingsRead,
            Self::SettingsWrite,
            Self::McpSessionCreate,
            Self::McpSessionRevoke,
        ]
    }
}

/// Product-facing managed role presets for project membership.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum ProjectAccessRolePreset {
    Guest,
    #[default]
    Reporter,
    Developer,
    Maintainer,
    Owner,
}

impl ProjectAccessRolePreset {
    /// Stable preset id used for storage and API transport.
    pub const fn key(self) -> &'static str {
        match self {
            Self::Guest => "guest",
            Self::Reporter => "reporter",
            Self::Developer => "developer",
            Self::Maintainer => "maintainer",
            Self::Owner => "owner",
        }
    }

    /// Human-readable title for settings and invite UI.
    pub const fn title(self) -> &'static str {
        match self {
            Self::Guest => "Guest",
            Self::Reporter => "Reporter",
            Self::Developer => "Developer",
            Self::Maintainer => "Maintainer",
            Self::Owner => "Owner",
        }
    }

    /// Managed policy id emitted by the role preset layer.
    pub const fn policy_id(self) -> &'static str {
        self.key()
    }
}

/// One explicit project member row.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectMember {
    /// Stable internal project id.
    #[serde(default)]
    pub project_id: String,
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Public user slug receiving membership.
    pub user_id: String,
    /// Stable internal user id receiving membership.
    #[serde(default)]
    pub member_user_id: String,
    /// Managed role preset.
    pub role_preset: ProjectAccessRolePreset,
    /// Extra policy ids layered on top of the role preset.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub custom_policy_ids: Vec<String>,
    /// Optional MCP capability ceiling for future per-user MCP sessions.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub mcp_capability_ceiling: Vec<ProjectCapability>,
    /// Acting user that created or last updated the row.
    #[serde(default)]
    pub created_by: String,
    /// Stable internal actor user id.
    #[serde(default)]
    pub created_by_user_id: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Invite lifecycle state.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum ProjectInviteStatus {
    #[default]
    Pending,
    Accepted,
    Revoked,
    Expired,
}

impl ProjectInviteStatus {
    /// Stable storage key, and what an error message calls this state.
    pub fn key(self) -> &'static str {
        match self {
            Self::Pending => "pending",
            Self::Accepted => "accepted",
            Self::Revoked => "revoked",
            Self::Expired => "expired",
        }
    }
}

/// One pending or historical invite row for project collaboration.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectInvite {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Stable invite id.
    pub invite_id: String,
    /// User id being invited.
    pub target_user: String,
    /// Managed role preset to grant on acceptance.
    pub role_preset: ProjectAccessRolePreset,
    /// Extra policy ids to apply on acceptance.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub custom_policy_ids: Vec<String>,
    /// Optional MCP capability ceiling to apply on acceptance.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub mcp_capability_ceiling: Vec<ProjectCapability>,
    /// Optional human note attached to the invite.
    #[serde(default)]
    pub note: String,
    /// Inviting actor user id.
    #[serde(default)]
    pub invited_by: String,
    /// Invite lifecycle state.
    #[serde(default)]
    pub status: ProjectInviteStatus,
    /// Optional expiry timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<i64>,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Create/update payload for one explicit project member.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct UpsertProjectMemberRequest {
    /// User id receiving membership.
    pub user_id: String,
    /// Managed role preset.
    pub role_preset: ProjectAccessRolePreset,
    /// Extra policy ids beyond the managed role preset.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub custom_policy_ids: Vec<String>,
    /// Optional MCP capability ceiling for this member.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub mcp_capability_ceiling: Vec<ProjectCapability>,
}

/// Create payload for one project invite.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CreateProjectInviteRequest {
    /// Target user id.
    pub target_user: String,
    /// Managed role preset proposed by the invite.
    pub role_preset: ProjectAccessRolePreset,
    /// Extra policy ids to layer on top of the role preset.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub custom_policy_ids: Vec<String>,
    /// Optional MCP capability ceiling for the invited user.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub mcp_capability_ceiling: Vec<ProjectCapability>,
    /// Optional note shown in invite listings.
    #[serde(default)]
    pub note: String,
    /// Optional invite expiry timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<i64>,
}

/// Project policy bundle stored in metadata and reused by users, MCP sessions, and assistants.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectPolicy {
    /// Stable internal project id.
    #[serde(default)]
    pub project_id: String,
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Stable policy id (`viewer`, `editor`, `owner`, ...).
    pub policy_id: String,
    /// Display label.
    pub title: String,
    /// Capability bundle.
    pub capabilities: Vec<ProjectCapability>,
    /// Whether this policy is platform-managed.
    pub managed: bool,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Subject kind bound to one project policy.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[serde(rename_all = "snake_case")]
pub enum ProjectSubjectKind {
    User,
    McpSession,
    AssistantProfile,
}

impl ProjectSubjectKind {
    /// Stable string id for storage and transport.
    pub fn key(self) -> &'static str {
        match self {
            Self::User => "user",
            Self::McpSession => "mcp_session",
            Self::AssistantProfile => "assistant_profile",
        }
    }
}

/// One project-level subject -> policy binding.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectPolicyBinding {
    /// Stable internal project id.
    #[serde(default)]
    pub project_id: String,
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Subject kind (`user`, `mcp_session`, `assistant_profile`).
    pub subject_kind: ProjectSubjectKind,
    /// Stable subject id.
    pub subject_id: String,
    /// Bound policy id.
    pub policy_id: String,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// Runtime subject passed into authorization checks so REST, MCP, and assistant paths
/// share the same policy gate.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectAccessSubject {
    /// Subject kind.
    pub kind: ProjectSubjectKind,
    /// Stable subject id.
    pub id: String,
}

impl ProjectAccessSubject {
    /// Creates a user subject.
    pub fn user(owner: &str) -> Self {
        Self {
            kind: ProjectSubjectKind::User,
            id: slug_segment(owner),
        }
    }

    /// Creates an MCP session subject.
    pub fn mcp_session(token: &str) -> Self {
        Self {
            kind: ProjectSubjectKind::McpSession,
            id: token.to_string(),
        }
    }
}

/// Pipeline metadata catalog entry stored in platform-level metadata DB.
///
/// The pipeline source file is stored under one project `app/` workspace
/// (git-sync friendly). This metadata is the fast index used by platform UI.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineMeta {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Pipeline id/name.
    pub name: String,
    /// Optional display title.
    pub title: String,
    /// Logical virtual folder path (for registry hierarchy), canonicalized.
    pub virtual_path: String,
    /// Relative source file path under project `app/` root.
    pub file_rel_path: String,
    /// Optional human-readable description.
    pub description: String,
    /// Trigger kind (`webhook`, `schedule`, `function`, ...).
    pub trigger_kind: String,
    /// Stable content hash for change tracking.
    pub hash: String,
    /// Activated production hash. When this differs from `hash`, the working
    /// tree has draft changes that are not promoted to runtime yet.
    pub active_hash: Option<String>,
    /// Unix timestamp seconds when the current active hash was promoted.
    pub activated_at: Option<i64>,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
}

/// One project doc file/folder in app/docs (ERD, README.md, AGENTS.md, use cases, etc.).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectDocItem {
    /// Relative path under app/docs.
    pub path: String,
    /// Display name (file or folder name).
    pub name: String,
    /// "file" or "folder".
    pub kind: String,
}

/// One agent doc entry (AGENTS.md, SOUL.md, MEMORY.md).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct AgentDocItem {
    /// File name (e.g. "AGENTS.md").
    pub name: String,
    /// Whether the user can edit this doc via REST (false for MEMORY.md — agent-only).
    pub user_editable: bool,
}

/// One breadcrumb segment in pipeline registry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineBreadcrumb {
    /// Display name.
    pub name: String,
    /// Link to this level.
    pub path: String,
    /// Whether a slash separator should appear before this segment.
    pub show_divider: bool,
}

/// One child folder shown in pipeline registry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineFolderItem {
    /// Folder segment name.
    pub name: String,
    /// Link to drill-down into this folder.
    pub path: String,
    /// True for reserved folders (assets, styles) — pinned at the bottom of the registry list.
    pub is_special: bool,
}

/// One template/script/style file shown in the pipeline registry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct RegistryFileItem {
    /// File name including extension (e.g. `home.tsx`).
    pub name: String,
    /// Path relative to `repo/` root (e.g. `pipelines/pages/home.tsx`).
    pub rel_path: String,
    /// File kind: `"template"` (.tsx), `"script"` (.ts), `"style"` (.css).
    pub kind: String,
    /// URL to open this file in the template editor.
    pub edit_href: String,
    /// Git status code if dirty.
    pub git_status: Option<String>,
}

/// One pipeline item shown at one registry level.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineRegistryItem {
    /// Pipeline name/id.
    pub name: String,
    /// Optional title.
    pub title: String,
    /// Description.
    pub description: String,
    /// Trigger kind.
    pub trigger_kind: String,
    /// Source file path under `app/`.
    pub file_rel_path: String,
    /// True when pipeline has an active hash matching current hash.
    pub is_active: bool,
    /// True when pipeline has an active hash but it differs from current hash (draft changes).
    pub has_draft: bool,
    /// Git status code (e.g. "M", "??", "D") if file is dirty, otherwise None.
    pub git_status: Option<String>,
}

/// Pipeline registry listing payload for one project + folder path.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineRegistryListing {
    /// Canonical current virtual path (`/` or `/a/b`).
    pub current_path: String,
    /// Breadcrumbs from root to current path.
    pub breadcrumbs: Vec<PipelineBreadcrumb>,
    /// Immediate child folders (sorted: normal first, special last).
    pub folders: Vec<PipelineFolderItem>,
    /// Pipeline entries located exactly at `current_path`.
    pub pipelines: Vec<PipelineRegistryItem>,
    /// Template/script/style files physically at `current_path`.
    pub files: Vec<RegistryFileItem>,
}

/// API payload used to create/update one pipeline definition.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct UpsertPipelineDefinitionRequest {
    /// Stable file-relative path under `repo/` (e.g. `"pipelines/api/my-hook.zf.json"`).
    /// This is the single canonical identifier — name and virtual_path are derived from it.
    pub file_rel_path: String,
    /// Optional display title.
    #[serde(default)]
    pub title: String,
    /// Optional human-readable description.
    #[serde(default)]
    pub description: String,
    /// Trigger kind (`webhook`, `schedule`, `function`, ...).
    #[serde(default)]
    pub trigger_kind: String,
    /// Full pipeline source (`*.zf.json`).
    pub source: String,
}

/// API payload used to delete one pipeline by its stable file_rel_path.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DeletePipelineRequest {
    /// Relative path of the pipeline source file under `repo/`.
    pub file_rel_path: String,
}

/// API payload for committing repo changes via git.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct GitCommitRequest {
    /// File paths relative to `repo/` to stage and commit.
    pub files: Vec<String>,
    /// Commit message.
    pub message: String,
    /// Whether to push after committing.
    #[serde(default)]
    pub push: bool,
    /// Credential ID to use for authenticated push (optional).
    pub credential_id: Option<String>,
    /// Remote repository URL for authenticated push (optional).
    pub repo_url: Option<String>,
    /// Branch to push to (optional, defaults to current branch).
    pub branch: Option<String>,
}

/// Request body for `PUT /api/projects/{owner}/{project}/settings/{section}`.
///
/// Wraps the section-specific data alongside a git commit message.
/// The handler writes the section to `zebflow.yaml` then commits the file.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpdateSettingsSectionRequest {
    /// Git commit message. Shown in the commit dialog before save. Sections
    /// stored in `zebflow.yaml` commit with it; instance-side sections
    /// (`addressing`) have nothing to commit and send none.
    #[serde(default)]
    pub commit_message: String,
    /// Section-specific payload. Deserialized per `{section}`.
    pub data: serde_json::Value,
}

/// API payload used to target one pipeline by its stable file path.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PipelineLocateRequest {
    /// Stable file-relative path under `repo/` (e.g. `"pipelines/api/my-hook.zf.json"`).
    pub file_rel_path: String,
}

/// Trigger type used for explicit pipeline execution calls.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum PipelineExecuteTrigger {
    Webhook,
    Schedule,
    Manual,
}

/// API payload used to execute one active pipeline with explicit trigger context.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ExecutePipelineRequest {
    /// Stable file-relative path under `repo/` (e.g. `"pipelines/api/my-hook.zf.json"`).
    pub file_rel_path: String,
    /// Trigger mode to validate against active trigger nodes. Optional: when
    /// absent, `manual` is inferred — unless the graph's first trigger is a
    /// webhook, in which case the run is validated as `webhook` against that
    /// trigger's own path and method, as if the caller had spelled them out.
    #[serde(default)]
    pub trigger: Option<PipelineExecuteTrigger>,
    /// Optional webhook path matcher.
    #[serde(default)]
    pub webhook_path: Option<String>,
    /// Optional webhook method matcher.
    #[serde(default)]
    pub webhook_method: Option<String>,
    /// Optional schedule cron matcher.
    #[serde(default)]
    pub schedule_cron: Option<String>,
    /// Request input payload passed to pipeline execution.
    #[serde(default)]
    pub input: serde_json::Value,
}

/// Payload used to create/update one project doc file under `app/docs`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct UpsertProjectDocRequest {
    /// Relative path under `app/docs`.
    pub path: String,
    /// Full file content.
    #[serde(default)]
    pub content: String,
}

/// Payload used to create one project docs folder under `repo/docs`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CreateProjectDocFolderRequest {
    /// Relative folder path under `repo/docs`.
    pub path: String,
}

/// Payload used to move one project docs file or folder.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectDocMoveRequest {
    /// Existing relative path under `repo/docs`.
    pub from_path: String,
    /// Destination parent folder under `repo/docs`.
    pub to_parent_path: String,
}

/// One template tree row for the templates workspace.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateTreeItem {
    /// Display name.
    pub name: String,
    /// Relative path under `app/templates`.
    pub rel_path: String,
    /// `folder` or `file`.
    pub kind: String,
    /// Nesting depth from template root.
    pub depth: usize,
    /// File classification for icon/behavior hints.
    pub file_kind: String,
    /// Whether the entry is protected from destructive actions.
    pub is_protected: bool,
}

/// Template workspace listing for one project.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateWorkspaceListing {
    /// Relative path of the preferred initial file.
    pub default_file: Option<String>,
    /// The folder these rows are the contents of. Empty is the repository root.
    ///
    /// Echoed back so a client holding several folders can file the answer
    /// under the right key without remembering what it asked for.
    #[serde(default)]
    pub path: String,
    /// Flattened tree rows in display order.
    pub items: Vec<TemplateTreeItem>,
}

/// Which part of the repository tree a caller wants.
///
/// A sidebar asks for one folder at a time as the reader opens it; the
/// quick-open palette and the pipeline pages ask for all of it. Making that a
/// parameter rather than two endpoints means a screen can change its mind
/// without the server growing a second road.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct RepoTreeScope {
    /// Subtree root relative to `repo/`. Empty is the repository root.
    pub path: String,
    /// Levels to walk below `path`. `None` walks the whole subtree.
    pub depth: Option<usize>,
}

impl RepoTreeScope {
    /// The whole repository, however deep it goes.
    pub fn all() -> Self {
        Self {
            path: String::new(),
            depth: None,
        }
    }

    /// One folder's immediate children — what an expanding sidebar asks for.
    pub fn children_of(path: impl Into<String>) -> Self {
        Self {
            path: path.into(),
            depth: Some(1),
        }
    }
}

/// One file status row from the project git repository for templates.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateGitStatusItem {
    /// Relative path under `app/templates`.
    pub rel_path: String,
    /// Short git porcelain status such as `M`, `A`, `D`, `??`, or `R`.
    pub code: String,
}

/// Payload used to save one template file.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateSaveRequest {
    /// Relative path under `app/templates`.
    pub rel_path: String,
    /// Full file content.
    pub content: String,
}

/// Supported controlled template creation kinds.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum TemplateCreateKind {
    /// `templates/pages/*.tsx`
    Page,
    /// `templates/components/*.tsx`
    Component,
    /// `templates/scripts/*.ts`
    Script,
    /// arbitrary folder inside `templates/`
    Folder,
}

/// Payload used to create one controlled template entry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateCreateRequest {
    /// Creation kind.
    pub kind: TemplateCreateKind,
    /// Human-entered base name.
    pub name: String,
    /// Optional parent folder under `app/templates`.
    pub parent_rel_path: Option<String>,
}

/// Payload used to move one template entry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateMoveRequest {
    /// Existing relative path under `app/templates`.
    pub from_rel_path: String,
    /// Destination parent folder under `app/templates`.
    pub to_parent_rel_path: String,
}

/// Basic template file response used by the web editor.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateFilePayload {
    /// Relative path under `app/templates`.
    pub rel_path: String,
    /// Display filename.
    pub name: String,
    /// File classification.
    pub file_kind: String,
    /// Full file content.
    pub content: String,
    /// Line count.
    pub line_count: usize,
    /// Whether the entry is protected from destructive actions.
    pub is_protected: bool,
}

/// Request payload used to compile one current template buffer.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateCompileRequest {
    /// Relative path under `app/templates`.
    pub rel_path: String,
    /// Unsaved editor content to compile.
    pub content: String,
}

/// One platform-facing template compile diagnostic.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateDiagnostic {
    /// Stable diagnostic code.
    pub code: String,
    /// Human-readable message.
    pub message: String,
    /// `error` or `warning`.
    pub severity: String,
    /// Optional zero-based source start offset.
    pub from: Option<usize>,
    /// Optional zero-based source end offset.
    pub to: Option<usize>,
}

/// Compile result returned to the web editor.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TemplateCompileResponse {
    /// Whether compile completed without a hard failure.
    pub ok: bool,
    /// Diagnostics emitted by the compile path.
    pub diagnostics: Vec<TemplateDiagnostic>,
}

/// One attribute definition in a Simple Table collection schema.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CollectionAttribute {
    /// Field name (slug).
    pub name: String,
    /// Data kind: `string` | `number` | `boolean` | `text` | `json` | `vector` | `geo`.
    pub kind: String,
    /// Active index types: `hash` | `range` | `fulltext` | `vector` | `spatial`.
    #[serde(default)]
    pub index_types: Vec<String>,
}

/// One managed Simple Table definition stored inside the project runtime DB.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct SimpleTableDefinition {
    /// Stable table slug.
    pub table: String,
    /// Backing collection name.
    pub collection: String,
    /// Attribute schema definitions.
    #[serde(default)]
    pub attributes: Vec<CollectionAttribute>,
    /// Hash indexed payload fields (exact equality).
    #[serde(default)]
    pub hash_indexed_fields: Vec<String>,
    /// Range indexed payload fields (ordered scans).
    #[serde(default)]
    pub range_indexed_fields: Vec<String>,
    /// Full-text indexed payload fields.
    #[serde(default)]
    pub fulltext_fields: Vec<String>,
    /// Vector indexed payload fields (semantic similarity).
    #[serde(default)]
    pub vector_fields: Vec<String>,
    /// Spatial indexed payload fields (geo queries).
    #[serde(default)]
    pub spatial_fields: Vec<String>,
    /// Live row count.
    pub row_count: usize,
}

/// One generation of the credential encryption keyring.
///
/// Never carries key material — only which generations exist and which one new
/// writes use. The instance key is not in the catalog and is not in any API.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CredentialKeyGeneration {
    /// The number every `zfc1:<key_id>:…` envelope written under it names.
    pub key_id: u32,
    /// When this generation was minted.
    pub created_at: i64,
    /// Whether new writes use it.
    pub current: bool,
}

/// The state of this instance's credential encryption keyring.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CredentialKeyringReport {
    /// `file` or `environment` — where the instance key came from.
    pub source: String,
    /// Where the instance key file is, whether or not it is the source in use.
    pub key_file: String,
    /// The generation new writes use.
    pub current_key_id: u32,
    /// Every generation, oldest first.
    pub generations: Vec<CredentialKeyGeneration>,
}

/// What a re-encryption sweep did.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CredentialSweepReport {
    /// Generation everything now sits under.
    pub key_id: u32,
    /// Credentials looked at.
    pub examined: usize,
    /// Credentials rewritten under [`Self::key_id`].
    pub rewritten: usize,
    /// Of those, ones that had been stored as plaintext before this release.
    pub migrated_from_plaintext: usize,
    /// Whether the catalog file was rebuilt afterwards.
    ///
    /// Re-encrypting a row overwrites the *row*; SQLite keeps the page the old
    /// bytes were on until it reuses it, and a WAL frame keeps them longer
    /// still. That is invisible to every query and perfectly visible to
    /// `strings catalog.db`, which is the exact reader this feature exists to
    /// defeat — so the sweep checkpoints and `VACUUM`s. Best effort: a rebuild
    /// that could not take the lock leaves the re-encryption done and says so
    /// here rather than failing the operation.
    pub compacted: bool,
}

/// Create payload for one project credential.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct UpsertProjectCredentialRequest {
    /// Stable credential id.
    pub credential_id: String,
    /// Display title.
    pub title: String,
    /// Driver/kind (`postgres`, `openai`, ...).
    pub kind: String,
    /// Secret payload.
    #[serde(default)]
    pub secret: serde_json::Value,
    /// Optional freeform notes.
    #[serde(default)]
    pub notes: String,
}

/// Create/update payload for one project DB connection.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct UpsertProjectDbConnectionRequest {
    /// Stable route slug.
    pub connection_slug: String,
    /// Display label.
    pub connection_label: String,
    /// Database kind (`sqlite`, `postgresql`, ...).
    pub database_kind: String,
    /// Optional linked credential id.
    pub credential_id: Option<String>,
    /// Optional kind-specific config payload.
    #[serde(default)]
    pub config: serde_json::Value,
}

/// Create/update payload for one project assistant config.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct UpsertProjectAssistantConfigRequest {
    /// Credential id for high-level reasoning/planning model.
    pub llm_high_credential_id: Option<String>,
    /// Credential id for general/cheap model.
    pub llm_general_credential_id: Option<String>,
    /// Max execution steps per request.
    pub max_steps: Option<u32>,
    /// Max replan attempts.
    pub max_replans: Option<u32>,
    /// Whether assistant is enabled for this project.
    pub enabled: Option<bool>,
    /// Number of user+assistant pairs to persist as server-side chat history.
    pub chat_history_pairs: Option<u32>,
}

/// Test payload for one project DB connection (existing or draft).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct TestProjectDbConnectionRequest {
    /// Existing connection slug to test.
    pub connection_slug: Option<String>,
    /// Optional draft database kind (used when slug is not provided).
    pub database_kind: Option<String>,
    /// Optional draft credential id (used when slug is not provided).
    pub credential_id: Option<String>,
    /// Optional draft config payload.
    #[serde(default)]
    pub config: serde_json::Value,
}

/// Describe payload for one DB connection runtime endpoint.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct DescribeProjectDbConnectionRequest {
    /// Describe scope (`tree`, `schemas`, `tables`, `functions`, `columns`).
    pub scope: Option<String>,
    /// Optional schema filter.
    pub schema: Option<String>,
    /// Filter to a specific table for column-level detail.
    /// Format: "schema.table" (e.g. "academic.staff") or just "table" for public schema.
    /// When set, scope is treated as "columns" automatically.
    #[serde(default)]
    pub table: Option<String>,
    /// Whether system schemas should be included when supported.
    pub include_system: Option<bool>,
}

/// One node in DB object tree.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DbObjectNode {
    /// Object kind (`schema`, `table`, `function`).
    pub kind: String,
    /// Object name.
    pub name: String,
    /// Optional schema name.
    pub schema: Option<String>,
    /// Optional children.
    #[serde(default)]
    pub children: Vec<DbObjectNode>,
    /// Optional metadata.
    #[serde(default)]
    pub meta: serde_json::Value,
}

/// One column type an engine actually offers.
///
/// The studio's type picker is built from these, so a PostgreSQL column is
/// declared `int4` or `timestamptz` — the engine's own words — rather than a
/// generic kind that has to be translated twice and loses meaning both ways.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DbTypeDef {
    /// The name written into DDL, lowercase (`varchar`, `int4`, `jsonb`).
    pub name: String,
    /// Grouping for the picker and the column icon.
    pub family: DbTypeFamily,
    /// Whether the type takes arguments, as `varchar(255)` or `numeric(10,2)`.
    pub parameterized: bool,
    /// Shown beside the name where the name alone is cryptic.
    pub note: String,
}

/// What a column type is for. Drives the picker's grouping and the icon the
/// column grid shows, and is the granularity at which a type change is judged
/// safe or refused.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum DbTypeFamily {
    #[default]
    Text,
    Number,
    Boolean,
    Json,
    DateTime,
    Uuid,
    Binary,
    Geometry,
    Vector,
    Other,
}

/// What one database engine supports, declared by its driver.
///
/// The data-management UI renders panels from this and never branches on
/// `database_kind`. Adding an engine is writing a driver, not editing the UI.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DbCapabilities {
    /// Rows can be edited in place in the grid.
    pub inline_edit: bool,
    /// Tables can be created from the UI.
    pub create_table: bool,
    /// Tables can be dropped from the UI.
    pub drop_table: bool,
    /// The engine exposes a health/sync/compact surface.
    pub maintenance: bool,
    /// The engine namespaces tables under schemas.
    pub schemas: bool,
    /// Attributes and index kinds can be edited after a table exists.
    pub edit_table_properties: bool,
    /// The column that identifies one row, for editing and deletion.
    ///
    /// Sekejap answers `_key`; SQL engines answer the primary key this
    /// platform creates. The studio reads this rather than assuming a name,
    /// because a row it cannot address is a row it cannot change.
    pub row_identity: String,
    /// The engine can store and return geometry.
    pub geo: bool,
    /// How this engine relates rows to each other.
    pub relations: DbRelationStyle,
}

impl Default for DbCapabilities {
    /// The conservative set: read and query only.
    ///
    /// A new driver that declares nothing gets a working read-only surface
    /// rather than buttons that fail when pressed.
    fn default() -> Self {
        Self {
            inline_edit: false,
            create_table: false,
            drop_table: false,
            maintenance: false,
            schemas: false,
            edit_table_properties: false,
            row_identity: String::new(),
            geo: false,
            relations: DbRelationStyle::None,
        }
    }
}

/// How an engine expresses relationships between rows.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum DbRelationStyle {
    /// No relationship surface.
    #[default]
    None,
    /// Declared foreign keys, as in SQL engines.
    ForeignKey,
    /// Free edges between rows, as in sekejap.
    Graph,
}

/// Describe result for one DB connection.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProjectDbConnectionDescribeResult {
    /// Stable connection id.
    pub connection_id: String,
    /// Stable route slug.
    pub connection_slug: String,
    /// Database kind (`sqlite`, `postgresql`, ...).
    pub database_kind: String,
    /// Effective scope.
    pub scope: String,
    /// What this engine supports. Stamped by the runtime from the driver, so a
    /// driver cannot forget to report it.
    #[serde(default)]
    pub capabilities: DbCapabilities,
    /// Object tree/list payload.
    #[serde(default)]
    pub nodes: Vec<DbObjectNode>,
}

/// Query payload for one DB connection runtime endpoint.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct QueryProjectDbConnectionRequest {
    /// SQL text (for SQL engines like PostgreSQL).
    #[serde(default)]
    pub sql: String,
    /// Positional bind parameters.
    #[serde(default)]
    pub params: Vec<serde_json::Value>,
    /// Optional table identifier for engines that do not use SQL directly.
    pub table: Option<String>,
    /// Optional max rows to return.
    pub limit: Option<usize>,
    /// Whether write statements are blocked (defaults true).
    pub read_only: Option<bool>,
}

/// One query result column.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DbQueryColumn {
    /// Column name.
    pub name: String,
    /// Optional engine-native data type.
    pub data_type: Option<String>,
}

/// Query result for one DB connection.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProjectDbConnectionQueryResult {
    /// Stable connection id.
    pub connection_id: String,
    /// Stable route slug.
    pub connection_slug: String,
    /// Database kind (`sqlite`, `postgresql`, ...).
    pub database_kind: String,
    /// Returned columns.
    #[serde(default)]
    pub columns: Vec<DbQueryColumn>,
    /// Returned rows as column-aligned vectors.
    #[serde(default)]
    pub rows: Vec<Vec<serde_json::Value>>,
    /// Number of rows in this payload.
    pub row_count: usize,
    /// Whether payload was truncated due to row limit.
    pub truncated: bool,
    /// Optional affected rows for write statements.
    pub affected_rows: Option<u64>,
    /// Query execution duration in milliseconds.
    pub duration_ms: u64,
}

/// Result payload returned by DB connection test endpoint.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProjectDbConnectionTestResult {
    /// Whether test passed.
    pub ok: bool,
    /// Human-friendly message.
    pub message: String,
    /// Optional details.
    pub details: serde_json::Value,
}

/// Create payload for one Simple Table.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CreateSimpleTableRequest {
    /// Stable table slug.
    pub table: String,
    /// Attribute schema definitions.
    #[serde(default)]
    pub attributes: Vec<CollectionAttribute>,
    /// Hash indexed payload fields.
    #[serde(default)]
    pub hash_indexed_fields: Vec<String>,
    /// Range indexed payload fields.
    #[serde(default)]
    pub range_indexed_fields: Vec<String>,
}

/// Update payload for an existing sekejap table (attributes + indexes).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct UpdateSimpleTableRequest {
    /// New attribute schema definitions (replaces existing).
    #[serde(default)]
    pub attributes: Vec<CollectionAttribute>,
    /// Hash indexed payload fields.
    #[serde(default)]
    pub hash_indexed_fields: Vec<String>,
    /// Range indexed payload fields.
    #[serde(default)]
    pub range_indexed_fields: Vec<String>,
}

/// Upsert payload for one Simple Table row.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct UpsertSimpleTableRowRequest {
    /// Target table slug.
    pub table: String,
    /// Stable row id within the table.
    pub row_id: String,
    /// Row payload.
    #[serde(default)]
    pub data: serde_json::Value,
}

/// Query payload for one Simple Table read.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct SimpleTableQueryRequest {
    /// Target table slug.
    pub table: String,
    /// Optional equality field name.
    pub where_field: Option<String>,
    /// Equality field value.
    pub where_value: Option<serde_json::Value>,
    /// Maximum rows to return.
    #[serde(default = "default_simple_table_limit")]
    pub limit: usize,
}

fn default_simple_table_limit() -> usize {
    100
}

/// Query result returned by project Simple Table management and nodes.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct SimpleTableQueryResult {
    /// Table definition.
    pub table: SimpleTableDefinition,
    /// Returned rows.
    pub rows: Vec<serde_json::Value>,
}

/// File-system tree returned for one project.
///
/// `data/` splits into four tiers (`project-directory.md` §3), and every tier
/// below `data_dir` is an accessor derived from it — the same pattern
/// `repo_source_dir()` and the other `repo_*` methods already use for `repo/`
/// — rather than a separately stored field, so there is exactly one place
/// that can disagree with the tree the contract draws.
#[derive(Debug, Clone)]
pub struct ProjectFileLayout {
    /// `{data_root}/users/{owner}/{project}`
    pub root: PathBuf,
    /// `.../data`
    pub data_dir: PathBuf,
    /// `.../files`
    pub files_dir: PathBuf,
    /// `.../repo` (git-sync workspace root).
    pub repo_dir: PathBuf,
    /// `.../repo/.git`
    pub repo_git_dir: PathBuf,
    /// `.../repo/zebflow.yaml` (non-sensitive project configuration, git-synced).
    pub project_config_file: PathBuf,
    /// The repository layout these paths project onto disk.
    ///
    /// Every directory inside `repo/` is derived from this rather than stored
    /// beside it, so an absolute path and the repository-relative rule that
    /// names it cannot disagree.
    pub repo_layout: ResolvedProjectLayout,
    /// The native store that owns this project's files: `spec.files.backend`
    /// resolved once, with everything opening it needs — the `files/`
    /// directory, or the bucket and the credential the instance selected for
    /// it (`data/store/files-backend.json`). Resolved here so that
    /// `open_files` cannot fail.
    pub file_store: FileStore,
}

impl ProjectFileLayout {
    /// Opens the native store that owns this project's files.
    ///
    /// Every caller that needs a project's bytes goes through here rather than
    /// naming an implementation, so a second backend is added in
    /// [`crate::zebfs::backend::open`] and nowhere else.
    pub fn open_files(&self) -> ZebFs {
        crate::zebfs::backend::open(&self.file_store)
    }

    /// The declared word for this project's store — what every FileRef written
    /// here carries in `backend`.
    pub fn file_backend(&self) -> FileBackend {
        self.file_store.backend()
    }

    /// The local directory behind this project's store, for the engines that
    /// stream from a file path — GDAL, DataFusion, the map server — and can
    /// only do so when there is one.
    ///
    /// A project whose files live in a bucket is refused by name, so no such
    /// engine silently reads or writes `files/`, which on that project is a
    /// scratch directory and not the store.
    pub fn local_files_dir(&self) -> Result<&Path, ZebFsError> {
        match &self.file_store {
            FileStore::Local(dir) => Ok(dir),
            FileStore::S3(config) => Err(ZebFsError::new(
                "ZEBFS_LOCAL_ONLY",
                format!(
                    "this project's files live in the bucket '{}', and this operation streams from local disk; it is not available on an object store yet",
                    config.bucket
                ),
            )),
        }
    }

    /// `.../repo/{source}` — unified source root: *.zf.json pipelines + *.tsx
    /// templates + *.ts scripts. Also the `@/` root for the RWE compiler.
    pub fn repo_source_dir(&self) -> PathBuf {
        self.repo_dir.join(&self.repo_layout.source)
    }

    /// `.../repo/{assets}` — files served under `/static/{owner}/{project}/...`.
    pub fn repo_static_dir(&self) -> PathBuf {
        self.repo_dir.join(&self.repo_layout.r#static)
    }

    /// `.../repo/{docs}` (project docs: ERD, README.md, use cases, etc.).
    pub fn repo_docs_dir(&self) -> PathBuf {
        self.repo_dir.join(&self.repo_layout.docs)
    }

    /// `.../repo/{node_interfaces}` — interfaces of the third-party nodes this
    /// project uses.
    ///
    /// These are `NodeDefinition` documents, not bundles. They let a graph stay
    /// readable and reimplementable on an instance where the bundle is absent.
    pub fn repo_node_interfaces_dir(&self) -> PathBuf {
        self.repo_dir.join(&self.repo_layout.node_interfaces)
    }

    /// `.../data/store` — durable, generated, irreplaceable. Back this up.
    pub fn data_store_dir(&self) -> PathBuf {
        self.data_dir.join("store")
    }

    /// `.../data/store/sekejap` — the project's database: WAL, indexes, snapshot.
    pub fn data_store_sekejap_dir(&self) -> PathBuf {
        self.data_store_dir().join("sekejap")
    }

    /// `.../data/store/local.db` — the project's SQLite runtime database.
    pub fn data_store_local_db_file(&self) -> PathBuf {
        self.data_store_dir().join("local.db")
    }

    /// `.../data/store/kv.db` — the project's durable `n.kv.*` state.
    ///
    /// `MemStateBus` (`src/infra/io/state/mem.rs`) builds this path itself
    /// from the data root because infra cannot see this type; the two sites
    /// are named in `project-directory.md` §5 so a layout change updates both.
    pub fn data_store_kv_db_file(&self) -> PathBuf {
        self.data_store_dir().join("kv.db")
    }

    /// `.../data/store/chat_history.json` — the project's assistant
    /// conversation history. User state, not cache: deleting it loses a
    /// conversation, so it lives in the `store` tier.
    pub fn data_store_chat_history_file(&self) -> PathBuf {
        self.data_store_dir().join("chat_history.json")
    }

    /// `.../data/store/assistant` — per-user assistant state.
    pub fn data_store_assistant_dir(&self) -> PathBuf {
        self.data_store_dir().join("assistant")
    }

    /// `.../data/store/assistant/{user_id}/memory.md` — one user's assistant
    /// memory. Machine-written by the assistant, irreplaceable, so `store`
    /// tier — deleting it loses everything the assistant learned.
    ///
    /// The format stays markdown: every reader and writer (MCP
    /// `docs_agent_read`/`docs_agent_write`, the assistant chat tools, the
    /// system-prompt embed) speaks markdown under the `MEMORY.md` doc name.
    /// Only the tier and the per-user keying changed with the move out of
    /// `data/cache/agent_docs/`.
    pub fn data_store_assistant_memory_file(&self, user_id: &str) -> PathBuf {
        self.data_store_assistant_dir()
            .join(slug_segment(user_id))
            .join("memory.md")
    }

    /// `.../data/cache` — disposable, rebuilds from `repo/`.
    pub fn data_cache_dir(&self) -> PathBuf {
        self.data_dir.join("cache")
    }

    /// `.../data/cache/pipelines` — materialized pipeline runtime (active
    /// snapshots compiled from `repo/`).
    pub fn data_cache_pipelines_dir(&self) -> PathBuf {
        self.data_cache_dir().join("pipelines")
    }

    /// `.../data/cache/agent_docs` (AGENTS.md, SOUL.md — agent context.
    /// MEMORY moved to the `store` tier: [`Self::data_store_assistant_memory_file`]).
    pub fn data_cache_agent_docs_dir(&self) -> PathBuf {
        self.data_cache_dir().join("agent_docs")
    }

    /// `.../data/cache/mapserver-artifacts` — generated map layer artifacts
    /// (chunked NDJSON + manifest per layer, `{instance}/{layer}/`). The
    /// engine builds them from the uploaded source in `files/mapserver/`, so
    /// they regenerate: CACHE, not OBJECT.
    pub fn data_cache_mapserver_artifacts_dir(&self) -> PathBuf {
        self.data_cache_dir().join("mapserver-artifacts")
    }

    /// First-touch tier move of `files/mapserver/.artifacts` onto its cache
    /// home `data/cache/mapserver-artifacts` (`instance-directory.md`). One
    /// atomic whole-directory rename; both-paths-present refuses rather than
    /// guesses, per `migrate_tier_entry`. Returns the cache root.
    pub fn ensure_mapserver_artifacts_home(&self) -> std::io::Result<PathBuf> {
        let new_root = self.data_cache_mapserver_artifacts_dir();
        crate::infra::io::durable::migrate_tier_entry(
            &self.files_dir.join("mapserver").join(".artifacts"),
            &new_root,
        )?;
        Ok(new_root)
    }

    /// Resolves a layer registry's stored artifact-manifest rel path to its
    /// absolute location under the cache root.
    ///
    /// Registry records written before the tier move carry
    /// `mapserver/.artifacts/{...}`; records written after carry
    /// `mapserver-artifacts/{...}`. Both are identifiers into the same moved
    /// tree — the registry (`{instance}.layers.json`, STORE) is not rewritten
    /// by the move, so both shapes must keep resolving.
    pub fn resolve_mapserver_artifact_path(&self, rel: &str) -> PathBuf {
        let rel = rel.trim_start_matches('/');
        if let Some(rest) = rel.strip_prefix("mapserver/.artifacts/") {
            self.data_cache_mapserver_artifacts_dir().join(rest)
        } else if let Some(rest) = rel.strip_prefix("mapserver-artifacts/") {
            self.data_cache_mapserver_artifacts_dir().join(rest)
        } else {
            // Unknown shape: resolve against files/ as before the move.
            self.files_dir.join(rel)
        }
    }

    /// `.../data/hub` — the INSTALLED tier: content unpacked from a hub or a
    /// local document (`instance-directory.md`). Removal is `uninstall`,
    /// recorded in `zeb.lock` — never a cleanup.
    pub fn data_hub_dir(&self) -> PathBuf {
        self.data_dir.join("hub")
    }

    /// `.../data/hub/nodes` — installed node bundles.
    ///
    /// These are materialized from `zeb.lock`, not authored, so they live with
    /// the machine's other derived state rather than in the source repository.
    /// A locked bundle's `entry` (`nodes/{slug}/definition.json`) resolves
    /// against [`Self::data_hub_dir`], so the recorded string survives the
    /// move from the pre-contract `data/nodes` home unchanged.
    pub fn data_hub_nodes_dir(&self) -> PathBuf {
        self.data_hub_dir().join("nodes")
    }

    /// `.../data/hub/rwe-libraries` — installed RWE libraries.
    ///
    /// Drawn by `instance-directory.md`; the writer arrives with library
    /// seeding. Scaffolded empty until then so the tree matches the contract.
    pub fn data_hub_rwe_libraries_dir(&self) -> PathBuf {
        self.data_hub_dir().join("rwe-libraries")
    }

    /// `.../data/recovery` — disposable, bounded. Migration safety copies,
    /// named with the date the migration ran (`project-directory.md` §5).
    pub fn data_recovery_dir(&self) -> PathBuf {
        self.data_dir.join("recovery")
    }

    /// `.../data/logs` — disposable, bounded. Invocation records, traces.
    pub fn data_logs_dir(&self) -> PathBuf {
        self.data_dir.join("logs")
    }
}

// ── Node package system ─────────────────────────────────────────────────────

/// Implementation type of one node in a bundle.
///
/// This is always derived from the node's [`RunBinding`]. It is never authored,
/// so a bundle cannot declare an implementation that disagrees with the artifact
/// the node actually points at.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum NodePackageSource {
    /// Composite node: the behavior is a function pipeline.
    Composite,
    /// WASM node: the behavior is an export in a compiled module.
    Wasm,
    /// Trigger node with no user code; the event payload passes through.
    Declarative,
}

impl NodePackageSource {
    /// Stable string used by the node API and UI.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Composite => "composite",
            Self::Wasm => "wasm",
            Self::Declarative => "declarative",
        }
    }
}

/// One compiled WASM artifact declared by a bundle.
///
/// The ABI belongs to the module because a bundle may carry artifacts compiled
/// at different times.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct WasmModuleSpec {
    /// Package-relative path of the module (e.g. `"wasm/ml.wasm"`).
    pub path: String,
    /// ABI identifier. Only `zebflow-wasm-json-v1` is accepted under v1.
    pub abi: String,
}

/// Where one node's code lives.
///
/// Exactly one form is valid: `function` names a key in `spec.functions`, or
/// `module` plus `export` names a key in `spec.modules` and a symbol inside it.
/// `export` is never optional, because a default symbol would make two WASM
/// nodes in one bundle resolve to the same entry point.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct RunBinding {
    /// Composite form: a key in `spec.functions`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub function: Option<String>,
    /// WASM form: a key in `spec.modules`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub module: Option<String>,
    /// WASM form: the exported symbol to call.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub export: Option<String>,
}

impl RunBinding {
    /// Implementation type implied by this binding, if it is well formed.
    pub fn source(&self) -> Option<NodePackageSource> {
        match (&self.function, &self.module, &self.export) {
            (Some(_), None, None) => Some(NodePackageSource::Composite),
            (None, Some(_), Some(_)) => Some(NodePackageSource::Wasm),
            _ => None,
        }
    }
}

/// Runtime-normalized manifest for one node from an installed `definition.json` bundle.
///
/// This is not an authoring or disk format. The registry derives it from the
/// canonical [`MultiNodePackageDefinition`] and uses it uniformly for composite
/// and WASM execution.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct NodePackageManifest {
    /// Implementation type, derived from `run`.
    pub source: NodePackageSource,
    /// `spec.package` of the bundle providing this node.
    ///
    /// Carried per node because the runtime resolves a manifest by kind and
    /// otherwise could not name the bundle a refusal came from.
    #[serde(default)]
    pub package: String,
    /// Package release version.
    pub version: String,
    /// External hosts the providing bundle declared in `spec.hosts`.
    ///
    /// Copied from the package because egress is enforced where a node runs,
    /// and the only thing in hand there is the manifest for one kind.
    #[serde(default)]
    pub hosts: Vec<String>,
    /// The node definition (same struct as native nodes).
    pub definition: crate::pipeline::NodeDefinition,
    /// Credential type definitions this node declares through `uses_credentials`.
    #[serde(default)]
    pub credentials: Vec<CredentialTypeDef>,
    /// Where this node's code lives. Absent only for a declarative trigger.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run: Option<RunBinding>,
    /// Trigger role configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trigger: Option<PackageTriggerConfig>,
    /// Lifecycle hooks. Valid only on a trigger node.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lifecycle: Option<PackageLifecycleConfig>,
    /// Function name → package-relative pipeline path.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub functions: BTreeMap<String, String>,
    /// Module name → compiled WASM artifact.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub modules: BTreeMap<String, WasmModuleSpec>,
}

impl NodePackageManifest {
    /// Name of the composite function this node runs, if it is a composite node.
    pub fn main_function(&self) -> Option<&str> {
        self.run.as_ref()?.function.as_deref()
    }

    /// Resolves the WASM module and export this node runs, if it is a WASM node.
    pub fn wasm_target(&self) -> Option<(&WasmModuleSpec, &str)> {
        let run = self.run.as_ref()?;
        let module = run.module.as_deref()?;
        let export = run.export.as_deref()?;
        Some((self.modules.get(module)?, export))
    }
}

/// Trigger role configuration for a node that starts a pipeline.
///
/// This declares a role, not an implementation. The inbound handler is the
/// node's `run` binding, which is why a WASM trigger is expressible.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PackageTriggerConfig {
    /// Trigger type: "webhook", "ws", "ws_client", "cron".
    #[serde(rename = "type")]
    pub trigger_type: String,
    /// Webhook path template with `{{ config_key }}` placeholders.
    /// E.g. `"/tg/{{ bot_credential_id }}"` resolves from node config.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path_template: Option<String>,
}

/// Lifecycle hooks for a trigger node. Each hook is a run binding, so composite
/// and WASM nodes have the same lifecycle capability.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct PackageLifecycleConfig {
    /// Runs when a pipeline using this trigger is activated.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_activate: Option<RunBinding>,
    /// Runs when a pipeline using this trigger is deactivated.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_deactivate: Option<RunBinding>,
}

/// Multi-node package definition (`definition.json` format).
///
/// A single file declaring N nodes, shared credentials, and reusable function pipelines.
/// The loader explodes this into N `NodePackageManifest` entries.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct MultiNodePackageDefinition {
    /// Package identifier. Owns the `n.x.{package_token}.` kind namespace.
    pub package: String,
    /// Release version, `major.minor.patch`.
    pub version: String,
    /// Human-readable title.
    pub title: String,
    /// Package description.
    #[serde(default)]
    pub description: String,
    /// Package-level icon path.
    #[serde(default)]
    pub icon: String,
    /// Credential kinds this package can use. Nodes opt in per entry.
    #[serde(default)]
    pub credentials: Vec<CredentialTypeDef>,
    /// External hosts this package is allowed to contact.
    ///
    /// Enforced at run time by [`crate::pipeline::security::BundleEgress`] over
    /// everything a bundle-provided node runs, inner nodes of a composite
    /// included. A non-empty list is an allowlist; an empty one restricts no
    /// host, because `#[serde(default)]` makes absent and empty the same bytes
    /// and a deny-all reading would break every bundle published before
    /// enforcement existed.
    ///
    /// Declaring nothing is not a way out. Every other guard the policy carries
    /// — refusing a node whose destination the guard cannot read — applies to a
    /// bundle that declared nothing exactly as it does to one that declared.
    #[serde(default)]
    pub hosts: Vec<String>,
    /// Function name → package-relative pipeline path.
    #[serde(default)]
    pub functions: BTreeMap<String, String>,
    /// Module name → compiled WASM artifact.
    #[serde(default)]
    pub modules: BTreeMap<String, WasmModuleSpec>,
    /// Node entries.
    pub nodes: Vec<MultiNodeEntry>,
}

/// A single node entry within a multi-node package.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct MultiNodeEntry {
    /// Node kind. Must be `n.x.{package_token}.{rest}`.
    pub kind: String,
    /// Node title.
    pub title: String,
    /// Node description.
    #[serde(default)]
    pub description: String,
    /// Per-node icon path (relative to package).
    #[serde(default)]
    pub icon: String,
    /// UI category for Project Studio node picker.
    #[serde(default)]
    pub ui_category: String,
    /// UI category label.
    #[serde(default)]
    pub ui_category_label: String,
    /// Credential kinds this node uses, declared in `spec.credentials`.
    #[serde(default)]
    pub uses_credentials: Vec<String>,
    /// Where this node's code lives. Required unless the node is a trigger.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run: Option<RunBinding>,
    /// Trigger role configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trigger: Option<PackageTriggerConfig>,
    /// Lifecycle hooks. Valid only alongside `trigger`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lifecycle: Option<PackageLifecycleConfig>,
    /// Node definition (pins, schema, fields, layout, dsl_flags).
    pub definition: MultiNodeEntryDefinition,
}

/// Partial node definition within a multi-node entry.
/// The full `NodeDefinition` is constructed by the loader, filling in kind/title/description
/// from the parent `MultiNodeEntry`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct MultiNodeEntryDefinition {
    #[serde(default)]
    pub input_pins: Vec<String>,
    #[serde(default)]
    pub output_pins: Vec<String>,
    #[serde(default)]
    pub config_schema: serde_json::Value,
    #[serde(default)]
    pub input_schema: serde_json::Value,
    #[serde(default)]
    pub output_schema: serde_json::Value,
    #[serde(default)]
    pub examples: Vec<crate::pipeline::NodeExample>,
    #[serde(default)]
    pub failure_semantics: Vec<crate::pipeline::NodeFailureSemantic>,
    #[serde(default)]
    pub fields: Vec<crate::pipeline::NodeFieldDef>,
    #[serde(default)]
    pub layout: Vec<crate::pipeline::model::LayoutItem>,
    #[serde(default)]
    pub dsl_flags: Vec<crate::pipeline::model::DslFlag>,
}

/// Runtime-enriched entry for an installed node package.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InstalledNodePackage {
    /// The slug (directory name under `data/hub/nodes/`).
    pub slug: String,
    /// Owner this package belongs to.
    pub owner: String,
    /// Project this package belongs to.
    pub project: String,
    /// Parsed manifest.
    pub manifest: NodePackageManifest,
    /// Absolute path to the package directory on disk.
    pub package_dir: String,
    /// Validated package-relative icon path for this node.
    pub icon_rel_path: Option<String>,
}

/// Request payload for user creation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateUserRequest {
    /// Target owner/user id.
    pub owner: String,
    /// Password.
    pub password: String,
    /// Role.
    #[serde(default = "default_member_role")]
    pub role: String,
    /// Display name for git commits.
    #[serde(default)]
    pub git_name: String,
    /// Email for git commits.
    #[serde(default)]
    pub git_email: String,
}

/// Self-service user settings payload.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct UpdateUserSettingsRequest {
    /// Display name for git commits.
    #[serde(default)]
    pub git_name: String,
    /// Email for git commits.
    #[serde(default)]
    pub git_email: String,
}

fn default_member_role() -> String {
    "member".to_string()
}

/// Source used to resolve one git author identity.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum GitIdentitySource {
    UserProfile,
    ProjectSettings,
    Fallback,
}

/// Concrete git identity chosen for one write action.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ResolvedGitIdentity {
    /// Resolved git author/committer name.
    pub name: String,
    /// Resolved git author/committer email.
    pub email: String,
    /// Source from which the identity was resolved.
    pub source: GitIdentitySource,
}

/// Runtime view of project configuration loaded from `repo/zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJson {
    #[serde(default)]
    pub metadata: ZebflowJsonMetadata,
    #[serde(default)]
    pub configs: ZebflowJsonConfigs,
    #[serde(default)]
    pub distribution: ZebflowJsonDistribution,
}

fn default_max_asset_size_mb() -> u32 {
    10
}

fn default_webhook_body_max_mb() -> u32 {
    100
}

pub const MAX_UPLOAD_SIZE_MB: u32 = 1024;

pub fn default_pipeline_node_timeout_secs() -> u64 {
    30
}

impl Default for ZebflowJson {
    fn default() -> Self {
        Self {
            metadata: ZebflowJsonMetadata::default(),
            configs: ZebflowJsonConfigs::default(),
            distribution: ZebflowJsonDistribution::default(),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonMetadata {
    #[serde(default)]
    pub title: String,
    #[serde(default)]
    pub description: String,
}

/// Repo-owned activation/bootstrap intent: which pipelines `zebflow.yaml`
/// asks the office to activate once the project's source is in place.
///
/// This is the project's own configuration, not a transfer format. It is read
/// by [`ProjectConfigurationSpec`](crate::contracts::kinds::ProjectConfigurationSpec)
/// and applied by the local repo refresh.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct ProjectBootstrapPlan {
    /// Pipeline glob patterns that should auto-activate after clone/import.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub activate: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonConfigs {
    /// Skipped when nothing is declared, so an undeclared layout stays absent
    /// from every serialization of this view rather than appearing as an empty
    /// object that was never authored.
    #[serde(default, skip_serializing_if = "ZebflowJsonLayout::is_undeclared")]
    pub layout: ZebflowJsonLayout,
    #[serde(default)]
    pub rwe: ZebflowJsonRwe,
    #[serde(default)]
    pub pipelines: ZebflowJsonPipelines,
    #[serde(default)]
    pub runtime: ProjectRuntimeProfile,
    #[serde(default)]
    pub bootstrap: ProjectBootstrapPlan,
    #[serde(default)]
    pub git: ZebflowJsonGit,
    #[serde(default)]
    pub assistant: ZebflowJsonAssistant,
    #[serde(default)]
    pub locks: ZebflowJsonLocks,
    #[serde(default)]
    pub data: ZebflowJsonData,
    #[serde(default)]
    pub files: ZebflowJsonFiles,
}

/// Repository-relative source root: pipelines, pages, styles, and components.
/// The source tree defaults to the repository itself.
///
/// A project starts as an empty repository: no `pipelines/`, no `pages/`, no
/// `docs/`. A pipeline, a page and a stylesheet may sit at the root beside the
/// README, and a project that wants them gathered under one directory says so
/// with `spec.layout.source`. The directories named by the other layout entries
/// are where their kind is *looked for*, never directories the platform
/// creates.
pub const DEFAULT_LAYOUT_SOURCE_DIR: &str = "";
/// Directory name, inside the source root, served for
/// `/static/{owner}/{project}/...`.
pub const DEFAULT_LAYOUT_STATIC_SUBDIR: &str = "static";
/// Repository-relative directory holding project documentation.
pub const DEFAULT_LAYOUT_DOCS_DIR: &str = "docs";
/// Repository-relative directory holding the exported database schema document.
pub const DEFAULT_LAYOUT_SCHEMA_DIR: &str = "schemas/sekejap";
/// Repository-relative directory holding the portable SQLite schema export.
pub const DEFAULT_LAYOUT_SQLITE_SCHEMA_DIR: &str = "schemas/sqlite";
/// Repository-relative directory holding third-party node interface documents.
pub const DEFAULT_LAYOUT_NODE_INTERFACES_DIR: &str = "nodes";
/// File extensions a package may write into `repo/`, lowercase, without a dot.
///
/// An extension is here because this build can say what the file is: source the
/// RWE compiler builds, a document a contract defines, or a media type
/// `content_type_for_path` serves from the asset route. Everything else lands
/// as `application/octet-stream` -- a binary nothing here reads -- which is the
/// `.dylib` and `.sh` case this set exists to refuse.
///
/// The test is a suffix, so it is decidable from the path alone with no
/// heuristic and no false positive. That is what makes it fit to be a
/// violation, which nobody can override, rather than a warning.
pub const DEFAULT_ALLOWED_FILE_EXTENSIONS: &[&str] = &[
    // Source and project documents. `.zf.json`, the schema exports, node
    // interfaces and library manifests are all `json`.
    "css", "geojson", "js", "json", "jsx", "md", "mjs", "sql", "ts", "tsx", "txt", "webmanifest", "xml",
    "yaml", "yml", // Assets: what the asset route serves with a content type of its own.
    "csv", "gif", "ico", "jpeg", "jpg", "mp3", "mp4", "pdf", "png", "svg", "ttf", "webp", "woff",
    "woff2",
];
/// Files a package may write whatever the extension set says, matched on the
/// whole file name.
///
/// These carry their meaning in the name rather than the suffix. Three of them
/// are load-bearing: a bundle with no `zebflow.yaml` is refused outright,
/// `zeb.lock` travels in every install scope and ends in nothing else, and
/// `ensure_project_layout` writes a `.gitkeep` into three directories of every
/// project -- so without these a project's own export could not come back. A
/// project narrows extensions and never this list, because narrowing it is how
/// a project would make its own bundles uninstallable.
pub const ALWAYS_ALLOWED_FILE_NAMES: &[&str] = &[
    ".gitkeep",
    "schema.json",
    "zeb.lock",
    "zebflow.init.json",
    "zebflow.yaml",
];
/// Filename suffix that marks a pipeline definition.
pub const PIPELINE_DEFINITION_EXTENSION: &str = ".zf.json";
/// The source root every persisted pipeline id carried before identity became
/// source-relative. It is the one prefix the migration knows how to remove.
pub const LEGACY_PIPELINE_IDENTITY_ROOT: &str = "pipelines";
/// Recovery copy stem written by the pipeline identity migration, combined
/// with the migration date (`project-directory.md` §5) into
/// `data/recovery/pipeline-identity-{date}.json`.
pub const PIPELINE_IDENTITY_BACKUP_FILE: &str = "pipeline-identity";
/// Filename of the exported schema document inside the schema directory.
pub const SCHEMA_DOCUMENT_FILE: &str = "schema.json";
/// Filename of the SQLite schema export inside the SQLite schema directory.
pub const SQLITE_SCHEMA_DOCUMENT_FILE: &str = "schema.sql";

/// Declared repository layout loaded from `zebflow.yaml`.
///
/// Every entry is optional and an absent entry means the platform default, so a
/// project written before this section existed keeps the directories the
/// platform hardcodes rather than acquiring a declaration it never made.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonLayout {
    /// Source root. This is also the RWE template root and the `@/` import root.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub r#static: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub docs: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub schema: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sqlite_schema: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_interfaces: Option<String>,
    /// Prefixes an install replays as initial data, each bound to one engine.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub initial_data: Option<Vec<ZebflowJsonInitialDataDir>>,
    /// File extensions this project accepts, narrowing the platform set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_extensions: Option<Vec<String>>,
}

/// One initial-data prefix and the database engine that would replay it.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonInitialDataDir {
    /// Repository-relative directory prefix.
    pub path: String,
    /// Engine name, matching the engine tokens the installer dispatches on.
    pub engine: String,
}

/// The default initial-data prefixes, derived from the installer's own table so
/// a declaration-free project can never resolve to a different set than the one
/// the installer actually replays.
pub fn default_initial_data_dirs() -> Vec<ZebflowJsonInitialDataDir> {
    crate::platform::policy::package::INITIAL_DATA_DIRS
        .iter()
        .map(|(path, engine)| ZebflowJsonInitialDataDir {
            path: (*path).to_string(),
            engine: (*engine).to_string(),
        })
        .collect()
}

/// The layout a project actually has: every entry resolved to a concrete,
/// repository-relative directory.
///
/// Consumers read this instead of the declaration so that "not declared" is
/// answered once, here, rather than at each of the places that need a path.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolvedProjectLayout {
    pub source: String,
    pub r#static: String,
    pub docs: String,
    pub schema: String,
    pub sqlite_schema: String,
    pub node_interfaces: String,
    pub initial_data: Vec<ZebflowJsonInitialDataDir>,
    /// Lowercase, dotless, and never wider than
    /// [`DEFAULT_ALLOWED_FILE_EXTENSIONS`].
    pub allowed_extensions: Vec<String>,
}

impl ZebflowJsonLayout {
    /// Returns true when the project declared no layout at all.
    pub fn is_undeclared(&self) -> bool {
        *self == Self::default()
    }

    /// Resolves the declaration against the platform defaults.
    pub fn resolve(&self) -> ResolvedProjectLayout {
        let resolved = |declared: &Option<String>, fallback: &str| {
            declared.clone().unwrap_or_else(|| fallback.to_string())
        };
        let source = resolved(&self.source, DEFAULT_LAYOUT_SOURCE_DIR);
        // The static root sits *inside* the source root rather than at a fixed
        // path, so a project that moves its source does not leave a static
        // directory behind in the tree it moved out of. With the source at the
        // repository root the subdirectory stands alone: joining `"/static"`
        // onto a path is absolute in Rust and would leave the project entirely.
        //
        // It keeps a directory of its own whatever the source is, because
        // `/static/{owner}/{project}/…` serves everything beneath it publicly
        // -- rooting it at the repository would publish `zebflow.yaml` and
        // every pipeline definition. It is the one layout entry that may not
        // be empty.
        let r#static = self.r#static.clone().unwrap_or_else(|| {
            if source.is_empty() {
                DEFAULT_LAYOUT_STATIC_SUBDIR.to_string()
            } else {
                format!("{source}/{DEFAULT_LAYOUT_STATIC_SUBDIR}")
            }
        });
        ResolvedProjectLayout {
            source,
            r#static,
            docs: resolved(&self.docs, DEFAULT_LAYOUT_DOCS_DIR),
            schema: resolved(&self.schema, DEFAULT_LAYOUT_SCHEMA_DIR),
            sqlite_schema: resolved(&self.sqlite_schema, DEFAULT_LAYOUT_SQLITE_SCHEMA_DIR),
            node_interfaces: resolved(&self.node_interfaces, DEFAULT_LAYOUT_NODE_INTERFACES_DIR),
            initial_data: self
                .initial_data
                .clone()
                .unwrap_or_else(default_initial_data_dirs),
            allowed_extensions: resolve_allowed_extensions(self.allowed_extensions.as_deref()),
        }
    }
}

/// The extensions a declaration ends up with: the platform set, or the declared
/// subset of it.
///
/// The intersection is the guarantee rather than the message. A declared
/// extension outside the platform set is refused by name when the document is
/// read, so no user ever reaches this clamp; it is here so that no code path
/// can construct a layout accepting more than the platform does either. A
/// project may narrow the set because narrowing only ever refuses more. It may
/// not widen it, because a violation nobody can override stops being one the
/// moment a line in a project's own configuration can turn it off.
fn resolve_allowed_extensions(declared: Option<&[String]>) -> Vec<String> {
    let Some(declared) = declared else {
        return DEFAULT_ALLOWED_FILE_EXTENSIONS
            .iter()
            .map(|value| (*value).to_string())
            .collect();
    };
    let mut resolved = declared
        .iter()
        .map(|value| value.trim().trim_start_matches('.').to_ascii_lowercase())
        .filter(|value| DEFAULT_ALLOWED_FILE_EXTENSIONS.contains(&value.as_str()))
        .collect::<Vec<_>>();
    resolved.sort();
    resolved.dedup();
    resolved
}

impl ResolvedProjectLayout {
    /// The layout of a project that declares nothing.
    pub fn platform_default() -> Self {
        ZebflowJsonLayout::default().resolve()
    }

    /// Repository-relative path of `rest` inside the source root.
    ///
    /// With the source at the repository root there is no prefix to add, and
    /// adding one anyway would make the path absolute.
    pub fn source_rel(&self, rest: &str) -> String {
        if rest.is_empty() {
            self.source.clone()
        } else if self.source.is_empty() {
            rest.to_string()
        } else {
            format!("{}/{rest}", self.source)
        }
    }

    /// `rel` with the source root removed, or `None` when it lives elsewhere.
    pub fn strip_source<'a>(&self, rel: &'a str) -> Option<&'a str> {
        strip_dir_prefix(&self.source, rel)
    }

    /// Whether `rel` is a repository-relative path inside the source root.
    pub fn is_in_source(&self, rel: &str) -> bool {
        self.strip_source(rel).is_some()
    }

    /// Whether `rel` names a pipeline definition.
    ///
    /// The safety review and the registration that follows it both ask this, so
    /// they agree by construction: a path the review skips can never be a path
    /// the install still writes and registers.
    pub fn is_pipeline_rel_path(&self, rel: &str) -> bool {
        self.is_in_source(rel) && rel.ends_with(PIPELINE_DEFINITION_EXTENSION)
    }

    /// Whether `rel` is part of the exported database schema document tree.
    pub fn is_schema_rel_path(&self, rel: &str) -> bool {
        strip_dir_prefix(&self.schema, rel).is_some()
    }

    /// Repository-relative path of the exported schema document itself.
    pub fn schema_document_rel(&self) -> String {
        format!("{}/{SCHEMA_DOCUMENT_FILE}", self.schema)
    }

    /// Whether `rel` is part of the portable SQLite schema export.
    pub fn is_sqlite_schema_rel_path(&self, rel: &str) -> bool {
        strip_dir_prefix(&self.sqlite_schema, rel).is_some()
    }

    /// Repository-relative path of the SQLite schema export itself.
    pub fn sqlite_schema_document_rel(&self) -> String {
        format!("{}/{SQLITE_SCHEMA_DOCUMENT_FILE}", self.sqlite_schema)
    }

    /// The engine that would replay `rel`, when this layout replays it at all.
    ///
    /// The prefix is anchored, so this names the files an install actually runs
    /// and not every `.sql` a package happens to ship.
    pub fn initial_data_engine(&self, rel: &str) -> Option<&str> {
        if !rel.ends_with(".sql") {
            return None;
        }
        self.initial_data
            .iter()
            .find(|dir| strip_dir_prefix(&dir.path, rel).is_some())
            .map(|dir| dir.engine.as_str())
    }

    /// Why this layout refuses to hold `rel`, or `None` when it accepts it.
    ///
    /// The answer is phrased for the refusal message: a package that cannot be
    /// installed by anyone's approval has to say exactly what it was refused
    /// for, and "no extension" is as much an answer as `.sh`.
    pub fn refused_file_type(&self, rel: &str) -> Option<String> {
        let name = rel.rsplit('/').next().unwrap_or(rel);
        if ALWAYS_ALLOWED_FILE_NAMES.contains(&name.to_ascii_lowercase().as_str()) {
            return None;
        }
        match file_extension(name) {
            Some(extension)
                if self
                    .allowed_extensions
                    .iter()
                    .any(|item| *item == extension) =>
            {
                None
            }
            Some(extension) => Some(format!("extension '.{extension}'")),
            None => Some("a name with no extension".to_string()),
        }
    }
}

/// The suffix a file name is judged by, lowercase and without the dot.
///
/// A leading dot marks a hidden file rather than a suffix, so `.env` has no
/// extension to judge and is refused as an unnamed type -- which is the answer
/// that case needs anyway.
fn file_extension(name: &str) -> Option<String> {
    let (stem, extension) = name.rsplit_once('.')?;
    if stem.is_empty() || extension.is_empty() {
        return None;
    }
    Some(extension.to_ascii_lowercase())
}

/// `rel` with `dir` and its separator removed, or `None` when `rel` is not
/// under `dir`. Anchored on a whole segment, so `pipelines-old/x` is not
/// treated as living under `pipelines`.
pub fn strip_dir_prefix<'a>(dir: &str, rel: &'a str) -> Option<&'a str> {
    // An empty declaration names the repository root, so everything is inside
    // it and nothing has a prefix to remove.
    if dir.is_empty() {
        return Some(rel);
    }
    rel.strip_prefix(dir)?.strip_prefix('/')
}

impl ZebflowJson {
    /// Effective repository layout for this project.
    pub fn layout(&self) -> ResolvedProjectLayout {
        self.configs.layout.resolve()
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonPipelines {
    #[serde(default)]
    pub logging: ZebflowJsonLogging,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_timeout_secs: Option<u64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonData {}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonFiles {
    /// The native store this project's `files/` live in.
    ///
    /// Absent means the platform default, so a project written before this
    /// entry existed keeps the store it already used. It is not the place a
    /// pipeline reads an outside bucket from — that is a connection, not a
    /// backend.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backend: Option<String>,
    #[serde(default)]
    pub uploads: ZebflowJsonUploads,
}

impl ZebflowJsonFiles {
    /// The declared backend, or the default a project inherits by declaring
    /// nothing. An unknown word is refused rather than defaulted.
    pub fn effective_backend(&self) -> Result<FileBackend, ZebFsError> {
        FileBackend::resolve(self.backend.as_deref())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonUploads {
    /// Max allowed size in MB for a single uploaded asset file (5–1024, default 10).
    #[serde(default = "default_max_asset_size_mb")]
    pub max_asset_size_mb: u32,
    /// Max allowed size in MB for one webhook request body.
    ///
    /// This controls the per-project logical limit enforced by `/wh/...` handlers.
    /// Route-level Axum buffering still uses a higher fallback ceiling so project
    /// overrides can be enforced inside the request handler.
    #[serde(default = "default_webhook_body_max_mb")]
    pub webhook_body_max_mb: u32,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_file_size_mb: Option<u32>,
}

impl Default for ZebflowJsonUploads {
    fn default() -> Self {
        Self {
            max_asset_size_mb: default_max_asset_size_mb(),
            webhook_body_max_mb: default_webhook_body_max_mb(),
            max_file_size_mb: None,
        }
    }
}

impl ZebflowJsonUploads {
    pub fn effective_max_asset_size_mb(&self) -> u32 {
        self.max_asset_size_mb.clamp(5, MAX_UPLOAD_SIZE_MB)
    }

    pub fn effective_webhook_body_max_mb(&self) -> u32 {
        self.webhook_body_max_mb
            .clamp(default_webhook_body_max_mb(), MAX_UPLOAD_SIZE_MB)
    }

    pub fn effective_max_file_size_mb(&self) -> u32 {
        self.max_file_size_mb
            .unwrap_or(MAX_UPLOAD_SIZE_MB)
            .clamp(5, MAX_UPLOAD_SIZE_MB)
    }
}

impl ZebflowJsonPipelines {
    pub fn effective_node_timeout_secs(&self) -> u64 {
        self.node_timeout_secs
            .unwrap_or_else(default_pipeline_node_timeout_secs)
            .clamp(5, 3600)
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonDistribution {
    #[serde(default)]
    pub hub: ZebflowJsonDistributionHub,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonDistributionHub {
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub entry_url: String,
    #[serde(default)]
    pub as_app: bool,
    #[serde(default)]
    pub producer_enabled: bool,
}

/// Lock settings loaded from `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonLocks {
    /// Template rel_paths (files or folder prefixes) blocked from agent read/write.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub templates: Vec<String>,
}

/// Git settings loaded from `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonGit {
    #[serde(default)]
    pub remote: ZebflowJsonGitRemote,
}

/// Git remote settings loaded from `zebflow.yaml`.
/// Stores remote repository configuration for push/sync operations.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonGitRemote {
    /// Credential ID for authenticated push (references `ProjectCredential.credential_id`).
    #[serde(default)]
    pub credential_id: String,
    /// Remote repository URL (e.g. `"https://gitlab.com/user/repo.git"`).
    #[serde(default)]
    pub repo_url: String,
    /// Default branch to push to (e.g. `"main"`).
    #[serde(default)]
    pub branch: String,
}

/// RWE settings loaded from `zebflow.yaml`.
///
/// Controls project-level compile/render behaviour for all `n.web.response` template nodes.
/// Values are merged into [`crate::rwe::ReactiveWebOptions`] at execution time,
/// before each pipeline run. Node-level `--load-scripts` is appended on top.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonRwe {
    /// URL patterns applied to the RWE resource allow-list (scripts and CSS).
    ///
    /// Each entry is a glob-style prefix, e.g. `https://cdnjs.cloudflare.com/*`.
    /// Blessed libraries (imported via `zeb/*`) are always allowed and do not
    /// appear here. Node-level `--load-scripts` is blocked at save time if any
    /// URL does not match an entry in this list.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allow_list: Vec<String>,
    /// Enable HTML minification on rendered output. Default: false.
    #[serde(default)]
    pub minify_html: bool,
    /// Enable strict compile-time checks. Default: true.
    #[serde(default = "default_rwe_strict_mode")]
    pub strict_mode: bool,
    /// Per-project enabled `zeb/*` library declarations.
    ///
    /// Keyed by library name (e.g. `"zeb/threejs"`). An entry here locks
    /// the version for reproducibility and surfaces the library in editor
    /// tooling. All libraries are served unconditionally at
    /// `/assets/libraries/zeb/…` regardless of this map.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub libraries: ZebflowJsonRweLibraries,
    /// Base URL prefix used when generating `<script src="...">` paths for
    /// compiled RWE scripts in production.
    ///
    /// Default (`None`): `/static/{owner}/{project}/_rwe/scripts/{hash}`
    ///
    /// When set, the prefix replaces `/static/{owner}/{project}`, so the
    /// resulting path becomes `{deployment_asset_base}/_rwe/scripts/{hash}`.
    ///
    /// Useful when the app is served behind a reverse proxy that rewrites
    /// asset paths, or when static assets are hosted at a custom sub-path.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub deployment_asset_base: Option<String>,
}

impl Default for ZebflowJsonRwe {
    fn default() -> Self {
        Self {
            allow_list: Vec::new(),
            minify_html: false,
            strict_mode: default_rwe_strict_mode(),
            libraries: HashMap::new(),
            deployment_asset_base: None,
        }
    }
}

/// Enabled library map loaded from `rwe.libraries` in `zebflow.yaml`.
pub type ZebflowJsonRweLibraries = HashMap<String, ZebflowJsonRweLibraryEntry>;

/// One enabled library entry loaded from `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonRweLibraryEntry {
    /// Pinned packed version string (e.g. `"bridge-0.1"`).
    pub version: String,
    /// Source kind: `"offline"` (embedded binary) or `"hub"` (installed copy).
    pub source: String,
}

pub fn default_rwe_strict_mode() -> bool {
    true
}

/// API request to update project-level RWE settings in `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpsertRweSettingsRequest {
    #[serde(default)]
    pub allow_list: Vec<String>,
    #[serde(default)]
    pub minify_html: bool,
    #[serde(default = "default_rwe_strict_mode")]
    pub strict_mode: bool,
}

/// Logging settings loaded from `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonLogging {
    /// Max invocation entries to retain per pipeline. Defaults to 20.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_invocations: Option<u32>,
    /// Project defaults for bounded node trace capture, overridden independently
    /// by each pipeline. Omitted fields inherit the engine defaults.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trace_capture: Option<crate::pipeline::trace_capture::TraceCaptureSettings>,
    /// Distinct error groups kept per project (`kinds/invocation-record`,
    /// Retention). Defaults to 200.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_error_groups: Option<u32>,
    /// Occurrences remembered per group as `(run_id, at)`. Defaults to 500.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub occurrence_ring: Option<u32>,
}

impl ZebflowJsonLogging {
    pub fn effective_max_invocations(&self) -> usize {
        self.max_invocations.unwrap_or(20).max(1) as usize
    }

    pub fn error_group_bounds(&self) -> ErrorGroupBounds {
        let d = ErrorGroupBounds::default();
        ErrorGroupBounds {
            max_groups: self.max_error_groups.map(|v| v.max(1) as usize).unwrap_or(d.max_groups),
            occurrence_ring: self.occurrence_ring.map(|v| v.max(1) as usize).unwrap_or(d.occurrence_ring),
            ..d
        }
    }
}

/// One distinct failure of a pipeline, counted across occurrences
/// (`kinds/invocation-record`, Error group).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PipelineErrorGroup {
    pub file_rel_path: String,
    pub signature: String,
    pub node_id: String,
    pub code: String,
    /// The message with runs of digits and quoted values blanked.
    pub message_pattern: String,
    pub count: u64,
    pub first_seen: i64,
    pub last_seen: i64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reopened_at: Option<i64>,
    pub first: PipelineInvocationEntry,
    pub latest: PipelineInvocationEntry,
    /// `(run_id, at)` of the newest occurrences.
    pub occurrences: Vec<(String, i64)>,
    /// `first-latest` or `all`.
    pub capture: String,
    /// Full records kept under `capture: all`, oldest first, up to the cap.
    #[serde(default)]
    pub captured: Vec<PipelineInvocationEntry>,
}

/// The three parts of a failure's signature: the failing node, its error
/// code, and the message. From the last trace entry that carries an error;
/// the run's own error message when no node does.
/// The trace entry that failed the run: the last one carrying an error whose
/// failure was not consumed by an `:error` edge. A `retry` or `error_routed`
/// entry is a node that failed and a run that went on, so it is not the
/// reason the run ended — and never the key of an error group.
pub fn failing_trace_entry(
    trace: &[crate::pipeline::model::NodeTraceEntry],
) -> Option<&crate::pipeline::model::NodeTraceEntry> {
    trace
        .iter()
        .rev()
        .find(|t| t.error.is_some() && t.status != "retry" && t.status != "error_routed")
}

pub fn error_group_parts(entry: &PipelineInvocationEntry) -> (String, String, String) {
    if let Some(t) = failing_trace_entry(&entry.trace) {
        let err = t.error.clone().unwrap_or_default();
        let (code, message) = match err.split_once(": ") {
            Some((c, m)) if c.len() < 48 && c.chars().all(|ch| ch.is_ascii_uppercase() || ch == '_' || ch.is_ascii_digit()) => (c.to_string(), m.to_string()),
            _ => (String::new(), err),
        };
        return (t.node_id.clone(), code, message);
    }
    (String::new(), String::new(), entry.error.clone().unwrap_or_default())
}

/// The message with runs of digits and quoted values blanked, so two
/// occurrences that differ only in an id or a value are one error
/// (`kinds/invocation-record`, Error group).
pub fn error_message_pattern(message: &str) -> String {
    let mut out = String::with_capacity(message.len());
    let mut chars = message.chars().peekable();
    let mut in_quote: Option<char> = None;
    while let Some(c) = chars.next() {
        if let Some(q) = in_quote {
            if c == q {
                in_quote = None;
                out.push(q);
            }
            continue;
        }
        match c {
            '"' | '\'' | '`' => {
                in_quote = Some(c);
                out.push(c);
                out.push('?');
            }
            d if d.is_ascii_digit() => {
                if !out.ends_with('#') {
                    out.push('#');
                }
                while chars.peek().is_some_and(|n| n.is_ascii_digit()) {
                    chars.next();
                }
            }
            other => out.push(other),
        }
    }
    out.chars().take(200).collect()
}

/// How many distinct errors, occurrences and full records a project keeps.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub struct ErrorGroupBounds {
    pub max_groups: usize,
    pub occurrence_ring: usize,
    pub capture_cap: usize,
    /// Quiet seconds after which a new occurrence reopens the group.
    pub reopen_after_secs: i64,
}

impl Default for ErrorGroupBounds {
    fn default() -> Self {
        Self { max_groups: 200, occurrence_ring: 500, capture_cap: 200, reopen_after_secs: 7 * 24 * 3600 }
    }
}

/// The retention a run's record is kept under: the pipeline's own setting
/// where it has one, else the project's.
#[derive(Debug, Clone, Copy)]
pub struct EffectivePipelineInvocationRetention {
    pub max_invocations: usize,
    pub max_age_secs: Option<i64>,
}

/// Resolves [`EffectivePipelineInvocationRetention`] for one run. Shared by
/// every path that writes a record — the API route, the webhook ingress, the
/// DSL `execute pipeline` — so all of them keep the same number of runs.
pub fn resolve_invocation_retention(
    project_cfg: &ZebflowJson,
    graph: Option<&crate::pipeline::PipelineGraph>,
) -> EffectivePipelineInvocationRetention {
    let project_max_invocations = project_cfg
        .configs
        .pipelines
        .logging
        .effective_max_invocations();
    let pipeline_retention = graph
        .and_then(|graph| graph.metadata.as_ref())
        .and_then(|metadata| metadata.settings.invocation_retention.as_ref());
    let max_invocations = pipeline_retention
        .and_then(|retention| retention.max_invocations)
        .map(|value| value.max(1) as usize)
        .unwrap_or(project_max_invocations);
    let max_age_secs = pipeline_retention
        .and_then(|retention| retention.max_age_secs)
        .map(|value| value.max(1) as i64);
    EffectivePipelineInvocationRetention {
        max_invocations,
        max_age_secs,
    }
}

/// One recorded pipeline invocation.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct PipelineInvocationEntry {
    /// Stable run identifier for this execution.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub run_id: String,
    /// Unix timestamp (seconds).
    pub at: i64,
    /// Wall-clock duration of the execution in milliseconds.
    pub duration_ms: u64,
    /// `"ok"` or `"error"`.
    pub status: String,
    /// Trigger source: `"webhook"`, `"manual"`, `"schedule"`, etc.
    pub trigger: String,
    /// Short error message, present only when `status == "error"`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Per-node execution trace for this invocation.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub trace: Vec<crate::pipeline::model::NodeTraceEntry>,
}

/// Per-pipeline invocation log storage summary.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct PipelineInvocationLogPipelineStats {
    pub file_rel_path: String,
    pub count: u64,
    pub trace_bytes: u64,
    pub largest_trace_bytes: u64,
    pub latest_at: i64,
}

/// Project-scoped invocation log storage summary.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct PipelineInvocationLogStats {
    pub count: u64,
    pub trace_bytes: u64,
    pub db_bytes: u64,
    pub wal_bytes: u64,
    pub shm_bytes: u64,
    pub pipelines: Vec<PipelineInvocationLogPipelineStats>,
}

/// Assistant settings loaded from `zebflow.yaml`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ZebflowJsonAssistant {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub high_model_credential: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub general_model_credential: Option<String>,
    #[serde(default)]
    pub max_steps: Option<u32>,
    #[serde(default)]
    pub max_replans: Option<u32>,
    #[serde(default)]
    pub chat_history_pairs: Option<u32>,
    #[serde(default)]
    pub enabled: Option<bool>,
}

/// Request payload for project creation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateProjectRequest {
    /// Project slug.
    pub project: String,
    /// Optional title.
    pub title: Option<String>,
    /// Optional initial local branch name. Defaults to "main" when None or empty.
    #[serde(default)]
    pub local_branch: Option<String>,
    /// Environment-owned runtime selection captured at create/clone time.
    #[serde(default)]
    pub runtime: ProjectRuntimeSelectionRequest,
}

/// Environment-owned runtime selection supplied during create/clone flows.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct ProjectRuntimeSelectionRequest {
    /// Optional explicit runtime mode override for the project.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub runtime_mode: Option<crate::infra::execution::placement::ProjectRuntimeMode>,
    /// Selected runtime host id, or `None`/`local` for the current office.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub placement_worker_id: Option<String>,
}

/// Internal office registration request.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct ClusterWorkerRegisterRequest {
    /// Stable office id.
    pub node_id: String,
    /// Human-readable office label.
    #[serde(default)]
    pub label: String,
    /// Advertised base URL reachable by the controller or peers.
    #[serde(default)]
    pub base_url: String,
    /// Declared runtime capabilities.
    #[serde(default)]
    pub capabilities: RunnerCapabilities,
    /// Fresh random nonce the controller must answer with a proof.
    ///
    /// `offices.md` §8 wants proof in both directions. The office sends this,
    /// and refuses a response whose `proof` does not verify, so it can tell a
    /// real controller from any host that answers its base URL.
    #[serde(default)]
    pub nonce: String,
}

/// Internal office heartbeat request.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct ClusterWorkerHeartbeatRequest {
    /// Stable office id.
    pub node_id: String,
    /// Current status summary.
    #[serde(default)]
    pub status: String,
    /// Refreshed advertised base URL.
    #[serde(default)]
    pub base_url: String,
    /// Refreshed runtime capabilities.
    #[serde(default)]
    pub capabilities: RunnerCapabilities,
}

/// Internal office registration response returned by the controller.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ClusterWorkerRegisterResponse {
    /// Whether the registration was accepted.
    pub ok: bool,
    /// Normalized registry record.
    pub worker: crate::infra::cluster::registry::WorkerRegistryRecord,
    /// HMAC over the office's nonce, keyed by this office's own secret digest.
    #[serde(default)]
    pub proof: String,
}

/// Internal office heartbeat response returned by the controller.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ClusterWorkerHeartbeatResponse {
    /// Whether the heartbeat update was accepted.
    pub ok: bool,
    /// Normalized heartbeat snapshot.
    pub heartbeat: WorkerHeartbeat,
}

/// Operator request to mint one office join token.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct ClusterJoinTokenMintRequest {
    /// Office the token is issued to. Minting creates the office record when
    /// it does not exist yet, so the holder is recorded before the token is.
    pub office_id: String,
    /// Display label for a newly created office record.
    #[serde(default)]
    pub label: String,
    /// Base URL of the planned office, when the operator already knows it.
    #[serde(default)]
    pub base_url: String,
    /// Operator note recorded beside the token.
    #[serde(default)]
    pub note: String,
    /// Replace an existing token for this office rather than refusing.
    #[serde(default)]
    pub rotate: bool,
}

/// One minted token, returned once and never readable again.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ClusterMintedJoinToken {
    /// The record the controller keeps.
    pub record: PlatformOfficeJoinToken,
    /// The office record minting created or reused.
    pub office: PlatformOffice,
    /// Plaintext token, shown once. The controller stores only its digest.
    pub token: String,
}

/// One runtime target option shown in project create/clone UI.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct ClusterRuntimeTargetOption {
    /// Stable value posted back by forms.
    pub value: String,
    /// Human-readable office label.
    pub label: String,
    /// Short description line for selection UI.
    #[serde(default)]
    pub description: String,
}

/// Export/import artifact kind used by first-class project portability flows.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ProjectTransferArtifactKind {
    /// Repository workspace plus project runtime data.
    Bundle,
    /// Project Zebflow FS object tree.
    Files,
    /// Full backup: every movable class in one archive.
    Full,
}

impl ProjectTransferArtifactKind {
    /// Stable API/storage key.
    pub fn key(self) -> &'static str {
        match self {
            Self::Bundle => "bundle",
            Self::Files => "files",
            Self::Full => "full",
        }
    }

    /// Stable archive filename used for downloads and operation artifacts.
    pub fn archive_name(self) -> &'static str {
        match self {
            Self::Bundle => "project.bundle.tar",
            Self::Files => "project.files.tar",
            Self::Full => "project.full.tar",
        }
    }

    /// The `ProjectBundle` classes this artifact kind selects.
    ///
    /// The artifact kinds are class selections of one archive format
    /// (`kinds/project-bundle/README.md`): `bundle` = repo + store, `files` =
    /// files, `full` = every movable class. The route/UI surface keeps the
    /// legacy words; the archive speaks classes.
    pub fn classes(self) -> &'static [crate::contracts::kinds::ProjectBundleClass] {
        use crate::contracts::kinds::ProjectBundleClass;
        match self {
            Self::Bundle => &[ProjectBundleClass::Repo, ProjectBundleClass::Store],
            Self::Files => &[ProjectBundleClass::Files],
            Self::Full => &[
                ProjectBundleClass::Repo,
                ProjectBundleClass::Store,
                ProjectBundleClass::Files,
            ],
        }
    }
}

/// Durable controller-side operation kind for project portability and sync flows.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ProjectOperationKind {
    /// Export `repo/` + `data/`.
    ExportBundle,
    /// Export Zebflow FS files.
    ExportFiles,
    /// Import `repo/` + `data/`.
    ImportBundle,
    /// Import Zebflow FS files.
    ImportFiles,
    /// Export every movable class.
    ExportFull,
    /// Import every movable class.
    ImportFull,
    /// Platform-scope import that created this project from an archive.
    PlatformImport,
    /// Reverse swap restoring recovery copies displaced by an import.
    RollbackImport,
}

impl ProjectOperationKind {
    /// Stable storage key.
    pub fn key(self) -> &'static str {
        match self {
            Self::ExportBundle => "export_bundle",
            Self::ExportFiles => "export_files",
            Self::ImportBundle => "import_bundle",
            Self::ImportFiles => "import_files",
            Self::ExportFull => "export_full",
            Self::ImportFull => "import_full",
            Self::PlatformImport => "platform_import",
            Self::RollbackImport => "rollback_import",
        }
    }
}

/// Durable controller-side operation state.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ProjectOperationStatus {
    Pending,
    Running,
    Failed,
    Completed,
}

impl ProjectOperationStatus {
    /// Stable storage key.
    pub fn key(self) -> &'static str {
        match self {
            Self::Pending => "pending",
            Self::Running => "running",
            Self::Failed => "failed",
            Self::Completed => "completed",
        }
    }
}

/// One durable controller-tracked project operation record.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProjectOperationRecord {
    /// Stable operation id.
    pub operation_id: String,
    /// Stable project id.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub project_id: String,
    /// Stable owner id.
    pub owner: String,
    /// Stable project slug.
    pub project: String,
    /// Operation type.
    pub kind: ProjectOperationKind,
    /// Current status.
    pub status: ProjectOperationStatus,
    /// Human-readable current step.
    #[serde(default)]
    pub current_step: String,
    /// Source office id when relevant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_office_id: Option<String>,
    /// Target office id when relevant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target_office_id: Option<String>,
    /// Relative artifact path under controller operation storage.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub artifact_rel_path: Option<String>,
    /// Archive SHA-256 when an artifact exists.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub artifact_sha256: Option<String>,
    /// Artifact byte size when known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub artifact_bytes: Option<u64>,
    /// Last error message when the operation failed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error_message: Option<String>,
    /// Retry count for resumed operations.
    #[serde(default)]
    pub retry_count: u32,
    /// Unix timestamp seconds.
    pub created_at: i64,
    /// Unix timestamp seconds.
    pub updated_at: i64,
    /// Unix timestamp seconds when operation reached a terminal success state.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub completed_at: Option<i64>,
}

/// Request payload for platform login page/form.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LoginRequest {
    /// Username/owner id.
    pub identifier: String,
    /// Password.
    pub password: String,
}

/// Request payload for `POST /api/profile/password`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangePasswordRequest {
    /// The password the account authenticates with right now.
    pub current_password: String,
    /// The replacement password.
    pub new_password: String,
}

/// Minimal auth session value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthSession {
    /// Authenticated owner id.
    pub owner: String,
}

/// Returns unix timestamp seconds.
pub fn now_ts() -> i64 {
    use std::time::{SystemTime, UNIX_EPOCH};
    match SystemTime::now().duration_since(UNIX_EPOCH) {
        Ok(d) => d.as_secs() as i64,
        Err(_) => 0,
    }
}

/// Current UTC date as `YYYY-MM-DD`.
///
/// Every migration that writes a recovery copy into `data/recovery/` names the
/// file with this stamp (`project-directory.md` §5), so the file itself
/// records when the migration ran without a separate audit log.
pub fn recovery_date_stamp() -> String {
    chrono::Utc::now().format("%Y-%m-%d").to_string()
}

/// Slug-normalize a segment for ids/paths.
pub fn slug_segment(raw: &str) -> String {
    raw.trim()
        .to_ascii_lowercase()
        .chars()
        .map(|c| {
            if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
                c
            } else {
                '-'
            }
        })
        .collect::<String>()
        .trim_matches('-')
        .to_string()
}

/// Canonicalize one virtual path used for pipeline registry hierarchy.
///
/// Rules:
/// - root is `/`
/// - removes empty segments
/// - disallows `.` and `..`
/// - each segment is slug-normalized
pub fn normalize_virtual_path(raw: &str) -> String {
    let trimmed = raw.trim();
    if trimmed.is_empty() || trimmed == "/" {
        return "/".to_string();
    }
    let mut parts = Vec::new();
    for seg in trimmed.split('/') {
        let seg = seg.trim();
        if seg.is_empty() || seg == "." || seg == ".." {
            continue;
        }
        let slug = slug_segment(seg);
        if !slug.is_empty() {
            parts.push(slug);
        }
    }
    if parts.is_empty() {
        "/".to_string()
    } else {
        format!("/{}", parts.join("/"))
    }
}

fn default_true() -> bool {
    true
}

/// MCP session record (in-memory and persisted per-project).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpSession {
    /// Owner identifier.
    pub owner: String,
    /// Project slug.
    pub project: String,
    /// Capabilities allowed for this session.
    pub capabilities: Vec<ProjectCapability>,
    /// Opaque session token.
    pub token: String,
    /// Unix timestamp seconds when session was created.
    #[serde(default)]
    pub created_at: i64,
    /// Optional seconds after which this session auto-expires.
    #[serde(default)]
    pub auto_reset_seconds: Option<u64>,
    /// Whether this session is active. Token persists even when disabled.
    #[serde(default = "default_true")]
    pub enabled: bool,
}

/// Request to create an MCP session for a project.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpSessionCreateRequest {
    /// Capabilities to allow for this session (can be specified as strings or capability keys).
    pub capabilities: Vec<String>,
    /// Optional seconds after which this session auto-expires (None = no expiry).
    #[serde(default)]
    pub auto_reset_seconds: Option<u64>,
}

/// Request to toggle an MCP session enabled/disabled.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpSessionToggleRequest {
    /// Whether to enable or disable the session.
    pub enabled: bool,
}

/// Response after creating an MCP session.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpSessionResponse {
    /// Opaque session token for Authorization header.
    pub token: String,
    /// Full MCP endpoint URL for this project.
    pub mcp_url: String,
    /// Allowed capabilities echoed back.
    pub capabilities: Vec<String>,
    /// Whether the session is currently accepted by the MCP handler.
    pub enabled: bool,
    /// Session creation timestamp.
    pub created_at: i64,
    /// Optional seconds after which this session auto-expires.
    #[serde(default)]
    pub auto_reset_seconds: Option<u64>,
    /// Global minimum creation timestamp required for persisted MCP sessions.
    pub rotation_epoch: i64,
}

/// Maps MCP tool name to required project capability.
pub fn mcp_tool_capability(tool_name: &str) -> Option<ProjectCapability> {
    match tool_name {
        "list_pipelines" => Some(ProjectCapability::PipelinesRead),
        "get_pipeline" => Some(ProjectCapability::PipelinesRead),
        "upsert_pipeline" => Some(ProjectCapability::PipelinesWrite),
        "activate_pipeline" => Some(ProjectCapability::PipelinesWrite),
        "deactivate_pipeline" => Some(ProjectCapability::PipelinesWrite),
        "execute_pipeline" => Some(ProjectCapability::PipelinesExecute),
        "list_templates" => Some(ProjectCapability::TemplatesRead),
        "get_template" => Some(ProjectCapability::TemplatesRead),
        "save_template" => Some(ProjectCapability::TemplatesWrite),
        "create_template" => Some(ProjectCapability::TemplatesCreate),
        "delete_template" => Some(ProjectCapability::TemplatesDelete),
        "get_credential" => Some(ProjectCapability::CredentialsRead),
        "upsert_credential" => Some(ProjectCapability::CredentialsWrite),
        "list_db_connections" => Some(ProjectCapability::TablesRead),
        "get_db_connection" => Some(ProjectCapability::TablesRead),
        "upsert_db_connection" => Some(ProjectCapability::TablesWrite),
        "update_db_connection" => Some(ProjectCapability::TablesWrite),
        "delete_db_connection" => Some(ProjectCapability::TablesWrite),
        "test_db_connection" => Some(ProjectCapability::TablesRead),
        "describe_db_connection" => Some(ProjectCapability::TablesRead),
        "query_db_connection" => Some(ProjectCapability::TablesRead),
        "list_db_connection_schemas" => Some(ProjectCapability::TablesRead),
        "list_db_connection_tables" => Some(ProjectCapability::TablesRead),
        "list_db_connection_functions" => Some(ProjectCapability::TablesRead),
        "preview_db_connection_table" => Some(ProjectCapability::TablesRead),
        "list_project_docs" => Some(ProjectCapability::ProjectRead),
        "read_project_doc" => Some(ProjectCapability::ProjectRead),
        "create_project_doc" => Some(ProjectCapability::FilesWrite),

        "list_credentials" => Some(ProjectCapability::CredentialsRead),
        // execute_pipeline_dsl temporarily disabled; keeping mapping for future re-enable
        "execute_pipeline_dsl" => Some(ProjectCapability::PipelinesExecute),
        "git_command" => Some(ProjectCapability::PipelinesWrite),
        // New domain-prefixed tool names
        "pipeline_list" => Some(ProjectCapability::PipelinesRead),
        "pipeline_get" => Some(ProjectCapability::PipelinesRead),
        "pipeline_register" => Some(ProjectCapability::PipelinesWrite),
        "pipeline_describe" => Some(ProjectCapability::PipelinesRead),
        "pipeline_patch" => Some(ProjectCapability::PipelinesWrite),
        "pipeline_activate" => Some(ProjectCapability::PipelinesWrite),
        "pipeline_deactivate" => Some(ProjectCapability::PipelinesWrite),
        "pipeline_execute" => Some(ProjectCapability::PipelinesExecute),
        "pipeline_run" => Some(ProjectCapability::PipelinesExecute),
        "pipeline_get_invocations" => Some(ProjectCapability::PipelinesRead),
        // One file vocabulary over the repository. `docs_project_*` is gone with
        // it: a `.md` is a file like any other, and had no reason to be reached
        // by its own three tools.
        "file_list" => Some(ProjectCapability::TemplatesRead),
        "file_read" => Some(ProjectCapability::TemplatesRead),
        "file_create" => Some(ProjectCapability::TemplatesCreate),
        "file_write" => Some(ProjectCapability::TemplatesWrite),
        "file_search" => Some(ProjectCapability::TemplatesRead),
        "file_edit" => Some(ProjectCapability::TemplatesWrite),
        "file_outline" => Some(ProjectCapability::TemplatesRead),
        "file_deps" => Some(ProjectCapability::TemplatesRead),
        "file_batch_edit" => Some(ProjectCapability::TemplatesWrite),
        "pipeline_search" => Some(ProjectCapability::PipelinesRead),
        "connection_list" => Some(ProjectCapability::TablesRead),
        "connection_describe" => Some(ProjectCapability::TablesRead),
        "credential_list" => Some(ProjectCapability::CredentialsRead),
        "docs_agent_list" => Some(ProjectCapability::SettingsRead),
        "docs_agent_read" => Some(ProjectCapability::SettingsRead),
        "docs_agent_write" => Some(ProjectCapability::SettingsWrite),
        // Help and orientation tools
        "start_here" => Some(ProjectCapability::ProjectRead),
        "help" => Some(ProjectCapability::ProjectRead),
        "help_search" => Some(ProjectCapability::ProjectRead),
        "skill_list" => Some(ProjectCapability::ProjectRead),
        "skill_read" => Some(ProjectCapability::ProjectRead),
        // UI catalog install tools
        "list_ui_catalog" => Some(ProjectCapability::PipelinesRead),
        "install_ui_components" => Some(ProjectCapability::PipelinesWrite),
        "hub_search" => Some(ProjectCapability::PipelinesRead),
        "hub_review" => Some(ProjectCapability::PipelinesRead),
        "hub_add" => Some(ProjectCapability::PipelinesWrite),
        "route_fetch" => Some(ProjectCapability::PipelinesExecute),
        "theme_generate" => Some(ProjectCapability::ProjectRead),
        // Move resource (requires both pipelines write + templates write — use higher capability)
        "move_resource" => Some(ProjectCapability::PipelinesWrite),
        _ => None,
    }
}