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 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
}

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 string

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
	// 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 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 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.
	FromDoc string
	// FromField is the field name on FromDoc that holds the reference.
	FromField string
	// ToDoc is the target DocType.
	ToDoc string
	// IsChildTable is true when the relationship is a child table embed,
	// false when it is a Link (foreign key).
	IsChildTable bool
}

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
}

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
}