Quick
5df181f733
The design removes the legacy /api/v1/settings routes and the profile DTO preference fields, while AGENTS.md states /api/v1 is additive-only and removals go through Deprecation/Sunset. Read together those contradict. They do not actually conflict: v1-scope.md scopes the additive-only rule to "when the scope locks", and the scope is still open, so a removal taken now is in scope and there is no amendment process to invoke yet. But that reasoning lived only in the settings design, where nobody checking the API policy would find it. v1-scope.md now carries a pre-lock removals table naming what goes and why waiting is worse, and states the deadline the argument depends on: a removal listed there must ship before lock or fall back to Deprecation/Sunset. AGENTS.md points at the table and says to treat an unlisted removal as a mistake. Reported by CodeRabbit review on #479.
2.6 KiB
Silo v1 Scope
Status: NOT LOCKED — proposal window open.
Propose capabilities with the v1 capability proposal issue template; triage happens on the Silo v1 project.
When the scope locks, this file becomes the source of truth and will contain:
- Locked capabilities — a table of capability epics (issue links) with one-line scope statements.
- API policy — additive-only within
/api/v1(no field renames/removals, no type changes, no status-code repurposing; removals only via the Deprecation/Sunset header flow; capability endpoints for feature detection). Contract tooling: #135. - Amendment rules — after lock, this file changes only via PR with code-owner review. An amendment PR is the exception process: it must say what changes, why it cannot wait for v1.1, and what it displaces.
Until lock: treat any capability not tracked as Proposed/Locked on the project as out of scope
for feature PRs (see the scope gate in CLAUDE.md).
Breaking removals taken before lock
The additive-only rule in item 2 binds at lock. Before then a removal is in scope, and there is no
amendment to write because the amendment process in item 3 does not exist yet. CLAUDE.md states
the rule without that qualifier, which reads as a contradiction — it is not, but a removal taken
now has to be recorded here so a reader after lock can tell a deliberate decision from a violation.
Each entry names what goes, why waiting is worse, and the design that decided it. Every removal listed here must have shipped before the scope locks. One still outstanding at lock loses its justification and falls back to the Deprecation/Sunset flow like anything else.
| Removed | Release | Rationale |
|---|---|---|
String GET/PUT/DELETE /api/v1/settings…, the unknown-key extension bag, preference fields on profile/library/series DTOs |
Cross-platform settings contract, design | Replaced wholesale by the typed settings contract. Deferring past lock would mean carrying the Deprecation/Sunset surface and the untyped key bag — which lets any client invent a production setting the server stores unvalidated — through the deprecation window, which is the exact surface the contract exists to close. |
Feature-detection precedent: clients discover which metadata providers (including the
built-in NFO provider, #216) apply to a library type via
GET /api/v1/libraries/provider-defaults rather than version sniffing. New capabilities
should follow the same capability-endpoint pattern.