@platforma-sdk/block-tools 2.13.0 → 2.14.0

package/src/v2/registry/kind_resolver.ts

@@ -0,0 +1,190 @@
+import type { BlockPackId } from "@milaboratories/pl-model-middle-layer";
+import { AnyChannel, StableChannel } from "@milaboratories/pl-model-middle-layer";
+import * as semver from "semver";
+import type { KindOverview } from "./schema_kinds";
+
+/**
+ * PURE, IO-free block-kind resolution core.
+ *
+ * Given a parsed {@link KindOverview} projection (fetched by the reader) and a
+ * version selector, this module answers "which concrete implementing block
+ * satisfies `{name}@{selector}`?" with a discriminated {@link KindResolution}.
+ *
+ * Everything here is fed literals in unit tests — no `FolderReader`, no cache,
+ * no `semver` use beyond range math. This is the net-new, correctness-critical
+ * seam (implementation-path §6): selector→range translation and channel
+ * selection each have edges worth isolating and testing.
+ *
+ * Naming: this module never parses the `{name}@{version}` *reference* string
+ * (that codec is `parseKindRef`, block_kind_ref.ts) nor the npm-name→path split
+ * (`npmNameToKindPath`, schema_kinds.ts). It consumes an already-split selector.
+ */
+
+/**
+ * The three version-selector tiers of the redefined-semver scheme
+ * (01-kind-and-lifecycle.md:63):
+ *   - `exact` — `@X.Y.Z`, pin to one version.
+ *   - `patch` — `~X.Y.Z`, behavior frozen (patch floats).
+ *   - `minor` — `^X.Y.Z`, behavior floats (minor floats).
+ */
+export type SelectorOp = "exact" | "patch" | "minor";
+
+export interface Selector {
+  op: SelectorOp;
+  version: string;
+}
+
+/**
+ * Split a raw selector string into its {@link Selector} operator + version.
+ *
+ * The leading character encodes the tier: `~`→patch, `^`→minor, `@`→exact.
+ * A bare version (no recognized leading operator) is treated as `exact`. Note
+ * that `@` as a *leading* char is redundant with the bare form and accepted
+ * only because the reference form is `{name}@{version}` — after `parseKindRef`
+ * splits on the final `@`, the version half is normally bare or `~`/`^`-prefixed.
+ */
+export function parseSelector(raw: string): Selector {
+  const s = raw.trim();
+  switch (s[0]) {
+    case "~":
+      return { op: "patch", version: s.slice(1) };
+    case "^":
+      return { op: "minor", version: s.slice(1) };
+    case "@":
+      return { op: "exact", version: s.slice(1) };
+    default:
+      return { op: "exact", version: s };
+  }
+}
+
+/**
+ * Map a {@link Selector} to a semver range string:
+ *   - `exact` — `=X.Y.Z`
+ *   - `patch` — `>=X.Y.Z <X.(Y+1).0-0`, behavior frozen, params float
+ *   - `minor` — `>=X.Y.Z <(X+1).0.0-0`, behavior floats, never crosses a params-break
+ *
+ * The kind scheme redefines the *meaning* of major/minor/patch, not the range
+ * arithmetic — so the arithmetic is written out here rather than delegated to
+ * npm's `~`/`^` operators, which are not major-agnostic. Below 1.0.0 npm expands
+ * both `^0.2.3` and `~0.2.3` to `>=0.2.3 <0.3.0-0`, treating a `0.x` minor as the
+ * breaking boundary per ecosystem convention. Under the kind scheme a
+ * params-break is a MAJOR bump at every major including zero, and nothing
+ * guarantees a kind starts at `1.0.0`, so borrowing `^` would silently collapse
+ * `patch` and `minor` into one tier for any `0.x` kind — erasing the distinction
+ * the whole scheme rests on.
+ *
+ * For `X >= 1` these forms are equivalent to `~`/`^`, down to npm's `-0`
+ * upper-bound suffix that keeps prereleases of the boundary out of range.
+ *
+ * @throws if `sel.version` is not a valid semver version. {@link parseSelector}
+ *   does not validate it; the model-side `parseKindSelector` does.
+ */
+export function selectorToRange(sel: Selector): string {
+  if (sel.op === "exact") return `=${sel.version}`;
+  const major = semver.major(sel.version);
+  const minor = semver.minor(sel.version);
+  const upperBound = sel.op === "patch" ? `${major}.${minor + 1}.0` : `${major + 1}.0.0`;
+  return `>=${sel.version} <${upperBound}-0`;
+}
+
+/**
+ * Outcome of resolving a kind reference against its overview projection.
+ *
+ * The three failure reasons are distinct on purpose (the caller maps each to a
+ * different user-facing error):
+ *   - `no-matching-kind-version` — the selector satisfies zero kind versions
+ *     (`maxSatisfying` returned `null`).
+ *   - `no-implementation` — a kind version matched, but it has no implementing
+ *     block at all.
+ *   - `no-stable-implementation` — implementing blocks exist for the matched
+ *     kind version, but none is on the `stable` channel and `allowUnstable` is
+ *     off.
+ */
+export type KindResolution =
+  | { ok: true; blockId: BlockPackId; channel: string }
+  | { ok: false; reason: "no-matching-kind-version" }
+  | { ok: false; reason: "no-implementation" }
+  | { ok: false; reason: "no-stable-implementation" };
+
+export type KindResolutionReason = Extract<KindResolution, { ok: false }>["reason"];
+
+/**
+ * Typed error the reader/facade throw when {@link resolveKind} fails, carrying
+ * the discriminated {@link KindResolutionReason} and the offending reference so
+ * a caller can map it to a spec-level error without re-deriving the reason.
+ */
+export class KindResolutionError extends Error {
+  constructor(
+    public readonly reason: KindResolutionReason,
+    public readonly ref: string,
+  ) {
+    super(`Cannot resolve block kind "${ref}": ${reason}`);
+    this.name = "KindResolutionError";
+  }
+}
+
+/**
+ * Newest implementing block for `(kindVersion, channel)` from the flat
+ * `implementers` list — the RMW source of truth. Newest by *block* version via
+ * `semver.gt`. Under `allowUnstable` every implementer of the kind version is
+ * eligible regardless of channel membership (the `AnyChannel` view); otherwise
+ * only implementers published to `channel` count.
+ */
+function pickNewestImplementer(
+  implementers: KindOverview["implementers"],
+  kindVersion: string,
+  channel: string,
+  allowUnstable: boolean,
+): BlockPackId | undefined {
+  const candidates = implementers.filter(
+    (i) => semver.eq(i.kindVersion, kindVersion) && (allowUnstable || i.channels.includes(channel)),
+  );
+  if (candidates.length === 0) return undefined;
+  return candidates.reduce((a, b) => (semver.gt(b.id.version, a.id.version) ? b : a)).id;
+}
+
+/**
+ * Resolve a kind reference to a concrete implementing block.
+ *
+ * 1. Pick the newest kind version satisfying the selector via
+ *    `semver.maxSatisfying` over the overview's `kindVersions`.
+ * 2. Select the target channel: `stable` by default, `any` when `allowUnstable`
+ *    is set (the apply-time flag).
+ * 3. Pick the newest implementing block in that `(version, channel)` via
+ *    `semver.gt`, reading the flat `implementers` source of truth and falling
+ *    back to the derived `latestByChannel` projection for older overviews.
+ *
+ * @param overview parsed & normalized kind projection (reader-supplied).
+ * @param selector either a raw selector string (`^1.2.3`, `~1.2.3`, `1.2.3`)
+ *   or a pre-parsed {@link Selector}.
+ */
+export function resolveKind(
+  overview: KindOverview,
+  selector: string | Selector,
+  opt: { allowUnstable: boolean },
+): KindResolution {
+  const sel = typeof selector === "string" ? parseSelector(selector) : selector;
+  const range = selectorToRange(sel);
+
+  const versions = overview.kindVersions.map((v) => v.kindVersion);
+  const picked = semver.maxSatisfying(versions, range);
+  if (picked === null) return { ok: false, reason: "no-matching-kind-version" };
+
+  const entry = overview.kindVersions.find((v) => semver.eq(v.kindVersion, picked));
+  const channel = opt.allowUnstable ? AnyChannel : StableChannel;
+
+  const blockId =
+    pickNewestImplementer(overview.implementers, picked, channel, opt.allowUnstable) ??
+    entry?.latestByChannel[channel];
+  if (blockId) return { ok: true, blockId, channel };
+
+  // Nothing in the target channel. Distinguish "no implementer at all" from
+  // "implementers exist but none stable". When `allowUnstable` is set the target
+  // channel is `any`, so an empty result here always means zero implementers.
+  const hasAnyImpl =
+    overview.implementers.some((i) => semver.eq(i.kindVersion, picked)) ||
+    (entry !== undefined && Object.keys(entry.latestByChannel).length > 0);
+
+  if (!hasAnyImpl) return { ok: false, reason: "no-implementation" };
+  return { ok: false, reason: "no-stable-implementation" };
+}

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

@@ -4,9 +4,15 @@ import { randomUUID } from "crypto";
 import path from "path";
 import fsp from "fs/promises";
 import { BlockRegistryV2 } from "./registry";
-import { UpdateSuggestions, BlockPackManifest } from "@milaboratories/pl-model-middle-layer";
+import {
+  UpdateSuggestions,
+  BlockPackManifest,
+  StableChannel,
+} from "@milaboratories/pl-model-middle-layer";
 import { inferUpdateSuggestions } from "./registry_reader";
 import { OverviewSnapshotsPrefix } from "./schema_internal";
+import { KindOverview, kindOverviewPath, npmNameToKindPath } from "./schema_kinds";
+import { resolveKind } from "./kind_resolver";
 
 type TestStorageInstance = {
   storage: RegistryStorage;
@@ -260,6 +266,246 @@ test.each(testStorages)(
   },
 );
 
+/**
+ * Fixture for the kind-projection test: a block version whose description
+ * carries a `{name}@{version}` kind reference. Only the id and that reference
+ * matter to the reconciler's kind pass.
+ */
+const kindTestKindNpmName = "@platforma-open/kindorg.kindpkg.kind";
+/** A second, unrelated kind — the migration target in the kind-change test. */
+const kindTestOtherKindNpmName = "@platforma-open/kindorg.otherpkg.kind";
+
+function kindImplementingManifest(
+  version: string,
+  kindVersion: string,
+  kindNpmName: string = kindTestKindNpmName,
+): BlockPackManifest {
+  return BlockPackManifest.parse({
+    schema: "v2",
+    description: {
+      id: { organization: "testorg", name: "kindblk", version },
+      title: "Kind implementing block",
+      summary: "Test package",
+      kind: `${kindNpmName}@${kindVersion}`,
+      components: {
+        workflow: { type: "workflow-v1", main: { type: "relative", path: "workflow.json" } },
+        model: { type: "relative", path: "model.json" },
+        ui: { type: "relative", path: "ui.json" },
+      },
+      meta: {
+        title: "Kind implementing block",
+        description: "Test package description",
+        organization: { name: "Test Organization", url: "https://test.com" },
+        tags: [],
+      },
+    },
+    files: [
+      {
+        name: "model.json",
+        size: 13,
+        sha256: "6FD977DB9B2AFE87A9CEEE48432881299A6AAF83D935FBBE83007660287F9C2E",
+      },
+    ],
+  });
+}
+
+const kindTestFileReader = async (fileName: string) => {
+  if (fileName === "model.json") return Buffer.from('{"test":true}');
+  throw new Error(`Unknown file: ${fileName}`);
+};
+
+/**
+ * Channel membership is per *block version* (`v2/{org}/{name}/{version}/channels/{channel}`),
+ * and every writer of a channel marker drops an update seed for that same
+ * version. So a `normal` (read-modify-write) reconcile pass always re-reads the
+ * versions whose membership changed, and the per-entry `channels` snapshot
+ * stored in `kinds/{org}/{name}/overview.json` cannot go stale behind it.
+ *
+ * This test pins that invariant on both sides of a stable-channel handover:
+ * adding `stable` to a newer version (both versions stable — marking is not a
+ * moving pointer, so the older one keeps its own membership) and then removing
+ * `stable` from the older one. Either step must leave every entry's snapshot
+ * equal to the markers actually present in storage, and stable resolution must
+ * follow. Regression guard: any future change that mutates a marker without
+ * seeding that exact version — or that turns `stable` into a single moving
+ * pointer — leaves the kind index asserting a version is stable when it is not.
+ */
+test.each(testStorages)(
+  "channel handover keeps kind overview channel snapshots correct in normal mode with $name",
+  async ({ storageProvider }) => {
+    const { storage, teardown } = storageProvider();
+    const registry = new BlockRegistryV2(storage, undefined, { skipSnapshotCreation: true });
+
+    const ovPath = kindOverviewPath(npmNameToKindPath(kindTestKindNpmName));
+    const readKindOverview = async (): Promise<KindOverview> => {
+      const content = await storage.getFile(ovPath);
+      expect(content).toBeDefined();
+      return KindOverview.parse(JSON.parse(content!.toString()));
+    };
+    const channelsOf = (overview: KindOverview, version: string): string[] => {
+      const entry = overview.implementers.find((i) => i.id.version === version);
+      expect(entry, `no implementer entry for ${version}`).toBeDefined();
+      return [...entry!.channels].sort();
+    };
+    const stableResolution = (overview: KindOverview) =>
+      resolveKind(overview, "1.0.0", { allowUnstable: false });
+
+    try {
+      // Two versions of one block, both implementing kind 1.0.0.
+      const a = kindImplementingManifest("1.0.0", "1.0.0");
+      const b = kindImplementingManifest("2.0.0", "1.0.0");
+      await registry.publishPackage(a, kindTestFileReader);
+      await registry.publishPackage(b, kindTestFileReader);
+
+      // A stable, reconcile.
+      await registry.addPackageToChannel(a.description.id, StableChannel);
+      await registry.updateIfNeeded("normal");
+
+      let overview = await readKindOverview();
+      expect(channelsOf(overview, "1.0.0")).toEqual([StableChannel]);
+      expect(channelsOf(overview, "2.0.0")).toEqual([]);
+      expect(stableResolution(overview)).toEqual({
+        ok: true,
+        blockId: a.description.id,
+        channel: StableChannel,
+      });
+
+      // B stable, reconcile in normal mode. A keeps its own marker (marking is
+      // additive per version), so both entries must read stable and resolution
+      // must move to the newer version.
+      await registry.addPackageToChannel(b.description.id, StableChannel);
+      await registry.updateIfNeeded("normal");
+
+      overview = await readKindOverview();
+      expect(channelsOf(overview, "1.0.0")).toEqual([StableChannel]);
+      expect(channelsOf(overview, "2.0.0")).toEqual([StableChannel]);
+      expect(await storage.listFiles(`v2/testorg/kindblk/1.0.0/channels/`)).toEqual([
+        StableChannel,
+      ]);
+      expect(stableResolution(overview)).toEqual({
+        ok: true,
+        blockId: b.description.id,
+        channel: StableChannel,
+      });
+
+      // Now the losing side of a real handover: drop stable from A. The version
+      // losing membership is the one seeded, so a normal pass must clear its
+      // snapshot rather than carry the stale `["stable"]`.
+      await registry.removePackageFromChannel(a.description.id, StableChannel);
+      await registry.updateIfNeeded("normal");
+
+      overview = await readKindOverview();
+      expect(channelsOf(overview, "1.0.0")).toEqual([]);
+      expect(channelsOf(overview, "2.0.0")).toEqual([StableChannel]);
+      expect(await storage.listFiles(`v2/testorg/kindblk/1.0.0/channels/`)).toEqual([]);
+      expect(stableResolution(overview)).toEqual({
+        ok: true,
+        blockId: b.description.id,
+        channel: StableChannel,
+      });
+
+      // Dropping the last stable marker must make the kind unresolvable on the
+      // stable channel — not silently fall back to a no-longer-stable version.
+      await registry.removePackageFromChannel(b.description.id, StableChannel);
+      await registry.updateIfNeeded("normal");
+
+      overview = await readKindOverview();
+      expect(channelsOf(overview, "1.0.0")).toEqual([]);
+      expect(channelsOf(overview, "2.0.0")).toEqual([]);
+      expect(stableResolution(overview)).toEqual({
+        ok: false,
+        reason: "no-stable-implementation",
+      });
+      expect(resolveKind(overview, "1.0.0", { allowUnstable: true })).toEqual({
+        ok: true,
+        blockId: b.description.id,
+        channel: "any",
+      });
+    } finally {
+      await teardown();
+    }
+  },
+);
+
+/**
+ * A block version can change which kind it implements: `publishPackage` overwrites
+ * same-version content (unlike `publishKind`, which is source-hash guarded), so a
+ * re-publish can move `{org}:{name}:{version}` from kind A to kind B.
+ *
+ * A `normal` pass only ever reads the CURRENT manifest, which names B — so nothing
+ * in the fresh scan points at A. Without an explicit visit A keeps listing the block
+ * as its implementer, and `resolveKind(A)` answers with a block whose manifest
+ * implements B: a mismatch that surfaces only at apply time, as rejected params.
+ * The reconciler recovers the old ref from the package overview it already loaded.
+ *
+ * Both halves are pinned here: A survives, minus the migrated version, while it
+ * still has an implementer — and is deleted once the last one leaves.
+ */
+test.each(testStorages)(
+  "changing a block's kind clears its old kind overview in normal mode with $name",
+  async ({ storageProvider }) => {
+    const { storage, teardown } = storageProvider();
+    const registry = new BlockRegistryV2(storage, undefined, { skipSnapshotCreation: true });
+
+    const ovPathA = kindOverviewPath(npmNameToKindPath(kindTestKindNpmName));
+    const ovPathB = kindOverviewPath(npmNameToKindPath(kindTestOtherKindNpmName));
+    const readOverview = async (ovPath: string): Promise<KindOverview | undefined> => {
+      const content = await storage.getFile(ovPath);
+      return content === undefined ? undefined : KindOverview.parse(JSON.parse(content.toString()));
+    };
+    const implementerVersions = (overview: KindOverview | undefined): string[] =>
+      (overview?.implementers ?? []).map((i) => i.id.version).sort();
+
+    try {
+      // Two versions of one block, both implementing kind A, both stable.
+      const a1 = kindImplementingManifest("1.0.0", "1.0.0");
+      const a2 = kindImplementingManifest("2.0.0", "1.0.0");
+      await registry.publishPackage(a1, kindTestFileReader);
+      await registry.publishPackage(a2, kindTestFileReader);
+      await registry.addPackageToChannel(a1.description.id, StableChannel);
+      await registry.addPackageToChannel(a2.description.id, StableChannel);
+      await registry.updateIfNeeded("normal");
+
+      expect(implementerVersions(await readOverview(ovPathA))).toEqual(["1.0.0", "2.0.0"]);
+      expect(await readOverview(ovPathB)).toBeUndefined();
+
+      // Re-publish 1.0.0 against kind B — same block id, different kind.
+      const b1 = kindImplementingManifest("1.0.0", "1.0.0", kindTestOtherKindNpmName);
+      await registry.publishPackage(b1, kindTestFileReader);
+      await registry.updateIfNeeded("normal");
+
+      const overviewA = await readOverview(ovPathA);
+      const overviewB = await readOverview(ovPathB);
+      expect(implementerVersions(overviewA)).toEqual(["2.0.0"]);
+      expect(implementerVersions(overviewB)).toEqual(["1.0.0"]);
+      // Each kind must resolve to the block that actually implements it now.
+      expect(resolveKind(overviewA!, "1.0.0", { allowUnstable: false })).toEqual({
+        ok: true,
+        blockId: a2.description.id,
+        channel: StableChannel,
+      });
+      expect(resolveKind(overviewB!, "1.0.0", { allowUnstable: false })).toEqual({
+        ok: true,
+        blockId: b1.description.id,
+        channel: StableChannel,
+      });
+
+      // Migrate the last implementer off A: its overview is orphaned and removed.
+      const b2 = kindImplementingManifest("2.0.0", "1.0.0", kindTestOtherKindNpmName);
+      await registry.publishPackage(b2, kindTestFileReader);
+      await registry.updateIfNeeded("normal");
+
+      expect(await readOverview(ovPathA)).toBeUndefined();
+      expect(implementerVersions(await readOverview(ovPathB))).toEqual(["1.0.0", "2.0.0"]);
+      expect(
+        resolveKind((await readOverview(ovPathB))!, "1.0.0", { allowUnstable: false }),
+      ).toEqual({ ok: true, blockId: b2.description.id, channel: StableChannel });
+    } finally {
+      await teardown();
+    }
+  },
+);
+
 test.each([
   {
     name: "test1",