Phase 11: Jobs, realtime and search infrastructure - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents.
Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-09-28
Phase: 11-jobs-realtime-and-search-infrastructure
Areas discussed: Job manager & job records, Broadcast delivery path, Realtime package split, Worker & scheduler model (incl. search sync)
Job manager & job records
The first question set was interrupted; the user ran /gsd-explore on whether to port Apparatus as a plugin or fold it into the framework. Outcome: .planning/notes/apparatus-dissolved-into-framework.md.
| Option |
Description |
Selected |
(a) keep golem15_apparatus_jobs |
Straight copy at cutover; framework carries a plugin prefix |
|
(b) summer_jobs |
Framework-owned name, same columns and int ids, rows copied at cutover |
✓ |
| (c) configurable table name |
Per-app name |
|
| Option |
Description |
Selected |
| Mirror PHP exactly |
Same integers; skip = COMPLETE + {skipped:true}; ERROR only on River discard |
✓ |
| Add SKIPPED status |
New integer 5 |
|
| Option |
Description |
Selected |
| Both |
is_canceled + STOPPED and River JobCancel; long jobs still poll |
✓ |
| Poll is_canceled only |
Literal PHP port |
|
| River cancel + ctx only |
Go-idiomatic |
|
User's choice: Dissolve Apparatus into the framework; summer_jobs; mirror PHP outcomes; cancel via both.
Broadcast delivery path
| Option |
Description |
Selected |
| River job in the write tx |
Published only after commit; broadcasts queue |
✓ |
| Direct publish after commit |
Goroutine after-commit callback |
|
| Synchronous publish |
Inline in request |
|
| Option |
Description |
Selected |
| One attempt, best-effort |
tries=1, 5 s timeout, warn on failure |
✓ |
| Small retry |
River backoff, e.g. 3 attempts |
|
| Option |
Description |
Selected |
| Per model type, ctx-scoped |
WithoutBroadcasting[T](ctx, fn) |
✓ |
| All broadcasts in ctx |
One switch |
|
| Option |
Description |
Selected |
| Capture from PHP Centrifugo |
tide subscribes during recorded flows; goldens |
✓ |
| Goldens derived from PHP code |
Hand-written expected payloads |
|
Realtime package split
| Option |
Description |
Selected |
| Framework package + thin plugin |
Generic realtime package in summercms.go |
|
| All in fonoteka.go plugin |
Wholesale app port |
|
| Framework-bundled plugin |
First-party plugin in summercms.go |
|
User's choice: Free text: concerned about hard dependency on Centrifugo; wants transports pluggable so a project can replace it. Claude proposed a transport-neutral realtime package with drivers (centrifugo, memory, log, null), a Centrifugo sub-package, and Web Push behind its own interface. User: "yep that's perfect."
| Option |
Description |
Selected |
| Hand-rolled net/http |
Stdlib-first, exact request bytes |
✓ |
| gocent/v3 |
Official client |
|
| Option |
Description |
Selected |
| Health check only |
Defer push/VAPID |
|
| Port all of it |
Web Push + both VAPID commands + health check |
✓ |
| None |
|
|
| Option |
Description |
Selected |
| Only what's called |
Connection + subscription tokens |
|
| Full parity with PHP class |
All generator variants |
✓ |
Route mounting: Claude first suggested app-mounted handlers (wristband precedent). User asked: "won't that be a problem if we implement multiple drivers in future?" Claude refined it: drivers declare Routes() by surface (UserAuth / ServerToServer / Public) and the app maps surfaces to its groups and buckets through realtime.Mount. User's choice: Lock it.
Worker & scheduler model
| Option |
Description |
Selected |
| In serve by default + queue:work |
queue.work_in_serve toggle |
✓ |
| Only queue:work |
Separate process always |
|
| Option |
Description |
Selected |
| River periodic jobs |
HasSchedule → periodic jobs, leader-elected; schedule:run foreground + --once |
✓ |
| Laravel-style schedule:run |
System cron every minute, own locking |
|
| Option |
Description |
Selected |
| Driver interface, Typesense driver |
Searchable interface + engine driver; hand-rolled Typesense |
✓ |
| Typesense client only |
Direct port, no abstraction |
|
| Option |
Description |
Selected |
| After commit, inline, non-fatal |
Like Scout queue=false |
✓ |
| River job in the write tx |
Retryable, lags the write |
|
Claude's Discretion
- Package names and layout; ctx-to-GORM-hook plumbing for suppression; actor capture; River client config and timed-test harness; whether the Phase 8 expiry sweep moves to a periodic job; tide Centrifugo capture mechanics.
Deferred Ideas
- The admin extension point ("Phase 10.1") is not on the roadmap. It stays deferred, and the references that call it a phase need rewording.
- More realtime/search drivers; a Jobs admin screen; backend admin API tokens; guarded HTTP client and redacting slog handler (pending todos).
