nucleus-core-ts 0.10.199 → 0.10.201

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/.build-ok +1 -1
  2. package/dist/client.js +2 -2
  3. package/dist/dist/index.d.ts +275 -1
  4. package/dist/index.js +48 -34
  5. package/dist/server.js +92 -56
  6. package/dist/src/Client/ApiCaller/system-tables.d.ts +228 -0
  7. package/dist/src/Data/EntityStore.d.ts +6 -0
  8. package/dist/src/Data/StoreQuery.d.ts +5 -19
  9. package/dist/src/Data/StoreReadQuery.d.ts +21 -0
  10. package/dist/src/Data/index.d.ts +4 -0
  11. package/dist/src/Data/journalCapture.d.ts +12 -0
  12. package/dist/src/Data/journalCollect.d.ts +56 -0
  13. package/dist/src/Data/journalConfig.d.ts +26 -0
  14. package/dist/src/Data/journalErase.d.ts +31 -0
  15. package/dist/src/Data/journalFlush.d.ts +32 -0
  16. package/dist/src/Data/journalHost.d.ts +42 -0
  17. package/dist/src/Data/journalImplicit.d.ts +11 -0
  18. package/dist/src/Data/journalReplayKit.d.ts +14 -0
  19. package/dist/src/Data/journalRequest.d.ts +30 -0
  20. package/dist/src/Data/journalTestKit.d.ts +131 -0
  21. package/dist/src/Data/journalTypes.d.ts +79 -0
  22. package/dist/src/Data/journalUpsert.d.ts +16 -0
  23. package/dist/src/Data/nucleusData.d.ts +5 -0
  24. package/dist/src/Data/storeSession.d.ts +6 -0
  25. package/dist/src/Data/storeTypes.d.ts +3 -0
  26. package/dist/src/Data/unitNotify.d.ts +4 -0
  27. package/dist/src/Data/unitTypes.d.ts +10 -1
  28. package/dist/src/Nucleus/routes/entity/entityWrite.d.ts +1 -0
  29. package/dist/src/Nucleus/routes/monitoring/alertHistory.d.ts +18 -0
  30. package/dist/src/Nucleus/routes/monitoring/history.d.ts +51 -0
  31. package/dist/src/Nucleus/routes/monitoring/index.d.ts +5 -0
  32. package/dist/src/Nucleus/routes/monitoring/jobs.d.ts +24 -0
  33. package/dist/src/Nucleus/routes/notification/index.d.ts +3 -0
  34. package/dist/src/Nucleus/routes/verification/buildServices.d.ts +3 -0
  35. package/dist/src/Nucleus/routes/verification/index.d.ts +2 -0
  36. package/dist/src/Server/createNucleusServer.d.ts +16 -0
  37. package/dist/src/Server/journalRequestKit.d.ts +30 -0
  38. package/dist/src/Server/journalRequestRoutes.d.ts +23 -0
  39. package/dist/src/Server/routeAnswer.d.ts +8 -0
  40. package/dist/src/Server/routeInput.d.ts +23 -0
  41. package/dist/src/Server/routeTable.d.ts +34 -0
  42. package/dist/src/Server/router.d.ts +10 -122
  43. package/dist/src/Server/routerTypes.d.ts +138 -0
  44. package/dist/src/Services/Jobs/jobRunHook.d.ts +24 -0
  45. package/dist/src/Services/Jobs/jobRunSink.d.ts +44 -0
  46. package/dist/src/Services/Jobs/jobRuns.d.ts +54 -0
  47. package/dist/src/Services/Jobs/jobRunsTestTables.d.ts +399 -0
  48. package/dist/src/Services/Jobs/tenantWalk.d.ts +2 -0
  49. package/dist/src/Services/Monitoring/AlertService.d.ts +36 -20
  50. package/dist/src/Services/Monitoring/alertEmail.d.ts +11 -0
  51. package/dist/src/Services/Monitoring/alertMappers.d.ts +10 -0
  52. package/dist/src/Services/Monitoring/alertRules.d.ts +30 -0
  53. package/dist/src/Services/Monitoring/alertStore.d.ts +56 -0
  54. package/dist/src/Services/Monitoring/alertTypes.d.ts +21 -0
  55. package/dist/src/Services/Monitoring/collectors/ApplicationCollector.d.ts +4 -0
  56. package/dist/src/Services/Monitoring/collectors/ProbeCollector.d.ts +26 -0
  57. package/dist/src/Services/Monitoring/collectors/routeGroups.d.ts +48 -0
  58. package/dist/src/Services/Monitoring/hostOptions.d.ts +3 -0
  59. package/dist/src/Services/Monitoring/index.d.ts +30 -2
  60. package/dist/src/Services/Monitoring/metricsStore.d.ts +27 -0
  61. package/dist/src/Services/Monitoring/series.d.ts +31 -0
  62. package/dist/src/Services/Monitoring/types.d.ts +92 -2
  63. package/dist/src/Services/Notification/index.d.ts +7 -0
  64. package/dist/src/Services/Notification/portalJournal.d.ts +33 -0
  65. package/dist/src/Services/Tenant/hostWrites.d.ts +1 -1
  66. package/dist/src/types.d.ts +95 -1
  67. package/package.json +9 -9
  68. package/schemas/config.nucleus.json +170 -1
  69. package/schemas/table.schema.json +2 -1
  70. package/scripts/schema/columnCode.ts +2 -2
  71. package/scripts/schema/features.ts +1 -0
  72. package/scripts/schema/types.ts +1 -0
  73. package/src/system.tables.json +185 -0
@@ -0,0 +1,131 @@
1
+ import type { InferInsertModel, InferSelectModel } from 'drizzle-orm';
2
+ import type { JournalImplicit } from './journalConfig';
3
+ import type { JournalChange } from './journalTypes';
4
+ import { type RuleEntities } from './ruleTestKit';
5
+ import type { UnitOfWork, UnitOfWorkOptions } from './unitTypes';
6
+ /**
7
+ * Fixture of the change journal suites: the database of the rule suites plus `jr_plain`, an entity
8
+ * with no rules at all (its writes are the raw statements) and a unique `code` to upsert on.
9
+ */
10
+ declare const plain: import("drizzle-orm/pg-core").PgTableWithColumns<{
11
+ name: "jr_plain";
12
+ schema: undefined;
13
+ columns: {
14
+ id: import("drizzle-orm/pg-core").PgColumn<{
15
+ name: "id";
16
+ tableName: "jr_plain";
17
+ dataType: "string";
18
+ columnType: "PgUUID";
19
+ data: string;
20
+ driverParam: string;
21
+ notNull: true;
22
+ hasDefault: true;
23
+ isPrimaryKey: true;
24
+ isAutoincrement: false;
25
+ hasRuntimeDefault: false;
26
+ enumValues: undefined;
27
+ baseColumn: never;
28
+ identity: undefined;
29
+ generated: undefined;
30
+ }, {}, {}>;
31
+ code: import("drizzle-orm/pg-core").PgColumn<{
32
+ name: "code";
33
+ tableName: "jr_plain";
34
+ dataType: "string";
35
+ columnType: "PgText";
36
+ data: string;
37
+ driverParam: string;
38
+ notNull: true;
39
+ hasDefault: false;
40
+ isPrimaryKey: false;
41
+ isAutoincrement: false;
42
+ hasRuntimeDefault: false;
43
+ enumValues: [string, ...string[]];
44
+ baseColumn: never;
45
+ identity: undefined;
46
+ generated: undefined;
47
+ }, {}, {}>;
48
+ qty: import("drizzle-orm/pg-core").PgColumn<{
49
+ name: "qty";
50
+ tableName: "jr_plain";
51
+ dataType: "number";
52
+ columnType: "PgInteger";
53
+ data: number;
54
+ driverParam: string | number;
55
+ notNull: true;
56
+ hasDefault: true;
57
+ isPrimaryKey: false;
58
+ isAutoincrement: false;
59
+ hasRuntimeDefault: false;
60
+ enumValues: undefined;
61
+ baseColumn: never;
62
+ identity: undefined;
63
+ generated: undefined;
64
+ }, {}, {}>;
65
+ note: import("drizzle-orm/pg-core").PgColumn<{
66
+ name: "note";
67
+ tableName: "jr_plain";
68
+ dataType: "string";
69
+ columnType: "PgText";
70
+ data: string;
71
+ driverParam: string;
72
+ notNull: false;
73
+ hasDefault: false;
74
+ isPrimaryKey: false;
75
+ isAutoincrement: false;
76
+ hasRuntimeDefault: false;
77
+ enumValues: [string, ...string[]];
78
+ baseColumn: never;
79
+ identity: undefined;
80
+ generated: undefined;
81
+ }, {}, {}>;
82
+ seenAt: import("drizzle-orm/pg-core").PgColumn<{
83
+ name: "seen_at";
84
+ tableName: "jr_plain";
85
+ dataType: "date";
86
+ columnType: "PgTimestamp";
87
+ data: Date;
88
+ driverParam: string;
89
+ notNull: false;
90
+ hasDefault: false;
91
+ isPrimaryKey: false;
92
+ isAutoincrement: false;
93
+ hasRuntimeDefault: false;
94
+ enumValues: undefined;
95
+ baseColumn: never;
96
+ identity: undefined;
97
+ generated: undefined;
98
+ }, {}, {}>;
99
+ };
100
+ dialect: "pg";
101
+ }>;
102
+ type PlainShape = {
103
+ row: InferSelectModel<typeof plain>;
104
+ insert: InferInsertModel<typeof plain>;
105
+ };
106
+ /** `change_log` as the system table declares it (journalTable.integration.test.ts keeps the two equal). */
107
+ export declare const CHANGE_LOG_DDL = "\n create table change_log (id uuid primary key default gen_random_uuid(),\n seq bigint generated always as identity unique, occurred_at timestamptz not null,\n request_id varchar(64), source varchar(200) not null, actor_user_id uuid,\n actor_kind varchar(16) not null default 'system', input jsonb, status smallint, output jsonb,\n changes jsonb not null, change_count integer not null, bucket varchar(32));\n create index change_log_bucket_seq_idx on change_log (bucket, seq);\n create index change_log_unbucketed_seq_idx on change_log (seq) where bucket is null";
108
+ export interface LogRow {
109
+ seq: number;
110
+ source: string;
111
+ actor_kind: string;
112
+ actor_user_id: string | null;
113
+ change_count: number;
114
+ changes: JournalChange[];
115
+ }
116
+ export type JournalEntities = RuleEntities & {
117
+ jr_plain: PlainShape;
118
+ };
119
+ export type JournalUnit = UnitOfWork<JournalEntities>;
120
+ export declare const inUnit: <T>(options: UnitOfWorkOptions, work: (unit: UnitOfWork<JournalEntities>) => Promise<T>) => Promise<T>;
121
+ /** Starts the database, creates `jr_plain`, and returns the helpers the suites share. */
122
+ export declare function useJournalDb(): {
123
+ readonly pool: import("pg").Pool;
124
+ options: (extra?: Partial<UnitOfWorkOptions>) => UnitOfWorkOptions;
125
+ journalOf: (work: (unit: JournalUnit) => Promise<void>) => Promise<JournalChange[]>;
126
+ implicitStore: (journal: JournalImplicit["options"]) => import("./EntityStore").EntityStore<JournalEntities>;
127
+ logRows: (afterSeq?: number) => Promise<LogRow[]>;
128
+ lastSeq: () => Promise<number>;
129
+ code: () => string;
130
+ };
131
+ export {};
@@ -0,0 +1,79 @@
1
+ /**
2
+ * The types of the change journal (N8): what one unit of work wrote, row by row, in the order it
3
+ * wrote it. The collector (`journalCollect.ts`) fills them in memory on the unit; the flush that
4
+ * stores them in `change_log` is a separate step that reads `unit.journal.changes()`.
5
+ */
6
+ /** A JSON value: what a journaled column holds once dates and bigints are written out. */
7
+ export type JournalCell = string | number | boolean | null | JournalCell[] | JournalColumns;
8
+ /** Columns of one row by field name (camelCase, as the generated routes answer them). */
9
+ export interface JournalColumns {
10
+ [field: string]: JournalCell;
11
+ }
12
+ /**
13
+ * One row change.
14
+ *
15
+ * - `c`: `a` is the full new row.
16
+ * - `u`: `a` holds only the columns that changed, with their new values; `b` the same columns' old values.
17
+ * - `d`: `b` is the full row as it was.
18
+ */
19
+ export interface JournalChange {
20
+ /** The entity (table) name. */
21
+ e: string;
22
+ op: 'c' | 'u' | 'd';
23
+ /** The row id. */
24
+ id: string;
25
+ a?: JournalColumns;
26
+ b?: JournalColumns;
27
+ }
28
+ /** What the host knows about the unit that wrote: the columns of the `change_log` row besides the changes. */
29
+ export interface JournalContext {
30
+ /** `POST /floor/calls/:callId/ack`, `job:<name>` or `system:<reason>`. Default `system:unit`. */
31
+ source?: string;
32
+ requestId?: string;
33
+ /** The verified caller; a value that is not a uuid is stored as null. Default: the unit's `actor.id`. */
34
+ actorUserId?: string;
35
+ /** `user`, `job`, `system` or `platform`. Default: the unit's `actor.kind`, else `user` for an actor with an id, else `system`. */
36
+ actorKind?: string;
37
+ /** Free for the host (a business date, say). */
38
+ bucket?: string;
39
+ input?: JournalCell;
40
+ status?: number;
41
+ output?: JournalCell;
42
+ /** Called with the unit's schema once its `change_log` row is written; the request seam uses it to stamp the answer. */
43
+ onFlushed?: (schema: string) => void;
44
+ }
45
+ /** Opt-in of a unit of work: its presence turns the collector on. */
46
+ export interface JournalOptions {
47
+ /** Entity names never journaled (`audit_logs` and `change_log` never are, whatever is listed). */
48
+ exclude?: readonly string[];
49
+ /** Column names dropped from the journaled rows when the unit commits, per entity name or `*` for every entity. */
50
+ redact?: Readonly<Record<string, readonly string[]>>;
51
+ /** The other columns of the `change_log` row. */
52
+ context?: JournalContext;
53
+ }
54
+ /** What a unit exposes: the changes it has collected so far, in write order, savepoint rollbacks already dropped. */
55
+ export interface UnitJournal {
56
+ changes(): readonly JournalChange[];
57
+ }
58
+ /**
59
+ * One `change_log` row as a raw query (node-postgres) returns it: the table's snake_case column names, `seq`
60
+ * (a bigint) as a decimal string, `occurred_at` as a `Date`, the jsonb columns already parsed. A host that
61
+ * replays or lists the journal reads rows of this shape and orders them by `seq`, never by `occurred_at`.
62
+ */
63
+ export interface ChangeLogRow {
64
+ id: string;
65
+ seq: string;
66
+ occurred_at: Date;
67
+ request_id: string | null;
68
+ /** `POST /floor/calls/:callId/ack`, `job:<name>` or `system:<reason>`. */
69
+ source: string;
70
+ actor_user_id: string | null;
71
+ /** `user`, `job`, `system` or `platform`. */
72
+ actor_kind: string;
73
+ input: JournalCell | null;
74
+ status: number | null;
75
+ output: JournalCell | null;
76
+ changes: JournalChange[];
77
+ change_count: number;
78
+ bucket: string | null;
79
+ }
@@ -0,0 +1,16 @@
1
+ import type { JournalCollector } from './journalCollect';
2
+ import type { QueryTarget } from './storeTypes';
3
+ import type { Row } from './writeScope';
4
+ /**
5
+ * The journal of an upsert (N8a). One `INSERT ... ON CONFLICT DO UPDATE` statement cannot hand back
6
+ * the old row, so with the journal on the rows the proposed rows may collide with are read and locked
7
+ * first (by the conflict columns, inside the scope); the statement's returned rows then split into
8
+ * created ones (`xmax = 0`: `c` with the full row) and updated ones (`u` against the pre-read row).
9
+ */
10
+ /** The existing rows the proposed rows can conflict with, locked. Empty when the journal is off. */
11
+ export declare function lockConflicting(target: QueryTarget, rows: readonly Row[], fields: readonly string[]): Promise<object[]>;
12
+ /** Reports what an upsert wrote: created rows as `c`, updated rows as `u` against their pre-read image. */
13
+ export declare function journalUpsert<R extends object>(journal: JournalCollector, entity: string, before: readonly object[], outcomes: readonly {
14
+ row: R;
15
+ created: boolean;
16
+ }[]): void;
@@ -12,6 +12,7 @@
12
12
  */
13
13
  import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
14
14
  import { type EntityStore, type EntityStoreOptions } from './EntityStore';
15
+ import { type JournalConfig, type JournalHost } from './journalHost';
15
16
  import type { RuleSet } from './ruleSet';
16
17
  import type { SessionLimits } from './sessionLimits';
17
18
  import { type EntityMap } from './storeTypes';
@@ -29,6 +30,8 @@ export interface NucleusData {
29
30
  readonly db: NodePgDatabase;
30
31
  /** The main schema of the install (`database.sharedSchema`, else the first of `schemas`). */
31
32
  readonly mainSchema: string;
33
+ /** The change journal of the install: config, the host's `when`, and what the request, action and job seams share. */
34
+ readonly journal: JournalHost;
32
35
  /** `runUnitOfWork` on nucleus's pool: one transaction, commit on resolve, rollback on throw. */
33
36
  runUnitOfWork<M extends EntityMap, T>(options: NucleusUnitOptions, work: (unit: UnitOfWork<M>) => Promise<T>): Promise<T>;
34
37
  /**
@@ -46,6 +49,8 @@ export interface NucleusDataDeps {
46
49
  relationsOf(schemaName: string): Record<string, unknown>;
47
50
  /** The entity rules of the install (config rules + `entityHooks`), undefined when nothing declares one. */
48
51
  getRules(): RuleSet | undefined;
52
+ /** `config.journal`, read live. Absent: the journal is off. */
53
+ getJournalConfig?(): JournalConfig | undefined;
49
54
  /** Limits set on every unit's transaction (`database.pool.statementTimeoutMs` ...), pooler-safe. Absent: none. */
50
55
  sessionLimits?: SessionLimits;
51
56
  }
@@ -1,5 +1,7 @@
1
1
  import { PgTable } from 'drizzle-orm/pg-core';
2
2
  import type { ScopedLogger } from '../Services/Logger';
3
+ import type { JournalCollector } from './journalCollect';
4
+ import type { JournalImplicit } from './journalConfig';
3
5
  import type { RuleSet } from './ruleSet';
4
6
  import type { RuleActor, RuleRuntime } from './ruleTypes';
5
7
  import { type Scope } from './scope';
@@ -30,6 +32,10 @@ export interface StoreSession {
30
32
  readonly ruleRuntime?: RuleRuntime;
31
33
  /** Who writes, as far as transition guards and hooks need it. */
32
34
  readonly actor?: RuleActor;
35
+ /** The change journal (N8) of the unit of work the store runs in; filled by runUnitOfWork. */
36
+ readonly journal?: JournalCollector;
37
+ /** Journals the writes of a store used outside a unit of work, each in an implicit unit (N8b); absent: they are not journaled. */
38
+ readonly journalImplicit?: JournalImplicit;
33
39
  }
34
40
  export declare function tableOf(session: StoreSession, entity: string): PgTable | undefined;
35
41
  /** The scope of an entity: its columns and the host's forced filters, also for entities `exists` reaches. */
@@ -1,5 +1,6 @@
1
1
  import type { PgDatabase, PgQueryResultHKT, PgTable } from 'drizzle-orm/pg-core';
2
2
  import type { Expr } from './exprTypes';
3
+ import type { JournalCollector } from './journalCollect';
3
4
  import type { RuleBinding } from './ruleTypes';
4
5
  import type { Scope } from './scope';
5
6
  import type { EntityReads, EntityShape, RelationsRequest, WhereOf } from './storeReadTypes';
@@ -118,6 +119,8 @@ export interface QueryTarget {
118
119
  readonly relate?: (rows: readonly object[], request: RelationsRequest) => Promise<object[]>;
119
120
  /** The entity rules to apply to writes of this target (N4); absent: raw writes. */
120
121
  readonly rules?: RuleBinding;
122
+ /** The change journal (N8) of the unit this target writes in; absent: writes are not journaled. */
123
+ readonly journal?: JournalCollector;
121
124
  }
122
125
  /** A refusal of the store itself (bad limit, foreign cursor, unknown entity); never a database error. */
123
126
  export declare class StoreError extends Error {
@@ -1,5 +1,7 @@
1
1
  import type { ScopedLogger } from '../Services/Logger';
2
2
  import type { NotificationChannel, NotificationDeliveryReport, SendNotificationParams } from '../Services/Notification/types';
3
+ import { type HostWriter, type TenantNotificationRow } from '../Services/Tenant/hostWrites';
4
+ import type { JournalCollector } from './journalCollect';
3
5
  import type { UnitEffects } from './unitEffects';
4
6
  /** The channels `notifyAfterCommit` reaches: everything but `portal`, which `unit.notify` writes in the transaction. */
5
7
  export type ExternalChannel = Exclude<NotificationChannel, 'portal'>;
@@ -14,3 +16,5 @@ export type UnitNotifier = (params: SendNotificationParams) => Promise<Notificat
14
16
  * into the request (the transaction is already committed).
15
17
  */
16
18
  export declare function notifyAfterCommit(notifier: UnitNotifier | undefined, effects: UnitEffects, log: ScopedLogger, params: AfterCommitNotification): void;
19
+ /** `unit.notify`: writes portal rows in the unit's transaction and reports them to the unit's journal. */
20
+ export declare function writeNotifications(tx: HostWriter, schema: string, journal: JournalCollector | null, rows: TenantNotificationRow | readonly TenantNotificationRow[]): Promise<void>;
@@ -1,6 +1,7 @@
1
1
  import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
2
2
  import type { TenantAuditRow, TenantNotificationRow } from '../Services/Tenant/hostWrites';
3
3
  import type { EntityStore, EntityStoreOptions } from './EntityStore';
4
+ import type { JournalOptions, UnitJournal } from './journalTypes';
4
5
  import type { UnitLocks } from './locks';
5
6
  import type { SessionLimits } from './sessionLimits';
6
7
  import type { EntityMap } from './storeTypes';
@@ -23,7 +24,7 @@ export interface UnitRetryOptions {
23
24
  /** Ceiling of one delay. Default 500 ms. */
24
25
  maxDelayMs?: number;
25
26
  }
26
- export interface UnitOfWorkOptions extends Omit<EntityStoreOptions, 'db'> {
27
+ export interface UnitOfWorkOptions extends Omit<EntityStoreOptions, 'db' | 'journal' | 'journalImplicit'> {
27
28
  /** Where the transaction opens. Ignored by a nested unit: it rides on its parent's connection. */
28
29
  db: UnitDatabase;
29
30
  /** Default: the server's (`read committed`). A nested unit may not ask for another one. */
@@ -36,6 +37,8 @@ export interface UnitOfWorkOptions extends Omit<EntityStoreOptions, 'db'> {
36
37
  sessionLimits?: SessionLimits;
37
38
  /** What `unit.notifyAfterCommit` sends through (`ctx.nucleus.sendNotification`); an action supplies it. */
38
39
  notifier?: UnitNotifier;
40
+ /** Keeps a change journal of the unit's writes (N8): `unit.journal.changes()`. Off when omitted; a nested unit uses its parent's. */
41
+ journal?: JournalOptions;
39
42
  }
40
43
  /** A callback registered with `afterCommit`. */
41
44
  export type AfterCommitCallback = () => void | Promise<void>;
@@ -52,6 +55,12 @@ export interface UnitOfWork<M extends EntityMap> {
52
55
  readonly schema: string;
53
56
  /** 0 for the outermost unit, 1 for a savepoint inside it, and so on. */
54
57
  readonly depth: number;
58
+ /**
59
+ * The change journal (N8): every row this unit's store wrote, in write order, as `c`/`u`/`d` changes with
60
+ * after and before images. A savepoint that rolled back has already dropped its own. Null unless the unit
61
+ * was opened with `journal`.
62
+ */
63
+ readonly journal: UnitJournal | null;
55
64
  /** Writes an audit row into this unit's schema, in this transaction: it commits or rolls back with the work. */
56
65
  audit(entry: TenantAuditRow): Promise<void>;
57
66
  /** Writes portal notifications into this unit's schema, in this transaction. */
@@ -55,6 +55,7 @@ export declare class EntityWriter {
55
55
  /** Whether writes of `entity` run through the store. */
56
56
  isRuled(entity: string): boolean;
57
57
  write(write: EntityWrite): Promise<WriteOutcome>;
58
+ private schemaOf;
58
59
  private inUnit;
59
60
  private run;
60
61
  /**
@@ -0,0 +1,18 @@
1
+ import type { MonitoringService } from '../../../Services/Monitoring';
2
+ /** Most rows one history request returns. */
3
+ export declare const ALERT_HISTORY_MAX = 500;
4
+ /**
5
+ * `GET <alerts>/history`: alerts opened and resolved, newest first, from `monitoring_alerts`
6
+ * (query `limit`, default 100, and `state` of `open` or `resolved`). Empty when no history table is wired.
7
+ */
8
+ export declare function createAlertHistoryRoute(path: string, getService: () => MonitoringService | null): import("../../../Server/defineRoute").Route<`${string}/history`, undefined, import("@sinclair/typebox").TObject<{
9
+ limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
10
+ state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"open">, import("@sinclair/typebox").TLiteral<"resolved">]>>;
11
+ }>, undefined, {
12
+ isSuccess: boolean;
13
+ message: string;
14
+ data: {
15
+ count: number;
16
+ alerts: import("../../../Services/Monitoring/alertStore").AlertRecord[];
17
+ };
18
+ }, never, "GET">;
@@ -0,0 +1,51 @@
1
+ import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
2
+ import type { MonitoringService } from '../../../Services/Monitoring';
3
+ /** Most rows one series request returns; at the 5-minute step that is 34 days. */
4
+ export declare const SERIES_MAX_POINTS = 10000;
5
+ export interface HistoryRouteConfig {
6
+ path: string;
7
+ /** Window of the Redis snapshot history, in minutes. */
8
+ maxMinutes: number;
9
+ getService: () => MonitoringService | null;
10
+ db?: NodePgDatabase | null;
11
+ schemaTables?: Record<string, unknown>;
12
+ }
13
+ /**
14
+ * `GET /history`.
15
+ *
16
+ * Without `name`: the snapshots of the last `minutes` from Redis (at most one hour).
17
+ * With `name` (a series configured in `persistence.series.names`): the averaged
18
+ * rows from `monitoring_metrics` between `from` and `to` (epoch ms or a date
19
+ * string; default the last 24 hours), oldest first, so a trend reaches back past
20
+ * Redis's hour for as long as retention keeps the rows.
21
+ */
22
+ export declare function createHistoryRoute(config: HistoryRouteConfig): import("../../../Server/defineRoute").Route<string, undefined, import("@sinclair/typebox").TObject<{
23
+ minutes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
24
+ name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
25
+ from: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString]>>;
26
+ to: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString]>>;
27
+ }>, undefined, {
28
+ isSuccess: boolean;
29
+ message: string;
30
+ data: {
31
+ name: string;
32
+ from: number;
33
+ to: number;
34
+ count: number;
35
+ points: import("../../../Services/Monitoring/metricsStore").SeriesRow[];
36
+ minutes?: undefined;
37
+ snapshots?: undefined;
38
+ };
39
+ } | {
40
+ isSuccess: boolean;
41
+ message: string;
42
+ data: {
43
+ minutes: number;
44
+ count: number;
45
+ snapshots: import("../../../Services").MonitoringSnapshot[];
46
+ name?: undefined;
47
+ from?: undefined;
48
+ to?: undefined;
49
+ points?: undefined;
50
+ };
51
+ }, never, "GET">;
@@ -38,6 +38,11 @@ export interface MonitoringRoutesConfig {
38
38
  enabled: boolean;
39
39
  path: string;
40
40
  };
41
+ /** `GET <jobs path>` (NM3): job runs. Off when absent. */
42
+ jobs?: {
43
+ enabled: boolean;
44
+ path: string;
45
+ };
41
46
  };
42
47
  }
43
48
  export declare function createMonitoringRoutes(config: MonitoringRoutesConfig): import("../../../Server/routeCollector").RouteCollector;
@@ -0,0 +1,24 @@
1
+ import type { JobRunSink } from '../../../Services/Jobs/jobRunSink';
2
+ /** Most runs one request returns. */
3
+ export declare const JOB_RUNS_MAX = 500;
4
+ /**
5
+ * `GET <jobs>`: the last run and the last success of every job, and the recent runs, newest first,
6
+ * from `job_runs` (query `limit`, default 50, and `job`). Empty when no run was recorded or no
7
+ * table is wired.
8
+ */
9
+ export declare function createJobsRoute(path: string, getSink?: () => JobRunSink | null): import("../../../Server/defineRoute").Route<string, undefined, import("@sinclair/typebox").TObject<{
10
+ limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
11
+ job: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
12
+ }>, undefined, {
13
+ isSuccess: boolean;
14
+ message: string;
15
+ data: {
16
+ jobs: Array<{
17
+ job: string;
18
+ lastRun: import("../../../Services/Jobs/jobRuns").JobRunRecord;
19
+ lastSuccess: import("../../../Services/Jobs/jobRuns").JobRunRecord | null;
20
+ }>;
21
+ recent: import("../../../Services/Jobs/jobRuns").JobRunRecord[];
22
+ count: number;
23
+ };
24
+ }, never, "GET">;
@@ -4,6 +4,7 @@ import type { Logger } from 'src/Services/Logger';
4
4
  import type { NotificationConfig } from 'src/Services/Notification';
5
5
  import { NotificationService } from 'src/Services/Notification';
6
6
  import type { TenantRegistry } from 'src/Services/Tenant';
7
+ import type { JournalHost } from '../../../Data/journalHost';
7
8
  export interface NotificationRoutesConfig {
8
9
  db: NodePgDatabase;
9
10
  schemaTables: Record<string, unknown>;
@@ -19,6 +20,8 @@ export interface NotificationRoutesConfig {
19
20
  */
20
21
  getTenantRegistry?: () => TenantRegistry | null;
21
22
  basePath?: string;
23
+ /** The install's change journal: portal rows the routes write are journaled while `config.journal` is on. */
24
+ journal?: JournalHost;
22
25
  }
23
26
  /** The header an in-cluster service presents to `POST {basePath}/send/service`. */
24
27
  export declare const SERVICE_TOKEN_HEADER = "x-internal-identity-token";
@@ -2,6 +2,7 @@ import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
2
2
  import type { Logger } from 'src/Services/Logger';
3
3
  import type { NotificationConfig } from 'src/Services/Notification';
4
4
  import { NotificationService } from 'src/Services/Notification';
5
+ import type { NotificationJournal } from 'src/Services/Notification/portalJournal';
5
6
  import { type VerificationConfig, VerificationService } from 'src/Services/Verification';
6
7
  export interface VerificationServiceDeps {
7
8
  db: NodePgDatabase;
@@ -10,6 +11,8 @@ export interface VerificationServiceDeps {
10
11
  notificationConfig?: NotificationConfig;
11
12
  logger: Logger;
12
13
  getEmailService?: () => import('src/Services/Email/types').EmailService | null;
14
+ /** The change journal and the schema `schemaTables` belong to: the notification rows a decision writes are journaled. */
15
+ journal?: NotificationJournal;
13
16
  }
14
17
  /**
15
18
  * The only way to build a verification service.
@@ -11,6 +11,8 @@ export interface VerificationRoutesConfig {
11
11
  logger: Logger;
12
12
  getEmailService?: () => import('src/Services/Email/types').EmailService | null;
13
13
  tenantRegistry?: TenantRegistry | null;
14
+ /** The install's change journal: notification rows a decision writes are journaled. */
15
+ journal?: import('../../../Data/journalHost').JournalHost;
14
16
  /** Read per request: the registry does not exist yet when these routes are registered. */
15
17
  getTenantRegistry?: () => TenantRegistry | null;
16
18
  }
@@ -1,12 +1,14 @@
1
1
  import type { NucleusConfig } from '@types';
2
2
  import type { ActionHost } from '../Data/actionTypes';
3
3
  import type { NucleusEntityHooks } from '../Data/entityHooks';
4
+ import type { JournalWhen } from '../Data/journalConfig';
4
5
  import { type NucleusData } from '../Data/nucleusData';
5
6
  import { buildNucleus } from '../Nucleus/index';
6
7
  import { type ViewHost, type ViewRouteDefinition } from '../Nucleus/routes/view';
7
8
  import { type NucleusRuntime } from '../Nucleus/runtime';
8
9
  import { type JobHostInput } from '../Services/Jobs/bootJobs';
9
10
  import type { JobDefinition } from '../Services/Jobs/defineJob';
11
+ import type { MonitoringHostOptions } from '../Services/Monitoring/types';
10
12
  import { type ActionDefinition } from './defineAction';
11
13
  import { type NucleusServer } from './NucleusServer';
12
14
  import type { Guard, RouteGroup } from './router';
@@ -114,6 +116,20 @@ export interface CreateNucleusServerOptions {
114
116
  * and main schema; `db` may be omitted for nucleus's pool). Tenants come from nucleus.
115
117
  */
116
118
  jobHost?: JobHostInput;
119
+ /**
120
+ * The change journal's per-tenant switch. `config.journal.enabled` creates `change_log`; `when(schema)`
121
+ * decides, per tenant schema, whether a unit of work journals (the host: a feature flag, say). Default:
122
+ * every schema while `config.journal.enabled` is true. See the `nucleus-journal` skill.
123
+ */
124
+ journal?: {
125
+ when?: JournalWhen;
126
+ };
127
+ /**
128
+ * Host hooks of nucleus monitoring. `onAlert` hears every alert that opens and every one that
129
+ * resolves (`MonitoringAlertNotice`), so the host can ring a bell or send a mail; it needs
130
+ * `config.monitoring.alerts.enabled`.
131
+ */
132
+ monitoring?: MonitoringHostOptions;
117
133
  /**
118
134
  * The host's own guard, run BEFORE nucleus's inbound guard and auth.
119
135
  *
@@ -0,0 +1,30 @@
1
+ import { type NucleusServerWithData } from './createNucleusServer';
2
+ import { SCHEMA } from './journalRequestRoutes';
3
+ /** Fixture of the request journal suite (N8c): one real server, journal on, on a real PostgreSQL. */
4
+ export { SCHEMA };
5
+ export declare const CAP = 400;
6
+ export declare let server: NucleusServerWithData;
7
+ export declare function startJournalFixture(): Promise<void>;
8
+ export declare function stopJournalFixture(): Promise<void>;
9
+ export declare const post: (path: string, payload?: object) => Promise<Response>;
10
+ export interface LogRow {
11
+ seq: number;
12
+ request_id: string | null;
13
+ source: string;
14
+ actor_kind: string;
15
+ input: {
16
+ params?: object;
17
+ query?: object;
18
+ body?: object;
19
+ } | null;
20
+ status: number | null;
21
+ output: object | null;
22
+ changes: {
23
+ e: string;
24
+ op: string;
25
+ a?: Record<string, object | string>;
26
+ }[];
27
+ }
28
+ /** The change_log rows after `seq`, oldest first. */
29
+ export declare function logAfter(seq: number): Promise<LogRow[]>;
30
+ export declare function lastSeq(): Promise<number>;
@@ -0,0 +1,23 @@
1
+ /** The host routes, action and job of the request journal suite (N8c). */
2
+ export declare const SCHEMA = "jr_req";
3
+ export declare const noScope: () => () => never[];
4
+ export declare const routes: {
5
+ prefix: string;
6
+ routes: (import("./defineRoute").Route<"/commit/:tag", import("@sinclair/typebox").TObject<{
7
+ label: import("@sinclair/typebox").TString;
8
+ password: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
9
+ secretNote: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
10
+ }>, undefined, undefined, {
11
+ ok: boolean;
12
+ data: {
13
+ label: string;
14
+ blob: string;
15
+ };
16
+ }, never, "POST"> | import("./defineRoute").Route<"/notify", undefined, undefined, undefined, {
17
+ ok: boolean;
18
+ }, never, "POST"> | import("./defineRoute").Route<"/upload", undefined, undefined, undefined, {
19
+ ok: boolean;
20
+ }, never, "POST">)[];
21
+ }[];
22
+ export declare const actions: import("./defineAction").ActionDefinition[];
23
+ export declare const jobs: import("../Services/Jobs").JobDefinition[];
@@ -0,0 +1,8 @@
1
+ import type { ResponseSet } from './response';
2
+ import type { BuildRoutesOptions, BunServerLike, RegisteredRoute } from './routerTypes';
3
+ /**
4
+ * Build the function that answers one request for a registered route.
5
+ *
6
+ * `method` and `path` identify the route for the journal frame.
7
+ */
8
+ export declare function createAnswer(registered: RegisteredRoute, method: string, path: string, options: BuildRoutesOptions): (request: Request, server: BunServerLike | undefined, set: ResponseSet) => Promise<Response>;
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Request input: read the body, prepare body/query/params, validate them.
3
+ *
4
+ * Runs after the early `onRequest` guard and before any group, route or host
5
+ * guard — the order Elysia uses, frozen by six route suites. A refusal comes
6
+ * back as a ready `Response`; otherwise the prepared input.
7
+ */
8
+ import type { ResponseSet } from './response';
9
+ import type { AnyRoute } from './routerTypes';
10
+ /** The prepared (defaulted, converted, stripped) and validated input of one request. */
11
+ export interface RouteInput {
12
+ body: unknown;
13
+ query: Record<string, string | undefined>;
14
+ params: Record<string, string>;
15
+ }
16
+ /**
17
+ * Read, prepare and validate a request's body, query and params.
18
+ *
19
+ * Returns a `Response` for a refusal (malformed body, failed validation) and
20
+ * the prepared `RouteInput` otherwise. Anything but a `BodyParseError` thrown
21
+ * while reading the body propagates to the caller's error wrap.
22
+ */
23
+ export declare function readInput(request: Request, route: AnyRoute, set: ResponseSet, rawParams: Record<string, string>, rawQuery: Record<string, string | undefined>): Promise<Response | RouteInput>;