@elevasis/core 0.37.0 → 0.38.0

package/src/_gen/__tests__/__snapshots__/system-interface-capabilities.md.snap

@@ -0,0 +1,47 @@
+<!-- @generated by scripts/monorepo/generate-scaffold-contracts.js -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+# System Interface Capabilities
+
+This catalog is generated from `SYSTEM_INTERFACE_PROFILES` and the derived-readiness checks in `packages/core/src/business/acquisition/ontology-validation.ts`.
+
+System Interface profiles are a closed platform adoption handshake. Tenant custom Systems should extend behavior through workflows/operations plus ontology, resources, and topology instead of declaring custom `apiInterface.readinessProfile` values.
+
+| Profile | Required System path | Interface key |
+| --- | --- | --- |
+| `sales.lead-gen.api` | `sales.lead-gen` | `api` |
+| `sales.crm.api` | `sales.crm` | `api` |
+| `sales.lead-gen.crm-handoff` | `sales.lead-gen` | `crm-handoff` |
+
+## `sales.lead-gen.api`
+
+- Required System path: `sales.lead-gen`
+- Interface key: `api`
+- Derived-readiness requirements:
+  - System Interface marker must be active and scope at least one active `sales.lead-gen` Resource.
+  - Object types: `sales.lead-gen:object/list`, `sales.lead-gen:object/company`, `sales.lead-gen:object/contact`.
+  - Scoped Resource `ontology.reads` bindings for each required object type.
+  - Catalog types with entries: `sales.lead-gen:catalog/build-template`, `sales.lead-gen:catalog/company-stage`, `sales.lead-gen:catalog/contact-stage`, and derived `sales.lead-gen:catalog/lead-gen.stage-catalog`.
+  - Scoped Resource `ontology.usesCatalogs` bindings for each required catalog.
+  - A lead-gen template-step catalog owned by `sales.lead-gen` whose `appliesTo` value is `sales.lead-gen:object/list`, plus a scoped `ontology.usesCatalogs` binding for it.
+
+## `sales.crm.api`
+
+- Required System path: `sales.crm`
+- Interface key: `api`
+- Derived-readiness requirements:
+  - System Interface marker must be active and scope at least one active `sales.crm` Resource.
+  - Catalog type with entries: `sales.crm:catalog/crm.pipeline`.
+  - Scoped Resource `ontology.usesCatalogs` binding for `sales.crm:catalog/crm.pipeline`.
+
+## `sales.lead-gen.crm-handoff`
+
+- Required System path: `sales.lead-gen`
+- Interface key: `crm-handoff`
+- Derived-readiness requirements:
+  - Derived handoff readiness is evaluated for `sales.lead-gen/crm-handoff`; it is not authored as a separate custom tenant API surface.
+  - Lead-gen API readiness requirements must pass for `sales.lead-gen/api`.
+  - CRM pipeline catalog must exist with entries: `sales.crm:catalog/crm.pipeline`. Foreign ownership is allowed because the provider is `sales.crm/api`.
+  - Derived scoped resources are active `sales.lead-gen` Resources whose `ontology.usesCatalogs` includes `sales.crm:catalog/crm.pipeline`.
+  - Provider readiness must pass for `sales.crm/api`.
+  - Topology must include a scoped `systemInterfaceGrant` relationship from consumer `sales.lead-gen/crm-handoff` to provider `sales.crm/api`.

package/src/_gen/__tests__/scaffold-contracts.test.ts

@@ -16,8 +16,17 @@ import { describe, it, expect } from 'vitest'
 /** Monorepo root relative to packages/core/src/_gen/__tests__/ */
 const ROOT = resolve(import.meta.dirname, '..', '..', '..', '..', '..')
 
-const OUTPUT_PATH = resolve(ROOT, 'packages/core/src/reference/_generated/contracts.md')
-const SNAPSHOT_PATH = resolve(import.meta.dirname, '__snapshots__', 'contracts.md.snap')
+const OUTPUT_PATH = resolve(ROOT, 'packages/core/src/reference/_generated/contracts.md')
+const SNAPSHOT_PATH = resolve(import.meta.dirname, '__snapshots__', 'contracts.md.snap')
+const CAPABILITY_CATALOG_OUTPUT_PATH = resolve(
+  ROOT,
+  'packages/core/src/reference/_generated/system-interface-capabilities.md'
+)
+const CAPABILITY_CATALOG_SNAPSHOT_PATH = resolve(
+  import.meta.dirname,
+  '__snapshots__',
+  'system-interface-capabilities.md.snap'
+)
 
 function normalizeSnapshotContent(content: string) {
   return content
@@ -29,7 +38,7 @@ function normalizeSnapshotContent(content: string) {
 }
 
 describe('scaffold-contracts generator', () => {
-  it('output file exists and has content', () => {
+  it('output file exists and has content', () => {
     // The generator must have been run (either manually or by CI gen step).
     // This test validates the committed artifact — it does NOT re-run the generator
     // so the test suite stays fast and deterministic.
@@ -43,8 +52,22 @@ describe('scaffold-contracts generator', () => {
       )
     }
 
-    expect(content.length).toBeGreaterThan(0)
-  })
+    expect(content.length).toBeGreaterThan(0)
+  })
+
+  it('capability catalog output file exists and has content', () => {
+    let content: string
+    try {
+      content = readFileSync(CAPABILITY_CATALOG_OUTPUT_PATH, 'utf8')
+    } catch {
+      throw new Error(
+        `Generated file not found: ${CAPABILITY_CATALOG_OUTPUT_PATH}\n` +
+          `Run "pnpm scaffold:generate" or "node scripts/monorepo/generate-scaffold-contracts.js" first.`
+      )
+    }
+
+    expect(content.length).toBeGreaterThan(0)
+  })
 
   it('output file matches stored snapshot', () => {
     let content: string
@@ -59,6 +82,22 @@ describe('scaffold-contracts generator', () => {
 
     const snapshot = readFileSync(SNAPSHOT_PATH, 'utf8')
 
-    expect(normalizeSnapshotContent(content)).toBe(normalizeSnapshotContent(snapshot))
-  })
-})
+    expect(normalizeSnapshotContent(content)).toBe(normalizeSnapshotContent(snapshot))
+  })
+
+  it('capability catalog output file matches stored snapshot', () => {
+    let content: string
+    try {
+      content = readFileSync(CAPABILITY_CATALOG_OUTPUT_PATH, 'utf8')
+    } catch {
+      throw new Error(
+        `Generated file not found: ${CAPABILITY_CATALOG_OUTPUT_PATH}\n` +
+          `Run "pnpm scaffold:generate" first to produce the artifact before snapshotting.`
+      )
+    }
+
+    const snapshot = readFileSync(CAPABILITY_CATALOG_SNAPSHOT_PATH, 'utf8')
+
+    expect(normalizeSnapshotContent(content)).toBe(normalizeSnapshotContent(snapshot))
+  })
+})

package/src/business/acquisition/api-schemas.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { type CrmPriorityRuleConfig, type StatefulPipelineDefinition } from '../../organization-model/domains/sales'
+import { SYSTEM_INTERFACE_PROFILES } from '../../organization-model/domains/systems'
 
 // Inline fixture for lead-gen pipeline stage/state validation tests.
 // The canonical constants live in @repo/elevasis-core; @repo/core cannot depend on it.
@@ -503,6 +504,14 @@ describe('DealStageSchema', () => {
 // ---------------------------------------------------------------------------
 
 describe('business ontology validation contracts', () => {
+  it('derives compatibility interface constants from the canonical profile registry', () => {
+    expect(SYSTEM_INTERFACE_PROFILES).toEqual([
+      LEAD_GEN_API_INTERFACE,
+      CRM_API_INTERFACE,
+      LEAD_GEN_CRM_HANDOFF_INTERFACE
+    ])
+  })
+
   it('computes structured readiness for a ready lead-gen API interface without CRM', () => {
     const model = buildMinimalLeadGenModel()
     const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
@@ -655,12 +664,15 @@ describe('business ontology validation contracts', () => {
     const model = buildMinimalLeadGenModel()
     const apiInterface = model.systems.sales?.systems?.['lead-gen']?.apiInterface
     if (apiInterface === undefined) throw new Error('Minimal fixture is missing lead-gen API interface')
-    apiInterface.readinessProfile = 'sales.lead-gen.unknown'
+    ;(apiInterface as { readinessProfile?: string }).readinessProfile = 'sales.lead-gen.unknown'
 
     const readiness = computeInterfaceReadiness(model, LEAD_GEN_API_INTERFACE)
 
     expect(readiness.ready).toBe(false)
     expect(readiness.issues).toMatchObject([{ family: 'SYSTEM_INTERFACE_INVALID', code: 'unknown-readiness-profile' }])
+    expect(readiness.issues[0]?.message).toContain('Supported profiles: "sales.lead-gen.api", "sales.crm.api", "sales.lead-gen.crm-handoff"')
+    expect(readiness.issues[0]?.message).toContain('Custom Systems should not declare apiInterface')
+    expect(readiness.issues[0]?.message).toContain('workflows/operations plus ontology, resources, and topology')
   })
 
   it('lead-gen-to-CRM handoff validation fails when the scoped topology grant is absent', () => {

package/src/business/acquisition/ontology-validation.ts

@@ -10,6 +10,10 @@ import {
 } from '../../organization-model/ontology'
 import type { OrganizationModel } from '../../organization-model/types'
 import type { ResourceEntry } from '../../organization-model/domains/resources'
+import {
+  SYSTEM_INTERFACE_PROFILES,
+  SYSTEM_INTERFACE_READINESS_PROFILES
+} from '../../organization-model/domains/systems'
 import type { OmTopologyRelationship } from '../../organization-model/domains/topology'
 import {
   type LeadGenStageCatalogEntry,
@@ -18,23 +22,11 @@ import {
 import { getSystem } from '../../organization-model/helpers'
 import { getLeadGenStageCatalog } from '../../organization-model/migration-helpers'
 
-export const LEAD_GEN_API_INTERFACE = {
-  systemPath: 'sales.lead-gen',
-  interfaceKey: 'api',
-  readinessProfile: 'sales.lead-gen.api'
-} as const
+export const LEAD_GEN_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[0]
 
-export const CRM_API_INTERFACE = {
-  systemPath: 'sales.crm',
-  interfaceKey: 'api',
-  readinessProfile: 'sales.crm.api'
-} as const
+export const CRM_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[1]
 
-export const LEAD_GEN_CRM_HANDOFF_INTERFACE = {
-  systemPath: 'sales.lead-gen',
-  interfaceKey: 'crm-handoff',
-  readinessProfile: 'sales.lead-gen.crm-handoff'
-} as const
+export const LEAD_GEN_CRM_HANDOFF_INTERFACE = SYSTEM_INTERFACE_PROFILES[2]
 
 const LEAD_GEN_API_READINESS_LABEL = LEAD_GEN_API_INTERFACE.readinessProfile
 const CRM_API_READINESS_LABEL = CRM_API_INTERFACE.readinessProfile
@@ -215,6 +207,10 @@ function formatInterfaceReadinessFailure(result: SystemInterfaceReadinessResult)
   return `${identity} readiness failed${result.readinessProfile ? ` (${result.readinessProfile})` : ''}: ${issueSummary}`
 }
 
+function formatSupportedReadinessProfiles(): string {
+  return SYSTEM_INTERFACE_READINESS_PROFILES.map((profile) => `"${profile}"`).join(', ')
+}
+
 function throwIfInterfaceNotReady(result: SystemInterfaceReadinessResult): void {
   if (result.ready) return
   throw new SystemInterfaceReadinessError(result)
@@ -607,20 +603,15 @@ export function computeInterfaceReadiness(
     )
   }
 
-  const supportedProfiles = [
-    LEAD_GEN_API_INTERFACE.readinessProfile,
-    CRM_API_INTERFACE.readinessProfile,
-    LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile
-  ] as const
   const supportedProfile =
-    readinessProfile !== undefined && supportedProfiles.some((profile) => profile === readinessProfile)
+    readinessProfile !== undefined && SYSTEM_INTERFACE_PROFILES.some((profile) => profile.readinessProfile === readinessProfile)
 
   if (!supportedProfile) {
     addReadinessIssue(
       issues,
       'SYSTEM_INTERFACE_INVALID',
       'unknown-readiness-profile',
-      `System Interface "${formatInterfaceIdentity(request.systemPath, request.interfaceKey)}" references unknown readiness profile "${readinessProfile}".`,
+      `System Interface "${formatInterfaceIdentity(request.systemPath, request.interfaceKey)}" references unknown readiness profile "${readinessProfile}". Supported profiles: ${formatSupportedReadinessProfiles()}. Custom Systems should not declare apiInterface; route custom behavior through workflows/operations plus ontology, resources, and topology.`,
       { path: `${readinessMarkerPath(request)}.readinessProfile`, ref: readinessProfile }
     )
     return {

package/src/organization-model/__tests__/domains/systems.test.ts

@@ -1,14 +1,20 @@
 import { describe, expect, it, vi } from 'vitest'
 import {
   DEFAULT_ORGANIZATION_MODEL_SYSTEMS,
+  SYSTEM_INTERFACE_PROFILES,
   SystemEntrySchema,
   SystemApiInterfaceSchema,
+  SystemInterfaceReadinessProfileSchema,
   SystemInterfaceRefSchema,
   SystemKindSchema,
   SystemStatusSchema,
   SystemsDomainSchema
 } from '../../domains/systems'
-import { resolveOrganizationModel } from '../../resolve'
+import { resolveOrganizationModel } from '../../resolve'
+import type {
+  OrganizationModelSystemApiInterface,
+  OrganizationModelSystemInterfaceReadinessProfile
+} from '../../types'
 
 const VALID_SYSTEM = {
   id: 'sys.lead-gen',
@@ -60,6 +66,32 @@ describe('SystemEntrySchema - positive parse', () => {
     }
   })
 
+  it('accepts only registry-backed readiness profiles', () => {
+    const profileValues = SYSTEM_INTERFACE_PROFILES.map((profile) => profile.readinessProfile)
+
+    for (const readinessProfile of profileValues) {
+      expect(SystemInterfaceReadinessProfileSchema.safeParse(readinessProfile).success).toBe(true)
+    }
+
+    expect(SystemInterfaceReadinessProfileSchema.safeParse('sales.lead-gen.unknown').success).toBe(false)
+    expect(SystemApiInterfaceSchema.safeParse({ readinessProfile: 'sales.lead-gen.unknown' }).success).toBe(false)
+  })
+
+  it('publishes a narrowed System Interface readiness profile type', () => {
+    const acceptedReadinessProfile: OrganizationModelSystemInterfaceReadinessProfile = 'sales.lead-gen.api'
+    const acceptedInterface: OrganizationModelSystemApiInterface = {
+      lifecycle: 'active',
+      readinessProfile: acceptedReadinessProfile,
+      resourceIds: []
+    }
+
+    // @ts-expect-error unsupported profiles are not part of the published readiness profile union.
+    const unsupportedReadinessProfile: OrganizationModelSystemInterfaceReadinessProfile = 'sales.lead-gen.unknown'
+
+    expect(acceptedInterface.readinessProfile).toBe('sales.lead-gen.api')
+    expect(unsupportedReadinessProfile).toBe('sales.lead-gen.unknown')
+  })
+
   it('represents missing and disabled System Interfaces distinctly', () => {
     const missing = SystemEntrySchema.parse(VALID_SYSTEM)
     const disabled = SystemEntrySchema.parse({
@@ -131,6 +163,7 @@ describe('SystemEntrySchema - negative parse', () => {
     expect(SystemApiInterfaceSchema.safeParse({ kind: 'api', lifecycle: 'active' }).success).toBe(false)
     expect(SystemApiInterfaceSchema.safeParse({ lifecycle: 'paused' }).success).toBe(false)
     expect(SystemApiInterfaceSchema.safeParse({ readinessProfile: 'Sales Lead Gen API' }).success).toBe(false)
+    expect(SystemApiInterfaceSchema.safeParse({ readinessProfile: 'sales.lead-gen.unknown' }).success).toBe(false)
     expect(
       SystemInterfaceRefSchema.safeParse({ systemPath: 'sales.lead-gen', interfaceKey: 'api' }).success
     ).toBe(true)

package/src/organization-model/__tests__/schema.test.ts

@@ -7,6 +7,7 @@ import {
   listResolvedOntologyRecords,
   parseOntologyId
 } from '../ontology'
+import { SYSTEM_INTERFACE_PROFILES } from '../domains/systems'
 import { resolveOrganizationModelWithResources } from '../resolve'
 import { OrganizationModelSchema } from '../schema'
 
@@ -236,6 +237,52 @@ describe('retired contract authoring surfaces', () => {
 })
 
 describe('System Interface schema integration', () => {
+  it('accepts every registry-backed System Interface readiness profile', () => {
+    for (const profile of SYSTEM_INTERFACE_PROFILES) {
+      const result = OrganizationModelSchema.safeParse({
+        ...makeMinimalModel({
+          sales: {
+            id: 'sales',
+            order: 10,
+            label: 'Sales',
+            lifecycle: 'active'
+          },
+          [profile.systemPath]: {
+            ...makeSystem(profile.systemPath, `/${profile.systemPath.replaceAll('.', '/')}`),
+            apiInterface: {
+              lifecycle: 'active',
+              readinessProfile: profile.readinessProfile
+            }
+          }
+        })
+      })
+
+      expect(result.success).toBe(true)
+    }
+  })
+
+  it('rejects unsupported System Interface readiness profiles', () => {
+    const messages = getIssueMessages(
+      makeMinimalModel({
+        sales: {
+          id: 'sales',
+          order: 10,
+          label: 'Sales',
+          lifecycle: 'active'
+        },
+        'sales.lead-gen': {
+          ...makeSystem('sales.lead-gen', '/lead-gen/lists'),
+          apiInterface: {
+            lifecycle: 'active',
+            readinessProfile: 'sales.lead-gen.unknown'
+          }
+        }
+      })
+    )
+
+    expect(messages.some((message) => message.includes('Invalid option'))).toBe(true)
+  })
+
   it('accepts a System API Interface scoped to resources from the same System', () => {
     const result = OrganizationModelSchema.safeParse({
       ...makeMinimalModel({

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

@@ -65,15 +65,28 @@ export const SystemInterfaceKeySchema = ModelIdSchema
 export const SystemInterfaceLifecycleSchema = z
   .enum(['draft', 'active', 'disabled', 'deprecated', 'archived'])
   .meta({ label: 'System interface lifecycle', color: 'teal' })
-export const SystemInterfaceReadinessProfileSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(200)
-  .regex(
-    /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*(?:\.[a-z0-9][a-z0-9-]*)?$/,
-    'Readiness profiles must use dotted lowercase identifiers (e.g. "sales.lead-gen.api")'
-  )
+export const SYSTEM_INTERFACE_PROFILES = [
+  {
+    systemPath: 'sales.lead-gen',
+    interfaceKey: 'api',
+    readinessProfile: 'sales.lead-gen.api'
+  },
+  {
+    systemPath: 'sales.crm',
+    interfaceKey: 'api',
+    readinessProfile: 'sales.crm.api'
+  },
+  {
+    systemPath: 'sales.lead-gen',
+    interfaceKey: 'crm-handoff',
+    readinessProfile: 'sales.lead-gen.crm-handoff'
+  }
+] as const
+type SystemInterfaceReadinessProfileValue = (typeof SYSTEM_INTERFACE_PROFILES)[number]['readinessProfile']
+export const SYSTEM_INTERFACE_READINESS_PROFILES = SYSTEM_INTERFACE_PROFILES.map(
+  (profile) => profile.readinessProfile
+) as [SystemInterfaceReadinessProfileValue, ...SystemInterfaceReadinessProfileValue[]]
+export const SystemInterfaceReadinessProfileSchema = z.enum(SYSTEM_INTERFACE_READINESS_PROFILES)
 export const SystemInterfaceResourceScopeSchema = z
   .array(ModelIdSchema)
   .default([])

package/src/organization-model/published.ts

@@ -109,6 +109,8 @@ export {
 } from './domains/goals'
 export {
   DEFAULT_ORGANIZATION_MODEL_SYSTEMS,
+  SYSTEM_INTERFACE_PROFILES,
+  SYSTEM_INTERFACE_READINESS_PROFILES,
   defineSystem,
   defineSystems,
   SystemEntrySchema,

package/src/platform/constants/versions.ts

@@ -1,3 +1,3 @@
 export const VERSION = {
-  CURRENT: '1.12.13'
+  CURRENT: '1.12.14'
 }