# 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.
