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

package/dist/telemetry/telemetry.options.js

@@ -0,0 +1,302 @@
+"use strict";
+// =============================================================================
+// TelemetryModule.forRoot options (issue #703, PP-4.2; Extension Contract rung 1)
+// =============================================================================
+//
+// What an app configures when it imports the telemetry slice:
+//
+//   host          the app's access decorators (`definePlatformHost`, issue
+//                 #696): every packaged route is guarded by them, so a
+//                 telemetry route authenticates and authorizes exactly as an
+//                 app route does.
+//   imports       the modules exporting the host-port providers (./ports.ts);
+//                 the reference app passes its `TelemetryHostModule`.
+//   metricGroups  extra dashboard metric groups, registered after the six
+//                 platform groups.
+//   actorId       how a route reads the caller's user id off the request
+//                 (default: `request.requestUser.id ?? request.user.id`, the
+//                 reference app's `@CurrentUser('id')`).
+//   dashboard     `verdictThresholds`: deep-merged over
+//                 `DEFAULT_VERDICT_THRESHOLDS` (zod-validated); `verdictPolicy`:
+//                 what `VERDICT_POLICY` is bound to (rung 3; default
+//                 `DefaultVerdictPolicy`).
+//   store         the id of the telemetry store the slice queries (default
+//                 `greptime`): a store registered with `registerTelemetryStore`
+//                 before `forRoot` runs (PP-14.11).
+//   assistant     `extraInstructions`: notes from the app's developers appended to
+//                 the assistant's system prompt (PP-14.18), above the rules
+//                 they cannot override.
+//   metrics       `freshMs`: how much older than its table's newest reading a
+//                 `last` cell (and an uptime check) may be and still count as
+//                 current (default `METRIC_FRESH_MS`, 150 s).
+//
+// Validated once, in `forRoot`: a bad option fails boot with a message naming
+// it.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS = exports.TELEMETRY_METRIC_FRESH_MS = exports.TELEMETRY_VERDICT_THRESHOLDS = exports.TELEMETRY_OPTIONS = void 0;
+exports.resolveMetricFreshMs = resolveMetricFreshMs;
+exports.resolveVerdictThresholds = resolveVerdictThresholds;
+exports.resolveAssistantExtraInstructions = resolveAssistantExtraInstructions;
+exports.defaultTelemetryActorId = defaultTelemetryActorId;
+exports.resolveTelemetryModuleOptions = resolveTelemetryModuleOptions;
+const common_1 = require("@nestjs/common");
+const telemetry_1 = require("@marinoscar/platform-contract/telemetry");
+const zod_1 = require("zod");
+const index_1 = require("../core/index");
+const telemetry_dashboard_verdict_1 = require("./dashboard/telemetry-dashboard.verdict");
+const metric_group_1 = require("./metrics/metric-group");
+// The built-in store registers on import: whatever validates a store id finds it.
+require("./stores/greptime/greptime.store");
+const telemetry_store_1 = require("./stores/telemetry-store");
+/**
+ * Injection token of the {@link ResolvedTelemetryModuleOptions}.
+ *
+ * @stability experimental
+ */
+exports.TELEMETRY_OPTIONS = Symbol.for('@marinoscar/platform/telemetry/OPTIONS');
+/**
+ * Injection token of the resolved {@link VerdictThresholds}: the defaults with
+ * the app's `dashboard.verdictThresholds` deep-merged over them, frozen. Every
+ * reader of a threshold injects this.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.TELEMETRY_VERDICT_THRESHOLDS = Symbol.for('@marinoscar/platform/telemetry/VERDICT_THRESHOLDS');
+/**
+ * Injection token of the metric groups' freshness window in milliseconds: the
+ * app's `metrics.freshMs`, else `METRIC_FRESH_MS`. The dashboard's `/metrics`
+ * route reads it and reports it as the response's `freshMs`.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.TELEMETRY_METRIC_FRESH_MS = Symbol.for('@marinoscar/platform/telemetry/METRIC_FRESH_MS');
+/**
+ * Injection token of the developers' notes appended to the assistant's system
+ * prompt: the app's `assistant.extraInstructions`, or `null`.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS = Symbol.for('@marinoscar/platform/telemetry/ASSISTANT_EXTRA_INSTRUCTIONS');
+/** The bounds of `metrics.freshMs`: one second to one day. */
+const FRESH_MS_MIN = 1_000;
+const FRESH_MS_MAX = 86_400_000;
+/**
+ * The freshness window for an override: validated, else the default.
+ *
+ * @param metrics - the app's `metrics`, or `undefined`.
+ * @returns the window in milliseconds.
+ * @throws Error when `metrics` is not an object or `freshMs` is not a whole number from 1 000 to 86 400 000.
+ *
+ * @stability experimental
+ */
+function resolveMetricFreshMs(metrics) {
+    if (metrics === undefined)
+        return metric_group_1.METRIC_FRESH_MS;
+    if (metrics === null || typeof metrics !== 'object')
+        fail('`metrics` must be an object');
+    const { freshMs } = metrics;
+    if (freshMs === undefined)
+        return metric_group_1.METRIC_FRESH_MS;
+    if (typeof freshMs !== 'number' || !Number.isInteger(freshMs) || freshMs < FRESH_MS_MIN || freshMs > FRESH_MS_MAX) {
+        fail(`\`metrics.freshMs\` must be a whole number of milliseconds from ${FRESH_MS_MIN} to ${FRESH_MS_MAX} (got ${String(freshMs)})`);
+    }
+    return freshMs;
+}
+const amount = zod_1.z.number().finite().nonnegative();
+const count = zod_1.z.number().int().positive();
+const levels = zod_1.z.object({ degraded: amount, critical: amount }).partial().strict();
+/** What a `dashboard.verdictThresholds` override may contain. */
+const verdictThresholdsOverrideSchema = zod_1.z
+    .object({
+    minRequests: zod_1.z.number().int().nonnegative(),
+    errorRatePct: levels,
+    p95Ms: levels,
+    errorLogs: zod_1.z
+        .object({ minCurrent: zod_1.z.number().int().nonnegative(), degradedRatio: amount, criticalRatio: amount })
+        .partial()
+        .strict(),
+    noDataMinutes: zod_1.z.number().finite().positive(),
+    unknownRoutes: zod_1.z.object({ criticalBearerRequests: count, criticalDistinctRoutes: count }).partial().strict(),
+    diskUtilizationPct: levels,
+    memoryUtilizationPct: levels,
+    dbConnectionsPct: levels,
+    oldestPendingJobMinutes: levels,
+    tlsDaysLeft: levels,
+    uptimeMinChecksForCritical: count,
+    collectorFailedPct: zod_1.z.object({ critical: amount }).partial().strict(),
+    backupAgeHours: levels,
+})
+    .partial()
+    .strict();
+/** The `{ degraded, critical }` pairs whose degraded bound must not exceed the critical one (`>`/`>=` rules). */
+const RISING = [
+    'errorRatePct',
+    'p95Ms',
+    'diskUtilizationPct',
+    'memoryUtilizationPct',
+    'dbConnectionsPct',
+    'oldestPendingJobMinutes',
+    'backupAgeHours',
+];
+function deepFreeze(value) {
+    if (value && typeof value === 'object') {
+        for (const inner of Object.values(value))
+            deepFreeze(inner);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * The verdict thresholds for an override: validated, deep-merged over
+ * {@link DEFAULT_VERDICT_THRESHOLDS} and frozen.
+ *
+ * @param override - the app's `dashboard.verdictThresholds`, or `undefined`.
+ * @returns the resolved thresholds.
+ * @throws Error naming every invalid field, or a degraded bound beyond its critical one.
+ *
+ * @stability experimental
+ */
+function resolveVerdictThresholds(override) {
+    const parsed = verdictThresholdsOverrideSchema.safeParse(override ?? {});
+    if (!parsed.success) {
+        const problems = parsed.error.issues
+            .map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+            .join('; ');
+        fail(`\`dashboard.verdictThresholds\` is invalid (${problems})`);
+    }
+    const merged = structuredClone(telemetry_dashboard_verdict_1.DEFAULT_VERDICT_THRESHOLDS);
+    for (const [key, value] of Object.entries(parsed.data)) {
+        if (value === undefined)
+            continue;
+        merged[key] =
+            value !== null && typeof value === 'object'
+                ? { ...merged[key], ...value }
+                : value;
+    }
+    const resolved = merged;
+    for (const key of RISING) {
+        const pair = resolved[key];
+        if (pair.degraded > pair.critical) {
+            fail(`\`dashboard.verdictThresholds.${key}\`: degraded (${pair.degraded}) must not exceed critical (${pair.critical})`);
+        }
+    }
+    if (resolved.tlsDaysLeft.degraded < resolved.tlsDaysLeft.critical) {
+        fail(`\`dashboard.verdictThresholds.tlsDaysLeft\`: degraded (${resolved.tlsDaysLeft.degraded}) must not be below ` +
+            `critical (${resolved.tlsDaysLeft.critical}); fewer days left is worse`);
+    }
+    if (resolved.errorLogs.degradedRatio > resolved.errorLogs.criticalRatio) {
+        fail(`\`dashboard.verdictThresholds.errorLogs\`: degradedRatio (${resolved.errorLogs.degradedRatio}) must not exceed ` +
+            `criticalRatio (${resolved.errorLogs.criticalRatio})`);
+    }
+    return deepFreeze(resolved);
+}
+/**
+ * The assistant's extra instructions for an override: validated, trimmed, else `null`.
+ *
+ * @param assistant - the app's `assistant` option, or `undefined`.
+ * @returns the notes, or `null` when there are none.
+ * @throws Error when `assistant` is not an object, or `extraInstructions` is not a string of at most
+ *   `TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS_MAX` characters without control characters.
+ *
+ * @stability experimental
+ */
+function resolveAssistantExtraInstructions(assistant) {
+    if (assistant === undefined)
+        return null;
+    if (assistant === null || typeof assistant !== 'object')
+        fail('`assistant` must be an object');
+    const { extraInstructions } = assistant;
+    if (extraInstructions === undefined)
+        return null;
+    if (typeof extraInstructions !== 'string')
+        fail('`assistant.extraInstructions` must be a string');
+    const text = extraInstructions.trim();
+    if (text.length > telemetry_1.TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS_MAX) {
+        fail(`\`assistant.extraInstructions\` is at most ${telemetry_1.TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS_MAX} characters (got ${text.length})`);
+    }
+    if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(text)) {
+        fail('`assistant.extraInstructions` must be plain text: no control characters other than a newline or a tab');
+    }
+    return text === '' ? null : text;
+}
+/**
+ * The default caller resolver: the authenticated user's `id`, from
+ * `request.requestUser` (set by the app's guards) or `request.user` (the JWT
+ * strategy's user).
+ *
+ * @param request - the framework request.
+ * @returns the user id, or `undefined`.
+ *
+ * @stability experimental
+ */
+function defaultTelemetryActorId(request) {
+    if (request === null || typeof request !== 'object')
+        return undefined;
+    const { requestUser, user } = request;
+    const id = (requestUser || user)?.id;
+    return typeof id === 'string' ? id : undefined;
+}
+function fail(why) {
+    throw new Error(`TelemetryModule.forRoot: ${why}.`);
+}
+/**
+ * Validates `options` and applies the defaults.
+ *
+ * @param options - what the app passed to `forRoot`.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the bad option.
+ *
+ * @stability experimental
+ */
+function resolveTelemetryModuleOptions(options) {
+    if (options === null || typeof options !== 'object')
+        fail('options are required ({ host, imports })');
+    if (!options.host)
+        fail('`host` is required (the app\'s definePlatformHost(...)): a platform route is never public');
+    const host = (0, index_1.definePlatformHost)(options.host);
+    if (!Array.isArray(options.imports)) {
+        fail('`imports` must list the modules that provide the telemetry host ports (the app\'s TelemetryHostModule)');
+    }
+    if (options.metricGroups !== undefined && !Array.isArray(options.metricGroups))
+        fail('`metricGroups` must be an array');
+    if (options.actorId !== undefined && typeof options.actorId !== 'function')
+        fail('`actorId` must be a function');
+    if (options.dashboard !== undefined && (options.dashboard === null || typeof options.dashboard !== 'object')) {
+        fail('`dashboard` must be an object');
+    }
+    const verdictPolicy = options.dashboard?.verdictPolicy;
+    if (verdictPolicy !== undefined) {
+        const kinds = verdictPolicy && typeof verdictPolicy === 'object'
+            ? ['useExisting', 'useClass', 'useFactory'].filter((k) => k in verdictPolicy)
+            : [];
+        if (kinds.length !== 1)
+            fail('`dashboard.verdictPolicy` needs exactly one of useExisting, useClass or useFactory');
+    }
+    const verdictThresholds = resolveVerdictThresholds(options.dashboard?.verdictThresholds);
+    const metricFreshMs = resolveMetricFreshMs(options.metrics);
+    const assistantExtraInstructions = resolveAssistantExtraInstructions(options.assistant);
+    const store = options.store ?? telemetry_store_1.BUILTIN_TELEMETRY_STORE_ID;
+    if (typeof store !== 'string' || !telemetry_store_1.telemetryStoreKind.has(store)) {
+        fail(`\`store\` ${JSON.stringify(store)} is not a registered telemetry store (registered: ${telemetry_store_1.telemetryStoreKind.ids().join(', ') || '(none)'}). ` +
+            'Register it with registerTelemetryStore at import time, before TelemetryModule.forRoot runs');
+    }
+    const actorId = options.actorId ?? defaultTelemetryActorId;
+    const param = (0, common_1.createParamDecorator)((_data, ctx) => actorId(ctx.switchToHttp().getRequest()));
+    return Object.freeze({
+        host,
+        imports: [...options.imports],
+        metricGroups: Object.freeze([...(options.metricGroups ?? [])]),
+        actorId,
+        actorIdParam: () => param(),
+        verdictThresholds,
+        verdictPolicy,
+        metricFreshMs,
+        store,
+        assistantExtraInstructions,
+    });
+}
+//# sourceMappingURL=telemetry.options.js.map

package/dist/telemetry/telemetry.options.js.map

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

package/dist/telemetry/telemetry.permissions.d.ts

@@ -0,0 +1,64 @@
+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 experimental
+ */
+export type TelemetryPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The telemetry permissions with their descriptions and default grants, keyed
+ * by the `PERMISSIONS` constant name the reference app derives from them.
+ * Register them with the app's permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(TELEMETRY_PERMISSION_DECLARATIONS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const TELEMETRY_PERMISSION_DECLARATIONS: {
+    /** `telemetry:read`: view telemetry settings and status. */
+    readonly TELEMETRY_READ: TelemetryPermissionDeclaration<'telemetry:read'>;
+    /** `telemetry:write`: change telemetry settings. */
+    readonly TELEMETRY_WRITE: TelemetryPermissionDeclaration<'telemetry:write'>;
+    /** `telemetry:query`: run SQL, export, the dashboard and the AI assistant. */
+    readonly TELEMETRY_QUERY: TelemetryPermissionDeclaration<'telemetry:query'>;
+};
+/**
+ * The permission strings the telemetry routes enforce: `READ` (settings and
+ * status), `WRITE` (change them) and `QUERY` (run SQL, export, the dashboard
+ * and the assistant).
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_PERMISSIONS: {
+    /** `telemetry:read`. */
+    readonly READ: 'telemetry:read';
+    /** `telemetry:write`. */
+    readonly WRITE: 'telemetry:write';
+    /** `telemetry:query`. */
+    readonly QUERY: 'telemetry:query';
+};
+/**
+ * Permissions the APP owns that telemetry routes also require; the app must
+ * declare them. `AI_USE`: the assistant spends an AI key (all-of with
+ * `telemetry:query`). `SYSTEM_SETTINGS_READ`/`SYSTEM_SETTINGS_WRITE`: the
+ * stack-agent routes (`/api/admin/telemetry/stack`) are deployment operations
+ * gated like the rest of the system settings.
+ *
+ * @stability experimental
+ */
+export declare const TELEMETRY_HOST_PERMISSIONS: {
+    /** `ai:use`: spend an AI key. */
+    readonly AI_USE: 'ai:use';
+    /** `system_settings:read`. */
+    readonly SYSTEM_SETTINGS_READ: 'system_settings:read';
+    /** `system_settings:write`. */
+    readonly SYSTEM_SETTINGS_WRITE: 'system_settings:write';
+};
+//# sourceMappingURL=telemetry.permissions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.permissions.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.permissions.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,8BAA8B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAEnG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,EAAE;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,8BAA8B,CAAC,gBAAgB,CAAC,CAAC;IAC1E,oDAAoD;IACpD,QAAQ,CAAC,eAAe,EAAE,8BAA8B,CAAC,iBAAiB,CAAC,CAAC;IAC5E,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,8BAA8B,CAAC,iBAAiB,CAAC,CAAC;CAoB7E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE;IAClC,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CAKnC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE;IACvC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,sBAAsB,CAAC;IACtD,+BAA+B;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,uBAAuB,CAAC;CAKzD,CAAC"}

package/dist/telemetry/telemetry.permissions.js

@@ -0,0 +1,85 @@
+"use strict";
+// =============================================================================
+// Telemetry permissions (issue #676, PP-1.4; exported as data by #703)
+// =============================================================================
+//
+// Pure data: the slice's three permissions and their default role grants. The
+// app registers the declarations with its own permission registry (the
+// reference app: the manifest slice (`registerPlatformPermissions()`), which also
+// derives `PERMISSIONS` from them in `common/constants/roles.constants.ts`).
+// The strings never change: they are rows in `permissions` and the exact
+// strings the controllers enforce.
+//
+// ADMIN ONLY, same reasoning as the other operational surfaces: telemetry
+// settings and ad-hoc queries against observability data start as narrow as
+// `db_backup:*`/`ai_config:*` and can be widened later without a migration,
+// since these are rows. THREE permissions, mirroring the `ai_config:*`/`ai:use`
+// split and the `db_backup:*` trio: `READ` and `WRITE` gate the
+// DEPLOYMENT-WIDE policy (whether telemetry is collected, its retention, and
+// the query/assistant bounds). `QUERY` is the separate act of actually running
+// SQL, exporting results, or invoking the AI assistant against telemetry data,
+// an act materially different from reading or changing the policy that
+// governs it.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_HOST_PERMISSIONS = exports.TELEMETRY_PERMISSIONS = exports.TELEMETRY_PERMISSION_DECLARATIONS = void 0;
+/**
+ * The telemetry permissions with their descriptions and default grants, keyed
+ * by the `PERMISSIONS` constant name the reference app derives from them.
+ * Register them with the app's permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(TELEMETRY_PERMISSION_DECLARATIONS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.TELEMETRY_PERMISSION_DECLARATIONS = {
+    TELEMETRY_READ: {
+        id: 'telemetry:read',
+        description: 'View telemetry settings and status',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    TELEMETRY_WRITE: {
+        id: 'telemetry:write',
+        description: 'Change telemetry settings',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    TELEMETRY_QUERY: {
+        id: 'telemetry:query',
+        description: 'Run SQL, export and use the AI assistant against telemetry',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+/**
+ * The permission strings the telemetry routes enforce: `READ` (settings and
+ * status), `WRITE` (change them) and `QUERY` (run SQL, export, the dashboard
+ * and the assistant).
+ *
+ * @stability stable
+ */
+exports.TELEMETRY_PERMISSIONS = {
+    READ: exports.TELEMETRY_PERMISSION_DECLARATIONS.TELEMETRY_READ.id,
+    WRITE: exports.TELEMETRY_PERMISSION_DECLARATIONS.TELEMETRY_WRITE.id,
+    QUERY: exports.TELEMETRY_PERMISSION_DECLARATIONS.TELEMETRY_QUERY.id,
+};
+/**
+ * Permissions the APP owns that telemetry routes also require; the app must
+ * declare them. `AI_USE`: the assistant spends an AI key (all-of with
+ * `telemetry:query`). `SYSTEM_SETTINGS_READ`/`SYSTEM_SETTINGS_WRITE`: the
+ * stack-agent routes (`/api/admin/telemetry/stack`) are deployment operations
+ * gated like the rest of the system settings.
+ *
+ * @stability experimental
+ */
+exports.TELEMETRY_HOST_PERMISSIONS = {
+    AI_USE: 'ai:use',
+    SYSTEM_SETTINGS_READ: 'system_settings:read',
+    SYSTEM_SETTINGS_WRITE: 'system_settings:write',
+};
+//# sourceMappingURL=telemetry.permissions.js.map

package/dist/telemetry/telemetry.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.permissions.js","sourceRoot":"","sources":["../../src/telemetry/telemetry.permissions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uEAAuE;AACvE,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,uEAAuE;AACvE,kFAAkF;AAClF,6EAA6E;AAC7E,yEAAyE;AACzE,mCAAmC;AACnC,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,gFAAgF;AAChF,gEAAgE;AAChE,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AACvE,cAAc;AACd,gFAAgF;;;AAchF;;;;;;;;;;;;GAYG;AACU,QAAA,iCAAiC,GAO1C;IACF,cAAc,EAAE;QACd,EAAE,EAAE,gBAAgB;QACpB,WAAW,EAAE,oCAAoC;QACjD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,eAAe,EAAE;QACf,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,2BAA2B;QACxC,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,eAAe,EAAE;QACf,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,4DAA4D;QACzE,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC;AAEF;;;;;;GAMG;AACU,QAAA,qBAAqB,GAO9B;IACF,IAAI,EAAE,yCAAiC,CAAC,cAAc,CAAC,EAAE;IACzD,KAAK,EAAE,yCAAiC,CAAC,eAAe,CAAC,EAAE;IAC3D,KAAK,EAAE,yCAAiC,CAAC,eAAe,CAAC,EAAE;CAC5D,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,0BAA0B,GAOnC;IACF,MAAM,EAAE,QAAQ;IAChB,oBAAoB,EAAE,sBAAsB;IAC5C,qBAAqB,EAAE,uBAAuB;CAC/C,CAAC"}

package/dist/telemetry/telemetry.settings.d.ts

@@ -0,0 +1,79 @@
+import type { TelemetrySettings } from '@marinoscar/platform-contract/telemetry';
+/**
+ * The namespace key under which the app stores the telemetry policy.
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_SETTINGS_NAMESPACE: "telemetry";
+/**
+ * The namespace's one-line description for the app's settings catalog.
+ *
+ * @stability experimental
+ */
+export declare const TELEMETRY_SETTINGS_DESCRIPTION = "Telemetry policy: whether telemetry is collected, how long it is kept, the bounds of an ad-hoc query, and the AI assistant over it.";
+/**
+ * The namespace's defaults: OFF and INERT, matching every namespace that ships
+ * ahead of its consumers. A fresh deployment does not collect or retain
+ * observability data nobody asked for.
+ *
+ * - `instanceId: null` follows the app's slug, resolved at the point of use,
+ *   so a renamed fork follows its new name until an administrator overrides it.
+ * - `assistant.enabled: false` on top of `enabled: false`: a second, narrower switch.
+ * - `assistant.shareResults: true`: an assistant that cannot see the rows it
+ *   queried cannot explain them; an administrator turns it off deliberately.
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_SETTINGS_DEFAULTS: TelemetrySettings;
+/**
+ * A partial update of the namespace: every field optional, `instanceId`,
+ * `assistant.provider` and `assistant.modelId` nullable (an explicit `null`
+ * clears them).
+ *
+ * @stability experimental
+ */
+export interface TelemetrySettingsPatch {
+    /** Whether telemetry is exported. */
+    enabled?: boolean;
+    /** The store's TTL, in days. */
+    retentionDays?: number;
+    /** The `app.instance.id` label; `null` follows the app's slug. */
+    instanceId?: string | null;
+    /** The bounds of an ad-hoc query. */
+    query?: {
+        /** Rows a query returns at most. */
+        maxRows?: number;
+        /** A query's timeout, seconds. */
+        timeoutSeconds?: number;
+    };
+    /** The telemetry assistant. */
+    assistant?: {
+        /** Whether the assistant is on. */
+        enabled?: boolean;
+        /** Its AI provider; `null` clears it. */
+        provider?: string | null;
+        /** Its model; `null` clears it. */
+        modelId?: string | null;
+        /** Whether row values are shown to the model. */
+        shareResults?: boolean;
+        /** Rows per statement the model sees at most. */
+        maxResultRowsToModel?: number;
+        /** Model round-trips per turn at most. */
+        maxSteps?: number;
+    };
+}
+/**
+ * Merges a patch over the current value, field by field, one level deep into
+ * `query` and `assistant`. An absent field keeps its stored value; the three
+ * NULLABLE fields (`instanceId`, `assistant.provider`, `assistant.modelId`)
+ * take an explicit `null` as "clear" (`!== undefined`, never `??`, or an
+ * operator could never clear a provider once set).
+ *
+ * @param current - the stored value.
+ * @param patch - the update, or `undefined` for none.
+ * @returns the merged value.
+ *
+ * @stability stable
+ */
+export declare function mergeTelemetrySettings(current: TelemetrySettings, patch: TelemetrySettingsPatch | undefined): TelemetrySettings;
+//# sourceMappingURL=telemetry.settings.d.ts.map

package/dist/telemetry/telemetry.settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.settings.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.settings.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAG,WAAoB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,wIAC4F,CAAC;AAExI;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAgBzC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qCAAqC;IACrC,KAAK,CAAC,EAAE;QACN,oCAAoC;QACpC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kCAAkC;QAClC,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,+BAA+B;IAC/B,SAAS,CAAC,EAAE;QACV,mCAAmC;QACnC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,yCAAyC;QACzC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,mCAAmC;QACnC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,iDAAiD;QACjD,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,iDAAiD;QACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,0CAA0C;QAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,sBAAsB,GAAG,SAAS,GACxC,iBAAiB,CAkBnB"}

package/dist/telemetry/telemetry.settings.js

@@ -0,0 +1,92 @@
+"use strict";
+// =============================================================================
+// The `telemetry` system-settings namespace, as data (issue #677; exported by #703)
+// =============================================================================
+//
+// The slice owns the namespace's SHAPE (the contract's `telemetrySettingsSchema`,
+// #702), its defaults and its merge rule; the app declares it in its own
+// settings-namespace registry with these (the reference app:
+// `apps/api/src/platform/telemetry/telemetry.system-settings.ts`), and stores
+// and validates it. Pure data: no Nest, no registry call.
+//
+// NO CREDENTIAL HERE: the assistant's provider key is resolved by the app's AI
+// platform like every other AI call (`TELEMETRY_SETTINGS_CARRIES_NO_SECRET`).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_SETTINGS_DEFAULTS = exports.TELEMETRY_SETTINGS_DESCRIPTION = exports.TELEMETRY_SETTINGS_NAMESPACE = void 0;
+exports.mergeTelemetrySettings = mergeTelemetrySettings;
+/**
+ * The namespace key under which the app stores the telemetry policy.
+ *
+ * @stability stable
+ */
+exports.TELEMETRY_SETTINGS_NAMESPACE = 'telemetry';
+/**
+ * The namespace's one-line description for the app's settings catalog.
+ *
+ * @stability experimental
+ */
+exports.TELEMETRY_SETTINGS_DESCRIPTION = 'Telemetry policy: whether telemetry is collected, how long it is kept, the bounds of an ad-hoc query, and the AI assistant over it.';
+/**
+ * The namespace's defaults: OFF and INERT, matching every namespace that ships
+ * ahead of its consumers. A fresh deployment does not collect or retain
+ * observability data nobody asked for.
+ *
+ * - `instanceId: null` follows the app's slug, resolved at the point of use,
+ *   so a renamed fork follows its new name until an administrator overrides it.
+ * - `assistant.enabled: false` on top of `enabled: false`: a second, narrower switch.
+ * - `assistant.shareResults: true`: an assistant that cannot see the rows it
+ *   queried cannot explain them; an administrator turns it off deliberately.
+ *
+ * @stability stable
+ */
+exports.TELEMETRY_SETTINGS_DEFAULTS = {
+    enabled: false,
+    retentionDays: 30,
+    instanceId: null,
+    query: {
+        maxRows: 10000,
+        timeoutSeconds: 30,
+    },
+    assistant: {
+        enabled: false,
+        provider: null,
+        modelId: null,
+        shareResults: true,
+        maxResultRowsToModel: 100,
+        maxSteps: 15,
+    },
+};
+/**
+ * Merges a patch over the current value, field by field, one level deep into
+ * `query` and `assistant`. An absent field keeps its stored value; the three
+ * NULLABLE fields (`instanceId`, `assistant.provider`, `assistant.modelId`)
+ * take an explicit `null` as "clear" (`!== undefined`, never `??`, or an
+ * operator could never clear a provider once set).
+ *
+ * @param current - the stored value.
+ * @param patch - the update, or `undefined` for none.
+ * @returns the merged value.
+ *
+ * @stability stable
+ */
+function mergeTelemetrySettings(current, patch) {
+    return {
+        enabled: patch?.enabled ?? current.enabled,
+        retentionDays: patch?.retentionDays ?? current.retentionDays,
+        instanceId: patch?.instanceId !== undefined ? patch.instanceId : current.instanceId,
+        query: {
+            maxRows: patch?.query?.maxRows ?? current.query.maxRows,
+            timeoutSeconds: patch?.query?.timeoutSeconds ?? current.query.timeoutSeconds,
+        },
+        assistant: {
+            enabled: patch?.assistant?.enabled ?? current.assistant.enabled,
+            provider: patch?.assistant?.provider !== undefined ? patch.assistant.provider : current.assistant.provider,
+            modelId: patch?.assistant?.modelId !== undefined ? patch.assistant.modelId : current.assistant.modelId,
+            shareResults: patch?.assistant?.shareResults ?? current.assistant.shareResults,
+            maxResultRowsToModel: patch?.assistant?.maxResultRowsToModel ?? current.assistant.maxResultRowsToModel,
+            maxSteps: patch?.assistant?.maxSteps ?? current.assistant.maxSteps,
+        },
+    };
+}
+//# sourceMappingURL=telemetry.settings.js.map

package/dist/telemetry/telemetry.settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.settings.js","sourceRoot":"","sources":["../../src/telemetry/telemetry.settings.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,oFAAoF;AACpF,gFAAgF;AAChF,EAAE;AACF,kFAAkF;AAClF,yEAAyE;AACzE,6DAA6D;AAC7D,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;;;AAqGhF,wDAqBC;AAtHD;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,WAAoB,CAAC;AAEjE;;;;GAIG;AACU,QAAA,8BAA8B,GACzC,qIAAqI,CAAC;AAExI;;;;;;;;;;;;GAYG;AACU,QAAA,2BAA2B,GAAsB;IAC5D,OAAO,EAAE,KAAK;IACd,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE;QACL,OAAO,EAAE,KAAK;QACd,cAAc,EAAE,EAAE;KACnB;IACD,SAAS,EAAE;QACT,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,IAAI;QAClB,oBAAoB,EAAE,GAAG;QACzB,QAAQ,EAAE,EAAE;KACb;CACF,CAAC;AAwCF;;;;;;;;;;;;GAYG;AACH,SAAgB,sBAAsB,CACpC,OAA0B,EAC1B,KAAyC;IAEzC,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,OAAO,IAAI,OAAO,CAAC,OAAO;QAC1C,aAAa,EAAE,KAAK,EAAE,aAAa,IAAI,OAAO,CAAC,aAAa;QAC5D,UAAU,EAAE,KAAK,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU;QACnF,KAAK,EAAE;YACL,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO;YACvD,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,IAAI,OAAO,CAAC,KAAK,CAAC,cAAc;SAC7E;QACD,SAAS,EAAE;YACT,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO;YAC/D,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ;YAC1G,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO;YACtG,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,YAAY;YAC9E,oBAAoB,EAAE,KAAK,EAAE,SAAS,EAAE,oBAAoB,IAAI,OAAO,CAAC,SAAS,CAAC,oBAAoB;YACtG,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC,QAAQ;SACnE;KACF,CAAC;AACJ,CAAC"}