Contract, UI, and Surface Reference

This checked-in reference is generated from the current Pharos repository contracts. It describes the app-owned declaration surfaces that the shared runtime and builder consume: routes, surfaces, UI elements, forms, actions, workflows, integrations, entities, queries, policies, and derived generated surfaces.

The filename remains library-reference.md because the docs app route, navigation, and agent knowledge index already use that stable path. The document title is the accurate name of the content.

Table of Contents

• contract inventory
• terminology
• route
• surface
• ui.element
• form
• action
• workflow
• integration.adapter
• integration.webhook_endpoint
• entity
• query
• policy
• generated_surface
• update contract

Contract Inventory

| Contract area | Source files | Declared records | Runtime use | | --- | ---: | ---: | --- | | routes | 8 | 176 | request path matching and dispatch | | surfaces | 5 | 17 | page, API, form, fragment, and UI library declarations | | UI elements | 3 | 16 types | canonical shared controls and preview fragments | | forms | 1 | 17 | field validation and submitted input contracts | | actions | 6 | 109 | validation, mutation execution, responses, and effects | | workflows | 5 | 13 workflows, 42 transitions | state machines and lifecycle events | | integrations | 3 | 13 adapters | outbound webhooks, notifications, audit, and local file records | | entities | 4 | 58 | storage, generated surface derivation, identity, and scope | | queries | 1 | 20 | relational lookup and projection contracts | | policies | 4 | 50 capabilities | auth gates and capability checks |

Terminology

• contract means an app-owned declaration file under data/contracts/ that the Pharos runtime or builder consumes.
• fixture remains present in some schema names and legacy field names, but the current repository uses these files as executable contract declarations, not throwaway test fixtures.
• surface means a declared user-facing or machine-facing interface such as an HTML page, JSON API, form, fragment, UI library, generated admin page, or generated API.
• generated_surface means a derived framework-owned CRUD surface built from entity, form, query, and route metadata.

route

Routes bind request paths to pages, actions, static artifacts, generated surfaces, or route-level request hooks.

Current route kinds:

• action
• mirror_query_param
• mirror_request_header
• page
• require_header
• require_query_param
• set_header

Common fields: route_id, path, kind, method, page_id, action_id, artifact, policy_id, auth_gate, security, request_hook, and response_hook.

Example:

route_id: dev_docs_library
path: /reference/library-reference.html
kind: page
artifact: reference/library-reference.html

surface

Surfaces declare renderable or callable app interfaces. Source surface files cover explicitly declared pages, APIs, forms, fragments, and UI libraries. Generated admin/API surfaces are derived at build time from entity metadata.

Current surface kinds:

• form
• fragment
• generated_admin
• generated_api
• html_page
• json_api
• status_page
• ui_lib

Observed source fields:

• intro
• surface_id
• surface_kind
• title

Example:

surface_id: dynamic_app_ui_lib
surface_kind: ui_lib
title: Framework-owned UI element library
intro: The native runtime renders these UI examples directly from checked fixture data so app authors can see the current shared surface contract in one place.
sections:
- section_id: inputs_and_widgets
  title: Inputs and widgets
  intro: Use shared framework inputs and long-form widgets when operators need typed entry surfaces without app-specific control markup.
  layout: grid
  examples:
  - id: business_name
    element_type: input
    input_type: text
    title: Text input
    label: Business name
    name: business_name
    placeholder: Lotus Studio
    usage: Use for short single-line text values such as names, slugs, titles, and other operator-entered identifiers that should stay concise.
    tooltip: Framework-owned single-line input for short text fields. Best for values operators can review quickly without opening a longer editor.
  - id: reviewer_email
    element_type: input
    input_type: email
    title: Email input
    label: Reviewer email
    name: reviewer_email
    placeholder: reviewer@llight.io
    usage: Use for operator-entered email addresses that should follow a strongly typed contact shape.
    tooltip: Framework-owned email widget for contact and notification targets. Prefer this over free-form text when the contract expects an address.

ui.element

UI elements are canonical shared controls and preview fragments declared in ui-elements.yml, ui-examples.yml, and UI-library surface sections.

Current UI element types:

• badge_list
• button
• button_row
• card
• card_grid
• checkbox
• checkbox_group
• detail
• input
• list
• radio_group
• select
• split_layout
• stat_group
• table
• textarea

form

Forms define accepted fields and validation rules for submitted input. Generated surfaces and app-authored actions both use these contracts.

Current validation rule kinds:

• after
• match
• range
• required

Example:

form_id: service_form
entity_id: service
fields: form-fields.yml#form.service.service_form.fields
submits_action: create_service
validation_rules:
- rule_id: service_name_required
  kind: required
  field_id: name
- rule_id: service_duration_required
  kind: required
  field_id: duration_minutes
- rule_id: service_cost_required
  kind: required
  field_id: cost
defaults:
  service_type: standard
  location_type: business
  buffer_minutes: 0
  description: ''
  is_active: true
  booking_options: []
  technician_ids: []
relation_inputs:
- field: technician_ids
  related_collection: technicians
  related_scope_field: business_id
  label_field: name
  form_checkbox_prefix: technician_ids__
  invalid_rule_id: service_technician_ids_invalid
  scope_rule_id: service_technician_scope_invalid
  invalid_message: Assigned technicians must be integer ids.
  scope_message: Assigned technicians must belong to the same business.

action

Actions define input contracts, mutation primitives, response contracts, and bounded effects.

Current mutation primitive kinds:

• append_record
• append_records_from_input_list
• append_records_from_related_collection
• approval_transition
• bulk_update
• delete_records_by_scope
• replace_records_from_input_list
• reservation_transition
• scoped_reassignment
• scoped_status_transition
• set_root_fields
• update_record
• upsert_record

Current response kinds:

• json
• redirect

Current effect hook groups:

• audit_records
• file_records
• notifications
• scheduled_jobs
• webhook_dispatch

Example:

action_id: create_task
entity_id: task
policy_gate: public
input_contract:
  fields: entity-fields.yml#entity.task.create_task.fields
mutation_primitives:
- primitive_id: create_task_record
  primitive_kind: append_record
  collection: items
  record_contract:
    id:
      source: next_id
    title:
      source: input
      field: title
    done:
      source: literal
      value: false
    workflow_state:
      source: literal
      value: created
- primitive_id: mark_last_action_create
  primitive_kind: set_root_fields
  fields: entity-fields.yml#entity.task.mark_last_action_create.fields
response_contract:
  response_kind: redirect
  location: /
effect_hooks:
  scheduled_jobs:
  - notify-task-created
  webhook_dispatch: []

workflow

Workflows group states and transitions around action-owned lifecycle changes. Transitions can emit audit events, event names, and scheduled jobs.

Common fields: workflow_id, states, transitions, transition_id, from_state, to_state, action_id, policy_gate, emits_audit_event, emits_event, scheduled_jobs, and presentation.

Example:

workflow_id: task_lifecycle
states:
- none
- created
- done
transitions:
- transition_id: create_task_transition
  from_state: none
  to_state: created
  action_id: create_task
  policy_gate: public
  emits_audit_event: true
  emits_event: task_created
  scheduled_jobs:
  - notify-task-created
  presentation:
    transition_label: Create task
    from_label: New
    to_label: Created
- transition_id: create_task_api_transition
  from_state: none
  to_state: created
  action_id: create_task_api
  policy_gate: public
  emits_audit_event: true
  emits_event: task_created_api
  scheduled_jobs:
  - notify-task-created-api
  presentation:
    transition_label: Create task API
    from_label: New
    to_label: Created

integration.adapter

Integration adapters declare outbound delivery and local side-effect targets used by action effect hooks and delivery workers.

Current adapter kinds:

• append_jsonl_local
• audit_local
• http_form
• http_json
• notification_local
• webhook
• write_json_local

Example:

adapter_id: board-webhook
adapter_kind: webhook
target_url_env: PHAROS_DYNAMIC_APP_BOARD_WEBHOOK_URL
content_type: application/json
timeout_seconds: 5
max_response_bytes: 8192
allow_plaintext_local: true
max_attempts: 2
backoff_seconds: 1

integration.webhook_endpoint

Webhook endpoints declare inbound webhook handling, including endpoint kind and signature verification settings.

Current endpoint kinds:

• json_webhook

entity

Entities declare relational storage, identity fields, tenant or parent scope, soft-delete behavior, uniqueness, generated surface requests, and field metadata.

Current storage kinds:

• relational

Example:

entity_id: service
storage_kind: relational
table: service
identity_field: id
scope_field: business_id
generated_surfaces:
- admin
- form
- api
- manifest
fields: entity-fields.yml#entity.service.fields
soft_delete_field: is_active

query

Queries declare reusable lookups and projections used by generated surfaces, page parameter builders, auth flows, and runtime handlers.

Example:

query_id: services_by_business
entity_id: service
visibility_scope: policy_bound
filter_set:
- business_id
- is_active
sort_set:
- sort_order_asc
- name_asc
pagination_mode: offset
preload_relations:
- business
- technician
backend_requirements:
- sqlite
- postgresql

policy

Policies declare roles, scopes, capabilities, and role-to-capability edges. Routes and generated surface operations use these capabilities for access control.

Current capabilities:

• account_login
• account_logout
• account_password_reset_complete
• account_password_reset_request
• account_register
• account_verify_email
• cancel_appointment
• complete_appointment
• create_appointment
• create_business
• customer
• export_builder_source
• framework_internal
• manage_availability
• manage_builder_settings
• manage_business
• manage_business_memberships
• manage_business_payments
• manage_business_visibility
• manage_google_calendar_connection
• manage_job_queue
• manage_payment_provider_connection
• manage_personal_booking
• manage_profile
• manage_services
• manage_technicians
• owner
• public
• rate_business
• release_builder_app
• request_cancel_appointment
• request_reschedule_appointment
• reschedule_appointment
• review_builder_plan
• run_appointment_maintenance
• scan_business_qr
• submit_builder_task
• subscribe_business
• unsubscribe_business
• view_appointment_detail
• view_appointment_diagnostics
• view_appointments
• view_business_calendar
• view_business_detail
• view_business_landing
• view_explore
• view_job_queue
• view_owned_businesses
• view_personal_booking_detail
• view_personal_bookings

generated_surface

Generated surfaces are derived build artifacts for framework-owned CRUD behavior. They are requested from entity metadata such as generated_surfaces: [admin, api] and assembled from entity, form, query, and route contracts.

Current generated surface kinds:

• generated_admin
• generated_api

Generated admin operations: manage, create, edit, update, delete, and restore when the entity supports soft delete.

Generated API operations: list, schema, create, update, delete, and restore when the entity supports soft delete.

See Generated Surfaces for the focused generated-surface contract.

Update Contract

Run scripts/check.sh docs reference to verify this checked-in Markdown against the current repo contracts. Run tests/check/docs_reference.py --write after changing contract surfaces so this file stays synchronized with the app-owned declarations.