Core concepts

Business program#

The business/ folder is the contract source of truth. The compiler imports every supported source module in canonical order and accepts exactly one default-exported fs.business() result. The conventional starter is business/business.ts, but discovery is filename-agnostic.

Declarations return immutable branded refs. Plans grant route, group, and frontend-integration refs rather than joining unrelated strings.

Deterministic build#

farthershore build executes the program twice and rejects differing output. Do not make contract declarations depend on time, randomness, network calls, filesystem state, or environment variables. The resulting Manifest IR is the wire contract; Core never executes arbitrary builder code.

Accepted contract and apply#

A local build proves that the program compiles. A pushed commit still has to pass repository validation and apply checks. The accepted contract is the last successful applied result, not whatever happens to be in an unverified branch.

Use the Apply Timeline to correlate commits, semantic diffs, phases, and failures:

farthershore apply-timeline list <business>
farthershore business contract <business>

Customer boundary#

Every subscriber is an organization, including a solo customer. Plans, subscriptions, billing, and business-level limits attach to that organization. A verified member principal identifies a person inside it; a verified service principal identifies an organization-owned machine credential.

The platform enforces plan access at the edge. Your backend uses the verified principal for row-level ownership and collaboration rules.

Entitlements, economics, and bounds#

A plan combines three independent decisions:

• route and integration grants decide access;
• flat and metered prices decide economics;
• meter and resource limits decide bounds.

A granted route may be free. A priced meter may have no hard cap. A hard cap may be unpriced. Read Entitlements vs economics.

Environments and release#

Preview environments let a branch apply without changing production. Concrete backend origins, runtime variables, and hosted frontend releases are scoped to an environment. The business program names logical contract objects; the platform binds their environment-specific operational values.

Publishing creates immutable business and plan release state. Existing subscriber cohorts are evaluated against the new candidate independently; use farthershore commercial-release diff <from-release.json> <to-release.json> before activation.

Repository vs CLI#

When a write is represented in business/, edit and push the program. When it has no code representation, use the CLI. farthershore operations list is the authoritative classifier for the current installed version.