HTTP API: delivery

Whether each product feature exists, computed and never recorded: on the trunk, deployed, publicly verified, its required tests current, that evidence published and linked from the interface — each a verdict of pass, fail or unknown with the reason and the remediation, and unknown never a pass. A feature short of any of them is not delivered, and its development stage (implemented on a branch, on master, tested, deployed) is a different type from delivery.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

delivery

GET /api/v1/delivery delivery.report

Does each feature exist

Every product feature of the layer against the delivery invariant, ordered by id: the six dimensions with their verdicts, reasons and remediations; the development stage when it is not delivered; the paths it is implemented by and the revisions that last touched them at HEAD and on the trunk; and the publication — the public site's identity, read once, and whether scripts/pages verified it. Reads git and the network; the site address can be replaced with MAJORDOMUS_DELIVERY_SITE_URL.

query
experimental
benchmark waived: external_dependency
cache disabled
MCP tool majordomus_delivery
$ delivery report

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/delivery"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	DeliveryReport	Does each feature exist: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/delivery/feature delivery.feature

Does this feature exist

One product feature against the delivery invariant: every dimension with its verdict, the sentence that decided it and what would change it, whether it exists, and — when it does not — how far development has carried it and which dimensions block it. An id the layer does not declare is not found rather than answered as not delivered.

query
experimental
benchmark waived: external_dependency
cache disabled
MCP tool majordomus_delivery_feature
$ delivery show

Query parameters

name	type	required	description	examples
id	string	yes	The feature's id, as `product.features` gives it.	first-feature: "benchmarks"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/delivery/feature?id=benchmarks"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	FeatureDelivery	Does this feature exist: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

DeliveryReport

object

Every feature of the layer against the delivery invariant.

property	type	required	description
schema	string	yes	`majordomus/delivery/v1`.
trunk	string \| null	no	The trunk ref every `on_master` verdict was measured against, when one was found.
publication	Publication → Publication	yes	What the public site was observed to serve, read once for every feature.
tallies	DeliveryTallies → DeliveryTallies	yes	The counts.
features	array of FeatureDelivery → FeatureDelivery	yes	Every feature, ordered by id.

Used by delivery.report

DeliveryState

one of 2 variants

Delivered, or not — and when not, how far development got and which dimensions stand in the way. Two variants of one type rather than a flag beside a stage: a delivered feature has no stage to report, and a stage can never be read as delivery.

variant Every dimension passes.

state

"delivered"

yes

variant At least one dimension does not pass.

stage	DevelopmentStage → DevelopmentStage	yes	How far development has carried it.
blocking	array of DimensionId → DimensionId	yes	The dimensions that do not pass, in the order of the conjunction.
state	"not_delivered"	yes

Used by FeatureDelivery

DeliveryTallies

object

How many features pass each measured dimension, and how many exist.

property	type	required	description
features	integer (uint)	yes	Features examined.
on_master	integer (uint)	yes	On the trunk.
deployed	integer (uint)	yes	Contained in the public identity.
publicly_verified	integer (uint)	yes	Publicly verified.
exists	integer (uint)	yes	Every dimension passes.

Used by DeliveryReport

DeliveryVerdict

"pass" | "fail" | "unknown"

One dimension's answer. Three values and never two: a question that could not be asked is not a question answered yes, and it is not one answered no either.

passThe dimension holds, and the reason says what was observed.
failThe dimension was measured and does not hold.
unknownThe dimension could not be measured. Not a pass.

Used by Dimension

DevelopmentStage

How far development has carried a feature that does not exist yet. A ladder: a rung is reached only when every rung below it passes, so a feature whose tests are unknown is on_master even when the site already serves it.

unknownGit could not say where its implementation is.
not_implementedIt names no implementation, or nothing ever committed one.
implemented_on_branchIts latest implementation revision is on a branch and not on the trunk.
on_masterIts implementation is on the trunk.
testedOn the trunk, with every required test current.
deployedTested, and contained in what the public site serves.

Used by DeliveryState

Dimension

object

One dimension, decided: the verdict, the sentence that decided it, and what would move it.

property	type	required	description
dimension	DimensionId → DimensionId	yes	Which dimension.
verdict	DeliveryVerdict → DeliveryVerdict	yes	Pass, fail or unknown.
reason	string	yes	What was observed, in one sentence.
remediation	string \| null	no	What would change the verdict; absent on a pass.

Used by FeatureDelivery

DimensionId

The six dimensions of the delivery invariant, in the order the conjunction is written.

on_masterThe feature's latest implementation revision is reachable from the trunk.
deployedThe public site's identity commit contains that revision.
publicly_verifiedThe publication was verified from outside: the site answers with a clean identity, a second probe agrees, and GitHub's own build of the published branch succeeded.
required_tests_currentEvery test the feature requires has a current passing execution.
test_evidence_publishedThe evidence of those executions is published.
ui_linkedThe feature is linked from the user interface.

Used by DeliveryState Dimension

FeatureDelivery

object

One feature against the invariant.

property	type	required	description
id	string	yes	The feature's id.
title	string	yes	Its title.
status	string	yes	The status its file declares. Editorial, and not one of the dimensions.
exists	boolean	yes	The conjunction: true only when every dimension passes.
delivery	DeliveryState → DeliveryState	yes	Delivered, or the development stage and what blocks it.
dimensions	array of Dimension → Dimension	yes	Every dimension, in the order of the conjunction.
implementation	Implementation → Implementation	yes	What it is implemented by.

Used by delivery.feature DeliveryReport

IdentityRead

one of 3 variants

What reading the public identity document gave.

variant The site answered with an identity naming the commit it was built from.

commit	string	yes	The commit, as the site states it.
dirty	boolean \| null	no	Whether the tree it was built from was dirty, when the identity says.
state	"served"	yes

variant The site was asked and gave no identity: no network, no route, not a document.

reason	string	yes	Why, in one clause.
state	"unreachable"	yes

variant There was nothing to ask: no site address or no publication model.

reason	string	yes	Why, in one clause.
state	"unconfigured"	yes

Used by Publication

Implementation

object

The paths a feature is implemented by and the revisions that last touched them.

property	type	required	description
paths	array of string	yes	Repository-relative paths, derived from what the feature names: the source file of every capability module, `lib/<command>.sh` of every shell command the dispatcher sources, and the `implementation` of every claim.
head_revision	string \| null	no	The latest commit touching them reachable from `HEAD`.
master_revision	string \| null	no	The latest commit touching them reachable from the trunk.

Used by FeatureDelivery

Publication

object

The publication as observed: where the site is, what it serves, and whether that was verified.

property	type	required	description
url	string \| null	no	The site's address, when one was found.
identity_path	string \| null	no	The identity document's path under it, from the publication model.
identity	IdentityRead → IdentityRead	yes	What reading it gave.
verification	SiteVerification → SiteVerification	yes	Whether the publication was verified.

Used by DeliveryReport

SiteVerification

one of 3 variants

Whether the publication was verified from outside.

variant Clean identity, a second probe agrees, GitHub's own build succeeded.

detail	string	yes	What was observed.
state	"verified"	yes

variant Measured, and it does not hold.

reason	string	yes	What was observed.
state	"refused"	yes

variant Could not be measured.

reason	string	yes	Why.
state	"unmeasured"	yes

Used by Publication