feat(pi): let an ask declare dormancy, so waiting work stops nagging
A first-boot acceptance ask is planted deliberately unanswerable: it describes
work that becomes possible only when the device is next recreated, and it must
STAY owed until then, because closing it early to tidy the mailbox is exactly how
that work gets lost. deriveOwed could only see "directed, open, not answered, not
withdrawn", so such an ask was announced at every session start and every poll
for as long as it was correctly waiting -- measured at three days running on
emb-7kj4vr4g (2026-09-28 -> 2026-10-01), and across three consecutive releases
before that. The ask was right; announcing it was wrong, and the cost landed on
the human reading the window, who is the one reader that cannot filter it.
An ask may now declare the condition under which it is merely waiting:
"dormant_unless": [
{ "kind": "json_field", "path": "/etc/pi-devbox/build-manifest.json",
"field": "release_tag", "baseline": "v1.9.4" },
{ "kind": "file_mtime", "path": "/etc/hostname",
"baseline": "2026-09-22T18:12:49Z" }
]
Dormant while EVERY condition still matches its baseline; live the moment ANY
differs -- which is the trigger those asks already stated in prose ("act when
EITHER differs"), now in a form the bridge can check. Two kinds, local files
only, no expression language, no shell, no network: a general evaluator in the
path that decides whether work is VISIBLE is a far worse trade than a clumsy
schema.
DORMANCY IS PROVEN, NEVER ASSUMED. Every unevaluable predicate announces the ask
instead of hiding it: missing file, unreadable file, unparseable baseline,
unknown kind, vanished field, relative path, more than eight conditions. The
dangerous failure here is not a spurious nag but work that disappears because a
predicate could not be evaluated -- indistinguishable from the ask being lost,
and not surfacing until a release needed it. An ask with no dormant_unless
behaves exactly as before, so this is backward compatible by construction.
Withheld from the ANNOUNCEMENT, never from the mailbox: deriveOwed now returns a
partition {owed, dormant} rather than a flat list, the wake-up injection lists
dormant asks once per session with ids, and a mid-session poll adds only a count
and only when the window is already open for something else. Dormant asks are
deliberately NOT added to the `surfaced` map, so one becomes announceable the
instant its baseline moves.
file_mtime compares WHOLE SECONDS in UTC. A filesystem mtime carries sub-second
residue (measured: /etc/hostname at .773761009) that a reported ISO baseline
never will, so comparing raw milliseconds would mark every such predicate
permanently "changed" -- silently disabling the feature while appearing to work.
The test records the residue for that reason.
scripts/test-dormancy.sh is this repo's first test: 22 cases, positive and
negative arms both, because a predicate that never fires makes the feature inert
and one that fires too eagerly hides real work. It copies the extension into a
temp tree with pi's typebox symlinked beside it (the copy is made per-run, so it
cannot drift like a vendored duplicate), owns its own fixtures rather than
reading /etc paths -- the first draft passed only on a pi-devbox container and
would have silently flipped to "not dormant" anywhere else -- and exits 2 for
INCONCLUSIVE rather than 0, since a test that skips quietly is the failure mode
it exists to catch. shellcheck clean.
This commit is contained in:
@@ -378,6 +378,57 @@ the one failure this derivation exists to prevent.
|
||||
protocol says a broadcast owes nobody a reply — which also means broadcasting an
|
||||
ask demonstrably reaches no owed set, giving that documented anti-pattern teeth.
|
||||
|
||||
**Dormant asks — open, owed, and deliberately not announced.** Some asks are
|
||||
planted *unanswerable on purpose*: a first-boot acceptance describes work that
|
||||
becomes possible only when the device is next recreated, and it must stay owed
|
||||
until then, because closing it early to tidy the mailbox is exactly how the work
|
||||
gets lost. Derivation alone cannot tell that apart from neglected work, so such
|
||||
an ask was announced at every session start and every poll for as long as it was
|
||||
correctly waiting — measured at three days running on `emb-7kj4vr4g`
|
||||
(2026-09-28 → 2026-10-01), and across three consecutive releases before that.
|
||||
The ask was right; announcing it was wrong, and the cost landed on the human
|
||||
reading the window, the one reader who cannot filter it.
|
||||
|
||||
An ask may therefore declare, in its own `metadata`, the condition under which it
|
||||
is merely waiting:
|
||||
|
||||
```json
|
||||
"dormant_unless": [
|
||||
{ "kind": "json_field", "path": "/etc/pi-devbox/build-manifest.json",
|
||||
"field": "release_tag", "baseline": "v1.9.4" },
|
||||
{ "kind": "file_mtime", "path": "/etc/hostname",
|
||||
"baseline": "2026-09-22T18:12:49Z" }
|
||||
]
|
||||
```
|
||||
|
||||
It is dormant while **every** condition still matches its baseline, and goes live
|
||||
the moment **any** of them differs — the trigger such asks already stated in
|
||||
prose ("act when EITHER differs"), now in a form the bridge can check. Two kinds,
|
||||
both local-file-only: `file_mtime` (compared at whole seconds in UTC, because a
|
||||
filesystem mtime carries sub-second residue that a reported ISO baseline never
|
||||
will — comparing raw milliseconds would mark every such predicate permanently
|
||||
"changed" and silently disable the feature) and `json_field` (dotted paths
|
||||
allowed, compared as strings so a manifest holding `3` matches a baseline of
|
||||
`"3"`). There is no expression language, no shell and no network: a general
|
||||
evaluator in the path that decides whether work is *visible* is a far worse trade
|
||||
than a clumsy schema.
|
||||
|
||||
Dormancy is **withheld from the announcement, never from the mailbox**: the
|
||||
wake-up injection lists dormant asks once per session with their ids, and a
|
||||
mid-session poll mentions only a count, and only when the window is already open
|
||||
for something else. They are not added to the resurface map, so one becomes
|
||||
announceable the instant its baseline moves.
|
||||
|
||||
**Dormancy must be proven, never assumed** — every unevaluable predicate shows
|
||||
the ask as owed. A missing file, an unreadable one, a baseline that will not
|
||||
parse, an unknown `kind`, a vanished field, a relative path, more than eight
|
||||
conditions: each announces. The dangerous failure here is not a spurious nag but
|
||||
work that disappears because a predicate could not be evaluated, which would be
|
||||
indistinguishable from the ask being lost and would not surface until a release
|
||||
needed it. An ask with no `dormant_unless` behaves exactly as it did before the
|
||||
feature existed. `scripts/test-dormancy.sh` exercises all of it, positive and
|
||||
negative arms both.
|
||||
|
||||
Gated on `MEMPALACE_PI_DEVICE` **and** `MEMPALACE_REMOTE_URL` (the same pair as
|
||||
the stamper, since an unstamped client has no address to be reached at), and
|
||||
disabled outright with `MEMPALACE_MAILBOX=0` (notifications alone with
|
||||
|
||||
Reference in New Issue
Block a user