@platforma-sdk/block-tools 2.13.0 → 2.14.0

package/src/v2/build_kind_dist.ts

@@ -0,0 +1,104 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { util } from "@platforma-sdk/package-builder-lib";
+import { calculateSha256 } from "../util";
+import type { KindManifest, KindManifestFileInfo } from "./registry/schema_kinds";
+
+export interface BuildKindDistOptions {
+  /** Kind package directory (the dir containing `package.json`, `src/`, `dist/`). */
+  modulePath?: string;
+  /** Source directory hashed into `sourceHash`, relative to `modulePath`. */
+  srcDir?: string;
+  /** Output directory holding the compiled bundle and receiving `manifest.json`. */
+  dst?: string;
+  /** Compiled entry file name inside `dst` (rolldown emits `kind.js`). */
+  entryFileName?: string;
+}
+
+// The on-wire kind manifest shape (identity, per-file info, and the manifest
+// itself) is owned by the registry schema module — the single source of truth
+// shared by the build side (this producer) and the registry read/write path.
+export type {
+  KindManifest,
+  KindManifestIdentity,
+  KindManifestFileInfo,
+} from "./registry/schema_kinds";
+
+export const KindManifestFile = "manifest.json";
+
+/**
+ * Read the kind's identity from its own `package.json` — the SINGLE source of
+ * truth. The block-kind build bakes the SAME `{name, version}` into the emitted
+ * bundle (via `define`), so the manifest identity here and the runtime
+ * descriptor's identity are guaranteed to agree. Reading package.json directly
+ * (rather than importing the ESM bundle) keeps this authoritative and free of a
+ * dynamic-import dependency on the compiled output.
+ */
+async function readKindPackageIdentity(
+  modulePath: string,
+): Promise<{ name: string; version: string }> {
+  const pkgPath = path.resolve(modulePath, "package.json");
+  let raw: string;
+  try {
+    raw = await fsp.readFile(pkgPath, "utf-8");
+  } catch {
+    throw new Error(`Cannot read kind package.json at ${pkgPath}.`);
+  }
+  const pkg = JSON.parse(raw) as { name?: unknown; version?: unknown };
+  if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
+    throw new Error(`Kind package.json at ${pkgPath} must declare string "name" and "version".`);
+  }
+  return { name: pkg.name, version: pkg.version };
+}
+
+/**
+ * Commander-free core: bundle-in, manifest-out. Reads the kind's npm package
+ * `name`/`version` from its `package.json`, computes one sha256 over the `src/`
+ * tree (upper-case), and writes `manifest.json` LAST as the commit marker (the
+ * build_dist.ts convention: readers treat the manifest's presence as "the dist
+ * is complete").
+ *
+ * Shaped commander-free so the deferred publish-time source-hash guard can
+ * `import` and reuse both the hash computation and this manifest shape without
+ * CLI coupling.
+ */
+export async function buildKindDist(opts: BuildKindDistOptions = {}): Promise<KindManifest> {
+  const modulePath = path.resolve(opts.modulePath ?? ".");
+  const srcDir = path.resolve(modulePath, opts.srcDir ?? "src");
+  const dst = path.resolve(modulePath, opts.dst ?? "dist");
+  const entryFileName = opts.entryFileName ?? "kind.js";
+
+  const { name, version } = await readKindPackageIdentity(modulePath);
+
+  const sourceHash = util.hashDirSync(srcDir).digest("hex").toUpperCase();
+
+  const artifactNames = [entryFileName, "kind.d.ts"];
+  const files: KindManifestFileInfo[] = [];
+  for (const artifact of artifactNames) {
+    const abs = path.resolve(dst, artifact);
+    let bytes: Buffer;
+    try {
+      bytes = await fsp.readFile(abs);
+    } catch (err: unknown) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        throw new Error(
+          `Kind build is incomplete: ${artifact} is missing from ${dst}. Run the kind's build before building its manifest.`,
+        );
+      }
+      throw err;
+    }
+    files.push({ name: artifact, size: bytes.length, sha256: await calculateSha256(bytes) });
+  }
+
+  const manifest: KindManifest = {
+    schema: "v1",
+    kind: { name, version },
+    sourceHash,
+    files,
+    timestamp: Date.now(),
+  };
+
+  // manifest.json written LAST — commit marker.
+  await fsp.writeFile(path.resolve(dst, KindManifestFile), JSON.stringify(manifest));
+  return manifest;
+}

package/src/v2/from_pack_v2.test.ts

@@ -80,12 +80,12 @@ test("loadPackDescriptionFromManifest resolves manifest entries to absolute FS p
   expect(existsSync(description.components.ui.folder)).toBe(true);
 });
 
-test("loadPackDescriptionFromManifest works against a real packed sum-numbers-v3", async () => {
+test("loadPackDescriptionFromManifest works against a real packed sum-numbers", async () => {
   // Runs when the block has been built+packed; skips gracefully in a clean
   // checkout where block-pack/ is gitignored. Guards against manifest-shape
   // drift the hermetic fixture above can't catch.
   const here = path.dirname(fileURLToPath(import.meta.url));
-  const real = path.resolve(here, "../../../../etc/blocks/sum-numbers-v3/block");
+  const real = path.resolve(here, "../../../../etc/blocks/sum-numbers/block");
   if (!existsSync(path.join(real, "block-pack", "manifest.json"))) return;
 
   const description = await loadPackDescriptionFromManifest(path.join(real, "block-pack"));

package/src/v2/index.ts

@@ -1,5 +1,9 @@
 export * from "./model";
 export * from "./build_dist";
+export * from "./build_kind_dist";
+export * from "./publish-block";
+export * from "./kind/resolve-refs";
+export * from "./kind/version-match";
 export * from "./source_package";
 export * from "./resolve_to_registry";
 export * from "./registry";

package/src/v2/kind/resolve-refs.ts

@@ -0,0 +1,150 @@
+import fsp from "node:fs/promises";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { formatKindRef, type BlockKindReference } from "@milaboratories/pl-model-common";
+import type { BlockPackManifest } from "@milaboratories/pl-model-middle-layer";
+import { KindManifest } from "../registry/schema_kinds";
+import type { RelativeContentReader } from "../model";
+
+/**
+ * Kind → block ref resolution. The single reader of the facade's kind dependency.
+ *
+ * A kind is a fourth block component alongside model, ui and workflow, and the facade
+ * depends on it DIRECTLY — not transitively through one of the other three. Its concrete
+ * version is not read from that dependency either: the facade's range may be
+ * `workspace:*` or `catalog:`, so the authority is the kind's own built manifest.
+ *
+ * Keeping every "how the facade names and locates its kind" assumption in this one module
+ * means the publish gate and the orchestrator never touch dependency-shape details.
+ */
+
+/** npm package-name suffix marking a package as a block kind (schema_kinds convention). */
+const KIND_PACKAGE_SUFFIX = ".kind";
+
+/**
+ * The kind reference the MODEL was compiled against, as baked into the block manifest
+ * when the block was built.
+ *
+ * It sits at the TOP LEVEL of the description — `description.kind`, a `{name}@{version}`
+ * string (declared in `block_description.ts`, read back by the registry's reconciler) —
+ * rather than under the model component, because the build lifts the model's
+ * container-level `kind` up when it writes the manifest. `undefined` means the block
+ * declares no kind.
+ */
+export function readModelCompiledKindRef(
+  manifest: BlockPackManifest,
+): BlockKindReference | undefined {
+  return manifest.description.kind;
+}
+
+/** A kind dependency as declared in the facade's `package.json`. */
+export interface FacadeKindDependency {
+  /** npm package name of the kind (ends in `.kind`). */
+  npmName: string;
+  /** Raw version range as written in `package.json` (e.g. `^1.2.3`, `workspace:*`). */
+  range: string;
+}
+
+/**
+ * The facade-side kind dependency, read from the facade's `package.json`.
+ *
+ * The facade depends on its kind DIRECTLY: the `.kind`-suffixed entry is a direct
+ * dependency of the facade, not something reached transitively through
+ * `model/package.json`. We scan both `dependencies` and
+ * `devDependencies` for the single `.kind` entry — the slim facade keeps the
+ * kind (like its model/ui/workflow siblings) as a build-time `workspace:*`
+ * devDep, and its concrete version is resolved from the kind's built manifest
+ * downstream, so the range written here (`workspace:*`/`catalog:`/a semver
+ * range) is not load-bearing.
+ *
+ * Returns `undefined` when no kind dependency is declared.
+ */
+export function readFacadeKindDependency(facadeDir: string): FacadeKindDependency | undefined {
+  const pkgPath = path.join(facadeDir, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+  const deps = { ...pkg.devDependencies, ...pkg.dependencies };
+  const entry = Object.entries(deps).find(([name]) => name.endsWith(KIND_PACKAGE_SUFFIX));
+  if (!entry) return undefined;
+  return { npmName: entry[0], range: entry[1] };
+}
+
+/**
+ * Resolved, publishable kind artifacts: the concrete reference, the kind's
+ * content manifest, and a reader rooted at the kind's `dist/` folder.
+ */
+export interface ResolvedFacadeKind {
+  /** Concrete `{name}@{version}` reference of the kind the facade actually ships. */
+  ref: BlockKindReference;
+  /** The kind content manifest (`build_kind_dist` output) read from the kind's dist. */
+  manifest: KindManifest;
+  /** Reads the manifest's `files[].name` relative to the kind's `dist/`. */
+  fileReader: RelativeContentReader;
+}
+
+/**
+ * Resolve the facade's kind dependency to concrete publishable artifacts.
+ *
+ * Resolves the kind npm package from the facade's perspective, reads its
+ * built `dist/manifest.json` (the authoritative concrete version — the facade
+ * `package.json` range may be `workspace:*`/`catalog:` and carry no concrete
+ * version), and returns a `dist/`-rooted file reader for `publishKind`.
+ *
+ * The concrete version comes from the built manifest, so a `workspace:*`/`catalog:`
+ * range in the facade's `package.json` resolves cleanly. Resolution uses standard node resolution from the facade dir; if the
+ * package or its manifest cannot be found it throws with a pointed message
+ * rather than silently skipping.
+ */
+export async function resolveFacadeKind(
+  facadeDir: string,
+  npmName: string,
+): Promise<ResolvedFacadeKind> {
+  const kindPkgDir = resolveKindPackageDir(facadeDir, npmName);
+  const distDir = path.join(kindPkgDir, "dist");
+
+  let manifestRaw: string;
+  try {
+    manifestRaw = await fsp.readFile(path.join(distDir, "manifest.json"), "utf-8");
+  } catch {
+    throw new Error(
+      `Kind package "${npmName}" resolved to ${kindPkgDir} but has no dist/manifest.json. ` +
+        `Build the kind (ts-builder build --target block-kind && block-tools build-kind-manifest) before publishing.`,
+    );
+  }
+  const manifest = KindManifest.parse(JSON.parse(manifestRaw));
+
+  const ref = formatKindRef({ name: manifest.kind.name, version: manifest.kind.version });
+  const fileReader: RelativeContentReader = async (relativePath) =>
+    Buffer.from(await fsp.readFile(path.resolve(distDir, relativePath)));
+
+  return { ref, manifest, fileReader };
+}
+
+/** Resolve the directory of an installed kind npm package from the facade's location. */
+function resolveKindPackageDir(facadeDir: string, npmName: string): string {
+  const req = createRequire(path.join(facadeDir, "package.json"));
+  // Prefer the package's own package.json (deterministic package root).
+  try {
+    return path.dirname(req.resolve(`${npmName}/package.json`));
+  } catch {
+    // Fall back to the package entry point, then walk up to the folder holding package.json.
+    try {
+      let dir = path.dirname(req.resolve(npmName));
+      for (let i = 0; i < 6; i++) {
+        if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    } catch {
+      /* fall through to the throw below */
+    }
+    throw new Error(
+      `Cannot resolve kind package "${npmName}" from ${facadeDir}. ` +
+        `Ensure it is installed as a dependency of the facade.`,
+    );
+  }
+}

package/src/v2/kind/version-match.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "vitest";
+import { formatKindRef } from "@milaboratories/pl-model-common";
+import { checkKindVersionMatch, KindVersionMismatchError } from "./version-match";
+
+/**
+ * `checkKindVersionMatch` is the pure pre-publish gate: the model's
+ * compiled-against kind and the facade's declared kind must be the SAME kind at
+ * the SAME version. Success is "did not throw". The full `{org, name}` identity is
+ * compared, not just the terminal name.
+ */
+describe("checkKindVersionMatch", () => {
+  const name = "@platforma-open/milaboratories.demo.kind";
+
+  test("identical name + version passes", () => {
+    expect(() =>
+      checkKindVersionMatch(
+        formatKindRef({ name, version: "1.2.3" }),
+        formatKindRef({ name, version: "1.2.3" }),
+      ),
+    ).not.toThrow();
+  });
+
+  test("same kind, different version -> version mismatch", () => {
+    expect(() =>
+      checkKindVersionMatch(
+        formatKindRef({ name, version: "1.2.3" }),
+        formatKindRef({ name, version: "1.2.4" }),
+      ),
+    ).toThrow(KindVersionMismatchError);
+  });
+
+  test("different name segment at the same version -> name mismatch", () => {
+    expect(() =>
+      checkKindVersionMatch(
+        formatKindRef({ name: "@platforma-open/milaboratories.demo.kind", version: "1.2.3" }),
+        formatKindRef({ name: "@platforma-open/milaboratories.other.kind", version: "1.2.3" }),
+      ),
+    ).toThrow(KindVersionMismatchError);
+  });
+
+  test("different org at the same version -> name mismatch (org IS compared)", () => {
+    expect(() =>
+      checkKindVersionMatch(
+        formatKindRef({ name: "@platforma-open/milaboratories.demo.kind", version: "1.2.3" }),
+        formatKindRef({ name: "@platforma-open/acme.demo.kind", version: "1.2.3" }),
+      ),
+    ).toThrow(KindVersionMismatchError);
+  });
+
+  test("an incidental npm-scope difference is normalized away", () => {
+    // Scoped vs. bare npm name: `npmNameToKindPath` drops the scope, so both
+    // resolve to the same `{org, name}` and the same kind matches.
+    expect(() =>
+      checkKindVersionMatch(
+        formatKindRef({ name: "@platforma-open/milaboratories.demo.kind", version: "1.2.3" }),
+        formatKindRef({ name: "milaboratories.demo.kind", version: "1.2.3" }),
+      ),
+    ).not.toThrow();
+  });
+});

package/src/v2/kind/version-match.ts

@@ -0,0 +1,55 @@
+import { parseKindRef, type BlockKindReference } from "@milaboratories/pl-model-common";
+import { npmNameToKindPath } from "../registry/schema_kinds";
+
+/**
+ * Thrown when the kind version the model was compiled against does not match
+ * the kind version the facade ships. Typed so the publish command (and future
+ * callers) can distinguish this hard-fail from generic errors.
+ */
+export class KindVersionMismatchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "KindVersionMismatchError";
+  }
+}
+
+/**
+ * Pure pre-publish gate: assert the model's compiled-against kind and the
+ * facade's declared kind are the same kind at the same version. Throws
+ * {@link KindVersionMismatchError} on mismatch; success is "did not throw".
+ *
+ * No I/O — both inputs are already-resolved `{name}@{version}` references, so a
+ * mismatch aborts before any S3 write (a strict superset of "abort before the
+ * facade publish"). Reuses the SINGLE `{name}@{version}` codec `parseKindRef`
+ * from `block_kind_ref.ts` (§3) — it is NOT redefined here.
+ *
+ * @param modelKindRef  reference the model was compiled against (`description.kind`)
+ * @param facadeKindDep concrete reference the facade ships (from resolve-refs)
+ */
+export function checkKindVersionMatch(
+  modelKindRef: BlockKindReference,
+  facadeKindDep: BlockKindReference,
+): void {
+  const m = parseKindRef(modelKindRef);
+  const f = parseKindRef(facadeKindDep);
+
+  // Version is the load-bearing comparison. Exact-match, no semver range: the
+  // facade reference is already normalized to a concrete version by resolve-refs
+  // (which resolves `workspace:*`/`catalog:` via the kind's built manifest), so
+  // a range never reaches here.
+  if (m.version !== f.version) {
+    throw new KindVersionMismatchError(
+      `Kind version mismatch: model compiled against ${modelKindRef}, ` +
+        `facade declares ${facadeKindDep}. Rebuild the model against the declared kind.`,
+    );
+  }
+
+  const mLoc = npmNameToKindPath(m.name);
+  const fLoc = npmNameToKindPath(f.name);
+  if (mLoc.org !== fLoc.org || mLoc.name !== fLoc.name) {
+    throw new KindVersionMismatchError(
+      `Kind name mismatch: model compiled against ${modelKindRef}, ` +
+        `facade declares ${facadeKindDep}.`,
+    );
+  }
+}

package/src/v2/model/block_description.ts

@@ -22,7 +22,14 @@ export type BlockPackDescriptionAbsolute = BlockPackDescription<
  * Resolves a raw `package.json`-form block-pack description against the
  * module root: workflow/model/ui paths via node module resolution, text and
  * binary fields in `meta` via `mapLocalToAbsolute`. Reads the resolved model
- * file to extract feature flags from its `BlockConfigContainer`.
+ * file to extract feature flags and the kind reference from its
+ * `BlockConfigContainer`.
+ *
+ * Both of those come from the built model rather than from `package.json`,
+ * because both are decided when the model is compiled. Carrying the kind here
+ * means a description means the same thing whichever side it was loaded from —
+ * a manifest already records it, and a caller should not have to know that a
+ * source package does not and re-read the model to find out.
  */
 export async function resolveBlockPackDescription(
   raw: BlockPackDescriptionRaw,
@@ -30,14 +37,18 @@ export async function resolveBlockPackDescription(
 ): Promise<BlockPackDescriptionAbsolute> {
   const components = resolveBlockComponents(raw.components, root);
   const meta = await resolveBlockPackMeta(raw.meta, root);
-  const cfg = extractConfigGeneric(
-    JSON.parse(await fsp.readFile(components.model.file, "utf-8")) as BlockConfigContainer,
-  );
+  const container = JSON.parse(
+    await fsp.readFile(components.model.file, "utf-8"),
+  ) as BlockConfigContainer;
+  const cfg = extractConfigGeneric(container);
   return {
     ...raw,
     components,
     meta,
     featureFlags: cfg.featureFlags,
+    // The kind sits at the container level, above the render envelope, so it
+    // survives `extractConfigGeneric` normalizing that envelope away.
+    ...(container.kind !== undefined ? { kind: container.kind } : {}),
   };
 }
 

package/src/v2/publish-block.ts

@@ -0,0 +1,60 @@
+import type { BlockPackManifest } from "@milaboratories/pl-model-middle-layer";
+import type { BlockRegistryV2 } from "./registry/registry";
+import type { RelativeContentReader } from "./model";
+import {
+  readModelCompiledKindRef,
+  readFacadeKindDependency,
+  resolveFacadeKind,
+} from "./kind/resolve-refs";
+import { checkKindVersionMatch } from "./kind/version-match";
+
+/**
+ * Publish a block package, kind-first.
+ *
+ * This is the single forward-compat seam the deferred kind/template phases
+ * extend. It sequences exactly three steps around the existing facade publish:
+ *
+ *   1. resolve both kind refs — every assumption about how the facade names and locates
+ *      its kind lives in `resolve-refs`, so this step has no shape details of its own,
+ *   2. run the pure version-match gate — hard-fails before ANY S3 write,
+ *   3. `publishKind` (kind content → `kinds/` tree, idempotent, source-hash
+ *      guarded), then
+ *   4. `publishPackage` — the facade block, byte-for-byte unchanged.
+ *
+ * A block that declares no kind (`description.kind` absent) publishes exactly as
+ * before: the gate and `publishKind` are skipped entirely.
+ *
+ * The channel marker / coords write / refresh tail stays in the publish command
+ * and runs only after this resolves.
+ */
+export async function publishBlock(
+  registry: BlockRegistryV2,
+  manifest: BlockPackManifest,
+  facadeDir: string,
+  fileReader: RelativeContentReader,
+): Promise<void> {
+  const modelKindRef = readModelCompiledKindRef(manifest);
+
+  if (modelKindRef !== undefined) {
+    // 1. resolve the facade-declared kind dependency
+    const facadeDep = readFacadeKindDependency(facadeDir);
+    if (facadeDep === undefined) {
+      throw new Error(
+        `Model was compiled against kind ${modelKindRef}, but the facade declares ` +
+          `no kind dependency in its package.json.`,
+      );
+    }
+
+    // Resolve to concrete artifacts (concrete version + kind content + reader).
+    const resolvedKind = await resolveFacadeKind(facadeDir, facadeDep.npmName);
+
+    // 2. pure gate — throws KindVersionMismatchError before any S3 write
+    checkKindVersionMatch(modelKindRef, resolvedKind.ref);
+
+    // 3. kind FIRST — idempotent, source-hash-guarded write to the kinds/ tree
+    await registry.publishKind(resolvedKind.manifest, resolvedKind.fileReader);
+  }
+
+  // 4. facade — unchanged behavior
+  await registry.publishPackage(manifest, fileReader);
+}

package/src/v2/registry/index.ts

@@ -1,3 +1,5 @@
 export * from "./registry";
 export * from "./registry_reader";
 export * from "./schema_public";
+export * from "./schema_kinds";
+export * from "./kind_resolver";

package/src/v2/registry/kind_resolver.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "vitest";
+import * as semver from "semver";
+import { AnyChannel, StableChannel } from "@milaboratories/pl-model-middle-layer";
+import type { BlockPackId } from "@milaboratories/pl-model-middle-layer";
+import { parseSelector, resolveKind, selectorToRange } from "./kind_resolver";
+import type { KindOverview } from "./schema_kinds";
+
+const block = (version: string): BlockPackId => ({
+  organization: "acme",
+  name: "blk",
+  version,
+});
+
+// Implementing block ids, one per kind version. Block versions are independent
+// of the kind versions they implement.
+const b100 = block("3.0.0"); // implements kind 1.0.0 (stable)
+const b120 = block("3.1.0"); // implements kind 1.2.0 (stable)
+const b130 = block("3.2.0"); // implements kind 1.3.0 (stable)
+const b200 = block("4.0.0"); // implements kind 2.0.0 (unstable only)
+
+/**
+ * Overview with a multi-step version ladder inside one major, so patch-tier and
+ * minor-tier resolution land on different versions, and a top kind version
+ * (2.0.0) whose only implementer sits off the stable channel — the
+ * `no-stable-implementation` fixture.
+ */
+const overview: KindOverview = {
+  schema: "v1",
+  implementers: [
+    { id: b100, kindVersion: "1.0.0", channels: [StableChannel] },
+    { id: b120, kindVersion: "1.2.0", channels: [StableChannel] },
+    { id: b130, kindVersion: "1.3.0", channels: [StableChannel] },
+    { id: b200, kindVersion: "2.0.0", channels: ["unstable"] },
+  ],
+  kindVersions: [
+    { kindVersion: "1.0.0", latestByChannel: { [StableChannel]: b100, [AnyChannel]: b100 } },
+    { kindVersion: "1.2.0", latestByChannel: { [StableChannel]: b120, [AnyChannel]: b120 } },
+    { kindVersion: "1.3.0", latestByChannel: { [StableChannel]: b130, [AnyChannel]: b130 } },
+    { kindVersion: "2.0.0", latestByChannel: { [AnyChannel]: b200 } },
+  ],
+};
+
+describe("selector parsing / range mapping", () => {
+  test("leading operator selects the tier; bare version is exact", () => {
+    expect(parseSelector("1.2.0")).toEqual({ op: "exact", version: "1.2.0" });
+    expect(parseSelector("~1.2.0")).toEqual({ op: "patch", version: "1.2.0" });
+    expect(parseSelector("^1.2.0")).toEqual({ op: "minor", version: "1.2.0" });
+  });
+
+  test("selectorToRange emits the explicit range for each tier", () => {
+    expect(selectorToRange({ op: "exact", version: "1.2.0" })).toBe("=1.2.0");
+    expect(selectorToRange({ op: "patch", version: "1.2.0" })).toBe(">=1.2.0 <1.3.0-0");
+    expect(selectorToRange({ op: "minor", version: "1.0.0" })).toBe(">=1.0.0 <2.0.0-0");
+  });
+
+  test("at or above 1.0.0 the explicit ranges are equivalent to npm ~ and ^", () => {
+    for (const version of ["1.0.0", "1.2.3", "2.0.0", "10.4.0", "1.2.0-rc.1"]) {
+      expect(semver.validRange(selectorToRange({ op: "patch", version }))).toBe(
+        semver.validRange(`~${version}`),
+      );
+      expect(semver.validRange(selectorToRange({ op: "minor", version }))).toBe(
+        semver.validRange(`^${version}`),
+      );
+    }
+  });
+
+  // npm collapses `^0.2.0` and `~0.2.0` to the same range, treating a 0.x minor
+  // as the breaking boundary. The kind scheme puts params-breaks on the major at
+  // every major, so the two tiers must stay distinct for a 0.x kind.
+  test("below 1.0.0 the tiers stay distinct, unlike npm ~ and ^", () => {
+    expect(selectorToRange({ op: "patch", version: "0.2.0" })).toBe(">=0.2.0 <0.3.0-0");
+    expect(selectorToRange({ op: "minor", version: "0.2.0" })).toBe(">=0.2.0 <1.0.0-0");
+
+    expect(semver.validRange("^0.2.0")).toBe(semver.validRange("~0.2.0"));
+    expect(semver.satisfies("0.3.0", selectorToRange({ op: "minor", version: "0.2.0" }))).toBe(
+      true,
+    );
+    expect(semver.satisfies("0.3.0", selectorToRange({ op: "patch", version: "0.2.0" }))).toBe(
+      false,
+    );
+    expect(semver.satisfies("1.0.0", selectorToRange({ op: "minor", version: "0.2.0" }))).toBe(
+      false,
+    );
+  });
+
+  test("an unparseable version is rejected at range construction", () => {
+    expect(() => selectorToRange({ op: "minor", version: "latest" })).toThrow();
+  });
+});
+
+describe("resolveKind", () => {
+  test("exact @X.Y.Z hit -> that kind version's stable block", () => {
+    const r = resolveKind(overview, "1.2.0", { allowUnstable: false });
+    expect(r).toEqual({ ok: true, blockId: b120, channel: StableChannel });
+  });
+
+  test("minor float ^1.0.0 picks the newest matching kind version (1.3.0)", () => {
+    const r = resolveKind(overview, "^1.0.0", { allowUnstable: false });
+    // ^1.0.0 == >=1.0.0 <2.0.0 -> maxSatisfying is 1.3.0.
+    expect(r).toEqual({ ok: true, blockId: b130, channel: StableChannel });
+  });
+
+  test("patch float ~1.2.0 stays within the minor line", () => {
+    const r = resolveKind(overview, "~1.2.0", { allowUnstable: false });
+    // ~1.2.0 == >=1.2.0 <1.3.0 -> maxSatisfying is 1.2.0.
+    expect(r).toEqual({ ok: true, blockId: b120, channel: StableChannel });
+  });
+
+  test("kind version exists but only an unstable implementer -> no-stable-implementation", () => {
+    const r = resolveKind(overview, "2.0.0", { allowUnstable: false });
+    expect(r).toEqual({ ok: false, reason: "no-stable-implementation" });
+  });
+
+  test("allowUnstable lifts the same 2.0.0 to the any channel", () => {
+    const r = resolveKind(overview, "2.0.0", { allowUnstable: true });
+    expect(r).toEqual({ ok: true, blockId: b200, channel: AnyChannel });
+  });
+
+  test("selector satisfying zero kind versions -> no-matching-kind-version", () => {
+    const r = resolveKind(overview, "5.0.0", { allowUnstable: false });
+    expect(r).toEqual({ ok: false, reason: "no-matching-kind-version" });
+  });
+});