@nest-yalc-2/omnikernel-module 1.1.0

package/README.md

@@ -0,0 +1,193 @@
+# OmniKernel Module
+
+`@nest-yalc-2/omnikernel-module` is the public package that provides the
+reusable OmniKernel persistence substrate. It is built and published with the
+normal framework release pipeline.
+
+The module deliberately contains no REST controllers, GraphQL resolvers, or
+application authentication. A consuming app owns those protocol and trust
+boundaries by composing the exported backend factories with CrudGen.
+
+## Build and package boundary
+
+The root `npm run build` first emits the shared workspace declarations and
+then builds this module into `dist/src`. The package manifest exports only that
+compiled directory and declares only versioned internal dependencies, so a
+tarball does not depend on a consumer being adjacent to this repository.
+
+```bash
+npm install @nest-yalc-2/omnikernel-module
+```
+
+The source workspace builds into its local `dist/src`; the root release build
+then materializes the package into `var/dist/omnikernel-module` with versioned
+internal dependencies. Generated output is not committed.
+
+## Server-owned scope
+
+Every Omni resource has a composite `(scopeId, guid)` identity. `scopeId` is
+never an API input or output field: the request-scoped `OmniScopeContext`
+derives it from a trusted adapter or an explicitly configured server default.
+All generated CRUD reads, grids, mutations, relations, external references,
+repositories, and dataloader cache keys use that context.
+
+```ts
+import { OmniKernelModule } from "@nest-yalc-2/omnikernel-module";
+
+@Module({
+  imports: [
+    OmniKernelModule.register({
+      dbConnection: "default",
+      resolveScope(request) {
+        return authenticateRequest(request).scopeId;
+      },
+      relationKinds: ["blocks"],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`resolveScope` must authenticate and authorize the request before returning a
+scope. When a resolver is configured, an absent or invalid result fails closed
+and never falls back to the default partition. The optional `defaultScopeId` is
+a server configuration compatibility partition only for an app without an
+adapter; it does not read a client field.
+
+## Resources and lifecycle
+
+| Resource           | Delete policy | Scoped database protection                  |
+| ------------------ | ------------- | ------------------------------------------- |
+| Named              | hard delete   | composite primary key                       |
+| Record             | tombstone     | composite primary key and grid index        |
+| Document           | tombstone     | record inheritance and grid index           |
+| Collection         | tombstone     | record inheritance and grid index           |
+| Relation           | hard delete   | composite foreign keys and endpoint indexes |
+| External reference | hard delete   | scoped external-identity unique index       |
+
+The default policies can be overridden at registration with `deletion`. A
+tombstoned resource is excluded from normal generated reads and mutations; the
+row remains available for a retention or recovery workflow owned by the app.
+
+Relations preserve the canonical `contains`, `references`, `related_to`, and
+`derived_from` constants. An app may register further lowercase relation kinds
+through `relationKinds`; unregistered kinds are rejected. Canonical endpoint
+semantics remain enforced, while extra kinds have no hidden generic policy.
+
+## Omni-owned extension projections
+
+An extension projection adds typed, generated CRUD without making a second
+root identity. Its dynamically generated table has `(scopeId, guid)` and a
+composite foreign key to `omni-record`; the owner remains the only authority
+for scope, identity, revision, timestamps, deletion, kind, and payload-schema
+metadata. The extension owns only its declared promoted columns and `payload`.
+
+Use `createOmniExtensionProjectionEntity` and
+`createOmniExtensionProjectionRegistration` from the package entrypoint. A
+registration returns its TypeORM entity, one generated CrudGen REST controller,
+one generated GraphQL resolver, its request-scoped service and dataloader
+providers, a fixed owner-kind reservation, and a reader registration. Compose
+those returned values into the app module; do not add a hand-written controller
+or resolver for ordinary create/read/grid/update/delete operations.
+
+Register every returned `reservedRecordKinds` value with
+`OmniKernelModule.register`. The generic record service then rejects creating,
+changing into, updating, or deleting an extension-owned record kind. The
+extension service is the sole generic path that can transact the owner and its
+extension row together.
+
+The extension table uses JSON1 text on SQLite and native `jsonb` on PostgreSQL.
+All JSON reads, predicates, mutation expressions, indexes, and inspection stay
+inside `ProjectionDialect`; applications only declare projection metadata.
+Owner revision is the optimistic-concurrency value exposed by both generated
+transports.
+
+### Lifecycle policies and transaction readers
+
+An optional `OmniProjectionLifecycleProvider` accepts a Nest injection token,
+not a prebuilt policy instance. Give the same token to an extension and/or
+relation registration. The factory resolves the request-scoped policy and runs
+`beforeCreate`, `beforeUpdate`, and `beforeDelete` in the store transaction,
+so REST and GraphQL have identical enforcement.
+
+If the application and this file package resolve separate physical copies of
+`@nestjs/core`, pass the application's `ModuleRef` provider token as
+`moduleRefToken` to each registration. CrudGen injects that explicit token into
+the generated resolver; no optional dependency or consumer cast is required.
+
+Build one `createOmniProjectionReaderCatalogProvider` from the `reader` values
+returned by the registrations. Lifecycle contexts receive the active
+`EntityManager` and manager-bound `readers`, rather than repositories. An
+extension reader supports declared equality filters and `take: 1..1000`; a
+relation reader supports scoped source/target filters and the same bounded
+`take`. Readers always enforce their registration's owner or relation metadata.
+Lifecycle-bearing writes use `SERIALIZABLE`; serialization or SQLite busy
+failures are reported as retryable conflicts.
+
+## Relation projections
+
+`createOmniRelationProjectionRegistration` creates one generated REST,
+GraphQL, and dataloader surface over the existing `omni-relation` table. It
+never creates a duplicate relation table. A definition has either legacy fixed
+`kind` or a non-empty unique `allowedKinds` list, fixed source/target record
+kinds, and fixed status/schema metadata. For a multi-kind resource, create
+requires one allowed kind; all reads, grids, updates, and deletes mechanically
+constrain that set and the fixed metadata. Endpoints and kind are immutable;
+payload updates require `expectedRevision` and atomically increment revision.
+
+Definitions may map public `kind`, `source`, `target`, and `payload` aliases to
+the native relation fields, keeping generated transports application-neutral.
+Relations require same-scope endpoints and retain the registered endpoint-kind
+checks. `OmniRelationEntity.payload` remains the existing portable
+`simple-json` column on both drivers; unlike an extension projection it is not
+advertised as PostgreSQL `jsonb`.
+
+## Versioned migration snapshots
+
+`captureOmniMigrationSnapshot` is an authoring-only helper. Capture it while
+reviewing a schema, copy the resulting literal into a versioned migration, and
+pass that literal through `defineOmniMigrationSnapshot` and
+`createOmniMigrationPlan`. A runtime migration never reads current TypeORM
+metadata or runs synchronize. The immutable snapshot includes both table
+options and dialect-compiled expression-index statements.
+
+`plan.create(queryRunner)` creates foreign-key parents before children, then
+creates expression indexes. `plan.drop(queryRunner)` drops the reverse order.
+The accepted argument is the package-owned `OmniMigrationRunner` capability
+contract (`createTable` and `query`), so an app's TypeORM `QueryRunner` works
+without a cast even when package-manager paths duplicate TypeORM. Cross-table
+foreign-key cycles and a missing referenced snapshot table fail clearly during
+migration authoring.
+This keeps app migrations free of repeated projection SQL and supports
+reversible SQLite and PostgreSQL migrations.
+
+## Payload contract
+
+Raw `payload` accepts a JSON object or `null`. Writes replace the complete
+value; OmniKernel does not provide raw JSON patching or typed payload filters.
+`payloadSchemaId` and positive `payloadSchemaVersion` are supplied together to
+identify the app-owned schema revision.
+
+The raw Omni payload is `simple-json`, so it is portable but opaque to the
+generic API, including PostgreSQL. Use the separate CrudGen scoped projection
+contract when a resource needs native PostgreSQL `jsonb`, typed filtering,
+sorting, or revision patch semantics; see
+[`docs/crud-gen-projections.md`](../../../docs/crud-gen-projections.md).
+
+## Indexes and bounded diagnostics
+
+The schema declares driver-portable composite indexes for record grid reads,
+relation source/target traversal, and external-reference lookup, plus scoped
+uniqueness for relations and external identities. `collectOmniKernelQueryPlanEvidence`
+uses diagnostic-only `EXPLAIN` statements for the record grid and relation
+source shapes. It does not replace TypeORM CRUD or certify a production scale
+SLA; callers must run their own production-volume measurements.
+
+## Exports
+
+The package exports entities, DTO metadata, scoped services and repositories,
+dataloaders, backend provider factories, relation-kind helpers, query helpers,
+and diagnostic helpers. Runtime imports resolve to `dist`, not TypeScript
+source files.
+
+Use `examples/omnikernel/app` for generated REST and GraphQL composition.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nest-yalc-2/omnikernel-module",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Foundational OmniKernel persistence module for nestjs-yalc",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./*.js": "./src/*.js",
+    "./*": "./src/*"
+  },
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@nest-yalc-2/crud-gen": "^1.5.0",
+    "@nest-yalc-2/data-loader": "^1.0.0",
+    "@nest-yalc-2/event-manager": "^1.3.4",
+    "@nest-yalc-2/graphql": "^1.0.0",
+    "@nest-yalc-2/types": "^1.0.0",
+    "@nest-yalc-2/utils": "^1.0.0",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@nestjs/event-emitter": "^3.0.1",
+    "@nestjs/graphql": "^13.2.5",
+    "@nestjs/typeorm": "^11.0.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "graphql": "^16.13.2",
+    "graphql-type-json": "^0.3.2",
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "^0.3.28"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nek97/nestjs-yalc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nek97/nestjs-yalc/issues"
+  },
+  "homepage": "https://github.com/Nek97/nestjs-yalc#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/omni-collection.entity.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniRecordEntity } from '../base/omni-record.entity.js';
+import { OmniCollectionEntity } from '../omni-collection.entity.js';
+import { OmniCollectionKind } from '../omni-collection-kind.enum.js';
+
+describe('OmniCollectionEntity', () => {
+  it('extends OmniRecordEntity', () => {
+    expect(new OmniCollectionEntity()).toBeInstanceOf(OmniRecordEntity);
+  });
+
+  it('stores collections as child records in the omni-record table', () => {
+    const metadata = getMetadataArgsStorage();
+    const recordTable = metadata.tables.find(
+      (item) => item.target === OmniRecordEntity,
+    );
+    const collectionTable = metadata.tables.find(
+      (item) => item.target === OmniCollectionEntity,
+    );
+    const inheritance = metadata.inheritances.find(
+      (item) => item.target === OmniRecordEntity,
+    );
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniCollectionEntity)
+      .map((item) => item.propertyName);
+
+    expect(recordTable?.name).toBe('omni-record');
+    expect(collectionTable?.type).toBe('entity-child');
+    expect(inheritance?.column).toMatchObject({ name: 'recordType' });
+    expect(entityColumns).toEqual(
+      expect.arrayContaining(['collectionKind', 'summary']),
+    );
+  });
+
+  it('defaults the base record kind to collection in the class instance', () => {
+    const entity = new OmniCollectionEntity();
+
+    expect(entity.kind).toBe(OmniCollectionKind.Collection);
+  });
+
+  it('allows explicit collection subtypes while keeping the base record kind stable', () => {
+    const entity = new OmniCollectionEntity();
+    entity.collectionKind = OmniCollectionKind.Folder;
+
+    expect(entity.kind).toBe(OmniCollectionKind.Collection);
+    expect(entity.collectionKind).toBe(OmniCollectionKind.Folder);
+  });
+});

package/src/__tests__/omni-collection.service.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { OmniCollectionService } from '../omni-collection.service.js';
+import { OmniCollectionEntity } from '../omni-collection.entity.js';
+import { OmniCollectionKind } from '../omni-collection-kind.enum.js';
+
+const createRepositoryPair = () => {
+  const readRepository = {
+    target: OmniCollectionEntity,
+    findOneOrFail: jest.fn(),
+    getId: jest.fn((entity: OmniCollectionEntity) => ({ guid: entity.guid })),
+  };
+  const writeRepository = {
+    target: OmniCollectionEntity,
+    create: jest.fn((input: unknown) => input),
+    insert: jest.fn(async () => ({
+      identifiers: [{ guid: 'aaaaaaaa-1111-1111-1111-111111111111' }],
+    })),
+    update: jest.fn(async () => ({ affected: 1 })),
+  };
+
+  return { readRepository, writeRepository };
+};
+
+describe('OmniCollectionService', () => {
+  it('forces the base record kind during createEntity', async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniCollectionService(
+      readRepository as never,
+      writeRepository as never,
+    );
+
+    await service.createEntity(
+      {
+        guid: 'aaaaaaaa-1111-1111-1111-111111111111',
+        title: 'Collection',
+        kind: 'unexpected-kind',
+        collectionKind: OmniCollectionKind.Folder,
+      },
+      undefined,
+      false,
+    );
+
+    expect(writeRepository.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: OmniCollectionKind.Collection,
+        collectionKind: OmniCollectionKind.Folder,
+      }),
+    );
+  });
+
+  it('forces the base record kind during updateEntity', async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniCollectionService(
+      readRepository as never,
+      writeRepository as never,
+    );
+    (service as any).validateConditions = jest.fn(async () => ({
+      guid: 'aaaaaaaa-1111-1111-1111-111111111111',
+    }));
+
+    await service.updateEntity(
+      { guid: 'aaaaaaaa-1111-1111-1111-111111111111' },
+      {
+        kind: 'unexpected-kind',
+        collectionKind: OmniCollectionKind.Folder,
+      },
+      undefined,
+      false,
+    );
+
+    expect(writeRepository.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        guid: 'aaaaaaaa-1111-1111-1111-111111111111',
+        kind: OmniCollectionKind.Collection,
+      }),
+      expect.objectContaining({
+        kind: OmniCollectionKind.Collection,
+        collectionKind: OmniCollectionKind.Folder,
+      }),
+    );
+  });
+});

package/src/__tests__/omni-document.entity.spec.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniRecordEntity } from '../base/omni-record.entity.js';
+import { OmniDocumentEntity } from '../omni-document.entity.js';
+import { OmniDocumentKind } from '../omni-document-kind.enum.js';
+
+describe('OmniDocumentEntity', () => {
+  it('extends OmniRecordEntity', () => {
+    expect(new OmniDocumentEntity()).toBeInstanceOf(OmniRecordEntity);
+  });
+
+  it('stores documents as child records in the omni-record table', () => {
+    const metadata = getMetadataArgsStorage();
+    const recordTable = metadata.tables.find(
+      (item) => item.target === OmniRecordEntity,
+    );
+    const documentTable = metadata.tables.find(
+      (item) => item.target === OmniDocumentEntity,
+    );
+    const inheritance = metadata.inheritances.find(
+      (item) => item.target === OmniRecordEntity,
+    );
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniDocumentEntity)
+      .map((item) => item.propertyName);
+
+    expect(recordTable?.name).toBe('omni-record');
+    expect(documentTable?.type).toBe('entity-child');
+    expect(inheritance?.column).toMatchObject({ name: 'recordType' });
+    expect(entityColumns).toEqual(
+      expect.arrayContaining([
+        'documentKind',
+        'content',
+        'contentMimeType',
+        'sourceUrl',
+        'publishedAt',
+      ]),
+    );
+  });
+
+  it('defaults the base record kind to document in the class instance', () => {
+    const entity = new OmniDocumentEntity();
+
+    expect(entity.kind).toBe(OmniDocumentKind.Document);
+  });
+
+  it('allows explicit document subtypes while keeping the base record kind stable', () => {
+    const entity = new OmniDocumentEntity();
+    entity.documentKind = OmniDocumentKind.Note;
+
+    expect(entity.kind).toBe(OmniDocumentKind.Document);
+    expect(entity.documentKind).toBe(OmniDocumentKind.Note);
+  });
+});

package/src/__tests__/omni-document.service.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { OmniDocumentService } from '../omni-document.service.js';
+import { OmniDocumentEntity } from '../omni-document.entity.js';
+import { OmniDocumentKind } from '../omni-document-kind.enum.js';
+
+const createRepositoryPair = () => {
+  const readRepository = {
+    target: OmniDocumentEntity,
+    findOneOrFail: jest.fn(),
+    getId: jest.fn((entity: OmniDocumentEntity) => ({ guid: entity.guid })),
+  };
+  const writeRepository = {
+    target: OmniDocumentEntity,
+    create: jest.fn((input: unknown) => input),
+    insert: jest.fn(async () => ({
+      identifiers: [{ guid: '11111111-1111-1111-1111-111111111111' }],
+    })),
+    update: jest.fn(async () => ({ affected: 1 })),
+  };
+
+  return { readRepository, writeRepository };
+};
+
+describe('OmniDocumentService', () => {
+  it('forces the base record kind during createEntity', async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniDocumentService(
+      readRepository as never,
+      writeRepository as never,
+    );
+
+    await service.createEntity(
+      {
+        guid: '11111111-1111-1111-1111-111111111111',
+        title: 'Document',
+        kind: 'unexpected-kind',
+        documentKind: OmniDocumentKind.Note,
+      },
+      undefined,
+      false,
+    );
+
+    expect(writeRepository.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: OmniDocumentKind.Document,
+        documentKind: OmniDocumentKind.Note,
+      }),
+    );
+  });
+
+  it('forces the base record kind during updateEntity', async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniDocumentService(
+      readRepository as never,
+      writeRepository as never,
+    );
+    (service as any).validateConditions = jest.fn(async () => ({
+      guid: '11111111-1111-1111-1111-111111111111',
+    }));
+
+    await service.updateEntity(
+      { guid: '11111111-1111-1111-1111-111111111111' },
+      {
+        kind: 'unexpected-kind',
+        documentKind: OmniDocumentKind.Article,
+      },
+      undefined,
+      false,
+    );
+
+    expect(writeRepository.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        guid: '11111111-1111-1111-1111-111111111111',
+        kind: OmniDocumentKind.Document,
+      }),
+      expect.objectContaining({
+        kind: OmniDocumentKind.Document,
+        documentKind: OmniDocumentKind.Article,
+      }),
+    );
+  });
+});