The mesh knows where a module came from, and whether it is behind

Delivery is a comparison, not a pipeline: the control plane holds what source
exists and what has been built from it, and the difference is the work. Both
halves are written down now, so "is this current" is a question about two
columns rather than something you find out by building.

`status` answers "did my change go out?", which ADR 0010 names as the real risk
of replacing a pipeline with a comparison -- it is answerable today by opening
a pipeline, and something had to replace that.

  zsh    holds 4f2a9c1e, source has 9e3b7d2a
         running on laptop

The machines are the point. A module being out of date is a fact about the
catalogue; which machines are running last week's version is the thing with
consequences.

Three things this had to get right.

A module with no source is never behind -- it was handed over directly, which
is how a one-off arrives, and saying "out of date" about it would be inventing
a comparison against nothing.

A source nobody has checked is not behind either. Reporting it as behind would
put every module on the list the moment provenance was recorded, which makes
the list say nothing. Fault injection found this: my first test passed with the
guard removed, because both halves were empty strings and compared equal. The
case that actually needed it -- a known commit and an unknown head -- was
untested.

And handing over a manifest by hand does not erase where the module normally
comes from. Fixing something in a hurry is legitimate; silently forgetting its
origin is not, because that record is the only thing that would say afterwards
that a machine is running something nobody can rebuild.

Also fixed the flag parsing, which stopped at the first positional argument and
silently ignored every flag after it -- so `module add thing.json --source x`
recorded no source at all and said it had succeeded. The host's own parser
documents this exact footgun and I wrote it again anyway.
This commit is contained in:
2026-08-29 22:32:16 +02:00
parent 931a3a19a5
commit 653e232f1c
4 changed files with 424 additions and 17 deletions
@@ -0,0 +1,20 @@
-- Where each module came from, and whether what the mesh holds is still current.
--
-- novox/hq ADR 0010: delivery is a comparison, not a pipeline. The control plane holds what
-- source exists and what has been built from it, and builds the difference. So both halves have
-- to be written down, and *is this current?* is a question about two columns rather than
-- something you find out by building.
alter table module add column source text; -- where it comes from
alter table module add column ref text; -- the branch followed there
alter table module add column built_from text; -- the commit this manifest was read at
alter table module add column source_head text; -- the newest commit the source is known to have
-- When the mesh last learned the source had moved. Kept apart from `registered`, which is when
-- the manifest last changed: a source that moved and was never built is exactly the state this
-- exists to make visible, and one timestamp could not show it.
alter table module add column source_seen timestamptz;
-- A module with no source is not a fault. It was handed over directly -- which is how every
-- module got here before this existed, and how a one-off still arrives. It is simply never out
-- of date, because there is nothing it could be behind.