appximo

type Allowlist []string

type App struct {
	// contains filtered or unexported fields
}

type Claims struct {
	UserID           string
	Role             string
	TenantID         string
	ExternalClientID string
}

type Config struct {
	// SchemaPath is the path to the schema JSON compiled at boot.
	SchemaPath string
	// DSN is the PostgreSQL connection string. Empty falls back to DATABASE_URL.
	DSN string

	// Port is the data-plane HTTP port. 0 falls back to 8080.
	Port int

	// Host is the data-plane bind address. Empty keeps the historical default
	// (all interfaces). Set "127.0.0.1" for a loopback-only deployment — a dev
	// box reached through an SSH tunnel, or a binary that only ever sits behind
	// a local reverse proxy (LIBRARY-GAPS-S2, from the 105's port-exposure
	// review: a public box's firewall should be the SECOND line, not the only
	// one).
	Host string

	// ControlHost is the control-plane bind address. Empty keeps the historical
	// default (all interfaces — relies on the firewall/AGENTS rule that :9090
	// never reaches the internet). "127.0.0.1" enforces localhost-only at the
	// socket, which is what the control plane's own documentation assumes.
	ControlHost string

	// ControlPort is the control-plane HTTP port (tenant registration,
	// X-Admin-Key-gated — keep it off the internet). 0 falls back to
	// APPXIMO_CONTROL_PORT, then 9090 (the historical fixed value, so a
	// single-engine deployment boots byte-identically). Parameterized in
	// MT-STRUCT-S1 so N engines can coexist on one box (`appximo fleet`).
	ControlPort int

	// ObsDBPath is the observability SQLite path. Empty falls back to
	// OBS_DB_PATH, then the package default (/var/lib/appximo/obs.db).
	// A Config field (not env-only) since MT-STRUCT-S3: N in-process apps
	// share the process env, and each app needs its OWN obs store.
	ObsDBPath string

	// JWTSecret signs/validates HS256 tokens. Empty falls back to JWT_SECRET.
	JWTSecret string
	// AdminKey gates the control plane (:9090) and /metrics, /debug, /admin on
	// the data plane. Empty falls back to ADMIN_KEY.
	AdminKey string

	// Env mirrors APPXIMO_ENV ("development" enables GraphiQL + introspection +
	// pprof). Empty falls back to the APPXIMO_ENV environment variable.
	Env string

	// GraphQLPlayground explicitly enables GraphQL introspection and the
	// GraphiQL explorer (/graphiql) OUTSIDE development — the operator's opt-in
	// for exploring/testing GraphQL in production without flipping the broader
	// Env=development flag (which also enables pprof). False falls back to
	// APPXIMO_GRAPHQL_PLAYGROUND (truthy); Env=="development" already implies
	// this regardless (GRAPHQL-EXPLORER-S1).
	GraphQLPlayground bool

	// FilesDir is the root directory of the content-addressable file store
	// (FILES-V1). Empty falls back to APPXIMO_FILES_DIR, then to
	// /var/lib/appximo/files. The directory is created lazily on the first
	// upload, so an engine that never serves /api/files touches no disk.
	// Applies to the "local" files backend only.
	FilesDir string

	// --- File store backends (FILES-V2): BYOC storage, swappable by config ---
	//
	// FilesBackend selects where blobs live: "local" (default — the tenant's
	// files on this VPS's disk, served by the engine with Range/ETag/sendfile)
	// or "s3" (any S3-compatible provider: Cloudflare R2, DO Spaces, MinIO,
	// AWS — served via short-lived presigned URL + 302 by default). Empty falls
	// back to APPXIMO_FILES_BACKEND, then "local". Tenancy, RBAC, metadata
	// and upload validation are IDENTICAL on both backends.
	FilesBackend string
	// FilesS3Bucket / FilesS3Endpoint / FilesS3Region / FilesS3AccessKey /
	// FilesS3SecretKey configure the S3 backend provider-agnostically. Each
	// falls back to its APPXIMO_FILES_S3_* env var (BUCKET, ENDPOINT, REGION,
	// ACCESS_KEY, SECRET_KEY). Endpoint empty means AWS S3 proper; Region
	// empty defaults to "auto" (R2's spelling, harmless elsewhere). With
	// FilesBackend="s3", a missing bucket or credentials fails boot loudly.
	FilesS3Bucket    string
	FilesS3Endpoint  string
	FilesS3Region    string
	FilesS3AccessKey string
	FilesS3SecretKey string
	// FilesS3ForcePathStyle addresses the bucket as <endpoint>/<bucket>
	// (required by MinIO). Falls back to APPXIMO_FILES_S3_FORCE_PATH_STYLE
	// (truthy).
	FilesS3ForcePathStyle bool
	// FilesS3Prefix namespaces keys inside the bucket. Empty falls back to
	// APPXIMO_FILES_S3_PREFIX, then "tenants/".
	FilesS3Prefix string
	// FilesS3ServeMode is how GET /api/files/{id} delivers S3 bytes:
	// "redirect" (default — 302 to a short-lived presigned URL; the engine
	// authorizes, the bucket serves, zero engine bandwidth) or "proxy" (bytes
	// stream through the engine; bucket never exposed). Falls back to
	// APPXIMO_FILES_S3_SERVE.
	FilesS3ServeMode string
	// FilesTokenTTLSeconds bounds signed download URLs (both the engine-minted
	// local tokens and S3 presigned URLs from /api/files/{id}/url). 0 falls
	// back to APPXIMO_FILES_TOKEN_TTL (seconds), then 180.
	FilesTokenTTLSeconds int
	// FilesAllowedExt replaces the default upload extension ALLOWLIST
	// (OWASP: allowlist, never denylist). Entries with or without the dot;
	// the single value "*" disables the extension check (magic-byte checks
	// still apply). Empty falls back to APPXIMO_FILES_ALLOWED_EXT
	// (comma-separated), then to files.DefaultAllowedExtensions.
	FilesAllowedExt []string

	// BareDomains are hostnames that are THIS APP ITSELF (the fleet manifest's
	// `domains`), not a tenant: a request whose Host equals one exactly carries
	// no tenant label, so the tenant middleware passes it through with no
	// TenantCtx instead of mis-reading the domain's first label as a tenant
	// (the observability phantom-tenant bug, FLEET-CONSOLE-S2). Empty (the
	// single-engine default) leaves the middleware byte-identical to before.
	BareDomains []string

	// BeforeStart runs ONCE at Start, after the engine is fully constructed (pool
	// open, control-plane tables ensured, schema loaded and compiled) and BEFORE
	// the data-plane listener accepts a single request — the seam framework-mode
	// backends need for boot work (LIBRARY-GAPS-S1): their own DDL for what the
	// schema grammar cannot express (a CHECK constraint, a generated column),
	// seeds, or a cache warm-up.
	//
	// It receives the ENGINE'S OWN pool (the same *pgxpool.Pool as App.Pool()), so
	// a backend no longer parses DATABASE_URL and opens a second pool that can
	// drift from the engine's configuration. The pool is NOT tenant-scoped: set
	// the search_path yourself, transaction-locally, exactly as the engine does —
	//
	//	tx.Exec(ctx, "SELECT set_config('search_path', $1, true)", pgSchema)
	//
	// — never by string concatenation.
	//
	// A non-nil error ABORTS the boot: Start returns it and the listener never
	// opens, so a backend whose invariants failed to install never serves traffic.
	// The context is cancelled on SIGINT/SIGTERM, so a hung hook still drains.
	BeforeStart func(ctx context.Context, pool *pgxpool.Pool) error

	// OnTenantProvisioned runs INSIDE every tenant registration this app
	// performs (control plane :9090/:9099 and the /admin API — both funnel
	// through the same Service), after the engine has provisioned the tenant's
	// tables (ENG-8, CONSUMER-PATH-S1). It is the per-tenant twin of
	// BeforeStart: BeforeStart covers the tenants that exist AT BOOT; this hook
	// covers every tenant created while the app is live — the normal flow of a
	// multi-tenant SaaS. Without it, consumer DDL (generated columns, CHECKs,
	// partial indexes) was missing from post-boot tenants until a restart.
	//
	// Same contract as BeforeStart: the engine's own pool, not tenant-scoped —
	// scope the search_path transaction-locally. MUST be idempotent (BeforeStart
	// typically re-applies the same DDL at every boot). An error FAILS the
	// registration all-or-nothing: the tenant is rolled back, never left
	// half-provisioned.
	OnTenantProvisioned func(ctx context.Context, pool *pgxpool.Pool, tenantID, pgSchema string) error

	// Static serves one or more file trees from THIS binary — the seam that makes
	// "one binary = backend + frontend + admin + docs" real (LOOSE-ENDS-SWEEP-S1).
	// Each mount is served outside /api/, with no tenant transaction, no RBAC
	// evaluation and no response-cache buffering; a collision with an
	// engine-owned prefix, a missing index document or a duplicated path is a
	// BOOT error. See StaticMount for the full contract (including the PCI note
	// on keeping a checkout page free of third-party scripts).
	//
	// Empty (the default, and the pure binary) mounts nothing and costs nothing.
	Static []StaticMount

	// Version is reported by /health and the synthetic monitor. Empty reports
	// "dev"; the cmd binary passes its ldflags-injected build version.
	Version string

	// DebugTracesHTML is the embedded /debug/traces explorer page. The cmd
	// binary injects its go:embed'd asset here; when nil the visual route is
	// not mounted (the JSON debug APIs are unaffected). Optional engine wiring,
	// not part of the day-to-day user surface.
	DebugTracesHTML []byte

	// AuthSignupRole is the RBAC role assigned to every PUBLIC signup
	// (POST /auth/signup), the auth-as-product core (AUTH-CORE-V1). Empty
	// DISABLES public signup (safe by default — no accidental self-service
	// accounts). It must name a role declared in the schema's RBAC; New rejects
	// an unknown role at boot. Empty falls back to APPXIMO_AUTH_SIGNUP_ROLE.
	AuthSignupRole string
	// AuthMinPasswordLength is the minimum accepted signup password length.
	// 0 falls back to APPXIMO_AUTH_MIN_PASSWORD, then to 8.
	AuthMinPasswordLength int

	// SafeGoTimeoutSeconds bounds a Ctx.SafeGo goroutine's context
	// (LIBRARY-HARDEN-S1): the context is cancelled after this (fn must honor
	// cancellation to actually stop — a deadline cannot forcibly kill a
	// goroutine). 0 falls back to APPXIMO_SAFEGO_TIMEOUT (seconds), then to 30s.
	// It does not affect the request-goroutine deadline, which is Route.Timeout.
	SafeGoTimeoutSeconds int

	// PublicRouteRPS / PublicRouteBurst tune the DEDICATED rate limit applied
	// to PUBLIC custom routes (Route.Public — LIBRARY-EXTEND-S1), per
	// (tenant, client IP), on top of the per-tenant limiter. Zero falls back to
	// APPXIMO_PUBLIC_ROUTE_RPS / APPXIMO_PUBLIC_ROUTE_BURST, then to the
	// deliberately conservative 5 rps / burst 10 — an anonymous endpoint is
	// abuse surface, so the default protects it without configuration.
	PublicRouteRPS   float64
	PublicRouteBurst int

	// AuthRequireVerified, when true, blocks login for a user whose email is not
	// yet verified (→ 403). Empty falls back to APPXIMO_AUTH_REQUIRE_VERIFIED
	// ("true"/"1"/"on"). Default false (login works without verification).
	AuthRequireVerified bool
	// AuthBaseURL optionally overrides the origin used to build password-reset /
	// email-verification links. Empty falls back to APPXIMO_AUTH_BASE_URL; if
	// still empty the link origin is derived from the request Host (the
	// multi-tenant-correct default). The link path is appended by the engine.
	AuthBaseURL string

	// OAuthCallbackURL is the FIXED public origin OAuth providers redirect back to
	// (AUTH-OAUTH-V1), e.g. "https://auth.example.com" — it must be the redirect
	// URI registered with each provider. Empty falls back to
	// APPXIMO_OAUTH_CALLBACK_URL; if still empty it is derived from the request.
	OAuthCallbackURL string
	// OAuthDefaultRole is the role assigned to a user auto-created on first social
	// login. Empty falls back to APPXIMO_OAUTH_DEFAULT_ROLE then to
	// AuthSignupRole; if all empty, a brand-new social email is rejected (existing
	// users still link/login). A configured role must exist in the schema RBAC.
	OAuthDefaultRole string
	// OAuthSuccessRedirect, when set, makes the OAuth callback 302 to
	// "<url>#token=<jwt>" instead of returning JSON. Empty falls back to
	// APPXIMO_OAUTH_SUCCESS_REDIRECT.
	OAuthSuccessRedirect string
	// OAuthProviders optionally sets the social-login provider credentials
	// directly ("google"/"github"/"microsoft" → client id+secret). Nil falls
	// back to the APPXIMO_OAUTH_{PROVIDER}_CLIENT_ID/_CLIENT_SECRET env vars.
	// A Config field so the in-process fleet can give EACH APP its own
	// providers (each app is a product with its own identity) instead of the
	// process-wide env.
	OAuthProviders map[string]userauth.OAuthProviderConfig

	// MFAKey is the key material that ENCRYPTS users' TOTP secrets at rest
	// (AUTH-MFA-V1, AES-256-GCM). Empty falls back to APPXIMO_MFA_KEY, then to
	// the JWT secret. Set a dedicated key if you want to rotate it independently of
	// JWT_SECRET (rotating it invalidates existing TOTP enrollments).
	MFAKey string
	// MFAIssuer is the issuer label shown in authenticator apps. Empty falls back
	// to APPXIMO_MFA_ISSUER, then to "Appximo".
	MFAIssuer string

	// --- CORS (API-PRODUCTIVA-V1): cross-origin access for browser clients ---
	// CORS is instance INFRASTRUCTURE config, not schema. An empty CORSAllowedOrigins
	// DISABLES CORS (the safe default — no Access-Control-* headers, no preflight
	// short-circuit); an operator opts in by listing browser origins. CORS applies
	// ONLY to the public data-plane routes (/api, /auth, /graphql, /openapi), never
	// to the control plane, /admin, /metrics or /debug.
	//
	// CORSAllowedOrigins is the exact origin allowlist, or the single literal "*"
	// for any origin. Empty falls back to APPXIMO_CORS_ORIGINS (comma-separated).
	CORSAllowedOrigins []string
	// CORSAllowedMethods is echoed in preflight responses. Empty falls back to
	// APPXIMO_CORS_METHODS, then to "GET,POST,PUT,PATCH,DELETE,OPTIONS".
	CORSAllowedMethods []string
	// CORSAllowedHeaders is echoed in preflight responses. Empty falls back to
	// APPXIMO_CORS_HEADERS, then to "Authorization,Content-Type".
	CORSAllowedHeaders []string
	// CORSExposedHeaders lists response headers a browser script may read. Empty
	// falls back to APPXIMO_CORS_EXPOSE_HEADERS, then to none.
	CORSExposedHeaders []string
	// CORSAllowCredentials sends Access-Control-Allow-Credentials: true (browser may
	// send cookies/Authorization). Falls back to APPXIMO_CORS_CREDENTIALS (truthy).
	// With credentials a literal "*" origin is reflected (the Fetch spec forbids "*").
	CORSAllowCredentials bool
	// CORSMaxAge bounds preflight caching (seconds). 0 falls back to
	// APPXIMO_CORS_MAX_AGE, then to 600.
	CORSMaxAge int
}

type CreatedUser struct {
	ID            string
	Email         string
	Role          string
	EmailVerified bool
}

type Ctx interface {
	// Identity — already verified by the middleware chain.
	Claims() Claims
	Tenant() string // tenant id, e.g. "acme" (from the Host subdomain)
	Role() string   // the JWT "role" claim
	// Allowlist returns the field projection the caller's role is granted on
	// resource, and whether the role may read it at all (false ⇒ denied).
	Allowlist(resource string) (Allowlist, bool)

	// Tx is the transaction opened by the middleware with the tenant
	// search_path already applied via set_config(...,true). Returning nil from
	// the Handler commits it; returning an error rolls it back.
	Tx() pgx.Tx
	// UnsafeTx returns the SAME transaction but signals to the reader (and to
	// `grep UnsafeTx`) that the RBAC-aware helpers are being bypassed. Tenant
	// isolation STILL holds — the search_path is the same. There is no API that
	// exposes the raw pool.
	UnsafeTx() pgx.Tx

	// RBAC-aware helpers — apply the role's row filter, validate against the
	// compiled schema rules, and project the permitted fields. Use by default.
	Query(resource string, opts QueryOpts) ([]map[string]any, error)
	// Get loads ONE row by id, with the role's row-level condition applied and
	// the role's field allowlist projected — the read counterpart of Update.
	//
	// It exists because `id` is NOT a filterable field: QueryOpts.Filters is
	// validated against the resource's DECLARED fields, and the implicit primary
	// key is not one of them, so `Query(r, QueryOpts{Filters: {"id": x}})` fails
	// with `unknown filter field: id`. That cost a real integration a debugging
	// round (docs/AUTHORING_JOURNEY.md 5-7), and the workaround people reach for —
	// UnsafeTx plus a hand-written SELECT — silently drops the row rule.
	//
	// A row the role may not see is indistinguishable from one that does not
	// exist: both return (nil, nil) — never a 403 — which is the same
	// anti-enumeration contract Ctx.Update and the generated GET/PATCH/DELETE
	// follow. A role denied `read` on the resource entirely is a forbidden error.
	Get(resource, id string) (map[string]any, error)
	Insert(resource string, data map[string]any) (map[string]any, error)
	Update(resource, id string, data map[string]any) (map[string]any, error)

	// Bind JSON-decodes the request body (1 MiB cap) into dst. BindResource
	// additionally validates the decoded body against the compiled schema rules
	// for resource (the same rule engine REST and GraphQL use).
	Bind(dst any) error
	BindResource(resource string, dst any) error

	// RawBody returns the request body's EXACT bytes, under the SAME 1 MiB cap
	// Bind applies (MaxBodyBytes) — the handler never re-implements the limit.
	//
	// USE IT FOR WEBHOOKS. A gateway signature (Stripe, Wompi, GitHub…) is
	// computed over the bytes as sent: parse-then-reserialize changes key order
	// and whitespace and breaks every signature, so Bind is the WRONG tool for a
	// signed payload. Verify over RawBody FIRST, then Bind (or unmarshal the same
	// bytes) once the signature checks out — parsing before verifying is the #1
	// documented payment-integration bug.
	//
	// The body is read ONCE and buffered: RawBody and Bind may be used together
	// in any order and both see the whole body (a plain io.ReadAll on
	// Request().Body would leave Bind an empty reader). The returned slice is the
	// engine's buffer — treat it as read-only. A body over the cap returns
	// ErrBodyTooLarge, which the middleware maps to 413 if the handler returns it.
	RawBody() ([]byte, error)

	// Enqueue writes an outbox job inside the current transaction (atomic with
	// the business write). A Handler error rolls back the enqueue too.
	Enqueue(topic string, payload any) (int64, error)

	// SafeGo launches fn in a NEW goroutine — the ONLY sanctioned way to start a
	// goroutine from a handler (LIBRARY-HARDEN-S1). A raw `go func(){…}()` whose
	// body panics crashes the ENTIRE multi-tenant process: recover() never
	// crosses a goroutine boundary, so the request-chain Recoverer cannot save a
	// child goroutine. SafeGo wraps fn in recover() + a structured log (tenant +
	// request id) + the goroutine_panics_total metric, so a panicking background
	// task degrades to a logged incident instead of an outage for every tenant.
	//
	// The context passed to fn is a FRESH root — it carries NO request values (a
	// detached copy of the request context would retain chi's pooled route
	// context, which is recycled once the handler returns) — with an INDEPENDENT
	// bounded deadline. fn MUST honor that deadline (return promptly once ctx is
	// Done): a deadline cancels the context, it cannot forcibly stop a goroutine,
	// so an fn that ignores cancellation still leaks. fn MUST NOT use the
	// handler's transaction (Tx/UnsafeTx/Query/Insert/Update) — that transaction
	// commits or rolls back as the handler returns, and a goroutine touching it
	// races a closed tx. SafeGo is for post-response, non-transactional side
	// effects where at-most-once is acceptable (fire-and-forget: a metric ping, a
	// best-effort cache warm). For DURABLE, retryable work use Enqueue (the
	// transactional outbox + worker); for parallel work whose result the response
	// needs, use SafeParallel and wait for it.
	SafeGo(fn func(context.Context))

	// CreateUser creates an identity in THIS tenant's auth_users, inside the
	// handler's transaction — if the handler later fails, the user rolls back
	// with everything else (LIBRARY-EXTEND-S1). It applies the SAME rules as
	// the admin API: the email is normalized + format-checked, the role must
	// be declared in the schema RBAC (ErrUnknownRole — no privilege invention),
	// the password is argon2id-hashed and must meet the engine's configured
	// minimum length. An EMPTY password creates an invitation-style user that
	// cannot password-login until a reset sets one (the OTP/invite gate — same
	// contract as an OAuth-created user). Duplicate email in the tenant →
	// ErrEmailTaken. Always scoped to Tenant(): a handler cannot create users
	// in another tenant. Deliberately usable on a Public route — creating the
	// user IS the point of a custom registration endpoint; the caller's
	// anonymity is why the role comes from the handler's code, never from
	// request input, and why every input must be validated by the handler.
	CreateUser(email, password, role string) (CreatedUser, error)

	// ServeFile streams one of THIS tenant's stored files (the engine file
	// store, pkg/files — the same store /api/files/{id} serves) as the route's
	// response: stored Content-Type, strong content-hash ETag (If-None-Match →
	// 304), Range → 206, and on the local backend sendfile zero-copy
	// (FRONTEND-SPEC-S1). It is the seam for a PUBLIC or custom-authorized
	// download route — the handler decides WHO may fetch the file (e.g. "it is
	// the image of an active product"), the engine moves the bytes safely.
	//
	// Contract:
	//   - The route MUST declare ByteServing: true (rejected loudly otherwise):
	//     that flag is what routes the response around the response cache and
	//     the compression wrapper, which would otherwise buffer the whole blob
	//     in RAM, drop Content-Disposition/Range headers on a cache hit, and
	//     suppress sendfile.
	//   - Call it once, INSTEAD of JSON/Error, and return its error. The bytes
	//     are streamed after the transaction commits (same flush discipline as
	//     JSON). ctx.Error before it still works (the error response wins).
	//   - fileID must be one of this tenant's file ids. A malformed id, an
	//     unknown id, or ANOTHER tenant's id all yield the same uniform 404
	//     (ErrFileNotFound — isolation is structural: the metadata lives in the
	//     tenant's own schema).
	//   - The lookup reads committed state (the engine pool), not the handler's
	//     transaction: a file uploaded inside THIS tx is not yet servable.
	//   - Cache policy (FILES-2): by default no Cache-Control is set (browsers
	//     revalidate — cheap 304s via the strong ETag). Pass
	//     appximo.WithCacheControl(...) to declare one; the store is
	//     content-addressed, so a given file id's BYTES can never change —
	//     appximo.CacheControlImmutable ("public, max-age=31536000,
	//     immutable") is safe for any route whose URL embeds the file id (a
	//     product image, an avatar): a different image is a different id, so a
	//     stale cache is structurally impossible. Do NOT use it when the SAME
	//     URL can start serving a DIFFERENT file (e.g. /api/logo that follows a
	//     mutable pointer) — there, the default revalidation is the correct
	//     policy. The header is only sent on a successful stream, never on the
	//     404/error paths.
	ServeFile(fileID string, opts ...ServeFileOption) error

	// JSON buffers a success response flushed AFTER the transaction commits, so
	// a commit failure becomes a 500 rather than a false 200. Error buffers an
	// error response and returns a non-nil error so the Handler can
	// `return ctx.Error(...)`; the middleware rolls back and flushes it.
	JSON(status int, v any) error
	Error(status int, msg string, cause error) error

	Request() *http.Request
	Context() context.Context
}

type Handler func(ctx Ctx) error

type InvalidTransitionError struct{ Message string }

type QueryOpts struct {
	Filters map[string]any
	Limit   int
	OrderBy string
	Desc    bool
}

type RateLimit struct {
	RPS   float64
	Burst int
}

type Registry struct {
	// contains filtered or unexported fields
}

type Route struct {
	Method  string // GET | POST | PUT | PATCH | DELETE
	Path    string // e.g. "/api/declarations/submit"
	Handler Handler

	// Description is an optional one-line summary published in the served
	// OpenAPI document (ENG-33). Every registered route appears in
	// /openapi.json regardless — method, path, auth mode (Public vs Bearer +
	// the RBAC segment/action it demands), RequireRole and ByteServing are all
	// facts the engine knows and publishes on its own; Description is the one
	// thing only the author can add. Request/response SHAPES are deliberately
	// not declarable here: a Go handler has no declared schema, and the app's
	// contract sheet (backend-spec §3.6b) stays the authority for shapes — the
	// OpenAPI is the authority for EXISTENCE. An empty Description publishes a
	// generic summary; an invisible route was the problem, a tersely-documented
	// one is not.
	Description string

	// RequireRole, when non-empty, demands the caller's JWT role equal it
	// (else 403). This is in ADDITION to the path-based RBAC the middleware
	// already applied; a Route with no RequireRole still gets deny-by-default
	// from the policy when its path segment matches a policy rule.
	RequireRole string

	// Timeout bounds this endpoint's execution (LIBRARY-HARDEN-S1). When > 0 the
	// handler's context — and the tenant transaction opened for it — is cancelled
	// after Timeout: a slow query or a hung outbound call is aborted (the deadline
	// propagates to pgx and to any downstream that honours the context), the
	// transaction rolls back, and the caller gets a 500 instead of the request
	// pinning a connection indefinitely. 0 uses the engine default (5s). It bounds
	// the REQUEST goroutine only; a Ctx.SafeGo goroutine outlives the request and
	// carries its own independent deadline.
	Timeout time.Duration

	// RateLimit overrides this endpoint's dedicated throttle, per (tenant, client
	// IP) — the same bucket shape the public-route limiter uses, sized for THIS
	// route (LIBRARY-GAPS-S1).
	//
	// The engine's default for a Public route (5 rps / burst 10) is calibrated for
	// a public WRITE endpoint — a registration or a webhook, where 5 rps is
	// generous and abuse is the real risk. A public READ endpoint (a storefront
	// catalogue) has the opposite profile: legitimate traffic is bursty and much
	// higher. That mismatch is what this field fixes, without touching the
	// conservative default everyone else inherits.
	//
	//	{Method: "GET", Path: "/api/catalogue", Public: true,
	//	 RateLimit: &appximo.RateLimit{RPS: 200, Burst: 400}}
	//
	// Nil (the default) keeps today's behavior EXACTLY: a Public route uses the
	// shared public-route limiter, a non-public route has no dedicated limit (only
	// the per-tenant one). Set on a NON-public route, it adds a per-(tenant, IP)
	// limit on top of the per-tenant limiter — useful for an expensive
	// authenticated endpoint (a report, an export).
	RateLimit *RateLimit

	// Public marks this route as PRE-AUTHENTICATION (LIBRARY-EXTEND-S1): the
	// JWT and path-RBAC middlewares skip it by EXACT method+path match, so a
	// caller needs no Bearer token — the seam for a custom registration/webhook
	// endpoint that must run before an identity exists.
	//
	// ⚠ A public route is ATTACK SURFACE. The engine keeps what it can by
	// default — the tenant still resolves from the Host (per-tenant isolation
	// holds), the shared per-tenant rate limit still applies, and a DEDICATED,
	// far more aggressive public-route rate limit (per tenant+client IP,
	// APPXIMO_PUBLIC_ROUTE_RPS/BURST, default 5 rps / burst 10 → 429) is
	// enforced before the handler runs. Everything else is the handler's
	// responsibility: validate EVERY input, and treat the caller as hostile.
	//
	// Authentication is OPTIONAL, not ignored (LIBRARY-GAPS-S2, ENG-6): with no
	// Authorization header the handler sees Claims() zero (anonymous — the
	// RBAC-aware helpers fail closed with forbidden; anonymous writes go
	// through CreateUser or a deliberate, greppable UnsafeTx). With a VALID
	// Bearer, Claims() is populated — one endpoint can serve guests and
	// recognized users (a checkout that links the order to a logged-in
	// customer). A present-but-invalid/expired/foreign-tenant Bearer is a 401:
	// sent credentials never silently degrade to anonymous, so the client
	// knows to re-authenticate or retry deliberately without the token. The
	// path-RBAC still skips a Public route entirely — a populated Claims is
	// input for the handler, never a new gate.
	//
	// Public routes must use literal paths (no chi {params} — the match is
	// exact) and cannot combine with RequireRole (use Claims().Role in the
	// handler if a public route wants to branch on identity). Only routes
	// explicitly marked Public relax auth; every other route keeps
	// deny-by-default.
	Public bool

	// ByteServing declares that this route streams a binary body (Ctx.ServeFile
	// — a file download, a public product image) instead of buffered JSON
	// (FRONTEND-SPEC-S1). It routes the response AROUND two wrappers that are
	// right for JSON and wrong for a stream: the response cache (which would
	// buffer the whole blob in RAM and strip Content-Disposition/Accept-Ranges
	// on a hit) and the Compress middleware (whose writer lacks io.ReaderFrom
	// and suppressed sendfile zero-copy — the FILES-BENCH finding, fixed for
	// the engine's own file routes by the same bypass this flag extends to
	// custom routes).
	//
	// Constraints (validated at Register): GET only, literal path (no chi
	// {params}/wildcards — the bypass, like the Public skip, matches the exact
	// path; pass the file id as a query parameter). Ctx.ServeFile refuses to
	// run on a route without this flag. Everything else about the route is
	// unchanged: auth/RBAC (or Public), RateLimit, Timeout, the tenant tx.
	ByteServing bool
}

type ServeArgs struct {
	SchemaPath  string
	Port        int
	ControlPort int
}

type ServeFileOption func(*serveFileOpts)

type StaticMount struct {
	// Path is the URL prefix this tree is served at: "/" for the whole site, or
	// a sub-path like "/app". It must not be under, or collide with, any prefix
	// the engine owns (/api, /auth, /admin, /editor, /docs, /graphql, /graphiql,
	// /openapi, /metrics, /debug, /healthz, /readyz, /health, /files, /fleet) —
	// a collision is a BOOT error, never a silently shadowed route.
	Path string

	// FS is the file tree. An embed.FS sub-tree (fs.Sub) compiles the frontend
	// INTO the binary; os.DirFS(dir) serves a directory from disk. Either way the
	// handler can only ever read inside this FS: paths are cleaned and io/fs
	// itself rejects anything that escapes the root, so traversal is impossible
	// by construction rather than by filtering.
	FS fs.FS

	// SPA opts into client-side-routing fallback: a request that matches no file
	// serves Index instead of 404, so /orders/42 reaches the router in the
	// browser. It is OPT-IN because it is wrong for a plain static site, where a
	// typo should 404. Requests under a prefix the engine owns are NEVER given
	// the fallback — an unknown /api/… path stays a real 404.
	SPA bool

	// Index is the document served for the mount root and (when SPA) for
	// unmatched client routes. Empty means "index.html".
	Index string

	// ImmutablePrefixes are path prefixes, RELATIVE to this mount, whose files
	// carry content-hashed names and may be cached forever
	// (Cache-Control: immutable). Empty means the Vite/webpack default
	// ["assets/", "_app/", "static/"]. Everything else gets a short max-age, and
	// the index document is ALWAYS no-cache — it names the current hashed
	// bundles, so a stale copy would point at files a deploy already deleted.
	ImmutablePrefixes []string

	// CSP is this mount's Content-Security-Policy (LIBRARY-GAPS-S2, ENG-5).
	//
	// The static handler OWNS the header on everything it serves, for BOTH
	// mount forms. Before this, the two forms diverged invisibly: a root mount
	// is chi's NotFound handler, which chi copies into the API subrouter that
	// lives inside the StrictCSP group — so the SPA shell shipped the API's
	// `default-src 'none'` and every browser blocked the app's own scripts
	// (a blank page curl can never see, because curl does not enforce CSP);
	// a sub-path mount bypassed the group and shipped NO policy at all.
	//
	//   ""  (default) → DefaultStaticCSP: a same-origin SPA policy (the shape
	//        the engine's own embedded UIs use — external self scripts, inline
	//        styles allowed for component libraries, no framing).
	//   any other string → emitted verbatim, replacing the default (e.g. add
	//        img-src for a CDN).
	//   CSPOff ("off") → NO Content-Security-Policy header at all: the handler
	//        DELETES any policy inherited from the chain, so opting out is the
	//        same on a root and a sub-path mount. For apps that set their own
	//        policy via <meta http-equiv>.
	CSP string
}

type ValidationError struct{ Fields []schema.FieldRuleError }