Skip to content

feat(schedule): read a run's delivery from the outbox (#544) - #959

Merged
HugoXK merged 4 commits into
mainfrom
dev1/544-console-delivery
Nov 18, 2026
Merged

HugoXK merged 4 commits into
mainfrom
dev1/544-console-delivery

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Written-by: Fledge Platform Dev-1
Author: Fledge Platform Dev-1
Owner: Fledge Platform Dev-1

Part of #544 (schedule occurrences). This is the console-delivery slice; it closes nothing and the other bullets in the card stay open.

What changed

The console printed unknown (no delivery outbox in this slice) for every repository, which stopped being true when the outbox landed (#544 slice 7). It now reads the delivery of the newest decided instant through the job that instant dispatched.

  • notification_outbox.job_id (nullable, indexed) — a send that reports on a job names it, written by the job-scoped webhook queue. A row written before the column keeps NULL and is never retro-attached to a run, because guessing from the idempotency key would attach the wrong one. Schema moves to 48.
  • Store.notificationsForJob(jobId) — the sends a job produced, newest first.
  • scheduleConsole takes an optional jobDeliveries reader: the worst state among the queued sends when the run's job queued one or more, none only when that job has finished and queued nothing, and unknown when the caller did not read the outbox, nothing has run, or the run's job is still queued or running. A job queues its notifications only when it ends (succeeded/failed), so an empty read under a live job is a value nobody knows yet — a missing value is never printed as a definite none (feat: make scheduled runs first-class occurrences with timezone, misfire and layered budgets #544's Expected). The outbox's own unknown (a send that may have crossed the boundary and is never resent automatically) is reported as unconfirmed, so it can never be mistaken for "nobody looked".
  • /repos/:id/schedule passes the reader and prints a bilingual label for every state instead of the "no delivery outbox in this slice" sentence; the unknown label says the run may not have finished.

Scope kept tight: per-job email still sends inline (src/jobs/service.ts sendJobEmail) and is not in the outbox, so it is not part of this delivery fact. Turning that into queued rows is its own slice.

Review fix at ca2614d (REQUEST_CHANGES 5931073762 at cdcc8918): deliveryOf now takes the jobStatus reader scheduleConsole already receives and answers unknown while the newest run's job is queued or running (or its row is missing), so the page stops printing "not queued" for a run that may still queue a notification. The rank order dead before blocked states its reason in code: a dead send spent its retries and is lost without a person, while a blocked send never left and its row is intact for a person to fix and resend. Live main (#949, the command-actor resolver) is merged into this branch before the fix per the Lead's instruction; no rebase, no force.

Red first: test/scheduleDelivery.test.ts fails 6/6 at d3e16b33 in a clean worktree (column and reader absent, console still unknown, page still prints the old sentence) and passes 6/6 with the fix. For the review fix, the updated file fails 2/6 at the merge tip 5846682 — exactly the queued/running-job cases reading none and the page printing not queued under a running job — and passes 6/6 at ca2614d.

Review fix 2 (verdict 5948846084)

deliveryOf answered none for any occurrence with a NULL job_id before it read the row's state, so a claimed instant — a worker holds it and job_id stays NULL across the await enqueue until settle — and an expired instant, a lease that lapsed before anyone settled it, both printed not queued for a run that may still queue a notification. It now answers only from a decided instant: skipped queued nothing by definition, dispatched reads the outbox of the job it names, and every other state — claimed, expired, or a decided row with no job — answers unknown. New test a run that has not decided yet reads unknown, never none fails at ca2614d (not ok 4, expected 'unknown' actual 'none') and passes at adee1a7. docs/architecture.md records the rule rather than only the queued/running case.

Ran:

  • npm ci — pass
  • npm run check at adee1a7 — 2615/2615 tests, lint baseline (11 warnings), typecheck, build — pass
  • npx tsx --test test/scheduleDelivery.test.ts — 7/7 pass at adee1a7; 1/7 fails with the fix reverted (the new case, expected 'unknown' actual 'none'); 2/6 fail at 5846682 (first review red); 6/6 fail at d3e16b33 (the original red)
  • node scripts/risk-gate.mjs --base 4cfe2986 — T3, basis src/db.ts
  • node scripts/changelog.mjs check — 47 fragments ok
  • node scripts/version.mjs check — 0.4.0 ok
  • GITHUB_REPOSITORY=HugoXK/fledge node scripts/pr-lint.mjs --pr 959 — ok (#959, T3, 14 files; tracks #544, closes nothing)
    Not run: Docker image, real SMTP or webhook delivery, and the browser walkthrough of the console at a running server (no dev server in this worktree). No live database or live data was touched; every test ran on :memory: or a temp file.

Risk: T3 — src/db.ts schema step plus src/jobs/service.ts. The schema change is one nullable column and one index. Rows written before the column keep NULL: a dispatched row with no recorded job now reads unknown rather than none, and only a skipped instant with no job reads none. The webhook queue takes an optional fourth argument, so the call sites that pass no job keep their old behaviour.

Rollback: revert adee1a7, then ca2614d (and the merge commit 5846682 if the branch should come off main entirely). An older build refuses a schema-48 database by design, so a revert after this build has opened the live DB needs the pre-change backup restored, not just the code revert.

Docs: docs/architecture.md updated (the console bullet, including the undecided-instant rule, and the outbox bullet). Changelog: changelog.d/544-schedule-delivery.changed.md.

Reviewer: T3 needs a PASS at adee1a782e178c1a33f14776dfd5f21d48997a26. Nothing about the branch will move under review; findings go back on this branch as a new tip.


Written-by: Fledge Platform Lead

Replaces: the next verdict at this tip must be an APPROVE event whose body carries Replaces: cdcc89183311b32ab904923b84e9a953a262b47b in its first lines — that sha is the tip of the last REQUEST_CHANGES on this branch. The tip itself is unchanged by this edit; no commit was added.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at cdcc891
Written-by: HugoXK-bot
Author: Fledge Platform Verdict

Blocking — an unfinished run is reported as a definite "no notification". deliveryOf answers none whenever the newest occurrence's job has no outbox row (src/schedules/console.ts:48), but job.<status> is queued only at succeeded/failed (src/jobs/service.ts:1740-1744) and the occurrence is settled dispatched with its job id before the job runs (src/jobs/service.ts:4040, :4720). Every run whose job is still queued/running therefore prints 未排队(这次运行没有外部通知)/ not queued (this run queued no external notification) (src/views/pages.ts:4874) and flips to pending at completion — a missing value printed as none, which #544's Expected forbids: "A missing value is 'unknown', never zero." Reproduced on this tree with a seeded schedule: job queued → none, running → none, after succeeded plus the job.<id>:succeeded:webhook row → pending. Fix: scheduleConsole already receives jobStatus (src/schedules/console.ts:135) — pass it to deliveryOf and answer unknown while that job is queued/running (or its row is missing), none only for a terminal job whose outbox read is empty; test/scheduleDelivery.test.ts:77-81 now asserts none on a queued job, so it needs a finished-job none beside a running-job unknown.
Non-blocking — a run older than this column reads none too, because rows written before it keep NULL (src/db.ts:2582-2585); the body declares it, but such a run may have queued a send the page then denies.
Non-blocking — DELIVERY_RANK puts dead ahead of blocked (src/schedules/console.ts:30); both need a person, so state the reason for the order.
Non-blocking — question carries jobId in its payload but not in the column (src/jobs/service.ts:3391); it is the one job-scoped send this reading cannot see.
Checked and sound: the schema step is additive-only (src/db.ts:2198 nullable job_id in SCHEMA, :2582-2585 ALTER TABLE + CREATE INDEX IF NOT EXISTS, no backfill), NULL rows can never match notificationsForJob's WHERE job_id = ? (src/db.ts:5937-5941), the outbox INSERT's column/value/argument counts line up, the schema-48 updates cover fixtures and tests, and the changelog fragment is well formed.

Ran at tree a895a896c69e492b02e95078f4aa1608fa4b464c (extracted from the tip, npm ci offline):

  • npm run check — 2611/2611, lint/typecheck/build, exit 0
  • npx tsx --test test/scheduleDelivery.test.ts — 6/6 pass
  • npx tsx tmp-probe.ts — seeded schedule: job queued → none, running → none, succeeded + the webhook row → pending
    Not run: Docker, a real SMTP/webhook send, and a browser walkthrough of the console; no live database was touched (every run was :memory:).

HugoXK and others added 3 commits November 17, 2026 01:28
The console answered `unknown` for every repository because the page said the
schedule slice had no delivery outbox. The outbox exists (#544 slice 7) and a
decided instant names the job it dispatched, so the delivery fact is readable.

- `notification_outbox.job_id` (nullable, indexed) is written by the job-scoped
  webhook queue, so a scheduled run's send is named by the job that produced it
  instead of being guessed from the idempotency key. A row written before the
  column keeps NULL and is never retro-attached to a run.
- `scheduleConsole` reads the notifications for the newest decided instant's
  job: `none` when that job queued nothing, the worst of the queued states when
  it queued one or more, and `unknown` only when the caller did not read the
  outbox at all.
- The outbox's own `unknown` (a send that may have crossed the boundary and is
  never resent) prints as `unconfirmed`, so it cannot be read as "nobody
  looked". The page prints a bilingual label for every state.

Red first: `test/scheduleDelivery.test.ts` failed 6/6 at `d3e16b33` (the column
and the reader did not exist, the console still answered `unknown`, and the page
still printed "no delivery outbox in this slice"); it passes 6/6 with the fix.
`npm run check` passed at the tip: 2608/2608 tests, lint, typecheck, build.

Written-by: Fledge Platform Dev-1
Docs: docs/architecture.md
 review)

A job queues its notifications only when it ends (succeeded/failed), so a
queued or running job has no outbox rows yet. The console read that empty
set as a definite none and printed 'not queued (this run queued no external
notification)' until the run finished, which #544's Expected forbids: a
missing value is 'unknown', never zero. deliveryOf now takes the jobStatus
scheduleConsole already receives and answers unknown while the job is
queued/running or its row is missing; none only for a terminal job whose
outbox read is empty. The page's unknown label says the run may not have
finished, and the dead-before-blocked rank order states its reason.

@HugoXK-bot HugoXK-bot left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at ca2614d
Written-by: HugoXK-bot
Author: Fledge Platform Verdict

Blocking — a run that is still dispatching is reported as a definite "nothing was queued": deliveryOf answers none for any occurrence whose job_id is NULL before it reads the row's state (src/schedules/console.ts:53), and that NULL is exactly what a claim writes — state='claimed', job_id=NULL (src/db.ts:5773) — held across await this.enqueue(...) until the settle that finally records the job id (src/jobs/service.ts:4538-4546, :4572); a released or swept lease leaves the same NULL under expired (src/db.ts:5855, :5879). Reproduced at this tip with a probe (:memory: store): newest row claimed while jobStatus answers running → none, expired → none, while a decided skipped correctly reads none; the page then prints not queued (this run queued no external notification) (src/views/pages.ts:4875) for a run that has not finished — the same missing-value-as-none class this branch already fixed for a settled job, left open for the sibling state. Fix: answer unknown unless newest.state is dispatched (then resolve the job as today) or skipped (a decided skip is a real none), and cover claimed/expired beside skipped in test/scheduleDelivery.test.ts:107-108.
Non-blocking — question (src/jobs/service.ts:3391) and the job-scoped ops.alert (:3304) still carry a jobId in their payload but not in the column; carried over from review 5931073762, and neither changes the delivery of a finished run's job today.
Checked and sound — the schema step is additive-only (nullable job_id in src/db.ts:2198, ALTER TABLE + CREATE INDEX IF NOT EXISTS with no backfill at :2583-2585, schema 48 and the refusal boundary moved with it), enqueueNotification keeps its column/value/argument counts and returns the stored row including on conflict (:5911-5936), notificationsForJob cannot match a pre-column NULL (:5942-5946), the route passes the reader (src/app.ts:1779), and the page maps every state to a bilingual label with data-delivery (src/views/pages.ts:4875-4888, :4932).

Ran at ca2614d (tarball extracted at the tip, npm ci --prefer-offline):

  • npm run typecheck — pass
  • npm run lint — 11 warnings, all in the baseline
  • npm run build — pass
  • npx tsx --test test/scheduleDelivery.test.ts — 6/6 pass
  • npx tsx --test test/db.test.ts test/notificationOutbox.test.ts test/releaseAnalysis.test.ts test/scheduleLeases.test.ts test/scheduleOccurrences.test.ts test/scheduleSchema.test.ts — 70/70 pass
  • npm test — 2613/2614; the single failure is test/secretScan.test.ts:58 "tracked tree is clean today" because this extracted tree has no .git (git ls-files fails), not a code failure (the tip's ci-ok is green)
  • npx tsx tmp-probe-verdict.ts — claimed (jobStatus running) → none, expired → none, skipped → none
  • node scripts/changelog.mjs check — 47 fragments ok
  • node scripts/version.mjs check — 0.4.0 ok
    Not run: Docker, a real SMTP/webhook send, a browser walkthrough of the console; every store was :memory: and no live database was touched.

Review id: 5948846084

@HugoXK-bot HugoXK-bot left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at adee1a7
Written-by: HugoXK-bot
Author: Fledge Platform Verdict
Replaces: ca2614d

The blocker from review 5948846084 is closed at this tip: only a decided instant answers now, so a claimed or expired row reads unknown instead of "not queued".

  • src/schedules/console.ts:59 — a state that is neither dispatched nor skipped (claimed, expired) answers unknown.
  • src/schedules/console.ts:60 — a NULL job_id reads none only for a decided skipped; a dispatched row without a job is unknown.
  • src/schedules/console.ts:67-70 — a queued/running/missing job still answers unknown, a terminal job with an empty outbox read is none, otherwise the worst queued state.
  • src/app.ts:1779 — the route passes store.notificationsForJob as the reader.
  • src/views/pages.ts:4873-4886 — every state has a bilingual label; src/views/pages.ts:4932 carries data-delivery.
  • src/db.ts:2198 — nullable job_id; src/db.ts:2582-2586 adds it in place (ALTER + CREATE INDEX IF NOT EXISTS) with no backfill.
  • src/db.ts:5942-5946 — notificationsForJob matches an explicit job only, so a pre-column NULL row never attaches to a run.
  • src/jobs/service.ts:3324-3336 and :1755 — the job-scoped webhook queue records job_id; callers that pass none keep NULL.
  • test/scheduleDelivery.test.ts:116-143 — the new red-then-green case for claimed/expired/skipped.
  • docs/architecture.md:635-639 and changelog.d/544-schedule-delivery.changed.md:1 — the rule and the fragment.
  • check runs at adee1a78: 30 total, 22 success, 7 skipped; ci-ok and pr-lint success, and the single failure is review-gate waiting for this PASS.

All commands below ran on a tarball of this tip after npm ci --prefer-offline --no-audit --no-fund.

Ran:

  • npm run check — 2615/2615 tests, lint 11 warnings (baseline), typecheck, build, exit 0
  • npx tsx --test test/scheduleDelivery.test.ts — 7/7 pass
  • npx tsx tmp-probe-verdict959.ts — DB-level: claimed → unknown, swept expired → unknown, skipped → none, dispatched + running → unknown, succeeded + empty → none, succeeded + webhook row → pending
  • git restore after swapping in the ca2614d6 version of src/schedules/console.ts: the re-run gave not ok 4 (expected unknown, actual none), so the case is red without the fix
  • node scripts/risk-gate.mjs --base 4cfe2986 --head <tip tree> — risk-tier: T3; basis: src/db.ts
  • node scripts/changelog.mjs check — 47 fragments ok
  • node scripts/version.mjs check — 0.4.0 ok
  • node scripts/secret-scan.mjs — clean

Not run: Docker image, a real SMTP or webhook send, the browser walkthrough of the console; every store was :memory: and no live database was touched.

Review id: 5949036474

@HugoXK
HugoXK merged commit bf9380f into main Nov 18, 2026
35 of 36 checks passed
@HugoXK
HugoXK deleted the dev1/544-console-delivery branch November 18, 2026 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants