[vladmesh]

Card: service-template-895 — Add schema-backed core settings contract
Branch: pipeline/service-template-895 → main

What the card asks for

Goal

Implement the service-template half of Sprint B1's schema-backed product-settings core so a freshly generated backend can own validated, authorized settings through typed settings.get and settings.set operations. This card establishes the product-side contract only; it does not make the orchestrator write initial values or implement Product Brief persistence.

Context

• Sprint sprint:1420, Definition of Done, and the accepted decision at state/knowledge/projects/codegen-orchestrator/decisions/2026-08-28-module-composition-protocol.md, sections 6, 8 and 9.
• state/knowledge/projects/codegen-orchestrator/plans/2026-08-28-group-2-increment.md, Sprint B item 1.
• Existing core-user capability and spec-first backend precedent: template/services/backend/spec/users.yaml, src/controllers/users.py, src/app/grant_capability.py, and template/shared/spec/models.yaml.
• The current framework deliberately ignores legacy services/*/spec/manifest.yaml; a new manifest/settings representation must therefore be explicitly owned, parsed and validated rather than treated as an incidental domain spec.

Implementation route

Reuse the template's spec-first backend, generated contracts, SQLAlchemy/Alembic patterns, and the existing capability-gate design. Add the smallest explicit manifest/settings-schema path and no dependency, compatibility shim, transport-specific identity, env duplicate, catalogue, or fallback. This is a forward-only core addition to newly generated products; no released generated-project state is a supported legacy format for this card.

Acceptance criteria

1. A generated backend has a versioned, typed core settings.get / settings.set API contract and persistent database storage for settings; generated API/OpenAPI artifacts and the documented contract reflect it.
2. A service/module manifest can declare a JSON Schema for user-controlled settings. The template loads and validates that declaration explicitly, rejects malformed or unsupported manifest/schema input fail-closed, and keeps manifest data out of ordinary domain-spec generation.
3. settings.set validates a value against the declared schema before persistence; valid values round-trip through settings.get, while unknown keys and invalid values cannot be stored. No setting is reconstructed from prose or represented as an environment variable by this core path.
4. Settings reads and writes have an explicit authorized product-side boundary. The write authority follows the established scoped-capability pattern or an equally typed core authority, rejects absent, duplicated and invalid credentials before mutation, and does not expose secret values or credentials in schemas, generated OpenAPI, logs, or LLM-facing data.
5. The persistence and write path are idempotent for a retry of the same effective setting value and preserve isolation between distinct product users/subjects where the contract scopes values. Migration, authorization, validation, idempotency, and isolation behavior have focused tests.
6. Add/update docs/CONTRACTS.md, architecture/pipeline documentation, and the English CHANGELOG.md wherever this repository's contract-change rules require. Synchronize the framework mirror if framework source changes, and prove synchronization.
7. Run focused tests while implementing, then the required service-template broad Secretary check on the exact candidate and leave its executable receipt for the dispatcher gate. CI must cover the generated/copier surface appropriate to changed template files.

Out of scope

• Orchestrator Product Brief storage, architect coverage accounting, and orchestrator initial-setting writes.
• jobs.fire / job_fired, scheduler implementation, module catalogue, event-digest, telegram-reader, web adapter, or admin conversation history.
• Any deployment, migration of existing pinned products, compatibility shim, or second source of authorization/configuration.

What the worker reports

Implemented and committed eac57c8 (Add schema-backed core settings contract).

Delivered:

• versioned typed settings.get / settings.set contracts, generated routers, OpenAPI, persistence migration, idempotent scoped repository, and focused backend tests;
• explicit services/<service>/manifest.yaml v1 loading and fail-closed Draft 2020-12 settings-schema validation, separate from ignored legacy domain manifests, with generated schema registry and framework mirror synchronization;
• one write-only scoped capability boundary that rejects absent, duplicate, malformed, and invalid credentials before mutation without publishing it in OpenAPI;
• contract, architecture, generated-project, environment-contract, and English changelog documentation.

Focused generated-backend candidate: make setup && make typecheck && make lint && make tests backend passed (26 tests). The one completed broad check was:

python3 -m secretary check broad --reuse --module pytest --module-arg tests/unit --module-arg tests/tooling --module-arg tests/copier --module-arg=-m --module-arg "not slow"

Receipt state/checks/broad-3b1ac81f470f6199.json is usable for this exact content (tree_sha b14031110a49d3acf22e034ec9150466dc56ee78): 292 passed, 13 deselected, exit 0, 138.40s; its process imported framework from this workspace. An earlier wrapper invocation ended without an intact receipt and therefore attested no completed suite; the reported invocation was the single completed broad run.

make check-sync passed. git status --porcelain is empty.

---

Opened by the secretary CI gate so that the pull_request workflow runs. Title and body are built from the card and the worker's done report.