@nekostack/schema 1.0.0

package/dist/src/migrations/stub.js

@@ -0,0 +1,201 @@
+/**
+ * `stubMigration(opts)` — pure migration-stub generator (v0.8 Step 6).
+ *
+ * Produces a `MigrationStub` payload — a `suggestedPath` and the
+ * full file `content` for a new `*.migration.ts` file. The CLI is
+ * responsible for actually writing the file; this primitive is
+ * pure (no `fs.*`, no `import()`, no `process.*`, no `console.*`).
+ *
+ * The content follows the locked migration shape (Decision #5 +
+ * Decision #6):
+ *
+ *   - JSDoc provenance header on top, generated by this function.
+ *   - `import type { Migration } from "@nekostack/schema/cli";`
+ *     (NOT root — Decision #6 keeps the v0.8 surface package-internal).
+ *   - A `const migration: Migration<schemaId, from, to> = { ... }`
+ *     with a skeleton `transform` that throws "Not yet implemented".
+ *     Authors edit the body; v0.8 never invokes `transform`.
+ *   - `export default migration;` so `buildMigrationRegistry` /
+ *     `verifyMigrationProvenance` can find it via the
+ *     `MigrationSourceEntry.migration` field.
+ *
+ * `suggestedPath` follows the locked path convention
+ * (Decision #5):
+ *
+ *   <schema-dir>/migrations/<basename>.<from-slug>-to-<to-slug>.migration.ts
+ *
+ * with the slug rule reused verbatim from `v0.7 src/registry/handlers/generate.ts`:
+ *   `lowercase → non-alphanumeric runs collapse to "-" → trim`.
+ *
+ * Reusing v0.7's `slugify` shape means one slug rule across the
+ * whole package — and it handles prerelease/build version markers
+ * (`1.0.0-beta.1`, `2.0.0+build.5`) cleanly.
+ *
+ * Failure path: if either operand version is absent from the schema
+ * registry → `Result.failure` with `migration_missing_endpoint`
+ * (same code as Step 4's planner uses for the same condition).
+ */
+import { findSchema } from "../registry/build-registry.js";
+import { GENERATOR_VERSION } from "../generators/version.js";
+// =============================================================================
+// Public entry
+// =============================================================================
+export function stubMigration(opts) {
+    const fromEntry = findSchema(opts.schemaRegistry, opts.schemaId, opts.fromVersion);
+    const toEntry = findSchema(opts.schemaRegistry, opts.schemaId, opts.toVersion);
+    if (fromEntry === undefined || toEntry === undefined) {
+        return failure(missingEndpointIssue(opts.schemaId, opts.fromVersion, opts.toVersion, fromEntry === undefined, toEntry === undefined));
+    }
+    const suggestedPath = suggestedMigrationPathFor(fromEntry.sourcePath, opts.fromVersion, opts.toVersion);
+    const content = renderStubContent({
+        schemaId: opts.schemaId,
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+        fromIrHash: fromEntry.irHash,
+        toIrHash: toEntry.irHash,
+        fromSourceHash: fromEntry.sourceHash,
+        toSourceHash: toEntry.sourceHash,
+    });
+    const stub = {
+        schemaId: opts.schemaId,
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+        suggestedPath,
+        content,
+    };
+    return { success: true, data: stub };
+}
+// =============================================================================
+// Path convention (Decision #5)
+// =============================================================================
+/**
+ * Translate a schema's `sourcePath` plus a version pair into the
+ * locked migration-file path:
+ *
+ *     <schema-dir>/migrations/<basename>.<from-slug>-to-<to-slug>.migration.ts
+ *
+ * `basename` strips a `.schema.{ts,js,mts,cts}` suffix when present;
+ * falls back to "filename minus last extension" otherwise. Forward
+ * slashes are canonical even on Windows — the CLI normalizes back
+ * to platform separators on write.
+ *
+ * Exported so the CLI's `stub` verb can advertise the same path
+ * without re-deriving the rule.
+ */
+export function suggestedMigrationPathFor(sourcePath, fromVersion, toVersion) {
+    const normalized = sourcePath.replace(/\\/g, "/");
+    const lastSlash = normalized.lastIndexOf("/");
+    const dir = lastSlash >= 0 ? normalized.slice(0, lastSlash) : "";
+    const filename = lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized;
+    const basename = basenameOf(filename);
+    const stem = `${basename}.${slugify(fromVersion)}-to-${slugify(toVersion)}`;
+    const migrationsDir = dir === "" ? "migrations" : `${dir}/migrations`;
+    return `${migrationsDir}/${stem}.migration.ts`;
+}
+function basenameOf(filename) {
+    const schemaMatch = filename.match(/^(.+?)\.schema\.(ts|js|mts|cts)$/);
+    if (schemaMatch)
+        return schemaMatch[1];
+    const lastDot = filename.lastIndexOf(".");
+    return lastDot > 0 ? filename.slice(0, lastDot) : filename;
+}
+/**
+ * Same shape as v0.7's `src/registry/handlers/generate.ts` slugify().
+ * One slug rule across the whole package — Round-2 lock.
+ */
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function renderStubContent(input) {
+    // Pad keys to 16 columns so the value column lines up visually,
+    // matching the v0.7 generator-header convention. The parser is
+    // whitespace-tolerant so consumers may edit the alignment without
+    // breaking provenance reads.
+    const header = renderHeader({
+        schemaId: input.schemaId,
+        fromVersion: input.fromVersion,
+        toVersion: input.toVersion,
+        fromIrHash: input.fromIrHash,
+        toIrHash: input.toIrHash,
+        fromSourceHash: input.fromSourceHash,
+        toSourceHash: input.toSourceHash,
+        generator: "neko-schema-migrate-stub",
+        generatorVersion: GENERATOR_VERSION,
+    });
+    const literalSchemaId = JSON.stringify(input.schemaId);
+    const literalFrom = JSON.stringify(input.fromVersion);
+    const literalTo = JSON.stringify(input.toVersion);
+    return `${header}
+import type { Migration } from "@nekostack/schema/cli";
+
+const migration: Migration<${literalSchemaId}, ${literalFrom}, ${literalTo}> = {
+  schemaId: ${literalSchemaId},
+  from: ${literalFrom},
+  to: ${literalTo},
+  transform(input) {
+    // Author fills this in.
+    throw new Error("Not yet implemented");
+  },
+};
+
+export default migration;
+`;
+}
+function renderHeader(fields) {
+    const keys = [
+        "schemaId",
+        "fromVersion",
+        "toVersion",
+        "fromIrHash",
+        "toIrHash",
+        "fromSourceHash",
+        "toSourceHash",
+        "generator",
+        "generatorVersion",
+    ];
+    const colon = ":";
+    const targetWidth = Math.max(...keys.map((k) => k.length + colon.length));
+    const lines = [
+        "/**",
+        " * @migration by @nekostack/schema",
+        ...keys.map((k) => {
+            const label = `${k}${colon}`;
+            return ` * ${label.padEnd(targetWidth + 1)}${fields[k]}`;
+        }),
+        " *",
+        " * DO NOT REMOVE THE HEADER. Authors EDIT THE BODY.",
+        " */",
+    ];
+    return lines.join("\n");
+}
+// =============================================================================
+// Failure helpers
+// =============================================================================
+function failure(issue) {
+    return { success: false, issues: [issue] };
+}
+function missingEndpointIssue(schemaId, fromVersion, toVersion, fromMissing, toMissing) {
+    const missing = [];
+    if (fromMissing)
+        missing.push("from");
+    if (toMissing)
+        missing.push("to");
+    return {
+        code: "migration_missing_endpoint",
+        path: [],
+        message: `Cannot stub migration for \`${schemaId}\`: ` +
+            `${missing.join(", ")} version not in the schema registry ` +
+            `(from=${fromVersion}, to=${toVersion}).`,
+        severity: "error",
+        metadata: {
+            schemaId,
+            fromVersion,
+            toVersion,
+            missing,
+        },
+    };
+}
+//# sourceMappingURL=stub.js.map

package/dist/src/migrations/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../../src/migrations/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAQ7D,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,MAAM,UAAU,aAAa,CAC3B,IAAuB;IAEvB,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACnF,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAE/E,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,OAAO,CACZ,oBAAoB,CAClB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,SAAS,EACd,SAAS,KAAK,SAAS,EACvB,OAAO,KAAK,SAAS,CACtB,CACF,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,yBAAyB,CAC7C,SAAS,CAAC,UAAU,EACpB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,SAAS,CACf,CAAC;IACF,MAAM,OAAO,GAAG,iBAAiB,CAAC;QAChC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,SAAS,CAAC,MAAM;QAC5B,QAAQ,EAAE,OAAO,CAAC,MAAM;QACxB,cAAc,EAAE,SAAS,CAAC,UAAU;QACpC,YAAY,EAAE,OAAO,CAAC,UAAU;KACjC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAkB;QAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa;QACb,OAAO;KACR,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,gCAAgC;AAChC,gFAAgF;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,WAAmB,EACnB,SAAiB;IAEjB,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,QAAQ,GACZ,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IAChE,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;IAC5E,MAAM,aAAa,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG,aAAa,CAAC;IACtE,OAAO,GAAG,aAAa,IAAI,IAAI,eAAe,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB;IAClC,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACvE,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC,CAAC,CAAE,CAAC;IACxC,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CAAC,CAAS;IACxB,OAAO,CAAC;SACL,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAgBD,SAAS,iBAAiB,CAAC,KAAkB;IAC3C,gEAAgE;IAChE,+DAA+D;IAC/D,kEAAkE;IAClE,6BAA6B;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,0BAA0B;QACrC,gBAAgB,EAAE,iBAAiB;KACpC,CAAC,CAAC;IACH,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,OAAO,GAAG,MAAM;;;6BAGW,eAAe,KAAK,WAAW,KAAK,SAAS;cAC5D,eAAe;UACnB,WAAW;QACb,SAAS;;;;;;;;CAQhB,CAAC;AACF,CAAC;AAED,SAAS,YAAY,CACnB,MAA8B;IAE9B,MAAM,IAAI,GAAG;QACX,UAAU;QACV,aAAa;QACb,WAAW;QACX,YAAY;QACZ,UAAU;QACV,gBAAgB;QAChB,cAAc;QACd,WAAW;QACX,kBAAkB;KACV,CAAC;IACX,MAAM,KAAK,GAAG,GAAG,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG;QACZ,KAAK;QACL,oCAAoC;QACpC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAChB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC;YAC7B,OAAO,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,CAAC,CAAC;QACF,IAAI;QACJ,qDAAqD;QACrD,KAAK;KACN,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,SAAS,OAAO,CAAC,KAAY;IAC3B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,oBAAoB,CAC3B,QAAgB,EAChB,WAAmB,EACnB,SAAiB,EACjB,WAAoB,EACpB,SAAkB;IAElB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,WAAW;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO;QACL,IAAI,EAAE,4BAA4B;QAClC,IAAI,EAAE,EAAE;QACR,OAAO,EACL,+BAA+B,QAAQ,MAAM;YAC7C,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC;YAC3D,SAAS,WAAW,QAAQ,SAAS,IAAI;QAC3C,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE;YACR,QAAQ;YACR,WAAW;YACX,SAAS;YACT,OAAO;SACR;KACF,CAAC;AACJ,CAAC"}

package/dist/src/migrations/types.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Type definitions for the v0.8 schema-side migration surface.
+ *
+ * This module is **types only** — no functions, no constants beyond
+ * what TypeScript requires for the type definitions themselves. All
+ * runtime behavior (migration registry construction, chain planning,
+ * provenance verification, stub generation) lives in the sibling
+ * modules that import these types.
+ *
+ * Boundary recap (Master plan Decision #1, continued from v0.6 / v0.7):
+ * - `@nekostack/schema` is **pure** — no `fs.*`, no `import()`, no
+ *   `process.*`, no `console.*`. Takes data, returns data.
+ * - `@nekostack/cli` is the **filesystem shell** — walks
+ *   `*.migration.ts` files, loads them via `tsx`, reads source bytes,
+ *   writes stub files, owns stdout / stderr / exit codes.
+ *
+ * Re-exported from the package-internal integration subpath
+ * `@nekostack/schema/cli` (Master plan Decision #10) in a later
+ * sequencing step. Root `@nekostack/schema` does NOT expose these
+ * names.
+ *
+ * **Hard-locked v0.8 boundary**: nothing in this file mentions
+ * `apply`. Migration execution is deferred to v0.9+. The `transform`
+ * function on `Migration<...>` exists so the file shape is stable
+ * for the eventual apply phase, but v0.8 never invokes it.
+ */
+import type { Result } from "../errors/issue.js";
+import type { DiffSeverity } from "../registry/types.js";
+import type { Registry } from "../registry/types.js";
+/**
+ * The default export of a `*.migration.ts` file.
+ *
+ * The five type parameters cascade from coarsest to finest:
+ *
+ * - `SchemaId`     — string literal of the schema this migration
+ *                    targets (e.g. `"com.x.User"`).
+ * - `FromVersion`  — string literal of the source version
+ *                    (e.g. `"1.0.0"`).
+ * - `ToVersion`    — string literal of the destination version.
+ * - `Input`        — the static type of `s.output<FromSchema>`.
+ *                    Defaults to `unknown` so loosely-typed
+ *                    migrations still compile; consumers who want
+ *                    static safety pass the inferred type here.
+ * - `Output`       — the static type of `s.output<ToSchema>`.
+ *                    Defaults to `unknown`.
+ *
+ * v0.8 NEVER calls `transform`. The function signature exists so
+ * authors write a v0.9+-ready migration file in v0.8, but the
+ * planner / verifier / stub primitives only inspect provenance,
+ * not behavior.
+ */
+export interface Migration<SchemaId extends string = string, FromVersion extends string = string, ToVersion extends string = string, Input = unknown, Output = unknown> {
+    readonly schemaId: SchemaId;
+    readonly from: FromVersion;
+    readonly to: ToVersion;
+    /**
+     * The data transformation. **NEVER invoked by v0.8.** Authors
+     * write the body; v0.9+ runtime apply will execute it.
+     */
+    readonly transform: (input: Input) => Output;
+}
+/**
+ * Widest legal `Migration`. Useful as a registry value type and as
+ * the loaded-export shape of `MigrationSourceEntry.migration`.
+ */
+export type AnyMigration = Migration<string, string, string, unknown, unknown>;
+/**
+ * One discovered `*.migration.ts` source file, after the CLI has
+ * read its bytes and dynamic-imported the module via `tsx`.
+ *
+ * `migration` is the module's default export. The CLI is responsible
+ * for asserting the export shape (`{ schemaId, from, to, transform }`)
+ * before constructing this entry; the schema-side primitives assume
+ * the field is a valid `AnyMigration`.
+ *
+ * Mirrors the v0.7 `RegistrySourceEntry` shape so the walker
+ * pipeline composes cleanly.
+ */
+export interface MigrationSourceEntry {
+    readonly sourcePath: string;
+    readonly sourceText: string;
+    readonly migration: AnyMigration;
+}
+/**
+ * One indexed migration. Identity is the `(schemaId, fromVersion,
+ * toVersion)` triple per Decision #8. The four hash fields are
+ * **provenance binding**, not identity — they let the verifier
+ * detect when the migration was authored against a schema state
+ * that has since changed.
+ *
+ * `fromIrHash` / `toIrHash` come from the v0.2-format provenance
+ * header on the migration source file; `fromSourceHash` /
+ * `toSourceHash` come from the same header (v0.8 always emits them
+ * via the stub generator).
+ */
+export interface MigrationEntry {
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly fromIrHash: `sha256:${string}`;
+    readonly toIrHash: `sha256:${string}`;
+    readonly fromSourceHash: `sha256:${string}`;
+    readonly toSourceHash: `sha256:${string}`;
+    readonly sourcePath: string;
+    readonly migration: AnyMigration;
+}
+/**
+ * Three-level map: outer key is `schemaId`, middle key is the
+ * `fromVersion`, inner key is the `toVersion`. The shape supports
+ * two access patterns the planner needs:
+ *
+ * - **Exact lookup** by triple — `reg.get(id)?.get(from)?.get(to)`.
+ * - **All outgoing edges from a fromVersion** — `reg.get(id)?.get(from)`
+ *   yields the full `Map<toVersion, MigrationEntry>`, which is the
+ *   set of edges BFS needs to expand a node.
+ *
+ * `buildMigrationRegistry` is the only legitimate producer.
+ */
+export type MigrationRegistry = ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, MigrationEntry>>>;
+/**
+ * Free-form annotation on a `MigrationPlan`. Documents *why* the
+ * chain came out the way it did when the result isn't a simple
+ * "found the chain":
+ *
+ * - `over_specified` — the diff classifier said no migration is
+ *   required (`worstSeverity` is `null` or `cosmetic`), but a
+ *   migration is registered for the pair anyway. The plan still
+ *   succeeds with an empty chain; this note records the
+ *   discrepancy for the CLI to surface.
+ * - `additive_no_migration` — `worstSeverity` is `additive` and no
+ *   migration is registered. The plan succeeds with an empty chain;
+ *   this note records that a consumer review may be desired.
+ */
+export type PlanNote = {
+    readonly kind: "over_specified";
+    readonly migration: MigrationEntry;
+} | {
+    readonly kind: "additive_no_migration";
+    readonly worstSeverity: DiffSeverity;
+};
+/**
+ * The output of `planMigration`. Always carries the resolved
+ * `versionPath` and `worstSeverity` so consumers can see the diff
+ * that drove the decision, even when the chain is empty.
+ *
+ * Decision #10 maps `worstSeverity` to the chain requirement:
+ *
+ * - `null` / `"cosmetic"` — chain is empty.
+ * - `"additive"`           — chain is empty unless a migration is
+ *                            registered for the pair.
+ * - `"breaking"`           — chain is required; failure paths emit
+ *                            `migration_not_found` /
+ *                            `migration_chain_broken` /
+ *                            `migration_ambiguous_chain` on the
+ *                            `Result.failure` branch.
+ *
+ * `versionPath` always includes both endpoints. For an empty chain
+ * the array is `[fromVersion, toVersion]`.
+ */
+export interface MigrationPlan {
+    readonly schemaId: string;
+    readonly chain: readonly MigrationEntry[];
+    readonly versionPath: readonly string[];
+    readonly worstSeverity: DiffSeverity | null;
+    readonly notes: readonly PlanNote[];
+}
+/**
+ * Per-migration outcome of the two-hash provenance check, mirroring
+ * the v0.7 `FreshnessVerdict` shape for artifacts. The four-value
+ * mapping is Decision #9 of the v0.8 plan:
+ *
+ * - `bound`            — both `irHash` and `sourceHash` match at
+ *                        both endpoints. Migration is current.
+ * - `cosmetic_drift`   — `irHash` matches at both endpoints, but at
+ *                        least one `sourceHash` differs. Source was
+ *                        edited without semantic effect. CLI warns
+ *                        on stderr; exit code stays `SUCCESS`.
+ * - `drift`            — at least one endpoint's `irHash` differs
+ *                        from the schema registry. The migration
+ *                        was authored against a schema state that
+ *                        has since changed semantically. CLI exits
+ *                        `LOGICAL_FAILURE`.
+ * - `missing_endpoint` — one or both versions are not in the schema
+ *                        registry. Indicates a stale migration or a
+ *                        deleted schema version. CLI exits
+ *                        `LOGICAL_FAILURE`.
+ *
+ * The discriminated-union shape mirrors v0.7's `FreshnessVerdict`
+ * so downstream tooling can pattern-match on `status` uniformly.
+ */
+export type MigrationVerdict = {
+    readonly status: "bound";
+    readonly sourcePath: string;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+} | {
+    readonly status: "cosmetic_drift";
+    readonly sourcePath: string;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+} | {
+    readonly status: "drift";
+    readonly sourcePath: string;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+} | {
+    readonly status: "missing_endpoint";
+    readonly sourcePath: string;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+};
+/**
+ * Cumulative output of `verifyMigrationProvenance`. `verdicts` is
+ * one entry per registered migration in input order. `summary`
+ * is the per-status tally for header rendering.
+ */
+export interface VerificationResult {
+    readonly verdicts: readonly MigrationVerdict[];
+    readonly summary: {
+        readonly bound: number;
+        readonly cosmetic_drift: number;
+        readonly drift: number;
+        readonly missing_endpoint: number;
+    };
+}
+/**
+ * `stubMigration` produces a file *content* string and a
+ * `suggestedPath`. The CLI is responsible for the filesystem write;
+ * this primitive is pure.
+ *
+ * Mirrors `GeneratedArtifact` from v0.7 — same separation between
+ * planner output and CLI write step.
+ */
+export interface MigrationStub {
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly suggestedPath: string;
+    readonly content: string;
+}
+/**
+ * `listMigrationsHandler({ migrationRegistry })` — enumerate every
+ * `MigrationEntry`. Deterministic ordering is the handler's
+ * responsibility (sort by schemaId, then by fromVersion, then by
+ * toVersion).
+ */
+export interface MigrationListOpts {
+    readonly migrationRegistry: MigrationRegistry;
+}
+export type MigrationListResult = Result<{
+    readonly entries: readonly MigrationEntry[];
+}>;
+/**
+ * `planMigrationHandler({ schemaRegistry, migrationRegistry, ... })`
+ * — the diff-aware planner (Round-3 amendment). Receives BOTH
+ * registries plus the operand triple. Resolves endpoints in
+ * `schemaRegistry`, computes `worstSeverity` via `diffNodes`,
+ * severity-gates the chain requirement.
+ */
+export interface MigrationPlanOpts {
+    readonly schemaRegistry: Registry;
+    readonly migrationRegistry: MigrationRegistry;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+}
+export type MigrationPlanResult = Result<MigrationPlan>;
+/**
+ * `verifyMigrationsHandler({ schemaRegistry, migrationRegistry })`
+ * — provenance verification for every registered migration. Receives
+ * BOTH registries so `findSchema(schemaRegistry, ...)` can supply the
+ * current `irHash` / `sourceHash` for comparison against each
+ * migration's recorded values.
+ */
+export interface MigrationVerifyOpts {
+    readonly schemaRegistry: Registry;
+    readonly migrationRegistry: MigrationRegistry;
+}
+export type MigrationVerifyResult = Result<VerificationResult>;
+/**
+ * `stubMigrationHandler({ schemaRegistry, schemaId, fromVersion,
+ * toVersion })` — generate stub content. Does NOT consume a
+ * migration registry; the stub is brand new. Endpoint hashes come
+ * from `schemaRegistry` via `findSchema`.
+ */
+export interface MigrationStubOpts {
+    readonly schemaRegistry: Registry;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+}
+export type MigrationStubResult = Result<MigrationStub>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/migrations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/types.ts"],"names":[],"mappings":"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"}

package/dist/src/migrations/types.js

@@ -0,0 +1,28 @@
+/**
+ * Type definitions for the v0.8 schema-side migration surface.
+ *
+ * This module is **types only** — no functions, no constants beyond
+ * what TypeScript requires for the type definitions themselves. All
+ * runtime behavior (migration registry construction, chain planning,
+ * provenance verification, stub generation) lives in the sibling
+ * modules that import these types.
+ *
+ * Boundary recap (Master plan Decision #1, continued from v0.6 / v0.7):
+ * - `@nekostack/schema` is **pure** — no `fs.*`, no `import()`, no
+ *   `process.*`, no `console.*`. Takes data, returns data.
+ * - `@nekostack/cli` is the **filesystem shell** — walks
+ *   `*.migration.ts` files, loads them via `tsx`, reads source bytes,
+ *   writes stub files, owns stdout / stderr / exit codes.
+ *
+ * Re-exported from the package-internal integration subpath
+ * `@nekostack/schema/cli` (Master plan Decision #10) in a later
+ * sequencing step. Root `@nekostack/schema` does NOT expose these
+ * names.
+ *
+ * **Hard-locked v0.8 boundary**: nothing in this file mentions
+ * `apply`. Migration execution is deferred to v0.9+. The `transform`
+ * function on `Migration<...>` exists so the file shape is stable
+ * for the eventual apply phase, but v0.8 never invokes it.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/migrations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/src/migrations/verify-provenance.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `verifyMigrationProvenance(opts)` — per-migration two-hash
+ * provenance verifier (v0.8 Step 5).
+ *
+ * For every `MigrationEntry` in the migration registry, compares
+ * the migration's recorded `(fromIrHash, toIrHash, fromSourceHash,
+ * toSourceHash)` against the current schema registry's
+ * `findSchema(...).irHash` / `.sourceHash` for the same versions.
+ * Emits one `MigrationVerdict` per migration plus a per-status
+ * summary on the success branch.
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `process.*`, no
+ * `console.*`. **Never invokes `migration.transform`** — verification
+ * is a `provenance-says-what-it-says` check, not a behavior check.
+ * Transform execution is deferred to v0.9+.
+ *
+ * Verdict mapping (Decision #9 — mirrors the v0.7 two-hash
+ * freshness matrix):
+ *
+ *   | irHash match | sourceHash match | verdict           |
+ *   |--------------|-----------------|-------------------|
+ *   | both         | both            | `bound`           |
+ *   | both         | at least one ≠  | `cosmetic_drift`  |
+ *   | at least one ≠ | (any)         | `drift`           |
+ *   | endpoint absent | n/a          | `missing_endpoint`|
+ *
+ * Result-envelope rules:
+ *
+ *   - Every verdict is recorded in `verdicts[]` regardless of status.
+ *   - `summary` carries per-status counts.
+ *   - `Result.success` when every verdict is `bound` or
+ *     `cosmetic_drift` (no `drift` and no `missing_endpoint`).
+ *     `cosmetic_drift` is warning-class and does NOT fail the run.
+ *   - `Result.failure` with one `Issue` per `drift` / `missing_endpoint`
+ *     verdict otherwise. The CLI dispatcher (Step 9 handler / Step 22
+ *     verb) maps to `LOGICAL_FAILURE`.
+ *
+ * Deterministic iteration: registry entries are visited in
+ * `(schemaId, fromVersion, toVersion)` lexicographic order so the
+ * `verdicts[]` array shape is stable regardless of how the input
+ * registry was built. Downstream tooling (CLI pretty/JSON output)
+ * relies on the order being predictable across runs.
+ */
+import type { MigrationVerifyOpts, MigrationVerifyResult } from "./types.js";
+export declare function verifyMigrationProvenance(opts: MigrationVerifyOpts): MigrationVerifyResult;
+//# sourceMappingURL=verify-provenance.d.ts.map

package/dist/src/migrations/verify-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-provenance.d.ts","sourceRoot":"","sources":["../../../src/migrations/verify-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,KAAK,EAIV,mBAAmB,EACnB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,mBAAmB,GACxB,qBAAqB,CAwBvB"}