instar 1.3.962 → 1.3.963

package/upgrades/1.3.963.md

@@ -0,0 +1,135 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A commitment can now carry a **check-in date**, and a background reconciler
+posts one reminder into that commitment's own topic when the date arrives.
+
+Before this, "I'll report back by Friday" lived in the session that said it. If
+that session ended, restarted, or compacted, Friday arrived and nothing
+happened. The PromiseBeacon nudges on *rhythm*, not on dates — it has no concept
+of a specific promised moment.
+
+**What ships (ACT-724 step 1 of 2):**
+
+- `Commitment.checkInAt` — an absolute instant, deliberately separate from the
+  beacon's `nextUpdateDueAt` / `softDeadlineAt` so a one-time dated reminder and
+  a rolling nudge cadence are not side effects of each other.
+- `CheckInReminderReconciler` — a scan over open commitments, driven by the new
+  `commitment-checkin-reminder` built-in job (every 5 minutes, `enabled: false`).
+- `POST /commitments/check-in-reminder/pass` and `GET /commitments/check-in-reminder`.
+
+**One recurring scan, not one alarm per commitment.** ACT-724 sketched a
+per-commitment scheduler entry; taken literally that reproduces two of the three
+defects the action itself lists — the two-file job dance (defect b) and
+self-disable by file edit (defect c). A scan has neither: coverage is a property
+of the scan, so there is no registration step that can be skipped, and teardown
+is just the commitment reaching a terminal status.
+
+**The ordering was wrong first, and the fix's own justification was unwired.**
+The first design stamped `checkInReminderSentAt` *before* sending — which made
+zero delivery a designed outcome, since a failed send left the commitment marked
+delivered and permanently ineligible. Inverted to send-then-stamp with bounded
+retry (5 attempts, then a loud `checkInReminderFailedAt`). The second review
+round then caught that the duplicate mitigation justifying that inversion —
+"the relay dedups" — was not connected: `sendToTopic` does not dedup, that lives
+in the `/telegram/reply` route. The send is now explicitly routed through the
+same durably-backed `OutboundContentDedup`.
+
+**Honest guarantee: at-least-once, deduped at the delivery layer** — not
+exactly-once. Both remaining windows are stated in the spec rather than designed
+away.
+
+A newly created scheduled job fired immediately on the next server restart —
+including one scheduled months ahead.
+
+At startup the scheduler sweeps for work that was missed while the machine was
+off. To decide, it compares now against the job's last run. For a job that has
+**never** run there is no last run, and the code resolved that case by treating
+it as overdue and triggering it. That is right for a job added while the server
+was down that slept through its window, and wrong for a job created minutes ago
+whose first window is in December — "has never run" describes both identically.
+
+The comment directly above that branch stated the correct rule —
+
+> *"Jobs that have never run: trigger on startup if their first expected run
+> time has already passed"*
+
+— and the code never checked the condition. It couldn't: nothing recorded when a
+job started existing, so there was no fact to reason from.
+
+`JobState.firstSeenAt` is now stamped once at registration, and the sweep applies
+the intended rule: a never-run job is missed only if it has existed longer than
+one of its own intervals. A December reminder created today waits; a job that has
+sat unrun through six four-hour windows still catches up.
+
+Every unknown resolves to **not firing** — missing or unparseable `firstSeenAt`,
+uncomputable interval. That asymmetry is deliberate: a skipped catch-up costs one
+delayed run, while a future-dated job that fires early marks itself delivered and
+never fires again, so nobody goes looking for it.
+
+**Why now:** this is the prerequisite for dated commitments materializing real
+scheduled reminders (ACT-724). A reminder built on a scheduler that fires
+future-dated jobs at boot would discharge itself before its date — worse than
+never having built it. The standard itself is not in this change.
+
+## What to Tell Your User
+
+Nothing changes until it's switched on. When it is: on the day the agent said it
+would check in on something, you get one short message in that conversation
+saying the date has arrived.
+
+It will not claim the work is done — a reminder that implies completion closes
+the question instead of reopening it.
+
+**Not yet true:** ACT-724 asks that a dated commitment without a reminder be
+structurally impossible. This ships dark, and a disabled watcher guarantees
+nothing. What is true today: if the reconciler is running, no dated commitment
+can slip past it individually. The creation-time gate that closes the rest is
+step 2, and it cannot itself ship dark.
+
+If you've ever seen a scheduled job run for no obvious reason shortly after a
+restart, this was probably it.
+
+The practical effect: reminders and scheduled work now happen when they're
+scheduled, not when the server next happens to reboot. A job that's been waiting
+less than one of its own cycles will now wait for its proper turn rather than
+firing at startup — that delay is the point.
+
+## Summary of New Capabilities
+
+- Commitments carry a first-class check-in date that produces a real reminder.
+- A reminder is never recorded as delivered unless it actually was; failures
+  retry and then give up visibly.
+- Two read/drive endpoints and a built-in job, all dark by default.
+
+- Scheduled jobs with a future first window are no longer discharged at server
+  startup.
+- Job state records when a job was first registered, so "brand new" and "long
+  overdue" are distinguishable facts rather than a guess.
+- The startup sweep fails toward not-running on every uncertainty.
+
+## Evidence
+
+- Tier 1 (41): the full eligibility predicate on both sides of every clause;
+  idempotency across repeated passes; **a failed send never reads as sent** (the
+  regression test for the round-1 finding); bounded retry to a loud terminal
+  state; per-pass cap deferring rather than dropping; the reminder text never
+  asserting completion.
+- Tier 2 (10): real Express routes + auth — delivery, HTTP-boundary idempotency,
+  dark 503, missing-transport 503, and `dryRun` defaulting ON when config omits it.
+- Tier 3 (4): real `AgentServer` boot with a real injected `CommitmentTracker`.
+
+- `tests/unit/job-scheduler-never-run-future-job.test.ts` (3 cases): a never-run
+  annual job and a freshly-registered daily job both stay at zero triggers; a job
+  registered 6h ago on a 5-minute cron still catches up. Written failing first —
+  the two "must not fire" cases failed against the old code, the catch-up case
+  already passed.
+- `tests/unit/job-scheduler-edge.test.ts`: the existing test that asserted the
+  buggy behaviour was **updated, not deleted** — it now seeds `firstSeenAt` in the
+  past so it exercises the scenario it was written for (a job that genuinely
+  missed windows), plus a new sibling pinning the other side of the boundary.
+- Full scheduler suite: 76 tests across 8 files, green.

package/upgrades/side-effects/dated-commitment-reminder.md

@@ -0,0 +1,240 @@
+# Side-effects review — dated-commitment-reminder
+
+**Change:** commitments gain a first-class `checkInAt`; a recurring reconciler
+posts exactly one fixed-template reminder to the commitment's topic when that
+instant arrives; a built-in job drives it. ACT-724 (critical, pinned).
+
+**Spec:** `docs/specs/dated-commitment-reminder.md` (2 review rounds; round 1
+returned SERIOUS ISSUES and inverted the send/stamp ordering).
+
+**Ships dark:** dev-agent gated + `dryRun` defaulting true + job manifest
+`enabled: false`.
+
+---
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+- **A dated commitment with no `topicId` is never reminded** (`no-topic`). A
+  reminder with nowhere to go is not a reminder; it is reported as a skip reason
+  rather than silently dropped, and appears in the `pending` list.
+- **An unparseable `checkInAt` fails closed.** Deliberate: coercing it would make
+  the commitment look overdue since epoch and fire immediately — the exact
+  boot-fire shape fixed in `scheduler-never-run-window` days earlier.
+- **A pass is capped at 25.** An overdue backlog drains across passes rather than
+  flooding a topic. The cap logs when it drops work, so a truncated pass is never
+  reported as a complete one.
+- **Only `pending` counts as open.** A status added later is treated as not-open
+  (no reminder) until classified deliberately. Safe direction, but it does mean a
+  future status would silently stop reminders until someone adds it to the set.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **"Structurally impossible" is not yet true.** ACT-724 asks that a dated
+  commitment without a reminder be impossible. Shipping dark means the watcher
+  can be off, so a dated commitment CAN exist with nothing watching. What IS
+  structural today: given the reconciler runs, no individual commitment can be
+  missed (coverage is a property of the scan, not of a per-commitment
+  registration). The creation-time gate that closes the rest is the declared
+  graduation step, and it cannot itself ship dark. Called out because the spec's
+  own framing over-claimed until review pushed back.
+- **A duplicate is possible in one narrow window** — crash between send and
+  stamp. Accepted, and mitigated by the relay's existing content dedup rather
+  than by design novelty. Stated plainly instead of claimed away.
+- **Clock jumps** shift a reminder in time (late on a backwards jump, early on a
+  forwards one) but cannot double-send or permanently suppress.
+- **No escalation if a reminder is ignored.** Out of scope: this delivers the
+  date, it does not chase. The beacon owns chasing.
+
+## 3. Level-of-abstraction fit
+
+The decision (`isCheckInReminderDue`) is pure and lives in
+`checkInReminderCore.ts`; the effects (CAS, send, retry) live in the reconciler;
+the cadence lives in a built-in job. That split is what let both sides of every
+clause be tested without a store, a clock, or a transport.
+
+**The alternative I rejected is the more standard one.** A transactional outbox
+(`reminder_deliveries` with pending/sent/failed) is the textbook answer and is
+genuinely better at volume. Rejected here because the commitment record already
+IS durable single-writer state: a second store would add a consistency boundary
+— a new class of divergence bug — to serve tens of commitments. The fields on the
+commitment are a degenerate outbox with exactly one row per commitment. If volume
+ever justifies it, the migration is mechanical.
+
+## 4. Signal vs authority compliance
+
+`docs/signal-vs-authority.md`. Both decision points are `invariant`:
+
+- **The due predicate** is arithmetic over durable state (open ∧ date arrived ∧
+  unstamped ∧ routed ∧ retries remain). No competing signals, nothing to weigh.
+  The failure being fixed was an ABSENT mechanism, not a bad judgment.
+- **The reminder text** is a fixed template, deliberately not model-authored.
+  Generating it would add a judgment where none is wanted and a failure mode
+  (provider down) on a path whose entire purpose is to not fail.
+
+**Deliberate gate bypass, argued:** the reminder rides the deterministic delivery
+path, not the LLM tone gate. The tone gate fails closed, and a reminder that can
+be held by a failing gate is the defect this feature exists to fix. This is not
+weakening a safety control — the control is inapplicable, because the message
+carries no agent prose for it to judge. Nothing model-generated reaches the user
+through this path.
+
+## 5. Interactions
+
+- **PromiseBeacon** — untouched. `checkInAt` is a NEW field precisely so beacon
+  cadence (`nextUpdateDueAt`, `softDeadlineAt`) is not overloaded; a one-time
+  dated reminder and a rolling nudge cadence stay independent.
+- **`CommitmentTracker.mutate`** — the existing single-writer CAS is reused, not
+  replaced. Two passes racing cannot double-stamp.
+- **The relay's content dedup** (`outboundContentDedup`) — now load-bearing for
+  this feature's duplicate story. Documented in both the spec and the reconciler
+  so a future change to that window is understood to affect this.
+- **The scheduler** — this is why `scheduler-never-run-window` shipped first. A
+  reminder job on the old scheduler would have fired at boot.
+- **`installBuiltinJobs`** — writes both `jobs/instar` and `jobs/schedule` for
+  built-ins, which is exactly why ACT-724's defect (b) (the two-file dance) does
+  not apply: that dance is only manual for USER jobs.
+
+## 6. External surfaces
+
+- **New:** `POST /commitments/check-in-reminder/pass`, `GET
+  /commitments/check-in-reminder`. Both Bearer-authed, both 503 when dark.
+- **New built-in job** `commitment-checkin-reminder`, `enabled: false`.
+- **New commitment fields** — additive and optional; existing records load
+  unchanged, no migration.
+- **User-visible:** one message per dated commitment, at its date, in its own
+  topic. Fixed template. The only user-facing text this change introduces.
+- **A transport is required only to SEND.** A dry run needs none — surfaced by
+  the Tier-3 test, which would otherwise have reported the feature dead on an
+  agent with no messaging configured.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Unified, with a single-executor rule.**
+
+- `checkInAt` / `checkInReminderSentAt` / `checkInReminderAttempts` /
+  `checkInReminderFailedAt` live on the commitment record and inherit the
+  commitment store's existing posture. No new state surface.
+- **The pass must run on ONE machine.** The built-in job is per-machine (each
+  machine runs its own scheduler), so on a pool the pass must be lease-gated the
+  way the benchmark-divergence analysis pass is. Belt-and-braces: even if two
+  ran, the CAS stamp makes the second a no-op — the lease prevents wasted work,
+  the CAS prevents the duplicate.
+- **HONEST GAP:** the lease gate is specified in §Multi-machine posture but the
+  job ships `enabled: false`, so it is not yet wired in this change. Enabling the
+  job on a multi-machine pool BEFORE adding the lease check would risk two
+  machines both passing — the CAS still prevents a duplicate reminder, but the
+  work would be duplicated. Recorded as a precondition of enabling, not as done.
+- No notice routing, no generated URL, nothing that strands on topic transfer.
+
+## 8. Rollback cost
+
+Disable `commitments.checkInReminder` or the job manifest. The reconciler is the
+only reader of these fields; commitments keep them inertly. No migration, no
+durable cleanup, no agent-state repair. Reverting the commit is equally safe.
+
+## Second-pass review
+
+**Required** — this sends messages to users (outbound messaging is on the Phase-5
+trigger list).
+
+Two rounds of external cross-model review, the first of which returned **SERIOUS
+ISSUES** and changed the design:
+
+1. **Stamp-before-send made zero delivery a designed outcome.** A failed send
+   left the commitment marked `checkInReminderSentAt` and permanently
+   ineligible. Inverted to send-then-stamp with bounded retry; the duplicate risk
+   is covered by the relay's existing dedup. A regression test asserts a failed
+   send never reads as sent.
+2. **"Structurally impossible" over-claimed** for a feature behind a disableable
+   flag. Split into what is true now versus at graduation.
+3. **Time semantics under-specified** — `checkInAt` is now defined as an absolute
+   instant with normalization at the creation boundary, and DST/clock-jump
+   behaviour is stated.
+4. **Cadence and scale omitted** — 5-minute cadence, worst-case lateness, the
+   in-memory store's actual size, per-pass cap and backlog drain are now stated.
+5. **Alternatives not compared** — outbox, durable queue, one-shot entries, and
+   per-commitment scheduler entries are now compared with reasons.
+
+Self-review found one thing the reviewer did not: the Tier-3 test initially
+asserted that `AgentServer` self-constructs the `CommitmentTracker`. It does
+not — `server.ts` injects it — so the routes 503'd on the real boot path while
+Tier 2 passed happily against a hand-assembled context. That is exactly the
+wiring assumption Tier 3 exists to break, and the test now mirrors the
+production entrypoint. It also surfaced the dry-run/transport coupling in §6.
+
+Tests: 41 unit + 10 integration + 4 e2e = 55.
+
+
+## Class-Closure Declaration
+
+**Class:** `unbounded-self-action` · **Closure:** `guard` · **Enforcement:** ratchet
+**Citation:** `tests/unit/self-action-convergence.test.ts`
+
+This change adds a self-triggered controller: a cadenced pass that SENDS
+messages to users without a human in the loop. Under the "Capacity Safety — No
+Unbounded Self-Action" standard that has to be proven to CONVERGE under
+sustained pressure, not merely be individually correct.
+
+Registered as `check-in-reminder-pass` in `src/testing/selfActionRegistry.ts`.
+
+**Steady-state bound.** The emit is gated by a durable per-commitment attempt
+counter (`CHECK_IN_MAX_ATTEMPTS = 5`), persisted through the CAS `mutate()`
+BEFORE the send — so a crash-loop cannot buy fresh attempts, and the registry's
+restart model (which reconstructs from durable state) settles at the same bound.
+
+**Settling brake.** Two terminal states, both durable: a successful send writes
+`checkInReminderSentAt`, making the commitment permanently ineligible; repeated
+failure exhausts the counter and writes a loud `checkInReminderFailedAt`.
+
+**Modeled at the worst case.** The registry model has every send FAIL, so the
+success stamp never lands and only the attempt counter can stop it. Without that
+counter the model emits once per tick forever and the ratchet fails — which is
+the point: the bound is load-bearing, not decorative.
+
+**Instantaneous mass** is separately bounded by the per-pass cap (25), which logs
+when it defers rather than dropping silently.
+
+
+---
+
+## Addendum — three CI gates, and a coverage gap they led me to
+
+**1. Write-domain classification.** `POST /commitments/check-in-reminder/pass`
+mutates the commitment store and was undeclared. Classified `cluster-shared` in
+`WriteDomainRegistry`, matching the requirement that the pass run on the
+serving-lease holder only — the same single-writer shape as the feedback-factory
+routes. This does NOT weaken the honest gap in section 7: the lease gate is still
+not wired, and the classification records the intended posture rather than
+asserting the wiring exists.
+
+**2. Agent-id header.** The job's curl shipped Bearer-only; I dropped the
+AGENT_ID line when adapting the template I copied from. Restored. Worth noting
+as a pattern: adapting a template is where declared requirements silently fall
+out.
+
+**3. Docs coverage.** Job coverage fell 85% to 83% because the new built-in job
+was undocumented. Added to the default-jobs reference. That floor caught a real
+Agent-Awareness omission, not a bureaucratic one — an undocumented job is one no
+operator can discover.
+
+**And the thing worth more than all three: a coverage gap in the tone-gate suite.**
+
+While dogfooding I hit a live advisory I could not override — four attempts,
+byte-identical text, matching rule, sufficient reason, refused every time. That
+is the RELEASING half of the advisory migration failing in production.
+
+Investigating: every existing test in the advisory-migration integration file
+pins ONE verdict for the whole run via a fixed mock, so the rule is constant by
+construction and an ack always matches. The live gate RE-REVIEWS on every attempt
+and can return a different rule — mine went B20_INTERNAL_ID_LEAK then
+B11_STYLE_MISMATCH. That variability was not covered at all.
+
+Two tests added: (a) re-review returns the SAME acked rule, ack honored, message
+sent; (b) re-review returns a DIFFERENT rule, the stale ack is refused rather
+than silently passing an objection nobody reviewed.
+
+BOTH PASS, which exonerates the ack mechanism and kills my working hypothesis. I
+therefore have a reproducible symptom and NO diagnosis, and I am shipping the
+closed coverage gap rather than a guess dressed as a fix. The evidence and the
+candidates I have not ruled out are in the run log; the four tone-gate tracking
+actions stay OPEN because the releasing half is unproven in production.