Platform-builder control plane

Platform builders can onboard their own customer organizations without proxying every runtime request. The management plane provisions tenant lineages and mints short-lived, actor-bound runtime credentials; the runtime still enforces the app’s write policies and projections on every request.

This preview surface requires the 0.5.9-preview.8 management/runtime contract and @tarski/client 0.8.0 or later. Discover it before enabling a signup path:

const capabilities = await management.api.discoverPlatformBuilderCapabilities({
  operation: 'discover_platform_builder_capabilities',
  operationContract:
    'tarski-client-sdk-api:v1/discover_platform_builder_capabilities',
});

Treat a typed unavailable capability as a deployment mismatch. Do not fall back to an undocumented route or a platform operator’s interactive credential.

Tokens, lineages, and revocation

Create a separate SDK client pointed at the management-plane origin. Its credential must stay in your trusted service backend and must never reach a browser:

import { createTarskiClient } from '@tarski/client';

const management = createTarskiClient({
  baseUrl: process.env.TARSKI_MANAGEMENT_ORIGIN!,
  token: () => process.env.TARSKI_PLATFORM_BUILDER_TOKEN!,
});

Provision one lineage with an idempotency key. An optional genesis batch contains observations only:

const provisioned = await management.api.provisionTenantLineage({
  operation: 'provision_tenant_lineage',
  operationContract: 'tarski-client-sdk-api:v1/provision_tenant_lineage',
  body: {
    organization_id: 'org_acme',
    tenant_id: 'tenant-acme',
    app_id: 'truepenny',
    environment_id: 'production',
    cell_id: 'cell-1',
    lineage_id: 'tenant-acme:user-42:primary',
    idempotency_key: 'signup:user-42',
    genesis_observations: [{
      kind: 'account.created',
      payload: { user_id: 'user-42' },
    }],
  },
  idempotency: { idempotency_key: 'signup:user-42' },
});

Tenant lineage prefixes are stored on the tenant and checked before dispatch to a runtime cell. Reusing the same idempotency key and canonical request returns the original receipt; conflicting reuse fails. Facts, intents, effects, provenance, and world documents are rejected as genesis input.

Use the generated methods for the remaining lifecycle:

SDK method	Route	Purpose
listTenantLineages	GET /api/v0/lineages	List lineages visible in the caller’s organization and tenant scope
issueDelegatedToken	POST /api/v0/tokens/delegated	Mint one actor-bound runtime credential
listDelegatedTokens	GET /api/v0/tokens/delegated	List redacted token metadata
rotateDelegatedToken	POST /api/v0/tokens/delegated/rotate	Replace one credential without widening its scope
revokeDelegatedToken	POST /api/v0/tokens/delegated/revoke	Revoke one credential
revokeDelegatedActorTokens	POST /api/v0/tokens/delegated/revoke-all	Sign one actor out everywhere in the selected tenant

Token issue and rotation return plaintext exactly once and report secret_material_persisted: false. Listings expose only digests and redacted metadata. Store the returned credential in your application’s secret/session system; Tarski cannot recover it later.

Revocation returns only after the target runtime cell acknowledges the revocation epoch. The receipt reports propagation state. This synchronous boundary means a successful “sign out everywhere” response is stronger than waiting for token expiry.

Authority boundaries

• The management credential is organization- and route-scoped. Request payloads cannot select another organization.
• A delegated token carries actor context, tenant, issuing authority, delegation chain, runtime scope, and expiry. The runtime constructs trusted context from the verified token; it never trusts matching payload fields.
• A runtime token cannot provision lineages, mint credentials, or deploy packages.
• A cloud automation token can deploy and promote packages but cannot impersonate an end user or mint delegated runtime credentials.
• Support snapshots and management listings are redacted and tenant-filtered.