@elevasis/core 0.26.0 → 0.28.0

package/src/organization-model/cross-ref.ts

@@ -0,0 +1,175 @@
+/**
+ * Browser-safe shared cross-reference index for the Organization Model.
+ *
+ * This module is the single source of truth for OM cross-reference resolution.
+ * It is consumed by:
+ *   - `OrganizationModelSchema.superRefine` (Zod validation, browser-safe)
+ *   - `packages/cli/src/knowledge/verify.ts` (CLI gate, Node-only)
+ *
+ * INVARIANT: No Node.js builtins, no `@repo/elevasis-core` import, no dynamic import().
+ */
+
+import { compileOrganizationOntology } from './ontology'
+import { listAllSystems } from './helpers'
+import type { OntologyKind } from './ontology'
+import type { OrganizationModel } from './types'
+
+// ---------------------------------------------------------------------------
+// Shared key-to-kind map
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps ontology reference field keys (as they appear inside ontology records
+ * and resource ontology bindings) to their expected OntologyKind.
+ *
+ * Single source of truth — replaces both the byte-identical
+ * `ontologyReferenceKeyKinds` in `schema.ts` and `genericReferenceKeyKinds`
+ * in `verify.ts`.
+ */
+export const ONTOLOGY_REFERENCE_KEY_KINDS: Record<string, OntologyKind> = {
+  valueType: 'value-type',
+  catalogType: 'catalog',
+  objectType: 'object',
+  eventType: 'event',
+  actionType: 'action',
+  linkType: 'link',
+  interfaceType: 'interface',
+  propertyType: 'property',
+  groupType: 'group',
+  surfaceType: 'surface',
+  stepCatalog: 'catalog'
+} satisfies Record<string, OntologyKind>
+
+// ---------------------------------------------------------------------------
+// Cross-reference index
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-built look-up sets derived from a resolved OrganizationModel.
+ * Built once, then consumed by both validation paths (superRefine + verify.ts).
+ */
+export interface OmCrossRefIndex {
+  /**
+   * Systems keyed by BOTH dotted path (e.g. "sales.lead-gen") AND system.id.
+   * Value is opaque (`unknown`) — consumers only call `.has()`.
+   */
+  systemsById: Map<string, unknown>
+  resourceIds: Set<string>
+  knowledgeIds: Set<string>
+  roleIds: Set<string>
+  goalIds: Set<string>
+  actionIds: Set<string>
+  customerSegmentIds: Set<string>
+  offeringIds: Set<string>
+  ontologyIds: Set<string>
+  /** Ontology records indexed by kind (value is a plain id→record map). */
+  ontologyIndexByKind: Record<OntologyKind, Record<string, unknown>>
+  /** IDs of individual stage entries from all catalogs with `kind === 'stage'`. */
+  stageIds: Set<string>
+}
+
+/**
+ * Build the OmCrossRefIndex from a resolved OrganizationModel.
+ *
+ * Call once per validation pass and share the result across all checks.
+ */
+export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex {
+  // Systems: keyed by path AND by system.id (path-OR-id resolution)
+  const systemsById = new Map<string, unknown>()
+  for (const { path, system } of listAllSystems(model)) {
+    systemsById.set(path, system)
+    systemsById.set(system.id, system)
+  }
+
+  const resourceIds = new Set(Object.keys(model.resources ?? {}))
+  const knowledgeIds = new Set(Object.keys(model.knowledge ?? {}))
+  const roleIds = new Set(Object.keys(model.roles ?? {}))
+  const goalIds = new Set(Object.keys(model.goals ?? {}))
+  const actionIds = new Set(Object.keys(model.actions ?? {}))
+  const customerSegmentIds = new Set(Object.keys(model.customers ?? {}))
+  const offeringIds = new Set(Object.keys(model.offerings ?? {}))
+
+  const ontologyCompilation = compileOrganizationOntology(model)
+
+  const ontologyIndexByKind: Record<OntologyKind, Record<string, unknown>> = {
+    object: ontologyCompilation.ontology.objectTypes,
+    link: ontologyCompilation.ontology.linkTypes,
+    action: ontologyCompilation.ontology.actionTypes,
+    catalog: ontologyCompilation.ontology.catalogTypes,
+    event: ontologyCompilation.ontology.eventTypes,
+    interface: ontologyCompilation.ontology.interfaceTypes,
+    'value-type': ontologyCompilation.ontology.valueTypes,
+    property: ontologyCompilation.ontology.sharedProperties,
+    group: ontologyCompilation.ontology.groups,
+    surface: ontologyCompilation.ontology.surfaces
+  }
+
+  const ontologyIds = new Set(Object.values(ontologyIndexByKind).flatMap((index) => Object.keys(index)))
+
+  // Stage IDs: entry keys from all catalogs whose kind === 'stage'
+  const stageIds = new Set<string>()
+  for (const catalog of Object.values(ontologyCompilation.ontology.catalogTypes)) {
+    if ((catalog as { kind?: string }).kind !== 'stage') continue
+    const entries = (catalog as { entries?: Record<string, unknown> }).entries
+    if (entries !== undefined) {
+      for (const stageId of Object.keys(entries)) {
+        stageIds.add(stageId)
+      }
+    }
+  }
+
+  return {
+    systemsById,
+    resourceIds,
+    knowledgeIds,
+    roleIds,
+    goalIds,
+    actionIds,
+    customerSegmentIds,
+    offeringIds,
+    ontologyIds,
+    ontologyIndexByKind,
+    stageIds
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Canonical resolution functions
+// ---------------------------------------------------------------------------
+
+/**
+ * The ONLY definition of which (kind, id) knowledge-link targets resolve.
+ *
+ * Fixes two confirmed divergences vs. the old inline `exists()` in verify.ts:
+ *  1. `kind === 'stage'` — previously missing in verify.ts, causing a false-positive error.
+ *  2. `kind === 'system'` — resolves via `systemsById` which is keyed by BOTH path AND
+ *     `system.id`, so a system referenced by its id (not its dotted path) is also found.
+ */
+export function knowledgeTargetExists(index: OmCrossRefIndex, kind: string, id: string): boolean {
+  if (kind === 'system') return index.systemsById.has(id)
+  if (kind === 'resource') return index.resourceIds.has(id)
+  if (kind === 'knowledge') return index.knowledgeIds.has(id)
+  if (kind === 'stage') return index.stageIds.has(id)
+  if (kind === 'action') return index.actionIds.has(id)
+  if (kind === 'role') return index.roleIds.has(id)
+  if (kind === 'goal') return index.goalIds.has(id)
+  if (kind === 'customer-segment') return index.customerSegmentIds.has(id)
+  if (kind === 'offering') return index.offeringIds.has(id)
+  if (kind === 'ontology') return index.ontologyIds.has(id)
+  return false
+}
+
+/**
+ * Returns `true` when a resource ontology binding references an ontology ID
+ * that does not exist in the compiled index for the expected kind.
+ *
+ * Shared between `schema.ts` resource-ontology binding validation and
+ * `verify.ts` resource ontology reference checks.
+ */
+export function resourceOntologyBindingMissing(
+  index: OmCrossRefIndex,
+  expectedKind: OntologyKind,
+  ontologyId: string
+): boolean {
+  return index.ontologyIndexByKind[expectedKind][ontologyId] === undefined
+}

package/src/organization-model/domains/actions.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { EntityIdSchema } from './entities'
 import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
+import { defineDomainRecord } from '../helpers'
 
 export const ActionResourceIdSchema = z
   .string()
@@ -107,6 +108,18 @@ export function findOrganizationActionById(
   return actions[id]
 }
 
+/** Validate and return a single action entry. */
+export function defineAction(entry: z.input<typeof ActionSchema>): z.infer<typeof ActionSchema> {
+  return ActionSchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of action entries. */
+export function defineActions(
+  entries: readonly z.input<typeof ActionSchema>[]
+): Record<string, z.infer<typeof ActionSchema>> {
+  return defineDomainRecord(ActionSchema, entries)
+}
+
 export type ActionId = z.infer<typeof ActionIdSchema>
 export type ActionScope = z.infer<typeof ActionScopeSchema>
 export type ActionRef = z.infer<typeof ActionRefSchema>

package/src/organization-model/domains/branding.ts

@@ -14,9 +14,9 @@ export const OrganizationModelBrandingSchema = z.object({
     .default({})
 })
 
-export const DEFAULT_ORGANIZATION_MODEL_BRANDING: z.infer<typeof OrganizationModelBrandingSchema> = {
-  organizationName: 'Default Organization',
-  productName: 'Elevasis',
-  shortName: 'Elevasis',
-  logos: {}
-}
+export const DEFAULT_ORGANIZATION_MODEL_BRANDING: z.infer<typeof OrganizationModelBrandingSchema> = {
+  organizationName: 'Default Organization',
+  productName: 'Organization OS',
+  shortName: 'Org OS',
+  logos: {}
+}

package/src/organization-model/domains/customers.ts

@@ -1,78 +1,95 @@
-import { z } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Firmographics — optional demographic/firmographic filters that describe the
-// target customer segment's organizational profile. All fields are optional so
-// a segment can declare only the axes relevant to targeting.
-// ---------------------------------------------------------------------------
-
-export const FirmographicsSchema = z.object({
-  /** Industry vertical (e.g. "Marketing Agency", "Legal", "Real Estate"). */
-  industry: z.string().trim().max(200).optional(),
-  /**
-   * Company headcount band (e.g. "1–10", "11–50", "51–200", "200+").
-   * Free-form string to accommodate any band notation.
-   */
-  companySize: z.string().trim().max(100).optional(),
-  /**
-   * Primary geographic region the segment operates in or is targeted from
-   * (e.g. "North America", "Europe", "Global").
-   */
-  region: z.string().trim().max(200).optional()
-})
-
-// ---------------------------------------------------------------------------
-// Customer segment schema — one entry per distinct buyer archetype.
-// Modeled after Value Proposition Canvas (BMC / VPC) and Business Model Canvas
-// customer-segment language. Fields use plain English throughout.
-// ---------------------------------------------------------------------------
-
-export const CustomerSegmentSchema = z.object({
-  /** Stable unique identifier for the segment (e.g. "segment-smb-agencies"). */
-  id: z.string().trim().min(1).max(100),
-  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
-  order: z.number(),
-  /** Human-readable name shown to agents and in UI (e.g. "SMB Marketing Agencies"). */
-  name: z.string().trim().max(200).default(''),
-  /** One or two sentences describing who this segment is. */
-  description: z.string().trim().max(2000).default(''),
-  /**
-   * The primary job(s) this segment is trying to get done — the goal they hire
-   * a product/service to accomplish. Plain-language narrative or bullet list.
-   */
-  jobsToBeDone: z.string().trim().max(2000).default(''),
-  /**
-   * Pains — frustrations, obstacles, and risks the segment experiences
-   * when trying to accomplish their jobs-to-be-done.
-   */
-  pains: z.array(z.string().trim().max(500)).default([]),
-  /**
-   * Gains — outcomes and benefits the segment desires; positive motivators
-   * beyond merely resolving pains.
-   */
-  gains: z.array(z.string().trim().max(500)).default([]),
-  /** Firmographic profile for targeting and filtering. */
-  firmographics: FirmographicsSchema.default({}),
-  /**
-   * Value proposition — one or two sentences stating why this organization's
-   * offering is uniquely suited for this segment's needs.
-   */
-  valueProp: z.string().trim().max(2000).default('')
-})
-
-// ---------------------------------------------------------------------------
-// Customers domain schema — id-keyed map of customer segments.
-// ---------------------------------------------------------------------------
-
-export const CustomersDomainSchema = z
-  .record(z.string(), CustomerSegmentSchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each segment entry id must match its map key'
-  })
-  .default({})
-
-// ---------------------------------------------------------------------------
-// Seed — empty by default; adapters populate with real segment definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_CUSTOMERS: z.infer<typeof CustomersDomainSchema> = {}
+import { z } from 'zod'
+import { defineDomainRecord } from '../helpers'
+
+// ---------------------------------------------------------------------------
+// Firmographics — optional demographic/firmographic filters that describe the
+// target customer segment's organizational profile. All fields are optional so
+// a segment can declare only the axes relevant to targeting.
+// ---------------------------------------------------------------------------
+
+export const FirmographicsSchema = z.object({
+  /** Industry vertical (e.g. "Marketing Agency", "Legal", "Real Estate"). */
+  industry: z.string().trim().max(200).optional(),
+  /**
+   * Company headcount band (e.g. "1–10", "11–50", "51–200", "200+").
+   * Free-form string to accommodate any band notation.
+   */
+  companySize: z.string().trim().max(100).optional(),
+  /**
+   * Primary geographic region the segment operates in or is targeted from
+   * (e.g. "North America", "Europe", "Global").
+   */
+  region: z.string().trim().max(200).optional()
+})
+
+// ---------------------------------------------------------------------------
+// Customer segment schema — one entry per distinct buyer archetype.
+// Modeled after Value Proposition Canvas (BMC / VPC) and Business Model Canvas
+// customer-segment language. Fields use plain English throughout.
+// ---------------------------------------------------------------------------
+
+export const CustomerSegmentSchema = z.object({
+  /** Stable unique identifier for the segment (e.g. "segment-smb-agencies"). */
+  id: z.string().trim().min(1).max(100),
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  /** Human-readable name shown to agents and in UI (e.g. "SMB Marketing Agencies"). */
+  name: z.string().trim().max(200).default(''),
+  /** One or two sentences describing who this segment is. */
+  description: z.string().trim().max(2000).default(''),
+  /**
+   * The primary job(s) this segment is trying to get done — the goal they hire
+   * a product/service to accomplish. Plain-language narrative or bullet list.
+   */
+  jobsToBeDone: z.string().trim().max(2000).default(''),
+  /**
+   * Pains — frustrations, obstacles, and risks the segment experiences
+   * when trying to accomplish their jobs-to-be-done.
+   */
+  pains: z.array(z.string().trim().max(500)).default([]),
+  /**
+   * Gains — outcomes and benefits the segment desires; positive motivators
+   * beyond merely resolving pains.
+   */
+  gains: z.array(z.string().trim().max(500)).default([]),
+  /** Firmographic profile for targeting and filtering. */
+  firmographics: FirmographicsSchema.default({}),
+  /**
+   * Value proposition — one or two sentences stating why this organization's
+   * offering is uniquely suited for this segment's needs.
+   */
+  valueProp: z.string().trim().max(2000).default('')
+})
+
+// ---------------------------------------------------------------------------
+// Customers domain schema — id-keyed map of customer segments.
+// ---------------------------------------------------------------------------
+
+export const CustomersDomainSchema = z
+  .record(z.string(), CustomerSegmentSchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each segment entry id must match its map key'
+  })
+  .default({})
+
+// ---------------------------------------------------------------------------
+// Seed — empty by default; adapters populate with real segment definitions.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ORGANIZATION_MODEL_CUSTOMERS: z.infer<typeof CustomersDomainSchema> = {}
+
+/** Validate and return a single customer segment entry. */
+export function defineCustomer(entry: z.input<typeof CustomerSegmentSchema>): z.infer<typeof CustomerSegmentSchema> {
+  return CustomerSegmentSchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of customer segment entries. */
+export function defineCustomers(
+  entries: readonly z.input<typeof CustomerSegmentSchema>[]
+): Record<string, z.infer<typeof CustomerSegmentSchema>> {
+  return defineDomainRecord(CustomerSegmentSchema, entries)
+}
+
+export type CustomerSegment = z.infer<typeof CustomerSegmentSchema>
+export type CustomersDomain = z.infer<typeof CustomersDomainSchema>
+export type Firmographics = z.infer<typeof FirmographicsSchema>