Skip to content

Curation P5: freshness — the refresh clock, admission on visit, the Stale tab, and the owner-versus-bot rules in code (under #254, #253; reopens #198) #259

Closed

Description

@holden

Reconciled 25 October 2026 with the independent assessment on #254 (its section C edits 7–11 apply here, accepted by the owner). Its contracts are now explicit in §5 with a race test each in §6. The list of changes is the reconciliation comment on #254.

Dedicated implementation issue for P5 of #254, under #253 (the product rules, which govern on any conflict) and #193. Written 25 October 2026. P1 (#255, PR #256) is live on love. P2 Delivery A merged at e25dd94; owner demonstration/Delivery B not evidenced. v2 holds one composition (love, composition 1). Same shape as #255 and #257: outcome, what you see, seams, scope, build, tests, two deliveries, acceptance, prompt. #198's "Admission and freshness" and "Publication and reader stability" paragraphs are the contract this restates; #198 is reopened for this part and stays open after it (§9).

1. Outcome

Every curated page knows when its inputs were last checked, whether they have changed since, and when it is next due, and says so to the reader. A visit to a stale page queues exactly one check on its own queue, never calls a model in the request path, and never moves the published pointer. The owner's queue gains its Stale tab for real. The rules of #253 §6a hold in code: withdrawal suppresses, a bot can only ever propose, a publication during a run flags the run's result, a late writer is refused. No model is called in this part: the worker completes without inference when nothing changed, and otherwise records that an editor is needed, which P6 consumes. A P5 needs_editor outcome means the inputs were checked, not that an editor evaluated their quality, and the disclosure says so until P6 completes an editor assessment.

This is the "every time it pulls a page it looks at the last time it was curated" the owner asked for on 21 October, and the prerequisite for a bot that runs on a schedule.

2. What you see

2.1 The disclosure, with the five dates distinct

On /on/love after this part, "How this was curated" open:

│ ▾ How this was curated · Published 23 October 2026 · global-default v1       │
│   Configuration   global-default, version 1 · lead rule bierce_first_v1      │
│   Selected by     Account #2 (operator) · 23 October 2026                    │
│   Published by    Account #2 (operator) · 23 October 2026 · version 1 · #3   │
│   Panel           None: published by the operator.                           │
│   Withheld        Nothing. Every selected item is still eligible.            │
│   Composition     #1, version 1                                              │
│   Last assessed   25 October 2026 · the inputs were checked, not judged:     │
│                   nothing has changed since this version was accepted        │
│   Checked         just now, against the record                               │
│   Inputs changed  not since this version was accepted                        │
│   Next assessment after 27 October 2026, or sooner if an input changes      │

Five different things, five different words, as #253 §7 insists: published (the receipt), last assessed (the last completed check), checked (read-time eligibility, every render), inputs changed (inputs_last_changed_at, kept after the pending dirty state clears), next assessment after (refresh_after). After a needs_editor check the row reads "the inputs were checked, not judged: an editor is needed", with why (the inputs changed, or the periodic re-assessment came due). A page with no check yet says "Last assessed: never · queued on your visit" once the visit has admitted a run, and "never" before.

2.2 The queue's Stale tab, /ops/curation?tab=stale

The test-partition demonstration (§7.3) has compositions on war and love; on v2 only love has one.

│ [Pilot pages 10] [Published 2] [Withheld items 0] [Stale 1] [Proposed — P6] │
│ WORD     STATE            LAST ASSESSED     WHY STALE                NEXT    │
│ war      published v1     25 Oct 09:14      a claim was reviewed     queued  │
│ love     published v1     25 Oct 09:14      —                        27 Oct  │
│ greed    never curated    —                 no composition yet       —       │
│ nepotism never curated    —                 no composition yet       —       │

"Why stale" is one of: never assessed, input changed (and which: a reviewed claim, a superseded revision, a new candidate, a withheld item, a configuration activation, re-opened), due (the window passed). A suppressed page (withdrawn) shows "withdrawn: not assessed until re-opened". A deferred page shows the failure and next_retry_at. A page with no composition shows "no composition yet: Curate to start its clock" (§5.2).

2.3 The editor's banner states (P2's editor, three new lines)

│ On war · global-default v1 · published v1 · last assessed 25 Oct 09:14      │
│ ⚠ Inputs changed since the last assessment: the Peloponnesian War claim was │
│   reviewed. Re-assessment is queued; nothing changes on the page until you  │
│   or an editor publishes a new version.                                     │

And after a withdrawal: "Withdrawn 25 Oct · not assessed again until you Re-open." Re-open now does write: it clears suppressed.

2.4 Nothing visible changes for the reader except the dates

No new section, no reshuffle. An open page keeps the version it rendered; a new publication applies on the next navigation. For withdrawal and lost rights, fresh loads revalidate; prompt suppression on already-open pages still needs an explicit bounded invalidation path and proof. That path is not in this part; it stays an open acceptance item of #198, and nothing here claims an open page drops a withdrawn item.

3. Seams

Need Existing
The pattern to copy Discovery.request/3 (admission on visit), Discovery.RunWorker (queue: :discovery, unique:), Discovery.Run (refresh_after, retry_at, expires_at, execution_lease_expires_at), Discovery.Policy.refresh_seconds/2
The inputs fingerprint Curation.Eligibility.evaluate/5 returns the eligibility fingerprint (configuration version, scope, applicable Bierce entries, every item's result); the published version's acceptance carries the fingerprint it was accepted with; Compositions.signature/1 for the scope
The candidate set's identity Curation.Candidates.for_page/1 (P2): its item specs, hashed with Curation.Digest.term/1, are the candidate half of the fingerprint until P4's packet digest replaces it (§5.1, versioned)
Where a visit happens WordLive.load/5 builds the page and reads the opening; the visit check runs there for every visit, plain HTTP render and LiveView mount alike, bounded (§5.6)
What a run reads and writes Published.current/1 and the composition's published pointer (reads), nothing on the publication (never moves the pointer)
The owner's rules Publications.withdraw/3 (sets suppressed), Publications.publish/3 with expected_pointer (compare-and-switch), P2's editor "Re-open" (clears suppressed)
Dirty triggers Claims.Contributions.review/6 (a claim decision), Registry.add_sense_revision/2 and add_content_revision/2 (a referenced revision superseded, or a new candidate under the scope), read-time withholding seen by the visit; a configuration activation needs no trigger (§5.4); P3's future pin revision
Oban config/config.exs queues [absorb: 1, enrich: 1, link: 2, discovery: 2, maintenance: 1]; add curation: 1
Budget 30 globally pending review-work units, reserved and released with actual reviewable work; unchanged assessments consume no new review unit. Daily inference occupancy is a separate 30-minute budget (Curation.Runtime.Gateway). P5 writes no reviewable work and calls no model, so it reserves neither; P6 charges both
The queue and editor P2's CurationLive (tabs pilot published withheld, tab-stale drawn disabled) and CurationLive.Editor (banner area, Re-open)

The configuration change. Adding the curation queue touches config/config.exs, which P2 showed the published host's code reloader refuses to pick up without a restart. So Delivery B of this part includes one restart of the published host, scheduled with the owner (the s237-release.sh restart path: bootout, bootstrap, wait_up; the launch script is unchanged). Until that restart the host keeps its old code, so the merge alone changes nothing live. Say so in the PR; it is the first part that needs one.

4. Scope

  • A curation_refresh_states table and schema, one row per composition and configuration version, with the §5.1 columns.
  • Curation.Refresh: admit/2 (the predicate, composition lock, generation, parent capture and the Oban insert in one transaction), mark_dirty/2, suppress/1, reopen/1, and the worker's claim, complete and defer.
  • Curation.RefreshWorker on the curation queue: build the fingerprint, compare, complete or record needs_editor; failures back off; no model call.
  • The visit check in WordLive, for every visit, bounded.
  • Dirty triggers at the seams in §3.
  • The disclosure's four new rows; the queue's Stale tab; the editor's banner lines; Re-open clears suppressed.
  • The §6a rules and the §5 contracts: suppressed, superseded_on_arrival persisted, the parent captured at admission, the fence on every write.
  • Telemetry: admitted, coalesced, deferred, completed (with outcome) as :telemetry events; the Health page lists the counts the record holds (§5.6).
  • Carried from the assessment (edit 5): the editor's scope label reads "Exact-word pages overlap this editing scope and cannot have a separate active lexical-page composition; they do not currently display this composition." One string in curation_live/editor.ex, which this part already changes.

Scope of pages: pilot allowlist only during MVP; later expansion disabled. No candidate threshold, no "every published composition" widening.

Out of scope, by the owner's word: any model call or proposal (P6); the packet (P4); pinning (P3); personas; a corpus-wide scan; the prompt-suppression path for already-open pages (§2.4); any change to how a page is read publicly beyond the four rows. If a blocker needs more, write it on the PR and stop.

5. Build

5.1 Migration (the one new table)

curation_refresh_states:

Column Type Meaning
composition_id FK, not null with configuration_version_id, unique
configuration_version_id FK, not null the configuration version the check is against
state enum idle queued running suppressed deferred suppressed set by withdrawal, cleared by Re-open; deferred is failure backoff only
refresh_generation bigint allocated per admitted run from idle; a retry from deferred and a lease recovery keep it
lease_token bigint the fence: incremented by every claim (worker start), recovery and suppression; every write carries the token it read and is refused if it moved
lease_expires_at timestamptz queued and running runs both hold a lease (queued 15 minutes, running 10); an expired one is recoverable (§5.2)
lease_attempts integer recoveries of the current generation; at 3 the run is deferred with backoff
admitted_parent_version_id FK, null the composition's published version at admission, not at worker start; nil when unpublished
superseded_on_arrival boolean the last completion found the published version moved since admission; P6 carries it onto the proposal
last_completed_at timestamptz the last successful check, including an unchanged or needs-editor result. Completion is not publication
last_outcome enum unchanged needs_editor what the last completed check found
refresh_after timestamptz last_completed_at + the window: 48 h default (#253 D7); an empty or abstaining result gets the empty window, 48 h initially
next_retry_at timestamptz failure backoff only: 1 minute, doubling with jitter, capped at 6 hours. A failed run never advances last_completed_at
failures integer consecutive failures, for the doubling; reset by a completion
last_error text the last failure, for the Stale tab
input_fingerprint text versioned: candidates-v1: + the eligibility fingerprint + the sha256 of the candidate set's item specs (ids and revisions, never text). P4's packet digest becomes packet-v2:. A fingerprint of another version never equals a new one
withheld_digest text the reader's withheld set at the last completion, so the visit can tell a new withholding (§5.4)
dirty_at timestamptz the pending change: set by a trigger if unset; cleared only by a completion that saw every change (dirty_seq)
dirty_reason text the latest pending reason: claim_reviewed, revision_superseded, candidate_added, item_withheld, reopened, pin_revised (P3)
dirty_seq bigint incremented by every trigger, so a change arriving during a run is never lost
run_dirty_seq bigint the dirty_seq the running worker read at its claim
inputs_last_changed_at timestamptz history: when an input last changed, kept after dirty_at clears; also set when a check finds the fingerprint changed
inputs_last_changed_reason text its reason
timestamps

Added in Delivery A (PR #261), in the same migration: run_periodic (boolean), decided at admission (the run was admitted only because its window passed: checked before, nothing pending) and cleared by any later dirty mark or publication, so only such a run completes as "due"; last_outcome_reason (text: accepted, unchanged, due, inputs_changed, fingerprint_version, nothing_accepted), so the page and the editor say why an editor is needed. The fingerprint also carries the version's standing as a whole.

Indexes: unique (composition_id, configuration_version_id); partial unique on composition_id where state in ('queued','running') (at most one in flight per composition, across configuration versions); (state, refresh_after) for the drain order.

5.2 Admission, in one transaction (Curation.Refresh.admit/2)

Scope. Admit only for a page on the pilot allowlist (CurationLive.pilot_pages/0) that has a composition under the active default configuration. A never-curated allowlisted page has no composition, so it has no refresh identity (the worker and the foreign key need one): it admits nothing, and the Stale tab lists it as "no composition yet". It gets its identity when a composition is provisioned: the screen's first Save draft (Compositions.provision/3) now; the editor's bot actor in P6. Its row is then initialised on its first admission.

Initialisation under a composition lock. Take a transaction-scoped advisory lock on the composition (pg_try_advisory_xact_lock; a visit that cannot take it at once returns :busy and writes nothing). Insert the row for the active configuration version if absent; a new row inherits suppressed from any other row of the composition. Then lock the row (FOR UPDATE).

Predicate. Admit when the state is idle or deferred, next_retry_at is nil or past, and one of: never completed, dirty_at set, refresh_after past. A queued or running row whose lease has expired is recovered instead (below); one whose lease holds is :in_flight (coalesced). suppressed is never admitted.

Admit. From idle allocate refresh_generation + 1; from deferred keep the generation (a retry). Capture admitted_parent_version_id = the composition's current published version id, read under the lock. Set queued, the queued lease, lease_attempts 1. Insert the Oban job (curation queue; args the row id and generation; unique on the row id over available/scheduled/retryable, a coalescing optimisation only) in the same transaction. No review unit and no inference time are reserved: P5 writes no reviewable work and calls no model.

Bounded lease recovery. An expired queued or running lease is re-queued with the same generation, lease_token + 1 (so the lost worker's writes are refused), a new lease and a new job, while lease_attempts < 3; the third expiry sets deferred with backoff, keeps the generation and resets the attempts. Readers are never affected.

A fresh visit makes zero inference requests; repeated stale visits cause one run (the second finds queued).

5.3 The worker (Curation.RefreshWorker)

  1. Claim, in one transaction: lock the row; refuse unless state == :queued and the job's generation is the row's (:stale_generation, discard, write nothing). Set running, lease_token + 1, the running lease, and run_dirty_seq = dirty_seq. The worker keeps the token it set.
  2. Read the inputs: the configuration version, Published.current/1, the candidate set; compute the fingerprint (§5.1).
  3. Decide. A periodic run (admitted only because refresh_after passed) → needs_editor (Curation agent MVP: what an editor does, what a curated entry contains, how the page looks, how the owner and the bots share one record, and how it stays current (under #193) #253 §7: a periodic run is an intentional re-assessment). Otherwise compare with the baseline: the stored input_fingerprint; for the first check of a published composition, the eligibility fingerprint the published version was accepted with (the candidate half becomes the baseline). Equal → unchanged; different, another fingerprint version, or nothing accepted yet → needs_editor. (P6 replaces needs_editor's stop with the editor call and proposal; this part stops at the record.)
  4. Complete, in one transaction: lock the row; refuse the write (:lease_lost) unless state == :running, the token is the worker's, the generation is the job's and the lease holds. A suppression during the run moved the token, so it is refused by the fence; a configuration change during the run (the active version is no longer the row's) is refused too (:configuration_changed), and the row is released to idle without a completion. Otherwise write last_completed_at now, refresh_after, last_outcome, the new fingerprint and withheld_digest, failures 0, next_retry_at nil, the lease cleared, state: :idle. Clear dirty_at and dirty_reason only if dirty_seq == run_dirty_seq; otherwise they stay pending for the next run. If the fingerprint changed, set inputs_last_changed_at (kept, never cleared). Persist superseded_on_arrival = the composition's current published version id differs from admitted_parent_version_id.
  5. On failure (an exception reading the inputs): under the same fence, deferred, failures + 1, next_retry_at by the backoff, last_error; last_completed_at untouched; the job ends (the next visit after next_retry_at retries the same generation).

5.4 Dirty triggers

Curation.Refresh.mark_dirty(composition_ids, reason) is one upsert per composition: dirty_seq + 1; dirty_at set if unset; dirty_reason, inputs_last_changed_at and its reason updated. It enqueues nothing (admission does, on the next visit). Callers:

  • Claims.Contributions.review/6: compositions whose items reference the claim, or whose scope's senses the claim is about (a newly accepted illustrates claim is a new exemplar candidate) → claim_reviewed.
  • Registry.add_sense_revision/2: compositions whose items reference the superseded revision → revision_superseded; compositions whose scope holds the sense's lexeme (new quotations are new candidates) → candidate_added.
  • Registry.add_content_revision/2: compositions whose items reference the superseded revision → revision_superseded.
  • Read-time withholding: the visit compares the reader's withheld set (already computed for the render) with the row's withheld_digest; a difference marks item_withheld once, in the admission transaction.
  • Configuration activation needs no write per composition: rows are per configuration version, so the new version's row is absent, the next visit admits it ("configuration activated"), and an in-flight run under the old version is refused at completion.

Anything these miss (a catalog row, a new entry) is caught by the periodic window.

5.5 The owner's rules in code

  • Publications.withdraw/3 → Refresh.suppress/1 in the same transaction: every row of the composition suppressed, lease_token + 1, lease cleared (an in-flight worker's write is then refused); a row is created suppressed if none exists.
  • P2's Re-open → Refresh.reopen/1: idle, dirty_at now, reason reopened. A publication on a suppressed composition (possible only outside the screen) clears it the same way.
  • admit/2 refuses suppressed.
  • The advisory lock, the row lock and the partial unique index are the correctness boundary; the Oban unique option only coalesces.
  • superseded_on_arrival as above.

5.6 Surfaces

  • PublishedReader adds assessment: %{last_completed_at, last_outcome, refresh_after, dirty_at, dirty_reason, inputs_last_changed_at, inputs_last_changed_reason, state} to Opening.Review; the component draws the four rows (§2.1) with the five distinct words and the needs-editor wording.
  • CurationLive: the Stale tab (§2.2) reads the rows; Proposed stays disabled (P6).
  • CurationLive.Editor: the banner lines (§2.3); Re-open calls reopen/1; the scope label (§4).
  • WordLive: on every visit to an On page on the allowlist, after the page is built, Refresh.admit(composition_id, :visit). Bounded: one indexed read when nothing is due; one short transaction when something is; never waits on a lock (a busy composition returns at once); a failure is logged and never reaches the page.
  • Telemetry events [:curation, :refresh, :admitted | :coalesced | :deferred | :completed] with the reason and outcome. /ops/health lists the counts the record holds: queue age (oldest queued or running), runs admitted today (oban_jobs on curation), completions today by outcome, deferred now. "Coalesced" is telemetry only.

5.7 Files

Add
priv/repo/migrations/<ts>_create_curation_refresh_states.exs §5.1
lib/devils_dictionary/curation/refresh_state.ex, refresh.ex, refresh_worker.ex §5.2–5.5
test/devils_dictionary/curation/refresh_test.exs, refresh_worker_test.exs §6
Change
config/config.exs curation: 1 in Oban queues (the restart in Delivery B)
lib/devils_dictionary/curation/{publications.ex,published_reader.ex,opening/review.ex} suppress on withdraw; the assessment fields
lib/devils_dictionary/claims/contributions.ex, lib/devils_dictionary/registry.ex the dirty triggers
lib/devils_dictionary_web/live/{word_live.ex,curation_live.ex,curation_live/editor.ex,health_live.ex} the visit check, the Stale tab, the banner and label, the counts
lib/devils_dictionary_web/components/opening.ex the four rows
docs/curation/persistence-slice-1.md one paragraph under Deferred

6. Tests

Refresh (refresh_test.exs):

  1. a fresh visit to a page with a published, assessed composition admits nothing;
  2. a first visit to a page with a published but never-assessed composition admits one run; a second visit while queued admits none;
  3. refresh_after past → one run; dirty_at set → one run with its reason;
  4. suppressed → none; after reopen/1 → one, reason reopened;
  5. next_retry_at in the future → none;
  6. an unchanged check and a needs_editor check reserve no review unit and no inference time: no composition version, review or claim is written and the runtime's budget is untouched;
  7. two concurrent admissions for one composition → one row queued, one job (the lock and the partial index, not Oban's uniqueness, decide);
  8. each dirty trigger marks exactly the compositions that reference the changed thing or whose scope gained a candidate;
  9. a never-curated allowlisted page admits nothing and lists as "no composition yet"; a page off the allowlist admits nothing even with a published composition.

Worker (refresh_worker_test.exs):
10. unchanged fingerprint → unchanged, last_completed_at advances, refresh_after set, the publication untouched, no runtime module called;
11. changed fingerprint → needs_editor, new fingerprint stored, inputs_last_changed_at set, publication untouched;
12. a periodic run (due) completes without a model call, as needs_editor, and resets the window;
13. a failure → deferred, last_completed_at unchanged, backoff doubles on the second failure, capped; the retry keeps the generation;
14. a job with a stale generation is discarded and writes nothing; a worker past its lease writes nothing;
15. a publication between admission and completion → superseded_on_arrival persisted on the row; the pointer is the new publication's, untouched by the worker.

Race tests, one per contract (deterministic: processes synchronised by messages, no sleeps):
16. parent captured at admission: publish between admission and the worker's claim → the row's admitted_parent_version_id is the version current at admission, and the completion flags superseded_on_arrival;
17. dirty during a run: a trigger between claim and completion → after completion dirty_at is still set with its reason, and the next visit admits one run;
18. inputs-last-changed history: after that next run completes and clears dirty_at, inputs_last_changed_at still shows the change;
19. initialisation under the composition lock: two first-ever admissions racing on an absent row → one row, one job, one generation;
20. bounded lease recovery: an expired running lease is re-queued with the same generation and a new token; the lost worker's completion is refused; the third expiry defers with backoff;
21. late write after suppression: withdraw while a worker runs → its completion is refused, the row stays suppressed, nothing else is written;
22. late write after a configuration change: activate another configuration version while a worker runs → its completion is refused and the old row is released without a completion; the next visit admits under the new version;
23. plain HTTP visits admit, bounded: a dead render of a stale pilot page admits one run; a following LiveView mount and a burst of further requests admit none.

Page and screen (additions to word_live_opening_test.exs, curation_live_test.exs):
24. the disclosure shows the four rows with the five distinct words, "never" before any check, and "checked, not judged" after one;
25. the Stale tab lists the right pages with the right reasons; a withdrawn page shows the suppressed line; Re-open clears it and the next visit admits a run;
26. the editor's banner shows "inputs changed" with the reason after a claim review, and the scope label reads the corrected sentence.

Precommit: MIX_ENV=test MIX_TEST_PARTITION=_cp5 DD_NO_OBAN=1 mix precommit (the test suite runs Oban in :manual; drain the curation queue explicitly in tests). Report the count.

7. Delivery A, implementation ready for review

  1. Worktree under .claude/worktrees/ on the external drive; symlinks for deps, data, priv/replay/*.jsonl.gz.
  2. Build §4–§5, tests §6, precommit green.
  3. Demonstrate on the test partition on war and love: first visit queues a run; the worker completes unchanged; review a claim → dirty with reason → next visit queues one → needs_editor; withdraw → suppressed, no admission; Re-open → one; a publication during a run → flagged. Keep the ids and the telemetry counts.
  4. Screenshots: §2.1 open on love, §2.2 the Stale tab, §2.3 the banner, each at 1280 and 375, every <details> closed except the disclosure in §2.1.
  5. PR "Curation P5 (Curation P5: freshness — the refresh clock, admission on visit, the Stale tab, and the owner-versus-bot rules in code (under #254, #253; reopens #198) #259): freshness, the refresh clock and the owner's rules", with the count, ids, screenshots, and the one migration and one restart it needs stated plainly. CodeRabbit and one independent review addressed. Write "PR open" on P5's line in Curation MVP implementation plan: seven parts with agent-ready briefs (P1 read compositions, P2 screen, P3 pin, P4 packet, P5 freshness, P6 proposals, P7 runtime) — under #253 #254; tick it only on merge. Comment here. Stop; the owner merges.

8. Delivery B, owner-approved live activation (this part needs one migration and one restart)

After the merge and the owner's yes in chat:

  1. git pull in the main checkout. The published host keeps its old code (the changed config/config.exs stops its reloader) until step 3. Read and record the actual live composition ids first (select id, current_published_version_id from editorial_compositions); do not invent the missing two. On 25 October v2 holds one, love's composition 1.
  2. Migrate v2: mix ecto.migrate (one new table; nothing else) only after the owner's explicit yes to the migration by name.
  3. Restart the published host once, because config/config.exs gained a queue. Do not use s237-release.sh rollback-on: its write_script on; restart rewrites the launch script, so "unchanged" could not be proved. Instead: record shasum -a 256 of ~/Library/Application Support/dictionary/phx-4007.sh, then launchctl bootout gui/$(id -u)/com.razrfly.dictionary.phx-4007, wait two seconds, launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.razrfly.dictionary.phx-4007.plist (repeat the bootstrap once if it races the bootout, as on 21 October), wait for http://127.0.0.1:4007/robots.txt to answer 200, confirm /on/love answers 200 through the tunnel within two minutes, and record the script's hash again: it must be identical.
  4. Confirm the curation queue is running (oban_jobs accepts a job on it; the Health page lists it) and that /ops/curation?tab=stale lists each composition recorded in step 1 as "never assessed".
  5. One visit per live composition's page through the tunnel → one job and one completion each (unchanged, or needs_editor where the owner changed something since), the disclosure's four rows filled. Record oban_jobs by worker before and after: exactly one Curation.RefreshWorker row per live composition, nothing else from curation.
  6. Review a claim on one page on the owner's say-so (or withdraw and re-open one): the page goes dirty with its reason, the next visit admits exactly one run, a second visit none.
  7. Evidence here; P5 ticked on Curation MVP implementation plan: seven parts with agent-ready briefs (P1 read compositions, P2 screen, P3 pin, P4 packet, P5 freshness, P6 proposals, P7 runtime) — under #253 #254 at merge; this issue closed. Final state: every live composition published, assessed, with its next assessment date shown.

9. Constraints

As #254's ground rules and #255 §9: external-drive checkout and worktrees, port 5434, private test partition, never edit the launch script, the one restart only in Delivery B on the owner's word, nothing against v2 before it, gh pr merge is the owner's, build only this issue and report a concrete blocker instead of widening. #198 stays open after this part: a model-free P5 does not meet its crash, recovery-with-proposals, prompt-suppression and proposal obligations.

10. Acceptance

  • Delivery A: the table, Refresh, the worker, the visit check, the triggers, the §6a rules and §5 contracts, the four rows, the Stale tab, the banner, telemetry; tests 1–26 green; precommit count reported.
  • A fresh visit makes zero inference requests and repeated stale visits cause one refresh (tests 1–2, 7, 23).
  • A failed run never advances last_completed_at; a stale generation, a lost lease, a suppression or a configuration change writes nothing (tests 13–14, 20–22).
  • Screenshots §2.1–§2.3 at both widths.
  • Reviewed PR; "PR open" on P5's line in Curation MVP implementation plan: seven parts with agent-ready briefs (P1 read compositions, P2 screen, P3 pin, P4 packet, P5 freshness, P6 proposals, P7 runtime) — under #253 #254, ticked on merge.
  • Delivery B: migration and one restart on the owner's yes; every live composition assessed; a dirty-then-one-run proof; oban_jobs shows only the expected rows; this issue closed.

11. Implementation prompt

Implement #259 exactly as written; its sections are the task. Read #259 in full, then #254's ground rules and P5 section, #253 §6a and §7, #198's "Admission and freshness" and "Publication and reader stability" paragraphs, PR #256 and PR #258 (the reader, the screen, the editor), and the files in §3 and §5.7. Copy discovery's refresh design; reuse the eligibility fingerprint; write the one migration in §5.1 and nothing more; call no model. Build §4–§5 with the tests in §6, demonstrate on the test partition on war and love, take the screenshots in §2, run the required precommit, open the PR, address CodeRabbit and one independent review, write "PR open" on P5's line in #254, comment here, and stop. Then present Delivery B's steps, including the migration and the one restart, for the owner's approval; run nothing against v2 and restart nothing until it is given. Do not build proposals, the packet, pinning or anything in a later part. Report a concrete blocker instead of broadening scope.

Activity

  1. holden commented on Oct 25, 2026

    @holden
    MemberAuthor

    Delivery A: #261, ready for the owner's merge

    Built, as reconciled on 25 October.

    • The table and its schema.
    • Curation.Refresh: admission, the fenced claim, completion and failure, the triggers, and the owner's rules.
    • Curation.RefreshWorker on the curation queue.
    • The visit check, for every visit, plain HTTP included, and bounded.
    • The disclosure's four rows, the Stale tab, the editor's banner, and the Health counts.
    • The corrected scope label (assessment edit 5).
    • Curation.Pilot: pilot allowlist only.

    No model is called, no review unit or inference time is reserved, and the published pointer never moves.

    Tests and precommit. §6 tests 1–26 pass, plus race tests for each §5 contract and the review's additions. MIX_ENV=test MIX_TEST_PARTITION=_cp5 DD_NO_OBAN=1 mix precommit: 19 doctests, 2,920 tests, 0 failures (on 20b7114).

    Reviewed. The independent review graded the first push B. The fence, the admission serialisation and the lease recovery held under real concurrency. Two semantic bugs (a dirty run past the window called "due"; a candidate change after a publication read as unchanged) and seven smaller findings were all fixed with tests in b846a00. CodeRabbit's one finding (clear run_periodic on a later dirty mark) was fixed in 20b7114. The detail is in the PR's "Review response" comment.

    Where the build departs from §5.1, or adds to it:

    1. Two extra columns, in the same migration, recorded under §5.1:
      • last_outcome_reason, so the page says why an editor is needed;
      • run_periodic, decided at admission, so only a run admitted for its window alone is "due".
    2. The fingerprint also carries the version's standing as a whole (Published.current/1's reasons). Item-level eligibility does not change when an approval is withdrawn, a scope changes or a configuration changes, and a check must not call those "unchanged".
    3. A publication resets the baseline the next check measures against (the eligibility the new version was accepted with). It makes the next visit due, and it is not recorded as an input change. Without this, every owner publication would read as "an editor is needed".
    4. The first check of a published composition compares against the fingerprint the published version was accepted with.
    5. A periodic run (admitted only for its window) completes needs_editor ("due"), as Curation agent MVP: what an editor does, what a curated entry contains, how the page looks, how the owner and the bots share one record, and how it stays current (under #193) #253 §7 says. A dirty run, or the owner's publication, is compared instead.
    6. A job that has not started takes a newer admission's arguments, so an old generation's job never sits in front of the new one.
    7. The bulk materializer's revisions do not pass through Registry.add_*_revision/2. They reach the clock through read-time withholding, which the visit sees, or through the window.

    Demonstration on devils_dictionary_test_cp5_demo (a migrated copy of P2's demo partition; port 4017; nothing touched v2). The ids, telemetry and oban_jobs counts are on the PR:

    • war and love each queued one check on first visit, and both completed unchanged;
    • a claim review dirtied war, and the next visit admitted one check (it found the fingerprint unchanged);
    • withdraw: suppressed, no admission;
    • Re-open: exactly one admission, which completed needs_editor;
    • a publication during a love run: superseded_on_arrival persisted.

    Screenshots at 1280 and 375 are on the PR.

    Not built here (still #198's): prompt suppression on already-open pages (§2.4), crash recovery with proposals, and the proposal path (P6).

    Delivery B: for the owner's approval

    Nothing runs against v2, and nothing restarts, until you say yes in chat.

    1. You merge: gh pr merge 261 --repo razrfly/dictionary --merge, or on GitHub.
    2. git pull in the main checkout. The published host keeps its old code: the changed config/config.exs stops its reloader.
    3. The one migration, on your yes by name: mix ecto.migrate against devils_dictionary_v2 (adds curation_refresh_states, nothing else). I record the live composition ids first; on 25 October there is one, love's composition 1.
    4. The one restart of the published host, on your yes: s237-release.sh rollback-on (bootout, bootstrap, wait for 4007). The launch script stays byte-identical; I confirm /on/love answers 200 through the tunnel within two minutes.
    5. I record oban_jobs by worker before and after one visit per live page: exactly one Curation.RefreshWorker row each, and nothing else from curation. The disclosure's four rows fill.
    6. On your say-so, a claim review (or a withdraw and re-open) shows dirty → one run → none on a second visit.
    7. Evidence goes here; P5 is ticked on Curation MVP implementation plan: seven parts with agent-ready briefs (P1 read compositions, P2 screen, P3 pin, P4 packet, P5 freshness, P6 proposals, P7 runtime) — under #253 #254 at merge; this issue closes.
  2. added a commit that references this issue on Oct 26, 2026
  3. holden commented on Oct 26, 2026

    @holden
    MemberAuthor

    Delivery B done, 26 October 2026 (owner's yes in chat: "tell the P5 session yes with the migration named")

    PR #261 merged as 9757c61 (my independent precommit on its head 20b7114: 19 doctests, 2,920 tests, 0 failures; CodeRabbit green, no open threads). Run from the main session, in this order, with nothing else touching v2:

    1. git pull in the main checkout: e25dd94 → 9757c61 (brings Runtime #221 fixes (P7 of #254, PR 1): stale refusals, the retry ceiling, confirmed runner stops, observable adverse counts #260 and Curation P5 (#259): freshness, the refresh clock and the owner's rules #261).
    2. mix ecto.migrate on v2: exactly one pending migration, 20261025200000_create_curation_refresh_states (table, two unique indexes, one state index, one check constraint). Nothing else pending before or after.
    3. Restart by bootout and bootstrap, not the release script: launch script sha256 6704fdf2553d6a97… before and after, identical; launchctl bootout then launchctl bootstrap (no race this time); 4007 answered in 9 s; new PID 61348; Curation.Refresh.beam in _build/published at 01:02.
    4. Through the tunnel: /on/love 200 with its opening; /ops/curation and /ops/curation?tab=stale 404.

    The clock, live:

    Step Result
    First tunnel visit to /on/love one Curation.RefreshWorker job (4645), completed 00:03:09; row idle / unchanged, generation 1, next assessment 28 Oct
    Second visit no new job (still 1)
    Publications.withdraw/3 (receipt 4, key p5-259-withdraw-1) row suppressed; opening gone through the tunnel; a visit admitted nothing
    Publications.publish/3 of version 1 again (receipt 5, key p5-259-love-3) row idle, dirty reason published (publication reset the accepted baseline)
    Next visit one job (4646), completed 00:04:22; row idle / unchanged, generation 2, next 28 Oct; opening back

    oban_jobs by worker after everything: Curation.RefreshWorker 2; CleanupWorker 672, Discovery.RunWorker 64, Quotations.VerifyWorker 337 unchanged. Final state: composition 1 published (version 1, receipt 5), assessed, with its next assessment shown.

    The disclosure through the tunnel now reads, after the P1 rows: Last assessed 26 October 2026 · the inputs were checked, not judged · Checked just now, against the record · Inputs changed not since this version was accepted · Next assessment after 28 October 2026, or sooner if an input changes. Five distinct words, as #253 §7 requires.

    Not exercised live: a claim review as the dirty trigger (no accepted claim exists on love); it is covered by the merged tests. #198 stays open as the contract. Closing this issue; P5 ticked on #254.

  4. holden commented on Oct 26, 2026

    @holden
    MemberAuthor

    P5 delivered and live; evidence above. #198 remains open as the contract.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions