deployment-scoped artifacts and reporting epic

.workhorse/specs/platform/artifacts.md

@@ -0,0 +1,88 @@
+---
+id: ART
+---
+
+# Version artifacts
+
+An artifact is a file published for a version: an installer, a package, a set of migrations, a manifest.
+Canopy holds what each one is and whom it is for, and a server or the infrastructure acting on a version's behalf learns from Canopy which files a version has and fetches each from where it rests.
+An artifact may be for one group alone, and Canopy offers it only to a caller whose group it is.
+
+## What an artifact belongs to
+
+An artifact belongs to one exact version, or to a range of versions given as a semver pattern, and never to both.
+A range artifact covers every version its pattern matches, so a file that does not change between releases is published once instead of per release.
+
+An artifact carries a type and a platform, which together say what it is and what it is for.
+A version's artifacts are the exact-version ones plus every range artifact whose pattern matches it.
+
+An artifact may belong to a group, and one that does is for that group alone.
+An artifact belonging to no group is for every group.
+A group scope exists because some artifacts are derived from a group's own data and are wrong for anyone else.
+
+## Where an artifact rests
+
+An artifact belonging to no group rests at a location Canopy records and does not hold, which whoever is offered the artifact reads for itself.
+
+A group-scoped artifact is carried to Canopy by the registration that publishes it, and Canopy holds it.
+A publisher sends the bytes on the connection it registers over and is issued no credential to any store, so being authorised to register for a group is the whole of what publishing into it takes.
+Canopy holds such an artifact in storage of its own, apart from any group's backup repo, so an artifact carries the retention, access, and cost basis of an artifact rather than those a backup repo is kept under (see [BAK](../public-server/backup.md)).
+Where Canopy puts them is its own, and no caller addresses them there.
+Canopy holds an artifact's bytes for as long as that artifact is registered, and keeps none of what it has stopped serving.
+A registration or a deregistration that fails once the bytes have moved can leave bytes no artifact reaches, and Canopy drops those as well rather than letting them accumulate.
+It does not expire bytes by age: an artifact's bytes are kept as long as it is registered however long that is, so age alone never says an artifact is finished with.
+
+Canopy serves the bytes only to a caller the artifact is offered to.
+The boundary is therefore enforced on the read rather than resting on a location being hard to guess.
+An artifact whose bytes Canopy cannot produce is answered as one that does not exist, identically to an artifact the caller is not offered, so what Canopy has failed to keep is not discoverable through the read.
+
+An artifact Canopy holds and an artifact Canopy records a location for are one thing to whoever is offered it.
+It is offered one artifact per type and platform, and where the bytes rest is not part of what it is offered.
+
+## What a version offers
+
+A read names a version range, and an exact version is a valid one.
+An exact version is answered for itself; a range is answered for the latest published version it covers that no known issue covers.
+
+Canopy offers a caller one artifact per type and platform, chosen from the artifacts that caller may see: those belonging to no group, and those scoped to the caller's group where that group is known.
+Where several match, the most specific is offered.
+An artifact scoped to the caller's group is more specific than one belonging to no group.
+Among artifacts of the same scope, an exact-version artifact is more specific than any range artifact, and between two ranges the narrower is more specific.
+A group-scoped artifact and an unscoped one of the same type and platform are therefore both recorded, each group is offered the one for it, and no caller is offered both.
+A pattern Canopy cannot parse matches nothing rather than everything, so a malformed range withholds a file instead of offering it to the whole fleet.
+
+The full set, including the artifacts specificity passed over, is available to operators.
+What resolution hides is a fact about how a version was published and an operator has to be able to see it.
+
+## Who is offered a group-scoped artifact
+
+A caller whose credential is bound to a server has that server's group, where the server has one.
+It never names a group and is answered for its own alone, so a server cannot ask what another group is offered.
+A caller carrying no group of its own names the group it asks about and is answered for a group it is authorised for: an operator for any group, and a component that produces or applies a group's artifacts for that group, as defined with those artifacts.
+A read carrying no identity, or naming no group, is answered with the unscoped artifacts alone, so giving an artifact a group narrows who is offered it rather than widening what an open path serves.
+A group-scoped artifact's existence is disclosed only to a caller it is offered to: a caller that names or guesses one it is not offered is answered as though it did not exist, so which groups hold one is not enumerable through the artifact surface.
+Canopy passes a group-scoped artifact's bytes only to a caller it is offered to.
+
+## Registration
+
+Registering an unscoped artifact and registering a group's are separate: they name different things, carry different bodies, and are authorised differently, so each is its own path rather than one path that changes shape on a parameter.
+An unscoped registration names the version or range, the type and the platform, and carries the artifact's location.
+A group-scoped one names the group as well, carries the artifact's bytes, and names an exact version Canopy already holds rather than drafting one.
+The group is named on the registration rather than inferred from the caller.
+
+A releaser device registers unscoped artifacts, and carries no authorisation for any group.
+An operator registers either.
+A component that produces a group-scoped artifact registers it for that group under an authorisation defined with that artifact, and is authorised for no other.
+A registration naming a group the caller is not authorised for is refused, which is the only gate publishing into a group has to pass.
+A registration replaces whatever is already registered for the same version or range, type, platform, and group, so a rebuilt artifact is published exactly as a first one is and a caller is never offered two of a kind.
+
+Canopy records which device registered an artifact and, where the registration names one, the run that produced it, so an artifact that arrived by automation is distinguishable from one entered by hand and traceable to what made it.
+
+## Digests
+
+An artifact carries a digest where whoever registers it records one, and an artifact Canopy holds carries one always.
+A digest is expressed in Subresource Integrity format, using SHA-256.
+A registration naming anything else is refused.
+Canopy verifies the bytes it holds against their digest as they arrive and refuses the registration on a mismatch, so a corrupted upload is refused while whoever sent it is still there to send it again.
+It verifies them again as it serves them and refuses them on a mismatch, so an artifact corrupted after it was taken in fails the read rather than reaching a server as the artifact it is not.
+An unscoped artifact is read from its location by the caller rather than by Canopy, so its digest is what that caller checks what it fetched against, and an artifact registered without one is fetched unchecked.

.workhorse/specs/public-server/reporting-schemas.md

@@ -0,0 +1,87 @@
+---
+id: RPT
+---
+
+# Reporting schemas
+
+A reporting schema is the set of database views a Tamanu application's reports read from.
+It is built for one Tamanu version against a database of one group, since its views follow from the group's configuration as well as from the version's schema, and every Tamanu application in that group applies the same one.
+Canopy holds zero or one reporting schema per pair of group and Tamanu version, has one built for every pair it knows of, and offers it to the Tamanu applications of that group.
+
+## Why it exists
+
+Part of a reporting schema follows from the Tamanu version's database schema and is the same for every group on that version.
+The rest follows from the group's own configuration, which only a database carrying that configuration can supply.
+A schema for a pair is therefore built from a database of that group at that version, and ahead of an upgrade no such database exists, since the group's applications run the version they are leaving.
+Canopy restores a group's backups into replicas and migrates them to a version (see [RST](restore-replicas.md)), so it is where such a database is produced, and it knows the version each group runs and the one it is moving to (see [APP](../servers/application-types.md), [UPG](../private-server/upgrade-plans.md)), so it is where the pairs are known.
+
+## Actors
+
+A **schema builder** produces a reporting schema from a database Canopy has restored and migrated for it, and publishes the result.
+It is a restore consumer (see [RST](restore-replicas.md)): a build operates on a replica, so the builder is dispatched, credentialled, and reports over the replica pathways and authorisations, and it advertises an intent carrying `reporting-schema`.
+How the builder produces a schema is the builder's own.
+
+An **operator** declares which groups have a builder, marks the declaration that publishes a group's schema, reads which schema each application runs, and asks for the builds the derivation does not produce.
+
+The **device of a machine a Tamanu application runs on** fetches the schema Canopy offers that application and applies it (see [DID](machine-identity.md)).
+
+Canopy owns which pairs exist, the replica a build is given, the artifact that results, and offering it to the group's applications.
+
+## Pairs
+
+A reporting schema is unique per pair of group and Tamanu version, and Canopy holds zero or one per pair.
+The pairs are, for each group covered by an enabled declaration marked as publishing its schema, each version a Tamanu application of the group reports running and the version its open plan moves it to (see [UPG](../private-server/upgrade-plans.md)).
+That declaration is what covers a group: it names the group, is enabled or disabled, carries the operator's mark, and is audited (see [RST](restore-replicas.md)).
+Only a published version is in a pair, since a version's migrations reach a builder as its published artifacts (see [ART](../platform/artifacts.md)) and an unpublished one has none.
+
+A pair with no schema is built, and a pair with one is settled.
+A settled pair is built again when the version's own artifacts change, since a schema built from a superseded release of the version is not the schema that version describes, and when an operator asks for it.
+An operator asking for a pair's build is how a schema is refreshed after the group's configuration changes.
+A rebuilt pair's schema replaces the one it held.
+A failed build settles the pair as well, since a build against a fixed version and configuration fails the same way every time, and the pair is built again on the same two events.
+
+## The build contract
+
+Canopy dispatches a build to the builder as a restore replica, through the worklist every replica is dispatched through (see [RST](restore-replicas.md)).
+The entry names the group and the Tamanu version the schema is for, and a machine of the group running a central Tamanu application, whose snapshot the replica is restored from, since the configuration a schema follows from is held centrally.
+It carries what any replica's entry carries: the snapshot to restore, the repo coordinates, and the intent's parameter values.
+The replica is migrated to the named version before the build reads it, and is not de-identified, since masking alters the configuration a schema follows from.
+
+The builder obtains read credentials for the restore per run as any consumer does, and no storage credential of any kind for what it publishes (see [RST](restore-replicas.md)).
+
+In the run it reports, the builder registers the **reporting schema** as an artifact of the exact version being built for, scoped to the group, of type `reporting-schema` on platform `any`, carrying a digest and the bytes themselves, which Canopy holds and serves (see [ART](../platform/artifacts.md)).
+The schema is the only type it may register: what is published for a group is offered to every machine in it and fetched, so the authorisation stays defined with the artifact it was written for.
+The builder is authorised to register artifacts for a group whose enabled declaration an operator has marked as publishing its reporting schema, and for no other, and is the one device other than a releaser that registers artifacts (see [ART](../platform/artifacts.md)).
+The mark is the operator's alone, and is the whole of the authorisation: a consumer registers the set of semantics it advertises itself, so they shape what Canopy dispatches to it and grant it nothing, and what is published for a group is offered to every machine in it and applied.
+Only a group-wide, non-redacting declaration of an intent carrying `reporting-schema` can carry the mark, which is the same declaration a build is dispatched for, so Canopy asks for no build it would refuse the result of.
+
+A schema is published for the exact version and never for a range, since it follows from the migrations that version applies, and one built against a patch is not the schema another patch of the same minor describes.
+
+## What a build reports
+
+A build reports as its replica's restore report (see [RST](restore-replicas.md)), which names the group, the machine, the snapshot restored, and when it was observed.
+Beyond those it carries:
+
+- the **version** it was built for;
+- the **outcome**, built or failed, and on failure a description of what went wrong;
+- a reference to each **artifact** the build registered, of which the schema is one.
+
+The restore's health and the build's outcome stay separate signals from the one report, as a migration test's do: a healthy replica whose build failed reports a healthy restore and a failed build.
+Reports are retained indefinitely as an audit trail.
+
+## The offering contract
+
+Canopy offers a Tamanu application's device the schema for the pair of its group and the version that application reports running, resolved as any group-scoped artifact is (see [ART](../platform/artifacts.md)).
+The device's credential resolves to the machine it is enrolled as and so to that machine's group, so it is offered its own group's schema and can fetch no other's.
+A facility application is offered the same schema as the central applications of its group, since a schema follows the group and the version rather than the application it was built from.
+
+The device compares what its application runs with what it is offered, applies the offered schema where they differ, and reports the result as a check on that application through the status contract (see [STA](statuses.md)), which is graded, presented, and alerted as any source's check is (see [CHK](../monitoring/checks.md)).
+
+## Alerting
+
+A failed build raises a reporting-schema check on the group's central Tamanu application, carrying the failure description (see [CHK](../monitoring/checks.md)).
+The check is a warning rather than a failure, and does not escalate: the application is up and its reports return rows, and a schema that cannot be built for the version its group is moving to is for whoever maintains the reports rather than whoever is on call.
+A replica that failed to restore or come up is the restore's own health rather than a build failure, and is dispatched again as any unhealthy restore is.
+The check recovers when the pair is built, and nothing else clears it: an operator asking for the build puts the pair back on the worklist, and the warning stands until a build lands, since asking changes nothing about whether the group's applications can be offered a schema.
+
+Pairs are presented per group, showing which have a schema, which are being built, and which failed, so whether a group's applications can be offered the schema for the version they run or are moving to is answered in one place.