schema

type APISchema struct {
	Schema    string                    `json:"$schema"`
	Version   string                    `json:"version"`
	Name      string                    `json:"name"`
	Resources map[string]ResourceSchema `json:"resources"`
	RBAC      RBACPolicy                `json:"rbac"`
	// Workflows is reserved for the Phase 2 multi-step orchestration engine
	// (ADR-012). The struct is parsed for forward compatibility, but no executor
	// runs it yet — present so existing schemas remain valid once it ships.
	Workflows map[string]WorkflowSchema `json:"workflows,omitempty"`
}

type AutoValue string

type Condition struct {
	Field string `json:"field"`
	Op    string `json:"op"`  // "eq", "neq", "in", etc.
	Val   string `json:"val"` // may reference session vars like "$user_id"
}

type FieldDef struct {
	// Type is one of: string, text, int, int64, float64, bool, uuid, time, json,
	// file. A `file` field (FILES-LINK-S1) stores the id of an uploaded file
	// (the file_id `POST /api/files` returns) as a UUID column carrying a REAL
	// foreign key to the tenant's own files table — the first-class file↔record
	// link. Its on_delete (restrict default | set_null; cascade rejected) governs
	// what happens to the record when the referenced FILE is deleted; deleting
	// the record never deletes the file.
	Type     string `json:"type"`
	Required bool   `json:"required,omitempty"`
	Unique   bool   `json:"unique,omitempty"`
	// Auto declares an engine-managed timestamp. Accepts `true` (legacy:
	// creation timestamp + refresh-on-update ONLY for the literal name
	// `updated_at`), or the explicit, name-independent roles `"create"` /
	// `"update"` (SILENT-CORRUPTION-S1) — see AutoValue in auto.go.
	Auto     AutoValue `json:"auto,omitempty"`
	Enum     []string  `json:"enum,omitempty"`
	Relation string    `json:"relation,omitempty"` // name of the related resource
	// OnDelete declares the referential action of THIS field's foreign key when the
	// referenced (parent) row is deleted (MIG-F1-S1): "restrict" | "cascade" |
	// "set_null". Only meaningful on a field that also declares `relation` (the FK
	// lives on the column, like `unique`/`required`). EMPTY DEFAULTS TO RESTRICT —
	// the safe choice: a delete of a still-referenced row is rejected (409) rather
	// than silently orphaning its children (the integrity bug this closes). set_null
	// requires the column to be nullable (not `required`); validated at load.
	OnDelete string `json:"on_delete,omitempty"`
	// OnUpdate declares the referential action of THIS field's foreign key when the
	// referenced (parent) row's KEY changes (MIG-F1-S5): "restrict" | "cascade" |
	// "set_null". Only meaningful with `relation`. EMPTY DEFAULTS TO NO ACTION — which
	// is what Postgres already records for an FK created without ON UPDATE, so adding
	// this key to an existing schema generates NO churn (a re-provision stays a no-op;
	// see refActionForOnUpdate). This is the deliberate asymmetry with on_delete (whose
	// default is RESTRICT): on_delete shipped RESTRICT from the start, so the live FKs
	// already carry it; on_update is introduced over FKs that already exist with NO
	// ACTION, so its default must match them. set_null requires a nullable column.
	OnUpdate string `json:"on_update,omitempty"`
	// References declares the target COLUMN this field's foreign key points at
	// (MIG-F1-S5). EMPTY DEFAULTS TO "id" (the target's implicit primary key — the only
	// behavior before this key, so retrocompat is total). A non-id value must name a
	// column that is UNIQUE on the target (Postgres requires an FK destination to be a
	// PK or unique column/index); validated at load. Only meaningful with `relation`.
	References string `json:"references,omitempty"`
	// RenamedFrom declares the PREVIOUS name of this field's column (MIG-F1-S2): the
	// migration engine emits `ALTER TABLE … RENAME COLUMN <old> TO <new>`
	// (metadata-only, data preserved, indexes/FK/unique follow the column) instead
	// of the converger's drop+add that stranded the data in the old column. The old
	// name must NOT still be a current field (you cannot rename from a name that
	// still exists); validated at load. Once applied the intent is INERT — a
	// re-provision with it present is a no-op (the old column no longer exists).
	RenamedFrom string `json:"renamed_from,omitempty"`
	Default     any    `json:"default,omitempty"`

	// Declarative validation rules (S44). Pointer types distinguish "absent"
	// from a legitimate zero (min: 0, minLength: 0).
	Min       *float64 `json:"min,omitempty"`       // numeric types: value >= Min
	Max       *float64 `json:"max,omitempty"`       // numeric types: value <= Max
	MinLength *int     `json:"minLength,omitempty"` // string/text: rune count >= MinLength
	MaxLength *int     `json:"maxLength,omitempty"` // string/text: rune count <= MaxLength
	Pattern   string   `json:"pattern,omitempty"`   // string/text: RE2 regex, len <= MaxPatternLength
	Format    string   `json:"format,omitempty"`    // string/text: email | uuid | url | date

	// Accept (FILES-1) — file fields only — is the per-FIELD upload policy: the
	// content types this field will attach. Entries are matched against the
	// file's STORED (magic-byte-sniffed at upload, never client-declared)
	// content type: a bare family name ("image", "audio", "video", "text")
	// matches the whole family (image/*…), "pdf" is a convenience alias for
	// application/pdf, and an entry containing "/" matches that exact type
	// ("application/zip"). JSON accepts a single string or an array. Enforced
	// at ATTACH time (create/update on REST, GraphQL and batch — the upload
	// endpoint is field-agnostic, so the field's policy applies when a record
	// references the file): a violating file_id is a 422 `file_policy` naming
	// what the field accepts. The instance-wide env knobs
	// (APPXIMO_FILES_MAX_BYTES / _ALLOWED_EXT) remain the outer bound at
	// upload.
	Accept StringList `json:"accept,omitempty"`
	// MaxBytes (FILES-1) — file fields only — caps the size of a file this
	// field will attach, in bytes (checked against the stored size at attach
	// time, same 422 file_policy). Must be > 0 when declared.
	MaxBytes int64 `json:"max_bytes,omitempty"`

	// StateMachine (G5) declares the allowed lifecycle transitions of a string
	// status field: which states a row may be CREATED in (Initial) and which moves
	// are permitted between states (Transitions). The engine forces it on create
	// (the initial state must be valid) and on update (a state may only move along a
	// declared transition; a state with no outgoing transitions is terminal /
	// immutable). A field without StateMachine is a free string (unchanged). Only
	// string/text fields; coherent with `enum` if both are declared.
	StateMachine *StateMachine `json:"state_machine,omitempty"`
}

type FieldRuleError struct {
	Field   string `json:"field"`
	Rule    string `json:"rule"`
	Message string `json:"message"`
}

type ForeignKeyDef struct {
	Columns    []string `json:"columns"`             // local columns (this resource)
	Target     string   `json:"target"`              // referenced resource
	RefColumns []string `json:"ref_columns"`         // referenced columns on Target (same count as Columns)
	OnDelete   string   `json:"on_delete,omitempty"` // restrict (default) | cascade | set_null
	OnUpdate   string   `json:"on_update,omitempty"` // restrict | cascade | set_null; unset → NO ACTION
}

type GovernedOp int

type HookConfig struct {
	Type          string `json:"type"`                      // "js" | "webhook" | "wasm"
	Script        string `json:"script,omitempty"`          // JS source for type=js
	URL           string `json:"url,omitempty"`             // endpoint for type=webhook
	HMACSecretEnv string `json:"hmac_secret_env,omitempty"` // env var holding the HMAC secret
	WasmModule    string `json:"wasm_module,omitempty"`     // for type=wasm: name of the pre-loaded module
	WasmFn        string `json:"wasm_fn,omitempty"`         // for type=wasm: function to call (default "transform")
	Timeout       string `json:"timeout,omitempty"`         // execution budget, e.g. "500ms" (default "500ms")
}

type ImportConfig struct {
	// Roles is the closed list of RBAC roles granted import. Required,
	// non-empty; every entry must be a role the schema's rbac block declares
	// (a typo is a load error, never a silently dead grant — the ENG-27 mold).
	// There is no wildcard: an auditor reads exactly who may import.
	Roles []string `json:"roles"`
	// Fields optionally narrows WHICH governed fields the grant covers, e.g.
	// ["id"] for client-generated ids without opening timestamp forgery.
	// Each entry must be "id" or an auto field of the resource. Absent = the
	// full governed set.
	Fields []string `json:"fields,omitempty"`
}

type IndexDef struct {
	Fields []string `json:"fields"`
	Unique bool     `json:"unique,omitempty"`

	// Method is the Postgres access method (LIBRARY-GAPS-S1): "btree" (the
	// default, and what every pre-S1 index used) or "gin". EMPTY MEANS BTREE, so
	// adding this key to an existing schema generates zero churn — the introspector
	// reads pg_am.amname back, and an unchanged index diffs identical.
	//
	// "gin" is the index that makes jsonb containment (`@>`) an index lookup
	// instead of a sequential scan; it is accepted ONLY over `jsonb` columns
	// (validated at load, never a runtime surprise) and never with unique (GIN
	// cannot enforce uniqueness).
	Method string `json:"method,omitempty"`

	// Opclass is the operator class applied to EVERY listed column, e.g.
	// "jsonb_path_ops" for a GIN index that only ever answers `@>` (smaller and
	// faster than the default jsonb_ops, at the cost of key-existence `?`
	// queries). Only valid with an explicit method, and only a value from the
	// method's closed allowlist (validIndexOpclasses) — it is rendered into DDL,
	// so it is never free-form text. Invisible to the diff (the introspector
	// cannot read an opclass back from the index key list), which is exactly why
	// declaring one causes no migration churn.
	Opclass string `json:"opclass,omitempty"`
}

type RBACPolicy struct {
	Roles map[string]RolePolicy `json:"roles"`

	// Public declares the ANONYMOUS surface (PUBLIC-SURFACE-S1, ADR-026): the
	// resources an UNAUTHENTICATED request may READ, each with its own row
	// condition and field allowlist — a blog's published articles, a catalogue,
	// a landing — with no Go and no token. It reuses the per-resource
	// permission shape (`{ "articulos": { "actions": ["read"], "conditions":
	// {…}, "fields": […] } }`) and compiles into the ONE existing evaluator as
	// the reserved role rbac.PublicRoleName, so every enforcement surface
	// (REST, GraphQL, aggregates, embeds, SSE, files) is the same code path an
	// authenticated role uses — never a second implementation.
	//
	// Constraints, validated at load (deny-by-default stays intact):
	//   - actions must be exactly ["read"] — the anonymous surface is
	//     read-only in v1 (an anonymous write is a spam/abuse surface that
	//     needs its own design; ADR-026 records the reasoning).
	//   - conditions.val must be a LITERAL ("published") — $user_id /
	//     $external_client_id name an identity an anonymous request does not
	//     have, so they are load errors here.
	//   - the built-in "files" store is grantable (actions-only, like any
	//     role) — the public-image pattern.
	//   - absent block ⇒ NOTHING anonymous, exactly today's behavior. The key
	//     is NEW, and unknown keys have always rejected the schema, so no
	//     existing schema can change meaning by upgrading the engine.
	//
	// Anonymous requests are additionally throttled by the public-route rate
	// limiter (APPXIMO_PUBLIC_ROUTE_RPS) and NEVER served from or stored in
	// the response cache.
	Public map[string]ResourcePermission `json:"public,omitempty"`
}

type RelationDef struct {
	Type     string `json:"type"`                // has_many | belongs_to | many_to_many
	Target   string `json:"target"`              // related resource name
	FK       string `json:"fk"`                  // foreign-key column (see Type for which table)
	Through  string `json:"through,omitempty"`   // junction table (many_to_many only)
	TargetFK string `json:"target_fk,omitempty"` // target's FK column in Through (many_to_many only)
	Limit    int    `json:"limit,omitempty"`     // top-N children per parent (0 → DefaultEmbedLimit)
}

type ResourcePermission struct {
	Actions          []string   `json:"actions"`
	Conditions       *Condition `json:"conditions,omitempty"`
	ConditionActions []string   `json:"condition_actions,omitempty"` // actions the condition gates (empty = all)
	Fields           []string   `json:"fields,omitempty"`            // per-resource field allowlist
}

type ResourceSchema struct {
	Fields  map[string]FieldDef   `json:"fields"`
	Hooks   map[string]HookConfig `json:"hooks,omitempty"`
	Indexes []IndexDef            `json:"indexes,omitempty"`

	// ForeignKeys declares COMPOSITE (multi-column) foreign keys at the resource
	// level (MIG-F1-S5). A single-column FK is the field-level `relation` (which is
	// inherently 1 column = 1 column → target.id, optionally → a unique non-id column
	// via `references`); a composite FK references MULTIPLE columns of the target's
	// composite PK/unique, which does not fit the field-level model, so it gets an
	// explicit block. Each entry is one constraint over (columns) → target(ref_columns)
	// with its own on_delete/on_update. A resource that omits this key behaves exactly
	// as before. See ForeignKeyDef.
	ForeignKeys []ForeignKeyDef `json:"foreign_keys,omitempty"`

	// RenamedFrom declares the PREVIOUS name of this resource's table (MIG-F1-S2):
	// the migration engine emits `ALTER TABLE <old> RENAME TO <new>` (metadata-only,
	// data + indexes + constraints preserved) instead of the converger's drop+add
	// that stranded the data. The old name must NOT still be a current resource
	// (you cannot rename from a name that still exists); validated at load. Once the
	// rename is applied the intent is INERT — re-provisioning with it still present
	// is a no-op (the old table no longer exists), so it is safe to leave in place.
	RenamedFrom string `json:"renamed_from,omitempty"`

	// Relations is the opt-in set of declarative relations (RELATIONS-V1,
	// ADR-019) keyed by the embed name exposed to clients (the key used in
	// ?include=<name> and the GraphQL nested field). A resource that omits this
	// key serves exactly as before and pays zero overhead on the read path —
	// relations are served ONLY when explicitly requested via ?include=.
	Relations map[string]RelationDef `json:"relations,omitempty"`

	// Events is the opt-in list of write actions that emit a transactional
	// outbox event (CRUD-EMIT-V1). Valid values: "create", "update", "delete"
	// (present-tense, matching the RBAC action vocabulary). For a declared
	// action the engine writes a row to public.outbox IN THE SAME TRANSACTION as
	// the CRUD write, with topic "{resource}.{created|updated|deleted}". A
	// resource that omits this key emits nothing and pays zero overhead. See
	// EmitActions / EmitTopic.
	Events []string `json:"events,omitempty"`

	// Import declares which roles may supply the engine-governed fields (the
	// implicit `id` + every `auto` timestamp) when CREATING rows — the data-
	// import / fixture-restore contract (WRITE-ASYMMETRY-S1). Absent, the
	// governed fields are rejected on create at every door, exactly as they
	// always were on update. See ImportConfig / GovernedFieldViolations.
	Import *ImportConfig `json:"import,omitempty"`
}

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

type RolePolicy struct {
	Resources  json.RawMessage `json:"resources,omitempty"`
	Actions    []string        `json:"actions,omitempty"`
	Conditions *Condition      `json:"conditions,omitempty"`
	Fields     []string        `json:"fields,omitempty"` // field-level allowlist (read-only roles)

	// Permissions is the per-resource form (G2): resource name → its grant. Empty for
	// a legacy role; omitempty keeps the marshalled legacy policy byte-identical so the
	// schema→rbac.Policy round-trip is unchanged for every existing schema.
	Permissions map[string]ResourcePermission `json:"permissions,omitempty"`

	// Routes grants access to CUSTOM ROUTES — endpoints a Go backend registers with
	// (*App).Register, whose first /api/ segment the engine authorizes as a VIRTUAL
	// resource (LIBRARY-GAPS-S1). It is keyed by that segment, with its own actions:
	//
	//	"routes": { "checkout": { "actions": ["create"] } }   → POST /api/checkout
	//
	// It is ORTHOGONAL to resources/permissions — a role may declare both, because
	// they govern different namespaces (real tables vs registered endpoints). That
	// is the whole point: before this key, a role using per-resource `permissions`
	// could not reach ANY custom route (every permissions key is checked against a
	// real resource), so "owner-scoped end users + a custom action endpoint" — a
	// customer with their own orders AND a checkout — was inexpressible.
	//
	// SEMANTICS, deliberately narrow:
	//   - AUTHORITATIVE: for a segment listed here, this entry decides. It can only
	//     narrow a wildcard role, never widen one — a segment NOT listed falls
	//     through to the role's normal resources/permissions evaluation, so
	//     deny-by-default is untouched.
	//   - NO conditions, NO field allowlist. A virtual segment has no rows and no
	//     columns; a row filter would be injected into SQL for a table that does not
	//     exist. Declaring either is a LOAD error, never a silent no-op.
	//   - Validated at BOOT against the REGISTERED routes: a grant for a segment no
	//     route serves (or an action no registered method provides) fails the boot
	//     with a clear message, instead of a confusing 403 at request time.
	// See docs/adr/ADR-021-custom-route-authorization.md.
	Routes map[string]RouteGrant `json:"routes,omitempty"`
}

type RouteGrant struct {
	Actions []string `json:"actions"`
}

type StateMachine struct {
	Initial     []string            `json:"initial"`
	Transitions map[string][]string `json:"transitions"`
}

type StringList []string

type StructuredError struct {
	Path     string   `json:"path"`               // dotted location, e.g. resources.posts.fields.author_id.references
	Rule     string   `json:"rule"`               // machine-readable category, e.g. invalid_type
	Message  string   `json:"message"`            // human-readable explanation
	Expected []string `json:"expected,omitempty"` // allowed values, when a closed set
	Got      string   `json:"got,omitempty"`      // the offending value, when applicable
	Fix      string   `json:"fix,omitempty"`      // how to correct it
	Source   string   `json:"source"`             // "metaschema" (structural) | "semantic" (cross-reference)
}

type ValidationError struct {
	Field   string
	Message string

	// Structured metadata for the LLM-friendly report (AI-F0-S2). All optional —
	// an error that predates the enrichment leaves them empty and the report derives
	// a fallback Rule from the Field path. They are NOT part of Error(), so the human
	// (interactive) output is byte-unchanged.
	Rule     string   `json:"rule,omitempty"`     // machine-readable category, e.g. "invalid_type"
	Fix      string   `json:"fix,omitempty"`      // how to correct it (an LLM can apply this)
	Expected []string `json:"expected,omitempty"` // the allowed values, when a closed set
	Got      string   `json:"got,omitempty"`      // the offending value, when applicable
}

type ValidationReport struct {
	Valid  bool              `json:"valid"`
	Errors []StructuredError `json:"errors"`
	// Warnings are findings that do NOT make the schema invalid but almost always
	// mean it will not do what its author intended (SCHEMA-5). They are reported in
	// the same shape as errors so the AI correction loop can act on them with the
	// same code path, and `valid` stays true — a warning never blocks a deploy.
	//
	// ALWAYS EMITTED, even when empty — deliberately not omitempty. With the key
	// absent, "this schema has no warnings" and "this binary has no warnings
	// feature" are the same JSON, so a caller cannot tell a clean bill of health
	// from an old engine. A third-party agent reported exactly that: it could not
	// confirm zero warnings as a POSITIVE signal and pre-empted the known rules by
	// hand instead. `errors` has always been emitted unconditionally; this makes
	// the two halves of the report symmetric.
	Warnings []StructuredError `json:"warnings"`
}

type WorkflowSchema struct {
	Trigger WorkflowTrigger `json:"trigger"`
	Steps   []WorkflowStep  `json:"steps,omitempty"`
}

type WorkflowStep struct {
	Name   string         `json:"name"`
	Type   string         `json:"type"`             // "hook" | "webhook" | "wasm" | "branch"
	Ref    string         `json:"ref,omitempty"`    // hook/module/url reference
	Config map[string]any `json:"config,omitempty"` // step-specific configuration
	Next   string         `json:"next,omitempty"`   // name of the next step (or branch target)
}

type WorkflowTrigger struct {
	Type     string `json:"type"`               // "event" | "cron" | "http"
	Event    string `json:"event,omitempty"`    // e.g. "after_create" (with Resource)
	Resource string `json:"resource,omitempty"` // resource the event applies to
	Cron     string `json:"cron,omitempty"`     // cron expression for type=cron
	Path     string `json:"path,omitempty"`     // route for type=http
}