@elevasis/sdk 1.27.1 → 1.28.1

package/reference/claude-config/sync-notes/2026-05-24-system-interface-readiness.md

@@ -0,0 +1,43 @@
+# System Interface readiness, scoped topology grants, and org ID brands
+
+## Why this note exists
+
+The Organization Model API boundary now uses `system.apiInterface` plus derived readiness instead of authored `System.contracts` or top-level `bridgeContracts`. API-backed Systems are ready when their scoped Resources, ontology bindings, catalog contents, and scoped topology grants satisfy the published readiness profile.
+
+This removes the old declaration-triggered contract layer before it became a tenant authoring requirement, and it gives API and UI consumers structured readiness diagnostics instead of incidental runtime failures.
+
+The same release train also publishes branded WorkOS organization IDs and Supabase organization UUIDs through the shared core/UI package surface. The brands are a compile-time guard against mixing auth identity (`org_...`) with database identity (UUID) in package consumers.
+
+## Applies to
+
+Template-derived projects that opt into API-backed Systems such as lead-gen or CRM after updating to the released package baselines that include `system.apiInterface` support.
+
+The bare `_template` remains API-interface-light by default. Disabled sales, lead-gen, and CRM shell Systems should not declare API interfaces until a compatible recipe pack or tenant-owned model intentionally opts in.
+
+Projects that consume the updated `@elevasis/core` or `@elevasis/ui` types may see stricter TypeScript checks around organization IDs. This is expected: WorkOS org IDs and Supabase org UUIDs are intentionally no longer interchangeable at typed chokepoints.
+
+## Required actions
+
+1. Pull the new package baselines after the release train publishes:
+   - `@elevasis/core`
+   - `@elevasis/ui`
+   - `@elevasis/sdk`
+2. Do not author `contracts`, `bridgeContracts`, versioned `*@v1` contract IDs, or a keyed `interfaces` map in tenant Organization Models.
+3. For an API-backed System, author the flat `system.apiInterface` marker only after the System's scoped Resources and ontology bindings are ready.
+4. Model cross-System API behavior with scoped topology grants rather than broad sibling-System references.
+5. Keep disabled optional-pack shells contract/interface-free until the project deliberately installs an API-ready pack.
+6. When TypeScript reports a branded org-ID mismatch, fix the source value rather than casting through `string`; use package-provided brand helpers only at trusted source boundaries.
+
+## Verification
+
+- `pnpm -C core test -- organization-model`
+- `pnpm -C operations check`
+- Verify API-backed routes return structured readiness errors when a required System Interface is absent or not ready.
+- Verify API-backed UI actions are disabled until the relevant System Interface readiness passes.
+- Verify org-scoped query keys and Supabase `organization_id` filters receive the intended org-ID flavor after package baselines update.
+
+## Not handled by /git-sync
+
+`/git-sync` can propagate template guidance, package baselines, and this note, but it does not decide when a tenant's business model is ready to declare `system.apiInterface`. Tenant-specific System Interface markers, scoped Resource bindings, and topology grants remain project-owned authoring decisions.
+
+`/git-sync` also does not repair tenant-specific organization identity plumbing. If a project has local hooks or direct Supabase calls outside the template baseline, audit those call sites manually when adopting the branded org-ID package surface.

package/reference/concepts.mdx

@@ -93,7 +93,7 @@ type MyInput = z.infer<typeof myInput>;
 
 Each execution creates an ephemeral worker thread from your deployed bundle. The platform validates input against your Zod schema, runs your handler, and returns the result. Workers are terminated immediately after completion -- there is no persistent server.
 
-Key implications: files written to disk disappear after execution, logs appear only after the execution completes (no streaming), and each execution is fully isolated with no shared state between runs. Outbound network access is unrestricted. Memory is capped at 256MB per worker; execution timeout is 300s for workflows and 600s for agents.
+Key implications: files written to disk disappear after execution, logs appear only after the execution completes (no streaming), and each execution is fully isolated with no shared state between runs. Outbound network access is unrestricted. Memory is capped at 256MB per worker; the platform applies a default execution ceiling of 2 hours to all resource types (agents can override via `constraints.timeout`).
 
 For the complete execution lifecycle, concurrency model, observability, and resource limits, see [Runtime](runtime.mdx).
 

package/reference/resources/patterns.mdx

@@ -130,7 +130,7 @@ const sendEmailStep: WorkflowStep = {
 
 **Key points:**
 
-- `platform.call()` is async and times out after 60 seconds
+- `platform.call()` is async and times out after 30 minutes (a worker-side safety net; real enforcement is server-side)
 - `credential` is the name of a platform environment variable set via `elevasis-sdk env set` when the tool needs one
 - On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
 - Always log success so executions are easy to debug in the dashboard

package/reference/runtime.mdx

@@ -30,13 +30,13 @@ Workers are ephemeral -- each execution creates a new worker thread. There is no
 
 Timeouts are enforced by the platform. You do not handle them explicitly in your code:
 
-- **Default timeout:** A platform default applies to all resource types unless overridden.
+- **Default timeout:** A platform default of 2 hours applies to all resource types unless overridden. This is a safety-net ceiling for runaway executions, not a target -- run long work with `--async` and observe via SSE/polling rather than holding a synchronous call open.
 - **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
 - **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
 
 ### Cancellation
 
-Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as cancelled.
+Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as `failed` with a cancellation reason (there is no separate `cancelled` status).
 
 **What triggers cancellation:**
 
@@ -61,7 +61,7 @@ Errors are displayed depending on the surface you use to inspect them:
 - **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
 - **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
 - **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
-- **Cancellation:** Execution is marked cancelled.
+- **Cancellation:** The worker is terminated and the execution is marked `failed` with a cancellation reason.
 
 ---
 
@@ -133,12 +133,11 @@ Limits enforced per worker thread at runtime:
 
 Hard limits to prevent abuse and ensure platform stability:
 
-| Limit                              | Value         |
-| ---------------------------------- | ------------- |
-| Max execution duration (workflows) | 300s (5 min)  |
-| Max execution duration (agents)    | 600s (10 min) |
-| Max log volume                     | 100MB/day     |
-| Max deploy frequency               | 60/day        |
+| Limit                  | Value                                                                                        |
+| ---------------------- | -------------------------------------------------------------------------------------------- |
+| Max execution duration | 2 hours (platform default for all resource types; agents override via `constraints.timeout`) |
+| Max log volume         | 100MB/day                                                                                    |
+| Max deploy frequency   | 60/day                                                                                       |
 
 - **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
 - **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -10,7 +10,7 @@ description: Add, hide, or replace CRM deal action buttons in a template-derived
 
 CRM deal pages derive their action buttons from an `ActionDef[]` array. The shared UI reads that array from the provider, filters it with `deriveActions(deal, actions)`, and renders one-click buttons for actions without a `payloadSchema`.
 
-For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, contracts, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
+For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, System Interfaces, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
 
 **Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/in-progress/active-development/sdk-changes/crm/crm-current-state-assessment.mdx`.
 
@@ -31,6 +31,8 @@ Every action in the CRM action catalog maps to a deployed workflow via its `work
 4. Returns the refetched deal.
 
 External projects override an action's behavior by deploying a workflow with the same `workflowId` as the action entry. The resource registry picks the project-owned workflow over the platform default. The `isAvailableFor` predicate comes from the caller-supplied action catalog; override what the action does and keep button availability aligned with the server-side gate.
+
+CRM action dispatch is an API-backed surface. The tenant Organization Model must expose an active and ready `sales.crm.apiInterface` marker before shared CRM action buttons are considered ready. If a lead-gen workflow hands off into CRM, model that crossing through lead-gen resources that bind the CRM pipeline plus a scoped topology grant to `sales.crm.apiInterface` instead of making base lead-gen readiness depend on CRM catalogs.
 
 ## ActionDef Shape
 
@@ -346,7 +348,9 @@ export function SendQuoteButton({ dealId }: { dealId: string }) {
 }
 ```
 
-Use this button through a custom deal route or a `renderActions` slot where available.
+Use this button through a custom deal route or a `renderActions` slot where available.
+
+Keep the same interface boundary for direct workflow buttons: custom UI may render read-only deal context without API readiness, but buttons that call `/execute`, `/execute-async`, or CRM action routes should be hidden or disabled until the relevant System Interface and any scoped topology grant are ready.
 
 ## 3. Build a Fully Custom Deal Page
 

package/reference/scaffold/recipes/extend-crm.md

@@ -3,7 +3,7 @@
 
 ---
 title: Build and Extend CRM
-description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
+description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, System Interfaces, and org-model extension boundaries.
 ---
 
 # Build and Extend CRM
@@ -25,13 +25,13 @@ CRM is a layered platform surface, not one component:
 - **Headless hooks:** deal, company, contact, note, task, list, transition, and action hooks live under `@elevasis/ui/hooks`.
 - **Action system:** `ActionDef`, `deriveActions`, and the caller-supplied provider-level `crmActions` catalog configure deal actions. The published `@elevasis/sdk` surface ships no default Elevasis action catalog -- projects supply their own `ActionDef[]`.
 - **Workflow adapters:** `crm` and `acqDb` from `@elevasis/sdk/worker` let workflows read and mutate CRM/acquisition data through platform tools.
-- **Contracts:** generated contract docs expose the current CRM shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+- **System API Interface:** `sales.crm` uses the flat `system.apiInterface` marker for its API-backed CRM boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Cross-system lead-gen handoff belongs in scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current CRM shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
 
 ## Decision Table
 
 | User wants                                                                       | Start here                                                                                          | Notes                                                                                                                                                             |
 | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Change CRM System availability, labels, pipeline stages, or resource descriptors | `core/config/organization-model.ts`                                                                 | Treat this as Organization OS work. Use the project's configure ceremony if available.                                                                            |
+| Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                 | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.             |
 | Add CRM sidebar nav or a CRM route                                               | `@elevasis/ui/features/crm` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
 | Wrap a shared CRM page with project chrome                                       | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                   | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
 | Build a custom deal page                                                         | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`       | Use hooks for platform data and compose your own UI.                                                                                                              |
@@ -237,6 +237,8 @@ Keep these boundaries straight:
 - `DealStage` and platform action defaults describe the current shared platform deal state vocabulary.
 - UI wrappers can relabel and route around shared surfaces, but changing persisted platform stages requires coordinated core/API/UI updates.
 - Do not add `sales.actions` to the org model in v1. Deal action customization is covered by [customize-crm-actions.md](customize-crm-actions.md).
+- Mark `sales.crm.apiInterface` active only after CRM object, pipeline, action, and resource refs are ready.
+- Model behavior that intentionally crosses from lead-gen into CRM through lead-gen resources that bind the CRM pipeline plus a scoped topology grant to `sales.crm.apiInterface`.
 
 ## Verify
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -3,7 +3,7 @@
 
 ---
 title: Build and Extend Lead Gen
-description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, provider-injected Organization Model config, data hooks, list/member state, artifacts, workflow adapters, contracts, and tenant-owned extension boundaries.
+description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, provider-injected Organization Model config, data hooks, list/member state, artifacts, workflow adapters, System Interfaces, and tenant-owned extension boundaries.
 ---
 
 # Build and Extend Lead Gen
@@ -27,13 +27,13 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 - **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, list members, list companies, telemetry, and stateful transition shapes are exposed through generated contracts.
 - **Core readers:** `getLeadGenStageCatalog`, `getAllBuildTemplates`, `getProspectingBuildTemplateOptions`, and `createBuildPlanSnapshotFromTemplateId` from `@elevasis/core` read caller-supplied Organization Model/template values. They do not ship tenant catalogs or default templates.
 - **Workflow adapters:** `acqDb`, `list`, and `listBuilderWorkflow` from `@elevasis/sdk/worker` let workflows read and mutate lead-gen data through platform tools.
-- **Contracts:** generated contract docs expose the current lead-gen shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+- **System API Interface:** `sales.lead-gen` uses the flat `system.apiInterface` marker for its API-backed lead-gen boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Lead-gen-to-CRM handoff uses scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current lead-gen shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
 
 ## Decision Table
 
-| User wants                                                                                              | Start here                                                                                                                                      | Notes                                                                                                           |
-| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, or topology | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Use the project's configure ceremony if available. |
+| User wants                                                                                              | Start here                                                                                                                                      | Notes                                                                                                           |
+| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, topology, or API readiness | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Mark `sales.lead-gen.apiInterface` active only when scoped resources and ontology are ready for API-backed lead-gen actions. |
 | Add lead-gen sidebar nav or a lead-gen route                                                            | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                           |
 | Wrap a shared lead-gen page with project chrome                                                         | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                               |
 | Build a custom campaign/list workspace                                                                  | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.         |
@@ -167,8 +167,9 @@ The shared pages call `useLeadGenConfig()` internally. That hook reads the provi
 - `buildTemplates` and `defaultBuildSteps` from `getAllBuildTemplates(organizationModel)`
 - `defaultBuildTemplateId` from the `sales.lead-gen` system config or first available template
 - `exportWorkflowId` from the lead-gen workflow resource whose action matches export semantics
+- `canUseLeadGenApiActions` from derived `sales.lead-gen.apiInterface` readiness
 
-If the provider has no Organization Model, shared UI renders with empty config instead of falling back to Elevasis-owned defaults. A tenant that wants list creation and the build runner to be useful must provide lead-gen catalogs/templates/actions/resources/topology in `core/config/organization-model.ts`.
+If the provider has no Organization Model, shared UI renders with empty config instead of falling back to Elevasis-owned defaults. Read-only shells can render without API readiness, but shared API-backed actions such as list creation, list deletion, data-mode updates, build runs, exports, and member transitions stay disabled until `sales.lead-gen.apiInterface` is active and ready. A tenant that wants list creation and the build runner to be useful must provide lead-gen catalogs/templates/actions/resources/topology in `core/config/organization-model.ts`; readiness is derived from those facts rather than a hand-authored requirements list.
 
 In external projects, pass the local list-action registry through the app factory and the tenant Organization Model through the authenticated shell:
 
@@ -425,6 +426,8 @@ Tenant-owned list-builder values belong in the main Organization Model:
 - action ids in the tenant action layer
 - workflow resources in the tenant resources map with ontology bindings and `primaryAction`
 - topology relationships in the tenant topology map
+- `sales.lead-gen.apiInterface` with `lifecycle: 'active'`, `readinessProfile: 'sales.lead-gen.api'`, and the scoped API resource ids when API-backed lead-gen actions are ready
+- lead-gen workflow resources that bind the CRM pipeline only when they intentionally hand off to CRM, plus a scoped topology grant from those lead-gen resources to `sales.crm.apiInterface`
 
 Use `core/config/extensions/*` for entity schema variants, not for list-builder stage catalogs or workflow bindings.
 

package/reference/scaffold/reference/contracts.md

@@ -306,6 +306,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
@@ -469,6 +499,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

package/reference/troubleshooting.mdx

@@ -152,7 +152,7 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ### PlatformToolError: timeout_error
 
-**Cause:** The platform tool call took longer than 60 seconds.
+**Cause:** The platform tool call took longer than 30 minutes (the `platform.call()` safety-net timeout; real per-tool enforcement is server-side).
 
 **Fix:**
 
@@ -173,9 +173,9 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ## Runtime Errors
 
-### Execution timeout (300s)
+### Execution timeout
 
-**Cause:** The entire workflow execution exceeded the 300-second limit.
+**Cause:** The entire execution exceeded the platform ceiling (2 hours by default; agents can override via `constraints.timeout`).
 
 **Fix:**