@platforma-sdk/block-tools 2.13.0 → 2.14.0

package/dist/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./config-BmJWc8sR.js`);var t=e.wt({GlobalOverviewPath:()=>e.r,MetaFile:()=>e.i,PlPackageConfigData:()=>e.c,PlPackageJsonConfigFile:()=>e.l,PlPackageYamlConfigFile:()=>e.u,PlRegCommonConfigData:()=>e.d,PlRegFullPackageConfigData:()=>e.f,PlRegPackageConfig:()=>e.t,PlRegPackageConfigDataShard:()=>e.p,packageContentPrefix:()=>e.a,packageOverviewPath:()=>e.o,payloadFilePath:()=>e.s});exports.BlockDescriptionPackageJsonField=e.G,exports.BlockPackFolderName=e.K,exports.BlockRegistryV2=e.b,exports.ChannelNameRegexp=e.x,exports.ChannelsFolder=e.S,exports.FSStorage=e.h,exports.GlobalOverviewFileName=e.C,exports.GlobalOverviewGzFileName=e.w,exports.GlobalOverviewGzPath=e.T,exports.GlobalOverviewPath=e.E,exports.MainPrefix=e.D,exports.ManifestFileName=e.O,exports.ManifestSuffix=e.k,exports.PackageManifestPattern=e.A,exports.PackageOverview=e.j,exports.PackageOverviewFileName=e.M,exports.PackageOverviewVersionEntry=e.N,exports.PublishedCoordsFileName=e.V,Object.defineProperty(exports,`RegistryV1`,{enumerable:!0,get:function(){return t}}),exports.RegistryV2Reader=e.v,exports.S3Storage=e.g,exports.absoluteToBase64=e.ft,exports.absoluteToBytes=e.pt,exports.absoluteToString=e.mt,exports.addRelativePathPrefix=e.$,exports.blockComponentsManifestToAbsoluteUrl=e.nt,exports.buildBlockPackDist=e.Q,exports.buildPublishedCoords=e.H,exports.consolidateBlockComponents=e.rt,exports.consolidateBlockPackDescription=e.et,exports.consolidateBlockPackMeta=e.ot,exports.cpAbsoluteToRelative=e.ht,exports.embedBlockPackMetaAbsoluteBase64=e.st,exports.embedBlockPackMetaAbsoluteBytes=e.ct,exports.embedBlockPackMetaBytes=e.lt,exports.folderReaderByUrl=e.m,exports.inferUpdateSuggestions=e.y,exports.loadPackDescription=e.q,exports.loadPackDescriptionFromManifest=e.J,exports.loadPackDescriptionRaw=e.Y,exports.mapLocalToAbsolute=e.gt,exports.packFolderToRelativeTgz=e._t,exports.packageChannelPrefix=e.P,exports.packageChannelPrefixInsideV2=e.F,exports.packageContentPrefix=e.I,exports.packageContentPrefixInsideV2=e.L,exports.packageOverviewPath=e.R,exports.packageOverviewPathInsideV2=e.z,exports.parseGlobalOverviewReg=e.B,exports.parsePackageName=e.X,exports.relativeToContentString=e.vt,exports.relativeToExplicitBinary64=e.yt,exports.relativeToExplicitBytes=e.bt,exports.relativeToExplicitString=e.xt,exports.resolveBlockComponents=e.it,exports.resolveBlockPackDescription=e.tt,exports.resolveBlockPackMeta=e.ut,exports.resolveManifestBlockComponents=e.at,exports.resolveManifestBlockPackMeta=e.dt,exports.resolveModuleFile=e.St,exports.resolveModuleFolder=e.Ct,exports.resolveToRegistry=e.U,exports.storageByUrl=e._,exports.tryLoadPackDescription=e.Z,exports.writePublishedCoords=e.W;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./config-CtXMWNgm.js`);var t=e.Yt({GlobalOverviewPath:()=>e.r,MetaFile:()=>e.i,PlPackageConfigData:()=>e.c,PlPackageJsonConfigFile:()=>e.l,PlPackageYamlConfigFile:()=>e.u,PlRegCommonConfigData:()=>e.d,PlRegFullPackageConfigData:()=>e.f,PlRegPackageConfig:()=>e.t,PlRegPackageConfigDataShard:()=>e.p,packageContentPrefix:()=>e.a,packageOverviewPath:()=>e.o,payloadFilePath:()=>e.s});exports.BlockDescriptionPackageJsonField=e.mt,exports.BlockPackFolderName=e.ht,exports.BlockRegistryV2=e.w,exports.ChannelNameRegexp=e.T,exports.ChannelsFolder=e.E,exports.FSStorage=e.h,exports.GlobalOverviewFileName=e.D,exports.GlobalOverviewGzFileName=e.O,exports.GlobalOverviewGzPath=e.k,exports.GlobalOverviewPath=e.A,exports.KindImplementer=e.tt,exports.KindManifest=e.nt,exports.KindManifestFile=e.xt,exports.KindManifestFileInfo=e.rt,exports.KindManifestFileName=e.it,exports.KindManifestIdentity=e.at,exports.KindOverview=e.ot,exports.KindOverviewFileName=e.st,exports.KindOverviewPathPattern=e.ct,exports.KindResolutionError=e.b,exports.KindVersionMismatchError=e.X,exports.KindVersionOverview=e.lt,exports.KindsPrefix=e.ut,exports.MainPrefix=e.j,exports.ManifestFileName=e.M,exports.ManifestSuffix=e.N,exports.PackageManifestPattern=e.P,exports.PackageOverview=e.F,exports.PackageOverviewFileName=e.I,exports.PackageOverviewVersionEntry=e.L,exports.PublishedCoordsFileName=e.G,Object.defineProperty(exports,`RegistryV1`,{enumerable:!0,get:function(){return t}}),exports.RegistryV2Reader=e.v,exports.S3Storage=e.g,exports.absoluteToBase64=e.Lt,exports.absoluteToBytes=e.Rt,exports.absoluteToString=e.zt,exports.addRelativePathPrefix=e.wt,exports.blockComponentsManifestToAbsoluteUrl=e.Dt,exports.buildBlockPackDist=e.Ct,exports.buildKindDist=e.St,exports.buildPublishedCoords=e.K,exports.checkKindVersionMatch=e.Z,exports.consolidateBlockComponents=e.Ot,exports.consolidateBlockPackDescription=e.Tt,exports.consolidateBlockPackMeta=e.jt,exports.cpAbsoluteToRelative=e.Bt,exports.embedBlockPackMetaAbsoluteBase64=e.Mt,exports.embedBlockPackMetaAbsoluteBytes=e.Nt,exports.embedBlockPackMetaBytes=e.Pt,exports.folderReaderByUrl=e.m,exports.inferUpdateSuggestions=e.y,exports.kindContentPrefix=e.dt,exports.kindOverviewPath=e.ft,exports.loadPackDescription=e.gt,exports.loadPackDescriptionFromManifest=e._t,exports.loadPackDescriptionRaw=e.vt,exports.mapLocalToAbsolute=e.Vt,exports.npmNameToKindPath=e.pt,exports.packFolderToRelativeTgz=e.Ht,exports.packageChannelPrefix=e.R,exports.packageChannelPrefixInsideV2=e.z,exports.packageContentPrefix=e.B,exports.packageContentPrefixInsideV2=e.V,exports.packageOverviewPath=e.H,exports.packageOverviewPathInsideV2=e.U,exports.parseGlobalOverviewReg=e.W,exports.parsePackageName=e.yt,exports.parseSelector=e.x,exports.publishBlock=e.Y,exports.readFacadeKindDependency=e.Q,exports.readModelCompiledKindRef=e.$,exports.relativeToContentString=e.Ut,exports.relativeToExplicitBinary64=e.Wt,exports.relativeToExplicitBytes=e.Gt,exports.relativeToExplicitString=e.Kt,exports.resolveBlockComponents=e.kt,exports.resolveBlockPackDescription=e.Et,exports.resolveBlockPackMeta=e.Ft,exports.resolveFacadeKind=e.et,exports.resolveKind=e.S,exports.resolveManifestBlockComponents=e.At,exports.resolveManifestBlockPackMeta=e.It,exports.resolveModuleFile=e.qt,exports.resolveModuleFolder=e.Jt,exports.resolveToRegistry=e.q,exports.selectorToRange=e.C,exports.storageByUrl=e._,exports.tryLoadPackDescription=e.bt,exports.writePublishedCoords=e.J;
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -1,20 +1,20 @@
-import { $ as e, A as t, B as n, C as r, Ct as i, D as a, E as o, F as s, G as c, H as l, I as u, J as d, K as f, L as p, M as m, N as h, O as g, P as _, Q as v, R as y, S as b, St as x, T as S, U as C, V as w, W as T, X as E, Y as D, Z as O, _ as k, _t as A, a as j, at as M, b as N, bt as P, c as F, ct as I, d as L, dt as R, et as z, f as B, ft as V, g as H, gt as U, h as W, ht as G, i as K, it as q, j as J, k as Y, l as X, lt as Z, m as Q, mt as $, nt as ee, o as te, ot as ne, p as re, pt as ie, q as ae, r as oe, rt as se, s as ce, st as le, t as ue, tt as de, u as fe, ut as pe, v as me, vt as he, w as ge, wt as _e, x as ve, xt as ye, y as be, yt as xe, z as Se } from "./config-CiC347sB.mjs";
+import { $ as e, A as t, At as n, B as r, Bt as i, C as a, Ct as o, D as s, Dt as c, E as l, Et as u, F as d, Ft as f, G as p, Gt as m, H as h, Ht as g, I as _, It as v, J as y, Jt as b, K as x, Kt as S, L as C, Lt as w, M as T, Mt as E, N as D, Nt as O, O as k, Ot as A, P as j, Pt as M, Q as N, R as P, Rt as F, S as I, St as L, T as R, Tt as z, U as B, Ut as V, V as H, Vt as U, W, Wt as G, X as K, Y as q, Yt as J, Z as Y, _ as X, _t as Z, a as Q, at as $, b as ee, bt as te, c as ne, ct as re, d as ie, dt as ae, et as oe, f as se, ft as ce, g as le, gt as ue, h as de, ht as fe, i as pe, it as me, j as he, jt as ge, k as _e, kt as ve, l as ye, lt as be, m as xe, mt as Se, nt as Ce, o as we, ot as Te, p as Ee, pt as De, q as Oe, qt as ke, r as Ae, rt as je, s as Me, st as Ne, t as Pe, tt as Fe, u as Ie, ut as Le, v as Re, vt as ze, w as Be, wt as Ve, x as He, xt as Ue, y as We, yt as Ge, z as Ke, zt as qe } from "./config-Dx45aFJ_.mjs";
 //#region src/registry_v1/index.ts
-var Ce = /* @__PURE__ */ _e({
-	GlobalOverviewPath: () => oe,
-	MetaFile: () => K,
-	PlPackageConfigData: () => F,
-	PlPackageJsonConfigFile: () => X,
-	PlPackageYamlConfigFile: () => fe,
-	PlRegCommonConfigData: () => L,
-	PlRegFullPackageConfigData: () => B,
-	PlRegPackageConfig: () => ue,
-	PlRegPackageConfigDataShard: () => re,
-	packageContentPrefix: () => j,
-	packageOverviewPath: () => te,
-	payloadFilePath: () => ce
+var Je = /* @__PURE__ */ J({
+	GlobalOverviewPath: () => Ae,
+	MetaFile: () => pe,
+	PlPackageConfigData: () => ne,
+	PlPackageJsonConfigFile: () => ye,
+	PlPackageYamlConfigFile: () => Ie,
+	PlRegCommonConfigData: () => ie,
+	PlRegFullPackageConfigData: () => se,
+	PlRegPackageConfig: () => Pe,
+	PlRegPackageConfigDataShard: () => Ee,
+	packageContentPrefix: () => Q,
+	packageOverviewPath: () => we,
+	payloadFilePath: () => Me
 });
 //#endregion
-export { c as BlockDescriptionPackageJsonField, f as BlockPackFolderName, N as BlockRegistryV2, ve as ChannelNameRegexp, b as ChannelsFolder, W as FSStorage, r as GlobalOverviewFileName, ge as GlobalOverviewGzFileName, S as GlobalOverviewGzPath, o as GlobalOverviewPath, a as MainPrefix, g as ManifestFileName, Y as ManifestSuffix, t as PackageManifestPattern, J as PackageOverview, m as PackageOverviewFileName, h as PackageOverviewVersionEntry, w as PublishedCoordsFileName, Ce as RegistryV1, me as RegistryV2Reader, H as S3Storage, V as absoluteToBase64, ie as absoluteToBytes, $ as absoluteToString, e as addRelativePathPrefix, ee as blockComponentsManifestToAbsoluteUrl, v as buildBlockPackDist, l as buildPublishedCoords, se as consolidateBlockComponents, z as consolidateBlockPackDescription, ne as consolidateBlockPackMeta, G as cpAbsoluteToRelative, le as embedBlockPackMetaAbsoluteBase64, I as embedBlockPackMetaAbsoluteBytes, Z as embedBlockPackMetaBytes, Q as folderReaderByUrl, be as inferUpdateSuggestions, ae as loadPackDescription, d as loadPackDescriptionFromManifest, D as loadPackDescriptionRaw, U as mapLocalToAbsolute, A as packFolderToRelativeTgz, _ as packageChannelPrefix, s as packageChannelPrefixInsideV2, u as packageContentPrefix, p as packageContentPrefixInsideV2, y as packageOverviewPath, Se as packageOverviewPathInsideV2, n as parseGlobalOverviewReg, E as parsePackageName, he as relativeToContentString, xe as relativeToExplicitBinary64, P as relativeToExplicitBytes, ye as relativeToExplicitString, q as resolveBlockComponents, de as resolveBlockPackDescription, pe as resolveBlockPackMeta, M as resolveManifestBlockComponents, R as resolveManifestBlockPackMeta, x as resolveModuleFile, i as resolveModuleFolder, C as resolveToRegistry, k as storageByUrl, O as tryLoadPackDescription, T as writePublishedCoords };
+export { Se as BlockDescriptionPackageJsonField, fe as BlockPackFolderName, Be as BlockRegistryV2, R as ChannelNameRegexp, l as ChannelsFolder, de as FSStorage, s as GlobalOverviewFileName, k as GlobalOverviewGzFileName, _e as GlobalOverviewGzPath, t as GlobalOverviewPath, Fe as KindImplementer, Ce as KindManifest, Ue as KindManifestFile, je as KindManifestFileInfo, me as KindManifestFileName, $ as KindManifestIdentity, Te as KindOverview, Ne as KindOverviewFileName, re as KindOverviewPathPattern, ee as KindResolutionError, K as KindVersionMismatchError, be as KindVersionOverview, Le as KindsPrefix, he as MainPrefix, T as ManifestFileName, D as ManifestSuffix, j as PackageManifestPattern, d as PackageOverview, _ as PackageOverviewFileName, C as PackageOverviewVersionEntry, p as PublishedCoordsFileName, Je as RegistryV1, Re as RegistryV2Reader, le as S3Storage, w as absoluteToBase64, F as absoluteToBytes, qe as absoluteToString, Ve as addRelativePathPrefix, c as blockComponentsManifestToAbsoluteUrl, o as buildBlockPackDist, L as buildKindDist, x as buildPublishedCoords, Y as checkKindVersionMatch, A as consolidateBlockComponents, z as consolidateBlockPackDescription, ge as consolidateBlockPackMeta, i as cpAbsoluteToRelative, E as embedBlockPackMetaAbsoluteBase64, O as embedBlockPackMetaAbsoluteBytes, M as embedBlockPackMetaBytes, xe as folderReaderByUrl, We as inferUpdateSuggestions, ae as kindContentPrefix, ce as kindOverviewPath, ue as loadPackDescription, Z as loadPackDescriptionFromManifest, ze as loadPackDescriptionRaw, U as mapLocalToAbsolute, De as npmNameToKindPath, g as packFolderToRelativeTgz, P as packageChannelPrefix, Ke as packageChannelPrefixInsideV2, r as packageContentPrefix, H as packageContentPrefixInsideV2, h as packageOverviewPath, B as packageOverviewPathInsideV2, W as parseGlobalOverviewReg, Ge as parsePackageName, He as parseSelector, q as publishBlock, N as readFacadeKindDependency, e as readModelCompiledKindRef, V as relativeToContentString, G as relativeToExplicitBinary64, m as relativeToExplicitBytes, S as relativeToExplicitString, ve as resolveBlockComponents, u as resolveBlockPackDescription, f as resolveBlockPackMeta, oe as resolveFacadeKind, I as resolveKind, n as resolveManifestBlockComponents, v as resolveManifestBlockPackMeta, ke as resolveModuleFile, b as resolveModuleFolder, Oe as resolveToRegistry, a as selectorToRange, X as storageByUrl, te as tryLoadPackDescription, y as writePublishedCoords };
 
 //# sourceMappingURL=index.mjs.map

package/dist/structure/engine/api.d.ts

@@ -1,5 +1,5 @@
 import { ContentForm, ManagedBody, RunMode, Structure, TriggerFn } from './ir';
-export type Scope = "root" | "block" | "model" | "ui" | "workflow" | "test" | "software";
+export type Scope = "root" | "block" | "model" | "ui" | "workflow" | "test" | "software" | "kind";
 /** Variables describing a block — populated by `init` or parsed by
  *  `check`/`refresh` from the block's package.json `name`. */
 export type BlockVars = {

package/dist/structure/rules/kind-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function kindPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function kindPackageJsonRules(): void;

package/dist/structure/rules/kind.d.ts

@@ -0,0 +1 @@
+export declare function kindRules(): void;

package/dist/v2/build_kind_dist.d.ts

@@ -0,0 +1,25 @@
+import { KindManifest } 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;
+}
+export type { KindManifest, KindManifestIdentity, KindManifestFileInfo, } from './registry/schema_kinds';
+export declare const KindManifestFile = "manifest.json";
+/**
+ * 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 declare function buildKindDist(opts?: BuildKindDistOptions): Promise<KindManifest>;

package/dist/v2/index.d.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/dist/v2/kind/resolve-refs.d.ts

@@ -0,0 +1,63 @@
+import { BlockKindReference } from '@milaboratories/pl-model-common';
+import { BlockPackManifest } from '@milaboratories/pl-model-middle-layer';
+import { KindManifest } from '../registry/schema_kinds';
+import { RelativeContentReader } from '../model';
+/**
+ * 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 declare function readModelCompiledKindRef(manifest: BlockPackManifest): BlockKindReference | undefined;
+/** 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 declare function readFacadeKindDependency(facadeDir: string): FacadeKindDependency | undefined;
+/**
+ * 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 declare function resolveFacadeKind(facadeDir: string, npmName: string): Promise<ResolvedFacadeKind>;

package/dist/v2/kind/version-match.d.ts

@@ -0,0 +1,23 @@
+import { BlockKindReference } from '@milaboratories/pl-model-common';
+/**
+ * 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 declare class KindVersionMismatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function checkKindVersionMatch(modelKindRef: BlockKindReference, facadeKindDep: BlockKindReference): void;

package/dist/v2/model/block_description.d.ts

@@ -7,7 +7,14 @@ export type BlockPackDescriptionAbsolute = BlockPackDescription<BlockComponentsD
  * 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 declare function resolveBlockPackDescription(raw: BlockPackDescriptionRaw, root: string): Promise<BlockPackDescriptionAbsolute>;
 /**

package/dist/v2/publish-block.d.ts

@@ -0,0 +1,23 @@
+import { BlockPackManifest } from '@milaboratories/pl-model-middle-layer';
+import { BlockRegistryV2 } from './registry/registry';
+import { RelativeContentReader } from './model';
+/**
+ * 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 declare function publishBlock(registry: BlockRegistryV2, manifest: BlockPackManifest, facadeDir: string, fileReader: RelativeContentReader): Promise<void>;

package/dist/v2/registry/index.d.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/dist/v2/registry/kind_resolver.d.ts

@@ -0,0 +1,121 @@
+import { BlockPackId } from '@milaboratories/pl-model-middle-layer';
+import { 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 declare function parseSelector(raw: string): Selector;
+/**
+ * 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 declare function selectorToRange(sel: Selector): string;
+/**
+ * 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 declare class KindResolutionError extends Error {
+    readonly reason: KindResolutionReason;
+    readonly ref: string;
+    constructor(reason: KindResolutionReason, ref: string);
+}
+/**
+ * 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 declare function resolveKind(overview: KindOverview, selector: string | Selector, opt: {
+    allowUnstable: boolean;
+}): KindResolution;

package/dist/v2/registry/registry.d.ts

@@ -2,6 +2,7 @@ import { MiLogger } from '@milaboratories/ts-helpers';
 import { RegistryStorage } from '../../io/storage';
 import { BlockPackId, BlockPackIdNoVersion, BlockPackManifest } from '@milaboratories/pl-model-middle-layer';
 import { GlobalOverviewReg, PackageOverview } from './schema_public';
+import { KindManifest } from './schema_kinds';
 import { RelativeContentReader } from '../model';
 export interface BlockRegistrySettings {
     skipSnapshotCreation?: boolean;
@@ -25,10 +26,32 @@ export declare class BlockRegistryV2 {
     updateIfNeeded(mode?: "force" | "normal" | "dry-run"): Promise<void>;
     getPackageOverview(name: BlockPackIdNoVersion): Promise<undefined | PackageOverview>;
     getGlobalOverview(): Promise<undefined | GlobalOverviewReg>;
+    /** Read+parse a kind overview by its absolute `kinds/{org}/{name}/overview.json` path. */
+    private getKindOverviewAt;
     private marchChanged;
     addPackageToChannel(id: BlockPackId, channel: string): Promise<void>;
     removePackageFromChannel(id: BlockPackId, channel: string): Promise<void>;
     listGlobalOverviewSnapshots(): Promise<GlobalOverviewBackupDescription[]>;
     restoreGlobalOverviewFromSnapshot(backupId: string): Promise<void>;
     publishPackage(manifest: BlockPackManifest, fileReader: RelativeContentReader): Promise<void>;
+    /**
+     * 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.
+     */
+    publishKind(kindManifest: KindManifest, fileReader: RelativeContentReader): Promise<void>;
 }

package/dist/v2/registry/registry_reader.d.ts

@@ -1,5 +1,7 @@
-import { BlockPackId, BlockPackIdNoVersion, UpdateSuggestions, SingleBlockPackOverview, BlockPackOverviewNoRegistryId } from '@milaboratories/pl-model-middle-layer';
+import { BlockPackId, BlockPackIdNoVersion, UpdateSuggestions, SingleBlockPackOverview, BlockPackOverviewNoRegistryId, BlockPackFromRegistryV2 } from '@milaboratories/pl-model-middle-layer';
+import { BlockKindReference } from '@milaboratories/pl-model-common';
 import { FolderReader } from '../../io';
+import { KindOverview } from './schema_kinds';
 import { BlockComponentsAbsoluteUrl } from '../model';
 export type RegistryV2ReaderOps = {
     /** Number of milliseconds to cache retrieved block list for */
@@ -12,6 +14,8 @@ export declare function inferUpdateSuggestions(currentVersion: string, available
 export declare class RegistryV2Reader {
     private readonly registryReader;
     private readonly v2RootFolderReader;
+    /** Rooted at `kinds/`, a sibling of `v2/` — the kind projection tree. */
+    private readonly kindsRootFolderReader;
     private readonly ops;
     constructor(registryReader: FolderReader, ops?: Partial<RegistryV2ReaderOps>);
     /**
@@ -31,4 +35,33 @@ export declare class RegistryV2Reader {
     getSpecificOverview(id: BlockPackId, channel: string): Promise<SingleBlockPackOverview>;
     private readonly componentsCache;
     getComponents(id: BlockPackId): Promise<BlockComponentsAbsoluteUrl>;
+    /**
+     * 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.
+     */
+    getKindOverview(kindNpmName: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<KindOverview | 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.
+     */
+    resolveKind(ref: BlockKindReference, { allowUnstable }: {
+        allowUnstable: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<BlockPackFromRegistryV2>;
 }