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

package/dist/core/principal/principal.types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * How a deployment isolates its users: one organisation everyone auto-joins
+ * (`'single'`) or one organisation per customer (`'multi'`).
+ *
+ * A deployment setting, not a code path: the same code and the same tables
+ * serve both modes. This type only names the two values; parsing the setting
+ * is not part of this contract.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const mode: TenancyMode = 'single';
+ * ```
+ */
+export type TenancyMode = 'single' | 'multi';
+/**
+ * How the request authenticated. One value per credential family the
+ * authentication guard accepts:
+ *
+ * - `'session'`: a browser access JWT (`Authorization: Bearer <jwt>`) whose
+ *   payload has no `did` claim.
+ * - `'device'`: an access JWT carrying `did`, issued by the device
+ *   authorization flow. A device flow that issued a `pat_` presents a PAT and
+ *   is `'pat'`: the kind names the credential presented, not the flow that
+ *   minted it.
+ * - `'pat'`: a `pat_` personal access token.
+ * - `'node'`: a `nod_` worker-node credential, confined to `/api/nodes`.
+ *
+ * Small and closed, so unlike an org id it is safe as a metric label.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const kind: CredentialKind = payload.did ? 'device' : 'session';
+ * ```
+ */
+export type CredentialKind = 'session' | 'device' | 'pat' | 'node';
+/**
+ * Discriminant of {@link Principal}: a human user (directly or through a
+ * credential they delegated) or an unattended worker node.
+ *
+ * @stability experimental
+ */
+export type PrincipalKind = 'user' | 'node';
+/**
+ * One organisation a principal belongs to.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const membership: OrgMembership = { orgId: 'org_1', role: 'member' };
+ * ```
+ */
+export interface OrgMembership {
+    /** The organisation's id. */
+    readonly orgId: string;
+    /** Org-scoped role name (spec: "Org roles"), e.g. `'org_admin'`, `'member'`. */
+    readonly role: string;
+}
+/**
+ * One group a principal belongs to. A group is a set of users inside one
+ * organisation that can own and share content; it is never a tenant.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const group: GroupMembership = { groupId: 'grp_1', orgId: 'org_1', role: 'member' };
+ * ```
+ */
+export interface GroupMembership {
+    /** The group's id. */
+    readonly groupId: string;
+    /** The organisation the group lives in. */
+    readonly orgId: string;
+    /** The member's role inside the group, e.g. `'owner'`, `'member'`. */
+    readonly role: string;
+}
+/**
+ * Fields every principal carries. Not exported: build a {@link UserPrincipal}
+ * or a {@link NodePrincipal}.
+ */
+interface PrincipalBase {
+    /** Discriminant; narrow on it. */
+    readonly kind: PrincipalKind;
+    /**
+     * The user whose authority is exercised. For a node principal, the owner of
+     * the node credential.
+     */
+    readonly userId: string;
+    /** That user's email, for logs and audit. */
+    readonly email: string;
+    /** How the request authenticated. */
+    readonly credential: CredentialKind;
+    /**
+     * System role names (spec: "System roles operate the deployment"). Today
+     * every role is a system role.
+     */
+    readonly roles: readonly string[];
+    /** Effective permission strings, deduplicated. */
+    readonly permissions: readonly string[];
+    /**
+     * The active organisation. ABSENT until organisations exist; afterwards
+     * always present on a user principal (single mode: the default org) and
+     * never present on a node principal, which stays system-scoped. Carried in
+     * the access token; switching org re-issues the token.
+     */
+    readonly activeOrgId?: string;
+    /** Every organisation the user belongs to. Absent until organisations exist. */
+    readonly memberships?: readonly OrgMembership[];
+    /** Every group the user belongs to. Absent until groups exist. */
+    readonly groups?: readonly GroupMembership[];
+}
+/**
+ * A human caller: a browser session, a device-flow token or a personal
+ * access token. A snapshot for one request; every field is readonly and a
+ * change (for example switching org) produces a new principal on the next
+ * request.
+ *
+ * There is no `isActive`: an inactive user never becomes a principal.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const principal: UserPrincipal = {
+ *   kind: 'user',
+ *   userId: requestUser.id,
+ *   email: requestUser.email,
+ *   credential: 'session',
+ *   roles: requestUser.roles,
+ *   permissions: requestUser.permissions,
+ * };
+ * ```
+ */
+export interface UserPrincipal extends PrincipalBase {
+    readonly kind: 'user';
+    readonly credential: 'session' | 'device' | 'pat';
+}
+/**
+ * An unattended worker process authenticated with a `nod_` credential. It
+ * acts with its owning user's roles and permissions and is confined to
+ * `/api/nodes` by the authentication guard.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const principal: NodePrincipal = {
+ *   kind: 'node',
+ *   userId: owner.id,
+ *   email: owner.email,
+ *   credential: 'node',
+ *   roles: owner.roles,
+ *   permissions: owner.permissions,
+ * };
+ * ```
+ */
+export interface NodePrincipal extends PrincipalBase {
+    readonly kind: 'node';
+    readonly credential: 'node';
+    /** The worker node the credential is enrolled as, when known. */
+    readonly nodeId?: string;
+}
+/**
+ * Who is calling. Narrow on `kind` (or `credential`) before reading the
+ * variant-specific fields.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * function describe(principal: Principal): string {
+ *   return principal.kind === 'node' ? `node ${principal.nodeId ?? '?'}` : principal.email;
+ * }
+ * ```
+ */
+export type Principal = UserPrincipal | NodePrincipal;
+/**
+ * The data boundary one operation runs in.
+ *
+ * Derived from a {@link Principal}, NEVER from request input (path, query or
+ * body): `userId = principal.userId`, `orgId = principal.activeOrgId`,
+ * `groupIds` = the principal's group ids, optionally narrowed by the
+ * operation, never widened.
+ *
+ * - `userId` is always required.
+ * - `orgId` is required once organisations exist; it is what row-level
+ *   security's transaction-local `app.org_id` setting will carry.
+ * - `groupIds` narrows to groups the principal belongs to (sharing).
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const scope: Scope = { userId: principal.userId, orgId: principal.activeOrgId };
+ * ```
+ */
+export interface Scope {
+    /** The user the operation acts for: always `principal.userId`. */
+    readonly userId: string;
+    /** The organisation: `principal.activeOrgId`. Required once organisations exist. */
+    readonly orgId?: string;
+    /** Groups to narrow to, each one the principal belongs to; never widened. */
+    readonly groupIds?: readonly string[];
+}
+/**
+ * An explicit, named escape from scoping for system work (backups, purges,
+ * the Doctor). The only way to run unscoped. Never derived from a request.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const actor: SystemActor = { kind: 'system', reason: 'retention.purge' };
+ * ```
+ */
+export interface SystemActor {
+    /** Discriminant: always `'system'`. */
+    readonly kind: 'system';
+    /**
+     * Short, greppable reason, e.g. `'retention.purge'`, `'db.backup.run'`.
+     * Logged and put on spans.
+     */
+    readonly reason: string;
+}
+export {};
+//# sourceMappingURL=principal.types.d.ts.map

package/dist/core/principal/principal.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.types.d.ts","sourceRoot":"","sources":["../../../src/core/principal/principal.types.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,QAAQ,GACR,KAAK,GACL,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,KAAK;IACpB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/core/principal/principal.types.js

@@ -0,0 +1,22 @@
+"use strict";
+// =============================================================================
+// The org-aware principal and scope contract (ADR 0001)
+// =============================================================================
+//
+// TYPES ONLY. This file has no runtime exports and imports nothing: not
+// `@prisma/client`, not `@nestjs/*`, not an app module. It was written that
+// way in the app (issue #687) so it could move into
+// `@marinoscar/platform-api/core` unchanged, which it did (issue #698). Both
+// properties are pinned by `test/core/principal.spec.ts` in this package.
+//
+// Nothing in the reference app consumes it yet. Requests still carry the
+// app's `RequestUser` (`apps/api/src/auth/interfaces/authenticated-user.interface.ts`);
+// attaching a `Principal` to the request, the runtime `toPrincipal()` mapper
+// and `@CurrentPrincipal()` arrive later (issue #724). The derivation rules
+// this contract is built on (credential mapping, scope derivation, tenancy
+// modes, `SystemActor`) are written down in
+// docs/adr/0001-org-aware-principal-and-scope.md. Read it before changing a
+// field here.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=principal.types.js.map

package/dist/core/principal/principal.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.types.js","sourceRoot":"","sources":["../../../src/core/principal/principal.types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,oDAAoD;AACpD,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,yEAAyE;AACzE,wFAAwF;AACxF,6EAA6E;AAC7E,4EAA4E;AAC5E,2EAA2E;AAC3E,4CAA4C;AAC5C,4EAA4E;AAC5E,cAAc;AACd,gFAAgF"}

package/dist/core/registry/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_REGISTRY_ID_PATTERN, REGISTRY_ID_MAX_LENGTH, Registry, RegistryError, defineRegistry, freezeDefinedRegistries, listDefinedRegistries, } from './registry';
+export type { RegistryErrorCode, RegistryOptions, RegistrySnapshot } from './registry';
+export { withTemporaryEntries } from './testing';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/registry/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,QAAQ,EACR,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/core/registry/index.js

@@ -0,0 +1,19 @@
+"use strict";
+// The framework-free registry primitive (issue #675). Recipe: ./README.md.
+//
+// `RegistryFreezeService` is deliberately NOT re-exported: this barrel must stay
+// importable where no Nest container exists (prisma/seed.ts, storage-purge.main.ts,
+// module-evaluation-time DTOs). Import the service from './registry-freeze.service'.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTemporaryEntries = exports.listDefinedRegistries = exports.freezeDefinedRegistries = exports.defineRegistry = exports.RegistryError = exports.Registry = exports.REGISTRY_ID_MAX_LENGTH = exports.DEFAULT_REGISTRY_ID_PATTERN = void 0;
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "DEFAULT_REGISTRY_ID_PATTERN", { enumerable: true, get: function () { return registry_1.DEFAULT_REGISTRY_ID_PATTERN; } });
+Object.defineProperty(exports, "REGISTRY_ID_MAX_LENGTH", { enumerable: true, get: function () { return registry_1.REGISTRY_ID_MAX_LENGTH; } });
+Object.defineProperty(exports, "Registry", { enumerable: true, get: function () { return registry_1.Registry; } });
+Object.defineProperty(exports, "RegistryError", { enumerable: true, get: function () { return registry_1.RegistryError; } });
+Object.defineProperty(exports, "defineRegistry", { enumerable: true, get: function () { return registry_1.defineRegistry; } });
+Object.defineProperty(exports, "freezeDefinedRegistries", { enumerable: true, get: function () { return registry_1.freezeDefinedRegistries; } });
+Object.defineProperty(exports, "listDefinedRegistries", { enumerable: true, get: function () { return registry_1.listDefinedRegistries; } });
+var testing_1 = require("./testing");
+Object.defineProperty(exports, "withTemporaryEntries", { enumerable: true, get: function () { return testing_1.withTemporaryEntries; } });
+//# sourceMappingURL=index.js.map

package/dist/core/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/registry/index.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,EAAE;AACF,iFAAiF;AACjF,oFAAoF;AACpF,qFAAqF;;;AAErF,uCAQoB;AAPlB,uHAAA,2BAA2B,OAAA;AAC3B,kHAAA,sBAAsB,OAAA;AACtB,oGAAA,QAAQ,OAAA;AACR,yGAAA,aAAa,OAAA;AACb,0GAAA,cAAc,OAAA;AACd,mHAAA,uBAAuB,OAAA;AACvB,iHAAA,qBAAqB,OAAA;AAGvB,qCAAiD;AAAxC,+GAAA,oBAAoB,OAAA"}

package/dist/core/registry/registry-freeze.service.d.ts

@@ -0,0 +1,14 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+/**
+ * Freezes every registry made with `defineRegistry` once the Nest application
+ * has bootstrapped. Provide it in a module of the app (the base provides it in
+ * `CommonModule`).
+ *
+ * @stability stable
+ */
+export declare class RegistryFreezeService implements OnApplicationBootstrap {
+    private readonly logger;
+    /** Freezes every registry created with `defineRegistry` and logs their sizes. */
+    onApplicationBootstrap(): void;
+}
+//# sourceMappingURL=registry-freeze.service.d.ts.map

package/dist/core/registry/registry-freeze.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-freeze.service.d.ts","sourceRoot":"","sources":["../../../src/core/registry/registry-freeze.service.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAsB,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAI5E;;;;;;GAMG;AACH,qBACa,qBAAsB,YAAW,sBAAsB;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAEjE,iFAAiF;IACjF,sBAAsB,IAAI,IAAI;CAO/B"}

package/dist/core/registry/registry-freeze.service.js

@@ -0,0 +1,55 @@
+"use strict";
+// =============================================================================
+// RegistryFreezeService (issue #675, PP-1.3)
+// =============================================================================
+//
+// Static registries (`defineRegistry`) fill at import time, from their
+// manifests, so every entry is present before Nest instantiates a single
+// provider. Once the application has bootstrapped, a late `register()` can only
+// be a mistake: some consumer may already have read the list (a DTO built its
+// enum, the seed ran, a guard cached a lookup). Freezing turns that mistake into
+// a loud `FROZEN` error instead of a list that differs depending on timing.
+//
+// `onApplicationBootstrap`, not `onModuleInit`, so the freeze runs after every
+// module's init hook, the same lifecycle point `jobs/job.worker.ts` starts work
+// at. Not `main.ts`: integration specs bootstrap through
+// `Test.createTestingModule({ imports: [AppModule] })` and would never exercise
+// it. `npm run openapi:dump` (Nest preview mode) never bootstraps, so nothing
+// freezes there, which is fine: nothing registers there either.
+//
+// Freezing is idempotent, so the second Nest application a Jest worker creates
+// simply finds the registries already frozen.
+// =============================================================================
+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 RegistryFreezeService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryFreezeService = void 0;
+const common_1 = require("@nestjs/common");
+const registry_1 = require("./registry");
+/**
+ * Freezes every registry made with `defineRegistry` once the Nest application
+ * has bootstrapped. Provide it in a module of the app (the base provides it in
+ * `CommonModule`).
+ *
+ * @stability stable
+ */
+let RegistryFreezeService = RegistryFreezeService_1 = class RegistryFreezeService {
+    logger = new common_1.Logger(RegistryFreezeService_1.name);
+    /** Freezes every registry created with `defineRegistry` and logs their sizes. */
+    onApplicationBootstrap() {
+        (0, registry_1.freezeDefinedRegistries)();
+        const registries = (0, registry_1.listDefinedRegistries)();
+        const summary = registries.map((r) => `${r.name}(${r.size})`).join(', ');
+        this.logger.debug(`Froze ${registries.length} static registries: ${summary || '(none)'}`);
+    }
+};
+exports.RegistryFreezeService = RegistryFreezeService;
+exports.RegistryFreezeService = RegistryFreezeService = RegistryFreezeService_1 = __decorate([
+    (0, common_1.Injectable)()
+], RegistryFreezeService);
+//# sourceMappingURL=registry-freeze.service.js.map

package/dist/core/registry/registry-freeze.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-freeze.service.js","sourceRoot":"","sources":["../../../src/core/registry/registry-freeze.service.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6CAA6C;AAC7C,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,gFAAgF;AAChF,8EAA8E;AAC9E,iFAAiF;AACjF,4EAA4E;AAC5E,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,yDAAyD;AACzD,gFAAgF;AAChF,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,8CAA8C;AAC9C,gFAAgF;;;;;;;;;;AAEhF,2CAA4E;AAE5E,yCAA4E;AAE5E;;;;;;GAMG;AAEI,IAAM,qBAAqB,6BAA3B,MAAM,qBAAqB;IACf,MAAM,GAAG,IAAI,eAAM,CAAC,uBAAqB,CAAC,IAAI,CAAC,CAAC;IAEjE,iFAAiF;IACjF,sBAAsB;QACpB,IAAA,kCAAuB,GAAE,CAAC;QAE1B,MAAM,UAAU,GAAG,IAAA,gCAAqB,GAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,UAAU,CAAC,MAAM,uBAAuB,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC;IAC5F,CAAC;CACF,CAAA;AAXY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAWjC"}

package/dist/core/registry/registry.d.ts

@@ -0,0 +1,268 @@
+/**
+ * The default pattern every registry id must match: a letter or digit first,
+ * then letters, digits and `. _ : / @ -`.
+ *
+ * It admits every id shape the codebase already uses (`db.connection`,
+ * `jobs:read`, `auth.initial-admin`, `coach/weekly-review`) and rejects whitespace and a
+ * leading separator. Override it per registry with {@link RegistryOptions.idPattern}.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_REGISTRY_ID_PATTERN: RegExp;
+/**
+ * The longest id any registry accepts, in UTF-16 code units.
+ *
+ * @stability stable
+ */
+export declare const REGISTRY_ID_MAX_LENGTH = 128;
+/**
+ * Why a registry refused an operation. Stable: callers may switch on it.
+ *
+ * - `INVALID_ID`: the id is not a string, is empty, is longer than
+ *   {@link REGISTRY_ID_MAX_LENGTH}, or fails the registry's id pattern.
+ * - `INVALID_ENTRY`: the registry's `validate` hook threw.
+ * - `DUPLICATE_ID`: the id is already registered and the policy is `'throw'`.
+ * - `FROZEN`: a write after {@link Registry.freeze}.
+ * - `UNKNOWN_ID`: {@link Registry.require} found no entry.
+ * - `DUPLICATE_REGISTRY`: {@link defineRegistry} was given a name already in use.
+ *
+ * @stability stable
+ */
+export type RegistryErrorCode = 'INVALID_ID' | 'INVALID_ENTRY' | 'DUPLICATE_ID' | 'FROZEN' | 'UNKNOWN_ID' | 'DUPLICATE_REGISTRY';
+/**
+ * The single error type every registry operation throws.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   permissions.register(entry);
+ * } catch (err) {
+ *   if (err instanceof RegistryError && err.code === 'DUPLICATE_ID') { ... }
+ * }
+ * ```
+ *
+ * @stability stable
+ */
+export declare class RegistryError extends Error {
+    /** Machine-readable reason; see {@link RegistryErrorCode}. */
+    readonly code: RegistryErrorCode;
+    /** The `name` of the registry that refused the operation. */
+    readonly registry: string;
+    /** The entry id involved, when there is one. */
+    readonly id?: string;
+    /**
+     * @param code - why the operation was refused.
+     * @param registry - the refusing registry's name.
+     * @param message - human-readable explanation.
+     * @param details - the id involved and, for `INVALID_ENTRY`, the original error as `cause`.
+     */
+    constructor(code: RegistryErrorCode, registry: string, message: string, details?: {
+        id?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * How a registry identifies, checks, de-duplicates and orders its entries.
+ *
+ * @typeParam T - the entry type.
+ *
+ * @stability stable
+ */
+export interface RegistryOptions<T> {
+    /**
+     * Name used in errors and introspection, e.g. `'permissions'`. Must be unique
+     * among registries created with {@link defineRegistry}.
+     */
+    name: string;
+    /** Extracts the entry's id. Called once per registration. */
+    idOf: (entry: T) => string;
+    /**
+     * Pattern every id must match. Default {@link DEFAULT_REGISTRY_ID_PATTERN}.
+     * A `g` or `y` flag is ignored, so matching never depends on `lastIndex`.
+     */
+    idPattern?: RegExp;
+    /**
+     * Rejects an entry by throwing (any value). The throw is wrapped as
+     * `INVALID_ENTRY`, keeping the original message and the original error as
+     * `cause`. Runs after the id check and before the duplicate check. During
+     * {@link Registry.registerAll} the registry passed in does not yet contain the
+     * batch's earlier entries.
+     */
+    validate?: (entry: T, registry: Registry<T>) => void;
+    /**
+     * What a second entry with an existing id does. Default `'throw'`
+     * (`DUPLICATE_ID`). `'replace'` keeps the NEW entry at the OLD entry's
+     * position and calls {@link RegistryOptions.onReplace}.
+     */
+    onDuplicate?: 'throw' | 'replace';
+    /**
+     * Called for each replacement under `onDuplicate: 'replace'`, after the write
+     * has been committed (never for a batch that was rejected).
+     */
+    onReplace?: (previous: T, next: T) => void;
+    /**
+     * Custom `DUPLICATE_ID` message. Default:
+     * `Duplicate id "<id>" in registry "<name>".`
+     */
+    describeDuplicate?: (existing: T, incoming: T) => string;
+    /**
+     * The order of {@link Registry.list} and {@link Registry.ids}. Default
+     * `'registration'`. `'id'` sorts by id in code-unit order (locale-independent,
+     * so `'B'` sorts before `'a'`). A comparator sorts entries; ties keep
+     * registration order.
+     */
+    order?: 'registration' | 'id' | ((a: T, b: T) => number);
+}
+/**
+ * The introspection shape of {@link Registry.snapshot}.
+ *
+ * @stability stable
+ */
+export interface RegistrySnapshot {
+    /** The registry's name. */
+    name: string;
+    /** Whether writes are refused. */
+    frozen: boolean;
+    /** Every id, in {@link Registry.list} order. */
+    ids: string[];
+}
+/** Opaque saved state; see {@link Registry._captureState}. @internal */
+export interface RegistryState<T> {
+    readonly entries: ReadonlyMap<string, T>;
+    readonly frozen: boolean;
+}
+/**
+ * An additive, typed, string-keyed list with a duplicate policy, deterministic
+ * order and an optional freeze.
+ *
+ * Entries are stored as given (never cloned); {@link list} and {@link ids}
+ * return fresh arrays, so mutating them never changes the registry. Because the
+ * registry holds references, entries should be `as const` or `Object.freeze`d
+ * data.
+ *
+ * @typeParam T - the entry type.
+ *
+ * @example
+ * ```ts
+ * const colours = new Registry<{ id: string; hex: string }>({
+ *   name: 'colours',
+ *   idOf: (c) => c.id,
+ *   validate: (c) => {
+ *     if (!/^#[0-9a-f]{6}$/i.test(c.hex)) throw new Error(`bad hex ${c.hex}`);
+ *   },
+ * });
+ * colours.register({ id: 'brand', hex: '#3366ff' });
+ * colours.require('brand').hex; // '#3366ff'
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability stable
+ */
+export declare class Registry<T> {
+    private readonly options;
+    /** The registry's name, as given in {@link RegistryOptions.name}. */
+    readonly name: string;
+    private entries;
+    private isFrozen;
+    private readonly idPattern;
+    /**
+     * @param options - see {@link RegistryOptions}.
+     * @throws RegistryError `INVALID_ID` when `options.name` is empty.
+     */
+    constructor(options: RegistryOptions<T>);
+    /**
+     * Adds one entry.
+     *
+     * @throws RegistryError `FROZEN`, `INVALID_ID`, `INVALID_ENTRY` or
+     * `DUPLICATE_ID` (see {@link RegistryErrorCode}); the registry is unchanged
+     * when it throws.
+     */
+    register(entry: T): void;
+    /**
+     * Adds every entry, all or nothing: each entry is checked (id, `validate`,
+     * duplicates against the registry AND earlier entries of the same batch)
+     * before any is added, so one bad entry rejects the whole batch and leaves the
+     * registry unchanged.
+     *
+     * @throws RegistryError as {@link register}; the first failing entry wins.
+     */
+    registerAll(entries: readonly T[]): void;
+    /** The entry registered under `id`, or `undefined`. */
+    get(id: string): T | undefined;
+    /**
+     * The entry registered under `id`.
+     *
+     * @throws RegistryError `UNKNOWN_ID` when there is none.
+     */
+    require(id: string): T;
+    /** Whether an entry is registered under `id`. */
+    has(id: string): boolean;
+    /** Every id, as a fresh array, in {@link list} order. */
+    ids(): string[];
+    /** Every entry, as a fresh array, in the order {@link RegistryOptions.order} names. */
+    list(): T[];
+    /** How many entries are registered. */
+    get size(): number;
+    /** Refuses every later write with `FROZEN`. Reads keep working. Idempotent. */
+    freeze(): void;
+    /** Whether {@link freeze} has been called. */
+    get frozen(): boolean;
+    /** Name, frozen state and ids, for logs, diagnostics and snapshot tests. */
+    snapshot(): RegistrySnapshot;
+    /**
+     * Saves the entries and frozen state. For `testing.ts` only.
+     * @internal
+     */
+    _captureState(): RegistryState<T>;
+    /**
+     * Restores a state saved by {@link _captureState}. For `testing.ts` only.
+     * @internal
+     */
+    _restoreState(state: RegistryState<T>): void;
+    /**
+     * Allows writes again. For `testing.ts` only.
+     * @internal
+     */
+    _unfreeze(): void;
+    private assertWritable;
+    private checkedId;
+    private sortedEntries;
+}
+/**
+ * Creates a module-level ("static") registry and records it in the catalogue,
+ * so {@link freezeDefinedRegistries} (called by `RegistryFreezeService` after
+ * bootstrap) freezes it and {@link listDefinedRegistries} reports it.
+ *
+ * Call it once, at module scope, in the registry's own file; fill it from the
+ * registry's manifest (see README.md next to this file).
+ *
+ * @param options - see {@link RegistryOptions}.
+ * @returns the new registry.
+ * @throws RegistryError `DUPLICATE_REGISTRY` when a defined registry already has that name.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/common/permissions/permission.registry.ts
+ * export const permissionRegistry = defineRegistry<PermissionDefinition>({
+ *   name: 'permissions',
+ *   idOf: (p) => p.id,
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability stable
+ */
+export declare function defineRegistry<T>(options: RegistryOptions<T>): Registry<T>;
+/**
+ * Every registry created with {@link defineRegistry}, in definition order.
+ *
+ * @stability stable
+ */
+export declare function listDefinedRegistries(): ReadonlyArray<Registry<unknown>>;
+/**
+ * Freezes every registry created with {@link defineRegistry}. Idempotent.
+ *
+ * @stability stable
+ */
+export declare function freezeDefinedRegistries(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/registry/registry.d.ts.map

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