@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# @marinoscar/platform-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The NestJS side of the platform: dynamic modules (one subpath export per slice, for example `@marinoscar/platform-api/<slice>`) that an app imports into its own `AppModule` and extends through options, registries and injection tokens. CommonJS, compiled with `tsc` so decorator metadata (`design:paramtypes`) survives for Nest dependency injection.
+
+## Purpose and scope
+
+Dynamic modules, services, guards and registries of the platform's API slices. It does not own the app's composition root, its product identity or its own feature modules.
+
+Status: pre-release (the current channel and how to install it: the [release runbook](../../docs/runbooks/release-platform-packages.md)). The root export is only the package name (`PLATFORM_PACKAGE`); the slices are subpath exports, each with its own README:
+
+- `@marinoscar/platform-api/core`: the bottom of the slice graph, code only: the typed registry primitive (`defineRegistry`, `Registry`, `RegistryError`, `RegistryFreezeService`, `withTemporaryEntries`), the principal and scope contract (`Principal`, `Scope`, `SystemActor`, ADR 0001), the exception filter and its exceptions (`HttpExceptionFilter`, `ErrorDto`, `withVerbatimErrorBody`, `DatabaseSeedException`), the secret cipher (`encryptSecret`, `decryptSecret`, `userCredentialPurpose`, `deriveSigningKey`, `verifyEncryptionKeyAtStartup`) and the OpenAPI tag registry (`openApiTags`), the role and permission registries (`roleRegistry`, `permissionRegistry`, `registerPermissions`, `buildPermissionCatalog`, #866), and scoped data access (`userOwnedModelRegistry`, `forUser`, `userScopeExtension`, `asSystem`, `ScopedAccessError`; schema-independent, #699). [README](src/core/README.md).
+- `@marinoscar/platform-api/testing`: the conformance harness (`runPlatformConformance`, `conformanceSuites`, the `cron-enqueue-only` and `user-owned-data` suites, and the small Prisma schema reader behind the latter). [README](src/testing/README.md).
+- `@marinoscar/platform-api/doctor` and `@marinoscar/platform-api/doctor/testing`: the admin Doctor, `GET /api/admin/doctor` (`DoctorModule.forRoot({ host })`, `DoctorCheckRegistry`, the check contract); the testing entry is the check author's kit (`describeDoctorCheckConformance`, a recording Prisma client, a write-failing storage provider) and the `doctor-read-only` conformance suite. The first packaged slice (#696). [README](src/doctor/README.md).
+- `@marinoscar/platform-api/otel-core` and `@marinoscar/platform-api/otel-core/sdk`: the emitting half of telemetry (#700): `initializeOtel` (the Nest-free SDK bootstrap, loaded first), the runtime export gate `telemetryGate`, the metrics host `MetricsHostService` with the app-metric name registry and the gauge-provider seam, `registerRequestSpanAttributes` and `@Trace()`. [README](src/otel-core/README.md).
+- `@marinoscar/platform-api/identity` and `@marinoscar/platform-api/identity/testing`: identity (#727): `IdentityModule.forRoot()`, the route-access decorators and guards (`@Auth`, `@Public`, `@CurrentUser`, `@CurrentPrincipal`, `JwtAuthGuard`), sessions and refresh tokens, personal access tokens, worker-node credentials, the device flow, users, the allowlist, organizations and tenancy, the sign-in provider registry, the `identity.*` events and the host ports identity reaches the app through; the test login, the stub host and the `identity` conformance suite. [README](src/identity/README.md).
+- `@marinoscar/platform-api/settings` and `@marinoscar/platform-api/settings/testing`: settings (#733): `SettingsModule.forRoot()`, the system and user namespace registries and their composition, `SystemSettingsService`, `UserSettingsService`, the org layer (`OrgSettingsService`, `/api/org-settings`), `SettingsResolver` (system, then org, then user) and `SystemSettingsRowStore`; the `settings` conformance suite. [README](src/settings/README.md).
+- `@marinoscar/platform-api/credentials` and `@marinoscar/platform-api/credentials/testing`: the encrypted credential stores (#735): the deployment's (`CredentialsService`), a user's own (`UserCredentialsService`) and an organization's (`OrgCredentialsService`, `org_credentials` under row-level security), `UserCredentialResolver` (user, then org, then deployment), the purpose registries `registerCredentialPurpose` and `registerUserCredentialPurpose`, and the `credentials` conformance suite. [README](src/credentials/README.md).
+- `@marinoscar/platform-api/onboarding` and `@marinoscar/platform-api/onboarding/testing`: onboarding (#745): `OnboardingModule.forRoot()`, the step, fact, ordering and activation-milestone registries, the platform steps (storage, email, access, AI, Web Push, backups, the org invite; profile, notifications), `GET /api/onboarding` (derived, read-only) and `GET /api/admin/onboarding/metrics` (aggregates only), the `onboarding` user-settings namespace and `extendOnboardingSettings`; the `onboarding` conformance suite. [README](src/onboarding/README.md).
+- `@marinoscar/platform-api/email` and `@marinoscar/platform-api/email/testing`: outgoing email (#737): `EmailModule.forRoot()`, pluggable transports (`registerEmailTransport`; SES and SMTP ship, with inline attachments), the `email` settings row and `/api/email-settings`, the template registry (`registerEmailTemplate`, `EmailTemplateDataMap` augmentation, overrides), the layout theme and brand-mark slot, the safe-HTML helpers, the `email` conformance suite and the `describeEmailTransportConformance` kit. [README](src/email/README.md).
+- `@marinoscar/platform-api/jobs` and `@marinoscar/platform-api/jobs/testing`: the background job queue (#734): `JobsModule.forRoot()`, enqueue with active dedup, the one-statement claim, leases, the terminal state machine, the worker pool, the lease reaper and the temp-file janitor, the `JobHandler` contract and `JobHandlerRegistry`, the label registry, `JobScope`, `enqueueHousekeepingJob`, `job.settled`, `org_id` on jobs and the `/api/admin/jobs` routes; the testing entry holds the `on-event-no-io` suite and the handler kit (`createFakeJobQueue`, `describeJobHandlerConformance`). [README](src/jobs/README.md).
+- `@marinoscar/platform-api/nodes`: the worker-node fleet (#734): `NodesModule.forRoot()`, `NodeCredentialModule` (`nod_` tokens), the node control and data planes (`NODE_OBJECT_STORE`), the brokered per-job secret, the fleet admin routes, sweeps and gauges, and the `nodes.node.offline` event. [README](src/nodes/README.md).
+- `@marinoscar/platform-api/storage` and `@marinoscar/platform-api/storage/testing`: object storage (#736): `StorageModule.forRoot()`, `STORAGE_PROVIDER` (the S3 driver configured per call from runtime settings; the rung-3 override), the objects API, the storage-config admin routes and Doctor checks, the object-processor registry, the key-prefix registry with scopes and org-aware keys (`buildObjectKey`, `allKeyPrefixes`, `orgKeyPrefixes`), `runStoragePurge`, `ProfileImageModule.forRoot()`, `nodeObjectStoreBinding` and the `storage` conformance suite. [README](src/storage/README.md).
+- `@marinoscar/platform-api/exports` and `@marinoscar/platform-api/exports/testing`: data export (#744): `ExportsModule.forRoot()`, the source and writer registries (`registerExportSource`, `registerExportWriter`), the `user-data` and `org-data` sources driven by the user-owned and ownership registries, the `json`, `csv` and `xlsx` writers, the CSV helpers, the `Exporter`/`ExporterRegistry` document primitives, the `export.run` and `export.purge` jobs, `/api/exports` and the `exports` conformance suite (secret egress). [README](src/exports/README.md).
+- `@marinoscar/platform-api/ai` and `@marinoscar/platform-api/ai/testing`: the AI platform (#739): `AiModule.forRoot()` with its host ports (`AI_SYSTEM_PRISMA`, `AI_OBJECT_STORE`, `AI_METRICS`), `AiService.forUser` and the gate pipeline, the five provider adapters (their SDKs confined to `ai/providers/`), the model catalogue, the `ai` settings namespaces with the org layer, the user, organization and deployment key tiers, per-org caps and usage, the feature registry (`registerAiFeature`), `AI_TARGET_RESOLVER`, and the fake provider, runtime harness, adapter conformance kit and orchestration-boundary suite. [README](src/ai/README.md).
+- `@marinoscar/platform-api/db-backup` and `@marinoscar/platform-api/db-backup/testing`: database backup and restore (#740): `DbBackupModule.forRoot()` (deployment-mode aware: `saas` turns in-app restore off), the streaming `pg_dump` engine, schedule and retention, the restore with its read-only pre-flight (the `rls_bypass` gate) and the `RestoreCarryOver` registry, the four job types, the per-job role broker, the host ports and the `db-backup` conformance suite. [README](src/db-backup/README.md).
+- `@marinoscar/platform-api/telemetry` and `@marinoscar/platform-api/telemetry/testing`: the API side of observability: the `telemetry` settings and runtime export gate, the runtime GreptimeDB connection, the explorer, the AI assistant, the dashboard with its metric-group registry and health verdict, the stack-agent surface, two server-only job types, five Doctor checks and a support-bundle section; the `telemetry` conformance suite. [README](src/telemetry/README.md).
+- `@marinoscar/platform-api/sharing` and `@marinoscar/platform-api/sharing/testing`: sharing primitives: groups, members and invites inside an organization, the ownership contract, grants (user, group and link), `AccessPolicy`, the "resources I can see" query helpers, link shares and the public-route pattern; the `sharing` conformance suite. [README](src/sharing/README.md).
+- `@marinoscar/platform-api/notifications` and `@marinoscar/platform-api/notifications/testing`: the notification framework: the event, channel and template registries, the dispatcher and its policy (system, then organization), the email, in-app and Web Push channels, runtime Web Push keys, admin broadcasts and the SSE stream; the `notifications` conformance suite. [README](src/notifications/README.md).
+- `@marinoscar/platform-api/android-app` and `@marinoscar/platform-api/android-app/testing`: the server half of the Android companion: trusted apps and the Digital Asset Links route, hosted APK releases, the `android_app` notification channel and the test notification; the conformance suites of its `testing` entry. [README](src/android-app/README.md).
+- `@marinoscar/platform-api/user-data` and `@marinoscar/platform-api/user-data/testing`: the per-user data deletion with scopes, the admin factory reset and organization offboarding, built from the category, scope, keep-or-delete hint, factory-reset step and offboarding-precondition registries; the conformance suites of its `testing` entry. [README](src/user-data/README.md).
+- `@marinoscar/platform-api/manifest`: what every platform slice registers, in registration order (#866): the platform roles and every slice's permission sets in seed order (`PLATFORM_ROLES`, `PLATFORM_PERMISSION_SETS`, `PLATFORM_PERMISSIONS`), `registerPlatformPermissions()` and its pure twin `platformPermissionCatalog()` (both take the app's own roles and permissions and an optional `slices` filter), and the inventory of platform models with a foreign key to `User` (`PLATFORM_USER_OWNED_MODELS`, `registerPlatformUserOwnedModels()`). Data and plain functions, no Nest module. [README](src/manifest/README.md).
+- `@marinoscar/platform-api/host` and `@marinoscar/platform-api/host/testing`: the API host core (#867): `PlatformHostCoreModule.forRoot()` with the cross-replica event bus (`EVENT_BUS`), the platform's `AppMetricsService` and app-metric declarations, maintenance mode (`MaintenanceModeService`, `/api/admin/maintenance`, `MaintenanceGuard` as the platform's `APP_GUARD`, first; an app's own global guard is declared to the `host` suite), the `{ data }` envelope, the request log line, the exception filter and request ids; the OpenAPI document and `/api/docs` (`createOpenApiDocument`, `registerPlatformDocs`); the `host` conformance suite and `FakeEventBusNetwork`. [README](src/host/README.md).
+
+The `core` slice also holds the **host ports** (#696: `definePlatformHost`, `AUDIT_SINK`, `SYSTEM_SETTINGS_STORE`, `PLATFORM_PRISMA`, `PlatformHostModule`), the one mechanism every packaged slice uses to reach app-owned capabilities, with test doubles in `testing`. [Host ports](src/core/README.md#host-ports).
+
+Every slice that has a `testing` entry registers its conformance suites when that entry is imported; `runPlatformConformance()` runs them ([testing README](src/testing/README.md)).
+
+## Install and peer dependencies
+
+```bash
+npm install @marinoscar/platform-api
+```
+
+Install these in the app; the package never bundles its own copy (a second copy breaks dependency injection, hooks or theme context). Which ones depends on the slices you import: only what `core` needs is required, everything else is an optional peer that npm does not install for you ([the rule](../../docs/PACKAGES.md#peer-dependencies-per-slice)). Import slices by their subpath (`@marinoscar/platform-api/telemetry`), never from the package root: the root entry may touch any slice and so would need every peer.
+
+Required by every slice (`core`, with the peers those packages need in turn):
+
+| Package | Range |
+|---|---|
+| `@nestjs/common` | `^11.1.12` |
+| `@nestjs/core` | `^11.1.12` |
+| `@nestjs/swagger` | `^11.2.5` |
+| `@opentelemetry/api` | `^1.9.1` |
+| `@prisma/client` | `^7.8.0` (only `@prisma/client/extension` is imported, by `core`'s scoped data access; no slice imports the generated client) |
+| `nestjs-zod` | `^5.4.0` |
+| `reflect-metadata` | `^0.2.2` |
+| `rxjs` | `^7.8.1` |
+| `zod` | `^4.4.3` |
+
+Optional peers, installed for the slices that need them:
+
+| Package | Range | Needed by |
+|---|---|---|
+| `@nestjs/config` | `^4.0.2` | `telemetry`, `identity`, `settings`, `onboarding`, `jobs`, `nodes`, `storage`, `notifications`, `db-backup`, `host` |
+| `@nestjs/schedule` | `^6.1.0` | `telemetry`, `sharing`, `identity`, `jobs`, `nodes`, `storage`, `exports`, `ai`, `db-backup` |
+| `@nestjs/event-emitter` | `^3.0.1` | `identity`, `jobs`, `nodes`, `storage`, `notifications`, `ai` |
+| `@nestjs/jwt` | `^11.0.2` | `identity`, `host` |
+| `@nestjs/passport` | `^11.0.5` | `identity` |
+| `passport` | `^0.7.0` | `identity` (with `@nestjs/passport`) |
+| `@nestjs/terminus` | `^11.0.0` | `host` (the health controller) |
+| `@prisma/client-runtime-utils` | `^7.8.0` | `jobs`, `ai`, `db-backup` |
+| `fastify` | `^5` | the slices with controllers that read the request or write the reply (types: `doctor`, `otel-core`, `telemetry`, `identity`, `storage`, `ai`, `android-app`, `host`) |
+| `@nestjs/platform-fastify` | `^11.1.12` | the telemetry conformance suite, `@marinoscar/platform-api/telemetry/testing` |
+| `supertest` | `^7.2.2` | the AI conformance suites, `@marinoscar/platform-api/ai/testing` |
+| `@types/supertest` | `^7.2.0` | with `supertest`, for the same suites' declarations |
+
+A slice also needs what the slices it depends on need (`packages/platform-slices.json`): `settings` needs `identity`'s peers, `storage` needs `jobs`' and `nodes`', and so on. The exact set per slice is `packages/platform-slice-peers.json`; `node scripts/check-slice-peers.mjs --table` prints it. For example `core`, `otel-core` and `telemetry` together need the required peers above plus `@nestjs/config`, `@nestjs/schedule` and `fastify`, and nothing else; [`tests/consumer-smoke/api-slim`](../../tests/consumer-smoke/api-slim/) installs exactly that from packed tarballs.
+
+The type packages the published declarations need whatever an app imports (`@types/passport`, `@types/passport-jwt`, `@types/passport-google-oauth20` for the identity slice, `@types/pg` for telemetry) are dependencies, so an app that type-checks its libraries (`skipLibCheck: false`) installs nothing extra. `test/declaration-type-deps.spec.ts` fails on a declaration import the manifest does not cover (#865).
+
+The OpenTelemetry SDK packages the `otel-core` slice installs (`@opentelemetry/sdk-node`, the auto-instrumentations, the OTLP/HTTP exporters and their SDK siblings) are regular dependencies, not peers: only `@opentelemetry/api`, which holds the process-wide providers, must be a single shared copy.
+
+## Quick start
+
+Run the platform's conformance suites from a spec of your own (the reference app's is [`apps/api/test/conformance.spec.ts`](../../apps/api/test/conformance.spec.ts)):
+
+```ts
+import { join } from 'node:path';
+import { runPlatformConformance } from '@marinoscar/platform-api/testing';
+
+runPlatformConformance({
+  sourceRoots: [join(__dirname, '..', '..', 'src')],
+  suites: { cronEnqueueOnly: { exempt: EXEMPT, minCronFiles: 8 } },
+});
+```
+
+Declare a registry with `defineRegistry`, register the exception filter and validate the encryption key at bootstrap with `@marinoscar/platform-api/core`; see the [core README](src/core/README.md#quick-start).
+
+## Configuration
+
+None at the package level. Each slice documents its own options: `DoctorModule.forRoot()` in the [doctor README](src/doctor/README.md#configuration), `initializeOtel()` and `OtelMetricsModule` in the [otel-core README](src/otel-core/README.md#configuration), `PlatformHostModule.forRoot()` in the [core README](src/core/README.md#host-ports), the harness in the [testing README](src/testing/README.md#configuration).
+
+## Extension-point catalog
+
+None. The root export is only the package name; the extension points live in the slice catalogs ([core](src/core/README.md#extension-point-catalog), [testing](src/testing/README.md#extension-point-catalog), [doctor](src/doctor/README.md#extension-point-catalog), [otel-core](src/otel-core/README.md#extension-point-catalog)).
+
+The extension ladder and a recipe per extension: [docs/EXTENDING.md](../../docs/EXTENDING.md).
+
+## Data
+
+None yet. A slice that owns models documents them here and in its own README; the schema fragments and migrations ship in `@marinoscar/platform-db`.
+
+## Permissions and settings
+
+The `doctor` slice requires `system_settings:read` by default and declares no permission of its own ([README](src/doctor/README.md#permissions-and-settings)). Other slices declare theirs in their own README as they are extracted.
+
+## UI
+
+None. Pages and settings cards live in `@marinoscar/platform-web`.
+
+## Infra
+
+Compose, nginx and collector configuration live in `@marinoscar/platform-infra`. The package reads `SECRETS_ENCRYPTION_KEY` (the `core` slice's secret cipher, see the [core README](src/core/README.md#configuration)) and, in the `otel-core` slice, the existing OpenTelemetry variables (`OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_DEBUG`); it exports OTLP/HTTP to the collector ([otel-core README](src/otel-core/README.md#infra)) and adds no variable.
+
+## Observability
+
+The `doctor` slice logs one `warn` line when a check throws; `core` logs one `debug` line when it freezes the static registries, one line per handled error and the encryption-key startup check ([core README](src/core/README.md#observability)). Packaged code logs through Nest's `Logger`, which the app routes to its own logger. `otel-core` installs the OpenTelemetry SDK (when `OTEL_ENABLED=true`) and exports only what its runtime gate lets through ([README](src/otel-core/README.md#observability)). Other slices document theirs as they are extracted.
+
+## Security notes
+
+Every packaged controller takes the app's auth decorators through the host access port (`definePlatformHost`) rather than ship its own, and every `forRoot` refuses to build one without a host, so a packaged route is never public. The one route so far, `GET /api/admin/doctor`, is read-only and requires `system_settings:read` by default. The `core` slice also holds the secret cipher and the exception filter; their key handling, the module-scope key cache (install exactly one copy of the package) and the error-body rules are in the [core README](src/core/README.md#security-notes).
+
+## Conformance suite
+
+The harness is the `testing` slice: `runPlatformConformance()` from `@marinoscar/platform-api/testing` runs the platform's suites in any app: `cron-enqueue-only`, `user-owned-data`, and the suites a slice ships in its `testing` entry (`on-event-no-io` with the jobs slice; the AI kill switch, RBAC matrix, secret egress, key policy, jobs server-only, no-SDK-leak and orchestration-boundary suites with the AI slice; one per slice besides). The [testing README](src/testing/README.md#conformance-suite) lists every suite id.
+
+## Upgrade notes
+
+None. No version has been published yet, so there is nothing to migrate from.
+
+## Troubleshooting
+
+None yet. Build and import problems common to every platform package are in [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages).
+
+## Links
+
+- [Platform packages spec](../../docs/specs/platform-packages.md): the extension contract and the package documentation standard
+- [Package documentation standard and checks](../../docs/PACKAGES.md): how this README, the TSDoc and the catalog are checked
+- [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages): build, test and lint commands

package/dist/ai/ai.constants.d.ts

@@ -0,0 +1,8 @@
+export declare const PERMISSIONS: Readonly<{
+    readonly AI_CONFIG_READ: "ai_config:read";
+    readonly AI_CONFIG_WRITE: "ai_config:write";
+    readonly AI_USE: "ai:use";
+    readonly ORG_AI_CONFIG_READ: "org_ai_config:read";
+    readonly ORG_AI_CONFIG_WRITE: "org_ai_config:write";
+}>;
+//# sourceMappingURL=ai.constants.d.ts.map

package/dist/ai/ai.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.constants.d.ts","sourceRoot":"","sources":["../../src/ai/ai.constants.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,WAAW;;;;;;EAMb,CAAC"}

package/dist/ai/ai.constants.js

@@ -0,0 +1,16 @@
+"use strict";
+// Internal: the names the AI platform's own code has always used for its
+// permission ids (`PERMISSIONS.AI_USE`), bound to the slice's declarations.
+// Not exported from the slice: the public name is `AI_PERMISSIONS`
+// (./ai.permissions.ts), and the app's own `PERMISSIONS` covers every slice.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSIONS = void 0;
+const ai_permissions_1 = require("./ai.permissions");
+exports.PERMISSIONS = Object.freeze({
+    AI_CONFIG_READ: ai_permissions_1.AI_PERMISSIONS.AI_CONFIG_READ.id,
+    AI_CONFIG_WRITE: ai_permissions_1.AI_PERMISSIONS.AI_CONFIG_WRITE.id,
+    AI_USE: ai_permissions_1.AI_PERMISSIONS.AI_USE.id,
+    ORG_AI_CONFIG_READ: ai_permissions_1.AI_PERMISSIONS.ORG_AI_CONFIG_READ.id,
+    ORG_AI_CONFIG_WRITE: ai_permissions_1.AI_PERMISSIONS.ORG_AI_CONFIG_WRITE.id,
+});
+//# sourceMappingURL=ai.constants.js.map

package/dist/ai/ai.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.constants.js","sourceRoot":"","sources":["../../src/ai/ai.constants.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,mEAAmE;AACnE,6EAA6E;;;AAE7E,qDAAkD;AAErC,QAAA,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,cAAc,EAAE,+BAAc,CAAC,cAAc,CAAC,EAAE;IAChD,eAAe,EAAE,+BAAc,CAAC,eAAe,CAAC,EAAE;IAClD,MAAM,EAAE,+BAAc,CAAC,MAAM,CAAC,EAAE;IAChC,kBAAkB,EAAE,+BAAc,CAAC,kBAAkB,CAAC,EAAE;IACxD,mBAAmB,EAAE,+BAAc,CAAC,mBAAmB,CAAC,EAAE;CAClD,CAAC,CAAC"}

package/dist/ai/ai.module.d.ts

@@ -0,0 +1,89 @@
+import { DynamicModule, type ForwardReference, type Type } from '@nestjs/common';
+import type { PortBinding } from '../core/index';
+import { type AiPricing } from './ports';
+import './providers/builtin-ai-providers';
+/**
+ * A provider id accepted by {@link AiModuleOptions.providers}: any id
+ * registered with `registerAiProvider`.
+ *
+ * @deprecated Since PP-14.6 (#924) the provider list is open: this is `string`,
+ *   kept as an alias for one release.
+ * @stability experimental
+ */
+export type AiProviderModuleId = string;
+/**
+ * Options of {@link AiModule.forRoot}. No option is an environment variable:
+ * keys, models and limits are runtime configuration (the `ai` settings
+ * namespace and the credential stores).
+ *
+ * @stability experimental
+ */
+export interface AiModuleOptions {
+    /**
+     * The ids of the providers whose modules to load. Default: every provider
+     * registered with `registerAiProvider` when `forRoot` is called (the five
+     * built-ins, and an app's or package's own: register them first, at import
+     * time). An unloaded provider is simply absent from the adapter registry
+     * (its settings slot stays, inert). An id with no registered definition
+     * throws, naming the registered ones.
+     */
+    readonly providers?: readonly string[];
+    /**
+     * The modules binding the slice's host ports (`AI_SYSTEM_PRISMA`,
+     * `AI_OBJECT_STORE`, optionally `AI_METRICS` and `AI_TARGET_RESOLVER`).
+     * Each must be `@Global()`, since every sub-module injects them.
+     */
+    readonly imports?: ReadonlyArray<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * Whether users may pick their own default model (the `ai.defaultModel`
+     * user setting). Default `true`. `false` for an app whose AI features pick
+     * their model themselves (an `AI_TARGET_RESOLVER`): the default resolver
+     * then ignores the setting and `GET /api/ai/config` reports
+     * `perUserDefaultModel: false`, so the web hides the picker.
+     */
+    readonly perUserDefaultModel?: boolean;
+    /**
+     * The deployment's price list (PP-14.17, #935): turns recorded usage into a
+     * cost, shown as a Cost column on the usage pages. `useExisting` names a
+     * provider a module in `imports` exports; `useClass` and `useFactory` take
+     * their dependencies from `imports` and the global modules. Bound here and
+     * not in an app module because Nest resolves a token from the consuming
+     * module's own providers and imports, so an app-level provider would be
+     * invisible to the usage service. Absent: no cost anywhere (the platform
+     * ships no rates).
+     *
+     * @example
+     * ```ts
+     * AiModule.forRoot({ imports: [AiHostModule], pricing: { useClass: RateCardPricing } });
+     * ```
+     */
+    readonly pricing?: PortBinding<AiPricing>;
+}
+/**
+ * The AI platform's root module (epic #419; packaged by #739).
+ *
+ * Deliberately just a list of imports: core, the provider modules, catalog,
+ * config, keys, runtime, HTTP and usage, each a module of its own. A feature
+ * module of the app imports the one configured `AiModule` and injects
+ * `AiService`.
+ *
+ * @example
+ * ```ts
+ * export const AiModule = PlatformAiModule.forRoot({ imports: [AiHostModule] });
+ * ```
+ *
+ * @stability experimental
+ */
+export declare class AiModule {
+    /**
+     * The configured module. Call once and import that object everywhere.
+     *
+     * @param options - the provider list and the host-port modules.
+     * @returns the dynamic module, exporting `AiCoreModule`, `AiConfigModule` and `AiRuntimeModule`.
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options?: AiModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=ai.module.d.ts.map

package/dist/ai/ai.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.module.d.ts","sourceRoot":"","sources":["../../src/ai/ai.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,KAAK,gBAAgB,EAAiB,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEhH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAUrD,OAAO,kCAAkC,CAAC;AAK1C;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC,CAAC;IAC5G;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;CAC3C;AAkCD;;;;;;;;;;;;;;GAcG;AACH,qBACa,QAAQ;IACnB;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,eAAoB,GAAG,aAAa;CAkC7D"}

package/dist/ai/ai.module.js

@@ -0,0 +1,117 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AiOptionsModule_1, AiModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiModule = void 0;
+const common_1 = require("@nestjs/common");
+const ai_options_1 = require("./ai.options");
+const ports_1 = require("./ports");
+const ai_catalog_module_1 = require("./catalog/ai-catalog.module");
+const ai_config_module_1 = require("./config/ai-config.module");
+const ai_core_module_1 = require("./core/ai-core.module");
+const ai_features_module_1 = require("./features/ai-features.module");
+const ai_http_module_1 = require("./http/ai-http.module");
+const ai_keys_module_1 = require("./keys/ai-keys.module");
+const ai_provider_definition_1 = require("./providers/ai-provider-definition");
+// Registers the five built-in providers (side effect) before the registry is read.
+require("./providers/builtin-ai-providers");
+const ai_runtime_module_1 = require("./runtime/ai-runtime.module");
+const ai_storage_key_prefixes_1 = require("./storage/ai-storage-key-prefixes");
+const ai_usage_module_1 = require("./usage/ai-usage.module");
+/** Holds the resolved options for every AI module (global, so no import edge is needed). */
+let AiOptionsModule = AiOptionsModule_1 = class AiOptionsModule {
+    static of(options, pricing, imports = []) {
+        return {
+            module: AiOptionsModule_1,
+            // The app's host modules are imported here too, so a `useExisting` /
+            // `useClass` pricing binding resolves its dependencies from them.
+            imports: pricing ? [...imports] : [],
+            providers: [
+                { provide: ai_options_1.AI_MODULE_OPTIONS, useValue: options },
+                ...(pricing ? [{ provide: ports_1.AI_PRICING, ...pricing }] : []),
+            ],
+            exports: [ai_options_1.AI_MODULE_OPTIONS, ...(pricing ? [ports_1.AI_PRICING] : [])],
+        };
+    }
+};
+AiOptionsModule = AiOptionsModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], AiOptionsModule);
+/** The binding must be one of Nest's three provider shapes, or boot fails naming the option. */
+function assertPortBinding(name, binding) {
+    const shapes = ['useExisting', 'useClass', 'useFactory'].filter((key) => key in binding);
+    if (shapes.length !== 1) {
+        throw new Error(`AiModule.forRoot({ ${name} }): bind it with exactly one of useExisting, useClass or useFactory.`);
+    }
+}
+/**
+ * The AI platform's root module (epic #419; packaged by #739).
+ *
+ * Deliberately just a list of imports: core, the provider modules, catalog,
+ * config, keys, runtime, HTTP and usage, each a module of its own. A feature
+ * module of the app imports the one configured `AiModule` and injects
+ * `AiService`.
+ *
+ * @example
+ * ```ts
+ * export const AiModule = PlatformAiModule.forRoot({ imports: [AiHostModule] });
+ * ```
+ *
+ * @stability experimental
+ */
+let AiModule = AiModule_1 = class AiModule {
+    /**
+     * The configured module. Call once and import that object everywhere.
+     *
+     * @param options - the provider list and the host-port modules.
+     * @returns the dynamic module, exporting `AiCoreModule`, `AiConfigModule` and `AiRuntimeModule`.
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const wanted = options.providers ?? ai_provider_definition_1.aiProviderKind.ids();
+        // Throws PluggableUnknownError for an unregistered id, naming it, the
+        // registered ids and how to register one.
+        const providers = [...new Set(wanted)].map((id) => (0, ai_provider_definition_1.requireAiProviderDefinition)(id));
+        // The slice's own object-key prefix (`ai-outputs/`), with the storage
+        // slice's registry; a no-op when the app's manifest registered it already.
+        (0, ai_storage_key_prefixes_1.registerAiStorageKeyPrefixes)();
+        if (options.pricing)
+            assertPortBinding('pricing', options.pricing);
+        const resolved = Object.freeze({
+            perUserDefaultModel: options.perUserDefaultModel ?? ai_options_1.DEFAULT_AI_OPTIONS.perUserDefaultModel,
+        });
+        return {
+            module: AiModule_1,
+            imports: [
+                AiOptionsModule.of(resolved, options.pricing, options.imports),
+                ...(options.imports ?? []),
+                ai_core_module_1.AiCoreModule,
+                ...providers.map((definition) => definition.module),
+                ai_catalog_module_1.AiCatalogModule,
+                ai_config_module_1.AiConfigModule,
+                ai_keys_module_1.AiKeysModule,
+                ai_runtime_module_1.AiRuntimeModule,
+                ai_http_module_1.AiHttpModule,
+                ai_usage_module_1.AiUsageModule,
+                // #739: `GET /api/ai/features`. Last, so the routes before it keep their OpenAPI order.
+                ai_features_module_1.AiFeaturesModule,
+            ],
+            // `AiRuntimeModule` is re-exported so a feature module can simply
+            // `imports: [AiModule]` and inject `AiService`.
+            exports: [ai_core_module_1.AiCoreModule, ai_config_module_1.AiConfigModule, ai_runtime_module_1.AiRuntimeModule],
+        };
+    }
+};
+exports.AiModule = AiModule;
+exports.AiModule = AiModule = AiModule_1 = __decorate([
+    (0, common_1.Module)({})
+], AiModule);
+//# sourceMappingURL=ai.module.js.map

package/dist/ai/ai.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.module.js","sourceRoot":"","sources":["../../src/ai/ai.module.ts"],"names":[],"mappings":"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"}

package/dist/ai/ai.options.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Injection token of the resolved {@link AiResolvedOptions}, provided
+ * globally by `AiModule.forRoot`. Optional everywhere: a unit test that
+ * builds a service by hand gets the defaults.
+ *
+ * @stability experimental
+ */
+export declare const AI_MODULE_OPTIONS: unique symbol;
+/**
+ * The options every AI service reads at run time.
+ *
+ * @stability experimental
+ */
+export interface AiResolvedOptions {
+    /**
+     * Whether a user may pick their own default model (the `ai.defaultModel`
+     * user setting). `false`: the default target resolver ignores it, and
+     * `GET /api/ai/config` says so, so the web hides the picker.
+     */
+    readonly perUserDefaultModel: boolean;
+}
+/**
+ * The defaults: every option as before #739.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_AI_OPTIONS: AiResolvedOptions;
+//# sourceMappingURL=ai.options.d.ts.map

package/dist/ai/ai.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.options.d.ts","sourceRoot":"","sources":["../../src/ai/ai.options.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA6D,CAAC;AAErG;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAAgE,CAAC"}

package/dist/ai/ai.options.js

@@ -0,0 +1,19 @@
+"use strict";
+// The AI slice's resolved forRoot options, as a token (issue #739).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AI_OPTIONS = exports.AI_MODULE_OPTIONS = void 0;
+/**
+ * Injection token of the resolved {@link AiResolvedOptions}, provided
+ * globally by `AiModule.forRoot`. Optional everywhere: a unit test that
+ * builds a service by hand gets the defaults.
+ *
+ * @stability experimental
+ */
+exports.AI_MODULE_OPTIONS = Symbol.for('@marinoscar/platform/ai/MODULE_OPTIONS');
+/**
+ * The defaults: every option as before #739.
+ *
+ * @stability experimental
+ */
+exports.DEFAULT_AI_OPTIONS = Object.freeze({ perUserDefaultModel: true });
+//# sourceMappingURL=ai.options.js.map

package/dist/ai/ai.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.options.js","sourceRoot":"","sources":["../../src/ai/ai.options.ts"],"names":[],"mappings":";AAAA,oEAAoE;;;AAEpE;;;;;;GAMG;AACU,QAAA,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;AAgBrG;;;;GAIG;AACU,QAAA,kBAAkB,GAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC"}

package/dist/ai/ai.permissions.d.ts

@@ -0,0 +1,42 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares: core's `PermissionDeclaration`, the
+ * entry type of the permission registry (`registerPermissions`).
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability stable
+ */
+export type AiPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The AI slice's permissions, keyed by the `PERMISSIONS` constant name the
+ * reference app derives from them:
+ *
+ * - `ai_config:read` / `ai_config:write` (system): the deployment-wide `ai`
+ *   policy, the deployment's provider keys, the model catalogue and the
+ *   deployment-wide usage report.
+ * - `ai:use` (org): call AI.
+ * - `org_ai_config:read` / `org_ai_config:write` (org, #739): one
+ *   organization's own provider keys (`/api/admin/ai/org-keys`), its usage
+ *   report and its `ai` org-settings layer.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(AI_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const AI_PERMISSIONS: {
+    /** `ai_config:read`. */
+    readonly AI_CONFIG_READ: AiPermissionDeclaration<'ai_config:read'>;
+    /** `ai_config:write`. */
+    readonly AI_CONFIG_WRITE: AiPermissionDeclaration<'ai_config:write'>;
+    /** `ai:use`. */
+    readonly AI_USE: AiPermissionDeclaration<'ai:use'>;
+    /** `org_ai_config:read`. */
+    readonly ORG_AI_CONFIG_READ: AiPermissionDeclaration<'org_ai_config:read'>;
+    /** `org_ai_config:write`. */
+    readonly ORG_AI_CONFIG_WRITE: AiPermissionDeclaration<'org_ai_config:write'>;
+};
+//# sourceMappingURL=ai.permissions.d.ts.map

package/dist/ai/ai.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.permissions.d.ts","sourceRoot":"","sources":["../../src/ai/ai.permissions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAE5F;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B,wBAAwB;IACxB,QAAQ,CAAC,cAAc,EAAE,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;IACnE,yBAAyB;IACzB,QAAQ,CAAC,eAAe,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IACrE,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,4BAA4B;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAC3E,6BAA6B;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,qBAAqB,CAAC,CAAC;CAoG9E,CAAC"}