Source of truth: ADR-016 — SDK 1.0 Stability Promise (Accepted 2026-05-25).

Phase: this file is part of Phase 2.1 of the Module Developer Platform initiative — the SDK 1.0 surface lockdown. It tells external developers what they can rely on across SDK majors.

Three tiers

Tier	Promise	How marked
@stable	Semver-bound. No breaking changes within a major. Deprecation requires 6 months notice.	JSDoc tag at the barrel level OR per-export
@experimental	May change or be removed in any release. Not bound by semver. CHANGELOG calls out experimental changes; no advance notice required.	JSDoc tag at the barrel OR per-export
@internal	Not exported. May be deleted at any time.	Underscore-prefixed names + omitted from dist/index.d.ts

Anything not explicitly tagged @experimental or @internal is @stable by default.

SDK 1.0 surface map

@stable (semver-bound)

These are the parts you can build your module on without expecting churn:

• @tv/extension-sdk/manifest — manifest schema, validator, scaffolders, checkExposes
• @tv/extension-sdk/context — PlatformContext runtime types
• @tv/extension-sdk/events — event catalog, envelope, subjects
• @tv/extension-sdk/api — PlatformApiClient types
• @tv/extension-sdk/react — <PlatformProvider>, usePlatformContext, useBuilding, useCurrentUser, useOptionalBuilding
• @tv/extension-sdk/nestjs — @ModuleCapability(), @RequiresLicense() decorators
• @tv/extension-sdk/testing — createMockPlatformContext
• @tv/extension-sdk/permissions — extractCatalog, extractCatalogFromFile, PermissionCatalog, SubjectEntry, PermissionAction
• The tv-sdk CLI commands: validate, check-exposes, init-manifest, init-module, write-version, snapshot-permissions
• The published JSON artifacts: manifest.schema.json, permissions.snapshot.json

@experimental (may change without notice)

These are powerful but still iterating — use them, but expect to track changes:

• @tv/extension-sdk/heartbeat — startHeartbeat() API and cadence/jitter contract
• @tv/extension-sdk/version-check — checkForUpdate, isNewerVersion, depends on version.json semantics
• @tv/extension-sdk/sandbox — CLI subcommand family (surface may grow during Phase 1a rollout)
• Manifest schema field: PayloadContract — consumer-driven event pact (Sprint 26 work)
• Manifest schema field: McpToolDeclaration.permissions — LLM tool gating mechanism
• CLI commands: tv-sdk check-events, tv-sdk check-api, tv-sdk check-pact, tv-sdk snapshot-events, tv-sdk snapshot-api
• React: useVersionCheck, <UpdatePrompt> — depend on version.json semantics
• NestJS: TvHeartbeatModule.register() — depends on heartbeat cadence contract

@internal

No exports are @internal at present. The convention is reserved for future use.

Deprecation policy

• @stable: minimum 6 months between the JSDoc @deprecated marker landing and the symbol being removed. Removal requires a major version bump. CHANGELOG entry on both events.
• @experimental: can be removed in any release with a CHANGELOG entry. No advance notice required.
• @internal: silent removal allowed.

Graduation: @experimental → @stable

An experimental symbol may graduate when:

1. It has been in @experimental for at least 6 months.
2. At least 2 internal modules consume it.
3. It has not received a breaking change in the trailing minor release.

Graduation is a deliberate decision and is announced in the CHANGELOG.

Supported versions

• Latest stable major: full support — security fixes, bug fixes, additive features.
• Previous stable major: security fixes only, for 12 months after the next major ships.
• Older majors: no support.

So when 1.x ships, support is full. When 2.x ships 12 months later, 1.x falls to security-only for 12 months and then reaches end-of-life.

How to read the source

Every barrel-level index.ts for an SDK subpath carries a JSDoc tag at the top:

/**
 * @stable
 *
 * <description>
 */

For per-export deviations from the barrel default, the symbol's own JSDoc carries the override:

/**
 * @experimental
 *
 * <reason this specific symbol is more volatile than its siblings>
 */
export const PayloadContract = z.object({ ... });

When in doubt, search the source for @experimental to see the full set of symbols not bound by semver.

Stability promise: active as of 1.0.0

@tv/extension-sdk@1.0.0 shipped 2026-05-30. The promise above is now binding:

• @stable exports won't break within the 1.x major. Removal requires a 6-month @deprecated window plus a major bump.
• @experimental exports may still change in any release; the CHANGELOG calls them out.

Build your module against @stable symbols and you can rely on them across every 1.x release.

Questions or proposals

If you want a tier change for a specific symbol, open an issue on the SDK repo with the symbol name + your migration cost estimate. Tier changes are reviewed against the criteria above.