@platforma-sdk/block-tools 2.13.0 → 2.14.0

package/src/v2/registry/registry.ts

@@ -10,6 +10,7 @@ import {
   blockPackIdToString,
   BlockPackManifest,
 } from "@milaboratories/pl-model-middle-layer";
+import { parseKindRef } from "@milaboratories/pl-model-common";
 import {
   GlobalUpdateSeedInFile,
   GlobalUpdateSeedOutFile,
@@ -37,6 +38,17 @@ import {
   MainPrefix,
   PackageManifestPattern,
 } from "./schema_public";
+import {
+  KindsPrefix,
+  KindManifest,
+  KindManifestFileName,
+  KindOverview,
+  KindOverviewPathPattern,
+  kindContentPrefix,
+  kindOverviewPath,
+  npmNameToKindPath,
+} from "./schema_kinds";
+import type { KindImplementer, KindVersionOverview } from "./schema_kinds";
 import type { RelativeContentReader } from "../model";
 import { addRelativePathPrefix } from "../model";
 import { randomUUID } from "node:crypto";
@@ -56,6 +68,30 @@ type PackageUpdateInfo = {
   versions: Set<string>;
 };
 
+/**
+ * What one kind overview (`kinds/{org}/{name}/overview.json`) will be rewritten to.
+ *
+ * Filled while the block manifests are already parsed in the main `updateRegistry` pass — no
+ * extra reads. Two shapes, because the pass has two modes and they read the existing file
+ * differently:
+ *
+ * - `rebuild: false` — read-modify-write. `replacedBlockIds` names the block-pack ids (with
+ *   version) whose manifests were re-read this pass; their existing `implementers` entries are
+ *   dropped so the fresh ones in `add` take their place instead of duplicating them.
+ * - `rebuild: true` — force mode. The scan re-enumerates every live kind reference, so the
+ *   existing content is discarded rather than filtered, and there is nothing to name.
+ *
+ * A discriminant rather than `Set<string> | null`: the mode is a fact about the pass, and
+ * encoding it as an absent collection makes "rebuild everything" and "replace nothing" look
+ * the same at the use site.
+ */
+type KindOverviewMerge = {
+  readonly add: KindImplementer[];
+} & (
+  | { readonly rebuild: true }
+  | { readonly rebuild: false; readonly replacedBlockIds: Set<string> }
+);
+
 export class BlockRegistryV2 {
   private readonly gzipAsync = promisify(gzip);
   private readonly gunzipAsync = promisify(gunzip);
@@ -130,7 +166,28 @@ export class BlockRegistryV2 {
 
     // reading update requests
     const packagesToUpdate = new Map<string, PackageUpdateInfo>();
+    // planned kind-overview rewrites, keyed by kinds/{org}/{name}/overview.json
+    const kindOverviewMerges = new Map<string, KindOverviewMerge>();
     const seedPaths: string[] = [];
+
+    /**
+     * Get-or-create the planned rewrite for one kind overview, recording `blockId` as
+     * re-read this pass so the RMW below drops its stale entry before merging.
+     *
+     * In force mode the plan is a rebuild and there is nothing to record — including for the
+     * plans the force pre-seed already created, which this must leave as rebuilds.
+     */
+    const mergeIntoKindOverview = (ovPath: string, blockId: string): KindOverviewMerge => {
+      const plan =
+        kindOverviewMerges.get(ovPath) ??
+        (mode === "force"
+          ? { rebuild: true as const, add: [] }
+          : { rebuild: false as const, replacedBlockIds: new Set<string>(), add: [] });
+      if (!plan.rebuild) plan.replacedBlockIds.add(blockId);
+      kindOverviewMerges.set(ovPath, plan);
+      return plan;
+    };
+
     const rawSeedPaths = await this.storage.listFiles(VersionUpdatesPrefix);
 
     const addVersionToBeUpdated = ({ organization, name, version }: BlockPackId) => {
@@ -169,6 +226,16 @@ export class BlockRegistryV2 {
         const added = addVersionToBeUpdated({ organization, name, version });
         this.logger.info(`  - ${organization}:${name}:${version} force_added:${added}`);
       }
+
+      // Seed every existing kind overview empty so kinds orphaned by
+      // migration/removal are rewritten (or deleted) this pass. The block scan
+      // above already re-enumerates every live kind ref (refs live inside block
+      // manifests); this LIST exists solely to reset orphans.
+      const kindPaths = await this.storage.listFiles(KindsPrefix);
+      for (const rel of kindPaths) {
+        if (!KindOverviewPathPattern.test(rel)) continue;
+        kindOverviewMerges.set(KindsPrefix + rel, { rebuild: true, add: [] });
+      }
     }
 
     // loading global overview
@@ -219,10 +286,19 @@ export class BlockRegistryV2 {
       );
 
       // removing versions that we will update
+      const droppedVersions = packageOverview.versions.filter((e) =>
+        packageInfo.versions.has(e.description.id.version),
+      );
       const newVersions = packageOverview.versions.filter(
         (e) => !packageInfo.versions.has(e.description.id.version),
       );
 
+      for (const e of droppedVersions) {
+        if (!e.description.kind) continue;
+        const ovPath = kindOverviewPath(npmNameToKindPath(parseKindRef(e.description.kind).name));
+        mergeIntoKindOverview(ovPath, blockPackIdToString(e.description.id));
+      }
+
       // reading new entries
       for (const [v] of packageInfo.versions.entries()) {
         const version = v.toString();
@@ -244,14 +320,26 @@ export class BlockRegistryV2 {
           }
         });
         // pushing the overview
+        const description = BlockPackManifest.parse(
+          JSON.parse(manifestContent.toString("utf8")),
+        ).description;
         newVersions.push({
-          description: addRelativePathPrefix(
-            BlockPackManifest.parse(JSON.parse(manifestContent.toString("utf8"))).description,
-            version,
-          ),
+          description: addRelativePathPrefix(description, version),
           manifestSha256: sha256,
           channels,
         });
+
+        // accumulate the kind-overview projection from this block's kind ref
+        // (both inputs already in hand: parsed manifest + listed channels).
+        if (description.kind) {
+          const { name: kindNpmName, version: kindVersion } = parseKindRef(description.kind);
+          const ovPath = kindOverviewPath(npmNameToKindPath(kindNpmName));
+          mergeIntoKindOverview(ovPath, blockPackIdToString(id)).add.push({
+            id,
+            kindVersion,
+            channels,
+          });
+        }
       }
 
       // sorting entries according to version
@@ -315,6 +403,61 @@ export class BlockRegistryV2 {
       });
     }
 
+    // projecting kind overviews (kinds/{org}/{name}/overview.json)
+    for (const [ovPath, plan] of kindOverviewMerges) {
+      // A rebuild reads nothing: the scan re-enumerated every live kind reference, so keeping
+      // any of the existing entries could only resurrect one the scan no longer sees.
+      const kept = plan.rebuild
+        ? []
+        : ((await this.getKindOverviewAt(ovPath))?.implementers ?? []).filter(
+            (e) => !plan.replacedBlockIds.has(blockPackIdToString(e.id)),
+          );
+      const merged = [...kept, ...plan.add];
+
+      if (merged.length === 0) {
+        if (mode !== "dry-run") await this.storage.deleteFiles(ovPath);
+        this.logger.info(`Kind overview ${ovPath} orphaned — removed`);
+        continue;
+      }
+
+      // bucket implementers by kind version, then compute the newest block per
+      // channel (+ derived AnyChannel), mirroring the package latestByChannel.
+      const byKindVersion = new Map<string, KindImplementer[]>();
+      for (const impl of merged) {
+        const bucket = byKindVersion.get(impl.kindVersion);
+        if (bucket) bucket.push(impl);
+        else byKindVersion.set(impl.kindVersion, [impl]);
+      }
+
+      const kindVersions: KindVersionOverview[] = [...byKindVersion.entries()]
+        .map(([kindVersion, impls]) => {
+          const allChannels = new Set<string>();
+          for (const i of impls) for (const c of i.channels) allChannels.add(c);
+          const latestByChannel = Object.fromEntries(
+            [...allChannels, AnyChannel].map((c) => {
+              const candidate = impls
+                .filter((i) => c === AnyChannel || i.channels.indexOf(c) !== -1)
+                .sort((a, b) => compareSemver(b.id.version, a.id.version))[0];
+              if (!candidate) throw new Error("Assertion error");
+              return [c, candidate.id];
+            }),
+          );
+          return { kindVersion, latestByChannel };
+        })
+        .sort((e1, e2) => compareSemver(e2.kindVersion, e1.kindVersion));
+
+      const overviewData = {
+        schema: "v1",
+        implementers: merged,
+        kindVersions,
+      } satisfies KindOverview;
+      if (mode !== "dry-run")
+        await this.storage.putFile(ovPath, Buffer.from(JSON.stringify(overviewData)));
+      this.logger.info(
+        `Kind overview ${ovPath} updated (${merged.length} implementers, ${kindVersions.length} kind versions)`,
+      );
+    }
+
     // writing global overview
     if (mode !== "dry-run") {
       const overviewData = JSON.stringify({
@@ -384,6 +527,13 @@ export class BlockRegistryV2 {
     return parseGlobalOverviewReg(JSON.parse(content.toString()));
   }
 
+  /** Read+parse a kind overview by its absolute `kinds/{org}/{name}/overview.json` path. */
+  private async getKindOverviewAt(path: string): Promise<KindOverview | undefined> {
+    const content = await this.storage.getFile(path);
+    if (content === undefined) return undefined;
+    return KindOverview.parse(JSON.parse(content.toString()));
+  }
+
   private async marchChanged(id: BlockPackId) {
     // adding update seed
     const seed = randomUUID();
@@ -501,4 +651,77 @@ export class BlockRegistryV2 {
 
     await this.marchChanged(manifest.description.id);
   }
+
+  /**
+   * Publish a block *kind* into the `kinds/` tree — idempotent, immutable,
+   * content-first. Cloned from {@link publishPackage} with two differences:
+   *
+   *   1. NET-NEW source-hash guard: kind versions are immutable. If a manifest
+   *      already exists with the same `sourceHash` this is a no-op; with a
+   *      different `sourceHash` it hard-fails. (No such guard exists for
+   *      blocks — `publishPackage` still overwrites same-version content.)
+   *   2. NO `marchChanged`: the kind projection is derived from *block*
+   *      manifests by the reconciler, so kind content publish drops no ticket —
+   *      it rides the block's publish ticket. A kind with zero implementing
+   *      blocks is deliberately invisible (no `overview.json`).
+   *
+   * The path is derived from the manifest's full npm package name
+   * (`kind.name`) via `npmNameToKindPath` (inside `kindContentPrefix`) — the
+   * SAME derivation the reconciler and readers use, so content and overview
+   * always co-locate under one `{org}/{name}` folder. There is no separate
+   * `organization` field on the identity.
+   */
+  public async publishKind(
+    kindManifest: KindManifest,
+    fileReader: RelativeContentReader,
+  ): Promise<void> {
+    const { name: npmName, version } = kindManifest.kind;
+    const prefix = kindContentPrefix(npmName, version);
+
+    // NET-NEW source-hash immutability guard (absent / equal / differ).
+    const existing = await this.storage.getFile(`${prefix}/${KindManifestFileName}`);
+    if (existing !== undefined) {
+      const prev = KindManifest.parse(JSON.parse(existing.toString()));
+      if (prev.sourceHash === kindManifest.sourceHash) {
+        this.logger.info(
+          `Kind ${npmName}@${version} already published with identical source — no-op`,
+        );
+        return; // idempotent
+      }
+      throw new Error(
+        `Immutable kind version republished with different content: ${prefix} ` +
+          `(stored sourceHash ${prev.sourceHash} != ${kindManifest.sourceHash})`,
+      );
+    }
+
+    // content-first upload, per-file size + sha256 verify (mirrors publishPackage)
+    for (const f of kindManifest.files) {
+      const bytes = await fileReader(f.name);
+      if (bytes.length !== f.size)
+        throw new Error(
+          `Actual file size don't match the manifest for ${f.name} (actual = ${bytes.length}; manifest = ${f.size})`,
+        );
+      const sha256 = await calculateSha256(bytes);
+      if (sha256 !== f.sha256.toUpperCase())
+        throw new Error(
+          `Actual file SHA-256 don't match the manifest for ${f.name} (actual = ${sha256}; manifest = ${f.sha256.toUpperCase()})`,
+        );
+
+      const dst = `${prefix}/${f.name}`;
+      this.logger.info(`Uploading ${f.name} -> ${dst} ...`);
+      await this.storage.putFile(dst, bytes);
+    }
+
+    // manifest LAST = commit marker; stamp firstUploadTimestamp when absent.
+    const toStore = KindManifest.parse({
+      ...kindManifest,
+      firstUploadTimestamp: kindManifest.firstUploadTimestamp ?? Date.now(),
+    } satisfies KindManifest);
+    const manifestDst = `${prefix}/${KindManifestFileName}`;
+    this.logger.info(`Uploading kind manifest to ${manifestDst} ...`);
+    await this.storage.putFile(manifestDst, Buffer.from(JSON.stringify(toStore)));
+
+    // NO `marchChanged`: the kind projection is derived from block manifests, so this
+    // publish drops no ticket of its own — see the note on this method.
+  }
 }

package/src/v2/registry/registry_reader.ts

@@ -6,12 +6,15 @@ import type {
   UpdateSuggestions,
   SingleBlockPackOverview,
   BlockPackOverviewNoRegistryId,
+  BlockPackFromRegistryV2,
 } from "@milaboratories/pl-model-middle-layer";
 import {
   blockPackIdNoVersionEquals,
   BlockPackManifest,
   AnyChannel,
 } from "@milaboratories/pl-model-middle-layer";
+import type { BlockKindReference } from "@milaboratories/pl-model-common";
+import { parseKindRef } from "@milaboratories/pl-model-common";
 import type { FolderReader } from "../../io";
 import canonicalize from "canonicalize";
 import {
@@ -22,6 +25,8 @@ import {
   packageContentPrefixInsideV2,
   parseGlobalOverviewReg,
 } from "./schema_public";
+import { KindsPrefix, KindOverview, KindOverviewFileName, npmNameToKindPath } from "./schema_kinds";
+import { resolveKind as resolveKindOverview, KindResolutionError } from "./kind_resolver";
 import type { BlockComponentsAbsoluteUrl } from "../model";
 import { blockComponentsManifestToAbsoluteUrl, embedBlockPackMetaBytes } from "../model";
 import { LRUCache } from "lru-cache";
@@ -65,6 +70,8 @@ export function inferUpdateSuggestions(currentVersion: string, availableVersions
 
 export class RegistryV2Reader {
   private readonly v2RootFolderReader: FolderReader;
+  /** Rooted at `kinds/`, a sibling of `v2/` — the kind projection tree. */
+  private readonly kindsRootFolderReader: FolderReader;
   private readonly ops: RegistryV2ReaderOps;
 
   constructor(
@@ -72,6 +79,7 @@ export class RegistryV2Reader {
     ops?: Partial<RegistryV2ReaderOps>,
   ) {
     this.v2RootFolderReader = registryReader.relativeReader(MainPrefix);
+    this.kindsRootFolderReader = registryReader.relativeReader(KindsPrefix);
     this.ops = { ...DefaultRegistryV2ReaderOps, ...ops };
   }
 
@@ -259,4 +267,64 @@ export class RegistryV2Reader {
   public async getComponents(id: BlockPackId): Promise<BlockComponentsAbsoluteUrl> {
     return await this.componentsCache.forceFetch(canonicalize(id)!, { context: id });
   }
+
+  /**
+   * Read the kind projection at `kinds/{org}/{name}/overview.json` for a kind
+   * npm package name. Single, no-LIST read against the `kinds/` sibling tree
+   * (rooted separately from `v2/`). Returns `undefined` when the overview is
+   * absent — a kind with zero implementing blocks has no overview by design.
+   *
+   * Client-side selector→version resolution is left to the §6 resolution
+   * concern; this method only fetches and parses.
+   */
+  public async getKindOverview(
+    kindNpmName: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<KindOverview | undefined> {
+    const { org, name } = npmNameToKindPath(kindNpmName);
+    const relPath = `${org}/${name}/${KindOverviewFileName}`;
+    try {
+      return await retry(async () => {
+        const bytes = await this.kindsRootFolderReader.readFile(relPath, {
+          signal: options?.signal,
+        });
+        return KindOverview.parse(JSON.parse(Buffer.from(bytes).toString()));
+      }, Retry2TimesWithDelay);
+    } catch {
+      // Absent overview (or unreadable) → treat as "no such kind projection".
+      return undefined;
+    }
+  }
+
+  /**
+   * Resolve a kind reference (`{name}@{selector}`) to a concrete implementing
+   * block, returning the **byte-identical** `from-registry-v2` spec shape that
+   * {@link getSpecificOverview} emits — so the resolved block flows through the
+   * unchanged add-block / `getComponents` / `prepareBlockPack` path.
+   *
+   * One projection read ({@link getKindOverview}) + client-side semver
+   * ({@link resolveKindOverview}); kind and its implementing blocks share this
+   * one registry, so no cross-registry intersection is needed. Throws a typed
+   * {@link KindResolutionError} on any failure (absent projection or no
+   * satisfying version/implementation) — the caller maps it to a spec error.
+   */
+  public async resolveKind(
+    ref: BlockKindReference,
+    { allowUnstable }: { allowUnstable: boolean },
+    options?: { signal?: AbortSignal },
+  ): Promise<BlockPackFromRegistryV2> {
+    const { name, version } = parseKindRef(ref);
+    const overview = await this.getKindOverview(name, options);
+    if (overview === undefined) throw new KindResolutionError("no-matching-kind-version", ref);
+
+    const r = resolveKindOverview(overview, version, { allowUnstable });
+    if (!r.ok) throw new KindResolutionError(r.reason, ref);
+
+    return {
+      type: "from-registry-v2",
+      id: r.blockId,
+      registryUrl: this.registryReader.rootUrl.toString(),
+      channel: r.channel,
+    };
+  }
 }

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

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { formatKindRef, parseKindRef } from "@milaboratories/pl-model-common";
+import { kindContentPrefix, kindOverviewPath, npmNameToKindPath } from "./schema_kinds";
+
+/**
+ * Seam-2 regression guard: a kind's reference is the FULL npm package name +
+ * version, and EVERYONE derives the S3 `{org, name}` from that npm name via the
+ * single `npmNameToKindPath` helper. If content and overview ever derive the
+ * folder differently again, this round-trip fails.
+ */
+describe("kind reference / path derivation round-trip", () => {
+  const npmName = "@platforma-open/milaboratories.mixcr-clonotyping.kind";
+  const version = "1.2.0";
+
+  test("npmName -> formatKindRef -> parseKindRef preserves name and version", () => {
+    const ref = formatKindRef({ name: npmName, version });
+    expect(ref).toBe(`${npmName}@${version}`);
+
+    // Split on the LAST '@', so the scoped npm name (which itself starts with
+    // '@') survives intact.
+    const parsed = parseKindRef(ref);
+    expect(parsed).toEqual({ name: npmName, version });
+  });
+
+  test("content path and overview path share the same {org, name} folder", () => {
+    const ref = formatKindRef({ name: npmName, version });
+    const parsed = parseKindRef(ref);
+
+    // The SINGLE derivation everyone uses.
+    const loc = npmNameToKindPath(parsed.name);
+
+    const contentPrefix = kindContentPrefix(parsed.name, parsed.version);
+    const overviewPath = kindOverviewPath(loc);
+
+    // Strip the version segment / the overview filename to expose the folder.
+    const contentDir = contentPrefix.slice(0, contentPrefix.lastIndexOf("/"));
+    const overviewDir = overviewPath.slice(0, overviewPath.lastIndexOf("/"));
+
+    expect(contentDir).toBe(overviewDir);
+    // kindContentPrefix derives {org,name} internally from the SAME npm name, so
+    // the co-located folder is exactly `kinds/{org}/{name}`.
+    expect(contentDir).toBe(`kinds/${loc.org}/${loc.name}`);
+    expect(contentPrefix).toBe(`kinds/${loc.org}/${loc.name}/${version}`);
+  });
+
+  test("npmNameToKindPath delegates to parsePackageName (scope dropped, 1st dotted segment = org, 2nd = name, .kind ignored)", () => {
+    // Scoped form: the npm scope (`@platforma-open/`) is dropped, then the dotted
+    // body yields org = 1st segment, name = 2nd, and the trailing `.kind` marker
+    // is simply not matched by the canonical parser.
+    expect(npmNameToKindPath("@platforma-open/milaboratories.mixcr-clonotyping.kind")).toEqual({
+      org: "milaboratories",
+      name: "mixcr-clonotyping",
+    });
+    // Bare dotted form: org = 1st segment, name = 2nd, `.kind` ignored.
+    expect(npmNameToKindPath("platforma-open.mixcr-clonotyping.kind")).toEqual({
+      org: "platforma-open",
+      name: "mixcr-clonotyping",
+    });
+    // Delegation means the derivation is identical whether or not the `.kind`
+    // marker is present — the trailing segment never participates in the split.
+    expect(npmNameToKindPath("@platforma-open/milaboratories.mixcr-clonotyping")).toEqual(
+      npmNameToKindPath("@platforma-open/milaboratories.mixcr-clonotyping.kind"),
+    );
+  });
+});

package/src/v2/registry/schema_kinds.ts

@@ -0,0 +1,169 @@
+import { BlockPackId, SemVer, Sha256Schema } from "@milaboratories/pl-model-middle-layer";
+// @todo: don't use zod
+import { z } from "zod";
+import { parsePackageName } from "../source_package";
+
+/**
+ * Registry tree for block *kinds*, a sibling of {@link MainPrefix} (`v2/`).
+ *
+ * Layout mirrors the package tree one level down:
+ *   kinds/{org}/{name}/{version}/manifest.json   — immutable kind content (publishKind)
+ *   kinds/{org}/{name}/{version}/kind.d.ts        — kind artifacts
+ *   kinds/{org}/{name}/overview.json              — projection over implementing blocks (reconciler)
+ */
+export const KindsPrefix = "kinds/";
+
+export const KindOverviewFileName = "overview.json";
+export const KindManifestFileName = "manifest.json";
+
+/** Location of a kind inside the `kinds/` tree, split into path segments. */
+export interface KindPathLocation {
+  org: string;
+  name: string;
+}
+
+/**
+ * `kinds/{org}/{name}/{version}` — the immutable per-version content folder,
+ * counterpart of {@link packageContentPrefix}.
+ *
+ * The `{org, name}` segments are DERIVED from the kind's full npm package name
+ * via {@link npmNameToKindPath} — the SAME helper {@link kindOverviewPath} and
+ * the reconciler use. This is what guarantees a kind's per-version content and
+ * its `overview.json` projection land under one identical `{org}/{name}` folder.
+ */
+export function kindContentPrefix(npmName: string, version: string): string {
+  const { org, name } = npmNameToKindPath(npmName);
+  return `${KindsPrefix}${org}/${name}/${version}`;
+}
+
+/**
+ * `kinds/{org}/{name}/overview.json` — the reconciler-maintained projection of
+ * every block that implements this kind, bucketed by kind version.
+ */
+export function kindOverviewPath(loc: KindPathLocation): string {
+  return `${KindsPrefix}${loc.org}/${loc.name}/${KindOverviewFileName}`;
+}
+
+/**
+ * Matches a `kinds/`-relative overview path (`{org}/{name}/overview.json`).
+ * Used by the force-mode orphan seed to enumerate every existing overview.
+ */
+export const KindOverviewPathPattern = new RegExp(
+  `^(?<org>[^/]+)/(?<name>[^/]+)/${KindOverviewFileName.replace(".", "\\.")}$`,
+);
+
+/**
+ * Kind npm package name → `{org, name}` path segments.
+ *
+ * DELEGATES to {@link parsePackageName} — the canonical block npm-name parser
+ * (`source_package.ts`) — so kind registry paths (`kinds/{org}/{name}/…`) mirror
+ * block paths (`v2/{org}/{name}/…`) byte-for-byte and cannot drift. That parser
+ * drops the npm scope (`@platforma-open/`), takes the 1st dotted segment as the
+ * organization and the 2nd as the name, and ignores any trailing segment (the
+ * kind's `.kind` marker simply is not matched):
+ *   - `@platforma-open/milaboratories.mixcr-clonotyping.kind` → `{ org: "milaboratories", name: "mixcr-clonotyping" }`
+ *   - `milaboratories.mixcr-clonotyping.kind`                 → `{ org: "milaboratories", name: "mixcr-clonotyping" }`
+ *
+ * This helper is DISTINCT from `parseKindRef` (the `{name}@{version}` reference
+ * codec in `block_kind_ref.ts`): `parseKindRef` splits a reference into
+ * name/version; `npmNameToKindPath` splits the *name* half into path segments.
+ */
+export function npmNameToKindPath(npmName: string): KindPathLocation {
+  const { organization, name } = parsePackageName(npmName);
+  return { org: organization, name };
+}
+
+/**
+ * On-wire kind identity, mirroring the `kind` block written by the build side
+ * (`build_kind_dist.ts` `KindManifestIdentity`).
+ *
+ * `name` is the FULL npm package name of the kind (e.g.
+ * `@platforma-open/milaboratories.mixcr-clonotyping.kind`). There is no separate
+ * `organization` field — the S3 `{org, name}` path is always derived from this
+ * npm name via {@link npmNameToKindPath}, so the content publisher and the
+ * overview reconciler resolve to the same folder.
+ */
+export const KindManifestIdentity = z
+  .object({
+    name: z.string(),
+    version: SemVer,
+  })
+  .passthrough();
+export type KindManifestIdentity = z.infer<typeof KindManifestIdentity>;
+
+export const KindManifestFileInfo = z
+  .object({
+    name: z.string(),
+    size: z.number(),
+    sha256: Sha256Schema,
+  })
+  .passthrough();
+export type KindManifestFileInfo = z.infer<typeof KindManifestFileInfo>;
+
+/**
+ * Kind content manifest, as produced by `build_kind_dist.ts` and stored (LAST,
+ * as the commit marker) at `kinds/{org}/{name}/{version}/manifest.json`.
+ *
+ * `sourceHash` is the sorted-`src/`-tree digest computed at build time (NOT the
+ * per-file `calculateSha256`); it is the comparand for the publish-time
+ * source-hash immutability guard. `firstUploadTimestamp` is stamped by
+ * `publishKind` when the manifest is first written to the registry.
+ */
+export const KindManifest = z
+  .object({
+    schema: z.literal("v1"),
+    kind: KindManifestIdentity,
+    sourceHash: z.string(),
+    files: z.array(KindManifestFileInfo),
+    /** Build-time timestamp carried from `build_kind_dist.ts`. */
+    timestamp: z.number().optional(),
+    /** Stamped by `publishKind` on first upload to the registry. */
+    firstUploadTimestamp: z.number().optional(),
+  })
+  .passthrough();
+export type KindManifest = z.infer<typeof KindManifest>;
+
+/**
+ * One implementing block version for some kind version. Flat and
+ * RMW-friendly: the reconciler filters this list by `(id)` to drop stale
+ * entries before re-adding fresh ones.
+ */
+export const KindImplementer = z
+  .object({
+    /** Full id of the implementing block, incl. its version. */
+    id: BlockPackId,
+    /** Kind version this block implements. */
+    kindVersion: SemVer,
+    /** Channels the block version is published to. */
+    channels: z.array(z.string()).default(() => []),
+  })
+  .passthrough();
+export type KindImplementer = z.infer<typeof KindImplementer>;
+
+/**
+ * Per-kind-version projection: the newest implementing block per channel,
+ * including the derived `any` channel. Mirrors the package overview's
+ * `latestByChannel` + `AnyChannel` computation.
+ */
+export const KindVersionOverview = z
+  .object({
+    kindVersion: SemVer,
+    latestByChannel: z.record(z.string(), BlockPackId),
+  })
+  .passthrough();
+export type KindVersionOverview = z.infer<typeof KindVersionOverview>;
+
+/**
+ * Reconciler-maintained projection at `kinds/{org}/{name}/overview.json`.
+ *
+ * `implementers` is the flat, RMW source of truth; `kindVersions` is the
+ * derived, reader-facing view (kind versions × newest implementer per channel).
+ */
+export const KindOverview = z
+  .object({
+    schema: z.literal("v1"),
+    implementers: z.array(KindImplementer),
+    kindVersions: z.array(KindVersionOverview),
+  })
+  .passthrough();
+export type KindOverview = z.infer<typeof KindOverview>;