Contracts

Pharos is contract-first. This section covers the checked declarations that drive runtime behavior, generated surfaces, extension points, and shared UI rendering.

Core contract references in this section:

• YAML Authoring
• Action Hooks and Middleware
• Feature Transaction Primitives
• Generated Surfaces
• Declarative CRM
• Payment Provider Management
• Integration Adapters

Application declaration contract

Every app must declare enough checked information for the runtime and packaging layer to load it consistently.

Typical declared families include:

• app identity
• route definitions
• page and layout surfaces
• forms and actions
• policy and workflow fixtures
• generated surface declarations
• integration declarations
• templates, assets, and media locations
• runtime profile and app-local config hooks

Route contract

Every route definition must specify:

• stable route id
• path pattern
• route kind
• bound page, action, or API surface
• auth or policy gates where required

Entity contract

Every entity must specify:

• stable entity id
• fields
• keys or identity
• storage mapping
• query visibility
• generated surface hints

The native Pharos runtime exposes this contract directly through native runtime sources, app manifests, and checked build artifacts.

Action contract

Every action must specify:

• input contract
• validation contract
• policy gate
• mutation scope
• emitted events where applicable
• replay or audit shape where applicable

The native Pharos runtime exposes action execution directly through the native runtime, checked route fixtures, and acceptance validation flows.

Policy contract

Every policy decision must specify:

• subject identity kind
• capability or role path
• guarded surface
• allow or deny result
• explanation inputs

Generated surface contract

Every generated surface must specify:

• surface id
• derivation source declarations
• explicit overrides
• generated kind
• drift detection inputs

Form contract

Every form must specify:

• stable form id
• target entity or action
• field list
• submit action
• validation rules

The native Pharos runtime exposes this contract directly through native route handling, declarative app files, and checked build artifacts.

Contract discipline

The implementation rule is:

• runtime behavior may elaborate a contract
• runtime behavior may not invent hidden contract truth

That means the framework should reject:

• hidden auth requirements
• generated admin behavior without provenance
• runtime-only workflow transitions
• undeclared tenant scope behavior
• undeclared job retry behavior
• benchmark claims without fixed scenario contracts