schema

type Attachment string

type BaseChild struct {
	ID       string `oj:"-"` // ULID — set by Document Engine
	ParentID string `oj:"-"` // ID of the parent Document record
	Idx      int    `oj:"-"` // position within the parent's child list
}

type BaseDocument struct {
	ID         string    `oj:"-"` // ULID — set by Document Engine
	Name       string    `oj:"-"` // human-readable identifier
	Owner      string    `oj:"-"` // user ID who created the record
	CreatedAt  time.Time `oj:"-"`
	UpdatedAt  time.Time `oj:"-"`
	ModifiedBy string    `oj:"-"` // user ID who last modified
	DocStatus  int       `oj:"-"` // 0=Draft, 1=Submitted, 2=Cancelled
	Deleted    bool      `oj:"-"` // soft-delete flag
}

type Cardinality string

type ColumnAlteration struct {
	// FieldName is the Go struct field name.
	FieldName string
	// ColumnName is the SQL column name being altered. Added for type-change
	// rendering (TAD §14's struct is silent on it; without it ALTER COLUMN
	// cannot be generated).
	ColumnName string
	// OldColumn is the previous DB column definition (dialect-specific).
	OldColumn string
	// NewColumn is the desired DB column definition.
	NewColumn string
}

type CompiledChild struct {
	// FieldName is the parent struct field name (e.g. "Skills").
	FieldName string
	// TypeName is the Go type name of the child struct (e.g. "EmployeeSkill").
	TypeName string
	// DocType is the canonical DocType name for the child table
	// (snake_case of TypeName by default, or set explicitly via DocMeta).
	DocType string
	// TableName is the pluralized snake_case table name, derived from TypeName
	// by the exact same rule as main tables (camelToSnake + "s", TAD §1.4).
	// Computed once at compile time so no consumer can derive it differently.
	TableName string
	// Fields is the compiled field set of the child struct.
	Fields []Field
	// Junction marks a child table as a many-to-many junction
	// (oj:"junction"). Storage and engine mechanics are identical to any other
	// child table; the flag changes only relationship metadata at compile time
	// — the junction's Link fields become many_to_many edges between the parent
	// and their targets. See Orjanda_relationship_model_proposal.md §3.8.
	Junction bool
}

type CompiledDoc struct {
	// Name is the canonical DocType name (e.g. "Employee").
	Name string
	// App is the app.Definition.Name that registered this Document.
	App string
	// Module is the logical grouping within the Application.
	Module string
	// TableName is the SQL table name (plural snake_case of Name).
	TableName string
	// Searchable — see Meta.Searchable.
	Searchable bool
	// Submittable — see Meta.Submittable.
	Submittable bool
	// Icon — see Meta.Icon.
	Icon string
	// Description — see Meta.Description.
	Description string
	// TitleField — see Meta.TitleField.
	TitleField string
	// SortField — see Meta.SortField.
	SortField string
	// SortOrder — see Meta.SortOrder.
	SortOrder SortOrder
	// Fields is the ordered list of compiled fields (base fields excluded —
	// they live in BaseDocument and are prepended by the Registry compiler).
	Fields []Field
	// Permissions is the per-role permission list from DocMeta().
	Permissions []DocPermission
	// ChildTables is the list of embedded child table types.
	ChildTables []CompiledChild
	// AgentHidden excludes the entire DocType from agent tool generation.
	AgentHidden bool
}

type Currency float64

type Date time.Time

type DateTime time.Time

type DocPermission struct {
	// Role is the role name this permission entry applies to (e.g. "HR Manager").
	Role string
	// CRUD flags.
	Read   bool
	Write  bool
	Create bool
	Delete bool
	// Submit controls whether the role may submit a Submittable Document.
	Submit bool
	// Match optionally restricts this permission to a subset of records.
	// Defaults to MatchAll (zero value).
	Match MatchType
}

type Document interface {
	// DocMeta returns the static metadata for this Document type.
	DocMeta() Meta

	// GetID returns the record's primary key (ULID string).
	GetID() string
	// SetID sets the primary key. Called by the Document Engine on creation.
	SetID(string)

	// Get returns a field value by Go struct field name.
	// Used by the Document Engine for map-based I/O without reflection.
	Get(field string) any
	// Set sets a field value by Go struct field name.
	// Returns errors.CodeValidation if the field name is unknown.
	Set(field string, value any) errors.Error
}

type DynamicLink struct {
	RefDocType string `json:"doctype"`
	RefID      string `json:"id"`
}

type Field struct {
	// Name is the Go struct field name (e.g. "FirstName").
	Name string
	// DBColumn is the snake_case column name (e.g. "first_name").
	DBColumn string
	// Type identifies the storage and agent interpretation category.
	Type FieldType
	// Required — field must have a non-zero value on create/update.
	Required bool
	// Unique — uniqueness constraint enforced by the DB and Document Engine.
	Unique bool
	// Searchable — included in full-text search index.
	Searchable bool
	// Label is the human-readable field label for UI and agent descriptions.
	Label string
	// Options holds the enumerated allowed values from oj:"options=A|B|C".
	Options []string
	// Default holds the string-encoded default value from oj:"default=X".
	Default string
	// Format is an optional validation format string: "email", "url", "phone".
	Format string
	// LinkTarget is the DocType name that a Link field references.
	LinkTarget string
	// LinkTargets is the optionally-declared `targets=A|B|C` set for a
	// DynamicLink field. Empty means "any registered DocType" (backward
	// compatible). Populated only for FieldTypeDynamicLink. See
	// Orjanda_relationship_model_proposal.md §3.10.
	LinkTargets []string
	// LinkTargetTable is the SQL table name of LinkTarget, resolved at compile
	// time by Registry.Compile() so the DAL dialects can emit a DB-level
	// FOREIGN KEY ... REFERENCES <table> without reaching into the Registry
	// (see Orjanda_relationship_model_proposal.md §3.5). Populated only for
	// FieldTypeLink fields; empty otherwise.
	LinkTargetTable string
	// NoFK skips DB-level FOREIGN KEY generation for this Link field
	// (oj:"link=X,no_fk"). Escape hatch for rare cross-shard/multi-tenant
	// cases where a hard constraint is undesirable — advanced/discouraged.
	// See Orjanda_relationship_model_proposal.md §3.5.
	NoFK bool
	// OnDelete is the declared delete behavior for a Link field
	// (oj:"on_delete=restrict|cascade|set_null", default restrict). Empty on
	// non-Link fields. Enforced by the Document Engine (soft-delete semantics)
	// — see Orjanda_relationship_model_proposal.md §3.6.
	OnDelete OnDeleteAction
	// Inverse is the optional cosmetic inverse-relationship label declared with
	// oj:"inverse=Name"; surfaced as the InverseLabel of inbound Relationship
	// entries. See Orjanda_relationship_model_proposal.md §3.7.
	Inverse string
	// ChildTypeName is the Go type name of child structs for FieldTypeChildTable.
	ChildTypeName string
	// Precision is the decimal precision for Currency fields.
	Precision int
	// PermissionRole gates access to this field to identities holding the
	// given role (oj:"permission=role"). Empty string means no gate.
	PermissionRole string
	// Hidden excludes the field from the default UI and agent BaseSchema.
	Hidden bool
	// System marks a framework-managed field (id, owner, created_at, ...).
	// Hidden system fields stay sortable; hidden user-data fields do not
	// (REVIEW-2026-08-12 finding 10: order_by must not reveal hidden data).
	System bool
	// ReadOnly prevents modification after initial creation.
	ReadOnly bool
	// Computed marks a derived value that is not stored.
	Computed bool
	// AgentHint is additional plain-text context appended to the field's
	// JSON Schema description in agent tool definitions. See PRD §24.4.
	AgentHint string
	// ValidatorName holds the oj:"validator=Name" registered validator name.
	ValidatorName string
	// AgentHidden excludes the field from the agent BaseSchema entirely,
	// stronger than Hidden (which still appears in the DB/API). See TAD §12.2.
	AgentHidden bool
}

type FieldType string

type ForeignKeyAction string

type ForeignKeyConstraint struct {
	// Table is the referencing table holding the foreign key column.
	Table string
	// Column is the referencing (child) column.
	Column string
	// RefTable is the referenced (parent) table.
	RefTable string
	// RefColumn is the referenced parent column (always "id" in Orjanda).
	RefColumn string
	// OnDelete is the desired ON DELETE action (RESTRICT/CASCADE/SET NULL).
	// For a CHANGE it also reflects the desired (new) action.
	OnDelete OnDeleteAction
	// Action is ADD, DROP, or CHANGE.
	Action ForeignKeyAction
}

type JSON []byte

type Link string

type MatchType int

type Meta struct {
	// Name is the canonical DocType name (e.g. "Employee"). Must be unique
	// within the Registry. Required.
	Name string
	// Module is the logical grouping within the Application (e.g. "HR").
	// Used by the Admin UI sidebar. Optional.
	Module string
	// Searchable marks the DocType as full-text searchable.
	// Generates a search_* agent tool (TAD §10.1 step 1).
	Searchable bool
	// Submittable marks the DocType as having a submission lifecycle.
	// Adds DocStatus field handling (PRD §10.2).
	Submittable bool
	// Icon is a UI hint for the Admin UI sidebar icon.
	Icon string
	// Description is a human-readable summary surfaced in the UI and Metadata API.
	Description string
	// AgentHidden excludes the entire DocType from agent tool generation
	// (TAD §10.1 — the schema-level agent_hidden flag, distinct from the
	// per-field hidden/agent_hidden tags of PRD §10.4 / TAD §12.2).
	AgentHidden bool
	// TitleField is the expression (field name or "First + Last" style) that
	// produces a human-readable record title in list views. See PRD §10.1.
	TitleField string
	// SortField is the default sort field for list queries.
	SortField string
	// SortOrder is Ascending (default) or Descending.
	SortOrder SortOrder
	// Permissions declares per-role CRUD grants for this DocType.
	Permissions []DocPermission
}

type OnDeleteAction string

type Registry interface {
	Get(docType string) (*CompiledDoc, error)
	List() []*CompiledDoc
	Relationships(docType string) []Relationship
	Register(app string, doc Document) error
	Compile() error
}

type Relationship struct {
	// FromDoc is the DocType that declares the link (outbound) or that holds
	// the reference reaching this DocType (inbound).
	FromDoc string
	// FromField is the field name on FromDoc that holds the reference. For a
	// many-to-many edge it is the parent child-table field carrying the
	// junction.
	FromField string
	// ToDoc is the target DocType.
	ToDoc string
	// IsChildTable is true when the relationship is backed by a child table
	// (ownership one_to_many or a many_to_many junction), false when it is a
	// Link (foreign key).
	IsChildTable bool
	// Direction is outbound when the relationship is declared on the queried
	// DocType, or inbound when synthesized from another DocType referencing it.
	Direction RelationshipDirection
	// Cardinality is derived at compile time: many_to_one (Link), one_to_one
	// (Link + unique), one_to_many (child table), many_to_many (junction).
	Cardinality Cardinality
	// InverseLabel is the human-readable label of the inverse edge:
	// oj:"inverse=X" on the declaring field, or a synthesized default (the
	// pluralized declaring DocType).
	InverseLabel string
	// OnDelete is the declared delete behavior of a Link edge ("" for child
	// table and virtual inbound edges when the field was non-Link).
	OnDelete OnDeleteAction
	// ViaJunction is non-empty only for many_to_many edges; it names the child
	// DocType that backs the junction (e.g. "project_member").
	ViaJunction string
	// ViaField is non-empty only for many_to_many edges; it names the junction
	// child's Link field through which the edge reaches ToDoc (e.g. "User").
	// The Admin UI uses it to read/write the junction rows when editing the
	// owning Document's child array. See registry.go junction resolution.
	ViaField string
}

type RelationshipDirection string

type RichText string

type SchemaDiff struct {
	// CreateTables is the list of new DocTypes that need a CREATE TABLE.
	CreateTables []CompiledDoc
	// AlterTables is the list of existing tables with column changes.
	AlterTables []TableAlteration
	// DropTables lists orphaned Orjanda-owned tables that exist in the live
	// database but are no longer produced by the Registry (requires
	// --allow-destructive, see TAD §14.1 step 2).
	DropTables []string
	// ForeignKeys lists FK deltas (add/drop/change). DROP and CHANGE are
	// destructive — gated by --allow-destructive (proposal §5.1).
	ForeignKeys []ForeignKeyConstraint
}

type SortOrder int

type TableAlteration struct {
	// TableName is the SQL table name being altered.
	TableName string
	// AddColumns is the list of new fields to add as columns.
	AddColumns []Field
	// DropColumns lists column names to drop (requires --allow-destructive).
	DropColumns []string
	// AlterColumns lists columns whose type or constraints have changed.
	AlterColumns []ColumnAlteration
}

type Text string

type Validator interface {
	// Validate returns nil if the value passes, or an errors.Error with
	// Code() == errors.CodeValidation on failure.
	Validate(ctx context.Context, field Field, value any) error
}