5.5.1 Introduction

farm is the system responsible for the farm data, from the moment it leaves the farm to the facts other systems read: the sources, feeds and devices data comes from, the raw files and parse jobs, the farm sync clients with their runs, and the canonical data itself (animals, observations, events and periods), its reconciliation into facts, the write number that is the one clock of the data, erasure requests and submissions to official bodies, and, since D2, what each Organization has purchased and how much it uses, which every product reads from here. Bringing data in and keeping it were two systems, ingestion and farm, until D1 of the open decisions merged them on 2026-10-30; entitlements followed with D2 the same day. It belongs to the Farm Data domain of the platform. Every interface it offers follows Choosing an Interface.

Proposal for review

The contracts of this system are a proposal, not confirmed design: endpoints, events and calls were written from the refined requirements, the data model and the flows, and wait for review. What needs a decision is collected in Open Decisions.

5.5.1.1 Host Names¶

Environment	Host
Prod	`farm.moonitoring.com`
Stage	`stage-farm.moonitoring.com`, behind IAP

The names follow the host name rule; on a developer's computer each service answers on a local port (Running Locally). Each domain below is a path on these hosts, followed by its version: https://farm.moonitoring.com/<domain>/v1.

5.5.1.2 Domains¶

Each domain of farm is one API, with its own contract and its own version.

5.5.2.1 Sources

Where farm data comes from: the origins that produce values and the channels that deliver them (global catalogs maintained by staff, plus an Organization's own), each farm's feeds with their coverage, and the devices installed at the farm. /sources/v1
5.5.2.2 Files

Raw files as received, what was skipped when parsing them and the parse jobs that processed them. /files/v1
5.5.2.3 Sync

The farm sync client and its runs. /sync/v1
5.5.2.4 Animals

The animal registry: animals with their identifiers, breed and profile evidence, groups and memberships, ownership and transfers, and the catalogs of species and breeds. /animals/v1
5.5.2.5 Observations

Measured and computed values about animals, groups and farm products, with the catalogs that give them meaning (types, methods, contexts, body sites), the sessions and samples that group them, the selections among proved duplicates and the derivations of computed values. /observations/v1
5.5.2.6 Events

What happened to an animal or a group, as each feed reported it (calvings, services, treatments, exits and the other canonical events), the periods derived from the resolved facts (lactations, dry periods, pregnancies, withdrawals), the catalogs of period and death kinds and each farm's configuration. /events/v1
5.5.2.7 Reconciliation

One fact per real event, built from the evidence of every feed by versioned rules: resolved events and the evidence behind them, animal links, data issues that tell the farm what to fix at the source, and the rule sets and source reliability rankings. /reconciliation/v1
5.5.2.8 Versioning

The one clock of the farm data: write commits and their numbers, the watermark below which the data never changes again, and erasure requests. /versioning/v1
5.5.2.9 Submissions

Submissions to official bodies, such as milk recording: the farm asks for a submission over a period in a format, reviews the generated file, sends it and records the recipient's answer. /submissions/v1
5.5.2.10 Entitlements

What each Organization has (an entitlement to a feature, a model or a plan, with its limits) and how much of a metered feature it used. /entitlements/v1

5.5.1.3 How It Is Used¶

Farm sync client¶

A technician issues an enrolment code in the Organization Dashboard.
The client redeems the code with a locally generated key and becomes a service account of the farm's Organization, then signs in through Access.
On each synchronization, the client opens one run per source feed, announces the file hashes it holds, uploads only new files through signed URLs, commits the run, and reports failures and digests.
Farm parses the received files into canonical revisions under one write number, preserving the source lineage.

Organization Dashboard¶

The Dashboard reads animals, observations, resolved facts, periods, and data issues for Organizations the user may act in.
Farm authorizes records against their time and the user's ownership episode, then returns the requested revision or as_of_seq view.
The Dashboard reads the watermark to know which write number is stable.

Vendor and model integrations¶

Vendor pullers enter the same raw-file and commit path as a sync client.
Farm asks ai-model-platform for predictions and stores the results as computed records; batch scorings arrive through gRPC.
Data entered in the app is stored as a raw file of the app feed and parsed like every other source, so it retains the same lineage.

Data scientists¶

ai-model-platform requests a dataset export from Farm at a selected write number.
Farm creates the export files without exposing its database.
The model workflow uses those files to build reproducible datasets and runs.

Submissions¶

Farm builds milk-recording or registry submissions from resolved facts.
The submission is sent to the official recipient and its response is recorded for the Organization.

Entitlements¶

Staff grant entitlements in the Console.
Farm publishes entitlement changes and serves synchronous entitlement and usage checks to product systems.
AI Gateway reserves and settles usage with Farm for each model call.

flowchart LR sync{{Farm sync client}} -->|REST sync runs| farm[Farm API] dashboard{{Organization Dashboard}} -->|REST reads| farm farm -->|gRPC predictions and exports| training[AI Model Platform] farm -->|gRPC usage and entitlements| products[Product systems] products -->|events| farm

Called by: Console (REST); Farm sync client and installed clients (REST); Organization Dashboard (REST); access (gRPC CatalogService); ai-gateway (gRPC EntitlementsService, gRPC UsageService); ai-model-platform (gRPC ComputedRecordsService, gRPC EntitlementsService, gRPC ExportsService, gRPC WatermarkService); grant (gRPC EntitlementsService); moochat (gRPC CatalogService, gRPC EntitlementsService); news (gRPC EntitlementsService); releases (gRPC EntitlementsService).
Calls: access (gRPC OrganizationsService); ai-model-platform (gRPC ModelsService); every system (gRPC CatalogService); releases (gRPC InstallationsService).
Publishes events consumed by: access (1 event type), ai-model-platform (10 event types), grant (6 event types), moochat (13 event types), releases (7 event types).
Consumes events of: access (4 entries), ai-model-platform (1 entry), every system (1 entry), grant (1 entry), releases (1 entry).
Reads no other system's database: everything above goes through a contract on this page or an event.

5.5.1.4 Synchronous Calls Between Systems¶

WatermarkService and ExportsService in Versioning; ComputedRecordsService in Observations; EntitlementsService and UsageService in Entitlements. It calls ModelsService of ai-model-platform, OrganizationsService.RegisterServiceAccount of access when a sync client enrols, OrganizationsService.DisableServiceAccount when a client is retired or reinstalled (its sweeper retries the disables the backend could not finish) and InstallationsService.VerifyInstallation of releases when a client reports its installation.

5.5.1.5 Events¶

Events are facts in the past tense, published through the outbox and delivered at least once on the topic farm.events.v1; the envelope and the guarantees are in common/v1/events.yaml. Events marked outside reach the Pub/Sub subscriptions an Organization registers in Webhooks, pushed to its HTTPS endpoint or pulled by its own service account.

Publishes (contract: events/v1/asyncapi.yaml):

Event	Published when	Consumers	Outside
`source_feed.connected.v1`	A feed was connected to a farm.	none yet	yes
`source_feed.disconnected.v1`	A feed's validity was closed.	none yet	yes
`sync_client.enrolled.v1`	A sync client redeemed an enrolment code: first setup or a reinstallation.	`releases`	yes
`sync_client.retired.v1`	A farm stopped using a sync client.	`releases`	yes
`sync_run.committed.v1`	A run delivered its files: the SyncRun, its RawMetadata and ParseJobs were recorded in one transaction.	none yet	yes
`sync_run.failed.v1`	A run failed on the client's side, reported at once or deferred to the next contact.	none yet	yes
`raw_file.committed.v1`	A new raw file is in the bucket and recorded.	none yet	no
`raw_file.removed.v1`	An uploaded file was removed by its Organization; every record parsed from it was cancelled.	none yet	yes
`parse_job.requested.v1`	A parse job is queued. The work queue of the parser workers: one message per job, ordered by feed so the files of one feed are parsed in order and all feeds in parallel. Delivered at least once; the job id and lease make a second delivery harmless.	`farm`	no
`parse_job.finished.v1`	A parse job ended: done, or failed with its class. A failed job never changes its run's delivery status.	none yet	no
`parse_job.dead.v1`	A job exhausted its attempts and waits for a person; the other feeds keep flowing.	none yet	no
`entitlement.granted.v1`	An Organization received a feature.	`moochat`, `grant`, `releases`, `ai-model-platform`	yes
`entitlement.changed.v1`	An entitlement's validity or limits changed.	`moochat`, `grant`, `releases`, `ai-model-platform`	yes
`entitlement.revoked.v1`	An entitlement ended.	`moochat`, `grant`, `releases`, `ai-model-platform`	yes
`feature_usage.limit_reached.v1`	A metered feature reached a limit of its period for an Organization.	`moochat`, `grant`	yes
`write_commit.committed.v1`	A write was committed; the watermark may have advanced. Carries the kind of write and what it came from, so a consumer knows which farm's data changed.	`ai-model-platform`, `moochat`	no
`animal.registered.v1`	A new animal record exists, from a feed or the app.	`moochat`	yes
`animal.merged.v1`	Two animal records were found to be the same animal; readers follow the survivor. Also published when a link is reverted.	`moochat`, `ai-model-platform`	yes
`ownership.transferred.v1`	An animal or group changed legal owner or manager farm; who can see it changed.	`moochat`	yes
`resolved_event.published.v1`	A resolved fact was created, revised, cancelled or retired: the calving, service, exit or other event consumers react to. `event_type` says which; `calving.registered` of the interface guidelines is this event with event_type ParturitionEvent.	`moochat`, `ai-model-platform`	yes
`data_issue.opened.v1`	The system found a doubt, a conflict or a blocked publication and tells the farm what to fix at the source.	`moochat`	yes
`data_issue.closed.v1`	A data issue was resolved at the source or became obsolete.	`moochat`	yes
`feed_coverage.updated.v1`	After a sync, how far a feed's data is present, complete and settled, per kind of data.	`ai-model-platform`	yes
`official_submission.sent.v1`	A submission left for an official body.	none yet	yes
`official_submission.outdated.v1`	Something a sent submission included changed or was cancelled at the source.	none yet	yes
`erasure_request.created.v1`	A farm asked for its data to be removed.	`moochat`, `ai-model-platform`, `grant`, `releases`	no
`erasure_request.executed.v1`	A farm's data was anonymized; every system that holds something that leads back to it does the same.	`moochat`, `ai-model-platform`, `grant`, `releases`, `access`	no
`dataset_export.completed.v1`	A dataset export finished: the files and manifest are in the datasets bucket.	`ai-model-platform`	no

Consumes:

Event	From	Why
`organization..v1, membership..v1, delegation.*.v1`	`access`	Keeps its copy of who may act on a farm's feeds and clients.
`service_account.registered.v1`	`access`	Matches the identity minted at enrolment with the sync client.
`installation.updated.v1`	`releases`	Shows the version each sync client runs.
`organization.created.v1`	`access`	Knows the Organizations entitlements can be granted to.
`capability catalogs`	`every system`	Validates the feature of an entitlement, through the Catalog gRPC service.
`organization..v1, membership..v1, delegation.*.v1, organization_role.updated.v1`	`access`	Keeps its copy of who may read and write which farm's data.
`model_version.deployed.v1, model_version.retired.v1`	`ai-model-platform`	Refreshes the model catalog it shows to Organizations.
`farmer_document.read.v1`	`grant`	Nothing today; a future link between funding checks and farm data (D21).