# Organization Model

The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.

Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.

## Published Exports

The public entry point exposes:

- `OrganizationModelSchema`
- `DEFAULT_ORGANIZATION_MODEL`
- `defineOrganizationModel`
- `resolveOrganizationModel`
- `createFoundationOrganizationModel`
- node ID and System 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`
- `domainMetadata`
- `branding`
- `navigation`
- `sales`
- `prospecting`
- `projects`
- `identity`
- `customers`
- `offerings`
- `roles`
- `goals`
- `systems`
- `resources`
- `capabilities`
- `policies`
- `statuses`
- `knowledge`

The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.

Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.

## System Set

System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:

```ts
systems: {
  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
}
```

Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.

## Sidebar Navigation

Shell navigation is authored as a recursive sidebar tree:

```ts
navigation: {
  sidebar: {
    primary: {
      dashboard: {
        type: 'surface',
        order: 10,
        label: 'Dashboard',
        path: '/',
        surfaceType: 'dashboard',
        targets: { systems: ['dashboard'] }
      },
      business: {
        type: 'group',
        order: 20,
        label: 'Business',
        children: {
          clients: {
            type: 'surface',
            order: 20,
            label: 'Clients',
            path: '/clients',
            surfaceType: 'list',
            targets: { systems: ['clients'] }
          }
        }
      }
    },
    bottom: {}
  }
}
```

Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.

## Graph IDs

Cross-collection links use kind-prefixed IDs:

- `system:sales.crm`
- `integration:instantly`
- `resource:lead-import`
- `action:operations.queue.review`

## Resource Descriptors

The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.

## 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.
- Id-keyed domain maps merge additively by key.
- Arrays replace the default value.
- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.

## Referential Integrity

- System IDs must be unique.
- Child System IDs require valid ancestors or `parentSystemId` links.
- Systems with UI provide `ui.path`.
- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.

## Practical Guidance

- Use `resolveOrganizationModel()` when you need a runtime-safe model.
- Use `defineOrganizationModel()` when authoring static overrides.
- Keep System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
- Put resource identity and governance in `resources`; attach executable behavior in operations.
