@elevasis/core 0.37.0 → 0.38.0

package/src/reference/_generated/system-interface-capabilities.md

@@ -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/reference/glossary.md

@@ -11,10 +11,16 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **AccessKeys** -- exported access-key constants from `@elevasis/core/auth` / `@repo/core/auth` for platform-admin, diagnostic, and permission-backed gates.
 
-**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
+**Boundary invariant** -- Organization Model rule that local resources may bind local System ontology directly, while sibling-System API behavior needs explicit scope through topology. For System Interfaces, lead-gen-to-CRM handoff is allowed through the `sales.lead-gen/crm-handoff` consumer, the `sales.crm/api` provider, scoped resources, and a `metadata.systemInterfaceGrant` topology grant.
+
+**Capability catalog** -- generated SDK-bundled reference that lists the closed System Interface profiles supported by the installed package, their required System paths, interface keys, and derived-readiness requirements. Current source: `packages/core/src/reference/_generated/system-interface-capabilities.md`; SDK mirror: `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.
+
+**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, resource ontology workflow I/O refs, or generated reference docs. Retired authored System/Bridge Contract surfaces such as `System.contracts`, `bridgeContracts`, and versioned `*@v1` OM contract IDs are not current authoring patterns.
 
 **DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
 
+**Derived readiness** -- readiness computed from resolved Organization Model facts instead of hand-authored readiness declarations. For System Interfaces, the checker evaluates the active `apiInterface` marker, scoped resource IDs, active resources, `resource.ontology` bindings, owned ontology, required catalogs, provider readiness, and scoped topology grants.
+
 **Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
 
 **SystemGuard** -- retired route-level System gate. Use **AccessGuard** with a System path or `AccessKeys` constant.
@@ -45,6 +51,10 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **System** -- tenant-defined bounded context in `OrganizationModel.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, lifecycle, System-local ontology, and System-local config.
 
+**System Interface** -- flat `System.apiInterface` marker that adopts a platform-provided API capability for a System. It declares intent through lifecycle, a closed `readinessProfile`, and optional scoped resource IDs; readiness is derived. Custom tenant Systems should not add custom `apiInterface` profiles. They extend behavior through workflows/operations plus ontology, resources, catalogs, topology, and navigation.
+
+**System Interface profile** -- platform-owned readiness profile from `SYSTEM_INTERFACE_PROFILES`, such as `sales.lead-gen.api`, `sales.crm.api`, or `sales.lead-gen.crm-handoff`. Profiles are a closed literal union tied to platform API consumers and readiness checkers, not tenant-defined extension strings.
+
 **ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
 
 **ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
@@ -55,7 +65,9 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
 
-**Topology** -- durable OM operational wiring declared in `OrganizationModel.topology.relationships`. Initial relationship kinds are `triggers`, `uses`, and `approval`; relationships use typed refs such as `{ kind: 'resource', id: 'lead-import' }`.
+**Scoped topology bridge** -- topology relationship scoped to a System or interface boundary, with metadata that grants a specific consumer interface access to a provider interface. It replaces authored Bridge Contract declarations for API handoff while keeping the bridge in `OrganizationModel.topology.relationships`.
+
+**Topology** -- durable OM operational wiring declared in `OrganizationModel.topology.relationships`. Relationship kinds are the closed set `triggers`, `uses`, and `approval`; relationships use typed refs such as `{ kind: 'resource', id: 'lead-import' }` and may carry structured metadata such as `systemInterfaceGrant`.
 
 ## Package Boundary