@elevasis/core 0.27.0 → 0.28.0

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

@@ -1,144 +1,157 @@
-import { z } from 'zod'
-import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
-
-export const EntityIdSchema = ModelIdSchema
-
-export const EntityLinkKindSchema = z
-  .enum(['belongs-to', 'has-many', 'has-one', 'many-to-many'])
-  .meta({ label: 'Link kind' })
-
-export const EntityLinkSchema = z.object({
-  toEntity: EntityIdSchema.meta({ ref: 'entity' }),
-  kind: EntityLinkKindSchema,
-  via: z.string().trim().min(1).max(255).optional(),
-  label: LabelSchema.optional()
-})
-
-export const EntitySchema = z.object({
-  id: EntityIdSchema,
-  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
-  order: z.number(),
-  label: LabelSchema,
-  description: DescriptionSchema.optional(),
-  ownedBySystemId: ModelIdSchema.meta({ ref: 'system' }),
-  table: z.string().trim().min(1).max(255).optional(),
-  rowSchema: ModelIdSchema.optional(),
-  stateCatalogId: ModelIdSchema.optional(),
-  links: z.array(EntityLinkSchema).optional()
-})
-
-export const EntitiesDomainSchema = z
-  .record(z.string(), EntitySchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each entity entry id must match its map key'
-  })
-  .default({})
-
-const ENTITY_ENTRY_INPUTS: z.input<typeof EntitySchema>[] = [
-  {
-    id: 'crm.deal',
-    order: 10,
-    label: 'Deal',
-    description: 'A CRM opportunity or sales pipeline record.',
-    ownedBySystemId: 'sales.crm',
-    table: 'crm_deals',
-    stateCatalogId: 'crm.pipeline',
-    links: [{ toEntity: 'crm.contact', kind: 'has-many', via: 'deal_contacts', label: 'contacts' }]
-  },
-  {
-    id: 'crm.contact',
-    order: 20,
-    label: 'CRM Contact',
-    description: 'A person associated with a CRM relationship or deal.',
-    ownedBySystemId: 'sales.crm',
-    table: 'crm_contacts'
-  },
-  {
-    id: 'leadgen.list',
-    order: 30,
-    label: 'Lead List',
-    description: 'A prospecting list that groups companies and contacts for acquisition workflows.',
-    ownedBySystemId: 'sales.lead-gen',
-    table: 'acq_lists',
-    links: [
-      { toEntity: 'leadgen.company', kind: 'has-many', via: 'acq_list_companies', label: 'companies' },
-      { toEntity: 'leadgen.contact', kind: 'has-many', via: 'acq_list_members', label: 'contacts' }
-    ]
-  },
-  {
-    id: 'leadgen.company',
-    order: 40,
-    label: 'Lead Company',
-    description: 'A company record sourced, enriched, and qualified during prospecting.',
-    ownedBySystemId: 'sales.lead-gen',
-    table: 'acq_list_companies',
-    stateCatalogId: 'lead-gen.company',
-    links: [
-      { toEntity: 'leadgen.list', kind: 'belongs-to', via: 'list_id', label: 'list' },
-      { toEntity: 'leadgen.contact', kind: 'has-many', via: 'company_id', label: 'contacts' }
-    ]
-  },
-  {
-    id: 'leadgen.contact',
-    order: 50,
-    label: 'Lead Contact',
-    description: 'A prospect contact discovered or enriched during lead generation.',
-    ownedBySystemId: 'sales.lead-gen',
-    table: 'acq_list_members',
-    stateCatalogId: 'lead-gen.contact',
-    links: [
-      { toEntity: 'leadgen.list', kind: 'belongs-to', via: 'list_id', label: 'list' },
-      { toEntity: 'leadgen.company', kind: 'belongs-to', via: 'company_id', label: 'company' }
-    ]
-  },
-  {
-    id: 'delivery.project',
-    order: 60,
-    label: 'Project',
-    description: 'A client delivery project.',
-    ownedBySystemId: 'projects',
-    table: 'projects',
-    links: [
-      { toEntity: 'delivery.milestone', kind: 'has-many', via: 'project_id', label: 'milestones' },
-      { toEntity: 'delivery.task', kind: 'has-many', via: 'project_id', label: 'tasks' }
-    ]
-  },
-  {
-    id: 'delivery.milestone',
-    order: 70,
-    label: 'Milestone',
-    description: 'A delivery checkpoint within a project.',
-    ownedBySystemId: 'projects',
-    table: 'project_milestones',
-    links: [
-      { toEntity: 'delivery.project', kind: 'belongs-to', via: 'project_id', label: 'project' },
-      { toEntity: 'delivery.task', kind: 'has-many', via: 'milestone_id', label: 'tasks' }
-    ]
-  },
-  {
-    id: 'delivery.task',
-    order: 80,
-    label: 'Task',
-    description: 'A delivery task that can move through the task status catalog.',
-    ownedBySystemId: 'projects',
-    table: 'project_tasks',
-    stateCatalogId: 'delivery.task',
-    links: [
-      { toEntity: 'delivery.project', kind: 'belongs-to', via: 'project_id', label: 'project' },
-      { toEntity: 'delivery.milestone', kind: 'belongs-to', via: 'milestone_id', label: 'milestone' }
-    ]
-  }
-]
-
-export const DEFAULT_ORGANIZATION_MODEL_ENTITIES: z.infer<typeof EntitiesDomainSchema> = Object.fromEntries(
-  ENTITY_ENTRY_INPUTS.map((entity) => {
-    const parsed = EntitySchema.parse(entity)
-    return [parsed.id, parsed]
-  })
-)
-
-export type EntityId = z.infer<typeof EntityIdSchema>
-export type EntityLinkKind = z.infer<typeof EntityLinkKindSchema>
-export type EntityLink = z.infer<typeof EntityLinkSchema>
-export type Entity = z.infer<typeof EntitySchema>
-export type EntitiesDomain = z.infer<typeof EntitiesDomainSchema>
+import { z } from 'zod'
+import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
+import { defineDomainRecord } from '../helpers'
+
+export const EntityIdSchema = ModelIdSchema
+
+export const EntityLinkKindSchema = z
+  .enum(['belongs-to', 'has-many', 'has-one', 'many-to-many'])
+  .meta({ label: 'Link kind' })
+
+export const EntityLinkSchema = z.object({
+  toEntity: EntityIdSchema.meta({ ref: 'entity' }),
+  kind: EntityLinkKindSchema,
+  via: z.string().trim().min(1).max(255).optional(),
+  label: LabelSchema.optional()
+})
+
+export const EntitySchema = z.object({
+  id: EntityIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  label: LabelSchema,
+  description: DescriptionSchema.optional(),
+  ownedBySystemId: ModelIdSchema.meta({ ref: 'system' }),
+  table: z.string().trim().min(1).max(255).optional(),
+  rowSchema: ModelIdSchema.optional(),
+  stateCatalogId: ModelIdSchema.optional(),
+  links: z.array(EntityLinkSchema).optional()
+})
+
+export const EntitiesDomainSchema = z
+  .record(z.string(), EntitySchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each entity entry id must match its map key'
+  })
+  .default({})
+
+const ENTITY_ENTRY_INPUTS: z.input<typeof EntitySchema>[] = [
+  {
+    id: 'crm.deal',
+    order: 10,
+    label: 'Deal',
+    description: 'A CRM opportunity or sales pipeline record.',
+    ownedBySystemId: 'sales.crm',
+    table: 'crm_deals',
+    stateCatalogId: 'crm.pipeline',
+    links: [{ toEntity: 'crm.contact', kind: 'has-many', via: 'deal_contacts', label: 'contacts' }]
+  },
+  {
+    id: 'crm.contact',
+    order: 20,
+    label: 'CRM Contact',
+    description: 'A person associated with a CRM relationship or deal.',
+    ownedBySystemId: 'sales.crm',
+    table: 'crm_contacts'
+  },
+  {
+    id: 'leadgen.list',
+    order: 30,
+    label: 'Lead List',
+    description: 'A prospecting list that groups companies and contacts for acquisition workflows.',
+    ownedBySystemId: 'sales.lead-gen',
+    table: 'acq_lists',
+    links: [
+      { toEntity: 'leadgen.company', kind: 'has-many', via: 'acq_list_companies', label: 'companies' },
+      { toEntity: 'leadgen.contact', kind: 'has-many', via: 'acq_list_members', label: 'contacts' }
+    ]
+  },
+  {
+    id: 'leadgen.company',
+    order: 40,
+    label: 'Lead Company',
+    description: 'A company record sourced, enriched, and qualified during prospecting.',
+    ownedBySystemId: 'sales.lead-gen',
+    table: 'acq_list_companies',
+    stateCatalogId: 'lead-gen.company',
+    links: [
+      { toEntity: 'leadgen.list', kind: 'belongs-to', via: 'list_id', label: 'list' },
+      { toEntity: 'leadgen.contact', kind: 'has-many', via: 'company_id', label: 'contacts' }
+    ]
+  },
+  {
+    id: 'leadgen.contact',
+    order: 50,
+    label: 'Lead Contact',
+    description: 'A prospect contact discovered or enriched during lead generation.',
+    ownedBySystemId: 'sales.lead-gen',
+    table: 'acq_list_members',
+    stateCatalogId: 'lead-gen.contact',
+    links: [
+      { toEntity: 'leadgen.list', kind: 'belongs-to', via: 'list_id', label: 'list' },
+      { toEntity: 'leadgen.company', kind: 'belongs-to', via: 'company_id', label: 'company' }
+    ]
+  },
+  {
+    id: 'delivery.project',
+    order: 60,
+    label: 'Project',
+    description: 'A client delivery project.',
+    ownedBySystemId: 'projects',
+    table: 'projects',
+    links: [
+      { toEntity: 'delivery.milestone', kind: 'has-many', via: 'project_id', label: 'milestones' },
+      { toEntity: 'delivery.task', kind: 'has-many', via: 'project_id', label: 'tasks' }
+    ]
+  },
+  {
+    id: 'delivery.milestone',
+    order: 70,
+    label: 'Milestone',
+    description: 'A delivery checkpoint within a project.',
+    ownedBySystemId: 'projects',
+    table: 'project_milestones',
+    links: [
+      { toEntity: 'delivery.project', kind: 'belongs-to', via: 'project_id', label: 'project' },
+      { toEntity: 'delivery.task', kind: 'has-many', via: 'milestone_id', label: 'tasks' }
+    ]
+  },
+  {
+    id: 'delivery.task',
+    order: 80,
+    label: 'Task',
+    description: 'A delivery task that can move through the task status catalog.',
+    ownedBySystemId: 'projects',
+    table: 'project_tasks',
+    stateCatalogId: 'delivery.task',
+    links: [
+      { toEntity: 'delivery.project', kind: 'belongs-to', via: 'project_id', label: 'project' },
+      { toEntity: 'delivery.milestone', kind: 'belongs-to', via: 'milestone_id', label: 'milestone' }
+    ]
+  }
+]
+
+export const DEFAULT_ORGANIZATION_MODEL_ENTITIES: z.infer<typeof EntitiesDomainSchema> = Object.fromEntries(
+  ENTITY_ENTRY_INPUTS.map((entity) => {
+    const parsed = EntitySchema.parse(entity)
+    return [parsed.id, parsed]
+  })
+)
+
+/** Validate and return a single entity entry. */
+export function defineEntity(entry: z.input<typeof EntitySchema>): z.infer<typeof EntitySchema> {
+  return EntitySchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of entity entries. */
+export function defineEntities(
+  entries: readonly z.input<typeof EntitySchema>[]
+): Record<string, z.infer<typeof EntitySchema>> {
+  return defineDomainRecord(EntitySchema, entries)
+}
+
+export type EntityId = z.infer<typeof EntityIdSchema>
+export type EntityLinkKind = z.infer<typeof EntityLinkKindSchema>
+export type EntityLink = z.infer<typeof EntityLinkSchema>
+export type Entity = z.infer<typeof EntitySchema>
+export type EntitiesDomain = z.infer<typeof EntitiesDomainSchema>

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

@@ -1,83 +1,100 @@
-import { z } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Measurable outcome schema — one trackable result that supports a goal.
-// The field name `keyResults` is used for compatibility with OKR tooling;
-// user-facing surfaces and documentation MUST say "measurable outcomes",
-// never "key results" or "OKR".
-// ---------------------------------------------------------------------------
-
-export const KeyResultSchema = z.object({
-  /** Stable unique identifier for the measurable outcome (e.g. "kr-revenue-q1"). */
-  id: z.string().trim().min(1).max(100),
-  /** Plain-language description of this measurable outcome (e.g. "Increase trial-to-paid conversion"). */
-  description: z.string().trim().min(1).max(500),
-  /**
-   * What is being measured — the metric name (e.g. "monthly revenue", "NPS score",
-   * "trial-to-paid conversion rate"). Free-form string.
-   */
-  targetMetric: z.string().trim().min(1).max(200),
-  /** Current measured value. Defaults to 0 when not yet tracked. */
-  currentValue: z.number().default(0),
-  /**
-   * Target value to reach for this measurable outcome to be considered achieved.
-   * Optional — omit if the outcome is directional (e.g. "reduce churn") without
-   * a hard numeric target.
-   */
-  targetValue: z.number().optional()
-})
-
-// ---------------------------------------------------------------------------
-// Objective schema — one goal the organization is working toward.
-// User-facing label is "goal"; this schema type is named Objective for
-// structural continuity with OKR tooling. Do NOT expose "OKR", "objective",
-// or "key result" in any user-facing label or documentation.
-//
-// Period fields use ISO 8601 date strings (YYYY-MM-DD). Cross-schema
-// validation (periodEnd > periodStart) is enforced in
-// `OrganizationModelSchema.superRefine()`.
-// ---------------------------------------------------------------------------
-
-const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/
-
-export const ObjectiveSchema = z.object({
-  /** Stable unique identifier for the goal (e.g. "goal-grow-arr-q1-2026"). */
-  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(),
-  /** Plain-language description of what the organization wants to achieve. */
-  description: z.string().trim().min(1).max(1000),
-  /**
-   * Start of the period this goal is active for — ISO 8601 date string (YYYY-MM-DD).
-   * Must be strictly before `periodEnd`.
-   */
-  periodStart: z.string().regex(ISO_DATE_REGEX, 'periodStart must be an ISO date string (YYYY-MM-DD)'),
-  /**
-   * End of the period this goal is active for — ISO 8601 date string (YYYY-MM-DD).
-   * Must be strictly after `periodStart`.
-   * Enforced via `OrganizationModelSchema.superRefine()`.
-   */
-  periodEnd: z.string().regex(ISO_DATE_REGEX, 'periodEnd must be an ISO date string (YYYY-MM-DD)'),
-  /**
-   * List of measurable outcomes that define success for this goal.
-   * Defaults to empty array so goals can be declared before outcomes are defined.
-   */
-  keyResults: z.array(KeyResultSchema).default([])
-})
-
-// ---------------------------------------------------------------------------
-// Goals domain schema — a collection of goals the organization is pursuing.
-// ---------------------------------------------------------------------------
-
-export const GoalsDomainSchema = z
-  .record(z.string(), ObjectiveSchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each objective entry id must match its map key'
-  })
-  .default({})
-
-// ---------------------------------------------------------------------------
-// Seed — empty by default; adapters populate with real goal definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_GOALS: z.infer<typeof GoalsDomainSchema> = {}
+import { z } from 'zod'
+import { defineDomainRecord } from '../helpers'
+
+// ---------------------------------------------------------------------------
+// Measurable outcome schema — one trackable result that supports a goal.
+// The field name `keyResults` is used for compatibility with OKR tooling;
+// user-facing surfaces and documentation MUST say "measurable outcomes",
+// never "key results" or "OKR".
+// ---------------------------------------------------------------------------
+
+export const KeyResultSchema = z.object({
+  /** Stable unique identifier for the measurable outcome (e.g. "kr-revenue-q1"). */
+  id: z.string().trim().min(1).max(100),
+  /** Plain-language description of this measurable outcome (e.g. "Increase trial-to-paid conversion"). */
+  description: z.string().trim().min(1).max(500),
+  /**
+   * What is being measured — the metric name (e.g. "monthly revenue", "NPS score",
+   * "trial-to-paid conversion rate"). Free-form string.
+   */
+  targetMetric: z.string().trim().min(1).max(200),
+  /** Current measured value. Defaults to 0 when not yet tracked. */
+  currentValue: z.number().default(0),
+  /**
+   * Target value to reach for this measurable outcome to be considered achieved.
+   * Optional — omit if the outcome is directional (e.g. "reduce churn") without
+   * a hard numeric target.
+   */
+  targetValue: z.number().optional()
+})
+
+// ---------------------------------------------------------------------------
+// Objective schema — one goal the organization is working toward.
+// User-facing label is "goal"; this schema type is named Objective for
+// structural continuity with OKR tooling. Do NOT expose "OKR", "objective",
+// or "key result" in any user-facing label or documentation.
+//
+// Period fields use ISO 8601 date strings (YYYY-MM-DD). Cross-schema
+// validation (periodEnd > periodStart) is enforced in
+// `OrganizationModelSchema.superRefine()`.
+// ---------------------------------------------------------------------------
+
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/
+
+export const ObjectiveSchema = z.object({
+  /** Stable unique identifier for the goal (e.g. "goal-grow-arr-q1-2026"). */
+  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(),
+  /** Plain-language description of what the organization wants to achieve. */
+  description: z.string().trim().min(1).max(1000),
+  /**
+   * Start of the period this goal is active for — ISO 8601 date string (YYYY-MM-DD).
+   * Must be strictly before `periodEnd`.
+   */
+  periodStart: z.string().regex(ISO_DATE_REGEX, 'periodStart must be an ISO date string (YYYY-MM-DD)'),
+  /**
+   * End of the period this goal is active for — ISO 8601 date string (YYYY-MM-DD).
+   * Must be strictly after `periodStart`.
+   * Enforced via `OrganizationModelSchema.superRefine()`.
+   */
+  periodEnd: z.string().regex(ISO_DATE_REGEX, 'periodEnd must be an ISO date string (YYYY-MM-DD)'),
+  /**
+   * List of measurable outcomes that define success for this goal.
+   * Defaults to empty array so goals can be declared before outcomes are defined.
+   */
+  keyResults: z.array(KeyResultSchema).default([])
+})
+
+// ---------------------------------------------------------------------------
+// Goals domain schema — a collection of goals the organization is pursuing.
+// ---------------------------------------------------------------------------
+
+export const GoalsDomainSchema = z
+  .record(z.string(), ObjectiveSchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each objective entry id must match its map key'
+  })
+  .default({})
+
+// ---------------------------------------------------------------------------
+// Seed — empty by default; adapters populate with real goal definitions.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ORGANIZATION_MODEL_GOALS: z.infer<typeof GoalsDomainSchema> = {}
+
+/** Validate and return a single goal (objective) entry. */
+export function defineGoal(entry: z.input<typeof ObjectiveSchema>): z.infer<typeof ObjectiveSchema> {
+  return ObjectiveSchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of goal entries. */
+export function defineGoals(
+  entries: readonly z.input<typeof ObjectiveSchema>[]
+): Record<string, z.infer<typeof ObjectiveSchema>> {
+  return defineDomainRecord(ObjectiveSchema, entries)
+}
+
+export type KeyResult = z.infer<typeof KeyResultSchema>
+export type Objective = z.infer<typeof ObjectiveSchema>
+export type GoalsDomain = z.infer<typeof GoalsDomainSchema>