docs: add application initialization contract to user-points protocol
This commit is contained in:
@@ -176,3 +176,30 @@ JSON constraints:
|
||||
- Backend service must derive owner identity from verified auth context.
|
||||
- Client must not be trusted for `user_id`/`operator_id` ownership semantics.
|
||||
- `metadata` and `settings` must not include secrets.
|
||||
|
||||
## Application initialization contract
|
||||
|
||||
Application initialization is split into two separate concerns: deterministic seed data and dynamic notification template sync. These are intentionally decoupled to avoid non-deterministic side effects during bootstrap.
|
||||
|
||||
### Seed data (deterministic)
|
||||
|
||||
Managed by `python -m core.runtime.cli init-data` (called by `dev-migrate.sh bootstrap`):
|
||||
|
||||
- `initialize_llm_catalog()` — seeds `llm_factory` and `llms` tables with known model definitions
|
||||
- `initialize_system_agents()` — seeds `system_agents` table
|
||||
|
||||
These are idempotent and version-locked to code; they do not depend on runtime state or user data.
|
||||
|
||||
### Notification templates (declarative sync)
|
||||
|
||||
Managed by `python -m core.runtime.cli sync-notifications [flags]`:
|
||||
|
||||
- Reads notification definitions from YAML files under `backend/src/core/config/static/notification/notifications/`
|
||||
- Syncs to `notifications` table; links existing users via `user_notifications` when `--reconcile-targets` is set
|
||||
- Supports flags:
|
||||
- `--dry-run` — validate without writing
|
||||
- `--prune` — remove static notifications no longer present in YAML files
|
||||
- `--reconcile-targets` — insert `user_notifications` entries for all existing users matching each notification's `target` predicate
|
||||
- `--source-key <key>` — sync only the notification with the matching `source_key`
|
||||
|
||||
Run after migrations on fresh environments or after adding new notification YAML definitions. Not included in `bootstrap` to keep bootstrap fast and free of unintended side effects.
|
||||
|
||||
Reference in New Issue
Block a user