@elevasis/core 0.7.1 → 0.8.2

package/src/organization-model/__tests__/schema.test.ts

@@ -1,407 +1,407 @@
-import { describe, expect, it } from 'vitest'
-import { DEFAULT_ORGANIZATION_MODEL_BRANDING } from '../domains/branding'
-import { DEFAULT_ORGANIZATION_MODEL_SALES } from '../domains/sales'
-import { DEFAULT_ORGANIZATION_MODEL_PROJECTS } from '../domains/projects'
-import { DEFAULT_ORGANIZATION_MODEL_PROSPECTING } from '../domains/prospecting'
-import { OrganizationModelSchema } from '../schema'
-
-// ---------------------------------------------------------------------------
-// Minimal valid fixture builders
-// ---------------------------------------------------------------------------
-
-function makeFeature(id: string, surfaceIds: string[] = [], resourceIds: string[] = []) {
-  return {
-    id,
-    label: id,
-    enabled: true,
-    entityIds: [],
-    surfaceIds,
-    resourceIds,
-    capabilityIds: []
-  }
-}
-
-function makeSurface(id: string, featureIds: string[] = [], resourceIds: string[] = []) {
-  return {
-    id,
-    label: id,
-    path: `/${id}`,
-    surfaceType: 'page' as const,
-    featureIds,
-    entityIds: [],
-    resourceIds,
-    capabilityIds: []
-  }
-}
-
-function makeGroup(id: string, surfaceIds: string[] = []) {
-  return { id, label: id, placement: 'primary' as const, surfaceIds }
-}
-
-function makeResourceMapping(id: string, resourceId: string, featureIds: string[] = [], surfaceIds: string[] = []) {
-  return {
-    id,
-    label: id,
-    resourceId,
-    resourceType: 'workflow' as const,
-    featureIds,
-    entityIds: [],
-    surfaceIds,
-    capabilityIds: []
-  }
-}
-
-/**
- * A minimal model that satisfies all base-schema field requirements.
- * The crm/leadGen/delivery fields use the official defaults so the schema
- * layer validates cleanly, leaving superRefine as the only concern.
- */
-function makeMinimalModel(
-  navOverride: { defaultSurfaceId?: string; surfaces?: unknown[]; groups?: unknown[] } = {},
-  extras: { features?: unknown[]; resourceMappings?: unknown[] } = {}
-) {
-  return {
-    version: 1 as const,
-    features: extras.features ?? [],
-    branding: DEFAULT_ORGANIZATION_MODEL_BRANDING,
-    navigation: {
-      defaultSurfaceId: navOverride.defaultSurfaceId,
-      surfaces: navOverride.surfaces ?? [],
-      groups: navOverride.groups ?? []
-    },
-    sales: DEFAULT_ORGANIZATION_MODEL_SALES,
-    prospecting: DEFAULT_ORGANIZATION_MODEL_PROSPECTING,
-    projects: DEFAULT_ORGANIZATION_MODEL_PROJECTS,
-    resourceMappings: extras.resourceMappings ?? []
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helper: collect all Zod issue messages from a failed parse
-// ---------------------------------------------------------------------------
-
-function getIssueMessages(data: unknown): string[] {
-  const result = OrganizationModelSchema.safeParse(data)
-  if (result.success) return []
-  return result.error.issues.map((i) => i.message)
-}
-
-// ---------------------------------------------------------------------------
-// Group 1: Bidirectional feature <-> surface refs
-// ---------------------------------------------------------------------------
-
-describe('bidirectional feature <-> surface refs', () => {
-  it('passes when feature and surface correctly reference each other', () => {
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('crm.pipeline', ['crm'])], groups: [] },
-      { features: [makeFeature('crm', ['crm.pipeline'])] }
-    )
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-
-  it('throws when feature references a surface that does not exist', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      { features: [makeFeature('crm', ['nonexistent-surface'])] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('references unknown surface'))).toBe(true)
-  })
-
-  it('throws when feature references a surface that does not include the feature', () => {
-    // Surface exists but its featureIds does not contain 'crm'
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('crm.pipeline', [] /* featureIds omits 'crm' */)], groups: [] },
-      { features: [makeFeature('crm', ['crm.pipeline'])] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('does not include feature'))).toBe(true)
-  })
-
-  it('throws when surface references a feature that does not exist', () => {
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('crm.pipeline', ['nonexistent-feature'])], groups: [] },
-      { features: [] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('references unknown feature'))).toBe(true)
-  })
-
-  it('throws when surface references a feature that does not include the surface', () => {
-    // Feature exists but its surfaceIds does not contain 'crm.pipeline'
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('crm.pipeline', ['crm'])], groups: [] },
-      { features: [makeFeature('crm', [] /* surfaceIds omits 'crm.pipeline' */)] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('does not include surface'))).toBe(true)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Group 2: Duplicate ID detection
-// ---------------------------------------------------------------------------
-
-describe('duplicate ID detection', () => {
-  it('throws on duplicate feature IDs', () => {
-    const model = makeMinimalModel({ surfaces: [], groups: [] }, { features: [makeFeature('crm'), makeFeature('crm')] })
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('Feature id "crm" must be unique'))).toBe(true)
-  })
-
-  it('throws on duplicate surface IDs', () => {
-    const model = makeMinimalModel({
-      surfaces: [makeSurface('home'), makeSurface('home')],
-      groups: []
-    })
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('Surface id "home" must be unique'))).toBe(true)
-  })
-
-  it('throws on duplicate navigation group IDs', () => {
-    const model = makeMinimalModel({
-      surfaces: [],
-      groups: [makeGroup('primary'), makeGroup('primary')]
-    })
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('Navigation group id "primary" must be unique'))).toBe(true)
-  })
-
-  it('throws on duplicate resource mapping IDs', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      { resourceMappings: [makeResourceMapping('rm-1', 'res-a'), makeResourceMapping('rm-1', 'res-b')] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('Resource mapping id "rm-1" must be unique'))).toBe(true)
-  })
-
-  it('throws on duplicate resource mapping resourceIds', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      {
-        resourceMappings: [
-          makeResourceMapping('rm-1', 'shared-resource'),
-          makeResourceMapping('rm-2', 'shared-resource')
-        ]
-      }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('resourceId "shared-resource" must be unique'))).toBe(true)
-  })
-
-  it('passes when all IDs are unique across all collections', () => {
-    const model = makeMinimalModel(
-      {
-        surfaces: [makeSurface('surf-1'), makeSurface('surf-2')],
-        groups: [makeGroup('grp-1'), makeGroup('grp-2')]
-      },
-      {
-        features: [makeFeature('feat-a'), makeFeature('feat-b')],
-        resourceMappings: [makeResourceMapping('rm-1', 'res-x'), makeResourceMapping('rm-2', 'res-y')]
-      }
-    )
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Group 3: defaultSurfaceId correctness
-// ---------------------------------------------------------------------------
-
-describe('defaultSurfaceId correctness', () => {
-  it('passes when defaultSurfaceId points at a declared surface', () => {
-    const model = makeMinimalModel(
-      {
-        defaultSurfaceId: 'crm.pipeline',
-        surfaces: [makeSurface('crm.pipeline', ['crm'])],
-        groups: []
-      },
-      { features: [makeFeature('crm', ['crm.pipeline'])] }
-    )
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-
-  it('throws when defaultSurfaceId references a surface that does not exist', () => {
-    const model = makeMinimalModel({
-      defaultSurfaceId: 'nonexistent',
-      surfaces: [],
-      groups: []
-    })
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('must reference a declared navigation surface'))).toBe(true)
-  })
-
-  it('passes when defaultSurfaceId is absent (undefined)', () => {
-    // NOTE: The falsy guard in schema.ts (line 69) skips the check entirely when
-    // defaultSurfaceId is undefined. This is current behavior — documented here.
-    const model = makeMinimalModel({ surfaces: [], groups: [] })
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Group 4: Resource-mapping feature <-> surface cross-refs
-// ---------------------------------------------------------------------------
-
-describe('resource-mapping feature <-> surface cross-refs', () => {
-  it('passes with a fully consistent resource mapping', () => {
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('crm.pipeline', ['crm'], ['workflow-a'])], groups: [] },
-      {
-        features: [makeFeature('crm', ['crm.pipeline'], ['workflow-a'])],
-        resourceMappings: [makeResourceMapping('rm-1', 'workflow-a', ['crm'], ['crm.pipeline'])]
-      }
-    )
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-
-  it('throws when resource mapping references a feature that does not exist', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      { resourceMappings: [makeResourceMapping('rm-1', 'res-a', ['nonexistent-feature'])] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('references unknown feature'))).toBe(true)
-  })
-
-  it('throws when resource mapping references a surface that does not exist', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      { resourceMappings: [makeResourceMapping('rm-1', 'res-a', [], ['nonexistent-surface'])] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('references unknown surface'))).toBe(true)
-  })
-
-  it('throws when feature resourceId ref exists but mapping does not back-reference the feature', () => {
-    // Resource mapping exists for 'workflow-a', feature lists it, but mapping.featureIds is empty
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      {
-        features: [makeFeature('crm', [], ['workflow-a'])],
-        resourceMappings: [makeResourceMapping('rm-1', 'workflow-a', [] /* missing 'crm' */)]
-      }
-    )
-
-    const messages = getIssueMessages(model)
-    // Feature side: "does not include resource"; ResourceMapping side: the feature is missing
-    expect(
-      messages.some((m) => m.includes('does not include resource') || m.includes('does not include feature'))
-    ).toBe(true)
-  })
-
-  it('throws when surface resourceId ref exists but mapping does not back-reference the surface', () => {
-    // Resource mapping exists for 'workflow-b', surface lists it, but mapping.surfaceIds is empty
-    const model = makeMinimalModel(
-      { surfaces: [makeSurface('home', [], ['workflow-b'])], groups: [] },
-      { resourceMappings: [makeResourceMapping('rm-2', 'workflow-b', [], [] /* missing 'home' */)] }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(
-      messages.some((m) => m.includes('does not include resource') || m.includes('does not include surface'))
-    ).toBe(true)
-  })
-
-  it('throws when feature references a resourceId that has no matching resource mapping', () => {
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      {
-        features: [makeFeature('crm', [], ['unknown-resource'])],
-        resourceMappings: []
-      }
-    )
-
-    const messages = getIssueMessages(model)
-    expect(messages.some((m) => m.includes('references unknown resource'))).toBe(true)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Group 5: Null / undefined behavior in ref fields
-// ---------------------------------------------------------------------------
-
-describe('null/undefined behavior in ref fields', () => {
-  it('treats missing surfaceIds as empty array via Zod default — no superRefine errors', () => {
-    // ReferenceIdsSchema defaults to []; omitting surfaceIds is safe — nothing to iterate
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      {
-        features: [
-          {
-            id: 'crm',
-            label: 'CRM',
-            enabled: true,
-            entityIds: [],
-            // surfaceIds intentionally omitted — Zod fills in []
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ]
-      }
-    )
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-
-  it('treats missing featureIds on a surface as empty array — no superRefine errors', () => {
-    const model = makeMinimalModel({
-      surfaces: [
-        {
-          id: 'home',
-          label: 'Home',
-          path: '/home',
-          surfaceType: 'page' as const,
-          // featureIds intentionally omitted — Zod fills in []
-          entityIds: [],
-          resourceIds: [],
-          capabilityIds: []
-        }
-      ],
-      groups: []
-    })
-
-    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
-  })
-
-  it('rejects explicit null for surfaceIds — Zod type error before superRefine runs', () => {
-    // null is not assignable to an array; the base schema rejects it before superRefine executes
-    const model = makeMinimalModel(
-      { surfaces: [], groups: [] },
-      {
-        features: [
-          {
-            id: 'crm',
-            label: 'CRM',
-            enabled: true,
-            entityIds: [],
-            surfaceIds: null,
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ]
-      }
-    )
-
-    const result = OrganizationModelSchema.safeParse(model)
-    expect(result.success).toBe(false)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_ORGANIZATION_MODEL_BRANDING } from '../domains/branding'
+import { DEFAULT_ORGANIZATION_MODEL_SALES } from '../domains/sales'
+import { DEFAULT_ORGANIZATION_MODEL_PROJECTS } from '../domains/projects'
+import { DEFAULT_ORGANIZATION_MODEL_PROSPECTING } from '../domains/prospecting'
+import { OrganizationModelSchema } from '../schema'
+
+// ---------------------------------------------------------------------------
+// Minimal valid fixture builders
+// ---------------------------------------------------------------------------
+
+function makeFeature(id: string, surfaceIds: string[] = [], resourceIds: string[] = []) {
+  return {
+    id,
+    label: id,
+    enabled: true,
+    entityIds: [],
+    surfaceIds,
+    resourceIds,
+    capabilityIds: []
+  }
+}
+
+function makeSurface(id: string, featureIds: string[] = [], resourceIds: string[] = []) {
+  return {
+    id,
+    label: id,
+    path: `/${id}`,
+    surfaceType: 'page' as const,
+    featureIds,
+    entityIds: [],
+    resourceIds,
+    capabilityIds: []
+  }
+}
+
+function makeGroup(id: string, surfaceIds: string[] = []) {
+  return { id, label: id, placement: 'primary' as const, surfaceIds }
+}
+
+function makeResourceMapping(id: string, resourceId: string, featureIds: string[] = [], surfaceIds: string[] = []) {
+  return {
+    id,
+    label: id,
+    resourceId,
+    resourceType: 'workflow' as const,
+    featureIds,
+    entityIds: [],
+    surfaceIds,
+    capabilityIds: []
+  }
+}
+
+/**
+ * A minimal model that satisfies all base-schema field requirements.
+ * The crm/leadGen/delivery fields use the official defaults so the schema
+ * layer validates cleanly, leaving superRefine as the only concern.
+ */
+function makeMinimalModel(
+  navOverride: { defaultSurfaceId?: string; surfaces?: unknown[]; groups?: unknown[] } = {},
+  extras: { features?: unknown[]; resourceMappings?: unknown[] } = {}
+) {
+  return {
+    version: 1 as const,
+    features: extras.features ?? [],
+    branding: DEFAULT_ORGANIZATION_MODEL_BRANDING,
+    navigation: {
+      defaultSurfaceId: navOverride.defaultSurfaceId,
+      surfaces: navOverride.surfaces ?? [],
+      groups: navOverride.groups ?? []
+    },
+    sales: DEFAULT_ORGANIZATION_MODEL_SALES,
+    prospecting: DEFAULT_ORGANIZATION_MODEL_PROSPECTING,
+    projects: DEFAULT_ORGANIZATION_MODEL_PROJECTS,
+    resourceMappings: extras.resourceMappings ?? []
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: collect all Zod issue messages from a failed parse
+// ---------------------------------------------------------------------------
+
+function getIssueMessages(data: unknown): string[] {
+  const result = OrganizationModelSchema.safeParse(data)
+  if (result.success) return []
+  return result.error.issues.map((i) => i.message)
+}
+
+// ---------------------------------------------------------------------------
+// Group 1: Bidirectional feature <-> surface refs
+// ---------------------------------------------------------------------------
+
+describe('bidirectional feature <-> surface refs', () => {
+  it('passes when feature and surface correctly reference each other', () => {
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('crm.pipeline', ['crm'])], groups: [] },
+      { features: [makeFeature('crm', ['crm.pipeline'])] }
+    )
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+
+  it('throws when feature references a surface that does not exist', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      { features: [makeFeature('crm', ['nonexistent-surface'])] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('references unknown surface'))).toBe(true)
+  })
+
+  it('throws when feature references a surface that does not include the feature', () => {
+    // Surface exists but its featureIds does not contain 'crm'
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('crm.pipeline', [] /* featureIds omits 'crm' */)], groups: [] },
+      { features: [makeFeature('crm', ['crm.pipeline'])] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('does not include feature'))).toBe(true)
+  })
+
+  it('throws when surface references a feature that does not exist', () => {
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('crm.pipeline', ['nonexistent-feature'])], groups: [] },
+      { features: [] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('references unknown feature'))).toBe(true)
+  })
+
+  it('throws when surface references a feature that does not include the surface', () => {
+    // Feature exists but its surfaceIds does not contain 'crm.pipeline'
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('crm.pipeline', ['crm'])], groups: [] },
+      { features: [makeFeature('crm', [] /* surfaceIds omits 'crm.pipeline' */)] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('does not include surface'))).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Group 2: Duplicate ID detection
+// ---------------------------------------------------------------------------
+
+describe('duplicate ID detection', () => {
+  it('throws on duplicate feature IDs', () => {
+    const model = makeMinimalModel({ surfaces: [], groups: [] }, { features: [makeFeature('crm'), makeFeature('crm')] })
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('Feature id "crm" must be unique'))).toBe(true)
+  })
+
+  it('throws on duplicate surface IDs', () => {
+    const model = makeMinimalModel({
+      surfaces: [makeSurface('home'), makeSurface('home')],
+      groups: []
+    })
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('Surface id "home" must be unique'))).toBe(true)
+  })
+
+  it('throws on duplicate navigation group IDs', () => {
+    const model = makeMinimalModel({
+      surfaces: [],
+      groups: [makeGroup('primary'), makeGroup('primary')]
+    })
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('Navigation group id "primary" must be unique'))).toBe(true)
+  })
+
+  it('throws on duplicate resource mapping IDs', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      { resourceMappings: [makeResourceMapping('rm-1', 'res-a'), makeResourceMapping('rm-1', 'res-b')] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('Resource mapping id "rm-1" must be unique'))).toBe(true)
+  })
+
+  it('throws on duplicate resource mapping resourceIds', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      {
+        resourceMappings: [
+          makeResourceMapping('rm-1', 'shared-resource'),
+          makeResourceMapping('rm-2', 'shared-resource')
+        ]
+      }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('resourceId "shared-resource" must be unique'))).toBe(true)
+  })
+
+  it('passes when all IDs are unique across all collections', () => {
+    const model = makeMinimalModel(
+      {
+        surfaces: [makeSurface('surf-1'), makeSurface('surf-2')],
+        groups: [makeGroup('grp-1'), makeGroup('grp-2')]
+      },
+      {
+        features: [makeFeature('feat-a'), makeFeature('feat-b')],
+        resourceMappings: [makeResourceMapping('rm-1', 'res-x'), makeResourceMapping('rm-2', 'res-y')]
+      }
+    )
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Group 3: defaultSurfaceId correctness
+// ---------------------------------------------------------------------------
+
+describe('defaultSurfaceId correctness', () => {
+  it('passes when defaultSurfaceId points at a declared surface', () => {
+    const model = makeMinimalModel(
+      {
+        defaultSurfaceId: 'crm.pipeline',
+        surfaces: [makeSurface('crm.pipeline', ['crm'])],
+        groups: []
+      },
+      { features: [makeFeature('crm', ['crm.pipeline'])] }
+    )
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+
+  it('throws when defaultSurfaceId references a surface that does not exist', () => {
+    const model = makeMinimalModel({
+      defaultSurfaceId: 'nonexistent',
+      surfaces: [],
+      groups: []
+    })
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('must reference a declared navigation surface'))).toBe(true)
+  })
+
+  it('passes when defaultSurfaceId is absent (undefined)', () => {
+    // NOTE: The falsy guard in schema.ts (line 69) skips the check entirely when
+    // defaultSurfaceId is undefined. This is current behavior — documented here.
+    const model = makeMinimalModel({ surfaces: [], groups: [] })
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Group 4: Resource-mapping feature <-> surface cross-refs
+// ---------------------------------------------------------------------------
+
+describe('resource-mapping feature <-> surface cross-refs', () => {
+  it('passes with a fully consistent resource mapping', () => {
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('crm.pipeline', ['crm'], ['workflow-a'])], groups: [] },
+      {
+        features: [makeFeature('crm', ['crm.pipeline'], ['workflow-a'])],
+        resourceMappings: [makeResourceMapping('rm-1', 'workflow-a', ['crm'], ['crm.pipeline'])]
+      }
+    )
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+
+  it('throws when resource mapping references a feature that does not exist', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      { resourceMappings: [makeResourceMapping('rm-1', 'res-a', ['nonexistent-feature'])] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('references unknown feature'))).toBe(true)
+  })
+
+  it('throws when resource mapping references a surface that does not exist', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      { resourceMappings: [makeResourceMapping('rm-1', 'res-a', [], ['nonexistent-surface'])] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('references unknown surface'))).toBe(true)
+  })
+
+  it('throws when feature resourceId ref exists but mapping does not back-reference the feature', () => {
+    // Resource mapping exists for 'workflow-a', feature lists it, but mapping.featureIds is empty
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      {
+        features: [makeFeature('crm', [], ['workflow-a'])],
+        resourceMappings: [makeResourceMapping('rm-1', 'workflow-a', [] /* missing 'crm' */)]
+      }
+    )
+
+    const messages = getIssueMessages(model)
+    // Feature side: "does not include resource"; ResourceMapping side: the feature is missing
+    expect(
+      messages.some((m) => m.includes('does not include resource') || m.includes('does not include feature'))
+    ).toBe(true)
+  })
+
+  it('throws when surface resourceId ref exists but mapping does not back-reference the surface', () => {
+    // Resource mapping exists for 'workflow-b', surface lists it, but mapping.surfaceIds is empty
+    const model = makeMinimalModel(
+      { surfaces: [makeSurface('home', [], ['workflow-b'])], groups: [] },
+      { resourceMappings: [makeResourceMapping('rm-2', 'workflow-b', [], [] /* missing 'home' */)] }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(
+      messages.some((m) => m.includes('does not include resource') || m.includes('does not include surface'))
+    ).toBe(true)
+  })
+
+  it('throws when feature references a resourceId that has no matching resource mapping', () => {
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      {
+        features: [makeFeature('crm', [], ['unknown-resource'])],
+        resourceMappings: []
+      }
+    )
+
+    const messages = getIssueMessages(model)
+    expect(messages.some((m) => m.includes('references unknown resource'))).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Group 5: Null / undefined behavior in ref fields
+// ---------------------------------------------------------------------------
+
+describe('null/undefined behavior in ref fields', () => {
+  it('treats missing surfaceIds as empty array via Zod default — no superRefine errors', () => {
+    // ReferenceIdsSchema defaults to []; omitting surfaceIds is safe — nothing to iterate
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      {
+        features: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            enabled: true,
+            entityIds: [],
+            // surfaceIds intentionally omitted — Zod fills in []
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ]
+      }
+    )
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+
+  it('treats missing featureIds on a surface as empty array — no superRefine errors', () => {
+    const model = makeMinimalModel({
+      surfaces: [
+        {
+          id: 'home',
+          label: 'Home',
+          path: '/home',
+          surfaceType: 'page' as const,
+          // featureIds intentionally omitted — Zod fills in []
+          entityIds: [],
+          resourceIds: [],
+          capabilityIds: []
+        }
+      ],
+      groups: []
+    })
+
+    expect(() => OrganizationModelSchema.parse(model)).not.toThrow()
+  })
+
+  it('rejects explicit null for surfaceIds — Zod type error before superRefine runs', () => {
+    // null is not assignable to an array; the base schema rejects it before superRefine executes
+    const model = makeMinimalModel(
+      { surfaces: [], groups: [] },
+      {
+        features: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            enabled: true,
+            entityIds: [],
+            surfaceIds: null,
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ]
+      }
+    )
+
+    const result = OrganizationModelSchema.safeParse(model)
+    expect(result.success).toBe(false)
+  })
+})