@elevasis/core 0.34.1 → 0.35.0

package/dist/organization-model/index.js

@@ -992,6 +992,26 @@ var SystemUiSchema = z.object({
   icon: IconNameSchema.optional(),
   order: z.number().int().optional()
 });
+var SystemInterfaceKeySchema = ModelIdSchema;
+var SystemInterfaceLifecycleSchema = z.enum(["draft", "active", "disabled", "deprecated", "archived"]).meta({ label: "System interface lifecycle", color: "teal" });
+var 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")'
+);
+var SystemInterfaceResourceScopeSchema = z.array(ModelIdSchema).default([]);
+var 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();
+var SystemInterfaceRefSchema = z.object({
+  systemPath: SystemPathSchema,
+  interfaceKey: SystemInterfaceKeySchema
+}).strict();
 var JsonValueSchema = z.lazy(
   () => z.union([
     z.string(),
@@ -1030,6 +1050,8 @@ var SystemEntrySchema = z.object({
   policies: z.array(ModelIdSchema.meta({ ref: "policy" })).default([]).optional(),
   /** Optional goals this system contributes to. */
   drivesGoals: 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. */
@@ -1508,6 +1530,15 @@ var OmTopologyMetadataSchema = z.record(z.string().trim().min(1).max(120), JsonV
   }
   visit(metadata, []);
 });
+var OmTopologySystemInterfaceGrantSchema = z.object({
+  consumer: SystemInterfaceRefSchema,
+  provider: SystemInterfaceRefSchema,
+  resourceIds: z.array(ResourceIdSchema).default([]),
+  ontologyIds: z.array(OntologyIdSchema).default([])
+}).strict();
+var OmTopologySystemInterfaceGrantMetadataSchema = z.object({
+  systemInterfaceGrant: OmTopologySystemInterfaceGrantSchema
+}).strict();
 var OmTopologyRelationshipSchema = z.object({
   from: OmTopologyNodeRefSchema,
   kind: OmTopologyRelationshipKindSchema,
@@ -2247,6 +2278,26 @@ function refineOrganizationModel(model, ctx) {
       );
     }
   });
+  allSystems.forEach(({ path: systemPath, schemaPath, system }) => {
+    system.apiInterface?.resourceIds?.forEach((resourceId, resourceIndex) => {
+      const resource = resourcesById.get(resourceId);
+      if (resource === void 0) {
+        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, bindingKey, expectedKind, ids) {
     const ontologyIds2 = ids === void 0 ? [] : Array.isArray(ids) ? ids : [ids];
     ontologyIds2.forEach((ontologyId, ontologyIndex) => {
@@ -3406,4 +3457,4 @@ function scaffoldOrganizationModel(model, spec) {
   return scaffoldKnowledgeNode(model, spec);
 }
 
-export { ActionIdSchema, ActionInvocationKindSchema, ActionInvocationSchema, ActionRefSchema, ActionSchema, ActionScopeSchema, ActionsDomainSchema, AgentKindSchema, AgentResourceEntrySchema, AgentRoleHolderSchema, ApiEndpointInvocationSchema, CodeReferenceRoleSchema, CodeReferenceSchema, ContractRefSchema, CustomerSegmentSchema, CustomersDomainSchema, DEFAULT_ONTOLOGY_SCOPE, DEFAULT_ORGANIZATION_MODEL, DEFAULT_ORGANIZATION_MODEL_ACTIONS, DEFAULT_ORGANIZATION_MODEL_CUSTOMERS, DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA, DEFAULT_ORGANIZATION_MODEL_GOALS, DEFAULT_ORGANIZATION_MODEL_NAVIGATION, DEFAULT_ORGANIZATION_MODEL_OFFERINGS, DEFAULT_ORGANIZATION_MODEL_POLICIES, DEFAULT_ORGANIZATION_MODEL_RESOURCES, DEFAULT_ORGANIZATION_MODEL_ROLES, DEFAULT_ORGANIZATION_MODEL_STATUSES, DEFAULT_ORGANIZATION_MODEL_SYSTEMS, DEFAULT_ORGANIZATION_MODEL_TOPOLOGY, EntitiesDomainSchema, EntityIdSchema, EntityLinkKindSchema, EntityLinkSchema, EntitySchema, EventDescriptorSchema, EventEmissionDescriptorSchema, EventIdSchema, FirmographicsSchema, GoalsDomainSchema, HumanRoleHolderSchema, IconNameSchema, IntegrationResourceEntrySchema, KNOWLEDGE_FEATURE_ID, KNOWLEDGE_SYSTEM_ID, KeyResultSchema, KnowledgeDomainSchema, KnowledgeLinkSchema, KnowledgeTargetKindSchema, KnowledgeTargetRefSchema, LinkSchema, MONITORING_FEATURE_ID, MONITORING_SYSTEM_ID, McpToolInvocationSchema, NavigationGroupSchema, NodeIdPathSchema, NodeIdStringSchema, OPERATIONS_COMMAND_VIEW_SURFACE_ID, OPERATIONS_FEATURE_ID, OPERATIONS_SYSTEM_ID, ORGANIZATION_MODEL_ICON_TOKENS, ObjectiveSchema, OfferingsDomainSchema, OmTopologyDomainSchema, OmTopologyMetadataSchema, OmTopologyNodeKindSchema, OmTopologyNodeRefSchema, OmTopologyRelationshipKindSchema, OmTopologyRelationshipSchema, OntologyActionTypeSchema, OntologyCatalogTypeSchema, OntologyEventTypeSchema, OntologyGroupSchema, OntologyIdSchema, OntologyInterfaceTypeSchema, OntologyKindSchema, OntologyLinkTypeSchema, OntologyObjectTypeSchema, OntologyScopeSchema, OntologySharedPropertySchema, OntologySurfaceTypeSchema, OntologyValueTypeSchema, OrgKnowledgeKindSchema, OrgKnowledgeNodeSchema, OrganizationModelBuiltinIconTokenSchema, OrganizationModelDomainKeySchema, OrganizationModelDomainMetadataByDomainSchema, OrganizationModelDomainMetadataSchema, OrganizationModelIconTokenSchema, OrganizationModelNavigationSchema, OrganizationModelSchema, PROJECTS_FEATURE_ID, PROJECTS_INDEX_SURFACE_ID, PROJECTS_SYSTEM_ID, PROJECTS_VIEW_ACTION_ID, PROSPECTING_FEATURE_ID, PROSPECTING_LISTS_SURFACE_ID, PROSPECTING_SYSTEM_ID, PoliciesDomainSchema, PolicyApplicabilitySchema, PolicyEffectSchema, PolicyIdSchema, PolicyPredicateSchema, PolicySchema, PolicyTriggerSchema, PricingModelSchema, ProductSchema, ResourceEntrySchema, ResourceGovernanceStatusSchema, ResourceIdSchema, ResourceKindSchema, ResourceOntologyBindingSchema, ResourcesDomainSchema, RoleHolderSchema, RoleHoldersSchema, RoleIdSchema, RoleSchema, RolesDomainSchema, SALES_FEATURE_ID, SALES_PIPELINE_SURFACE_ID, SALES_SYSTEM_ID, SEO_FEATURE_ID, SEO_SYSTEM_ID, SETTINGS_FEATURE_ID, SETTINGS_ROLES_SURFACE_ID, SETTINGS_SYSTEM_ID, ScriptExecutionInvocationSchema, ScriptResourceEntrySchema, ScriptResourceLanguageSchema, ScriptResourceSourceSchema, SidebarNavigationSchema, SidebarNodeSchema, SidebarSectionSchema, SidebarSurfaceTargetsSchema, SlashCommandInvocationSchema, StatusEntrySchema, StatusSemanticClassSchema, StatusesDomainSchema, SurfaceDefinitionSchema, SurfaceTypeSchema, SystemEntrySchema, SystemIdSchema, SystemKindSchema, SystemLifecycleSchema, SystemPathSchema, SystemStatusSchema, SystemUiSchema, SystemsDomainSchema, TeamRoleHolderSchema, TechStackEntrySchema, UiPositionSchema, WorkflowResourceEntrySchema, compileOrganizationOntology, compileTopologyNodeRef, createFoundationOrganizationModel, defineAction, defineActions, defineCustomer, defineCustomers, defineDomainRecord, defineEntities, defineEntity, defineGoal, defineGoals, defineKnowledgeNode, defineKnowledgeNodes, defineOffering, defineOfferings, defineOrganizationModel, definePolicies, definePolicy, defineResource, defineResourceOntology, defineResources, defineRole, defineRoles, defineStatus, defineStatuses, defineSystem, defineSystems, defineTopology, defineTopologyRelationship, findOrganizationActionById, formatOntologyId, getOntologyDiagnostics, getSortedSidebarEntries, isOntologyGraphNodeId, isOntologyTopologyRef, listAllSystems, listResolvedOntologyRecords, ontologyGraphNodeId, ontologyIdFromGraphNodeId, parseContractRef, parseOntologyId, parseTopologyNodeRef, projectOrganizationSurfaces, resolveOrganizationModel, resolveOrganizationModelWithResources, scaffoldOrganizationModel, topologyRef, topologyRelationship, validateOrganizationSurfaceProjection };
+export { ActionIdSchema, ActionInvocationKindSchema, ActionInvocationSchema, ActionRefSchema, ActionSchema, ActionScopeSchema, ActionsDomainSchema, AgentKindSchema, AgentResourceEntrySchema, AgentRoleHolderSchema, ApiEndpointInvocationSchema, CodeReferenceRoleSchema, CodeReferenceSchema, ContractRefSchema, CustomerSegmentSchema, CustomersDomainSchema, DEFAULT_ONTOLOGY_SCOPE, DEFAULT_ORGANIZATION_MODEL, DEFAULT_ORGANIZATION_MODEL_ACTIONS, DEFAULT_ORGANIZATION_MODEL_CUSTOMERS, DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA, DEFAULT_ORGANIZATION_MODEL_GOALS, DEFAULT_ORGANIZATION_MODEL_NAVIGATION, DEFAULT_ORGANIZATION_MODEL_OFFERINGS, DEFAULT_ORGANIZATION_MODEL_POLICIES, DEFAULT_ORGANIZATION_MODEL_RESOURCES, DEFAULT_ORGANIZATION_MODEL_ROLES, DEFAULT_ORGANIZATION_MODEL_STATUSES, DEFAULT_ORGANIZATION_MODEL_SYSTEMS, DEFAULT_ORGANIZATION_MODEL_TOPOLOGY, EntitiesDomainSchema, EntityIdSchema, EntityLinkKindSchema, EntityLinkSchema, EntitySchema, EventDescriptorSchema, EventEmissionDescriptorSchema, EventIdSchema, FirmographicsSchema, GoalsDomainSchema, HumanRoleHolderSchema, IconNameSchema, IntegrationResourceEntrySchema, KNOWLEDGE_FEATURE_ID, KNOWLEDGE_SYSTEM_ID, KeyResultSchema, KnowledgeDomainSchema, KnowledgeLinkSchema, KnowledgeTargetKindSchema, KnowledgeTargetRefSchema, LinkSchema, MONITORING_FEATURE_ID, MONITORING_SYSTEM_ID, McpToolInvocationSchema, NavigationGroupSchema, NodeIdPathSchema, NodeIdStringSchema, OPERATIONS_COMMAND_VIEW_SURFACE_ID, OPERATIONS_FEATURE_ID, OPERATIONS_SYSTEM_ID, ORGANIZATION_MODEL_ICON_TOKENS, ObjectiveSchema, OfferingsDomainSchema, OmTopologyDomainSchema, OmTopologyMetadataSchema, OmTopologyNodeKindSchema, OmTopologyNodeRefSchema, OmTopologyRelationshipKindSchema, OmTopologyRelationshipSchema, OmTopologySystemInterfaceGrantMetadataSchema, OmTopologySystemInterfaceGrantSchema, OntologyActionTypeSchema, OntologyCatalogTypeSchema, OntologyEventTypeSchema, OntologyGroupSchema, OntologyIdSchema, OntologyInterfaceTypeSchema, OntologyKindSchema, OntologyLinkTypeSchema, OntologyObjectTypeSchema, OntologyScopeSchema, OntologySharedPropertySchema, OntologySurfaceTypeSchema, OntologyValueTypeSchema, OrgKnowledgeKindSchema, OrgKnowledgeNodeSchema, OrganizationModelBuiltinIconTokenSchema, OrganizationModelDomainKeySchema, OrganizationModelDomainMetadataByDomainSchema, OrganizationModelDomainMetadataSchema, OrganizationModelIconTokenSchema, OrganizationModelNavigationSchema, OrganizationModelSchema, PROJECTS_FEATURE_ID, PROJECTS_INDEX_SURFACE_ID, PROJECTS_SYSTEM_ID, PROJECTS_VIEW_ACTION_ID, PROSPECTING_FEATURE_ID, PROSPECTING_LISTS_SURFACE_ID, PROSPECTING_SYSTEM_ID, PoliciesDomainSchema, PolicyApplicabilitySchema, PolicyEffectSchema, PolicyIdSchema, PolicyPredicateSchema, PolicySchema, PolicyTriggerSchema, PricingModelSchema, ProductSchema, ResourceEntrySchema, ResourceGovernanceStatusSchema, ResourceIdSchema, ResourceKindSchema, ResourceOntologyBindingSchema, ResourcesDomainSchema, RoleHolderSchema, RoleHoldersSchema, RoleIdSchema, RoleSchema, RolesDomainSchema, SALES_FEATURE_ID, SALES_PIPELINE_SURFACE_ID, SALES_SYSTEM_ID, SEO_FEATURE_ID, SEO_SYSTEM_ID, SETTINGS_FEATURE_ID, SETTINGS_ROLES_SURFACE_ID, SETTINGS_SYSTEM_ID, ScriptExecutionInvocationSchema, ScriptResourceEntrySchema, ScriptResourceLanguageSchema, ScriptResourceSourceSchema, SidebarNavigationSchema, SidebarNodeSchema, SidebarSectionSchema, SidebarSurfaceTargetsSchema, SlashCommandInvocationSchema, StatusEntrySchema, StatusSemanticClassSchema, StatusesDomainSchema, SurfaceDefinitionSchema, SurfaceTypeSchema, SystemApiInterfaceSchema, SystemEntrySchema, SystemIdSchema, SystemInterfaceKeySchema, SystemInterfaceLifecycleSchema, SystemInterfaceReadinessProfileSchema, SystemInterfaceRefSchema, SystemKindSchema, SystemLifecycleSchema, SystemPathSchema, SystemStatusSchema, SystemUiSchema, SystemsDomainSchema, TeamRoleHolderSchema, TechStackEntrySchema, UiPositionSchema, WorkflowResourceEntrySchema, compileOrganizationOntology, compileTopologyNodeRef, createFoundationOrganizationModel, defineAction, defineActions, defineCustomer, defineCustomers, defineDomainRecord, defineEntities, defineEntity, defineGoal, defineGoals, defineKnowledgeNode, defineKnowledgeNodes, defineOffering, defineOfferings, defineOrganizationModel, definePolicies, definePolicy, defineResource, defineResourceOntology, defineResources, defineRole, defineRoles, defineStatus, defineStatuses, defineSystem, defineSystems, defineTopology, defineTopologyRelationship, findOrganizationActionById, formatOntologyId, getOntologyDiagnostics, getSortedSidebarEntries, isOntologyGraphNodeId, isOntologyTopologyRef, listAllSystems, listResolvedOntologyRecords, ontologyGraphNodeId, ontologyIdFromGraphNodeId, parseContractRef, parseOntologyId, parseTopologyNodeRef, projectOrganizationSurfaces, resolveOrganizationModel, resolveOrganizationModelWithResources, scaffoldOrganizationModel, topologyRef, topologyRelationship, validateOrganizationSurfaceProjection };

package/dist/test-utils/index.d.ts

@@ -3739,6 +3739,17 @@ declare const OntologyScopeSchema: z.ZodDefault<z.ZodObject<{
 }, z.core.$strip>>;
 type OntologyScope = z.infer<typeof OntologyScopeSchema>;
 
+declare const SystemApiInterfaceSchema: z.ZodObject<{
+    lifecycle: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        deprecated: "deprecated";
+        draft: "draft";
+        archived: "archived";
+        disabled: "disabled";
+    }>>;
+    readinessProfile: z.ZodOptional<z.ZodString>;
+    resourceIds: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
 type JsonPrimitive = string | number | boolean | null;
 type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
@@ -3767,6 +3778,7 @@ interface SystemEntry {
     }[];
     policies?: string[];
     drivesGoals?: string[];
+    apiInterface?: z.infer<typeof SystemApiInterfaceSchema>;
     /** @deprecated Use lifecycle. Accepted for one publish cycle. */
     status?: 'active' | 'deprecated' | 'archived';
     path?: string;

package/dist/test-utils/index.js

@@ -20318,6 +20318,26 @@ var SystemUiSchema = z.object({
   icon: IconNameSchema.optional(),
   order: z.number().int().optional()
 });
+var SystemInterfaceKeySchema = ModelIdSchema;
+var SystemInterfaceLifecycleSchema = z.enum(["draft", "active", "disabled", "deprecated", "archived"]).meta({ label: "System interface lifecycle", color: "teal" });
+var 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")'
+);
+var SystemInterfaceResourceScopeSchema = z.array(ModelIdSchema).default([]);
+var 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();
+var SystemInterfaceRefSchema = z.object({
+  systemPath: SystemPathSchema,
+  interfaceKey: SystemInterfaceKeySchema
+}).strict();
 var JsonValueSchema = z.lazy(
   () => z.union([
     z.string(),
@@ -20356,6 +20376,8 @@ var SystemEntrySchema = z.object({
   policies: z.array(ModelIdSchema.meta({ ref: "policy" })).default([]).optional(),
   /** Optional goals this system contributes to. */
   drivesGoals: 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. */
@@ -20771,6 +20793,15 @@ var OmTopologyMetadataSchema = z.record(z.string().trim().min(1).max(120), JsonV
   }
   visit(metadata, []);
 });
+var OmTopologySystemInterfaceGrantSchema = z.object({
+  consumer: SystemInterfaceRefSchema,
+  provider: SystemInterfaceRefSchema,
+  resourceIds: z.array(ResourceIdSchema).default([]),
+  ontologyIds: z.array(OntologyIdSchema).default([])
+}).strict();
+z.object({
+  systemInterfaceGrant: OmTopologySystemInterfaceGrantSchema
+}).strict();
 var OmTopologyRelationshipSchema = z.object({
   from: OmTopologyNodeRefSchema,
   kind: OmTopologyRelationshipKindSchema,
@@ -21398,6 +21429,26 @@ function refineOrganizationModel(model, ctx) {
       );
     }
   });
+  allSystems.forEach(({ path: systemPath, schemaPath, system }) => {
+    system.apiInterface?.resourceIds?.forEach((resourceId, resourceIndex) => {
+      const resource = resourcesById.get(resourceId);
+      if (resource === void 0) {
+        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, bindingKey, expectedKind, ids) {
     const ontologyIds2 = ids === void 0 ? [] : Array.isArray(ids) ? ids : [ids];
     ontologyIds2.forEach((ontologyId, ontologyIndex) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/core",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "license": "MIT",
   "description": "Minimal shared constants across Elevasis monorepo",
   "sideEffects": false,

package/src/_gen/__tests__/__snapshots__/contracts.md.snap

@@ -303,6 +303,36 @@ export type OrganizationModelSystemKind = z.infer<typeof SystemKindSchema>
 export type OrganizationModelSystemLifecycle = z.infer<typeof SystemLifecycleSchema>
 ```
 
+### `OrganizationModelSystemInterfaceKey`
+
+```typescript
+export type OrganizationModelSystemInterfaceKey = z.infer<typeof SystemInterfaceKeySchema>
+```
+
+### `OrganizationModelSystemInterfaceLifecycle`
+
+```typescript
+export type OrganizationModelSystemInterfaceLifecycle = z.infer<typeof SystemInterfaceLifecycleSchema>
+```
+
+### `OrganizationModelSystemInterfaceReadinessProfile`
+
+```typescript
+export type OrganizationModelSystemInterfaceReadinessProfile = z.infer<typeof SystemInterfaceReadinessProfileSchema>
+```
+
+### `OrganizationModelSystemApiInterface`
+
+```typescript
+export type OrganizationModelSystemApiInterface = z.infer<typeof SystemApiInterfaceSchema>
+```
+
+### `OrganizationModelSystemInterfaceRef`
+
+```typescript
+export type OrganizationModelSystemInterfaceRef = z.infer<typeof SystemInterfaceRefSchema>
+```
+
 ### `OrganizationModelSystemStatus`
 
 ```typescript
@@ -466,6 +496,20 @@ export type OrganizationModelTopologyRelationship = z.infer<typeof OmTopologyRel
 export type OrganizationModelTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
 ```
 
+### `OrganizationModelTopologySystemInterfaceGrant`
+
+```typescript
+export type OrganizationModelTopologySystemInterfaceGrant = z.infer<typeof OmTopologySystemInterfaceGrantSchema>
+```
+
+### `OrganizationModelTopologySystemInterfaceGrantMetadata`
+
+```typescript
+export type OrganizationModelTopologySystemInterfaceGrantMetadata = z.infer<
+  typeof OmTopologySystemInterfaceGrantMetadataSchema
+>
+```
+
 ### `OrganizationModelActions`
 
 ```typescript
@@ -1328,38 +1372,33 @@ export interface HumanCheckpointDefinition extends ResourceDefinition {
 ### `DeploymentSpec`
 
 ```typescript
-/**
- * Organization-specific resource collection
- *
- * Complete manifest of all automation resources for an organization.
- * Used by ResourceRegistry for discovery and Command View for visualization.
- */
-export interface DeploymentSpec {
+/**
+ * Organization-specific resource collection
+ *
+ * Complete manifest of all automation resources for an organization.
+ * Used by ResourceRegistry for discovery and Command View for visualization.
+ */
+export interface DeploymentSpec {
   /** Deployment version (semver) */
   version: string
-  /** Optional Organization Model governance catalog used for OM-code validation */
-  organizationModel?: Partial<
-    Pick<
-      OrganizationModel,
-      'systems' | 'resources' | 'ontology' | 'topology' | 'roles' | 'policies' | 'entities' | 'actions'
-    >
-  >
-  /** Workflow definitions */
-  workflows?: WorkflowDefinition[]
-  /** Agent definitions */
-  agents?: AgentDefinition[]
-
-  // Resource Manifest fields (optional for backwards compatibility)
-  /** Trigger definitions - entry points that initiate executions */
-  triggers?: TriggerDefinition[]
-  /** Integration definitions - external service connections */
-  integrations?: IntegrationDefinition[]
-  /** Explicit relationship declarations between resources */
-  relationships?: ResourceRelationships
-  /** External automation resources (n8n, Make, Zapier, etc.) */
-  externalResources?: ExternalResourceDefinition[]
-  /** Human checkpoint definitions - human decision points in automation */
-  humanCheckpoints?: HumanCheckpointDefinition[]
+  /** Optional full Organization Model snapshot used for OM-code validation and deployment persistence */
+  organizationModel?: OrganizationModel
+  /** Workflow definitions */
+  workflows?: WorkflowDefinition[]
+  /** Agent definitions */
+  agents?: AgentDefinition[]
+
+  // Resource Manifest fields (optional for backwards compatibility)
+  /** Trigger definitions - entry points that initiate executions */
+  triggers?: TriggerDefinition[]
+  /** Integration definitions - external service connections */
+  integrations?: IntegrationDefinition[]
+  /** Explicit relationship declarations between resources */
+  relationships?: ResourceRelationships
+  /** External automation resources (n8n, Make, Zapier, etc.) */
+  externalResources?: ExternalResourceDefinition[]
+  /** Human checkpoint definitions - human decision points in automation */
+  humanCheckpoints?: HumanCheckpointDefinition[]
 }
 ```
 

package/src/auth/multi-tenancy/index.ts

@@ -1,26 +1,29 @@
-// Theme preset SSOT (const tuple + derived union + Zod enum)
-export * from './theme-presets'
-
-// Config types
-export * from './types'
-
-// Permission catalog (canonical PERMISSIONS constant + types)
-export * from './permissions'
-
-// Role management schemas
-export * from './role-management/index'
-
-// Organization types
-export * from './organizations/index'
-
-// User types
-export * from './users/index'
-
-// Membership types
-export * from './memberships/index'
-
-// Invitation types
-export * from './invitations/index'
-
-// Credentials types
-export * from './credentials/index'
+// Theme preset SSOT (const tuple + derived union + Zod enum)
+export * from './theme-presets'
+
+// Config types
+export * from './types'
+
+// Branded organization identifiers (WorkOS id vs Supabase UUID)
+export * from './org-id'
+
+// Permission catalog (canonical PERMISSIONS constant + types)
+export * from './permissions'
+
+// Role management schemas
+export * from './role-management/index'
+
+// Organization types
+export * from './organizations/index'
+
+// User types
+export * from './users/index'
+
+// Membership types
+export * from './memberships/index'
+
+// Invitation types
+export * from './invitations/index'
+
+// Credentials types
+export * from './credentials/index'

package/src/auth/multi-tenancy/org-id.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest'
+import {
+  asSupabaseOrgId,
+  asWorkOsOrgId,
+  asSupabaseOrgIdOrNull,
+  asWorkOsOrgIdOrNull,
+  brandSupabaseOrgId,
+  brandWorkOsOrgId,
+  isSupabaseOrgId,
+  isWorkOsOrgId,
+  type SupabaseOrgId,
+  type WorkOsOrgId
+} from './org-id'
+
+// Real fixtures pulled from the dev `organizations` table so the format checks
+// exercise production-shaped values, not invented ones.
+const ELEVASIS_UUID = 'f9aa5a56-8c13-4cd1-9161-8827ae7b452b'
+const ELEVASIS_WORKOS = 'org_01K64D59CA5J3PJCWJFQV87PPN'
+const TESTER_UUID = '1b7a6cb2-d73f-44cb-942b-1fa841085ec0'
+const TESTER_WORKOS = 'org_01K4EW076HK9ND7JWPFZKGCNJF'
+// A WorkOS test-org id -- still prefixed `org_`, must be treated as a WorkOS id.
+const TEST_ORG_WORKOS = 'org_test_1776593934703_6gfvsb_l6nyy6'
+const TEST_ORG_UUID = '2ac228f7-a0a1-49f9-920e-8a348f5253d3'
+
+describe('org-id brands: runtime validation', () => {
+  it('asSupabaseOrgId accepts real Supabase UUIDs and returns the same value', () => {
+    expect(asSupabaseOrgId(ELEVASIS_UUID)).toBe(ELEVASIS_UUID)
+    expect(asSupabaseOrgId(TESTER_UUID)).toBe(TESTER_UUID)
+    expect(asSupabaseOrgId(TEST_ORG_UUID)).toBe(TEST_ORG_UUID)
+  })
+
+  it('asWorkOsOrgId accepts real WorkOS ids (including org_test_*) and returns the same value', () => {
+    expect(asWorkOsOrgId(ELEVASIS_WORKOS)).toBe(ELEVASIS_WORKOS)
+    expect(asWorkOsOrgId(TESTER_WORKOS)).toBe(TESTER_WORKOS)
+    expect(asWorkOsOrgId(TEST_ORG_WORKOS)).toBe(TEST_ORG_WORKOS)
+  })
+
+  it('asSupabaseOrgId throws loudly when handed a WorkOS id (the silent footgun, surfaced)', () => {
+    expect(() => asSupabaseOrgId(ELEVASIS_WORKOS)).toThrow(/Supabase organization UUID/)
+    expect(() => asSupabaseOrgId(TEST_ORG_WORKOS)).toThrow(/Supabase organization UUID/)
+  })
+
+  it('asWorkOsOrgId throws loudly when handed a Supabase UUID (the reverse footgun)', () => {
+    expect(() => asWorkOsOrgId(ELEVASIS_UUID)).toThrow(/WorkOS organization id/)
+    expect(() => asWorkOsOrgId(TESTER_UUID)).toThrow(/WorkOS organization id/)
+  })
+
+  it('rejects empty and obviously malformed values', () => {
+    expect(() => asSupabaseOrgId('')).toThrow()
+    expect(() => asSupabaseOrgId('not-a-uuid')).toThrow()
+    expect(() => asWorkOsOrgId('')).toThrow()
+    expect(() => asWorkOsOrgId('01K64D59CA5J3PJCWJFQV87PPN')).toThrow() // missing org_ prefix
+  })
+})
+
+describe('org-id brands: type guards', () => {
+  it('isSupabaseOrgId is true only for UUIDs', () => {
+    expect(isSupabaseOrgId(ELEVASIS_UUID)).toBe(true)
+    expect(isSupabaseOrgId(ELEVASIS_WORKOS)).toBe(false)
+  })
+
+  it('isWorkOsOrgId is true only for org_ prefixed values', () => {
+    expect(isWorkOsOrgId(ELEVASIS_WORKOS)).toBe(true)
+    expect(isWorkOsOrgId(TEST_ORG_WORKOS)).toBe(true)
+    expect(isWorkOsOrgId(ELEVASIS_UUID)).toBe(false)
+  })
+})
+
+describe('org-id brands: nullable mint helpers', () => {
+  it('pass null/undefined through unchanged', () => {
+    expect(asSupabaseOrgIdOrNull(null)).toBeNull()
+    expect(asSupabaseOrgIdOrNull(undefined)).toBeNull()
+    expect(asWorkOsOrgIdOrNull(null)).toBeNull()
+    expect(asWorkOsOrgIdOrNull(undefined)).toBeNull()
+  })
+
+  it('validate non-null values', () => {
+    expect(asSupabaseOrgIdOrNull(ELEVASIS_UUID)).toBe(ELEVASIS_UUID)
+    expect(asWorkOsOrgIdOrNull(ELEVASIS_WORKOS)).toBe(ELEVASIS_WORKOS)
+    expect(() => asSupabaseOrgIdOrNull(ELEVASIS_WORKOS)).toThrow()
+  })
+})
+
+describe('org-id brands: trusted-source casts', () => {
+  it('brand* never throws (trusted values are not re-validated) and preserves the value', () => {
+    expect(brandSupabaseOrgId(ELEVASIS_UUID)).toBe(ELEVASIS_UUID)
+    expect(brandWorkOsOrgId(ELEVASIS_WORKOS)).toBe(ELEVASIS_WORKOS)
+    // Unlike as*, brand* does not validate -- it is the trusted-data path.
+    expect(() => brandSupabaseOrgId('anything')).not.toThrow()
+    expect(() => brandWorkOsOrgId('anything')).not.toThrow()
+  })
+
+  it('brand* maps null/undefined to null', () => {
+    expect(brandSupabaseOrgId(null)).toBeNull()
+    expect(brandSupabaseOrgId(undefined)).toBeNull()
+    expect(brandWorkOsOrgId(null)).toBeNull()
+    expect(brandWorkOsOrgId(undefined)).toBeNull()
+  })
+})
+
+/**
+ * Compile-time enforcement. These sinks model the real consumers: a Supabase
+ * `.eq('organization_id', ...)` helper (needs SupabaseOrgId) and a query-key
+ * factory (needs WorkOsOrgId). The `@ts-expect-error` directives are the actual
+ * assertions -- if a brand ever fails to block a swap, the directive becomes
+ * "unused" and `tsc` (check-types) fails. The sinks are runtime no-ops, so this
+ * block executes harmlessly under vitest; the guarantee is verified by the type
+ * checker.
+ */
+describe('org-id brands: compile-time swap prevention', () => {
+  function expectsSupabaseOrgId(_id: SupabaseOrgId): void {}
+  function expectsWorkOsOrgId(_id: WorkOsOrgId): void {}
+
+  it('accepts correctly-branded ids and keeps string compatibility', () => {
+    // Positive: the right brand flows into the right sink.
+    expectsSupabaseOrgId(asSupabaseOrgId(ELEVASIS_UUID))
+    expectsWorkOsOrgId(asWorkOsOrgId(ELEVASIS_WORKOS))
+
+    // A branded id is still a string everywhere a plain string is expected.
+    const asString: string = asSupabaseOrgId(ELEVASIS_UUID)
+    expect(asString).toBe(ELEVASIS_UUID)
+  })
+
+  it('rejects cross-brand and raw-string assignment at compile time', () => {
+    // @ts-expect-error WorkOsOrgId must not be usable where a SupabaseOrgId is required.
+    expectsSupabaseOrgId(asWorkOsOrgId(ELEVASIS_WORKOS))
+
+    // @ts-expect-error SupabaseOrgId must not be usable where a WorkOsOrgId is required.
+    expectsWorkOsOrgId(asSupabaseOrgId(ELEVASIS_UUID))
+
+    // @ts-expect-error a raw string cannot reach the sink without minting through the factory.
+    expectsSupabaseOrgId(ELEVASIS_UUID)
+
+    // @ts-expect-error a raw string cannot reach the sink without minting through the factory.
+    expectsWorkOsOrgId(ELEVASIS_WORKOS)
+
+    expect(true).toBe(true)
+  })
+})

package/src/auth/multi-tenancy/org-id.ts

@@ -0,0 +1,112 @@
+/**
+ * Branded organization identifiers.
+ *
+ * Every organization carries TWO distinct ID values that are both plain
+ * strings at runtime but mean different things:
+ *
+ * - WorkOS organization id (`org_...`) -- the auth/JWT identity. Used for API
+ *   requests, SSE headers, and org-scoped query keys.
+ * - Supabase organization id (UUID) -- the database key. Used for
+ *   `.eq('organization_id', ...)` queries and RLS scoping.
+ *
+ * They are not interchangeable, yet both are `string` -- so a swap compiles
+ * cleanly and fails silently (zero rows on the Supabase side, cross-pollinated
+ * cache keys on the API side). These brands make the two non-assignable to one
+ * another, turning that silent footgun into a compile error at the sink.
+ *
+ * Mint a brand only through the `as*` factories below: they are the single
+ * validate-and-tag boundary (compile-time brand + runtime format check). The
+ * type predicates double as the cast, so no raw `as` cast is needed anywhere.
+ *
+ * Lives on the published `@repo/core` / `@repo/core/auth` surface so the UI,
+ * the API, and the dogfooding `@repo/elevasis-*` packages can all use it.
+ */
+
+import { UuidSchema } from '../../platform/utils/validation'
+
+declare const supabaseOrgIdBrand: unique symbol
+declare const workOsOrgIdBrand: unique symbol
+
+/** A Supabase organization id (UUID) -- the database key for RLS-scoped rows. */
+export type SupabaseOrgId = string & { readonly [supabaseOrgIdBrand]: true }
+
+/** A WorkOS organization id (`org_...`) -- the auth identity for API/SSE/query keys. */
+export type WorkOsOrgId = string & { readonly [workOsOrgIdBrand]: true }
+
+/** WorkOS organization ids are always prefixed with `org_` (incl. `org_test_...`). */
+const WORKOS_ORG_ID_PREFIX = 'org_'
+
+/** True when `value` is shaped like a Supabase organization UUID. */
+export function isSupabaseOrgId(value: string): value is SupabaseOrgId {
+  return UuidSchema.safeParse(value).success
+}
+
+/** True when `value` is shaped like a WorkOS organization id (`org_...`). */
+export function isWorkOsOrgId(value: string): value is WorkOsOrgId {
+  return value.startsWith(WORKOS_ORG_ID_PREFIX)
+}
+
+/**
+ * Validate-and-brand a string as a Supabase organization id.
+ *
+ * @throws {Error} if the value is not a UUID (e.g. a WorkOS `org_...` id leaked in).
+ */
+export function asSupabaseOrgId(value: string): SupabaseOrgId {
+  if (!isSupabaseOrgId(value)) {
+    throw new Error(
+      `Expected a Supabase organization UUID, received "${value}". ` +
+        `A WorkOS org id (org_...) was likely used where the database key is required.`
+    )
+  }
+  return value
+}
+
+/**
+ * Validate-and-brand a string as a WorkOS organization id.
+ *
+ * @throws {Error} if the value is not `org_...` (e.g. a Supabase UUID leaked in).
+ */
+export function asWorkOsOrgId(value: string): WorkOsOrgId {
+  if (!isWorkOsOrgId(value)) {
+    throw new Error(
+      `Expected a WorkOS organization id (org_...), received "${value}". ` +
+        `A Supabase UUID was likely used where the auth identity is required.`
+    )
+  }
+  return value
+}
+
+/** Nullable convenience for mint sites that read `... ?? null` from a membership. */
+export function asSupabaseOrgIdOrNull(value: string | null | undefined): SupabaseOrgId | null {
+  return value == null ? null : asSupabaseOrgId(value)
+}
+
+/** Nullable convenience for mint sites that read `... ?? null` from a membership. */
+export function asWorkOsOrgIdOrNull(value: string | null | undefined): WorkOsOrgId | null {
+  return value == null ? null : asWorkOsOrgId(value)
+}
+
+// ---------------------------------------------------------------------------
+// Trusted-source casts (brand WITHOUT validating).
+//
+// Use these when the value is already known to be well-formed -- e.g. an
+// organization id read from our own database/membership API, or a test
+// fixture. They never throw, so they are safe at UI mint points (a provider
+// must not white-screen on data shape) and avoid re-validating trusted DB
+// UUIDs on every render. For UNTRUSTED input (route params, external ids)
+// prefer the validating `as*` factories above, which throw on a bad shape.
+// ---------------------------------------------------------------------------
+
+/** Brand a trusted string as a Supabase organization id without validating. */
+export function brandSupabaseOrgId(value: string): SupabaseOrgId
+export function brandSupabaseOrgId(value: string | null | undefined): SupabaseOrgId | null
+export function brandSupabaseOrgId(value: string | null | undefined): SupabaseOrgId | null {
+  return (value ?? null) as SupabaseOrgId | null
+}
+
+/** Brand a trusted string as a WorkOS organization id without validating. */
+export function brandWorkOsOrgId(value: string): WorkOsOrgId
+export function brandWorkOsOrgId(value: string | null | undefined): WorkOsOrgId | null
+export function brandWorkOsOrgId(value: string | null | undefined): WorkOsOrgId | null {
+  return (value ?? null) as WorkOsOrgId | null
+}