Complete Entity Grammar

The Live Vocabulary Inventory is the companion raw index of every exported type. This page explains how those terms compose and which properties authors can configure.

This page is the implementation-backed reference for describing an entity from its smallest value atom through database generation, protocol execution, and application rendering.

It answers two questions:

1. What can a Blueprint author configure?
2. Which declarations are semantic objects, typed references, extension keys, or physical/wire identifiers?

The grammar is industry-neutral. Pharma, finance, public-sector, logistics, and other domains supply different declarations; they do not get different Blueprint runtimes.

Universal vocabulary identity

Every renderable Blueprint vocabulary item crosses the explorer and protocol boundary with one canonical schema identity:

Property	Contract
schemaType	Required semantic discriminator. Consumers dispatch only on this value.
name	Required stable vocabulary name. It is not title-cased or localized.
title	Required human-facing display string. It may be explicitly authored or deterministically derived during assembly.
code	Optional exact developer identifier such as iam.user or mfg.equipment.cleaning.release. Its case and punctuation are preserved.
pluralTitle	Optional plural display string for collection surfaces.
description	Optional explanatory display copy.
i18nKey	Optional localization lookup key.

Columns use the same nomenclature: name is the stable projected field name and title is the visible column heading. The canonical wire contract does not introduce a parallel label property. A renderer may call a text widget a label internally, but it must not manufacture Blueprint identity from UI terminology.

The typed sealed ProjectionResult hierarchy remains the cardinality and data shape contract. schema.schemaType remains its only semantic discriminator; name, title, and code are identity and display metadata, never alternate type tags. The wire-level shape value (collection, item, or custom) selects the sealed data envelope only; it does not identify business semantics.

The authoring rule

Use this precedence whenever one declaration points at another:

1. Hold the declaration object when both objects are in the same Dart graph.
2. Hold a typed Ref when the target is cross-module, configuration data, or a registered extension.
3. Use a string only at an explicitly named physical, protocol, registry, or presentation boundary.

Fields follow that rule rigorously:

abstract final class AreaFields {
  static const tenantId = TenantIdField();
  static const code = CodeField();
  static const name = NameField();
  static const status = StatusField(
    'status',
    AreaStatus.values,
    dbEnumName: 'area_status',
  );
  static const createdAt = TimestampField('created_at');
}

const areaUi = EntityUI(
  list: ListUI(
    layouts: [
      TableUI(
        columns: [
          TableColumnUI(field: AreaFields.code, required: true),
          TableColumnUI(field: AreaFields.name),
          TableColumnUI(
            field: AreaFields.status,
            appearance: UIColumnAppearance.status,
          ),
          TableColumnUI(
            field: AreaFields.description,
            visible: false,
          ),
        ],
        defaultFilter: Compare(
          AreaFields.status,
          PredicateOp.equals,
          'active',
        ),
        defaultOrderBy: [FieldOrder(AreaFields.name)],
      ),
      GridUI(
        content: CardContentUI(
          titleField: AreaFields.name,
          subtitleField: AreaFields.code,
          statusField: AreaFields.status,
        ),
      ),
    ],
  ),
);

Never repeat semantic field names in those surfaces:

// Do not author this:
// columns: ['code', 'name']
// defaultOrderBy: [FieldOrder('name')]
// filter: FilterCondition(field: 'status', ...)

ProjectedFieldRef('qualified.path') is the deliberate escape hatch for a field produced by assembly, a projection, or an extension when no declaration token exists. It is not a shortcut for avoiding a real Field constant.

End-to-end structure

The entity declaration is not a generated API model. It is the program the generic runtime interprets.

Configuration inventory

This is the exhaustive map of the current built-in grammar. Each row points to the section that defines the individual properties and sealed choices. An extension reference is an intentional escape hatch; it does not turn the grammar into an untyped property bag.

Plane	Configurable surface	What can be configured
Program	Blueprint	Identity, version, modules, Blueprint-wide query limits, and action-placement defaults.
Program	Module	Namespace, database schema, release, dependencies, exports, entities, contributed descriptors, rules, task templates, DB posture, UI defaults, and seed pack.
Domain	Entity	Identity, physical table, human language, facets, direct tenant field, aggregates, save history and governed revisions, unique keys, projection, DB hints, UI hints, and seed hints.
Domain	Facet	Name, language, fields, relationships, lifecycle, actions, derived values, UI grouping, contribution priority, and merge mode.
Data	Field<T>	Semantic type, name, title, help, nullability, default, validation, indexing, DB mapping, seed strategy, UI presentation, input behavior, formatting, and derivation. Uniqueness is Entity.uniqueKeys.
Data	field type	Text, integer, decimal, boolean, UUID, timestamp, date, time, duration, JSON, binary, list, enum, reference, actor, tenant, site, code, name, description, status, identifier, effective-from, and effective-until semantics.
Data	Relationship	Name, target entity, cardinality/kind, owning field, requiredness, physical or logical storage, discriminator, cascade, inverse name, and picker/detail presentation.
Data	derived/projection	Expression/evaluator, dependencies, materialization, cache behavior, projection fields, relationship expansions, and projection purpose.
Behavior	Lifecycle	State field, initial state, transitions, triggers, guards, effects, and transition action binding.
Behavior	Action	Identity, language, input contract, rules, capture contract, evidence requirements, audit envelope, snapshots, emitted domain events, effects, idempotency, and UI metadata.
Behavior	rule/condition	Access, data, policy, lifecycle, aggregate, separation-of-duties, field comparison, existence, evidence, actor/grant, boolean composition, and evaluator references.
Behavior	effect	Create/update/delete, transition, event, notification, outbox, task, workflow signal/start/complete, evidence, audit, and custom effect references.
Work	actor/assignment/task	Actor kind and source, assignee strategy, candidate users/groups/roles, scope, due/escalation rules, completion requirements, and task payload.
Integrity	invariant/subscription	Row/aggregate/evaluator truth, severity, dependencies, subscribed entities/events, invalidation scope, and handler references.
Storage	ModuleDb	Extensions, RLS mode, audit mode, realtime, outbox, retention, cross-entity indexes, triggers, views, materialized views, and notes.
Storage	EntityDb	Sizing, write rate, read pattern, partitioning, partition field, audit/realtime overrides, retention, query patterns, and notes.
Storage	FieldDb	SQL type override, column name, generated expression, collation, index method, operator class, check expression, and storage notes.
Seed	module/entity/field seed	Enablement, deterministic pack, scale, realism, locale, tenant/scenario coverage, record counts, fixed values, generator, sequence, null rate, distribution, reference strategy, and system seed actor.
Entity UX	EntityUI	Icon, visibility, access, category, route prefix, explicit-or-derived collection contract, typed list columns, default sort, read-only behavior, priority, query limits, action placements, and detail-tab extensions.
Field UX	FieldUI	Title/help, visibility, input capability, required/read-only behavior, editor kind, formatter, mask, placeholder, value titles, table/filter/sort/search/group participation, column appearance, reference picker, derivation, and extension key.
Relationship UX	RelationshipUI	Picker/link/detail presentation, option search, title/subtitle fields, projection, empty behavior, and relationship-tab behavior.
App UX	BlueprintApp	Routes, menus, effective entity UI plans, settings, global search, command palette, status bar, shell, deployment labels, app portfolio, and developer tools.
Collection UX	ListUI	Projection, typed columns, default predicate, typed order, supported view modes, query limits, paging, selection, create action, and empty/loading/error behavior.
Detail UX	detail/tab surfaces	Summary, related data, versions, audit, workflow/runtime data, Blueprint metadata, tab ordering, visibility, actions, docking, and custom builders.
Editor UX	editor/form surfaces	Create/edit mode, dock/dialog/page presentation, single or multiple parts/tabs, facet inclusion, explicit sections, typed field placement, columns, unplaced-field policy, actions, dirty guard, and custom form binding.
Shell UX	shell surfaces	Navigation, pinned/compact behavior, actor and scope selectors, theme/text scaling, global search, notifications, environment/release badges, status-bar contributions, dock defaults, and portfolio awareness.
Runtime	protocol/runtime configuration	Protocol base, installed Blueprint/features, persistence strategy, authentication context, environment discovery, query and action execution, retries, cache, realtime, logging, tracing, and developer transcript exposure.
Extension	typed refs	Evaluator, transformer, formatter, editor, renderer, effect, policy, persistence, seed generator, route, and custom surface references.

Configuration cascade

Defaults are resolved property by property, not by replacing an entire lower level object:

field / relationship / action
  -> facet
  -> entity
  -> module
  -> blueprint
  -> platform default

An explicit value wins. An absent value inherits. A sealed off, none, or hidden value is an explicit override and therefore does not inherit. Runtime policy can further reduce the effective result, but cannot silently expand what the declaration permits.

Declared, derived, and runtime-effective

Not every runtime value is author-configurable:

Kind	Source
Declared	The domain or app author chooses it in the Blueprint.
Derived	Assembly computes routes, default projections, inverse cache edges, generated DB artifacts, editor fields, and dependency order from declarations.
Runtime-effective	Actor grants, subscription, tenant/site scope, record state, policy decisions, installed extensions, environment, and feature licensing reduce or specialize the declared result.
Recorded	Action id, command id, timestamps, actor, request lineage, technical version, revision evidence, emitted events, effects, and audit outcome are created by execution and cannot be authored retroactively.

The runtime must reject an unresolved reference or unsupported configuration. It must not guess a field name, fabricate tenant scope, synthesize persistence data, or silently substitute an editor.

1. Blueprint

Blueprint is the root domain program.

Property	Meaning
name	Stable Blueprint identity.
version	Version of the declaration program.
modules	Bounded contexts assembled into the program.
ui	Blueprint-wide UI defaults.

Blueprint.single(...) is a convenience for a one-module program. bootstrap() assembles descriptors and returns an EffectiveBlueprint.

BlueprintUI currently configures:

• query limits with QueryUI
• inherited ActionPlacementUI contributions

QueryUI supports maxSortLevels and maxGroupLevels. Values cascade one property at a time:

entity -> module -> blueprint -> platform default

2. Module

Module is a namespace, release, database-schema, governance, and ownership boundary.

Property	Meaning
name, schema, version	Stable module identity and schema placement.
title, pluralTitle, description, i18nKey	Human language.
entities	Entity declarations owned by the module.
descriptors	Cross-module contributions assembled onto entities.
dependsOn	Module dependency DAG.
exports	Cross-module entity, derived-value, and trigger gates.
rules	Module-wide Rule truths lifted onto mutating actions.
taskTemplates	Assignment-shaped work contracts.
db	Schema-level physical and security posture.
ui	Module UI defaults.
seed	Module seed-pack guidance.

Exports are sealed as:

• EntityExport
• DerivedValueExport
• TriggerExport

ModuleUI configures icon, visibility, access, category, route prefix, module/category navigation hierarchy and disclosure behavior, query limits, and action placements.

ModuleDb configures:

• Postgres extensions
• audit mode: standard, full, immutable
• realtime: off, on, outboxOnly
• RLS: off, permissive, enforced
• outbox: off, schema, perEntity
• retention reference
• cross-entity physical indexes
• database triggers
• views and materialized views
• design notes

ModuleSeed configures enablement, dataset size (none, smoke, demo, validation, load), realism (synthetic, realistic, regulated), locale, tenant/scenario coverage, and notes.

3. Entity

Entity is the identity-bearing aggregate root.

Property	Meaning
name	Module-local identity.
schemaType	Stable qualified identity; defaults to module.entity.
tableName, schema	Physical host-table placement.
title, pluralTitle, description, i18nKey	Human language.
facets	Composable state and behavior slices.
tenantField	Optional typed tenant field reference for directly tenant-scoped entities. Null means global or scope-through-owner; no field name is fabricated.
aggregates	Cross-facet derived values.
versioning	none, save versions, or governed revisions(...).
uniqueKeys	Composite uniqueness expressed as List<List<Field>>.
projection	Effective entity read projection.
db, ui, seed	Physical, presentation, and seed configuration.

Versioning

EntityVersioning.none has no immutable entity history.

EntityVersioning.versions records one monotonic sequence of immutable snapshots for optimistic concurrency, forensic history, and reconstruction.

const EntityVersioning.revisions(...) uses the same save sequence and adds a governed draft/review/effective revision lifecycle. Its revision policy, actions, audit requirements, and owned relationships live directly on the versioning declaration. There is no entity role, master constructor, or separate master-control object.

The generated history table is <host_table>_versions. Its primary key is (entity_id, version). The history intentionally outlives deletion of the current record.

Governed revisions use <host_table>_revisions; host columns are named revision_id, revision_number, revision_status, parent_revision_id, and effective_revision_id.

Entity DB configuration

EntityDb configures:

• expected rows: unknown, small, medium, large, millions, billions
• write rate: unknown, low, medium, high, streaming
• read pattern: unknown, runtimeLookup, runtimeList, analytical, appendOnly, eventStream
• partition strategy: none, tenant, time, tenantAndTime
• typed partition field
• audit and realtime overrides
• retention reference
• query patterns
• notes

Query patterns are filter, join, sort, search, range, aggregate, uniqueness, lifecycle, audit, and realtime.

Entity seed configuration

EntitySeed configures enablement, target/minimum/maximum rows, scenarios, additional generation dependencies, and notes. Relationship dependencies are derived automatically; dependsOn is only for dependencies not represented by the relationship graph.

4. Facet

Facet owns one cohesive state/behavior slice.

Property	Meaning
name, title, description, i18nKey	Identity and language.
fields	Stored typed state.
relationships	Entity graph edges owned by this facet.
lifecycle	State machine, if any.
actions	Commands this facet accepts.
projection	Facet read projection.
derived	Pure calculated values.
subscriptions	Reactions to published derived changes.
evidence	Proof vocabulary owned by the facet.
audit	Default audit envelope.
dependsOn	Facet assembly DAG.
ui	Section/detail/editor posture.

IdentityFacet fixes its name to identity and anchors entity identity.

FacetUI configures section kind, access, order, and collapsed-by-default. Section kinds are form, detail, lifecycle, evidence, audit, relationships, and analytics.

5. Fields

Common field configuration

Every Field<T> can configure:

• name
• title, description, i18nKey
• nullable
• literal defaultValue
• runtime/database defaultExpr
• simple indexed and unique flags
• FieldDb
• FieldUI
• UIReferenceHint
• FieldSeed

Default expressions are now, uuidV4, actorId, and siteId.

Primitive field tokens

Token	Dart value	Additional configuration
TextField	String	maximum length
IntegerField	int	—
BigIntField	int	—
DoubleField	double	—
DecimalField	exact decimal string	precision, scale
BooleanField	bool	—
TimestampField	DateTime	timezone posture
DateField	DateTime	—
UuidField	String	—
JsonbField	JSON object	—
EnumField<E>	Dart enum	values, Postgres enum name
ListField<T>	typed list	element codec
FileField	file descriptor JSON	kind, size, MIME types, multiplicity

Semantic field tokens

Use semantic tokens to carry cross-surface conventions without repeating hints:

• CodeField
• NameField
• DescriptionField
• TenantIdField
• SiteIdField
• ActorField
• StatusField<E>
• EffectiveFromField
• EffectiveUntilField
• ReferenceIdField
• IdentifierField
• QuantityField
• MoneyField
• RelatedField<T>

IdentifierField supports literal, context, sequence, and code segments plus reset scopes (tenant, site, year, month).

QuantityField and MoneyField require either a typed companion field or a fixed unit/currency ref.

Field DB configuration

FieldDb configures index materialization, index kind (btree, hash, gin, gist, brin), query patterns, cardinality (unknown, low, medium, high, unique), partial-index predicate, and notes.

Field seed configuration

FieldSeed configures:

• strategy: auto, code, label, enumValue, range, relationship, timestamp, jsonObject, evidenceArtifact, instrumentReading
• example values
• controlled-vocabulary refs
• numeric min/max
• pattern
• sensitive-data posture
• notes

Field UI configuration

FieldUI is the shared source for tables, details, filters, and editors.

Group	Configurable properties
Editor	widget, input posture, form section, read-only, hidden, placeholder, help text, custom editor ref
Query	filterable, sortable, searchable
Table	table-column flag, appearance, width factor, minimum width, responsive visibility
Values	boolean labels, enum/choice labels, option-search behavior and threshold
Access	read/write/execute rules
Ordering	field order
Derivation	source fields, transforms, override behavior, create/update application

Built-in widgets are auto, text, multilineText, number, decimal, checkbox, date, dateTime, enumSelect, referencePicker, jsonEditor, evidencePicker, signature, checklist, photoCapture, instrumentCapture, and custom.

Input posture is auto, never, create, update, or createAndUpdate.

Column appearance is auto, identity, badge, status, metric, or timestamp. Responsive visibility starts at always, sm, md, lg, xl, or xxl.

Option search is auto, always, or never.

Derived form values

UIFieldDerivation links writable fields generically:

const codeUi = FieldUI(
  derivation: UIFieldDerivation(
    sourceFields: [AreaFields.name],
    transforms: [
      UITrimTransform(),
      UIUpperCaseTransform(),
      UIReplacePatternTransform(pattern: r'[^A-Z0-9]+', replacement: '-'),
    ],
    override: UIFieldDerivationOverride.untilOverridden,
  ),
);

Built-in transforms are join, trim, upper-case, lower-case, and regex replace. UIFieldTransformRef is the runtime extension escape hatch.

6. Relationships

Relationship configures:

• identity, title, description, i18n key
• target entity
• kind: belongsTo, hasOne, hasMany, manyToMany
• explicit typed storage field
• storage: foreignKey or logical
• cascade: restrict, nullify, cascade, preserveHistory
• embed hint: lazy, eager, manual
• requiredness
• typed discriminator field and discriminator value
• RelationshipUI

RelationshipUI configures picker/list/table/card/tree/graph/custom presentation, projection, searchable options, editor/detail/inverse visibility, related-record creation, order, access, custom picker ref, and custom renderer ref.

A foreign key is not the relationship. The field owns storage; the relationship owns graph semantics. Association data belongs in an association entity, not in a magical many-to-many edge.

7. Derived values and projections

Derived values are sealed by execution tier:

• GeneratedColumnDerivedValue
• SqlViewDerivedValue
• MaterializedViewDerivedValue
• ServerDerivedValue

All carry name, output type, human language, and typed dependencies. Specialized members configure SQL expression/select, refresh events, or a server evaluator ref.

Projection configuration includes:

• ProjectionMode: read, write, readWrite
• StoragePlacement
• StorageBinding
• ProjectionAccess
• QueryBehavior
• ProjectionUIBehavior
• ProjectedField
• FacetProjection
• EntityProjection

Projection sourcePath, statePath, generated column names, and JSON paths are assembled/wire identifiers. They are intentionally strings because they name the lowered projection artifact, not a declaration-plane field.

8. Lifecycle

Lifecycle configures a typed state field, legal transitions, and optional initial state.

Transition configures:

• from state or Transition.anyState
• to state
• same-facet trigger/action name
• typed rule refs
• outbound effects

The validator requires (from, trigger) to be deterministic.

9. Actions

Action is the complete command contract.

Area	Configuration
Identity	name, title, description, i18n key, source references
Invocation	source, scope, payload fields, consistency, idempotency field
Decision	rules and typed errors
Proof	evidence, audit envelope, snapshot strategy
Output	declared events and effects
Replay	capture policy
UI	icon, presentation, access, order, tooltip, confirmation, destructive flag, capture-form ref

Sources are manual, system, workflow, and event. Scope is collection, selection, or record. Consistency is strict or eventual.

Create, update, archive/delete, and restore are ordinary actions—normally contributed by the identity facet—not special protocol endpoints.

Rules and conditions

Rule configures id, kind, phase, condition, severity, typed error, i18n, source references, and metadata.

Rule kinds are access, policy, lifecycle, data, evidence, audit, snapshot, effect, and custom. Phases are availability, before-commit, after-commit, and async. Severity is info, warning, or blocking.

Conditions are exhaustive:

• AlwaysCondition
• NeverCondition
• PredicateCondition
• ActorInSetCondition
• AllCondition
• AnyCondition
• NotCondition
• EvaluatorCondition
• ActorHasGrantCondition
• ActorQualifiedCondition
• PolicyAllowsCondition
• StateIsCondition
• FieldEqualsCondition
• ExistsCondition
• EvidencePresentCondition

FieldPredicate provides MatchEverything, MatchNothing, Compare, AllMatch, AnyMatch, and NoneMatch. Compare holds a FieldRef, not a field-name string.

Evidence and audit

Evidence kinds are artifact, log, controlled document, photo, record, signature, checklist, generated report, and external reference.

Each Evidence configures identity/language, requiredness, typed producer ref, retention ref, and metadata.

AuditEnvelope configures signature, reason code, actor/dual-control signature mode, evidence, replayability, and metadata.

Evidence is proof collected by an action. Audit is the immutable account of the action context and outcome. They are linked but not interchangeable.

Snapshots, events, and effects

ActionCapture.snapshot (ContextSnapshot) contains named environment targets captured by SnapshotStrategy.reference (revision pin) or SnapshotStrategy.value (blob).

ActionEvent configures name, event kind, optional entity/facet/payload adapter, requiredness, provenance, and metadata.

Effect configures target entity/facet/trigger, typed target-payload to source-field mapping, typed target-id source, and consistency override. Workflow signaling is an effect like any other; the kernel has no workflow-specific transaction path.

ActionCapture configures proofs (evidence), the environment pin (snapshot), traces, and whether payload and events are retained.

10. Actors, assignments, and tasks

ActorSet is a sealed eligibility algebra:

• anyone/no-one
• concrete actor
• initiator
• actor stored in a field
• role, group, grant, qualification
• all/any/none composition
• locked subtree

Assignment selectors are concrete user, group, role, and typed derived field. AssignmentSpec combines selectors with pool or direct claim mode.

TaskTemplate configures identity/language, task kind, completion action ref, default assignment, completion strategy, expiry, escalations, separation-of-duties rules, expiry template, and metadata.

Completion strategies are single claim, parallel all, and quorum.

11. Rules and subscriptions

Rule is the only predicate vocabulary. Author it on Action.rules, Entity.rules, Relationship.rules, Module.rules, or Blueprint.rules. Bootstrap lifts shared rules onto mutating actions without rewriting Rule.phase.

• beforeCommit — must hold before the write commits (row predicates become CHECK constraints when they are single-facet field-local)
• afterCommit — evaluated after the candidate write set is materialized
• availability — whether the action may be offered

Subscription names a published source entity/facet/projection, the local delivery trigger, and an optional condition ref.

12. Entity UI

EntityUI configures:

• icon
• route/menu/search/dashboard visibility
• read/write/execute access
• category and route prefix
• one list configuration
• typed list columns, filters, ordering, and query limits
• detail views, editors, and relationship views
• read-only posture
• priority
• extra detail-tab extension refs
• action placements

ListUI is the collection configuration. Its ordered layouts are the complete set offered to the user, and the first layout is the default:

const ListUI(
  layouts: [
    TableUI(
      columns: [
        TableColumnUI(field: AreaFields.code, required: true),
        TableColumnUI(field: AreaFields.name),
        TableColumnUI(
          field: AreaFields.status,
          appearance: UIColumnAppearance.status,
        ),
      ],
    ),
    GridUI(
      content: CardContentUI(
        titleField: AreaFields.name,
        subtitleField: AreaFields.code,
        statusField: AreaFields.status,
      ),
    ),
    TimelineUI(
      startField: AreaFields.createdAt,
      item: CardContentUI(titleField: AreaFields.name),
    ),
  ],
)

The built-in typed layout vocabulary is TableUI, GridUI, KanbanUI, CalendarUI, TreeUI, and TimelineUI. CustomUI is the symbolic renderer escape hatch. Each layout owns its projection, initial filter, initial ordering, and layout-specific composition. ListUI.auto() explicitly delegates a conservative table-and-card derivation to assembly. An omitted list uses that auto posture because it is the EntityUI default.

FormUI is the complete form configuration. FormUI.derived() orders input-capable fields from facet and field metadata. FormUI.sections(...) contains ordered FormSectionUI children; each section selects facets and/or typed field refs and declares its column count. EditorUI.form configures a single form editor, while each EditorPartUI.form configures one tab or step in a multipart editor.

UIVisibility configures surfaces, menu group/order, and search terms.

UIAccessRule configures permission, policy, role, and user-group refs plus fallback (hide, disable, redact, placeholder, readOnly).

Action placements are extensible refs. Built-ins cover collection toolbar/menu, selection toolbar/menu, record header/action bar/menu, command palette, and tab toolbar/menu. Each action entry configures presentation, overflow, order, title, and tooltip.

13. App Blueprint

The entity Blueprint declares the domain. BlueprintApp declares one application experience over that domain.

It configures:

• app identity, version, and description
• included application modules and features
• workspace regions and navigation
• shell
• routes
• effective entity UI plans
• inboxes and dashboards
• search and settings
• realtime and offline
• localization and profile
• integrations and demos

An optional AppPortfolio advertises independently deployed applications. It does not merge them into one monolith.

Routes and navigation

Routes can be entity list/detail, editor, dashboard, inbox, settings, search, report, or custom. Configure name, path, title, entity, access refs, and custom handler ref.

Navigation configures groups, items, shortcuts, route refs, entity types, and access refs.

Collections

EffectiveEntityUI configures entity, title/description, read-only posture, route prefix, list, details, editors, relationships, effective action catalog/placements, analytics, dashboards, and search.

ListUI configures an ordered set of named layouts:

• TableUI: title, projection, typed columns, default FieldPredicate, and typed FieldOrder list;
• GridUI: title, projection, card content slots, minimum item width, maximum columns, default predicate, and typed order;
• the first declared layout is the default and the declared layouts are the complete set available to saved views.

Grid items are card-shaped, but cards is not a second layout kind. The canonical collection vocabulary is table or grid; richer modes remain separate typed layouts when declared.

Details

DetailUI configures identity/title, kind, facet refs, projection ref, and custom widget ref. Kinds are summary, details, analytics, history, audit, evidence, relationships, execution, and custom.

Editors and forms

EditorUI configures:

• form/tabs/wizard/designer/custom composition
• adaptive/dock/dialog/page presentation
• create/update operations
• facet and typed field selection
• derived or explicit form structure
• multi-part editor parts
• action refs
• custom widget ref

FormUI.derived() groups input-capable fields by FieldUI.formSection, then facet. FormUI.sections(...) supplies explicit sections with typed fields, facet selection, one-to-four columns, and optional automatic placement of new fields.

Input capability always comes from FieldUI.input; a form cannot make a runtime-managed field editable.

Editor parts may be form, relationship, designer, preview, audit, or custom, with their own fields, form, actions, requiredness, and widget extension.

Other application UI

The App grammar also configures:

• inbox item kinds and sources
• dashboard metric/chart/table/timeline/map/graph/custom widgets
• global/entity/faceted/full-text/vector search
• settings and policy packs
• command palette
• realtime streams/subscriptions
• offline read/draft/queued-action strategy and conflict ref
• locale catalogs
• profile tenant/site/role/delegation controls
• reports, blocks, outputs, and exporters
• help fragments and keyboard shortcut
• simulation actor/scope switching and protocol transcript
• integrations/endpoints/webhooks
• demo seed/scenario packs

Global search and command palette

Every effective entity also receives a standard reference projection for top-line identity resolution. It contains id plus the available code, human-name (name, display_name, title, label, username, or email), and description fields. Reference links and pickers use this projection when they need one known entity, so resolving a label never loads the full detail projection. Reference queries are cached by entity type and identifier, concurrent identical reads are deduplicated, and successful mutations invalidate the changed entity plus relationships derived from the Blueprint graph.

SearchUI declares one independently queryable search source. It selects collections by entity type and uses the standard global_search projection by default. The server derives that projection for every effective entity from:

• identity fields, including id;
• the first available human identity fields such as code, name, title, label, display_name, username, or email;
• every additional readable field whose query metadata marks it searchable.

The projection is executed against persisted data. The client never fabricates display rows. If a result is an association record whose own fields do not contain a human label, the client follows its declared belongsTo relationships and resolves target labels through their global_search projections. The raw identifier remains only a last-resort fallback.

CommandPaletteUI.searchRefs references these SearchUI declarations. Each referenced search is registered as a separate provider, so its tab can populate as soon as its own request completes. A slow or failed provider does not delay or erase results already returned by another provider.

Shell

AppShell configures:

• actor, tenant, site, and custom scope selectors
• deployment labels and window-title identity
• menu bar and user menu
• theme modes and text-scale steps
• contextual status bar
• notifications and activity stream
• inspector
• policy, access, evidence, audit, and execution routes
• offline queue/conflict routes
• saved views and reports
• help and simulation

Status indicators configure kind, placement, priority, route/entity/menu context, literal/selection/navigation/recent-action/deployment/extension source, hide-when-empty, and metadata.

14. Extension grammar

Platform defaults are sealed so validators and runtimes can be exhaustive. Imperative or client-specific behavior crosses a named extension seam.

BlueprintExtensionRef declares:

• side: server or client
• kind: action handler, rule evaluator, policy resolver, effect handler, route, widget, detail tab, empty state, dashboard widget, report block, form, or custom
• package/feature ownership and metadata

Other named extension seams include evaluator refs, field transform refs, custom field editors, relationship pickers/renderers, route handlers, widgets, forms, report blocks, data sources, integration endpoints, and conflict policies.

The declaration remains serializable and inspectable; the runtime registry supplies the implementation.

15. Where strings are legitimate

Boundary	Why it is a string
name, title, description, i18n key	Declared identity or language.
SQL expressions, predicates, functions, tables, generated columns	Explicit physical database boundary.
route paths and URLs	Router/deployment boundary.
projection sourcePath/statePath and JSON path	Lowered artifact/wire boundary.
registry/extension refs	Implementation is intentionally outside the declaration graph.
external ids and configuration row ids	Runtime data, not a declaration object.
event, policy, source-document, retention, vocabulary refs	Cross-module/configuration catalog boundary.
serialized request/response field names	Protocol wire representation produced from typed declarations.

If a string is being used only because the author already knows a local field's name, it is not legitimate—use the field object.

16. Validation and lowering

BlueprintValidator checks the declaration before generation or serving. It validates module/export gates, descriptor assembly, enum identity, lifecycle determinism, relationship storage, unique keys, effects and payload mapping, typed field references, related-field chains, identifiers, measured fields, task templates, rules, and UI declarations.

The lowering sequence is:

declarations
  -> validate
  -> bootstrap descriptors
  -> effective entity graph
  -> dependency plan
  -> schema / RLS / outbox / seed artifacts
  -> protocol runtime
  -> app surface assembly
  -> CDX query and control adapters

The Blueprint is the only semantic source. SQL names and protocol JSON are outputs, not alternate authoring languages.

17. Minimal complete example

enum AreaStatus { draft, active, retired }

abstract final class AreaFields {
  static const tenantId = TenantIdField();
  static const code = CodeField();
  static const name = NameField();
  static const status = StatusField(
    'status',
    AreaStatus.values,
    dbEnumName: 'area_status',
    defaultValue: 'draft',
  );
}

const area = Entity(
  name: 'area',
  title: 'Area',
  pluralTitle: 'Areas',
  tableName: 'areas',
  schema: 'ops',
  tenantField: AreaFields.tenantId,
  versioning: const EntityVersioning.revisions(),
  uniqueKeys: [
    [AreaFields.tenantId, AreaFields.code],
  ],
  facets: [
    IdentityFacet(
      fields: [
        AreaFields.tenantId,
        AreaFields.code,
        AreaFields.name,
        AreaFields.status,
      ],
      actions: [
        Action(
          name: 'create',
          title: 'Create Area',
          scope: ActionScope.collection,
          payload: [AreaFields.code, AreaFields.name],
        ),
        Action(
          name: 'activate',
          title: 'Activate',
          rules: [
            Rule(
              id: 'area.activate.from_draft',
              kind: RuleKind.lifecycle,
              condition: FieldEqualsCondition(
                field: AreaFields.status,
                value: 'draft',
              ),
            ),
          ],
          audit: AuditEnvelope(requireReasonCode: true),
          emits: [
            ActionEvent(
              name: 'area.activated',
              kind: ActionEventKind.stateChanged,
            ),
          ],
        ),
      ],
    ),
  ],
  db: EntityDb(
    expectedRows: DbRowScale.medium,
    readPattern: DbReadPattern.runtimeList,
    queryPatterns: [QueryPattern.filter, QueryPattern.search],
  ),
  ui: EntityUI(
    list: ListUI(
      layouts: [
        TableUI(
          columns: [
            TableColumnUI(field: AreaFields.code, required: true),
            TableColumnUI(field: AreaFields.name),
            TableColumnUI(
              field: AreaFields.status,
              appearance: UIColumnAppearance.status,
            ),
          ],
          defaultOrderBy: [FieldOrder(AreaFields.name)],
        ),
        GridUI(
          content: CardContentUI(
            titleField: AreaFields.name,
            subtitleField: AreaFields.code,
            statusField: AreaFields.status,
          ),
        ),
      ],
    ),
  ),
  seed: EntitySeed(targetRows: 100),
);

That declaration is enough for the generic layers to derive validation, dependency ordering, storage, immutable history, query metadata, CRUD action contracts, editors, tables/grids, filters, and runtime execution surfaces.