Carlos Florêncio
8.2 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 17-runtime-settings | Expose permitted runtime overrides | done | 17 |
|
plan.md |
|
|
|
Task 17: Expose permitted runtime overrides
Summary
Deliver the domain through the shared settings tools and authorized resource lookup. Include its complete eligible field set, current UI result, and independent contract checks.
In scope
- Derive runtime descriptors from the current flag registry and startup descriptors from the typed startup catalog.
- Expose one runtime_flag resource per existing key, with boolean/null override semantics.
- Enforce org.settings.manage before SetOverride. Preserve environment locks, mutability, retired identities, and pending-restart state.
- Keep features.auth interactive-only and all deployment-owned startup settings read-only.
- Preserve disabled-feature boundaries. Do not introduce a new flag, change shipped defaults, or restart the process.
- Use the existing Feature Toggles UI for saved/active values and live invalidation.
- Register metadata, context schemas, typed updates, redacted reads, and authorized lookup in the production composition.
- Add domain aliases to the independent search-query suite and update the generated snapshots.
- Include shared DTO conversion, semantic validation, and required atomic patch behavior for every write interface.
- Use current domain events, or add scoped value-free invalidation when none exists.
- Add coverage bindings and scoped editor tests. Update
docs/public/automation-and-mcp.mdwith delivered behavior.
Out of scope
- New persistence owners, arbitrary database access, privilege changes, and unrelated lifecycle operations.
- Automatic merging of dirty drafts, new navigation layouts, and real provider credentials in tests.
Acceptance
- Registered MCP calls match the existing UI contract for every eligible field, including explicit empties and domain-specific errors.
- Unauthorized, invalid, and conflicting changes preserve invariants without partial writes or sensitive output. New atomic patches cover competing writers.
- Clean editors update live and survive reload. Dirty drafts survive until recovery, on desktop and phone.
Verification
Run from the repository root after the one-time workspace dependency install in Task 00. These new test paths and names are planned implementation outputs, not existing evidence.
rtk proxy go -C apps/backend test ./internal/runtimeflags ./internal/common/config ./internal/profiles ./internal/mcp/server ./internal/mcp/handlers
rtk proxy go -C apps/backend run ./cmd/settings-catalog --check
rtk make -C apps/backend lint
rtk pnpm --dir apps/web exec vitest run lib/state/slices/features/features-contract.test.ts
rtk pnpm --dir apps/web exec vitest run lib/settings-discovery/runtime-settings-contract.test.ts components/settings/runtime-settings-reconciliation.test.tsx
rtk pnpm --dir apps/web run typecheck
rtk pnpm --dir apps/web run lint
rtk pnpm --dir apps/web run i18n:check
rtk pnpm --dir apps/web e2e:run --project chromium tests/settings/runtime-settings-mcp.spec.ts
rtk pnpm --dir apps/web e2e:run --project mobile-chrome tests/settings/mobile-runtime-settings-mcp.spec.ts
rtk node scripts/validate-public-docs.mjs
rtk git diff --check
Add TestRuntimeSettingsParity and TestRuntimeSettingsAuthority in
apps/backend/internal/mcp/server/settings_runtime_settings_test.go.
Use real registered tools plus domain fixtures, not only direct handler invocation.
Add domain tests for any changed persistence path, including rollback and concurrent updates.
When a SQL query changes, include SQLite/PostgreSQL behavior evidence under the existing domain test conventions.
E2E scenario
Save and clear a permitted override, observe pending restart, and reject an environment-locked or authentication flag change. Use disposable resources and mock providers. Restore user-level settings in cleanup, including after failures. Run desktop and phone separately with the managed runner and record discovered test counts.
Files likely touched
apps/backend/internal/runtimeflags/registry.goapps/backend/internal/runtimeflags/service.goapps/backend/internal/runtimeflags/handlers.goapps/backend/internal/runtimeflags/settings_catalog.go (new)apps/backend/internal/common/config/catalog.goapps/web/lib/state/slices/features/apps/backend/internal/backendapp/services.goand MCP handler composition.apps/backend/internal/mcp/server/settings_runtime_settings_test.go(new).apps/web/lib/settings-discovery/runtime-settings-contract.test.ts(new).apps/web/components/settings/runtime-settings-reconciliation.test.tsx(new): clean updates, dirty conflicts, own acknowledgements, and late replies.apps/web/lib/settings-discovery/coverage-inventory.tsand generated snapshots.- Relevant domain store subscriptions, current editor state, and locale catalogs.
- The two E2E files named in Verification.
Dependencies
Task 16 completes the preceding slice. Tasks 00 through 04 establish inventory, schemas, generic tools, and draft-recovery behavior. The sequential order avoids conflicts in shared composition and generated snapshots.
Risks
- The HTTP authorization guard does not run in MCP dispatch. A saved override is not proof that the running feature changed.
- Saved settings and active runtime state can differ. Responses must not claim an unobserved runtime change.
- Missing identity can look like an internal service caller. MCP must reject that case under enforced authentication.
Mobile contract
Reuse the current domain settings route, shared save contributor, and existing phone composition. Keep recovery inline with the existing discard action, one content scroll owner, and safe-area-aware controls. Prove touch access and no horizontal page overflow. No new modal or breakpoint layout is required.
Parallelism
sequential
Inputs
- Both system designs, especially Required domains, Mutation semantics, Relationships, and Visible results.
- Task 00's field inventory and each source contract listed above.
- Existing domain tests, profile parity tests, and nearby shipped settings E2E.
- Scoped AGENTS.md, /tdd, /mobile-parity, /e2e, and /docs-maintainer before implementation.
- /runtime-feature-flags. Existing identities and shipped defaults remain unchanged.
Results
Completed on 2026-09-09.
- Registered permitted runtime overrides using the existing typed runtime-flag registry.
- Preserved environment locks, explicit reset behavior, source provenance, and pending-restart state.
- Covered the catalog
overridemapping and adapter behavior in backend tests.