@elevasis/core 0.21.0 → 0.23.0

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

@@ -0,0 +1,145 @@
+import { z } from 'zod'
+import { ModelIdSchema } from './shared'
+import { SystemPathSchema, SystemLifecycleSchema } from './systems'
+import { ActionInvocationSchema } from './actions'
+
+// ---------------------------------------------------------------------------
+// Resources domain
+// ---------------------------------------------------------------------------
+//
+// Resources are governance-only OM descriptors. Runtime code imports these
+// descriptors and attaches executable behavior; it does not re-author identity.
+
+export const ResourceKindSchema = z
+  .enum(['workflow', 'agent', 'integration', 'script'])
+  .meta({ label: 'Resource kind', color: 'orange' })
+export const ResourceGovernanceStatusSchema = z
+  .enum(['active', 'deprecated', 'archived'])
+  .meta({ label: 'Governance status', color: 'teal' })
+export const AgentKindSchema = z
+  .enum(['orchestrator', 'specialist', 'utility', 'platform'])
+  .meta({ label: 'Agent kind', color: 'violet' })
+export const ScriptResourceLanguageSchema = z.enum(['shell', 'sql', 'typescript', 'python']).meta({ label: 'Language' })
+
+export const ResourceIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(255)
+  .regex(/^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*$/, 'Resource IDs must use letters, numbers, -, _, or . separators')
+
+export const EventIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(300)
+  .regex(
+    /^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*:[a-z0-9]+(?:[-._][a-z0-9]+)*$/,
+    'Event IDs must use <owner-id>:<event-key>'
+  )
+
+export const EventKeySchema = ModelIdSchema
+
+export const EventEmissionDescriptorSchema = z.object({
+  eventKey: EventKeySchema,
+  label: z.string().trim().min(1).max(120),
+  payloadSchema: ModelIdSchema.optional(),
+  lifecycle: SystemLifecycleSchema.optional()
+})
+
+export const EventDescriptorSchema = EventEmissionDescriptorSchema.extend({
+  id: EventIdSchema,
+  ownerId: z.union([ResourceIdSchema, ModelIdSchema]),
+  ownerKind: z.enum(['resource', 'entity']).meta({ label: 'Owner kind' })
+})
+
+const ResourceEntryBaseSchema = z.object({
+  /** Canonical resource id; runtime resourceId derives from this value. */
+  id: ResourceIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number().default(0),
+  /** Required single System membership — value is a dot-separated system path (e.g. "sales.lead-gen"). */
+  systemPath: SystemPathSchema.meta({ ref: 'system' }),
+  /** Optional role responsible for maintaining this resource. */
+  ownerRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
+  status: ResourceGovernanceStatusSchema
+})
+
+export const WorkflowResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('workflow'),
+  /** Mirrors WorkflowConfig.actionKey when the runtime workflow has one. */
+  actionKey: z.string().trim().min(1).max(255).optional(),
+  emits: z.array(EventEmissionDescriptorSchema).optional()
+})
+
+export const AgentResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('agent'),
+  /** Mirrors code-side AgentConfig.kind. */
+  agentKind: AgentKindSchema,
+  /** Role this agent embodies, if any. */
+  actsAsRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
+  /** Mirrors AgentConfig.sessionCapable. */
+  sessionCapable: z.boolean(),
+  /** Broad/composite callable entry points orchestrated by this agent. */
+  invocations: z.array(ActionInvocationSchema).default([]),
+  emits: z.array(EventEmissionDescriptorSchema).optional()
+})
+
+export const IntegrationResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('integration'),
+  provider: z.string().trim().min(1).max(100)
+})
+
+export const ScriptResourceSourceSchema = z.union([
+  z.string().trim().min(1).max(50_000),
+  z.object({
+    file: z.string().trim().min(1).max(500)
+  })
+])
+
+export const ScriptResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('script'),
+  language: ScriptResourceLanguageSchema,
+  source: ScriptResourceSourceSchema
+})
+
+export const ResourceEntrySchema = z.discriminatedUnion('kind', [
+  WorkflowResourceEntrySchema,
+  AgentResourceEntrySchema,
+  IntegrationResourceEntrySchema,
+  ScriptResourceEntrySchema
+])
+
+export const ResourcesDomainSchema = z
+  .record(z.string(), ResourceEntrySchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each resource entry id must match its map key'
+  })
+  .default({})
+
+export const DEFAULT_ORGANIZATION_MODEL_RESOURCES: z.infer<typeof ResourcesDomainSchema> = {}
+
+export function defineResource<const TResource extends ResourceEntry>(resource: TResource): TResource {
+  return ResourceEntrySchema.parse(resource) as TResource
+}
+
+export function defineResources<const TResources extends Record<string, ResourceEntry>>(
+  resources: TResources
+): TResources {
+  return Object.fromEntries(
+    Object.entries(resources).map(([key, resource]) => [key, ResourceEntrySchema.parse(resource)])
+  ) as TResources
+}
+
+export type ResourceId = z.infer<typeof ResourceIdSchema>
+export type ResourceKind = z.infer<typeof ResourceKindSchema>
+export type ResourceGovernanceStatus = z.infer<typeof ResourceGovernanceStatusSchema>
+export type ResourceAgentKind = z.infer<typeof AgentKindSchema>
+export type ScriptResourceLanguage = z.infer<typeof ScriptResourceLanguageSchema>
+export type ScriptResourceSource = z.infer<typeof ScriptResourceSourceSchema>
+export type WorkflowResourceEntry = z.infer<typeof WorkflowResourceEntrySchema>
+export type AgentResourceEntry = z.infer<typeof AgentResourceEntrySchema>
+export type IntegrationResourceEntry = z.infer<typeof IntegrationResourceEntrySchema>
+export type ScriptResourceEntry = z.infer<typeof ScriptResourceEntrySchema>
+export type ResourceEntry = z.infer<typeof ResourceEntrySchema>
+export type ResourcesDomain = z.infer<typeof ResourcesDomainSchema>

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

@@ -1,55 +1,96 @@
-import { z } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Role schema — one entry per distinct role in the organization's chart.
-// Inspired by the EOS Accountability Chart but uses plain-language field names
-// throughout. No EOS jargon: "title" (not seatTitle), "responsibilities"
-// (not accountabilities), "reportsToId", "heldBy".
-//
-// Cross-reference: `reportsToId` (when present) must resolve to another
-// `roles[].id` in the same collection. Enforcement is via
-// `OrganizationModelSchema.superRefine()` — not at the individual schema level.
-// Cycle detection is NOT enforced (known limitation; document if needed).
-// ---------------------------------------------------------------------------
-
-export const RoleSchema = z.object({
-  /** Stable unique identifier for the role (e.g. "role-ceo", "role-head-of-sales"). */
-  id: z.string().trim().min(1).max(100),
-  /** Human-readable title shown to agents and in UI (e.g. "CEO", "Head of Sales"). */
-  title: z.string().trim().min(1).max(200),
-  /**
-   * List of responsibilities this role owns — plain-language descriptions of
-   * what the person in this role is accountable for delivering.
-   * Defaults to empty array so minimal role definitions stay concise.
-   */
-  responsibilities: z.array(z.string().trim().max(500)).default([]),
-  /**
-   * Optional: ID of another role this role reports to.
-   * When present, must reference another `roles[].id` in the same organization.
-   * Cross-reference enforced in `OrganizationModelSchema.superRefine()`.
-   * Absence indicates a top-level role (no reporting line).
-   */
-  reportsToId: z.string().trim().min(1).max(100).optional(),
-  /**
-   * Optional: name or email of the person currently holding this role.
-   * Free-form string — supports "Alice Johnson", "alice@example.com", or
-   * any human-readable identifier. Not validated against any user registry.
-   */
-  heldBy: z.string().trim().max(200).optional()
-})
-
-// ---------------------------------------------------------------------------
-// Roles domain schema — a collection of roles.
-// ---------------------------------------------------------------------------
-
-export const RolesDomainSchema = z.object({
-  roles: z.array(RoleSchema).default([])
-})
-
-// ---------------------------------------------------------------------------
-// Seed — empty by default; adapters populate with real role definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_ROLES: z.infer<typeof RolesDomainSchema> = {
-  roles: []
-}
+import { z } from 'zod'
+import { ResourceIdSchema } from './resources'
+import { ModelIdSchema } from './shared'
+import { SystemIdSchema } from './systems'
+
+// ---------------------------------------------------------------------------
+// Role schema - one entry per distinct role in the organization's chart.
+// Inspired by the EOS Accountability Chart but uses plain-language field names
+// throughout. No EOS jargon: "title" (not seatTitle), "responsibilities"
+// (not accountabilities), "reportsToId", "heldBy".
+//
+// Cross-reference enforcement lives in `OrganizationModelSchema.superRefine()`:
+// `reportsToId` must resolve to another Role, `responsibleFor` entries must
+// resolve to Systems, and agent holders must resolve to Agent Resources.
+// Role hierarchy cycle detection is also enforced at the model level.
+// ---------------------------------------------------------------------------
+
+export const RoleIdSchema = ModelIdSchema
+
+export const HumanRoleHolderSchema = z.object({
+  kind: z.literal('human'),
+  userId: z.string().trim().min(1).max(200)
+})
+
+export const AgentRoleHolderSchema = z.object({
+  kind: z.literal('agent'),
+  agentId: ResourceIdSchema.meta({ ref: 'resource' })
+})
+
+export const TeamRoleHolderSchema = z.object({
+  kind: z.literal('team'),
+  memberIds: z.array(z.string().trim().min(1).max(200)).min(1)
+})
+
+export const RoleHolderSchema = z.discriminatedUnion('kind', [
+  HumanRoleHolderSchema,
+  AgentRoleHolderSchema,
+  TeamRoleHolderSchema
+])
+
+export const RoleHoldersSchema = z.union([RoleHolderSchema, z.array(RoleHolderSchema).min(1)])
+
+export const RoleSchema = z.object({
+  /** Stable unique identifier for the role (e.g. "role-ceo", "role-head-of-sales"). */
+  id: RoleIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  /** Human-readable title shown to agents and in UI (e.g. "CEO", "Head of Sales"). */
+  title: z.string().trim().min(1).max(200),
+  /**
+   * List of responsibilities this role owns - plain-language descriptions of
+   * what the person in this role is accountable for delivering.
+   * Defaults to empty array so minimal role definitions stay concise.
+   */
+  responsibilities: z.array(z.string().trim().max(500)).default([]),
+  /**
+   * Optional: ID of another role this role reports to.
+   * When present, must reference another `roles[].id` in the same organization.
+   */
+  reportsToId: RoleIdSchema.meta({ ref: 'role' }).optional(),
+  /**
+   * Optional: human, agent, or team holder currently filling this role.
+   * Agent holders reference OM Resource IDs and are validated at the model level.
+   */
+  heldBy: RoleHoldersSchema.optional(),
+  /**
+   * Optional Systems this role is accountable for.
+   * Cross-reference enforced in `OrganizationModelSchema.superRefine()`.
+   */
+  responsibleFor: z.array(SystemIdSchema.meta({ ref: 'system' })).optional()
+})
+
+// ---------------------------------------------------------------------------
+// Roles domain schema - a collection of roles.
+// ---------------------------------------------------------------------------
+
+export const RolesDomainSchema = z
+  .record(z.string(), RoleSchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each role entry id must match its map key'
+  })
+  .default({})
+
+// ---------------------------------------------------------------------------
+// Seed - empty by default; adapters populate with real role definitions.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ORGANIZATION_MODEL_ROLES: z.infer<typeof RolesDomainSchema> = {}
+
+export type RoleId = z.infer<typeof RoleIdSchema>
+export type HumanRoleHolder = z.infer<typeof HumanRoleHolderSchema>
+export type AgentRoleHolder = z.infer<typeof AgentRoleHolderSchema>
+export type TeamRoleHolder = z.infer<typeof TeamRoleHolderSchema>
+export type RoleHolder = z.infer<typeof RoleHolderSchema>
+export type Role = z.infer<typeof RoleSchema>
+export type RolesDomain = z.infer<typeof RolesDomainSchema>

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

@@ -1,6 +1,16 @@
 import { z } from 'zod'
 import { DescriptionSchema, DisplayMetadataSchema, ModelIdSchema, ReferenceIdsSchema } from './shared'
 
+export { LEAD_GEN_STAGE_CATALOG, type LeadGenStageCatalogEntry } from '../catalogs/lead-gen'
+
+// Phase 4 cut: OrganizationModelSalesSchema and DEFAULT_ORGANIZATION_MODEL_SALES removed.
+// Pipeline/stage data moved into system.content as (schema:pipeline) and (schema:stage)
+// content nodes on the owning system (e.g. sales.crm). Use getAllPipelines() /
+// getStagesInPipeline() from migration-helpers to read pipeline data portably.
+//
+// SalesStageSemanticClassSchema, SalesStageSchema, SalesPipelineSchema are retained
+// below as TypeScript types used by CRM business logic and the Stateful pipeline definitions.
+
 export const SalesStageSemanticClassSchema = z.enum(['open', 'active', 'nurturing', 'closed_won', 'closed_lost'])
 
 export const SalesStageSchema = DisplayMetadataSchema.extend({
@@ -19,80 +29,6 @@ export const SalesPipelineSchema = z.object({
   stages: z.array(SalesStageSchema).min(1)
 })
 
-export const OrganizationModelSalesSchema = z.object({
-  entityId: ModelIdSchema,
-  defaultPipelineId: ModelIdSchema,
-  pipelines: z.array(SalesPipelineSchema).min(1)
-})
-
-export const DEFAULT_ORGANIZATION_MODEL_SALES: z.infer<typeof OrganizationModelSalesSchema> = {
-  entityId: 'crm.deal',
-  defaultPipelineId: 'default',
-  pipelines: [
-    {
-      id: 'default',
-      label: 'Default Pipeline',
-      entityId: 'crm.deal',
-      stages: [
-        {
-          id: 'interested',
-          label: 'Interested',
-          color: 'blue',
-          order: 1,
-          semanticClass: 'open',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'proposal',
-          label: 'Proposal',
-          color: 'yellow',
-          order: 2,
-          semanticClass: 'active',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closing',
-          label: 'Closing',
-          color: 'lime',
-          order: 3,
-          semanticClass: 'active',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closed_won',
-          label: 'Closed Won',
-          color: 'green',
-          order: 4,
-          semanticClass: 'closed_won',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'closed_lost',
-          label: 'Closed Lost',
-          color: 'red',
-          order: 5,
-          semanticClass: 'closed_lost',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        },
-        {
-          id: 'nurturing',
-          label: 'Nurturing',
-          color: 'grape',
-          order: 6,
-          semanticClass: 'nurturing',
-          surfaceIds: ['crm.pipeline'],
-          resourceIds: []
-        }
-      ]
-    }
-  ]
-}
-
 // ============================================================================
 // Lead-Gen Stateful Pipeline Definitions (Decision N8, Wave 4)
 //
@@ -442,148 +378,3 @@ export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefin
   'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
   'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
 }
-
-// ============================================================================
-// Lead-Gen Stage Catalog (OM Spine processing-state model)
-//
-// Canonical set of processing stage keys for acq_companies.processing_state and
-// acq_contacts.processing_state. These keys coordinate build templates, workflow
-// factory validation, API filters, and UI progress projections.
-//
-// State is sparse: absent keys mean "not attempted"; present keys hold terminal
-// status entries such as success, no_result, skipped, or error.
-//
-// Historical sources:
-//   ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE  → personalized, uploaded, interested,
-//                                          discovered, verified
-//   ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE → populated, extracted, qualified
-//   Design plan hint (lead-gen-domain-cleanup.mdx §4) → scraped, enriched
-//
-// ============================================================================
-
-/** One entry in the lead-gen stage catalog. */
-export interface LeadGenStageCatalogEntry {
-  /** Matches the status key written into processing_state jsonb (e.g. 'scraped'). */
-  key: string
-  /** Human-readable label for UI display. */
-  label: string
-  /** Short description of what this stage represents. */
-  description: string
-  /** Canonical pipeline order for UI sorting. Lower = earlier in the funnel. */
-  order: number
-  /** Which entity's processing_state jsonb carries this stage status. */
-  entity: 'company' | 'contact'
-  /** Additional entities allowed to write/read this processing_state key. */
-  additionalEntities?: Array<'company' | 'contact'>
-  /**
-   * Optional read-side override for Records views when a company-scoped step
-   * produces records on a different entity.
-   */
-  recordEntity?: 'company' | 'contact'
-  /** Stage key to read from recordEntity.processing_state for Records views. */
-  recordStageKey?: string
-}
-
-/**
- * Canonical lead-gen processing stage catalog.
- * Keys are the stage names written by workflow steps into processing_state jsonb.
- *
- * Ordered roughly by pipeline progression (prospecting → outreach → qualification).
- */
-export const LEAD_GEN_STAGE_CATALOG: Record<string, LeadGenStageCatalogEntry> = {
-  // Prospecting — company population
-  scraped: {
-    key: 'scraped',
-    label: 'Scraped',
-    description: 'Company was scraped from a source directory (Apify actor run).',
-    order: 1,
-    entity: 'company'
-  },
-  populated: {
-    key: 'populated',
-    label: 'Companies found',
-    description: 'Companies have been found and added to the lead-gen list.',
-    order: 2,
-    entity: 'company'
-  },
-  crawled: {
-    key: 'crawled',
-    label: 'Websites crawled',
-    description:
-      'Company websites have been crawled (e.g. via Apify) and raw page content stored for downstream LLM analysis.',
-    order: 2.5,
-    entity: 'company'
-  },
-  extracted: {
-    key: 'extracted',
-    label: 'Websites analyzed',
-    description: 'Company websites have been analyzed for business signals.',
-    order: 3,
-    entity: 'company'
-  },
-  enriched: {
-    key: 'enriched',
-    label: 'Enriched',
-    description: 'Company or contact enriched with third-party data (e.g. Tomba, Anymailfinder).',
-    order: 4,
-    entity: 'company'
-  },
-  'decision-makers-enriched': {
-    key: 'decision-makers-enriched',
-    label: 'Decision-makers found',
-    description: 'Decision-maker contacts discovered and attached to a qualified company.',
-    order: 6,
-    entity: 'company',
-    recordEntity: 'contact',
-    recordStageKey: 'discovered'
-  },
-
-  // Prospecting — contact discovery
-  discovered: {
-    key: 'discovered',
-    label: 'Decision-makers found',
-    description: 'Decision-maker contact details have been found.',
-    order: 5,
-    entity: 'contact'
-  },
-  verified: {
-    key: 'verified',
-    label: 'Emails verified',
-    description: 'Contact email addresses have been checked for deliverability.',
-    order: 7,
-    entity: 'contact'
-  },
-
-  // Qualification
-  qualified: {
-    key: 'qualified',
-    label: 'Companies qualified',
-    description: 'Companies have been scored against the qualification criteria.',
-    order: 8,
-    entity: 'company'
-  },
-
-  // Outreach
-  personalized: {
-    key: 'personalized',
-    label: 'Personalized',
-    description: 'Outreach message personalized for the contact (Instantly personalization workflow).',
-    order: 9,
-    entity: 'contact'
-  },
-  uploaded: {
-    key: 'uploaded',
-    label: 'Reviewed and exported',
-    description: 'Approved records have been reviewed and exported for handoff.',
-    order: 10,
-    entity: 'company',
-    additionalEntities: ['contact']
-  },
-  interested: {
-    key: 'interested',
-    label: 'Interested',
-    description: 'Contact replied with a positive signal (Instantly reply-handler transition).',
-    order: 11,
-    entity: 'contact'
-  }
-}

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

@@ -1,63 +1,63 @@
 import { z } from 'zod'
 import { OrganizationModelIconTokenSchema } from '../icons'
-
-export const ModelIdSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(100)
-  .regex(/^[a-z0-9]+(?:[-._][a-z0-9]+)*$/, 'IDs must be lowercase and use -, _, or . separators')
-
-export const LabelSchema = z.string().trim().min(1).max(120)
+
+export const ModelIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(100)
+  .regex(/^[a-z0-9]+(?:[-._][a-z0-9]+)*$/, 'IDs must be lowercase and use -, _, or . separators')
+
+export const LabelSchema = z.string().trim().min(1).max(120)
 export const DescriptionSchema = z.string().trim().min(1).max(2000)
 export const ColorTokenSchema = z.string().trim().min(1).max(50)
 export const IconNameSchema = OrganizationModelIconTokenSchema
 export const PathSchema = z.string().trim().startsWith('/').max(300)
-
-export const ReferenceIdsSchema = z.array(ModelIdSchema).default([])
-
-export const DisplayMetadataSchema = z.object({
-  label: LabelSchema,
-  description: DescriptionSchema.optional(),
-  color: ColorTokenSchema.optional(),
-  icon: IconNameSchema.optional()
-})
-
-// ---------------------------------------------------------------------------
-// TechStack subsection — optional extension on a ResourceMapping entry that
-// captures external-SaaS integration metadata: which platform, its purpose,
-// credential health, and whether it is the system of record for its domain.
-// Backward-compatible: existing entries without this key parse cleanly.
-// ---------------------------------------------------------------------------
-
-export const TechStackEntrySchema = z.object({
-  /** Name of the external platform (e.g. "HubSpot", "Stripe", "Notion"). */
-  platform: z.string().trim().min(1).max(200),
-  /** Free-form description of what this integration is used for. */
-  purpose: z.string().trim().min(1).max(500),
-  /**
-   * Health of the credential backing this integration.
-   * - configured: credential present and valid
-   * - pending: not yet set up
-   * - expired: credential existed but has lapsed
-   * - missing: expected but not present
-   */
-  credentialStatus: z.enum(['configured', 'pending', 'expired', 'missing']),
-  /**
-   * Whether this integration is the primary system of record for its domain
-   * (e.g. HubSpot is SoR for contacts). Defaults to false.
-   */
-  isSystemOfRecord: z.boolean().default(false)
-})
-
-export const ResourceMappingSchema = DisplayMetadataSchema.extend({
-  id: ModelIdSchema,
-  resourceId: z.string().trim().min(1).max(255),
-  resourceType: z.enum(['workflow', 'agent', 'trigger', 'integration', 'external', 'human_checkpoint']),
-  featureIds: ReferenceIdsSchema,
-  entityIds: ReferenceIdsSchema,
-  surfaceIds: ReferenceIdsSchema,
-  capabilityIds: ReferenceIdsSchema,
-  /** Optional tech-stack metadata for external-SaaS integrations. */
-  techStack: TechStackEntrySchema.optional()
-})
+
+export const ReferenceIdsSchema = z.array(ModelIdSchema).default([])
+
+export const DisplayMetadataSchema = z.object({
+  label: LabelSchema,
+  description: DescriptionSchema.optional(),
+  color: ColorTokenSchema.optional(),
+  icon: IconNameSchema.optional()
+})
+
+// ---------------------------------------------------------------------------
+// TechStack subsection — optional extension on a ResourceMapping entry that
+// captures external-SaaS integration metadata: which platform, its purpose,
+// credential health, and whether it is the system of record for its domain.
+// Backward-compatible: existing entries without this key parse cleanly.
+// ---------------------------------------------------------------------------
+
+export const TechStackEntrySchema = z.object({
+  /** Name of the external platform (e.g. "HubSpot", "Stripe", "Notion"). */
+  platform: z.string().trim().min(1).max(200),
+  /** Free-form description of what this integration is used for. */
+  purpose: z.string().trim().min(1).max(500),
+  /**
+   * Health of the credential backing this integration.
+   * - configured: credential present and valid
+   * - pending: not yet set up
+   * - expired: credential existed but has lapsed
+   * - missing: expected but not present
+   */
+  credentialStatus: z.enum(['configured', 'pending', 'expired', 'missing']),
+  /**
+   * Whether this integration is the primary system of record for its domain
+   * (e.g. HubSpot is SoR for contacts). Defaults to false.
+   */
+  isSystemOfRecord: z.boolean().default(false)
+})
+
+export const ResourceMappingSchema = DisplayMetadataSchema.extend({
+  id: ModelIdSchema,
+  resourceId: z.string().trim().min(1).max(255),
+  resourceType: z.enum(['workflow', 'agent', 'trigger', 'integration', 'external', 'human_checkpoint']),
+  systemIds: ReferenceIdsSchema,
+  entityIds: ReferenceIdsSchema,
+  surfaceIds: ReferenceIdsSchema,
+  actionIds: ReferenceIdsSchema,
+  /** Optional tech-stack metadata for external-SaaS integrations. */
+  techStack: TechStackEntrySchema.optional()
+})