@elevasis/core 0.21.0 → 0.23.0

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

@@ -1,80 +1,83 @@
-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),
-  /** 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.object({
-  objectives: z.array(ObjectiveSchema).default([])
-})
-
-// ---------------------------------------------------------------------------
-// Seed — empty by default; adapters populate with real goal definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_GOALS: z.infer<typeof GoalsDomainSchema> = {
-  objectives: []
-}
+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> = {}

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

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { IconNameSchema, ModelIdSchema } from './shared'
-import { NodeIdStringSchema } from './features'
+import { NodeIdStringSchema } from './systems'
+import { RoleIdSchema } from './roles'
 
 // ---------------------------------------------------------------------------
 // KnowledgeLink — a typed graph link pointing to another OM node.
@@ -8,12 +9,60 @@ import { NodeIdStringSchema } from './features'
 // Phase 1 only emits 'governs' edges from knowledge nodes.
 // ---------------------------------------------------------------------------
 
-export const KnowledgeLinkSchema = z.object({
+export const KnowledgeTargetKindSchema = z
+  .enum([
+    'system',
+    'resource',
+    'knowledge',
+    'stage',
+    'action',
+    'role',
+    'goal',
+    'customer-segment',
+    'offering',
+    // D4: content nodes are a valid knowledge target after compound-domain data moved into system.content
+    'content-node'
+  ])
+  .meta({ label: 'Target kind' })
+
+export const KnowledgeTargetRefSchema = z.object({
+  kind: KnowledgeTargetKindSchema,
+  // D4: content-node targets use a qualified id format '<system-path>:<local-content-id>'
+  // which contains a colon separator and cannot satisfy ModelIdSchema. Use a permissive
+  // string schema here; business-logic validation of target existence is done in
+  // OrganizationModelSchema.superRefine (knowledgeTargetExists).
+  id: z.string().trim().min(1).max(300)
+})
+
+const LegacyKnowledgeLinkSchema = z.object({
   nodeId: NodeIdStringSchema
 })
 
-export const KnowledgeSkillBindingSchema = z.string().trim().min(1).max(120)
-export const KnowledgeDomainBindingSchema = z.string().trim().min(1).max(80)
+const CanonicalKnowledgeLinkSchema = z.object({
+  target: KnowledgeTargetRefSchema
+})
+
+function nodeIdFromTarget(target: z.infer<typeof KnowledgeTargetRefSchema>): string {
+  return `${target.kind}:${target.id}`
+}
+
+function targetFromNodeId(nodeId: string): z.infer<typeof KnowledgeTargetRefSchema> {
+  const [kind, ...idParts] = nodeId.split(':')
+  return {
+    kind: KnowledgeTargetKindSchema.parse(kind),
+    id: idParts.join(':')
+  }
+}
+
+export const KnowledgeLinkSchema = z
+  .union([CanonicalKnowledgeLinkSchema, LegacyKnowledgeLinkSchema])
+  .transform((link) => {
+    const target = 'target' in link ? link.target : targetFromNodeId(link.nodeId)
+    return {
+      target,
+      nodeId: nodeIdFromTarget(target)
+    }
+  })
 
 // ---------------------------------------------------------------------------
 // OrgKnowledgeNode — single schema, `kind` discriminator drives presentation.
@@ -21,7 +70,9 @@ export const KnowledgeDomainBindingSchema = z.string().trim().min(1).max(80)
 // Phase 2 (deferred): structured block format (Supabase-backed authoring).
 // ---------------------------------------------------------------------------
 
-export const OrgKnowledgeKindSchema = z.enum(['playbook', 'strategy', 'reference'])
+export const OrgKnowledgeKindSchema = z
+  .enum(['playbook', 'strategy', 'reference'])
+  .meta({ label: 'Knowledge kind', color: 'grape' })
 
 export const OrgKnowledgeNodeSchema = z.object({
   id: ModelIdSchema,
@@ -29,6 +80,8 @@ export const OrgKnowledgeNodeSchema = z.object({
   title: z.string().trim().min(1).max(200),
   summary: z.string().trim().min(1).max(1000),
   icon: IconNameSchema.optional(),
+  /** Canonical documentation URL when body content is a local summary. */
+  externalUrl: z.string().trim().url().max(500).optional(),
   /** Raw MDX string. Phase 2 will introduce a structured block format. */
   body: z.string().trim().min(1),
   /**
@@ -36,27 +89,33 @@ export const OrgKnowledgeNodeSchema = z.object({
    * Each link emits a `governs` edge: knowledge-node -> target node.
    */
   links: z.array(KnowledgeLinkSchema).default([]),
-  /** Operator skill or command bindings relevant to this node. */
-  skills: z.array(KnowledgeSkillBindingSchema).optional(),
-  /** Domain key used to derive fast graph->skill registries. */
-  domain: KnowledgeDomainBindingSchema.optional(),
-  /** Identifiers of the roles or members who own this knowledge node. */
-  ownerIds: z.array(ModelIdSchema).default([]),
+  /** Role identifiers that own this knowledge node. */
+  ownerIds: z.array(RoleIdSchema.meta({ ref: 'role' })).default([]),
   /** ISO date string (YYYY-MM-DD or full ISO 8601) of last meaningful update. */
   updatedAt: z.string().trim().min(1).max(50)
 })
 
 // ---------------------------------------------------------------------------
-// Domain schema — flat array of knowledge nodes
+// Domain schema — flat Record<id, KnowledgeNode> (D3: flatten per Phase 4 cut)
+//
+// Wave 1 shape change: the old wrapper object { version, lastModified, nodes[] }
+// is replaced by a plain id-keyed map. version/lastModified move to
+// domainMetadata.knowledge (D7). The default is an empty map {}.
+//
+// Wave 2 (elevasis-core canonicalOrganizationModel) must produce a value of this
+// shape: Record<KnowledgeId, OrgKnowledgeNode> — i.e., an object keyed by
+// each node's id string, with OrgKnowledgeNode as the value. Example:
+//   knowledge: {
+//     'playbook.crm.discovery': { id: 'playbook.crm.discovery', kind: 'playbook', ... },
+//   }
 // ---------------------------------------------------------------------------
 
-export const KnowledgeDomainSchema = z.object({
-  nodes: z.array(OrgKnowledgeNodeSchema).default([])
-})
+export const KnowledgeDomainSchema = z.record(ModelIdSchema, OrgKnowledgeNodeSchema).default({})
 
 export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
+export type OrgKnowledgeNodeInput = z.input<typeof OrgKnowledgeNodeSchema>
 export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>
+export type KnowledgeTargetKind = z.infer<typeof KnowledgeTargetKindSchema>
+export type KnowledgeTargetRef = z.infer<typeof KnowledgeTargetRefSchema>
 export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>
-export type KnowledgeSkillBinding = z.infer<typeof KnowledgeSkillBindingSchema>
-export type KnowledgeDomainBinding = z.infer<typeof KnowledgeDomainBindingSchema>
 export type KnowledgeDomain = z.infer<typeof KnowledgeDomainSchema>