@elevasis/core 0.34.1 → 0.35.0

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

@@ -1,11 +1,13 @@
-import { describe, expect, it, vi } from 'vitest'
-import {
-  DEFAULT_ORGANIZATION_MODEL_SYSTEMS,
-  SystemEntrySchema,
-  SystemKindSchema,
-  SystemStatusSchema,
-  SystemsDomainSchema
-} from '../../domains/systems'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  DEFAULT_ORGANIZATION_MODEL_SYSTEMS,
+  SystemEntrySchema,
+  SystemApiInterfaceSchema,
+  SystemInterfaceRefSchema,
+  SystemKindSchema,
+  SystemStatusSchema,
+  SystemsDomainSchema
+} from '../../domains/systems'
 import { resolveOrganizationModel } from '../../resolve'
 
 const VALID_SYSTEM = {
@@ -27,7 +29,7 @@ describe('SystemEntrySchema - positive parse', () => {
     }
   })
 
-  it('accepts all optional governance references when present', () => {
+  it('accepts all optional governance references when present', () => {
     const result = SystemEntrySchema.safeParse({
       ...VALID_SYSTEM,
       responsibleRoleId: 'role.sales-ops',
@@ -35,8 +37,43 @@ describe('SystemEntrySchema - positive parse', () => {
       drivesGoals: ['goal.pipeline-coverage']
     })
 
-    expect(result.success).toBe(true)
-  })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts a thin API System Interface marker with scoped resources', () => {
+    const result = SystemEntrySchema.safeParse({
+      ...VALID_SYSTEM,
+      apiInterface: {
+        lifecycle: 'active',
+        readinessProfile: 'sales.lead-gen.api',
+        resourceIds: ['lead-gen-list-builder']
+      }
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.apiInterface).toEqual({
+        lifecycle: 'active',
+        readinessProfile: 'sales.lead-gen.api',
+        resourceIds: ['lead-gen-list-builder']
+      })
+    }
+  })
+
+  it('represents missing and disabled System Interfaces distinctly', () => {
+    const missing = SystemEntrySchema.parse(VALID_SYSTEM)
+    const disabled = SystemEntrySchema.parse({
+      ...VALID_SYSTEM,
+      apiInterface: {
+        lifecycle: 'disabled',
+        readinessProfile: 'sales.lead-gen.api'
+      }
+    })
+
+    expect(missing.apiInterface).toBeUndefined()
+    expect(disabled.apiInterface?.lifecycle).toBe('disabled')
+    expect(disabled.apiInterface?.resourceIds).toEqual([])
+  })
 
   it('trims id, title, and description', () => {
     const result = SystemEntrySchema.safeParse({
@@ -86,10 +123,19 @@ describe('SystemEntrySchema - negative parse', () => {
     expect(SystemEntrySchema.safeParse({ ...VALID_SYSTEM, status: 'paused' }).success).toBe(false)
   })
 
-  it('rejects IDs that do not match the OM model-id format', () => {
-    expect(SystemEntrySchema.safeParse({ ...VALID_SYSTEM, id: 'Sys Lead Gen' }).success).toBe(false)
-  })
-})
+  it('rejects IDs that do not match the OM model-id format', () => {
+    expect(SystemEntrySchema.safeParse({ ...VALID_SYSTEM, id: 'Sys Lead Gen' }).success).toBe(false)
+  })
+
+  it('rejects malformed System Interface states', () => {
+    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(
+      SystemInterfaceRefSchema.safeParse({ systemPath: 'sales.lead-gen', interfaceKey: 'api' }).success
+    ).toBe(true)
+  })
+})
 
 describe('SystemsDomainSchema', () => {
   it('accepts an empty systems record', () => {

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

@@ -3,6 +3,8 @@ import { ZodError } from 'zod'
 import {
   OmTopologyDomainSchema,
   OmTopologyMetadataSchema,
+  OmTopologySystemInterfaceGrantMetadataSchema,
+  OmTopologySystemInterfaceGrantSchema,
   defineTopology,
   defineTopologyRelationship,
   parseTopologyNodeRef,
@@ -128,6 +130,27 @@ describe('OM topology domain', () => {
     ).toBe(false)
   })
 
+  it('documents scoped System Interface topology grants', () => {
+    const grant = OmTopologySystemInterfaceGrantSchema.parse({
+      consumer: { systemPath: 'sales.lead-gen', interfaceKey: 'api' },
+      provider: { systemPath: 'sales.crm', interfaceKey: 'api' },
+      resourceIds: ['lead-gen-crm-handoff'],
+      ontologyIds: ['sales.crm:object/deal']
+    })
+
+    expect(grant).toEqual({
+      consumer: { systemPath: 'sales.lead-gen', interfaceKey: 'api' },
+      provider: { systemPath: 'sales.crm', interfaceKey: 'api' },
+      resourceIds: ['lead-gen-crm-handoff'],
+      ontologyIds: ['sales.crm:object/deal']
+    })
+    expect(
+      OmTopologySystemInterfaceGrantMetadataSchema.safeParse({
+        systemInterfaceGrant: grant
+      }).success
+    ).toBe(true)
+  })
+
   it('compiles typed resource objects through authoring helpers', () => {
     const relationship = defineTopologyRelationship({
       from: SOURCE_RESOURCE,

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

@@ -187,6 +187,118 @@ describe('domain metadata validation', () => {
   })
 })
 
+describe('retired contract authoring surfaces', () => {
+  it('does not materialize absent System Contracts or Bridge Contracts for existing OMs', () => {
+    const model = OrganizationModelSchema.parse(makeMinimalModel({ dashboard: makeSystem('dashboard', '/') }))
+
+    expect((model.systems.dashboard as Record<string, unknown>).contracts).toBeUndefined()
+    expect((model as Record<string, unknown>).bridgeContracts).toBeUndefined()
+  })
+
+  it('rejects authored System Contracts and top-level Bridge Contracts', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel({
+        sales: { id: 'sales', order: 10, label: 'Sales', lifecycle: 'active' },
+        'sales.lead-gen': {
+          ...makeSystem('sales.lead-gen', '/lead-gen/lists'),
+          contracts: [
+            {
+              id: 'retired.contract',
+              ownerSystemPath: 'sales.lead-gen',
+              provided: []
+            }
+          ]
+        },
+        'sales.crm': {
+          ...makeSystem('sales.crm', '/crm'),
+          contracts: [
+            {
+              id: 'retired.crm.contract',
+              ownerSystemPath: 'sales.crm',
+              provided: []
+            }
+          ]
+        }
+      }),
+      bridgeContracts: [
+        {
+          id: 'retired.bridge',
+          ownerSystemPath: 'sales.lead-gen',
+          consumerSystemPath: 'sales.crm',
+          required: [],
+          provided: []
+        }
+      ]
+    })
+
+    expect(messages.some((message) => message.includes('Unrecognized key'))).toBe(true)
+  })
+})
+
+describe('System Interface schema integration', () => {
+  it('accepts a System API Interface scoped to resources from the same System', () => {
+    const result = OrganizationModelSchema.safeParse({
+      ...makeMinimalModel({
+        'sales.lead-gen': {
+          ...makeSystem('sales.lead-gen', '/lead-gen/lists'),
+          apiInterface: {
+            lifecycle: 'active',
+            readinessProfile: 'sales.lead-gen.api',
+            resourceIds: ['lead-gen-list-builder']
+          }
+        }
+      }),
+      resources: {
+        'lead-gen-list-builder': {
+          id: 'lead-gen-list-builder',
+          order: 10,
+          kind: 'workflow',
+          systemPath: 'sales.lead-gen',
+          status: 'active'
+        }
+      }
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.systems['sales.lead-gen']?.apiInterface).toMatchObject({
+        lifecycle: 'active',
+        readinessProfile: 'sales.lead-gen.api',
+        resourceIds: ['lead-gen-list-builder']
+      })
+    }
+  })
+
+  it('rejects System Interface resource scopes that point at missing or foreign-System resources', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel({
+        'sales.lead-gen': {
+          ...makeSystem('sales.lead-gen', '/lead-gen/lists'),
+          apiInterface: {
+            readinessProfile: 'sales.lead-gen.api',
+            resourceIds: ['missing-resource', 'crm-deal-sync']
+          }
+        },
+        'sales.crm': makeSystem('sales.crm', '/crm')
+      }),
+      resources: {
+        'crm-deal-sync': {
+          id: 'crm-deal-sync',
+          order: 10,
+          kind: 'workflow',
+          systemPath: 'sales.crm',
+          status: 'active'
+        }
+      }
+    })
+
+    expect(messages.some((message) => message.includes('scopes unknown resource "missing-resource"'))).toBe(true)
+    expect(
+      messages.some((message) => message.includes('scopes resource "crm-deal-sync" from system "sales.crm"'))
+    ).toBe(true)
+  })
+})
+
 describe('deployment projection validation', () => {
   it('rejects old deploy governance projections that omit referenced full-model domains', () => {
     const messages = getIssueMessages({

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

@@ -61,6 +61,42 @@ export const SystemUiSchema = z.object({
   order: z.number().int().optional()
 })
 
+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 SystemInterfaceResourceScopeSchema = z
+  .array(ModelIdSchema)
+  .default([])
+
+export const SystemApiInterfaceSchema = z
+  .object({
+    lifecycle: SystemInterfaceLifecycleSchema.default('active'),
+    readinessProfile: SystemInterfaceReadinessProfileSchema.optional(),
+    /**
+     * Resource ids that participate in this API interface. This scopes readiness
+     * derivation without duplicating authored required/provided contract refs.
+     */
+    resourceIds: SystemInterfaceResourceScopeSchema.optional()
+  })
+  .strict()
+
+export const SystemInterfaceRefSchema = z
+  .object({
+    systemPath: SystemPathSchema,
+    interfaceKey: SystemInterfaceKeySchema
+  })
+  .strict()
+
 // ---------------------------------------------------------------------------
 // Recursive SystemEntry schema.
 //
@@ -102,6 +138,7 @@ export interface SystemEntry {
   actions?: { actionId: string; intent: 'exposes' | 'consumes'; invocation?: unknown }[]
   policies?: string[]
   drivesGoals?: string[]
+  apiInterface?: z.infer<typeof SystemApiInterfaceSchema>
   /** @deprecated Use lifecycle. Accepted for one publish cycle. */
   status?: 'active' | 'deprecated' | 'archived'
   path?: string
@@ -155,6 +192,8 @@ export const SystemEntrySchema: ZodType<SystemEntry> = z
       .array(ModelIdSchema.meta({ ref: 'goal' }))
       .default([])
       .optional(),
+    /** Thin API runtime-boundary marker. Readiness is derived from scoped resources and topology. */
+    apiInterface: SystemApiInterfaceSchema.optional(),
     /** @deprecated Use lifecycle. Accepted for one publish cycle. */
     status: SystemStatusSchema.optional(),
     /** @deprecated Use ui.path. Kept for one-cycle Feature compatibility. */
@@ -240,6 +279,11 @@ export type SystemLifecycle = z.infer<typeof SystemLifecycleSchema>
 /** @deprecated Use SystemLifecycle. Accepted for one publish cycle. */
 export type SystemStatus = z.infer<typeof SystemStatusSchema>
 export type SystemLocalConfig = z.infer<typeof SystemConfigSchema>
+export type SystemInterfaceKey = z.infer<typeof SystemInterfaceKeySchema>
+export type SystemInterfaceLifecycle = z.infer<typeof SystemInterfaceLifecycleSchema>
+export type SystemInterfaceReadinessProfile = z.infer<typeof SystemInterfaceReadinessProfileSchema>
+export type SystemApiInterface = z.infer<typeof SystemApiInterfaceSchema>
+export type SystemInterfaceRef = z.infer<typeof SystemInterfaceRefSchema>
 // SystemEntry is declared as an explicit interface above the schema (required for
 // recursive z.lazy() type inference). Re-export omitted — the interface IS the type.
 export type SystemsDomain = z.infer<typeof SystemsDomainSchema>

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

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import { OntologyIdSchema, parseOntologyId } from '../ontology'
-import { JsonValueSchema, SystemPathSchema } from './systems'
+import { JsonValueSchema, SystemInterfaceRefSchema, SystemPathSchema } from './systems'
 import { ModelIdSchema } from './shared'
 import { ResourceIdSchema, type ResourceEntry } from './resources'
 
@@ -74,6 +74,21 @@ export const OmTopologyMetadataSchema = z
     visit(metadata, [])
   })
 
+export const OmTopologySystemInterfaceGrantSchema = z
+  .object({
+    consumer: SystemInterfaceRefSchema,
+    provider: SystemInterfaceRefSchema,
+    resourceIds: z.array(ResourceIdSchema).default([]),
+    ontologyIds: z.array(OntologyIdSchema).default([])
+  })
+  .strict()
+
+export const OmTopologySystemInterfaceGrantMetadataSchema = z
+  .object({
+    systemInterfaceGrant: OmTopologySystemInterfaceGrantSchema
+  })
+  .strict()
+
 export const OmTopologyRelationshipSchema = z.object({
   from: OmTopologyNodeRefSchema,
   kind: OmTopologyRelationshipKindSchema,
@@ -99,6 +114,8 @@ export type OmTopologyNodeKind = z.infer<typeof OmTopologyNodeKindSchema>
 export type OmTopologyRelationshipKind = z.infer<typeof OmTopologyRelationshipKindSchema>
 export type OmTopologyNodeRef = z.infer<typeof OmTopologyNodeRefSchema>
 export type OmTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
+export type OmTopologySystemInterfaceGrant = z.infer<typeof OmTopologySystemInterfaceGrantSchema>
+export type OmTopologySystemInterfaceGrantMetadata = z.infer<typeof OmTopologySystemInterfaceGrantMetadataSchema>
 export type OmTopologyRelationship = z.infer<typeof OmTopologyRelationshipSchema>
 export type OmTopologyDomain = z.infer<typeof OmTopologyDomainSchema>
 

package/src/organization-model/published.ts

@@ -29,7 +29,11 @@ export {
   OrganizationModelDomainMetadataSchema,
   OrganizationModelSchema
 } from './schema'
-export { NodeIdPathSchema, NodeIdStringSchema, UiPositionSchema } from './domains/systems'
+export {
+  NodeIdPathSchema,
+  NodeIdStringSchema,
+  UiPositionSchema
+} from './domains/systems'
 export { LinkSchema } from './graph/link'
 export { IconNameSchema, TechStackEntrySchema } from './domains/shared'
 export {
@@ -113,6 +117,11 @@ export {
   defineSystems,
   SystemEntrySchema,
   SystemIdSchema,
+  SystemInterfaceKeySchema,
+  SystemInterfaceLifecycleSchema,
+  SystemInterfaceReadinessProfileSchema,
+  SystemInterfaceRefSchema,
+  SystemApiInterfaceSchema,
   SystemKindSchema,
   SystemLifecycleSchema,
   SystemPathSchema,
@@ -158,6 +167,8 @@ export {
   OmTopologyNodeRefSchema,
   OmTopologyRelationshipKindSchema,
   OmTopologyRelationshipSchema,
+  OmTopologySystemInterfaceGrantMetadataSchema,
+  OmTopologySystemInterfaceGrantSchema,
   parseTopologyNodeRef,
   topologyRelationship,
   topologyRef
@@ -291,6 +302,11 @@ export type {
   OrganizationModelKeyResult,
   OrganizationModelObjective,
   OrganizationModelSystemEntry,
+  OrganizationModelSystemApiInterface,
+  OrganizationModelSystemInterfaceKey,
+  OrganizationModelSystemInterfaceLifecycle,
+  OrganizationModelSystemInterfaceReadinessProfile,
+  OrganizationModelSystemInterfaceRef,
   OrganizationModelSystemId,
   OrganizationModelSystemKind,
   OrganizationModelSystemLifecycle,
@@ -322,6 +338,8 @@ export type {
   OrganizationModelTopologyNodeRef,
   OrganizationModelTopologyRelationship,
   OrganizationModelTopologyRelationshipKind,
+  OrganizationModelTopologySystemInterfaceGrant,
+  OrganizationModelTopologySystemInterfaceGrantMetadata,
   OrganizationModelWorkflowResourceEntry,
   OrganizationModelActions,
   OrganizationModelAction,

package/src/organization-model/schema-refinements.ts

@@ -372,6 +372,7 @@ export function refineOrganizationModel(model: OrganizationModel, ctx: z.Refinem
         )
       }
     })
+
   })
 
   Object.values(model.actions).forEach((action) => {
@@ -571,6 +572,28 @@ export function refineOrganizationModel(model: OrganizationModel, ctx: z.Refinem
     }
   })
 
+  allSystems.forEach(({ path: systemPath, schemaPath, system }) => {
+    system.apiInterface?.resourceIds?.forEach((resourceId, resourceIndex) => {
+      const resource = resourcesById.get(resourceId)
+      if (resource === undefined) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'apiInterface', 'resourceIds', resourceIndex],
+          `System Interface "${systemPath}/api" scopes unknown resource "${resourceId}"`
+        )
+        return
+      }
+
+      if (resource.systemPath !== systemPath) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'apiInterface', 'resourceIds', resourceIndex],
+          `System Interface "${systemPath}/api" scopes resource "${resourceId}" from system "${resource.systemPath}"`
+        )
+      }
+    })
+  })
+
   function validateResourceOntologyBinding(
     resourceId: string,
     bindingKey: 'actions' | 'primaryAction' | 'reads' | 'writes' | 'usesCatalogs' | 'emits',

package/src/organization-model/types.ts

@@ -37,6 +37,11 @@ import {
 } from './domains/knowledge'
 import {
   SystemEntrySchema,
+  SystemInterfaceKeySchema,
+  SystemInterfaceLifecycleSchema,
+  SystemInterfaceReadinessProfileSchema,
+  SystemInterfaceRefSchema,
+  SystemApiInterfaceSchema,
   SystemConfigSchema,
   SystemIdSchema,
   SystemKindSchema,
@@ -74,7 +79,9 @@ import {
   OmTopologyNodeKindSchema,
   OmTopologyNodeRefSchema,
   OmTopologyRelationshipKindSchema,
-  OmTopologyRelationshipSchema
+  OmTopologyRelationshipSchema,
+  OmTopologySystemInterfaceGrantMetadataSchema,
+  OmTopologySystemInterfaceGrantSchema
 } from './domains/topology'
 import {
   ActionsDomainSchema,
@@ -156,6 +163,11 @@ export type OrganizationModelSystemId = z.infer<typeof SystemIdSchema>
 export type OrganizationModelSystemPath = z.infer<typeof SystemPathSchema>
 export type OrganizationModelSystemKind = z.infer<typeof SystemKindSchema>
 export type OrganizationModelSystemLifecycle = z.infer<typeof SystemLifecycleSchema>
+export type OrganizationModelSystemInterfaceKey = z.infer<typeof SystemInterfaceKeySchema>
+export type OrganizationModelSystemInterfaceLifecycle = z.infer<typeof SystemInterfaceLifecycleSchema>
+export type OrganizationModelSystemInterfaceReadinessProfile = z.infer<typeof SystemInterfaceReadinessProfileSchema>
+export type OrganizationModelSystemApiInterface = z.infer<typeof SystemApiInterfaceSchema>
+export type OrganizationModelSystemInterfaceRef = z.infer<typeof SystemInterfaceRefSchema>
 /** @deprecated Use OrganizationModelSystemLifecycle. Accepted for one publish cycle. */
 export type OrganizationModelSystemStatus = z.infer<typeof SystemStatusSchema>
 export type OrganizationModelResources = z.infer<typeof ResourcesDomainSchema>
@@ -185,6 +197,10 @@ export type OrganizationModelTopologyNodeRef = z.infer<typeof OmTopologyNodeRefS
 export type OrganizationModelTopologyRelationshipKind = z.infer<typeof OmTopologyRelationshipKindSchema>
 export type OrganizationModelTopologyRelationship = z.infer<typeof OmTopologyRelationshipSchema>
 export type OrganizationModelTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
+export type OrganizationModelTopologySystemInterfaceGrant = z.infer<typeof OmTopologySystemInterfaceGrantSchema>
+export type OrganizationModelTopologySystemInterfaceGrantMetadata = z.infer<
+  typeof OmTopologySystemInterfaceGrantMetadataSchema
+>
 export type OrganizationModelActions = z.infer<typeof ActionsDomainSchema>
 export type OrganizationModelAction = z.infer<typeof ActionSchema>
 export type OrganizationModelActionId = z.infer<typeof ActionIdSchema>

package/src/platform/constants/versions.ts

@@ -1,3 +1,3 @@
 export const VERSION = {
-  CURRENT: '1.12.5'
+  CURRENT: '1.12.7'
 }