@elevasis/core 0.10.0 → 0.11.0

package/src/organization-model/README.md

@@ -1,97 +1,101 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
-
-Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `PROJECTS_FEATURE_ID`
-- `PROJECTS_INDEX_SURFACE_ID`
-- `PROJECTS_VIEW_CAPABILITY_ID`
-- `OrganizationModel` and the supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  PROJECTS_VIEW_CAPABILITY_ID,
-  defineOrganizationModel,
-  PROJECTS_FEATURE_ID,
-  PROJECTS_INDEX_SURFACE_ID,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version` - schema version for the resolved contract.
-- `branding` - organization branding defaults and overrides.
-- `features` - unified feature entries that combine enablement, labels, and semantic references.
-- `navigation` - navigation model for the product shell.
-- `sales` - sales pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
-- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
-- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
-- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
-
-## Default Feature Set
-
-The default model includes eight feature IDs:
-
-- `sales` - deal pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `operations` - organization graph and command-view surfaces.
-- `monitoring` - monitoring surfaces.
-- `settings` - organization settings.
-- `seo` - SEO surfaces (disabled by default).
-- `configure` - `/configure` skill entry point (external projects).
-
-## Project Bridge Constants
-
-The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
-
-- `PROJECTS_FEATURE_ID` -> `projects`
-- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
-- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
-
-Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
-- Plain objects merge recursively.
-- Arrays replace the default value instead of merging element-by-element.
-- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- `navigation.defaultSurfaceId` must point at a declared navigation surface.
-- Every navigation group `surfaceId` must resolve to a declared surface.
-- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
-- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
-- Feature-bearing surfaces validate `featureId` against the canonical feature set.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
-- Use `defineOrganizationModel()` when authoring a static partial model in source.
-- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
-- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's product shape to flat feature hierarchy, shell navigation, business semantics, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, feature gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `FeatureSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and feature helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `branding`
+- `features`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `statuses`
+- `operations`
+
+Resources bind to the graph from deployment metadata through `links` and `category`.
+
+## Feature Set
+
+Feature hierarchy is authored as a flat array. Dotted IDs define parent/child relationships:
+
+```ts
+features: [
+  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
+  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
+  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
+  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
+]
+```
+
+Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `feature:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `capability:operations.queue.review`
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- Feature IDs must be unique.
+- Child feature IDs require ancestor feature nodes.
+- Container features omit `path`.
+- Leaf features provide `path`.
+- Resource links are validated against graph node IDs during registry registration.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model.
+- Use `defineOrganizationModel()` when authoring static overrides.
+- Keep feature IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put semantic resource relationships on resource metadata, not on feature nodes.

package/src/organization-model/__tests__/domains/resource-mappings.test.ts

@@ -267,96 +267,27 @@ describe('ResourceMappingSchema — mixed techStack presence across entries', ()
 // Group 6: Integration via resolveOrganizationModel
 // ---------------------------------------------------------------------------
 
-describe('resolveOrganizationModel — resourceMappings with techStack', () => {
-  it('resolves a model with no resourceMappings (default empty array)', () => {
-    const model = resolveOrganizationModel({})
-    expect(model.resourceMappings).toEqual([])
-  })
-
-  it('resolves a model with a resourceMapping that has no techStack', () => {
-    const model = resolveOrganizationModel({
-      resourceMappings: [
-        {
-          id: 'rm-legacy',
-          label: 'Legacy mapping',
-          resourceId: 'legacy-workflow',
-          resourceType: 'workflow',
-          featureIds: [],
-          entityIds: [],
-          surfaceIds: [],
-          capabilityIds: []
-        }
-      ]
-    })
-    expect(model.resourceMappings).toHaveLength(1)
-    expect(model.resourceMappings[0].techStack).toBeUndefined()
-  })
-
-  it('resolves a model with a resourceMapping that has techStack', () => {
-    const model = resolveOrganizationModel({
-      resourceMappings: [
-        {
-          id: 'rm-crm-sync',
-          label: 'CRM Sync',
-          resourceId: 'crm-sync-workflow',
-          resourceType: 'workflow',
-          featureIds: [],
-          entityIds: [],
-          surfaceIds: [],
-          capabilityIds: [],
-          techStack: {
-            platform: 'Salesforce',
-            purpose: 'Enterprise CRM integration',
-            credentialStatus: 'configured',
-            isSystemOfRecord: true
-          }
-        }
-      ]
-    })
-    expect(model.resourceMappings).toHaveLength(1)
-    const mapping = model.resourceMappings[0]
-    expect(mapping.techStack).toBeDefined()
-    expect(mapping.techStack?.platform).toBe('Salesforce')
-    expect(mapping.techStack?.isSystemOfRecord).toBe(true)
-  })
-
-  it('resolves multiple mappings with mixed techStack presence', () => {
-    const model = resolveOrganizationModel({
-      resourceMappings: [
-        {
-          id: 'rm-a',
-          label: 'Mapping A',
-          resourceId: 'workflow-a',
-          resourceType: 'workflow',
-          featureIds: [],
-          entityIds: [],
-          surfaceIds: [],
-          capabilityIds: [],
-          techStack: {
-            platform: 'HubSpot',
-            purpose: 'Contacts',
-            credentialStatus: 'pending'
-          }
-        },
-        {
-          id: 'rm-b',
-          label: 'Mapping B',
-          resourceId: 'workflow-b',
-          resourceType: 'agent',
-          featureIds: [],
-          entityIds: [],
-          surfaceIds: [],
-          capabilityIds: []
-        }
-      ]
-    })
-    expect(model.resourceMappings).toHaveLength(2)
-    expect(model.resourceMappings[0].techStack?.platform).toBe('HubSpot')
-    expect(model.resourceMappings[0].techStack?.isSystemOfRecord).toBe(false)
-    expect(model.resourceMappings[1].techStack).toBeUndefined()
-  })
-
-  it('resolved model still validates without errors when resourceMappings omitted', () => {
-    expect(() => resolveOrganizationModel({})).not.toThrow()
-  })
-})
+describe('resolveOrganizationModel resource mapping removal', () => {
+  it('resolved model validates without resourceMappings', () => {
+    expect(() => resolveOrganizationModel({})).not.toThrow()
+  })
+
+  it('drops resourceMappings overrides because graph links now live on resources', () => {
+    const model = resolveOrganizationModel({
+      resourceMappings: [
+        {
+          id: 'rm-legacy',
+          label: 'Legacy mapping',
+          resourceId: 'legacy-workflow',
+          resourceType: 'workflow',
+          featureIds: [],
+          entityIds: [],
+          surfaceIds: [],
+          capabilityIds: []
+        }
+      ]
+    } as Parameters<typeof resolveOrganizationModel>[0])
+
+    expect('resourceMappings' in model).toBe(false)
+  })
+})