@nest-yalc-2/omnikernel-module 1.1.0

package/src/__tests__/omni-external-ref.entity.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniBaseEntity } from '../base/omni-base.entity.js';
+import {
+  OmniExternalRefEntity,
+} from '../base/omni-external-ref.entity.js';
+
+describe('OmniExternalRefEntity', () => {
+  it('extends OmniBaseEntity', () => {
+    expect(new OmniExternalRefEntity()).toBeInstanceOf(OmniBaseEntity);
+  });
+
+  it('registers external mapping columns', () => {
+    const metadata = getMetadataArgsStorage();
+    const table = metadata.tables.find(
+      (item) => item.target === OmniExternalRefEntity,
+    );
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniExternalRefEntity)
+      .map((item) => item.propertyName);
+
+    expect(table?.name).toBe('omni-external-ref');
+    expect(entityColumns).toEqual(
+      expect.arrayContaining([
+        'internalType',
+        'internalId',
+        'provider',
+        'account',
+        'container',
+        'externalId',
+        'payload',
+      ]),
+    );
+  });
+});

package/src/__tests__/omni-external-ref.service.spec.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it, jest } from "@jest/globals";
+
+import { OmniExternalRefService } from '../omni-external-ref.service.js';
+import { OmniExternalRefEntity } from '../base/omni-external-ref.entity.js';
+import { OmniExternalRefInternalType } from '../omni-external-ref-internal-type.enum.js';
+
+const bindingValidator = {
+  assertTarget: jest.fn(async () => ({})),
+};
+
+const createRepositoryPair = () => {
+  const readRepository = {
+    target: OmniExternalRefEntity,
+    findOne: jest.fn(),
+    find: jest.fn(),
+    findOneOrFail: jest.fn(),
+    getId: jest.fn((entity: OmniExternalRefEntity) => ({ guid: entity.guid })),
+  };
+  const writeRepository = {
+    target: OmniExternalRefEntity,
+    create: jest.fn((input: unknown) => input),
+    insert: jest.fn(async () => ({
+      identifiers: [{ guid: "eeeeeeee-1111-1111-1111-111111111111" }],
+    })),
+    update: jest.fn(async () => ({ affected: 1 })),
+  };
+
+  return { readRepository, writeRepository };
+};
+
+describe("OmniExternalRefService", () => {
+  it('requires a binding validator instead of silently bypassing target validation', () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+
+    expect(
+      () =>
+        new OmniExternalRefService(
+          readRepository as never,
+          writeRepository as never,
+          'hard',
+          undefined as never,
+        ),
+    ).toThrow('requires an OmniExternalRefBindingValidator');
+  });
+
+  it("looks up references by provider/external identity", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+
+    await service.findByExternalIdentity({
+      provider: "github",
+      externalId: "123",
+      account: "acme",
+      container: "kb",
+    });
+
+    expect(readRepository.findOne).toHaveBeenCalledWith({
+      where: {
+        scopeId: "default",
+        provider: "github",
+        externalId: "123",
+        account: "acme",
+        container: "kb",
+      },
+    });
+  });
+
+  it("returns all references for an internal record", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+
+    await service.findForInternalRecord(
+      OmniExternalRefInternalType.Document,
+      "doc-1",
+      "github",
+    );
+
+    expect(readRepository.find).toHaveBeenCalledWith({
+      where: {
+        scopeId: "default",
+        internalType: OmniExternalRefInternalType.Document,
+        internalId: "doc-1",
+        provider: "github",
+      },
+      order: {
+        createdAt: "ASC",
+      },
+    });
+  });
+
+  it("creates a new external ref when the identity does not exist", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    readRepository.findOne.mockResolvedValue(null);
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+    const createSpy = jest
+      .spyOn(service, "createEntity")
+      .mockResolvedValue({ guid: "created" } as OmniExternalRefEntity);
+
+    const result = await service.upsertExternalRef({
+      internalType: OmniExternalRefInternalType.Document,
+      internalId: "doc-1",
+      provider: "github",
+      externalId: "123",
+    });
+
+    expect(createSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        internalType: OmniExternalRefInternalType.Document,
+        internalId: "doc-1",
+      }),
+    );
+    expect(result.guid).toBe("created");
+  });
+
+  it("validates record bindings without changing legacy non-record bindings", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    readRepository.findOne.mockResolvedValue(null);
+    const validator = {
+      assertTarget: jest.fn(async () => ({})),
+    };
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      "hard",
+      validator as never,
+    );
+
+    await service.createEntity({
+      guid: "eeeeeeee-1111-1111-1111-111111111112",
+      provider: "example",
+      externalId: "record",
+      internalType: OmniExternalRefInternalType.Record,
+      internalId: "aaaaaaaa-1111-1111-1111-111111111111",
+    });
+    expect(validator.assertTarget).toHaveBeenCalledWith({
+      internalType: OmniExternalRefInternalType.Record,
+      internalId: "aaaaaaaa-1111-1111-1111-111111111111",
+    });
+
+    await service.createEntity({
+      guid: "eeeeeeee-1111-1111-1111-111111111113",
+      provider: "example",
+      externalId: "legacy-document",
+      internalType: OmniExternalRefInternalType.Document,
+      internalId: "aaaaaaaa-1111-1111-1111-111111111112",
+    });
+    expect(validator.assertTarget).toHaveBeenCalledTimes(1);
+  });
+
+  it("updates an existing external ref when the identity already exists", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    readRepository.findOne.mockResolvedValue({
+      guid: "existing-guid",
+      internalType: OmniExternalRefInternalType.Document,
+      internalId: "doc-1",
+    });
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+    const updateSpy = jest
+      .spyOn(service, "updateEntity")
+      .mockResolvedValue({ guid: "existing-guid" } as OmniExternalRefEntity);
+
+    const result = await service.upsertExternalRef({
+      internalType: OmniExternalRefInternalType.Document,
+      internalId: "doc-1",
+      provider: "github",
+      externalId: "123",
+      payload: { synced: true },
+    });
+
+    expect(updateSpy).toHaveBeenCalledWith(
+      { guid: "existing-guid" },
+      expect.objectContaining({
+        payload: { synced: true },
+      }),
+    );
+    expect(result.guid).toBe("existing-guid");
+  });
+
+  it("rejects blank provider or external identity during upsert", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+
+    await expect(
+      service.upsertExternalRef({
+        internalType: OmniExternalRefInternalType.Document,
+        internalId: "doc-1",
+        provider: "",
+        externalId: "123",
+      }),
+    ).rejects.toThrow("OmniExternalRef.provider is required");
+
+    await expect(
+      service.upsertExternalRef({
+        internalType: OmniExternalRefInternalType.Document,
+        internalId: "doc-1",
+        provider: "github",
+        externalId: "   ",
+      }),
+    ).rejects.toThrow("OmniExternalRef.externalId is required");
+  });
+
+  it("syncs document references with the document internal type", async () => {
+    const { readRepository, writeRepository } = createRepositoryPair();
+    const service = new OmniExternalRefService(
+      readRepository as never,
+      writeRepository as never,
+      'hard',
+      bindingValidator as never,
+    );
+    const upsertSpy = jest
+      .spyOn(service, "upsertExternalRef")
+      .mockResolvedValue({ guid: "doc-ref" } as OmniExternalRefEntity);
+
+    await service.syncDocumentReference("doc-1", {
+      provider: "github",
+      externalId: "123",
+      account: "acme",
+    });
+
+    expect(upsertSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        internalType: OmniExternalRefInternalType.Document,
+        internalId: "doc-1",
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,33 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniBaseEntity } from '../base/omni-base.entity.js';
+import { OmniNamedEntity } from '../base/omni-named.entity.js';
+
+describe('OmniNamedEntity', () => {
+  it('extends OmniBaseEntity', () => {
+    expect(new OmniNamedEntity()).toBeInstanceOf(OmniBaseEntity);
+  });
+
+  it('registers the expected table and columns', () => {
+    const metadata = getMetadataArgsStorage();
+    const table = metadata.tables.find(
+      (item) => item.target === OmniNamedEntity,
+    );
+    const baseColumns = metadata.columns
+      .filter((item) => item.target === OmniBaseEntity)
+      .map((item) => item.propertyName);
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniNamedEntity)
+      .map((item) => item.propertyName);
+
+    expect(table?.name).toBe('omni-named');
+    expect(baseColumns).toEqual(expect.arrayContaining(['guid']));
+    expect(metadata.columns.map((item) => item.propertyName)).toEqual(
+      expect.arrayContaining(['createdAt', 'updatedAt']),
+    );
+    expect(entityColumns).toEqual(
+      expect.arrayContaining(['externalId', 'title', 'slug']),
+    );
+  });
+});

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniNamedEntity } from '../base/omni-named.entity.js';
+import { OmniRecordEntity } from '../base/omni-record.entity.js';
+
+describe('OmniRecordEntity', () => {
+  it('extends OmniNamedEntity', () => {
+    expect(new OmniRecordEntity()).toBeInstanceOf(OmniNamedEntity);
+  });
+
+  it('registers core columns and directional relations', () => {
+    const metadata = getMetadataArgsStorage();
+    const table = metadata.tables.find(
+      (item) => item.target === OmniRecordEntity,
+    );
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniRecordEntity)
+      .map((item) => item.propertyName);
+    const relations = metadata.relations
+      .filter((item) => item.target === OmniRecordEntity)
+      .map((item) => item.propertyName);
+
+    expect(table?.name).toBe('omni-record');
+    expect(entityColumns).toEqual(
+      expect.arrayContaining(['kind', 'status', 'payload']),
+    );
+    expect(relations).toEqual(
+      expect.arrayContaining(['outgoingRelations', 'incomingRelations']),
+    );
+  });
+});

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

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it } from '@jest/globals';
+import { DataSource } from 'typeorm';
+
+import { OmniNamedEntity } from '../base/omni-named.entity.js';
+import { OmniRecordEntity } from '../base/omni-record.entity.js';
+import { OmniRelationEntity } from '../base/omni-relation.entity.js';
+import { OmniExternalRefEntity } from '../base/omni-external-ref.entity.js';
+import { OmniRecordStatus } from '../omni-record-status.enum.js';
+import { OmniRecordService } from '../omni-record.service.js';
+
+const scope = {
+  scopeId: 'scope-record-guard',
+  cacheKey: (key: string) => `scope-record-guard:${key}`,
+};
+const reservedKind = 'registered_extension';
+const ownerGuid = '10000000-0000-4000-8000-000000000301';
+const normalGuid = '10000000-0000-4000-8000-000000000302';
+
+describe('OmniRecordService extension owner guard', () => {
+  let dataSource: DataSource;
+  let service: InstanceType<typeof OmniRecordService>;
+
+  beforeEach(async () => {
+    dataSource = new DataSource({
+      type: 'sqlite',
+      database: ':memory:',
+      dropSchema: true,
+      synchronize: true,
+      entities: [
+        OmniNamedEntity,
+        OmniRecordEntity,
+        OmniRelationEntity,
+        OmniExternalRefEntity,
+      ],
+    });
+    await dataSource.initialize();
+    service = new OmniRecordService(
+      dataSource.getRepository(OmniRecordEntity) as never,
+      scope,
+      'tombstone',
+      [reservedKind],
+    );
+    await dataSource.getRepository(OmniRecordEntity).save({
+      scopeId: scope.scopeId,
+      guid: ownerGuid,
+      title: 'Extension-owned record',
+      kind: reservedKind,
+      status: OmniRecordStatus.Active,
+      payloadSchemaId: 'registered.extension.v1',
+      payloadSchemaVersion: 1,
+    });
+  });
+
+  afterEach(async () => {
+    await dataSource.destroy();
+  });
+
+  it('rejects generic creation, mutation, promotion, and deletion of a reserved extension owner', async () => {
+    await expect(
+      service.createEntity({
+        guid: '10000000-0000-4000-8000-000000000303',
+        title: 'Attempted extension owner',
+        kind: reservedKind,
+        status: OmniRecordStatus.Active,
+      }),
+    ).rejects.toThrow('owned by a registered extension projection');
+
+    await service.createEntity({
+      guid: normalGuid,
+      title: 'Normal record',
+      kind: 'normal_record',
+      status: OmniRecordStatus.Active,
+    });
+    await expect(
+      service.updateEntity(
+        { guid: normalGuid },
+        { kind: reservedKind },
+      ),
+    ).rejects.toThrow('owned by a registered extension projection');
+    await expect(
+      service.updateEntity(
+        { guid: ownerGuid },
+        { kind: 'normal_record' },
+      ),
+    ).rejects.toThrow('owned by a registered extension projection');
+    await expect(service.deleteEntity({ guid: ownerGuid })).rejects.toThrow(
+      'owned by a registered extension projection',
+    );
+
+    expect(
+      await dataSource.getRepository(OmniRecordEntity).findOneByOrFail({
+        scopeId: scope.scopeId,
+        guid: ownerGuid,
+      }),
+    ).toMatchObject({
+      kind: reservedKind,
+      payloadSchemaId: 'registered.extension.v1',
+      payloadSchemaVersion: 1,
+    });
+    expect(
+      await dataSource.getRepository(OmniRecordEntity).findOneByOrFail({
+        scopeId: scope.scopeId,
+        guid: normalGuid,
+      }),
+    ).toMatchObject({ kind: 'normal_record' });
+  });
+});

package/src/__tests__/omni-relation-semantics.spec.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { OmniCollectionKind } from '../omni-collection-kind.enum.js';
+import { OmniDocumentKind } from '../omni-document-kind.enum.js';
+import { OmniRelationKind } from '../omni-relation-kind.enum.js';
+import {
+  OMNI_COLLECTION_MEMBERSHIP_RELATION_KIND,
+  isAllowedOmniRelation,
+  isCanonicalCollectionMembershipRelation,
+  isOmniCollectionRecordKind,
+  isOmniDocumentRecordKind,
+} from '../omni-relation-semantics.js';
+
+describe('Omni relation semantics', () => {
+  it('treats collection contains as the canonical collection membership edge', () => {
+    expect(OMNI_COLLECTION_MEMBERSHIP_RELATION_KIND).toBe(
+      OmniRelationKind.Contains,
+    );
+    expect(
+      isCanonicalCollectionMembershipRelation({
+        sourceKind: OmniCollectionKind.Collection,
+        relationKind: OmniRelationKind.Contains,
+      }),
+    ).toBe(true);
+    expect(
+      isCanonicalCollectionMembershipRelation({
+        sourceKind: OmniDocumentKind.Document,
+        relationKind: OmniRelationKind.Contains,
+      }),
+    ).toBe(false);
+  });
+
+  it('recognizes the current concrete record families', () => {
+    expect(isOmniCollectionRecordKind(OmniCollectionKind.Collection)).toBe(
+      true,
+    );
+    expect(isOmniCollectionRecordKind(OmniDocumentKind.Document)).toBe(false);
+    expect(isOmniDocumentRecordKind(OmniDocumentKind.Document)).toBe(true);
+    expect(isOmniDocumentRecordKind(OmniCollectionKind.Collection)).toBe(false);
+  });
+
+  it('allows collection-to-document contains links and rejects the reversed organization edge', () => {
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniCollectionKind.Collection,
+        targetKind: OmniDocumentKind.Document,
+        relationKind: OmniRelationKind.Contains,
+      }),
+    ).toBe(true);
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniDocumentKind.Document,
+        targetKind: OmniCollectionKind.Collection,
+        relationKind: OmniRelationKind.Contains,
+      }),
+    ).toBe(false);
+  });
+
+  it('limits derived_from to document lineage', () => {
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniDocumentKind.Document,
+        targetKind: OmniDocumentKind.Document,
+        relationKind: OmniRelationKind.DerivedFrom,
+      }),
+    ).toBe(true);
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniCollectionKind.Collection,
+        targetKind: OmniDocumentKind.Document,
+        relationKind: OmniRelationKind.DerivedFrom,
+      }),
+    ).toBe(false);
+  });
+
+  it('keeps references and related_to flexible for cross-record graph links', () => {
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniDocumentKind.Document,
+        targetKind: OmniCollectionKind.Collection,
+        relationKind: OmniRelationKind.References,
+      }),
+    ).toBe(true);
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniCollectionKind.Collection,
+        targetKind: OmniDocumentKind.Document,
+        relationKind: OmniRelationKind.RelatedTo,
+      }),
+    ).toBe(true);
+  });
+
+  it('returns false for unexpected relation values at runtime', () => {
+    expect(
+      isAllowedOmniRelation({
+        sourceKind: OmniCollectionKind.Collection,
+        targetKind: OmniDocumentKind.Document,
+        relationKind: 'unexpected' as OmniRelationKind,
+      }),
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,38 @@
+import { describe, expect, it } from '@jest/globals';
+import { getMetadataArgsStorage } from 'typeorm';
+
+import { OmniBaseEntity } from '../base/omni-base.entity.js';
+import { OmniRelationEntity } from '../base/omni-relation.entity.js';
+
+describe('OmniRelationEntity', () => {
+  it('extends OmniBaseEntity', () => {
+    expect(new OmniRelationEntity()).toBeInstanceOf(OmniBaseEntity);
+  });
+
+  it('registers the record linkage columns and relations', () => {
+    const metadata = getMetadataArgsStorage();
+    const table = metadata.tables.find(
+      (item) => item.target === OmniRelationEntity,
+    );
+    const entityColumns = metadata.columns
+      .filter((item) => item.target === OmniRelationEntity)
+      .map((item) => item.propertyName);
+    const relations = metadata.relations
+      .filter((item) => item.target === OmniRelationEntity)
+      .map((item) => item.propertyName);
+
+    expect(table?.name).toBe('omni-relation');
+    expect(entityColumns).toEqual(
+      expect.arrayContaining([
+        'sourceRecordId',
+        'targetRecordId',
+        'kind',
+        'status',
+        'payload',
+      ]),
+    );
+    expect(relations).toEqual(
+      expect.arrayContaining(['sourceRecord', 'targetRecord']),
+    );
+  });
+});

package/src/__tests__/omni-scope-substrate.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, jest } from "@jest/globals";
+
+import { canonicalOmniRelationKinds, createOmniRelationKindContract } from '../omni-relation-kind.contract.js';
+import { normalizeOmniKernelRegistrationOptions, OmniScopeContext } from '../omni-scope.js';
+import { OmniScopedRepository } from '../omni-scoped.repository.js';
+
+describe("Omni scoped substrate", () => {
+  it("derives a trusted scope, scopes cache keys, and rejects invalid registration", () => {
+    const options = normalizeOmniKernelRegistrationOptions({
+      dbConnection: "default",
+      defaultScopeId: "fallback",
+      resolveScope: (request) =>
+        (request as { authenticatedScope?: string }).authenticatedScope,
+      relationKinds: ["blocks"],
+      deletion: { record: "tombstone" },
+    });
+    const scope = new OmniScopeContext(
+      { req: { authenticatedScope: "scope-alpha" } },
+      options,
+    );
+
+    expect(scope.scopeId).toBe("scope-alpha");
+    expect(scope.cacheKey("record-1")).toBe("scope-alpha:record-1");
+    expect(options.deletion.document).toBe("tombstone");
+    expect(() => new OmniScopeContext({ req: {} }, options)).toThrow(
+      "unavailable",
+    );
+    expect(() =>
+      normalizeOmniKernelRegistrationOptions({
+        dbConnection: "",
+      }),
+    ).toThrow("database connection");
+    expect(() =>
+      normalizeOmniKernelRegistrationOptions({
+        dbConnection: "default",
+        deletion: { record: "erase" as never },
+      }),
+    ).toThrow("must be hard or tombstone");
+    expect(() =>
+      normalizeOmniKernelRegistrationOptions({
+        dbConnection: "default",
+        deletion: { records: "tombstone" } as never,
+      }),
+    ).toThrow("Unknown OmniKernel deletion policy resource");
+  });
+
+  it("keeps canonical relation kinds stable while validating registered extensions", () => {
+    const contract = createOmniRelationKindContract(["blocks"]);
+
+    expect(canonicalOmniRelationKinds).toContain("contains");
+    expect(contract.has("blocks")).toBe(true);
+    expect(() => contract.assert("unknown")).toThrow("not registered");
+    expect(() => createOmniRelationKindContract(["not portable!"])).toThrow(
+      "lowercase letters",
+    );
+  });
+
+  it("adds scope to lower-level repository queries and refuses caller scope input", async () => {
+    const repository = {
+      find: jest.fn(async () => []),
+      findOne: jest.fn(async () => null),
+    };
+    const scoped = new OmniScopedRepository(repository as never, {
+      scopeId: "scope-alpha",
+      cacheKey: (key: string) => key,
+    });
+
+    await scoped.findOneByGuid("record-1");
+    await scoped.find({ title: "Scoped record" } as never);
+
+    expect(repository.findOne).toHaveBeenCalledWith({
+      where: { guid: "record-1", scopeId: "scope-alpha" },
+    });
+    expect(repository.find).toHaveBeenCalledWith({
+      where: { title: "Scoped record", scopeId: "scope-alpha" },
+    });
+    expect(() => scoped.where({ scopeId: "scope-bravo" } as never)).toThrow(
+      "derived from server context",
+    );
+  });
+});