# constants

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The constants module owns the single source of truth for the current schema
version of `@suaveplan/control-surface-schema`. Every other module — the
Zod schemas, the validator, the upgrade engine, the migration registry —
imports `CURRENT_SCHEMA_VERSION` from this file so that bumping a release
touches exactly one literal. The version drives both the strict-root Zod
literal check and the loop-termination condition inside `upgradeSurface`.

## Features

- Single exported value `CURRENT_SCHEMA_VERSION` of literal type `"0.1.0"`.
- Companion `CurrentSchemaVersion` type alias for use in API surfaces that
  pin a parameter to the current release.
- Zero runtime dependencies — pure const.

## Usage: Basic Example

```ts
import { CURRENT_SCHEMA_VERSION } from "@suaveplan/control-surface-schema";

const draft = {
    id: "abc",
    name: "draft",
    version: CURRENT_SCHEMA_VERSION,
    createdAt: Date.now(),
    updatedAt: Date.now(),
    skin: { id: "default" },
    root: {
        type: "group",
        id: "root",
        layout: { kind: "absolute" },
        transform: { position: { x: 0, y: 0 } },
        children: [],
    },
} as const;
```

## Usage: Advanced Example

Use the literal type as a generic parameter for a build-time check:

```ts
import {
    CURRENT_SCHEMA_VERSION,
    type CurrentSchemaVersion,
    upgradeSurface,
} from "@suaveplan/control-surface-schema";

declare function persistAtCurrent<V extends CurrentSchemaVersion>(
    version: V,
): void;

const upgraded = upgradeSurface(rawDocFromDisk);
persistAtCurrent(upgraded.version as CurrentSchemaVersion);
// The signature pins the call site to whatever version this build emits;
// a stale literal becomes a typecheck error at the call site.
```

## API Reference

- `CURRENT_SCHEMA_VERSION` — readonly string literal `"0.1.0"`.
- `type CurrentSchemaVersion` — typeof `CURRENT_SCHEMA_VERSION`.

## Implementation Notes

The version literal is intentionally narrow (`as const`) so consumer code
can rely on type narrowing in switch statements over versioned documents.
A breaking change to the schema MUST bump this constant AND register the
forward migration before the release ships; the pre-publish gate fails if
`validateSurface` produces a different version than `CURRENT_SCHEMA_VERSION`
on the same document `upgradeSurface` returned, which catches missed bumps.
Consumers that hard-code the literal in their own typed shapes should
import the type alias rather than re-derive it, so a future schema
version bump only requires updating the version string in this file plus
the registered migration in `src/upgrade/upgrade.ts`. The constant lives
outside the schema module so circular imports between Zod schemas and the
upgrade pipeline never form.