Initial Commit

packages/media/audio/control-surface-schema/src/constants/constants.md

@@ -0,0 +1,84 @@
+# 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.