@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.5

package/CHANGELOG.md

@@ -1,5 +1,180 @@
 # @marinoscar/platform-contract
 
+## 0.1.0-next.5
+
+## 0.1.0-next.4
+
+### Minor Changes
+
+- a426fd8: Open the AI capability and operation vocabularies, add a custom-operation port, richer transcription results and per-feature usage (PP-14.17). API: `registerAiCapability` and `registerAiOperation` (the 14 built-in capabilities and the usage operations register through them; `AiCapability` and `AiUsageOperation` become `Builtin | (string & {})`; `AI_CAPABILITIES` stays as a deprecated alias of `BUILTIN_AI_CAPABILITIES`); `AiProviderAdapter.operations` and `AiService.forUser(...).run(operationId, input)` run an app's operation through the same gate pipeline as a built-in port (kill switch, schema-validated input and output, model and capability gates, key policy, rate limits, one usage row, one span), never logging or recording its input or output and refusing an output or an error that carries the key; `AiTranscriptionResult.extras` (speaker-labelled segments, language and any JSON, at most 64 KiB, dropped when malformed) reaches the run output, and a transcription's `providerOptions` is bounded to 4 KiB and never logged; `GET /api/admin/ai/capabilities` (`ai_config:read`) lists the vocabularies; the usage reports take a `feature` filter and group by `feature` and `operation`; `AiModule.forRoot({ pricing })` binds the `AI_PRICING` port and the admin and organization reports then carry `priced` and a `cost` per bucket. The provider conformance kit gains `operations.*` scenarios, `FakeAiProvider` gains `operations` and `transcriptionExtras`, and `ai-secret-egress` covers the new route and fields. Contract: `AI_CAPABILITY_ID_PATTERN`, `AI_OPERATION_ID_PATTERN`, `AI_FEATURE_ID_PATTERN` and the capability, operation and cost schemas. Web: `registerAiPlaygroundMode` (subpath `/ai/ui/playground-modes`; the six built-in modes register through it, DOM unchanged; the fixed `AI_PLAYGROUND_MODES` tuple and `AiModePlaceholder` are removed), `useAiCapabilities` and `registerAiCapabilityLabel` (the Models page filter and the override dialog list an app's capabilities), Feature and Operation breakdowns, a Cost tile and column on a priced usage report, and speaker-labelled transcripts. DB: migration `0035_ai_usage_feature` adds the nullable `feature` column to `ai_usage_events` and `ai_runs` and the `(org_id, feature, created_at)` index on usage (both tables are row-level-security tables, so the migration runs in the `app.rls_bypass` transaction form); apply it with `npm run db:sync`, then `prisma:migrate`. Back-compat: every existing route, shape and id is unchanged; rows written before the column have no feature. The OpenAPI document shows a pattern where the models list's `capability` query and a provider's `supportedCapabilities` showed an enum.
+- b2df59a: Let an app or package add an AI provider (PP-14.6, #924): `registerAiProvider(AiProviderDefinition)` of `@marinoscar/platform-api/ai`, backed by the `ai-provider` pluggable kind. A definition carries the provider's id, label, Nest module, zod `settingsSchema` and `defaults` for its non-secret settings, `requiresKey`, `requiresBaseUrl`, `help` and `sdkPackages`; the five built-ins register through the same function. `AiModule.forRoot({ providers })` takes any registered id (default: every registered definition) and imports each definition's `module`; the closed `AiProviderModuleId` union (now `string`) and `PROVIDER_MODULES` are gone.
+
+  `ai.providers` is a record keyed by provider id (`aiProviderIdSchema`, `aiProviderSlotSchema`; `BUILTIN_AI_PROVIDER_IDS`, with `AI_PROVIDER_IDS` kept as a deprecated alias). The namespace reads, merges and validates each slot with its provider's `settingsSchema`: an unregistered id is `400 AI_UNKNOWN_PROVIDER` on write and dropped with one warning on read, so removing a provider never bricks the row. The stored shape of the five built-ins is unchanged. `AI_PROVIDER_SETTINGS_FIELDS` and `PROVIDERS_REQUIRING_BASE_URL` are replaced by the definition; `providerRequiresKey(slot, providerId?)` takes the provider id.
+
+  `GET /api/admin/ai/config` gains `descriptors` (one `PluggableDescriptor` per registered provider) and, per provider, `settings`, `requiresBaseUrl` and `help`; `settingsFields` is now `string[]`. `createAiRuntimeHarness` takes `extraProviders`, `extraAdapters` and `extraProviderSettings`; `ai-no-sdk-leak` takes `providerDirs` and bans the registered definitions' `sdkPackages` outside them; the provider conformance kit checks the provider id pattern (no underscore). `describeConfigField` unwraps `default` and `prefault`.
+
+  Web: `registerAiProviderCard(id, Component)` (`@marinoscar/platform-web/ai/ui`, and the new `/ai/ui/provider-cards` subpath) chooses the component that draws a provider on the admin AI page. The five built-ins register their bespoke cards through it (markup unchanged); any other provider is drawn by `AiGenericProviderCard` from the descriptor the API serves: a switch, `PluggableConfigForm` for its settings and a write-only key with the deployment-key actions, saved as `{ enabled, ...settings }`. The endpoint rule and help text come from the API (`requiresBaseUrl`, `help`) instead of a switch on the provider id; `AiAdminProvider` gained `settings`, `requiresBaseUrl` and `help`, `AiAdminConfig` gained `descriptors`, and `AiProviderSettingsField` is now `string`.
+
+- 823ec07: Add the AI slice: `@marinoscar/platform-api/ai` (`AiModule.forRoot` with the `AI_SYSTEM_PRISMA`, `AI_OBJECT_STORE` and `AI_METRICS` host ports, `AiService.forUser(userId, { orgId, feature })` and the gate pipeline, the OpenAI, Anthropic, Gemini, Azure OpenAI and OpenAI-compatible adapters with their SDKs confined to `ai/providers/`, the model catalogue, the `ai` settings namespaces with a tighten-only org layer, the organization key tier (`/api/admin/ai/org-keys`, `org_ai_config:read`/`write`) and `deploymentKeyServesOrgs`, per-organization daily caps (`limits.perOrg`) and usage (`/api/admin/ai/org-usage`, `groupBy=org`), `registerAiFeature` and `GET /api/ai/features`, `AI_TARGET_RESOLVER`, `UserAiKeysService.importKey`, the `ai-outputs/` key prefix registered with the storage slice, and at `/ai/testing` the fake provider, runtime harness, adapter conformance kit and `runOrchestrationBoundarySuite`), `@marinoscar/platform-contract/ai` (the `ai` namespace schemas, `orgAiSettingsSchema`, `tightenAiPolicy`, the org-key and feature shapes) and `@marinoscar/platform-web/ai` (`useOrgAiKeys`, `useOrgAiPolicy`, `OrgAiKeysPage`).
+- 6a7af76: Add the email slice: `@marinoscar/platform-api/email` (`EmailModule.forRoot`, the SES and SMTP transports with inline attachments, the `email` settings row on `SystemSettingsRowStore`, the template registry with `EmailTemplateDataMap` augmentation and explicit overrides, the layout theme and brand-mark slot, the safe-HTML helpers, the `email` conformance suite at `/email/testing`), `@marinoscar/platform-contract/email` (the admin route DTOs) and `@marinoscar/platform-web/email` (`useEmailSettings`, `EmailSettingsPage`); `SystemSettingsRowStore.write` accepts `auditMeta`, and `PlatformViewer` an optional `email`.
+- deeb8b5: Add the notifications slice: `@marinoscar/platform-api/notifications` (`NotificationsModule.forRoot`, the event, channel and template registries with open channel ids and `registerNotificationChannel`, `NotificationsService` with org-aware policy, the `notifications` system namespace with an org layer that only tightens, runtime Web Push (VAPID) configuration on `SystemSettingsRowStore`, broadcasts with `targetOrgId` and the org-scoped `org_broadcasts:*` pair, the SSE stream on `NOTIFICATIONS_EVENT_BUS`, the email channel forwarding template attachments, the `notifications` conformance suite at `/notifications/testing`), `@Auth({ anyPermissions })` in the identity slice, a `SystemSettingsRowStore` row key that admits camelCase (`webPush`), `@marinoscar/platform-contract/notifications` (the wire shapes, `BROADCAST_CHUNK_SIZE`), `@marinoscar/platform-web/notifications/{headless,ui}` (`configureNotificationsWeb`, `NotificationProvider`, `usePushSubscriptionSync`, `NotificationBell` with slots, the banner and the four pages, the service-worker helpers `registerNotificationServiceWorkerHandlers`, `handlePushEvent`, `handleNotificationClick`, `handlePushSubscriptionChange`), any-of card permissions in the settings hub (`SettingsCardDef.permission: string | readonly string[]`, `cardPermissionGranted`), and the platform migration `0032_add_broadcast_target_org` (`notification_broadcasts.target_org_id`).
+- a20f306: Move the retention engine into the slices that own the data. `@marinoscar/platform-api/jobs` now exports the one shared `purgeInBatches` / `runRetentionPolicyPurge` loop (the duplicate under `ai/runtime` is gone), the `RetentionPurgeRegistry` a purge handler declares its `retention.*` policy in, the 01:00 enqueue-only `RetentionPurgeTask`, the `retention` settings namespace (`RETENTION_SYSTEM_SETTINGS`, registered by `JobsModule.forRoot()` unless the app's manifest lists it) and `AuditEventsPurgeHandler`; `@marinoscar/platform-api/notifications` provides `notifications.inbox.purge` and `notifications.deliveries.purge`; `ai.runs.purge` uses the shared loop; `@marinoscar/platform-contract/jobs` carries the `retention` schemas. Job type strings and the OpenAPI document are unchanged.
+- 2be194f: Add `@marinoscar/platform-contract/android-app` (trusted apps, assetlinks, APK releases, download links, the Android test notification) and the push subscription `platform` field with `PUSH_SUBSCRIPTION_PLATFORMS` and `ANDROID_APP_NOTIFICATION_CHANNEL_ID` in `/notifications` (#746).
+- 0b9962b: Add `@marinoscar/platform-contract/exports` (#744): the `/api/exports` request and responses, the cell, column and request-field shapes a source declares, and the JSON export file envelope (`schemaVersion: 1`).
+- 606d231: Add `@marinoscar/platform-contract/identity` (#727): `AUTH_ERROR_CODES` as the single source of the sign-in failure codes (the API and the web app both import it), the `/api/auth/me`, token, personal-access-token and device-flow response schemas, and the request schemas of switch-org, personal access tokens, the device flow and organization administration, moved verbatim from the API's DTO files. Zod-free constants for the error codes, tenancy modes, org roles and statuses. Stability: `stable`. No wire or OpenAPI change.
+- 0426848: Add `@marinoscar/platform-contract/jobs` and `/nodes` (#734): the admin job routes' list query and row (with the new `orgId`), summary, insights and bulk-action schemas, and the worker-node control plane, data plane, per-job secret and node credential request schemas, moved from the API slices' `dto/` files with their comments, plus the zod-free status, reason, window and node bounds. `@marinoscar/platform-api/jobs` and `/nodes` wrap them with `createZodDto` and still re-export every schema under its old name.
+- 077c0c0: Add the `./onboarding` subpath (#745): the stored `onboarding` user-settings namespace and its PATCH branch, the `GET /api/onboarding` query and response, and the activation metrics query and response, as zod schemas, types and zod-free constants.
+- fc11b22: Add the `./settings` subpath (#733): the core user-settings fields (`theme`, `profile`), the `dataTables` and `navigation` user namespaces, the system and user settings response bases, and the `/api/org-settings` request and response schemas. Moved verbatim from the reference app; no wire change.
+- 685657b: Add the grant shapes to `@marinoscar/platform-contract/sharing` (#729): the create, update, list and "shared with me" schemas of `/api/grants` (user and group grantees), the link-grant shapes #730 builds on (`linkGrantCreateSchema`, `linkGrantViewSchema`, `publicLinkResolutionSchema`), the zod-free `GRANT_GRANTEE_KINDS`, `ACCESS_SCOPES`, `SHARED_WITH_ME_VIA`, `SHARING_IDENTIFIER_PATTERN`, `LINK_TOKEN_HEADER` (`x-link-token`) and `buildLinkUrl(appUrl, token)`, which puts the token in the URL fragment (`/s#<token>`).
+- 5d0dd86: Add the `./sharing` subpath (#728): the zod schemas and types of the `/api/groups` routes (groups, members, invites, the caller's own invites), the zod-free `GROUP_ROLES`, `GROUP_INVITE_STATUSES` and `SHARING_LIMITS`, and the flat pagination shape.
+- 03eeaab: Link-share wire shapes in `@marinoscar/platform-contract/sharing` (#730): `issuedLinkGrantSchema` (the create response, carrying the token once), `linkGrantListSchema`, `LINK_TOKEN_PREFIX` and `LINK_TOKEN_PATTERN`; `linkGrantCreateSchema` takes an optional `role` (the weakest link role) and `reuseActive`, and `updateGrantSchema` an optional link `label`.
+- 17d6ed1: Add `@marinoscar/platform-contract/storage` (#736): the `storage` system-settings namespace schemas (stored value, partial, PUT and PATCH branches, GET branch) with the compile-time `StorageSettingsCarriesNoSecret` proof, the objects API and status shapes, and the storage-config admin bodies and results, plus the zod-free provider, status and missing-field lists.
+- f80189d: Add the pluggable-kind primitive (PP-14.5, #923). `@marinoscar/platform-api/core` gains `definePluggableKind` (one registry of implementations per kind, each with its own zod settings schema, defaults, declared secrets and `build`; settings stored as a record keyed by implementation id with `parseSettings`, `mergeSettingsRecord` that rejects unknown ids on write and `readSettingsRecord` that drops them with one warning on read; `describe` and `describeAll` returning the descriptor a generated form renders, with presence flags for secrets), `PluggableUnknownError`, `PluggableSettingsError` and `describeConfigFields` (the organization settings field description, generalised, adding `label` and `help`). The new `@marinoscar/platform-api/core/testing` entry exports `describePluggableKindConformance`. `@marinoscar/platform-contract/settings` gains `configFieldSchema` (with a write-only `secret` kind), `pluggableDescriptorSchema`, `CONFIG_FIELD_KINDS` and `PLUGGABLE_ID_PATTERN`. `orgSettingsFieldSchema` and the organization settings response are unchanged. `@marinoscar/platform-web/settings/ui` gains `PluggableConfigForm` (the generated configuration form of one implementation: Switch, select, text and number inputs, a note for `other`, a write-only `SecretField` for `secret`, optional `slots`) and `@marinoscar/platform-web/settings/headless` gains `usePluggableConfigForm` (`value`, `secrets`, `dirty`, `setField`, `setSecret`, `reset`, `payload()` which omits untouched secrets). The settings web slice now depends on the credentials slice.
+- 115705f: Add the credentials slice (#735). platform-api: the `./credentials` subpath with `CredentialsModule`/`CredentialsService` (the deployment store), `UserCredentialsModule`/`UserCredentialsService` (a user's own keys) and the new `OrgCredentialsModule`/`OrgCredentialsService` (an organization's keys in `org_credentials`, under row-level security, encrypted under `org:<orgId>:<purpose>`), `UserCredentialResolver.resolve(userId, purpose, name?, { orgId })` (user, then the purpose's `fallback` of org and system, then none), the purpose registries `registerCredentialPurpose` and `registerUserCredentialPurpose` (writes to an undeclared purpose throw), `CREDENTIALS_MODEL_OWNERSHIP`/`CREDENTIALS_USER_OWNED_MODELS`, and `./credentials/testing` with the `credentials` conformance suite and `withCredentialPurposes`; core gains `orgCredentialPurpose` and `ORG_CREDENTIAL_DOMAIN_PREFIX`; telemetry exports `TELEMETRY_GREPTIME_CREDENTIAL_PURPOSE`. platform-web: `./credentials/headless` (`savedSecretHelperText`, `secretForSubmit`) and `./credentials/ui` (`SecretField`). platform-contract: `./credentials` (`credentialInfoSchema`, `userCredentialInfoSchema`, `orgCredentialInfoSchema`, `CREDENTIAL_TIERS`, `CREDENTIAL_SOURCES`, `SECRET_BEARING_KEYS`).
+- d1d1258: The database backup slice has three new extension points (PP-14.12, #930).
+
+  Backup target. Where an archive is written is now a port: `DB_BACKUP_TARGET` (a `BackupTarget`: `id`, `label`, `openWrite(key, meta)` returning `{ stream, done }`, `openRead`, `delete`, an optional `list`, `isConfigured()` and `describe()`), bound with `DbBackupModule.forRoot({ target, mirrorTargets })`. The default adapter (`StorageBackupTarget`) wraps the deployment's `STORAGE_PROVIDER`, so a deployment that binds nothing behaves exactly as before. The archive is still never buffered: `pg_dump` streams through the checksum meter into the sink, and the runner awaits both the sink's `done` and the dump's exit code. The `database-backups/` key prefix rule stays in the server. After the primary archive is written and verified, the same `db.backup.run` job copies it to every mirror target (read back from the primary, written through the mirror's sink, read back from the mirror and compared by sha256, deleted on a mismatch); a mirror failure never fails the run. Each copy is recorded as an `audit_events` row (`db_backup.mirror.completed` / `db_backup.mirror.failed`), so no migration is needed, and the new `backup.mirrors` Doctor check warns when a mirror's latest copy failed or has never run. Retention deletes the same key from every mirror. `describeBackupTargetConformance` (`@marinoscar/platform-api/db-backup/testing`) is the kit every target runs: streaming without buffering, a failing sink rejects `done`, read-back equals write, delete is idempotent, an unconfigured target says so.
+
+  Schedule policy. `frequency` gains `'cron'` with a `cron` field (five fields: `*`, numbers, ranges, steps and lists; month `*`; at most one of day-of-month and day-of-week restricted; at least one hour between runs, enforced when the setting is saved and when the schedule is read), evaluated in the policy's timezone with the same DST handling as the other frequencies. `retention` is now `{ count?, maxAgeDays? }`; `retentionCount` stays as an alias that is read and written in step with `retention.count`, so existing settings rows, API clients and the web page keep working. Retention deletes a completed archive when it is beyond either bound, and never the newest completed one.
+
+  Restore gates. `registerRestoreGate({ id, label, kind, check })` adds a pre-flight gate from an app or a package at import time; the eight built-in gates register through the same function (`BUILTIN_RESTORE_GATE_IDS`). Gates run in registration order (built-ins first), fail closed (a gate that throws or exceeds 10 seconds is a block), and an app gate (`kind: 'app'`) that fails is a hard block that cannot be overridden. `describeRestoreGateConformance` is the kit every gate runs: it answers within the bound, writes nothing to its context, is repeatable, and evaluates to a pre-flight row. The pre-flight stays read-only: no gate creates, drops or renames anything, and the cluster admin connection stays outside the Prisma pool.
+
+  Events. `db_backup.run.completed` and `db_backup.restore.completed`, each with `{ runId, status, targetId, sizeBytes, durationMs }`, are emitted on the event bus after the run settles and outside any transaction.
+
+  Invariants unchanged: every dump and restore still carries both `--enable-row-security` and `PGOPTIONS=-c app.rls_bypass=on` (`buildPgDumpArgs` and `buildPgRestoreArgs` are untouched), and all work stays inside the registered `db.backup.run` job.
+
+  Migration notes: `RESTORE_GATE_IDS` is now a deprecated alias of `BUILTIN_RESTORE_GATE_IDS`, and a restore gate id is an open string (`RESTORE_GATE_ID_PATTERN`) rather than a closed union; a pre-flight row can carry `kind: 'app'`; `frequency` can be `'cron'`, so code that switches over it must handle the new member; the stored `cron` and `retention` fields are optional (the defaults are unchanged); `DbBackupTx` gains `auditEvent.findMany`, so a hand-built double of that structural type needs it; the runner, retention service, restore service and pre-flight service take trailing optional constructor parameters, so code that constructs them by hand keeps working; node offload is withheld while an app binds its own primary target (only the storage-backed adapter can be read by a node).
+
+  Web: `DbBackupPage` accepts `slots.Sections` (an app's own sections below the packaged ones; the markup is identical when it is not passed), the policy panel renders a cron field for `frequency: 'cron'`, and the restore dialog lists app gates. Contract: `backupRetentionSchema`, `restoreGateIdSchema`, `BACKUP_CRON_*` limits, the event name constants and payload types, and `BackupMirrorResult`.
+
+- b46725d: Add the database backup and restore slice: `@marinoscar/platform-contract/db-backup` (the wire shapes and the `databaseBackup` namespace), `@marinoscar/platform-api/db-backup` (`DbBackupModule.forRoot` with the deployment-mode restore gate, the `RestoreCarryOver` registry, the `rls_bypass` pre-flight gate and the `database-backups/` key prefix) and `@marinoscar/platform-web/db-backup` (the admin page, its hook and client, and the admin section entry).
+- e6acb4b: Email transports are pluggable (PP-14.8, #926). `registerEmailTransport` adds a way of sending mail (SendGrid, Postmark, a log) from an app or a package: its own settings schema, declared secrets (stored encrypted at the credential purpose `email_<id>`, never in settings or the environment), and `build`, which returns an `EmailTransport` (`send`, optionally `verify` and `destroy`). Extend `BaseEmailProvider` to inherit the never-throw guarantee, secret redaction and rate-limit classification. `ses` and `smtp` are transports registered through the same function and still wrap `SesEmailProvider` and `SmtpEmailProvider` unchanged. `EmailTransportResolver` (provided and exported once by `EmailModule`) resolves the transport the settings' `provider` names; `EmailNotificationChannel` and the admin "Send test email" depend on it instead of the concrete SES and SMTP classes, so a registered transport is used by both. The Doctor check, the network-egress view and the test email name a transport by what it registers (`label`, `summary`, `missing`, `egressCapability`, `egressHosts`). `describeEmailTransportConformance` (`@marinoscar/platform-api/email/testing`) is the kit every transport runs: `send` never throws, no secret or message content in error text, attachments and headers passed through, throttles classified.
+
+  The `email` settings row stores `provider` (a transport id) and a `transports` record validated per transport. A row stored before this release loads unchanged (its `sesRegion`, `sesAccessKeyId`, `smtpHost`, `smtpPort`, `smtpUseTls` and `smtpUsername` become `transports.ses` and `transports.smtp`, field by field, and are rewritten in the new shape on the next save), the flat fields stay accepted on `PUT /api/email-settings` as aliases and published as a deprecated read view, and `smtpPassword` / `sesSecretAccessKey` stay accepted beside the new `secrets` record. A stored `provider` that names a transport nobody registers no longer makes the row unreadable: the send and the Doctor report it.
+
+  Contract: `BUILTIN_EMAIL_PROVIDER_KINDS` (`EMAIL_PROVIDER_KINDS` stays as a deprecated alias), `EMAIL_TRANSPORT_ID_PATTERN`, `emailTransportIdSchema`; `EmailProviderKind` widens to `string`; the response gains `transports`, `descriptors` and `secretStatuses`; the PUT body gains optional `transports` and `secrets`. The `email` contract slice now depends on the `settings` slice.
+
+  Migration notes for code that builds these by hand: `EmailNotificationChannel` and `EmailTestSendService` take an `EmailTransportResolver` instead of `SesEmailProvider` and `SmtpEmailProvider`; `SesEmailProvider` and `SmtpEmailProvider` take a `Pick<EmailSettingsService, 'get'>` and a `Pick<CredentialsService, 'getSecret'>`; the egress view lists transports in registration order (`email.ses`, `email.smtp`, then the app's).
+
+  Web: `registerEmailTransportPanel(id, Component, { validate, toForm, toInput })` (`@marinoscar/platform-web/email/ui`, and the new `/email/ui/transport-panels` subpath) chooses the form the admin email page draws for a transport. The page lists one radio per descriptor the API serves; the built-in `ses` and `smtp` transports register their bespoke forms through the registry (markup unchanged); any other transport is drawn by `EmailGenericTransportPanel` from its descriptor (`PluggableConfigForm`, with write-only secrets), so an app that adds a transport with `registerEmailTransport` needs no web code. The page saves `{ provider, enabled, fromAddress, fromName, transports: { <selected>: settings }, secrets: { <selected>: { <name>: value } } }`, and completes a response from an API that predates the transports from its flat fields.
+
+- 2c4bf2c: Slots for the identity and sharing pages, the login layout, and the shell's navigation and themes (PP-14.25, #943).
+
+  API: `registerCurrentUserExtension({ id, resolve(userId, ctx) })` and `registerUserListExtension({ id, resolve(userIds, ctx) => Map })` of `@marinoscar/platform-api/identity` add bounded JSON of the app's own to `GET /api/auth/me` and to each row of `GET /api/users` under `extensions.<id>`. The list resolver is batched: one call per request with the ids of the page, a `Map` keyed by user id, so a list never costs a query per row. Every contribution is checked (plain JSON, at most 5 levels, 4 KiB on `/auth/me` and 1 KiB per list row, no secret-named key such as `token`, `apiKey` or `clientSecret`, no credential-looking value such as a JWT or a `pat_` token) and every extension runs isolated under its own timeout: a throw, a timeout or a refused contribution skips that extension and logs a warning with its id, and never fails the request. `checkUserExtensionContribution`, `resolveCurrentUserExtensions` and `resolveUserListExtensions` are exported. OpenAPI: `CurrentUserDto` gains an optional `extensions`; the rows of `GET /api/users` reference the new `UserListItemDto` (`UserResponseDto` plus an optional `extensions`); nothing changes on the wire while no extension is registered.
+
+  Contract: `currentUserSchema` gains an optional `extensions`; new `userExtensionsSchema`, `UserExtensions`, `USER_EXTENSION_ID_PATTERN` and `USER_EXTENSION_LIMITS`.
+
+  Web: `UsersPage`, `UserList`, `OrganizationPage`, `OrgMembersPanel`, `OrganizationsPage`, `UserTokensPage`, `ActivateDevicePage`, `LoginPage`, `AuthCallbackPage`, `GroupsPage`, `GroupDetailPage` and `PublicLinkPage` take the packaged-page slot contract (`PageSlotsBase`) and leave the exempt list; the pages that draw rows add the table slots (`Columns` on the users table; `RowActions`, `DetailPanel` and `Toolbar` on the member and organization lists, which are cards, not tables). `UsersPage` adds an append-only `Tabs` slot (the Users and Allowlist tabs stay; the Settings UI rule 2 still holds), `GroupDetailPage` adds `MemberRowActions` and `Tabs`, `ShareDialog` adds `Sections` (both ends) and `Footer`, and `LoginPage` finishes its layout slots with the contract's. `AuthUser.extensions`, `UserListItem.extensions`, `useCurrentUserExtension` and `userExtension` read what the API added. `ShellDestination` gains `badge`, `group`, `external` (an `http(s)` URL opened in a new tab; any other scheme is not drawn) and `onClick` (cancel the navigation with `preventDefault`) on the rail, the bottom bar and the user menu; `ShellBottomNav` gains `maxItems` (default 4) with a More sheet for the rest (a navigation with four or fewer visible destinations renders what it did); `ShellThemeMode` and `ShellThemes` are open, `registerThemeMode({ id, label, theme })` adds a theme mode, and the `applyTheme` host port and `useUserSettings` hand a stored theme id to the app when the settings document lists it in `themeOptions` (pairs with `registerThemePreference`, #939). The five breakpoint gates did not move. A `Header` slot written against the old props of the groups and group pages keeps working; `LoginPage.slots.Title` keeps working and `Header` replaces it.
+
+- c6f97da: Let an app or package add a sign-in provider (PP-14.9, #927): `registerAuthProvider(AuthProviderDefinition)` of `@marinoscar/platform-api/identity` now completes a full login. A definition supplies its Passport strategy as `strategy` + `guard` classes (Google) or as `createStrategy(ctx)`, built on every sign-in request from the credential store (purpose `auth_<id>`, `authCredentialPurpose`), plus `label`, `mode` (`redirect` default, or `custom`), an optionally asynchronous `isEnabled(config, ctx)`, `mapProfile`, `linkExistingByEmail`, `egressHosts` and `doctorRemedy`. `AuthProviderRegistration` is the same type under its old name: a registration written as `isEnabled: (config) => ...` is unchanged, and `strategy` and `guard` became optional (one of that pair or `createStrategy` is required).
+
+  `AuthService.completeExternalLogin(ExternalProfile)` runs the shared sign-in for any provider (`handleGoogleLogin` maps the Google profile and runs the same path with Google's rules; tokens, cookie attributes, redirects, events and metrics are unchanged). The slice mounts `GET /api/auth/:providerId` and `/callback` for every registered `redirect` provider (Google keeps its own routes; new in OpenAPI, reachable during a maintenance window), and exports the browser ending as `respondToSignIn`, `setRefreshTokenCookie`, `buildSignInSuccessRedirectUrl`, `REFRESH_TOKEN_COOKIE` and `REFRESH_TOKEN_COOKIE_OPTIONS`; the refresh cookie and its rules are unchanged. The callback no longer logs the redirect URL, which carried the access token.
+
+  Safety rules of the generic path: a profile with no address or an unverified one is refused (`access_denied`) before any lookup; a new provider is never linked to an existing user by address (matched case-insensitively) unless its definition declares `linkExistingByEmail`, which means "trusted to vouch for the address" (Google does, as it always did), otherwise that sign-in is refused; the same flag gates the `INITIAL_ADMIN_EMAIL` allowlist bypass and the first administrator's grant, so any other provider is allowlist-only; optional `pictureUrl` (https, at most 2048) and `displayName` (at most 255) are dropped when out of bounds; the ids `jwt` and `session` are reserved and a `createStrategy` strategy is registered with Passport as `auth-provider:<id>`; `createCookieStateStore` gives a `passport-oauth2` strategy login-CSRF `state` without a session plugin (`state: true` without a store throws on every sign-in here); the route overwrites `ExternalProfile.provider` with the serving definition's id; `ExternalProfile.raw` is never logged or stored.
+
+  `IdentityModule.forRoot({ signInPolicy })` binds a `SignInPolicy` (`IDENTITY_SIGNIN_POLICY`): `beforeLogin(profile, ctx)` returns `{ allow: true, roles? }` or `{ allow: false, reason }`, runs for every provider after the allowlist and before any write, maps roles onto a NEW user only, and fails closed when it throws. `IDENTITY_AUTH_CREDENTIALS` binds the credential store a provider reads (unbound, every secret is absent). New events `identity.login.succeeded` (`{ userId, provider, isNewUser }`) and `identity.org.created` (`{ orgId, createdBy }`); `identity.user.created` `source` is now the provider id. The Doctor's `auth.providers` check lists every registered provider with its `doctorRemedy`, and the egress inventory reads `egressHosts` from the definitions. `describeAuthProviderConformance` of `@marinoscar/platform-api/identity/testing` is the provider kit; `createStubIdentityHost` takes `authCredentials`.
+
+  Contract: `authProviderSchema` gains the optional `mode: 'custom'`, which `GET /api/auth/providers` sends only for a provider that owns its flow; a redirect provider's entry is unchanged. Web: `login(id)` calls the `start()` of the look registered with `registerAuthProvider` for a `custom` provider instead of navigating; `LoginPage` gains `BeforeProviders` and `AfterProviders` slots (props `{ providers, login }`); `AuthCallbackPage` reads the provider to retry from its `provider` prop, a `:provider` route segment, or the provider the sign-in started with (`lastAuthProvider`), validated as a provider id, before falling back to `google`; `AuthProviderInfo` gains `mode`. `AUTH_ERROR_CODES` stays closed.
+
+- 8a0f3b9: Open the jobs and nodes vocabularies to an app (PP-14.19). Jobs: `registerRetentionPolicy` puts an app table on the nightly retention (the `retention` settings namespace is composed from the registry: schemas, defaults, merge and policy-by-policy read-compat; the platform's four keep their order and defaults, and the enqueue-only `RetentionPurgeTask` enqueues one purge per enabled policy whose handler is mounted); `registerJobReason` opens `jobs.reason`, with `reasonLabel` on the admin job row. Migration `0034_open_job_reason` turns `jobs.reason` from the `JobReason` enum into `TEXT`, keeping every stored value (apply it with `npm run db:sync`, then `prisma:migrate`; the table is rewritten under a short lock); `JobReason` becomes `BuiltinJobReason | (string & {})` and the contract's `reason` a pattern (`jobReasonSchema`), so the OpenAPI document shows a pattern where it showed an enum. Nodes: a heartbeat may carry `vitals.extra` (at most 16 numeric keys), `registerNodeVital` words them in the vitals dialog, which also lists the node's reported capabilities; relayed spans may be named `job.app.<name>` with attributes registered through `registerNodeSpanAttribute` (emitted as `job.app.<key>`), and a span that fails validation is now dropped and counted instead of failing its whole batch with a 400. CLI: `registerJobRequirement` and `registerProbedBinary` (with `versionArgs`) are exported from `@marinoscar/platform-cli/node` and used by the startup self-test and `node doctor`; `JobExecutor.vitals()` feeds `vitals.extra`. Back-compat: with only the built-ins nothing served changes; `JOB_REASONS` and `RETENTION_POLICY_KEYS` remain as deprecated aliases of `BUILTIN_JOB_REASONS` and `BUILTIN_RETENTION_POLICY_KEYS`. Upgrade the API before the nodes: an API that predates `vitals.extra` answers a heartbeat that carries it with a 400, and the CLI then stops sending vitals for the process.
+- aeace4a: Add the worker-node admin response schemas to `@marinoscar/platform-contract/nodes` (`adminNodeSchema`, `adminNodeCredentialSchema`, `nodeCredentialListItemSchema`, `nodeCredentialCreatedSchema`, `NODE_STATUSES`, `NODE_HEALTHS`) that the API's Swagger classes now implement (#881), and add `@marinoscar/platform-web/nodes` (`/nodes/headless`, `/nodes/ui`): the fleet and credential client, hooks, adapters and the Worker Nodes page, which `@marinoscar/platform-web/jobs` re-exports for compatibility.
+- fce5417: Make an app's notification channel (Slack, SMS, Teams, a webhook) first-class (PP-14.10, #928). `NotificationChannelSender.resolveRecipient(recipient, context)` resolves a destination asynchronously and returns `{ to, display }`: `to` goes to `deliver`, the redacted `display` is what the delivery row's `recipient` stores. `resolveTo` still works and is now optional (a sender has one of the two). `context.handle()` reads the app's `RecipientHandleSource` (`handleFor(userId, channelId)`), bound with `NotificationsModule.forRoot({ recipientHandles })` to the new `NOTIFICATION_RECIPIENT_HANDLES` token. `forRoot({ pushPayload })` adds allowlisted extras (`actions`, `icon`, `badge`, `urgency`, `tag`) to a Web Push payload; the service worker shows them. `registerChannelTemplate` (and `registerNotification({ channelTemplates })`) is a registry of per-channel renderers validated at registration; `renderChannelPayload` reads one from `deliver`. `NotificationChannelDef` gains `criticalCapable`, `broadcastDefault` and `rendersRawData`. `describeNotificationSenderConformance` joins `@marinoscar/platform-api/notifications/testing`, and the `notifications` conformance suite gains a `channel-templates` case.
+
+  The `notifications` system namespace (and its org layer) gains an optional `channels` record, `{ <channelId>: { enabled } }`: a switch per channel, sparse, an absent channel is enabled. `browserEnabled` stays the browser channel's spelling and `channels.browser.enabled` is its alias (a write of either sets both; the stricter wins on read), so stored rows and old clients load unchanged. `policyChannels` applies the switch to every channel; a `mandatory` event keeps its `browser` row but is no longer exempt from another channel's switch. A broadcast over a channel an administrator switched off gets a warning.
+
+  `GET /api/notifications/channels` (any signed-in user) serves every registered channel (`notificationChannelDescriptorSchema`: label, `userConfigurable`, `criticalCapable`, `broadcastCapable`, `broadcastDefault`, `order`). The critical-broadcast rule reads "a channel flagged `criticalCapable`" (`browser`) and moves from `createBroadcastSchema` to the API's registry check. The `push` channel's label is `Push`. `AndroidAppNotificationChannel` takes the push payload hook as its third constructor argument (before the sender registry). OpenAPI: one new route and optional fields only.
+
+  Web: the broadcast composer, the preferences matrix and the admin Notifications page draw channels from the descriptors (`useNotificationChannels`) instead of `CHANNEL_ORDER`, `DEFAULT_CHANNELS` and `CHANNEL_LABELS`; with only the platform's channels the markup is unchanged (a recorded-DOM snapshot test). The admin page gains one switch per app channel, `UserNotificationsPage` takes `channelStates` to gate an app channel's column like push's, and `NotificationChannelDescriptor`, `NotificationChannelSwitch`, `NotificationAction`, `ChannelState` and `ChannelAlert` are exported.
+
+- 48b275d: Close the small vocabularies of onboarding, the DataTable and exports (PP-14.20, #938).
+
+  Onboarding. The audience vocabulary is open: `registerOnboardingAudience({ id, label, matches(principal, ctx) })` of `@marinoscar/platform-api/onboarding`, with `user`, `admin` and the new `org_admin` (the holder of the `org_admin` role of an active organization) registered through it. `OnboardingAudience` is `Builtin | (string & {})`; `onboardingAudienceSchema` is a string pattern (the OpenAPI `audience` enum becomes a pattern); `ONBOARDING_AUDIENCES` (`admin`, `user`) is deprecated for `BUILTIN_ONBOARDING_AUDIENCES`. `GET /api/onboarding` gains an optional `audiences` record with the block of every other audience the caller matches and that has a step for them, absent otherwise; `user` and `admin` keep their rules (the engine ignores a rule registered for those ids). `evaluateOnboarding` takes optional `audiences` and `audienceContext`, the `onboarding` conformance suite derives the `org_admin` block and flags a step naming an unregistered audience, and the web provider keeps the `audiences` blocks and their skip overlay.
+
+  DataTable. `registerDataTableFilterType({ type, operators, Editor, matches, coerce?, format? })` of `@marinoscar/platform-web/datatable/headless`; the five built-ins register through it, `FilterOperator` and `DataTableFilterType` are open (`BuiltinFilterOperator`, `BuiltinDataTableFilterType`), `DataTableColumn.filter = { type, editor?, operators? }` declares a column's filter, and `matchesFilters` filters rows on the page with the type's rules. `DataTableStoredLayout` gains `extra` (bounded plain JSON, 8 KiB, 32 keys, 8 levels) and `savedViews` (at most 20), validated by the user-settings API on write (`dataTableExtraSchema`, `dataTableSavedViewSchema`, a 32 KiB cap per table entry; the user-settings OpenAPI gains both fields) and sanitised on read; `useDataTableLayoutPrefs` gains `extra`, `setExtra`, `savedViews`, `saveView`, `applyView` and `deleteView`, and `reset` keeps the saved views. `DataTable` takes `slots={{ Toolbar, BulkBar }}`. The filter-model operator unions of the jobs, nodes, identity and db-backup slices gain `(string & {})`. A table that uses none of this renders the markup it did.
+
+  Exports. `registerExportWriter({ attachTo: '*' | string[], columnTypes? })` offers a writer on sources that do not list it, `ExportSource.columnTypes` and `acceptsAttachedWriters` gate and pin it, and `writersFor` returns the listed formats then the attached ones (platform writers first). The platform sources list no formats: their formats are the writers attached to them, so json, csv and xlsx are unchanged and an app's writer follows. A writer that cannot write a column type fails the export before any row (`guardWriterColumns`). `ExportColumn.meta` (flat scalars, at most 16 keys) carries a custom writer's own typing; the built-in writers never write it. `ExportsList` takes `slots={{ Columns, RowActions }}`. A source may now list an empty `formats`; `exports` conformance flags a writer attached to an unknown source.
+
+- fe61ffe: Roles: an app's own roles are assignable end to end, and an app can grant platform permissions to them, with no package edit and no migration (roles are strings). New `GET /api/roles?scope=system|org` lists `{ id, label, description, scope, assignable }` (`users:read` for `system`, `org_members:read` for `org`). `RoleDeclaration` gains `label` and `assignable` (registry-only, never seeded). The invite, org member update, user-role and test-login routes check the role registry and fail closed: an unknown role, a role of the other scope (`admin` on an invitation) or an `assignable: false` role is a `400` with the error code `ROLE_NOT_ASSIGNABLE` (registered through `registerErrorCode`, also `details.reason`); an invitation whose role stopped being assignable is left pending at sign-in, and `PUT /api/users/:id/roles` leaves a user's `assignable: false` system role in place. Manifest: `registerPlatformPermissions({ app: { grants } })` and `grantPermissions` give an app role platform permissions (validated, folded into the catalog's `rolePermissions`, so the seed and the permission resolver agree; a platform role cannot be the target), and `registerPermissionSet({ slice, roles, permissions })` lets a package declare its own slice, with `PlatformPermissionSlice` open and `identity` still mandatory. Contract: `roleIdSchema` (a string pattern) replaces the `z.enum` of `roleName` on the invite and member routes (OpenAPI: enum to pattern), `BUILTIN_ORG_ROLES` is the new name of `ASSIGNABLE_ORG_ROLES` (kept as a deprecated alias), `AssignableOrgRole` widens to any string. Web: `useRoles` reads the API; the invite dialog, member role select, invitation labels and Manage roles dialog offer the assignable roles with the API's labels and the hard-coded role lists are gone (`ORG_ROLES` is deprecated, `buildUserColumns(roles?)` and `ManageRolesDialog` take the roles, `InviteMemberDialog` takes `roles`); the user-roles call now sends `roleNames`, the field the API reads. Migration: a request that named `admin` as an org role used to fail request validation and is now refused by the service with the same `400` status; group roles stay `admin`, `editor` and `viewer` (a database enum).
+- b480c02: Open the settings slice to an app and to an installed package (PP-14.21, #939). Nothing changes for an app that registers none of the new points: no schema, stored value or OpenAPI field moves.
+
+  `@marinoscar/platform-api/settings`: `extendSystemSettingsNamespace` and `extendUserSettingsNamespace` take a dot `path` to an object field and add the fields inside it (an existing leaf key is refused, the parent is not; a stored value that predates the field keeps everything else). A system extension takes an `org` block (`mode: 'override' | 'tighten'`, `fields`, `tighten` per field as `'and'`, `'or'`, `'min'`, `'max'` or a function) that makes ONLY the added fields organization-overridable, composed with an existing org layer (`SettingsNamespaceOrgLayer` gained an optional `mode`). `overrideSettingsNamespaceDefaults(key, partial)` changes a namespace's defaults only, checked against its stored schema. `registerSettingsContribution({ id, system, user, extensions })` lets a package contribute namespaces and extensions from a side-effect import; `assembleSystemSettingsNamespaces` and `assembleUserSettingsNamespaces` list the platform's namespaces, the contributions' (import order) and the app's, fold the extensions and apply the defaults overrides. `extendUserProfile({ fields })` adds optional, bounded fields to the core user `profile`, and `registerThemePreference({ id, label })` adds a theme id `theme` accepts, listed in the new optional `themeOptions` of `GET /api/user-settings` while any is registered. `security` stays closed.
+
+  `@marinoscar/platform-contract/settings`: `THEME_PREFERENCE_ID_PATTERN`, `THEME_OPTION_LABEL_MAX`, `themePreferenceIdSchema`, `themeOptionSchema`, `ThemeOption`, `ThemePreferenceId` and `UserSettingsResponseBase.themeOptions`.
+
+  `@marinoscar/platform-web/settings`: `ProfileSettings` and `ThemeSettings` take `slots.ExtraFields` (and `UserProfilePage` and `UserAppearancePage` pass `slots` through), `ThemeSettings` offers `extraOptions`, `themePreferenceOptions` and `useThemePreferenceOptions` derive them from the settings document, and `registerOrgSettingsFieldRenderer(namespace, field, Component)` draws an `other` field of the organization settings page. `useUserSettings` hands `applyTheme` only `light`, `dark` and `system`; `UserSettingsDocument.theme`, `UserSettingsUpdateBase.theme` and `ThemeSettings`' `currentTheme` and `onThemeChange` widened to a theme id. The DOM of the three controls is unchanged without a slot, a renderer or a registered theme.
+
+- f994de1: Settings namespace seams for apps built on the packages (#865). `SystemSettingsNamespaces`, `SystemSettingsNamespaceDeclarations`, `UserSettingsNamespaces` and `UserSettingsNamespaceDeclarations` are declared in `@marinoscar/platform-api/settings` itself, so an app's `declare module '@marinoscar/platform-api/settings'` augmentation types `getNamespace(key)` whatever order the compiler meets it in (it used to lose the app's key once an installed slice's augmentation was processed after it). `SystemSettingsService.getNamespace(declaration)` reads a namespace typed by its declaration (`SystemSettingsNamespaceOf<D>`), with no augmentation. The `jobs` and `nodes` namespaces are the slices' own: `JOBS_SYSTEM_SETTINGS` / `mergeJobsSettings` (`/jobs`) and `NODES_SYSTEM_SETTINGS` / `mergeNodesSettings` (`/nodes`), with `DEFAULT_JOBS_POLICY` and `DEFAULT_NODES_POLICY` as defaults, registered by `JobsModule.forRoot()` and `NodesModule.forRoot()` through the new `ensureSystemSettingsNamespaces` unless the app's manifest already did (call them before `SettingsModule.forRoot()`). Their schemas are in `@marinoscar/platform-contract/jobs` and `/nodes`.
+- 9f4c147: Open the two places sharing hard-coded (PP-14.16, #934): who a grant can name, and how a decision is made.
+
+  `@marinoscar/platform-api/sharing`: `registerGranteeKind(GranteeKindDef)` and `registerAccessRule(AccessRuleDef)`. The built-in `user`, `group` and `link` kinds register through `registerGranteeKind` (no private fast path); `AccessPolicy`, `accessibleWhere`, `accessibleSql` and `POST /api/grants` compose the registry, with behaviour and SQL shape unchanged for the built-ins. A kind supplies `validateGrantee`, `describe` and the in-memory (`matchesPrincipal`) and SQL (`resolvePrincipalMatch`, parameterised through the app's SQL kit) spellings of one predicate. An access rule joins the documented order (owner and bypass first, rules `before-grants`, grants, rules `after-grants`, the org default): `deny` from any rule wins, a failing rule denies (logged with the rule id only), the record's user owner and a bypass holder are decided before the rules, and an allow confers a `role` (default the weakest). A rule gives `sql({ allow?, deny? })` so lists agree with decisions; a rule that can deny (`mayDeny`) must. `AccessVia` is open (`BuiltinAccessVia | (string & {})`: a widening of a stable type), rule ids and kind `via` values cannot impersonate a platform source, registered definitions are shallow-frozen, the decision counter's `via` label gains `app` and its `outcome` label gains `rule_error` (an access rule failed or was misconfigured; `AccessDecision.ruleFailure`). `AccessPolicy` takes a savepoint per call when rules apply so a failing rule statement cannot abort the shared transaction; the slice refuses the caller alias `g` in `accessibleSql`. `GET /api/sharing/grantee-kinds` (`sharing:read`) serves the registered kinds. `POST /api/grants` accepts `{ kind: 'custom', granteeKind, ref }` and answers 422 `GRANTEE_KIND_UNKNOWN`, `GRANTEE_INVALID` or `GRANTEE_KIND_NOT_PERSISTABLE`. New kits in `@marinoscar/platform-api/sharing/testing`: `describeGranteeKindConformance`, `describeAccessRuleConformance`, `recordingSqlKit`, `HOSTILE_STRINGS`.
+
+  A grant of an app-registered kind cannot be stored yet: `grants.grantee_kind` is an enum, so `registerGranteeKind` refuses `persisted: true` for a non-built-in kind until the sharing storage migration (tracked with the group-role migration) ships. No migration in this change.
+
+  `@marinoscar/platform-contract/sharing`: `BUILTIN_GRANTEE_KINDS`, `GRANTEE_KIND_ID_PATTERN`, `GRANTEE_KIND_INPUTS`, `granteeKindDescriptorSchema`, `granteeKindListSchema`, `customGranteeSchema` (a third `grantGranteeInputSchema` variant; the `user` and `group` shapes keep their validation), `SHARING_LIMITS.granteeRefMax`. `GRANT_GRANTEE_KINDS` is unchanged (the stored vocabulary).
+
+  `@marinoscar/platform-web/sharing`: `registerGranteePicker(kind, Component)`, `freezeGranteePickers()`, `useGranteeKinds()`, `SharingClient.listGranteeKinds`, `ShareActions.shareWithGrantee` and the `granteePickers` prop of `ShareDialog`. The dialog offers each non-built-in kind a grant can be stored for as one more choice (a text field, or the registered picker); the DOM is unchanged when only the built-ins are listed.
+
+- d35900e: Sharing: open group roles and persisted app grantee kinds. Migration `0037_open_sharing_vocabularies` turns `group_members.role`, `group_invites.role` and `grants.grantee_kind` from Prisma enums into text, adds the nullable `grants.grantee_ref` and relaxes `grants_grantee_consistency_check`; an app registers a group role with `registerGroupRole` and a persisted grantee kind with `registerGranteeKind({ persisted: true })`, and the share dialog and member role pickers read the registries.
+- 74c4aff: Declare peer dependencies per slice (`packages/platform-slice-peers.json`, checked by `npm run check:slice-peers`) and make every peer that the universal slice does not need optional. `platform-api` now requires only what `core` needs (`@nestjs/common`, `@nestjs/core`, `@nestjs/swagger`, `@opentelemetry/api`, `@prisma/client`, `nestjs-zod`, `reflect-metadata`, `rxjs`, `zod`); `@nestjs/config`, `@nestjs/schedule`, `@nestjs/event-emitter`, `@nestjs/jwt`, `@nestjs/passport`, `passport`, `@nestjs/terminus` and `@prisma/client-runtime-utils` become optional peers an app installs for the slices that use them. `platform-web` requires only `@mui/material`, Emotion, `react` and `react-dom`; `@mui/icons-material`, `react-router-dom` and `zod` become optional. `platform-db` no longer lists `@prisma/client` (its seed takes the app's client structurally) and `prisma` becomes optional; `platform-cli`'s `react` becomes optional. An app that installed every peer needs no change; an app that imports only some slices can now install only their peers. The datatable no longer imports the undeclared transitive `@mui/utils`.
+- 5e98e3d: Storage drivers are pluggable (PP-14.7, #925). `registerStorageDriver` adds an object store (Azure Blob, Google Cloud Storage, a local disk) from an app or a package: its own settings schema, declared secrets (stored encrypted at the credential purpose `storage_<id>`, never in settings or the environment), `build`, `testConnection`, and optionally `provision`, `listKeys` and `purge`. `s3`, `r2` and `s3compatible` are drivers registered through the same function, and all S3-specific code (the connection test, bucket provisioning, the purge lister, the per-flavour requirements and region fallback, the Doctor egress host) moved into them. The connection test, provisioning, purge, egress and the resolving provider delegate to the active driver. `describeStorageDriverConformance` (`@marinoscar/platform-api/storage/testing`) is the kit every driver runs.
+
+  The `storage` settings namespace stores `provider` (a driver id) and a `drivers` record validated per driver. A row stored before this release loads unchanged (its flat fields become `drivers.<provider>`, field by field), and the flat fields (`bucket`, `region`, `endpoint`, `accountId`, `accessKeyId`, `forcePathStyle`) stay accepted on PUT, PATCH and the admin routes and published as a deprecated read view. `databaseBackup.storageProvider` accepts any driver id.
+
+  Contract: `BUILTIN_STORAGE_PROVIDER_KINDS` (`STORAGE_PROVIDER_KINDS` stays as a deprecated alias), `storageDriverIdSchema`, `StorageProviderKind` widens to `string`; the admin config view gains `drivers` and `descriptors` and `missing` becomes a list of strings; the admin PUT, test and bucket bodies gain optional `drivers` and `secrets`; the test and provisioning results gain `message`. The `storage` contract slice now depends on the `settings` slice.
+
+  Migration notes for code that builds these by hand: `ResolvedStorageConfig` is the generic active configuration (`provider`, `bucket`, `region`, `endpoint?`, `settings`, `secrets`; the S3 family's is `ResolvedS3Config`); `StorageConnectionTestService` and `StorageBucketProvisionService` take a `StorageSubmissionService`; `resolveStorageConfig` (S3 only) is deprecated; `npm run storage:purge` exits `3` for a driver that can neither purge nor list its keys. New installs seed `storage` as `{ provider, drivers }`.
+
+  Web: `registerStorageDriverPanel(id, Component, { validate })` (`@marinoscar/platform-web/storage/ui`, and the new `/storage/ui/driver-panels` subpath) chooses the form the admin storage page draws for a driver. The page lists one radio per descriptor the API serves and the built-in `s3`, `r2` and `s3compatible` drivers register their bespoke form through the registry (markup unchanged); any other driver is drawn by `StorageGenericDriverPanel` from its descriptor (`PluggableConfigForm`, with write-only secrets), so an app that adds a driver with `registerStorageDriver` needs no web code. The page saves, tests and provisions with `{ provider, drivers: { <id>: settings }, secrets: { <id>: { <name>: value } } }`, shows a driver's `message` and `details` and offers provisioning after a failed test that reported no checks. `StorageProviderKind` and `MissingStorageConfigField` are `string`, `StorageConfigView` gained `drivers` and `descriptors`, `StorageConfigInput` needs only `provider`, and the test and provisioning results gained `message`. The S3-compatible radio label is now the driver's own ("S3-compatible"). The `storage` web slice now depends on `settings`.
+
+- 5425626: Let an app put its own numbers on the Telemetry Dashboard and in the assistant (PP-14.18, #936).
+
+  Units: `registerMetricUnit(MetricUnitDef)` of `@marinoscar/platform-api/telemetry`; the 15 built-in units register through it (`BUILTIN_METRIC_UNITS`, with `METRIC_UNITS` kept as a deprecated alias), `assertUnit` reads the registry and `GET dashboard/metric-groups` serves, per group, `units` (the descriptors of the units it uses beyond the built-ins) so the browser formats an app unit with no web change. A unit descriptor has one of nine fixed formats and no code (`metricUnitDescriptorSchema`).
+
+  Presentation: `MetricGroupDef.presentation` is data (tiles, charts with theme-token colours, tables with Top N and `problems-first` or `value-desc` sort and column displays, and `ratio`, `delta` and `rate` virtual columns), zod-validated and bounded when the group is registered, and served on `/metric-groups`. The six platform groups declare theirs (`PLATFORM_METRIC_PRESENTATIONS` of the contract) instead of the web's section table, and draw with the same DOM. `metricGroupPresentationSchema` and the presentation interfaces are new contract exports.
+
+  Panels: `registerDashboardPanel(DashboardPanelDef)` and `dashboardPanelRegistry` (API; `GET dashboard/panels` and `panels/:id`, payload at most 256 KiB, a time budget, a generic failure) with `registerDashboardPanelView(id, View, { frame? })` (web, also from the new `@marinoscar/platform-web/telemetry/ui/dashboard-panels`). The platform's `api` and `logs` panels register through the same calls. `TelemetryQueryFacade` (`query`, `sql`, `dialect`) is the only way a panel reads the store: one guarded, capped, timed-out and audited statement per call (audit source `panel`), under a per-request statement budget.
+
+  Assistant: `registerTelemetryAssistantTool(TelemetryAssistantToolDef)` adds a read-only tool that receives the facade and never a client (a name that shadows one of the eight built-ins is refused; `rows` output is withheld from the model while `assistant.shareResults` is off), and `TelemetryModule.forRoot({ assistant: { extraInstructions } })` appends developer notes (at most 4 000 characters of plain text) to the system prompt as an `APPLICATION NOTES` section.
+
+  Pages: `TelemetryDashboardPage`, `TelemetrySettingsPage` and `TelemetryExplorerPage` take `slots` of the page-slot contract and are off `page-slots.exempt.json`; the explorer also takes `starterQueries`.
+
+  otel-core: `initializeOtel` accepts `spanProcessors`, `logRecordProcessors`, `metricReaders`, `views`, `sampler`, `textMapPropagator` and `resourceAttributes`; every processor and reader is wrapped in a gated one (`GatedSpanProcessor`, `GatedLogRecordProcessor`, `GatedMetricReader`), so nothing exports while the runtime gate is closed.
+
+  Conformance: the `telemetry` suite gains check 9 (registered panels and tools are well formed, the platform's panels remain) and check 10 (the facade has exactly `query`, `sql` and `dialect` and is frozen), and check 1 validates presentations. `/telemetry/testing` exports `createQueryFacade`, `checkFacadeSurface` and `checkRegisteredExtensions`.
+
+  Additive: a host that registers nothing sees no change except the new optional `presentation` and `units` fields on `GET dashboard/metric-groups` and the new `dashboard/panels` routes.
+
+- 175ddd3: Make the dashboard metric tables' freshness window an option: `TelemetryModule.forRoot({ metrics: { freshMs } })` (default `METRIC_FRESH_MS`, 150 s; resolved into the `TELEMETRY_METRIC_FRESH_MS` token). The `/metrics` response reports it as the optional `freshMs`, and each dashboard section with a table shows it in its header ("Current within 2 min 30 s").
+- 1171b1c: Complete the telemetry slice in all five packages. `@marinoscar/platform-api/telemetry/testing` gains the telemetry conformance suite (registered with `runPlatformConformance()` as `suites.telemetry`: metric groups, route permissions, read-only Doctor checks, no secrets in responses, the cron coverage and the boot without a store), the stub host ports, and the five activity and six coach fixture tables; `ConformanceCase.run` may be async and a slice may add a suite key by augmenting `PlatformConformanceSuiteOptions`. Every telemetry slice README now follows the Package documentation standard with a catalog that links a working example in the reference app.
+- 2732024: The telemetry store is replaceable (PP-14.11, #929). The explorer, the export, the assistant's statements, the Telemetry Dashboard, the status page, the retention job, the Doctor checks and the support bundle now depend on two injection tokens, `TELEMETRY_STORE` (a `TelemetryStore`: `query(sql, params, { readOnly: true, timeoutMs, signal })`, `schema()`, `ping()`, `close()`, `isConfigured()`, an optional `retention` control) and `TELEMETRY_SQL_DIALECT` (a `TelemetrySqlDialect`: the time bucket, the percentile, the regular-expression replace, the JSON attribute read, the case-insensitive substring match, the text cast, the row cap and the metric tables' time and value columns), and never on `GreptimeClient`. `registerTelemetryStore` adds a store from an app or a package at import time (its own settings schema, defaults and declared secrets, stored encrypted at the credential purpose `telemetry_<id>`, and `build`, which returns the store and its dialect), and `TelemetryModule.forRoot({ store: '<id>' })` selects it (default `greptime`; an id nobody registered fails boot naming the registered ones). `greptime` is the built-in store, registered through the same function: `GreptimeClient` now implements `TelemetryStore` (its `query()` runs on the read-only login, `queryReader()` and `queryAdmin()` are unchanged), its dialect, retention control and schema read live under `telemetry/stores/greptime/`, and its connection, the `telemetry_connection` row and the `telemetry_greptime` credential purpose are unchanged. The explorer's guard (one read-only statement, the row cap, the timeout, the audit row) stays in the platform, above the store. `describeTelemetryStoreConformance` (`@marinoscar/platform-api/telemetry/testing`) is the kit every store runs: writes refused, timeout and abort honoured, `schema()` shape, a `ping()` that never throws or leaks a secret, an unconfigured store, and, over a fixture, every dashboard statement built with the store's dialect.
+
+  A store that is not GreptimeDB has `GET` and `PUT /api/admin/telemetry/store` (`telemetry:read` / `telemetry:write`, `If-Match`): its non-secret settings are one entry of the new `telemetry_store` system-settings row and its secrets are write-only. `GET /api/admin/telemetry/config` gains an optional `store: { id, label }`. The dashboard SQL builders take an optional trailing `TelemetrySqlDialect` (default: the GreptimeDB one, so their text is unchanged), and the stub ports of `telemetry/testing` take a `policy` patch and per-purpose secrets.
+
+  Migration notes: the app's `TELEMETRY_SETTINGS_STORE` adapter must allow the new row key (`telemetry_store`, beside `telemetry_connection`; the reference app's `TELEMETRY_OWNED_ROW_KEYS`); code that constructs `TelemetryQueryService`, `TelemetrySchemaService`, `TelemetryStatusService`, `TelemetryRetentionHandler`, `TelemetrySettingsService`, the Doctor reachability and freshness checks or the support-bundle section by hand now passes a `TelemetryStore` (a `GreptimeClient` is one) where it passed the client; the `greptime/greptime.client.ts`, `greptime-host.ts` and `greptime.errors.ts` files moved under `telemetry/stores/` (the public exports are unchanged, and the store errors are now exported too); the `telemetry` platform-api slice depends on `credentials`, and the `telemetry` contract and web slices on `settings`.
+
+  Web: the Telemetry settings page keeps the Telemetry services and GreptimeDB Connection sections for the built-in store (markup unchanged) and draws a Store section for any other registered store: the settings slice's `PluggableConfigForm` over the descriptor `GET /admin/telemetry/store` serves, with write-only secrets and an `If-Match` on every save, so an app that registers a store needs no web code. `useTelemetryStore` and the `TelemetryStoreConfig` types are exported from `@marinoscar/platform-web/telemetry/headless`; the settings slice's index exports `usePluggableConfigForm`. Contract: `telemetryStoreSummarySchema`, `telemetryStoreResponseSchema` and `updateTelemetryStoreSchema`.
+
+- 39b5300: Add the user-data slice (#743): registry-driven per-user deletion with scopes (`user.data.purge`), the admin factory reset (`admin.factory_reset`) and organization offboarding (`org.offboard`), with the Danger Zone, factory reset and offboarding UI; `StorageKeyPrefixDef.survivesFactoryReset`; `OrganizationsPage` `renderActions`.
+- 8246e10: The packaged-page slot contract (PP-14.23) is applied to the AI, storage, email, Android, host, profile, appearance, organization settings, user-data and notification pages (PP-14.24, #942). Every page takes an optional `slots` prop typed to `PageSlotsBase`; a page given none renders the markup it always did (each page group has a DOM snapshot recorded from the old components).
+
+  - **Web, `@marinoscar/platform-web/core`**: `PageSlotsFrame` lays a page body out in slot order (no wrapper element), for the packaged pages and for an app's own page.
+  - **AI**: `AiConfigPage` (`ProviderCardExtra`, drawn under each provider's card), `AiModelsPage` and `AiUsagePage` (the table slots), `UserAiKeysPage`, `OrgAiKeysPage` and `AiPlaygroundPage` (the playground `Header` receives its "New conversation" button as `actions`). `AiUsageTable` takes `slots` too.
+  - **Storage, email**: `StorageConfigPage` and `EmailSettingsPage` take the base slots (the driver and transport panels stay registries).
+  - **Android**: `AndroidAppPage` takes the base slots; `TrustedAppsSection`, `ReleasesSection` and `NotificationsSection` are exported from `android-app/ui`.
+  - **Host**: `AboutPage` and `MaintenancePage` take the base slots. `MaintenanceScreen` gains `logo`, `actions` and `children`; `InstallPrompt` `icon` and `copy`; `MaintenanceBanner` `copy` and `actions`.
+  - **Settings**: `UserProfilePage`, `UserAppearancePage` and `OrgSettingsPage` take the base slots.
+  - **Notifications**: `BroadcastsPage`, `PushConfigPage`, `NotificationSettingsPage` and `UserNotificationsPage` take the base slots.
+  - **User data**: `FactoryResetPage` and `UserDangerZonePage` take `slots` and `copy`, and print the kept and deleted lines of the summary responses instead of constants (the constants stay as the fallback, word for word).
+  - **API and contract (user-data)**: `GET /api/user-data/summary` returns `kept: string[]`, `GET /api/admin/factory-reset/summary` returns `deleted: string[]` and `kept: string[]`. The platform's lines are exactly the text the web bundle held; `UserDataModelHint.summary` (a kept model) and `FactoryResetStepDef.summary` (a step) add one line each. `userDataSummarySchema` and `factoryResetSummarySchema` gain the required arrays: deploy the API before the web, and add the arrays to any hand-built summary in a test.
+  - The telemetry pages, the identity and sharing pages and the exports and onboarding pages stay on `test/page-slots.exempt.json`.
+
+### Patch Changes
+
+- f6e319b: Documentation only: every slice README's Extension-point catalog links the new extension author guide (`docs/EXTENDING.md`); the email README no longer promises that a provider of `SmtpEmailProvider` in the app module replaces the transport (it does not reach the package's consumers; a transport registry is not supported yet); the AI READMEs say that a provider cannot be enabled from an app yet; the platform-db README documents `rlsPolicies` in `platform.lock` with the migration SQL for an app table protected by row-level security.
+- fe73d7a: Documentation only: the overview READMEs list every shipped slice and subpath, and the stale "version 0.0.0" status lines are replaced.
+- 6487697: Finish the identity slice move (#727): the reference app now imports identity only from `@marinoscar/platform-{api,web,contract}/identity`, so the web identity catalog's examples point at the app's real uses (`App.tsx`, and one example per data hook in `apps/web/src/identity/dataHookExamples.tsx`), the identity hook, page, guard and component suites the app kept run in `platform-web`'s own tests (with a `fakeIdentityApi` test helper), and comments naming the app's old identity paths point at the packages. No API change.
+- 346e661: The sharing slice's READMEs are complete in all three packages (#732): quick start, the full extension-point catalog with a compiled, tested reference example for every entry (`apps/api/test/examples/sharing/`, `apps/web/src/__tests__/examples/sharing/`), minimal examples, observability, security notes, the conformance suite, troubleshooting, and two migration recipes (a per-record share table, kvox-style; circles and public links, MemoriaHub-style). `ownedByMeOrMyGroups`, `ShareDialog`, `useGrants`, `useShareActions` and `useSharedWithMe` are now catalogued extension points.
+
 ## 0.1.0-next.3
 
 ### Minor Changes

package/README.md

@@ -12,6 +12,21 @@ Slices (each a subpath export with its own README):
 |---|---|---|
 | `@marinoscar/platform-contract/doctor` | The admin Doctor's report, row, status and query (#701), and the support bundle envelope (#772) | [src/doctor/README.md](src/doctor/README.md) |
 | `@marinoscar/platform-contract/telemetry` | Telemetry wire shapes, `stable`: config, status, explorer, connection, stack, dashboard, assistant and the `telemetry` settings namespace (#702) | [src/telemetry/README.md](src/telemetry/README.md) |
+| `@marinoscar/platform-contract/identity` | Identity wire shapes, `stable`: the sign-in error codes (`AUTH_ERROR_CODES`, the single source), `/api/auth/me`, token responses, personal access tokens, the device flow, organizations, members and invitations (#727) | [src/identity/README.md](src/identity/README.md) |
+| `@marinoscar/platform-contract/settings` | Settings wire shapes, `stable` (the org-settings shapes `experimental`): the core user fields (`theme`, `profile`), the `dataTables` and `navigation` user namespaces, the system and user response bases, and `/api/org-settings` (#733) | [src/settings/README.md](src/settings/README.md) |
+| `@marinoscar/platform-contract/credentials` | The presentation-safe shapes of a stored credential (deployment, user, organization), the tiers and the secret-bearing key list (#735) | [src/credentials/README.md](src/credentials/README.md) |
+| `@marinoscar/platform-contract/onboarding` | Onboarding wire shapes, `experimental`: the stored `onboarding` user-settings namespace, `GET /api/onboarding` and the activation metrics (#745) | [src/onboarding/README.md](src/onboarding/README.md) |
+| `@marinoscar/platform-contract/email` | The email settings, the `PUT` body with its write-only secrets, the response with masked credential status, the test-send result and the built-in transport list with the open transport id (#737, PP-14.8) | [src/email/README.md](src/email/README.md) |
+| `@marinoscar/platform-contract/jobs` | The admin job routes' list query and row (with `orgId`), summary, insights and bulk-action shapes, and the status, reason and window lists (#734) | [src/jobs/README.md](src/jobs/README.md) |
+| `@marinoscar/platform-contract/nodes` | The worker-node control plane, data plane, per-job secret and node credential request shapes, and the node bounds (#734) | [src/nodes/README.md](src/nodes/README.md) |
+| `@marinoscar/platform-contract/storage` | The `storage` settings namespace (with the no-secret proof), the objects API and status shapes, and the storage-config admin bodies and results (save, connection test, bucket provisioning) (#736) | [src/storage/README.md](src/storage/README.md) |
+| `@marinoscar/platform-contract/exports` | The `/api/exports` request and responses, the cell, column and request-field shapes, and the JSON export file envelope (#744) | [src/exports/README.md](src/exports/README.md) |
+| `@marinoscar/platform-contract/ai` | The `ai` system and user settings namespaces (with the no-secret proof), the org layer and its tighten-only merge, the org-key and feature-list shapes (#739) | [src/ai/README.md](src/ai/README.md) |
+| `@marinoscar/platform-contract/db-backup` | The `databaseBackup` settings namespace, every `/api/admin/db-backup` body and response (config, runs, actions, restore, rollback, node-credential pre-flight) and the `db.backup.run` node result (#740) | [src/db-backup/README.md](src/db-backup/README.md) |
+| `@marinoscar/platform-contract/sharing` | The group, member, invite and grant request and response shapes, and the role and status lists | [src/sharing/README.md](src/sharing/README.md) |
+| `@marinoscar/platform-contract/notifications` | The inbox, events, push subscription, Web Push configuration and broadcast shapes, and the `notifications` settings namespaces | [src/notifications/README.md](src/notifications/README.md) |
+| `@marinoscar/platform-contract/android-app` | The trusted-app, Digital Asset Links, APK release and test-notification shapes | [src/android-app/README.md](src/android-app/README.md) |
+| `@marinoscar/platform-contract/user-data` | The user deletion, factory reset and organization offboarding shapes, with their confirmation phrases | [src/user-data/README.md](src/user-data/README.md) |
 
 The root entry exports only `PLATFORM_PACKAGE`; schemas are reached through their slice's subpath, so a consumer loads only the slices it uses.
 
@@ -49,7 +64,7 @@ Install these in the app; the package never bundles its own copy (a second copy
 
 | Package | Range |
 |---|---|
-| `zod` | `^4.4.3` |
+| `zod` | `^4.4.3` (required; every slice imports it) |
 
 An app that uses `@marinoscar/platform-api` or `@marinoscar/platform-web` gets this package with them, but still installs `zod` itself.
 
@@ -94,6 +109,8 @@ None. Schemas take no options; the routes that use them are configured in `@mari
 
 None. The root entry exports only `PLATFORM_PACKAGE`; every schema is an extension point of its slice and is catalogued in that slice's README (`schema` kind), for example [the Doctor's](src/doctor/README.md#extension-point-catalog).
 
+The extension ladder and a recipe per extension: [docs/EXTENDING.md](../../docs/EXTENDING.md).
+
 ## Data
 
 None. The package holds schemas of HTTP payloads, not database models; models live in `@marinoscar/platform-db`.
@@ -128,6 +145,7 @@ What counts as breaking, for every slice: renaming or removing a field, making a
 
 - #701: first slice, `./doctor`. The Doctor's schemas moved here from `@marinoscar/platform-api/doctor` and its types from `@marinoscar/platform-web/doctor/headless`; both packages re-export the old names. No wire or OpenAPI change.
 - #702: `./telemetry`. The telemetry wire shapes moved here from the API's telemetry DTOs and the web's hand-written mirrors; both keep their old names. No wire or OpenAPI change.
+- #727: `./identity`. `AUTH_ERROR_CODES` is defined here once (the API and the web app both import it, replacing the hand-kept mirror), and the request schemas of switch-org, personal access tokens, the device flow and organization administration moved here from the API's DTO files. No wire or OpenAPI change.
 
 ## Troubleshooting
 
@@ -144,3 +162,7 @@ Build and import problems common to every platform package are in [DEVELOPMENT.m
 - [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages): build, test and lint commands
 - [Doctor slice](src/doctor/README.md)
 - [Telemetry slice](src/telemetry/README.md)
+- [Identity slice](src/identity/README.md)
+- [Settings slice](src/settings/README.md)
+- [Onboarding slice](src/onboarding/README.md)
+- [Exports slice](src/exports/README.md)

package/dist/cjs/ai/capabilities.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * A capability id on the wire. Open: any `AI_CAPABILITY_ID_PATTERN` string, never
+ * `z.enum(BUILTIN_AI_CAPABILITIES)`.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare const aiCapabilityIdSchema: z.ZodString;
+/**
+ * An operation id on the wire (the `operation` of a usage row). Open: any
+ * `AI_OPERATION_ID_PATTERN` string.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare const aiOperationIdSchema: z.ZodString;
+/**
+ * A feature id on the wire (the `feature` of a usage row or a run).
+ *
+ * @stability experimental
+ */
+export declare const aiFeatureIdSchema: z.ZodString;
+/**
+ * One capability, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export declare const aiCapabilityDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    builtin: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * One operation, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+export declare const aiOperationDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    capability: z.ZodString;
+    builtin: z.ZodBoolean;
+    runnable: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The body of `GET /api/admin/ai/capabilities`.
+ *
+ * @stability experimental
+ */
+export declare const aiCapabilitiesResponseSchema: z.ZodObject<{
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodString;
+        builtin: z.ZodBoolean;
+    }, z.core.$strip>>;
+    operations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        capability: z.ZodString;
+        builtin: z.ZodBoolean;
+        runnable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * A cost the deployment's pricing port computed (`AI_PRICING`): an amount in
+ * a currency, never a rate card.
+ *
+ * @stability experimental
+ */
+export declare const aiUsageCostSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>;
+/** One capability on the wire. @stability experimental */
+export type AiCapabilityDescriptor = z.infer<typeof aiCapabilityDescriptorSchema>;
+/** One operation on the wire. @stability experimental */
+export type AiOperationDescriptor = z.infer<typeof aiOperationDescriptorSchema>;
+/** The capabilities response. @stability experimental */
+export type AiCapabilitiesResponse = z.infer<typeof aiCapabilitiesResponseSchema>;
+/** A computed cost. @stability experimental */
+export type AiUsageCost = z.infer<typeof aiUsageCostSchema>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/cjs/ai/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/ai/capabilities.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,aAA6C,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAA4C,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAA0C,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;iBASvC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAWtC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;iBAKvC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;iBAK5B,CAAC;AAEH,0DAA0D;AAC1D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,yDAAyD;AACzD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,yDAAyD;AACzD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/cjs/ai/capabilities.js

@@ -0,0 +1,93 @@
+"use strict";
+// =============================================================================
+// The AI capability and operation vocabularies on the wire (PP-14.17, #935)
+// =============================================================================
+//
+// `GET /api/admin/ai/capabilities` lists every capability and operation the
+// deployment knows: the platform's own and the ones an app registered with
+// `registerAiCapability` / `registerAiOperation` (`@marinoscar/platform-api/ai`).
+// The admin pages draw their capability labels from it, so an app capability
+// needs no web change.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiUsageCostSchema = exports.aiCapabilitiesResponseSchema = exports.aiOperationDescriptorSchema = exports.aiCapabilityDescriptorSchema = exports.aiFeatureIdSchema = exports.aiOperationIdSchema = exports.aiCapabilityIdSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * A capability id on the wire. Open: any `AI_CAPABILITY_ID_PATTERN` string, never
+ * `z.enum(BUILTIN_AI_CAPABILITIES)`.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.aiCapabilityIdSchema = zod_1.z.string().regex(constants_js_1.AI_CAPABILITY_ID_PATTERN);
+/**
+ * An operation id on the wire (the `operation` of a usage row). Open: any
+ * `AI_OPERATION_ID_PATTERN` string.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.aiOperationIdSchema = zod_1.z.string().regex(constants_js_1.AI_OPERATION_ID_PATTERN);
+/**
+ * A feature id on the wire (the `feature` of a usage row or a run).
+ *
+ * @stability experimental
+ */
+exports.aiFeatureIdSchema = zod_1.z.string().regex(constants_js_1.AI_FEATURE_ID_PATTERN);
+/**
+ * One capability, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+exports.aiCapabilityDescriptorSchema = zod_1.z.object({
+    /** The capability id (`audio_transcription`). */
+    id: exports.aiCapabilityIdSchema,
+    /** The short label the admin pages show (`Transcription`). */
+    label: zod_1.z.string(),
+    /** One sentence on what a model with it can do. */
+    description: zod_1.z.string(),
+    /** Whether the platform ships it (`false`: an app or package registered it). */
+    builtin: zod_1.z.boolean(),
+});
+/**
+ * One operation, as `GET /api/admin/ai/capabilities` lists it.
+ *
+ * @stability experimental
+ */
+exports.aiOperationDescriptorSchema = zod_1.z.object({
+    /** The operation id (`audio.transcribe`), the `operation` of its usage rows. */
+    id: exports.aiOperationIdSchema,
+    /** The label usage reports show. */
+    label: zod_1.z.string(),
+    /** The model capability an operation needs. */
+    capability: exports.aiCapabilityIdSchema,
+    /** Whether the platform ships it. */
+    builtin: zod_1.z.boolean(),
+    /** Whether `AiService.forUser(...).run(id, input)` can run it (an app operation with schemas). */
+    runnable: zod_1.z.boolean(),
+});
+/**
+ * The body of `GET /api/admin/ai/capabilities`.
+ *
+ * @stability experimental
+ */
+exports.aiCapabilitiesResponseSchema = zod_1.z.object({
+    /** Every registered capability, built-ins first, then registration order. */
+    capabilities: zod_1.z.array(exports.aiCapabilityDescriptorSchema),
+    /** Every registered operation, built-ins first, then registration order. */
+    operations: zod_1.z.array(exports.aiOperationDescriptorSchema),
+});
+/**
+ * A cost the deployment's pricing port computed (`AI_PRICING`): an amount in
+ * a currency, never a rate card.
+ *
+ * @stability experimental
+ */
+exports.aiUsageCostSchema = zod_1.z.object({
+    /** The amount, in `currency`'s major unit. */
+    amount: zod_1.z.number(),
+    /** An ISO 4217 code (`USD`) or any short label the pricing port uses. */
+    currency: zod_1.z.string().min(1).max(8),
+});
+//# sourceMappingURL=capabilities.js.map

package/dist/cjs/ai/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/ai/capabilities.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,kFAAkF;AAClF,6EAA6E;AAC7E,uBAAuB;AACvB,gFAAgF;;;AAEhF,6BAAwB;AAExB,iDAA0G;AAE1G;;;;;;GAMG;AACU,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,uCAAwB,CAAC,CAAC;AAE/E;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,sCAAuB,CAAC,CAAC;AAE7E;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oCAAqB,CAAC,CAAC;AAEzE;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACnD,iDAAiD;IACjD,EAAE,EAAE,4BAAoB;IACxB,8DAA8D;IAC9D,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,mDAAmD;IACnD,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE;IACvB,gFAAgF;IAChF,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAClD,gFAAgF;IAChF,EAAE,EAAE,2BAAmB;IACvB,oCAAoC;IACpC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,+CAA+C;IAC/C,UAAU,EAAE,4BAAoB;IAChC,qCAAqC;IACrC,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;IACpB,kGAAkG;IAClG,QAAQ,EAAE,OAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACnD,6EAA6E;IAC7E,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,oCAA4B,CAAC;IACnD,4EAA4E;IAC5E,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,mCAA2B,CAAC;CACjD,CAAC,CAAC;AAEH;;;;;GAKG;AACU,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,8CAA8C;IAC9C,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,yEAAyE;IACzE,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC"}