@ultimat3/core 27.10.4 → 27.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.10.4",
+  "version": "27.12.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "27.10.4"
+    "@ultimat3/schema": "27.12.0"
   }
 }

package/src/config-defaults.ts

@@ -2,7 +2,12 @@
 // Split from `config.ts`, which sits at its 500-line ceiling; literals only, so it reads no key.
 
 import type { AppConfig } from './config';
-import { JOBS_CONCURRENCY_DEFAULT } from './config-jobs';
+import {
+  JOBS_CONCURRENCY_DEFAULT,
+  JOBS_DEAD_RETENTION_MS_DEFAULT,
+  JOBS_DONE_RETENTION_MS_DEFAULT,
+  JOBS_OUTBOX_RETENTION_MS_DEFAULT,
+} from './config-jobs';
 import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline';
 import { defaultReadinessGraceMs } from './lifecycle-grace';
 import { ROLES } from './roles';
@@ -31,6 +36,9 @@ export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
       maxAttempts: 5,
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
+      doneRetentionMs: JOBS_DONE_RETENTION_MS_DEFAULT,
+      deadRetentionMs: JOBS_DEAD_RETENTION_MS_DEFAULT,
+      outboxRetentionMs: JOBS_OUTBOX_RETENTION_MS_DEFAULT,
     },
     // ON by default since 22.0.0, when the boot began obeying the key: an app with no section
     // keeps the `sync` node it always got, and `enabled: false` is the explicit opt-out.

package/src/config-jobs.ts

@@ -14,6 +14,26 @@ import { isJsonObject } from './json-object';
  */
 export const JOBS_CONCURRENCY_DEFAULT = 8;
 
+/**
+ * `jobs.doneRetentionMs` when no layer says: how long a `done` row and its step records are kept
+ * before the boot's hourly purge deletes them. Two weeks — every incident is read inside it, and
+ * a finished row is bookkeeping, unlike an inbox message: a `mail.send` input is an address and a
+ * rendered body, personal data with no reason to outlive the delivery.
+ */
+export const JOBS_DONE_RETENTION_MS_DEFAULT = 14 * 86_400_000;
+
+/**
+ * `jobs.deadRetentionMs` when no layer says: `dead`, `failed` and `cancelled` rows, which staff
+ * read to explain a failure, kept a quarter.
+ */
+export const JOBS_DEAD_RETENTION_MS_DEFAULT = 90 * 86_400_000;
+
+/**
+ * `jobs.outboxRetentionMs` when no layer says: a PUBLISHED `x_outbox` row, whose job is already in
+ * `x_jobs`, kept a week. An unpublished row is never swept, whatever this says.
+ */
+export const JOBS_OUTBOX_RETENTION_MS_DEFAULT = 7 * 86_400_000;
+
 /** One slot count for every queue, or slots per queue name — `jobWorker`'s own `concurrency`. */
 export type JobsConcurrency = number | Readonly<Record<string, number>>;
 

package/src/config.ts

@@ -163,6 +163,17 @@ export interface JobsConfig {
   readonly maxAttempts: number;
   readonly backoff: (typeof JOB_BACKOFFS)[number];
   readonly visibilityTimeoutMs: number;
+  /**
+   * Age past which the hourly purge deletes a `done` row and its steps. Unset: 14 days
+   * (`JOBS_DONE_RETENTION_MS_DEFAULT`). OPTIONAL, as `realtime.maxSocketsPerActor` is, so a
+   * `JobsConfig` literal written before the key existed still type-checks: `defineConfig` fills it
+   * in, and the boot (`runtime-jobs-retention.ts`) resolves the same constant for one that did not.
+   */
+  readonly doneRetentionMs?: number | undefined;
+  /** The same for `dead`, `failed` and `cancelled` rows. Unset: 90 days. */
+  readonly deadRetentionMs?: number | undefined;
+  /** Age of `published_at` past which a PUBLISHED `x_outbox` row goes. Unset: 7 days. */
+  readonly outboxRetentionMs?: number | undefined;
 }
 
 /**
@@ -274,6 +285,9 @@ function validate(config: AppConfig): void {
     ...jobsConcurrencyIssues(config.jobs.concurrency),
     countIssue('jobs.maxAttempts', config.jobs.maxAttempts, 1),
     countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
+    ...(['doneRetentionMs', 'deadRetentionMs', 'outboxRetentionMs'] as const).map((key) =>
+      config.jobs[key] === undefined ? undefined : countIssue(`jobs.${key}`, config.jobs[key], 1),
+    ),
     oneOfIssue('jobs.backoff', config.jobs.backoff, JOB_BACKOFFS),
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
     oneOfIssue('database.driver', config.database.driver, DATABASE_DRIVERS),

package/src/index.ts

@@ -146,7 +146,13 @@ export type { AiConfig, AiConfigInput, McpConfig } from './config-ai';
 export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
 export { READINESS_MODES } from './config-health';
 export type { IslandsConfig, IslandsSection, IslandsSectionInput } from './config-islands';
-export { JOBS_CONCURRENCY_DEFAULT, type JobsConcurrency } from './config-jobs';
+export {
+  JOBS_CONCURRENCY_DEFAULT,
+  JOBS_DEAD_RETENTION_MS_DEFAULT,
+  JOBS_DONE_RETENTION_MS_DEFAULT,
+  JOBS_OUTBOX_RETENTION_MS_DEFAULT,
+  type JobsConcurrency,
+} from './config-jobs';
 export type {
   MailConfig,
   MailRetainMimeConfig,
@@ -675,6 +681,7 @@ export { setLogSink } from './logger';
 export {
   isMcpExposed,
   type McpAnnotationHints,
+  type McpEffect,
   type McpExposureDeclaration,
   type McpListFilterOp,
   type McpListParams,

package/src/mcp-exposure.ts

@@ -14,6 +14,15 @@ export interface McpAnnotationHints {
   readonly openWorldHint?: boolean;
 }
 
+/**
+ * What an exposed action DOES, for a surface that dispatches by it (`@ultimat3/mcp`'s
+ * `surface: 'meta-split'`): `'write'` creates or changes app state, reversibly or within a
+ * standing budget; `'delete'` archives, cancels or deletes, sends something outside the app, or
+ * commits money. A query is a read and declares none. No default: a wrong one either hides a
+ * deletion behind an ordinary write or asks deletion-grade consent for an update.
+ */
+export type McpEffect = 'write' | 'delete';
+
 /** One comparison a list filter accepts. A filter key is `<field><op>`: `status_eq`. */
 export type McpListFilterOp = '_eq' | '_in' | '_gt' | '_lt' | '_cont';
 
@@ -64,6 +73,12 @@ export interface McpExposureDeclaration {
    * nothing, `openWorldHint: true` for one that reaches outside the app.
    */
   readonly annotations?: McpAnnotationHints;
+  /**
+   * The action's effect class — required for an action a `'meta-split'` surface groups
+   * (`X_MCP_EFFECT_UNDECLARED`), refused on a query (`X_MCP_EFFECT_CONFLICT`). Picks
+   * `write_resource` or `delete_resource`; ignored by every other surface.
+   */
+  readonly effect?: McpEffect;
   /** A list query's whitelist, carried to the tool for the meta surface. Never an action's. */
   readonly listParams?: McpListParams;
 }