@elevasis/core 0.7.0 → 0.8.0

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

@@ -1,690 +1,690 @@
-import { describe, expect, it } from 'vitest'
-import { OrganizationModelSchema } from '../schema'
-import { defineOrganizationModel, resolveOrganizationModel } from '../resolve'
-
-describe('organization-model', () => {
-  it('resolves defaults for a minimal override', () => {
-    const model = resolveOrganizationModel(
-      defineOrganizationModel({
-        branding: {
-          organizationName: 'Acme',
-          productName: 'Acme OS',
-          shortName: 'Acme'
-        }
-      })
-    )
-
-    expect(model.version).toBe(1)
-    expect(model.branding.organizationName).toBe('Acme')
-    expect(model.sales.pipelines[0]?.stages).toHaveLength(6)
-    expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
-
-    const operationsFeature = model.features.find((f) => f.id === 'operations')
-    expect(operationsFeature?.enabled).toBe(true)
-  })
-
-  it('replaces arrays when a downstream override supplies a full slice', () => {
-    const model = resolveOrganizationModel({
-      features: [
-        {
-          id: 'crm',
-          label: 'CRM',
-          description: 'Custom CRM workspace',
-          enabled: true,
-          color: 'blue',
-          entityIds: [],
-          surfaceIds: ['custom.home'],
-          resourceIds: [],
-          capabilityIds: []
-        }
-      ],
-      navigation: {
-        defaultSurfaceId: 'custom.home',
-        surfaces: [
-          {
-            id: 'custom.home',
-            label: 'Home',
-            path: '/home',
-            surfaceType: 'page',
-            featureIds: ['crm'],
-            entityIds: [],
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ],
-        groups: [{ id: 'primary', label: 'Primary', placement: 'primary', surfaceIds: ['custom.home'] }]
-      }
-    })
-
-    expect(model.navigation.defaultSurfaceId).toBe('custom.home')
-    expect(model.navigation.surfaces).toHaveLength(1)
-    expect(model.navigation.surfaces[0]?.path).toBe('/home')
-  })
-
-  describe('deepMerge semantics', () => {
-    it('returns defaults when no override is provided', () => {
-      const model = resolveOrganizationModel(undefined)
-
-      expect(model.version).toBe(1)
-      expect(model.branding.organizationName).toBe('Default Organization')
-      expect(model.branding.productName).toBe('Elevasis')
-      expect(model.branding.shortName).toBe('Elevasis')
-      expect(model.features).toHaveLength(8)
-      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
-      expect(model.navigation.surfaces).toHaveLength(24)
-      expect(model.navigation.groups).toHaveLength(4)
-    })
-
-    it('preserves sibling fields when overriding a nested property', () => {
-      const model = resolveOrganizationModel({
-        branding: {
-          organizationName: 'OverriddenOrg'
-        }
-      })
-
-      expect(model.branding.organizationName).toBe('OverriddenOrg')
-      expect(model.branding.productName).toBe('Elevasis')
-      expect(model.branding.shortName).toBe('Elevasis')
-    })
-
-    it('replaces arrays entirely rather than merging', () => {
-      const model = resolveOrganizationModel({
-        features: [
-          {
-            id: 'crm',
-            label: 'CRM',
-            description: 'CRM only',
-            enabled: true,
-            color: 'blue',
-            entityIds: [],
-            surfaceIds: [],
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ],
-        navigation: {
-          defaultSurfaceId: 'home',
-          surfaces: [
-            {
-              id: 'home',
-              label: 'Home',
-              path: '/home',
-              surfaceType: 'page',
-              featureIds: [],
-              entityIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          groups: []
-        }
-      })
-
-      expect(model.features).toHaveLength(1)
-      expect(model.features[0]?.id).toBe('crm')
-    })
-
-    it('ignores undefined values in the override', () => {
-      const model = resolveOrganizationModel({
-        branding: {
-          organizationName: 'Test',
-          productName: undefined
-        }
-      })
-
-      expect(model.branding.organizationName).toBe('Test')
-      expect(model.branding.productName).toBe('Elevasis')
-    })
-  })
-
-  describe('navigation group normalization', () => {
-    const singleSurfaceOverride = {
-      features: [
-        {
-          id: 'crm',
-          label: 'CRM',
-          description: 'CRM workspace',
-          enabled: true,
-          color: 'blue',
-          entityIds: [],
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: [],
-          capabilityIds: []
-        }
-      ],
-      navigation: {
-        defaultSurfaceId: 'crm.pipeline',
-        surfaces: [
-          {
-            id: 'crm.pipeline',
-            label: 'Pipeline',
-            path: '/crm/pipeline',
-            surfaceType: 'graph' as const,
-            featureIds: ['crm'],
-            entityIds: [],
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ]
-        // groups intentionally omitted -- normalization must filter inherited groups
-      }
-    }
-
-    it('filters inherited groups to match overridden surfaces', () => {
-      const model = resolveOrganizationModel(singleSurfaceOverride)
-
-      expect(model.navigation.surfaces).toHaveLength(1)
-      expect(model.navigation.surfaces[0]?.id).toBe('crm.pipeline')
-
-      // Only the workspace group survives (it has crm.pipeline); operations group is gone
-      expect(model.navigation.groups).toHaveLength(1)
-      expect(model.navigation.groups[0]?.id).toBe('primary-workspace')
-      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
-    })
-
-    it('removes groups with no valid surface references', () => {
-      const model = resolveOrganizationModel(singleSurfaceOverride)
-
-      // The operations group references surfaces not present in the override -- it must be removed
-      const operationsGroup = model.navigation.groups.find((g) => g.id === 'primary-operations')
-      expect(operationsGroup).toBeUndefined()
-    })
-
-    it('skips normalization when groups are explicitly overridden', () => {
-      const model = resolveOrganizationModel({
-        features: [
-          {
-            id: 'crm',
-            label: 'CRM',
-            description: 'CRM workspace',
-            enabled: true,
-            color: 'blue',
-            entityIds: [],
-            surfaceIds: ['crm.pipeline'],
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ],
-        navigation: {
-          defaultSurfaceId: 'crm.pipeline',
-          surfaces: [
-            {
-              id: 'crm.pipeline',
-              label: 'Pipeline',
-              path: '/crm/pipeline',
-              surfaceType: 'graph',
-              featureIds: ['crm'],
-              entityIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          groups: [
-            {
-              id: 'custom-group',
-              label: 'Custom',
-              placement: 'primary',
-              surfaceIds: ['crm.pipeline']
-            }
-          ]
-        }
-      })
-
-      expect(model.navigation.groups).toHaveLength(1)
-      expect(model.navigation.groups[0]?.id).toBe('custom-group')
-      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
-    })
-  })
-
-  describe('defineOrganizationModel', () => {
-    it('returns the input unchanged', () => {
-      const input = { branding: { organizationName: 'Test', productName: 'TestOS', shortName: 'T' } }
-      const output = defineOrganizationModel(input)
-
-      expect(output).toBe(input)
-    })
-  })
-
-  describe('deepMerge edge cases', () => {
-    it('overrides a numeric primitive field in a nested object', () => {
-      // version is a numeric literal; overriding branding fields (numeric-adjacent: color codes etc.)
-      // Use crm pipeline stage count as a numeric primitive proxy
-      const model = resolveOrganizationModel({
-        branding: {
-          organizationName: 'NumericTest'
-        }
-      })
-
-      // The resolved model should have the overridden string value; confirms primitive override path
-      expect(model.branding.organizationName).toBe('NumericTest')
-      // Sibling string fields are preserved from defaults
-      expect(typeof model.branding.productName).toBe('string')
-      expect(model.branding.productName.length).toBeGreaterThan(0)
-    })
-
-    it('replaces a top-level array with an empty array', () => {
-      // resourceMappings defaults to [] in the DEFAULT_ORGANIZATION_MODEL. We seed one entry,
-      // confirm it lands, then override with [] and confirm replacement (not append).
-      // Using resourceMappings avoids navigation cross-ref complexity.
-      const withMappings = resolveOrganizationModel({
-        resourceMappings: [
-          {
-            id: 'rm-1',
-            label: 'Test Resource',
-            resourceId: 'res-1',
-            resourceType: 'workflow',
-            featureIds: [],
-            entityIds: [],
-            surfaceIds: [],
-            capabilityIds: []
-          }
-        ]
-      })
-      expect(withMappings.resourceMappings).toHaveLength(1)
-
-      // Now override with empty — confirms replacement semantics, not append
-      const withEmpty = resolveOrganizationModel({
-        resourceMappings: []
-      })
-      expect(withEmpty.resourceMappings).toHaveLength(0)
-    })
-
-    it('replaces a deeply-nested array with a shorter array (not appended)', () => {
-      // Confirms array merge does NOT happen — the override is used verbatim.
-      // We provide a complete consistent model (features + navigation) so superRefine passes,
-      // isolating the assertion to "array length = override length, not override + default length".
-      const model = resolveOrganizationModel({
-        features: [
-          {
-            id: 'crm',
-            label: 'CRM',
-            description: 'CRM only',
-            enabled: true,
-            color: 'blue',
-            entityIds: [],
-            surfaceIds: ['crm.pipeline'],
-            resourceIds: [],
-            capabilityIds: []
-          },
-          {
-            id: 'lead-gen',
-            label: 'Lead Gen',
-            description: 'Lead gen only',
-            enabled: false,
-            color: 'cyan',
-            entityIds: [],
-            surfaceIds: ['lead-gen.lists'],
-            resourceIds: [],
-            capabilityIds: []
-          }
-        ],
-        navigation: {
-          defaultSurfaceId: 'crm.pipeline',
-          surfaces: [
-            {
-              id: 'crm.pipeline',
-              label: 'Pipeline',
-              path: '/crm/pipeline',
-              surfaceType: 'graph',
-              featureIds: ['crm'],
-              entityIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            },
-            {
-              id: 'lead-gen.lists',
-              label: 'Lists',
-              path: '/lead-gen/lists',
-              surfaceType: 'page',
-              featureIds: ['lead-gen'],
-              entityIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          groups: []
-        }
-      })
-
-      // deepMerge replaces, not appends: exactly 2 features (not 2 + 8 defaults)
-      expect(model.features).toHaveLength(2)
-      expect(model.features[0]?.id).toBe('crm')
-      expect(model.features[1]?.id).toBe('lead-gen')
-    })
-
-    it('deeply-nested undefined fields in override are skipped (multi-level)', () => {
-      // Three levels deep: branding -> a field set to undefined inside a nested call
-      // The path here is: override.branding.organizationName = 'Keep', productName = undefined
-      // Result: productName comes from defaults, not undefined
-      const model = resolveOrganizationModel({
-        branding: {
-          organizationName: 'Keep',
-          productName: undefined,
-          shortName: undefined
-        }
-      })
-
-      expect(model.branding.organizationName).toBe('Keep')
-      // undefined-valued keys are skipped; defaults remain
-      expect(model.branding.productName).toBe('Elevasis')
-      expect(model.branding.shortName).toBe('Elevasis')
-    })
-
-    it('null override in a nested object field overwrites the default', () => {
-      // null is NOT skipped by deepMerge (only undefined is). A null value for an object field
-      // replaces the default with null. This test documents current behavior.
-      // NOTE: This behavior reveals a potential gap — if a caller accidentally passes null for a
-      // required nested object, deepMerge will assign null and OrganizationModelSchema.parse() will
-      // catch it. The parse acts as the safety net here, not deepMerge itself.
-      //
-      // TODO: The deepMerge function does not guard against null overrides. If a caller passes
-      // null for a required sub-object (e.g. branding: null), the parse throws a schema error
-      // instead of a clear "null override rejected" message. Consider adding an explicit null-guard
-      // in deepMerge to produce a better developer error surface — tracked in vibe-layer decision #22.
-      expect(() =>
-        resolveOrganizationModel({
-          // @ts-expect-error: intentionally passing null to test runtime behavior
-          branding: null
-        })
-      ).toThrow()
-    })
-
-    it('string primitive override replaces default at nested leaf', () => {
-      // Covers the non-plain-object branch in deepMerge when both base and override are strings
-      const model = resolveOrganizationModel({
-        navigation: {
-          defaultSurfaceId: 'crm.pipeline'
-        }
-      })
-
-      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
-      // Sibling object field is preserved from defaults
-      expect(model.navigation.surfaces.length).toBeGreaterThan(0)
-      expect(model.navigation.groups.length).toBeGreaterThan(0)
-    })
-
-    it('deeply nested object merges without clobbering peer keys', () => {
-      // Three-level merge: override a leaf inside navigation without touching other navigation fields.
-      // navigation.defaultSurfaceId is overridden; navigation.surfaces and groups come from defaults.
-      const model = resolveOrganizationModel({
-        navigation: {
-          defaultSurfaceId: 'crm.pipeline'
-        }
-      })
-
-      // Only the leaf was overridden; peer arrays are inherited from defaults (non-empty)
-      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
-      // Peer arrays come from defaults — we check they are non-empty without pinning to a count
-      // that would break every time defaults.ts adds a new surface or group.
-      expect(model.navigation.surfaces.length).toBeGreaterThan(0)
-      expect(model.navigation.groups.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe('merged-result schema validation (80/20 gap — decision #22)', () => {
-    // These cases demonstrate that deepMerge() can produce a type-compatible merged result that
-    // OrganizationModelSchema.parse() correctly rejects via superRefine(). The gap cited in
-    // vibe-layer decision #22 is that callers who skip parse() (e.g. use the merged object directly)
-    // will silently carry invalid cross-references. The parse call inside resolveOrganizationModel
-    // is the required gate — skipping it is the 80/20 risk.
-
-    it('rejects a model where defaultSurfaceId does not match any declared surface', () => {
-      // Override navigation to replace all surfaces with one surface, but keep defaultSurfaceId
-      // pointing at a different (non-existent) surface.
-      // deepMerge produces a structurally valid object; superRefine catches the dangling ref.
-      expect(() =>
-        resolveOrganizationModel({
-          navigation: {
-            defaultSurfaceId: 'does-not-exist',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: [],
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: []
-          },
-          features: []
-        })
-      ).toThrow()
-    })
-
-    it('rejects a model where a feature references a surface that does not back-reference it', () => {
-      // Feature says it owns surface 'crm.pipeline'; surface does NOT list the feature in featureIds.
-      // Both sides are plain strings — TypeScript cannot catch this. superRefine must.
-      expect(() =>
-        resolveOrganizationModel({
-          features: [
-            {
-              id: 'crm',
-              label: 'CRM',
-              description: 'CRM',
-              enabled: true,
-              color: 'blue',
-              entityIds: [],
-              surfaceIds: ['crm.pipeline'], // claims this surface
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          navigation: {
-            defaultSurfaceId: 'crm.pipeline',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: [], // does NOT back-reference 'crm'
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: []
-          }
-        })
-      ).toThrow()
-    })
-
-    it('rejects a model where a surface references a feature that does not back-reference it', () => {
-      // Mirror of the previous case: surface claims a feature; feature does not list the surface.
-      expect(() =>
-        resolveOrganizationModel({
-          features: [
-            {
-              id: 'crm',
-              label: 'CRM',
-              description: 'CRM',
-              enabled: true,
-              color: 'blue',
-              entityIds: [],
-              surfaceIds: [], // does NOT list 'crm.pipeline'
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          navigation: {
-            defaultSurfaceId: 'crm.pipeline',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: ['crm'], // claims feature 'crm'
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: []
-          }
-        })
-      ).toThrow()
-    })
-
-    it('rejects a model with duplicate feature ids', () => {
-      // Two features with the same id — structurally valid JavaScript, superRefine detects the collision
-      expect(() =>
-        resolveOrganizationModel({
-          features: [
-            {
-              id: 'crm',
-              label: 'CRM A',
-              description: 'First',
-              enabled: true,
-              color: 'blue',
-              entityIds: [],
-              surfaceIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            },
-            {
-              id: 'crm', // duplicate
-              label: 'CRM B',
-              description: 'Second',
-              enabled: false,
-              color: 'red',
-              entityIds: [],
-              surfaceIds: [],
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          navigation: {
-            defaultSurfaceId: 'crm.pipeline',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: [],
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: []
-          }
-        })
-      ).toThrow()
-    })
-
-    it('rejects a model with duplicate navigation surface ids', () => {
-      // Two surfaces sharing an id — TypeScript sees string[], superRefine enforces uniqueness
-      expect(() =>
-        resolveOrganizationModel({
-          features: [],
-          navigation: {
-            defaultSurfaceId: 'crm.pipeline',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline A',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: [],
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              },
-              {
-                id: 'crm.pipeline', // duplicate
-                label: 'Pipeline B',
-                path: '/crm/pipeline-2',
-                surfaceType: 'page',
-                featureIds: [],
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: []
-          }
-        })
-      ).toThrow()
-    })
-
-    it('accepts a fully consistent minimal model with bidirectional refs', () => {
-      // Positive control: a hand-constructed model that satisfies all superRefine cross-ref rules
-      // should NOT throw — proving the rejection cases above are schema-specific, not noise
-      expect(() =>
-        resolveOrganizationModel({
-          features: [
-            {
-              id: 'crm',
-              label: 'CRM',
-              description: 'CRM',
-              enabled: true,
-              color: 'blue',
-              entityIds: [],
-              surfaceIds: ['crm.pipeline'],
-              resourceIds: [],
-              capabilityIds: []
-            }
-          ],
-          navigation: {
-            defaultSurfaceId: 'crm.pipeline',
-            surfaces: [
-              {
-                id: 'crm.pipeline',
-                label: 'Pipeline',
-                path: '/crm/pipeline',
-                surfaceType: 'graph',
-                featureIds: ['crm'], // back-references 'crm'
-                entityIds: [],
-                resourceIds: [],
-                capabilityIds: []
-              }
-            ],
-            groups: [
-              {
-                id: 'primary',
-                label: 'Primary',
-                placement: 'primary',
-                surfaceIds: ['crm.pipeline']
-              }
-            ]
-          }
-        })
-      ).not.toThrow()
-    })
-
-    it('OrganizationModelSchema.parse rejects the same invalid model that resolveOrganizationModel rejects', () => {
-      // Confirms the gap: if a caller uses deepMerge output WITHOUT calling parse,
-      // the dangling defaultSurfaceId ref would go undetected. parse() is the required gate.
-      // This test documents the behavior by verifying parse throws on the invalid merged object.
-      const invalidNavigation = {
-        defaultSurfaceId: 'ghost-surface',
-        surfaces: [],
-        groups: []
-      }
-
-      // Calling parse directly on a shape that has the right structure but broken refs
-      const rawInvalidModel = {
-        version: 1 as const,
-        features: [],
-        branding: {
-          organizationName: 'Test',
-          productName: 'Test',
-          shortName: 'T'
-        },
-        navigation: invalidNavigation,
-        crm: { pipelines: [] },
-        leadGen: { lists: [] },
-        delivery: { projects: [] },
-        resourceMappings: []
-      }
-
-      expect(() => OrganizationModelSchema.parse(rawInvalidModel)).toThrow()
-    })
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { OrganizationModelSchema } from '../schema'
+import { defineOrganizationModel, resolveOrganizationModel } from '../resolve'
+
+describe('organization-model', () => {
+  it('resolves defaults for a minimal override', () => {
+    const model = resolveOrganizationModel(
+      defineOrganizationModel({
+        branding: {
+          organizationName: 'Acme',
+          productName: 'Acme OS',
+          shortName: 'Acme'
+        }
+      })
+    )
+
+    expect(model.version).toBe(1)
+    expect(model.branding.organizationName).toBe('Acme')
+    expect(model.sales.pipelines[0]?.stages).toHaveLength(6)
+    expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
+
+    const operationsFeature = model.features.find((f) => f.id === 'operations')
+    expect(operationsFeature?.enabled).toBe(true)
+  })
+
+  it('replaces arrays when a downstream override supplies a full slice', () => {
+    const model = resolveOrganizationModel({
+      features: [
+        {
+          id: 'crm',
+          label: 'CRM',
+          description: 'Custom CRM workspace',
+          enabled: true,
+          color: 'blue',
+          entityIds: [],
+          surfaceIds: ['custom.home'],
+          resourceIds: [],
+          capabilityIds: []
+        }
+      ],
+      navigation: {
+        defaultSurfaceId: 'custom.home',
+        surfaces: [
+          {
+            id: 'custom.home',
+            label: 'Home',
+            path: '/home',
+            surfaceType: 'page',
+            featureIds: ['crm'],
+            entityIds: [],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        groups: [{ id: 'primary', label: 'Primary', placement: 'primary', surfaceIds: ['custom.home'] }]
+      }
+    })
+
+    expect(model.navigation.defaultSurfaceId).toBe('custom.home')
+    expect(model.navigation.surfaces).toHaveLength(1)
+    expect(model.navigation.surfaces[0]?.path).toBe('/home')
+  })
+
+  describe('deepMerge semantics', () => {
+    it('returns defaults when no override is provided', () => {
+      const model = resolveOrganizationModel(undefined)
+
+      expect(model.version).toBe(1)
+      expect(model.branding.organizationName).toBe('Default Organization')
+      expect(model.branding.productName).toBe('Elevasis')
+      expect(model.branding.shortName).toBe('Elevasis')
+      expect(model.features).toHaveLength(8)
+      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
+      expect(model.navigation.surfaces).toHaveLength(24)
+      expect(model.navigation.groups).toHaveLength(4)
+    })
+
+    it('preserves sibling fields when overriding a nested property', () => {
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'OverriddenOrg'
+        }
+      })
+
+      expect(model.branding.organizationName).toBe('OverriddenOrg')
+      expect(model.branding.productName).toBe('Elevasis')
+      expect(model.branding.shortName).toBe('Elevasis')
+    })
+
+    it('replaces arrays entirely rather than merging', () => {
+      const model = resolveOrganizationModel({
+        features: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            description: 'CRM only',
+            enabled: true,
+            color: 'blue',
+            entityIds: [],
+            surfaceIds: [],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        navigation: {
+          defaultSurfaceId: 'home',
+          surfaces: [
+            {
+              id: 'home',
+              label: 'Home',
+              path: '/home',
+              surfaceType: 'page',
+              featureIds: [],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          groups: []
+        }
+      })
+
+      expect(model.features).toHaveLength(1)
+      expect(model.features[0]?.id).toBe('crm')
+    })
+
+    it('ignores undefined values in the override', () => {
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'Test',
+          productName: undefined
+        }
+      })
+
+      expect(model.branding.organizationName).toBe('Test')
+      expect(model.branding.productName).toBe('Elevasis')
+    })
+  })
+
+  describe('navigation group normalization', () => {
+    const singleSurfaceOverride = {
+      features: [
+        {
+          id: 'crm',
+          label: 'CRM',
+          description: 'CRM workspace',
+          enabled: true,
+          color: 'blue',
+          entityIds: [],
+          surfaceIds: ['crm.pipeline'],
+          resourceIds: [],
+          capabilityIds: []
+        }
+      ],
+      navigation: {
+        defaultSurfaceId: 'crm.pipeline',
+        surfaces: [
+          {
+            id: 'crm.pipeline',
+            label: 'Pipeline',
+            path: '/crm/pipeline',
+            surfaceType: 'graph' as const,
+            featureIds: ['crm'],
+            entityIds: [],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ]
+        // groups intentionally omitted -- normalization must filter inherited groups
+      }
+    }
+
+    it('filters inherited groups to match overridden surfaces', () => {
+      const model = resolveOrganizationModel(singleSurfaceOverride)
+
+      expect(model.navigation.surfaces).toHaveLength(1)
+      expect(model.navigation.surfaces[0]?.id).toBe('crm.pipeline')
+
+      // Only the workspace group survives (it has crm.pipeline); operations group is gone
+      expect(model.navigation.groups).toHaveLength(1)
+      expect(model.navigation.groups[0]?.id).toBe('primary-workspace')
+      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
+    })
+
+    it('removes groups with no valid surface references', () => {
+      const model = resolveOrganizationModel(singleSurfaceOverride)
+
+      // The operations group references surfaces not present in the override -- it must be removed
+      const operationsGroup = model.navigation.groups.find((g) => g.id === 'primary-operations')
+      expect(operationsGroup).toBeUndefined()
+    })
+
+    it('skips normalization when groups are explicitly overridden', () => {
+      const model = resolveOrganizationModel({
+        features: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            description: 'CRM workspace',
+            enabled: true,
+            color: 'blue',
+            entityIds: [],
+            surfaceIds: ['crm.pipeline'],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        navigation: {
+          defaultSurfaceId: 'crm.pipeline',
+          surfaces: [
+            {
+              id: 'crm.pipeline',
+              label: 'Pipeline',
+              path: '/crm/pipeline',
+              surfaceType: 'graph',
+              featureIds: ['crm'],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          groups: [
+            {
+              id: 'custom-group',
+              label: 'Custom',
+              placement: 'primary',
+              surfaceIds: ['crm.pipeline']
+            }
+          ]
+        }
+      })
+
+      expect(model.navigation.groups).toHaveLength(1)
+      expect(model.navigation.groups[0]?.id).toBe('custom-group')
+      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
+    })
+  })
+
+  describe('defineOrganizationModel', () => {
+    it('returns the input unchanged', () => {
+      const input = { branding: { organizationName: 'Test', productName: 'TestOS', shortName: 'T' } }
+      const output = defineOrganizationModel(input)
+
+      expect(output).toBe(input)
+    })
+  })
+
+  describe('deepMerge edge cases', () => {
+    it('overrides a numeric primitive field in a nested object', () => {
+      // version is a numeric literal; overriding branding fields (numeric-adjacent: color codes etc.)
+      // Use crm pipeline stage count as a numeric primitive proxy
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'NumericTest'
+        }
+      })
+
+      // The resolved model should have the overridden string value; confirms primitive override path
+      expect(model.branding.organizationName).toBe('NumericTest')
+      // Sibling string fields are preserved from defaults
+      expect(typeof model.branding.productName).toBe('string')
+      expect(model.branding.productName.length).toBeGreaterThan(0)
+    })
+
+    it('replaces a top-level array with an empty array', () => {
+      // resourceMappings defaults to [] in the DEFAULT_ORGANIZATION_MODEL. We seed one entry,
+      // confirm it lands, then override with [] and confirm replacement (not append).
+      // Using resourceMappings avoids navigation cross-ref complexity.
+      const withMappings = resolveOrganizationModel({
+        resourceMappings: [
+          {
+            id: 'rm-1',
+            label: 'Test Resource',
+            resourceId: 'res-1',
+            resourceType: 'workflow',
+            featureIds: [],
+            entityIds: [],
+            surfaceIds: [],
+            capabilityIds: []
+          }
+        ]
+      })
+      expect(withMappings.resourceMappings).toHaveLength(1)
+
+      // Now override with empty — confirms replacement semantics, not append
+      const withEmpty = resolveOrganizationModel({
+        resourceMappings: []
+      })
+      expect(withEmpty.resourceMappings).toHaveLength(0)
+    })
+
+    it('replaces a deeply-nested array with a shorter array (not appended)', () => {
+      // Confirms array merge does NOT happen — the override is used verbatim.
+      // We provide a complete consistent model (features + navigation) so superRefine passes,
+      // isolating the assertion to "array length = override length, not override + default length".
+      const model = resolveOrganizationModel({
+        features: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            description: 'CRM only',
+            enabled: true,
+            color: 'blue',
+            entityIds: [],
+            surfaceIds: ['crm.pipeline'],
+            resourceIds: [],
+            capabilityIds: []
+          },
+          {
+            id: 'lead-gen',
+            label: 'Lead Gen',
+            description: 'Lead gen only',
+            enabled: false,
+            color: 'cyan',
+            entityIds: [],
+            surfaceIds: ['lead-gen.lists'],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        navigation: {
+          defaultSurfaceId: 'crm.pipeline',
+          surfaces: [
+            {
+              id: 'crm.pipeline',
+              label: 'Pipeline',
+              path: '/crm/pipeline',
+              surfaceType: 'graph',
+              featureIds: ['crm'],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            },
+            {
+              id: 'lead-gen.lists',
+              label: 'Lists',
+              path: '/lead-gen/lists',
+              surfaceType: 'page',
+              featureIds: ['lead-gen'],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          groups: []
+        }
+      })
+
+      // deepMerge replaces, not appends: exactly 2 features (not 2 + 8 defaults)
+      expect(model.features).toHaveLength(2)
+      expect(model.features[0]?.id).toBe('crm')
+      expect(model.features[1]?.id).toBe('lead-gen')
+    })
+
+    it('deeply-nested undefined fields in override are skipped (multi-level)', () => {
+      // Three levels deep: branding -> a field set to undefined inside a nested call
+      // The path here is: override.branding.organizationName = 'Keep', productName = undefined
+      // Result: productName comes from defaults, not undefined
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'Keep',
+          productName: undefined,
+          shortName: undefined
+        }
+      })
+
+      expect(model.branding.organizationName).toBe('Keep')
+      // undefined-valued keys are skipped; defaults remain
+      expect(model.branding.productName).toBe('Elevasis')
+      expect(model.branding.shortName).toBe('Elevasis')
+    })
+
+    it('null override in a nested object field overwrites the default', () => {
+      // null is NOT skipped by deepMerge (only undefined is). A null value for an object field
+      // replaces the default with null. This test documents current behavior.
+      // NOTE: This behavior reveals a potential gap — if a caller accidentally passes null for a
+      // required nested object, deepMerge will assign null and OrganizationModelSchema.parse() will
+      // catch it. The parse acts as the safety net here, not deepMerge itself.
+      //
+      // TODO: The deepMerge function does not guard against null overrides. If a caller passes
+      // null for a required sub-object (e.g. branding: null), the parse throws a schema error
+      // instead of a clear "null override rejected" message. Consider adding an explicit null-guard
+      // in deepMerge to produce a better developer error surface — tracked in vibe-layer decision #22.
+      expect(() =>
+        resolveOrganizationModel({
+          // @ts-expect-error: intentionally passing null to test runtime behavior
+          branding: null
+        })
+      ).toThrow()
+    })
+
+    it('string primitive override replaces default at nested leaf', () => {
+      // Covers the non-plain-object branch in deepMerge when both base and override are strings
+      const model = resolveOrganizationModel({
+        navigation: {
+          defaultSurfaceId: 'crm.pipeline'
+        }
+      })
+
+      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
+      // Sibling object field is preserved from defaults
+      expect(model.navigation.surfaces.length).toBeGreaterThan(0)
+      expect(model.navigation.groups.length).toBeGreaterThan(0)
+    })
+
+    it('deeply nested object merges without clobbering peer keys', () => {
+      // Three-level merge: override a leaf inside navigation without touching other navigation fields.
+      // navigation.defaultSurfaceId is overridden; navigation.surfaces and groups come from defaults.
+      const model = resolveOrganizationModel({
+        navigation: {
+          defaultSurfaceId: 'crm.pipeline'
+        }
+      })
+
+      // Only the leaf was overridden; peer arrays are inherited from defaults (non-empty)
+      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
+      // Peer arrays come from defaults — we check they are non-empty without pinning to a count
+      // that would break every time defaults.ts adds a new surface or group.
+      expect(model.navigation.surfaces.length).toBeGreaterThan(0)
+      expect(model.navigation.groups.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('merged-result schema validation (80/20 gap — decision #22)', () => {
+    // These cases demonstrate that deepMerge() can produce a type-compatible merged result that
+    // OrganizationModelSchema.parse() correctly rejects via superRefine(). The gap cited in
+    // vibe-layer decision #22 is that callers who skip parse() (e.g. use the merged object directly)
+    // will silently carry invalid cross-references. The parse call inside resolveOrganizationModel
+    // is the required gate — skipping it is the 80/20 risk.
+
+    it('rejects a model where defaultSurfaceId does not match any declared surface', () => {
+      // Override navigation to replace all surfaces with one surface, but keep defaultSurfaceId
+      // pointing at a different (non-existent) surface.
+      // deepMerge produces a structurally valid object; superRefine catches the dangling ref.
+      expect(() =>
+        resolveOrganizationModel({
+          navigation: {
+            defaultSurfaceId: 'does-not-exist',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: [],
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: []
+          },
+          features: []
+        })
+      ).toThrow()
+    })
+
+    it('rejects a model where a feature references a surface that does not back-reference it', () => {
+      // Feature says it owns surface 'crm.pipeline'; surface does NOT list the feature in featureIds.
+      // Both sides are plain strings — TypeScript cannot catch this. superRefine must.
+      expect(() =>
+        resolveOrganizationModel({
+          features: [
+            {
+              id: 'crm',
+              label: 'CRM',
+              description: 'CRM',
+              enabled: true,
+              color: 'blue',
+              entityIds: [],
+              surfaceIds: ['crm.pipeline'], // claims this surface
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          navigation: {
+            defaultSurfaceId: 'crm.pipeline',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: [], // does NOT back-reference 'crm'
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: []
+          }
+        })
+      ).toThrow()
+    })
+
+    it('rejects a model where a surface references a feature that does not back-reference it', () => {
+      // Mirror of the previous case: surface claims a feature; feature does not list the surface.
+      expect(() =>
+        resolveOrganizationModel({
+          features: [
+            {
+              id: 'crm',
+              label: 'CRM',
+              description: 'CRM',
+              enabled: true,
+              color: 'blue',
+              entityIds: [],
+              surfaceIds: [], // does NOT list 'crm.pipeline'
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          navigation: {
+            defaultSurfaceId: 'crm.pipeline',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: ['crm'], // claims feature 'crm'
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: []
+          }
+        })
+      ).toThrow()
+    })
+
+    it('rejects a model with duplicate feature ids', () => {
+      // Two features with the same id — structurally valid JavaScript, superRefine detects the collision
+      expect(() =>
+        resolveOrganizationModel({
+          features: [
+            {
+              id: 'crm',
+              label: 'CRM A',
+              description: 'First',
+              enabled: true,
+              color: 'blue',
+              entityIds: [],
+              surfaceIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            },
+            {
+              id: 'crm', // duplicate
+              label: 'CRM B',
+              description: 'Second',
+              enabled: false,
+              color: 'red',
+              entityIds: [],
+              surfaceIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          navigation: {
+            defaultSurfaceId: 'crm.pipeline',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: [],
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: []
+          }
+        })
+      ).toThrow()
+    })
+
+    it('rejects a model with duplicate navigation surface ids', () => {
+      // Two surfaces sharing an id — TypeScript sees string[], superRefine enforces uniqueness
+      expect(() =>
+        resolveOrganizationModel({
+          features: [],
+          navigation: {
+            defaultSurfaceId: 'crm.pipeline',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline A',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: [],
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              },
+              {
+                id: 'crm.pipeline', // duplicate
+                label: 'Pipeline B',
+                path: '/crm/pipeline-2',
+                surfaceType: 'page',
+                featureIds: [],
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: []
+          }
+        })
+      ).toThrow()
+    })
+
+    it('accepts a fully consistent minimal model with bidirectional refs', () => {
+      // Positive control: a hand-constructed model that satisfies all superRefine cross-ref rules
+      // should NOT throw — proving the rejection cases above are schema-specific, not noise
+      expect(() =>
+        resolveOrganizationModel({
+          features: [
+            {
+              id: 'crm',
+              label: 'CRM',
+              description: 'CRM',
+              enabled: true,
+              color: 'blue',
+              entityIds: [],
+              surfaceIds: ['crm.pipeline'],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          navigation: {
+            defaultSurfaceId: 'crm.pipeline',
+            surfaces: [
+              {
+                id: 'crm.pipeline',
+                label: 'Pipeline',
+                path: '/crm/pipeline',
+                surfaceType: 'graph',
+                featureIds: ['crm'], // back-references 'crm'
+                entityIds: [],
+                resourceIds: [],
+                capabilityIds: []
+              }
+            ],
+            groups: [
+              {
+                id: 'primary',
+                label: 'Primary',
+                placement: 'primary',
+                surfaceIds: ['crm.pipeline']
+              }
+            ]
+          }
+        })
+      ).not.toThrow()
+    })
+
+    it('OrganizationModelSchema.parse rejects the same invalid model that resolveOrganizationModel rejects', () => {
+      // Confirms the gap: if a caller uses deepMerge output WITHOUT calling parse,
+      // the dangling defaultSurfaceId ref would go undetected. parse() is the required gate.
+      // This test documents the behavior by verifying parse throws on the invalid merged object.
+      const invalidNavigation = {
+        defaultSurfaceId: 'ghost-surface',
+        surfaces: [],
+        groups: []
+      }
+
+      // Calling parse directly on a shape that has the right structure but broken refs
+      const rawInvalidModel = {
+        version: 1 as const,
+        features: [],
+        branding: {
+          organizationName: 'Test',
+          productName: 'Test',
+          shortName: 'T'
+        },
+        navigation: invalidNavigation,
+        crm: { pipelines: [] },
+        leadGen: { lists: [] },
+        delivery: { projects: [] },
+        resourceMappings: []
+      }
+
+      expect(() => OrganizationModelSchema.parse(rawInvalidModel)).toThrow()
+    })
+  })
+})