docs: capture exploration — apparatus dissolved into framework

.planning/notes/apparatus-dissolved-into-framework.md

@@ -0,0 +1,46 @@
+---
+title: "Decision: Apparatus is dissolved into the framework, not ported as a plugin"
+date: 2026-09-28
+context: /gsd-explore during Phase 11 discuss (job manager gray area)
+---
+
+# Decision: Apparatus Is Dissolved Into the Framework
+
+**Date:** 2026-09-28
+**Status:** Accepted for Phase 11 onward
+
+## Decision
+
+`Golem15\Apparatus` is not ported as a plugin. The few pieces the ported plugins depend on move into `summercms.go` as framework packages; the rest is dropped or deferred. No `apparatus` plugin exists in `fonoteka.go`.
+
+## Job record: `summer_jobs`
+
+The PHP `JobManager` (`golem15_apparatus_jobs`, `JobStatus`, `ApparatusQueueJob`) becomes a framework job package over River.
+
+- Table name is **`summer_jobs`** (framework-owned, no Golem15 plugin prefix).
+- Columns and semantics are kept from PHP: integer auto-increment `id`, `label`, `status`, `progress`, `progress_max`, `user_id`, `is_admin`, `is_canceled`, `metadata`, timestamps.
+- `JobStatus` integers are kept: `IN_QUEUE=0`, `IN_PROGRESS=1`, `COMPLETE=2`, `ERROR=3`, `STOPPED=4`.
+- Integer ids stay the public contract: the CSV import API exposes them as `import_job_id` / `match_job_id`.
+- At cutover, rows from `golem15_apparatus_jobs` are copied into `summer_jobs` with ids preserved (same approach as Phase 9's `backend_users`).
+- River executes the work; the `summer_jobs` row is the record that API responses, progress and cooperative cancellation (`is_canceled`) read.
+- A `queue:clear` command (River bulk delete) belongs with this package. A Jobs admin screen can later be plain admin YAML.
+
+## Triage of the rest of Apparatus
+
+| Apparatus piece | Consumers in ported plugins | Disposition |
+|---|---|---|
+| JobManager, JobStatus, ApparatusQueueJob, jobs table | fonoteka CSV import/match, wishlist digest | **Framework** job package over River, `summer_jobs` (above) |
+| RequestSender (curl wrapper, bearer, multipart, private-IP guard) | feedback `G15OfficeClient`, golem `AIService` | **Do not port the class.** Extend `fetchguard` into a guarded `http.Client` (POST/PUT/multipart/bearer). fetchguard checks the IP at dial time, which closes RequestSender's resolve-then-connect DNS-rebind gap |
+| RedactCredentialsTap (log scrubbing) | logging config | **Framework** `slog` handler with the same sensitive keys and patterns |
+| SafeExceptionResponse (generic 500 message outside debug) | user `ApiController`, golem `AIService` | Verify `surf` already covers it; otherwise a small framework helper |
+| DependencyInjector, BackendInjector, NeedsDependencies, Resolver facade, DatabaseManager, Pipeline/Pipe | internal | **Drop**: the `backpack` service registry, constructor injection and Go middleware chains replace them |
+| RouteResolver, Messaging/ConfirmModal/InfiniteScroll components, HumanDateExtension, TranslApiController, theme scanner hook, BlogUrlValidationMiddleware | CMS pages / Twig | **Drop**: v1 is headless |
+| KnobWidget, Sensitive, ListToggle form widgets; BackgroundImportExport behavior | Winter backend | **Drop for now**; Sensitive may return as an admin SPA field type (Phase 10.1) |
+| PersonalApiToken for backend admins, TokenAuthenticate, ForceJsonResponse | none in Płytarium | **Defer** (todo: backend admin API tokens) |
+| Mail import/export/reset, SaneGitModules, Optimize, FakeJob, BrowserGeneration, generic CsvImportJob, HtmlSanitizer | none (fonoteka documents it does not use the generic CsvImportJob; HtmlSanitizer is used only inside Apparatus) | **Drop** |
+
+## Consequences
+
+- Phase 11's job manager service (JOBS-01) is the framework `summer_jobs` package; its migration ships with the framework.
+- Phase 14 plugins (feedback, AI recognition, Discogs) use the extended fetchguard client instead of a RequestSender port.
+- The Phase 15 cutover runbook must include the `golem15_apparatus_jobs` → `summer_jobs` copy.