@platforma-sdk/block-tools 2.13.0 → 2.14.0

package/src/cli.test.ts

@@ -15,8 +15,9 @@ function longNames(cmd: Command): string[] {
 describe("block-tools CLI structure", () => {
   const program = buildProgram();
 
-  it("exposes the full command surface (11 commands + structure topic)", () => {
+  it("exposes the full command surface (12 commands + structure topic)", () => {
     expect(program.commands.map((c) => c.name()).sort()).toEqual([
+      "build-kind-manifest",
       "build-meta",
       "build-model",
       "list-overview-snapshots",

package/src/cli.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { buildMetaCommand } from "./cmd/build-meta";
 import { buildModelCommand } from "./cmd/build-model";
+import { buildKindManifestCommand } from "./cmd/build-kind-manifest";
 import { packCommand } from "./cmd/pack";
 import { publishCommand } from "./cmd/publish";
 import { refreshRegistryCommand } from "./cmd/refresh-registry";
@@ -25,6 +26,7 @@ export function buildProgram(packageRoot: string = process.cwd()): Command {
 
   program.addCommand(buildMetaCommand());
   program.addCommand(buildModelCommand());
+  program.addCommand(buildKindManifestCommand());
   program.addCommand(packCommand());
   program.addCommand(publishCommand());
   program.addCommand(refreshRegistryCommand());

package/src/cmd/build-kind-manifest.ts

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { buildKindDist } from "../v2/build_kind_dist";
+
+// @todo: disscuss why we need manifest for kind
+
+/**
+ * Thin commander wrapper (build-model.ts shape) delegating to the commander-free
+ * `buildKindDist` core. Bundles the compiled kind's identity + src source-hash
+ * into `dist/manifest.json`.
+ */
+export function buildKindManifestCommand(): Command {
+  const cmd = new Command("build-kind-manifest").description(
+    "Writes the block-kind dist manifest (identity + src source-hash) from a pre-built kind bundle",
+  );
+
+  cmd.option(
+    "-i, --modulePath <path>",
+    "kind package dir (contains package.json, src/, dist/)",
+    ".",
+  );
+  cmd.option(
+    "-s, --srcDir <path>",
+    "source dir hashed into sourceHash, relative to modulePath",
+    "src",
+  );
+  cmd.option(
+    "-o, --dst <path>",
+    "output dir with the compiled bundle, relative to modulePath",
+    "dist",
+  );
+
+  cmd.action(async (flags) => {
+    await buildKindDist({
+      modulePath: flags.modulePath,
+      srcDir: flags.srcDir,
+      dst: flags.dst,
+    });
+  });
+
+  return cmd;
+}

package/src/cmd/publish.ts

@@ -9,6 +9,7 @@ import {
 } from "@milaboratories/pl-model-middle-layer";
 import { storageByUrl } from "../io/storage";
 import { BlockRegistryV2 } from "../v2/registry/registry";
+import { publishBlock } from "../v2/publish-block";
 import { buildPublishedCoords, writePublishedCoords } from "../v2/resolve_to_registry";
 import path from "node:path";
 
@@ -82,15 +83,23 @@ export function publishCommand(): Command {
       manifest as BlockPackManifest & Record<string, unknown>,
     );
     const manifestRoot = path.dirname(manifestPath);
+    // The facade package root holds `package.json` (with the direct kind
+    // dependency the kind-first publish reads); the manifest sits one level down
+    // in `block-pack/`. `readFacadeKindDependency`/`resolveFacadeKind` need the
+    // package root, not the block-pack dir.
+    const facadeDir = path.dirname(manifestRoot);
 
     logger.info(`Manifest root = ${manifestRoot}`);
+    logger.info(`Facade root = ${facadeDir}`);
 
     if (flags.versionOverride) manifest = overrideManifestVersion(manifest, flags.versionOverride);
 
     const storage = storageByUrl(flags.registry);
     const registry = new BlockRegistryV2(storage, logger);
 
-    await registry.publishPackage(manifest, async (file) =>
+    // Kind-first publish: resolve refs -> version-match gate (before any S3
+    // write) -> publishKind (if the block declares a kind) -> publishPackage.
+    await publishBlock(registry, manifest, facadeDir, async (file) =>
       Buffer.from(await fs.promises.readFile(path.resolve(manifestRoot, file))),
     );
 

package/src/structure/__tests__/model-package-json.snapshot.test.ts

@@ -29,6 +29,7 @@ const EXPECTED_MODEL_PACKAGE_JSON = `{
     "check": "ts-builder check --target block-model"
   },
   "dependencies": {
+    "@platforma-open/test-org.demo.kind": "workspace:*",
     "@platforma-sdk/model": "catalog:"
   },
   "devDependencies": {

package/src/structure/engine/api.ts

@@ -10,7 +10,7 @@
 
 import type { 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`. */

package/src/structure/engine/ctx.ts

@@ -55,6 +55,7 @@ export function modulesForInit(vars: BlockVars): Module[] {
     { scope: "root", name: facade, path: "" },
     { scope: "block", name: `${facade}.block`, path: "block" },
     { scope: "model", name: `${facade}.model`, path: "model" },
+    { scope: "kind", name: `${facade}.kind`, path: "kind" },
     { scope: "ui", name: `${facade}.ui`, path: "ui" },
     { scope: "workflow", name: `${facade}.workflow`, path: "workflow" },
     { scope: "test", name: `${facade}.test`, path: "test" },

package/src/structure/engine/discovery.ts

@@ -1,4 +1,4 @@
-// Workspace-package classification — the seven scope detection rules.
+// Workspace-package classification — the eight scope detection rules.
 //
 // Input: the parsed package.json of every workspace member, plus its
 // block-relative path. Output: `Module[]` (scope + name + path).
@@ -7,7 +7,16 @@
 
 import type { Module, Scope } from "./api";
 
-export const ALL_SCOPES: Scope[] = ["root", "block", "model", "ui", "workflow", "test", "software"];
+export const ALL_SCOPES: Scope[] = [
+  "root",
+  "block",
+  "model",
+  "ui",
+  "workflow",
+  "test",
+  "software",
+  "kind",
+];
 
 export type WorkspacePackage = {
   /** Block-relative path of the package — "" or "." means the
@@ -96,6 +105,11 @@ export function classifyOne(wp: WorkspacePackage): Scope | undefined {
 
   const deps = depKeys(wp.pkg);
 
+  // kind — @platforma-sdk/block-kind is unique to kind packages (no other scope
+  // depends on it). MUST precede the model rule: a kind sets `main`, and were it
+  // to carry any model-ish signal it would otherwise misclassify.
+  if (deps.has("@platforma-sdk/block-kind")) return "kind";
+
   // 1. software — top-level `block-software` field OR
   //    (package-builder AND any @platforma-open/*runenv* dep).
   if (wp.pkg["block-software"] !== undefined) return "software";

package/src/structure/rules/block-package-json.ts

@@ -153,6 +153,11 @@ export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown
     ...scopeDepMaps(ctx, "model"),
     ...scopeDepMaps(ctx, "ui"),
     ...scopeDepMaps(ctx, "workflow"),
+    // The kind is a fourth block component the facade depends on directly (the
+    // tetrad); like its siblings it is a build-time workspace devDep, never a
+    // runtime dependency, and it is NOT a bundled `block.component` (its content
+    // publishes to the `kinds/` registry tree, not into block-pack).
+    ...scopeDepMaps(ctx, "kind"),
   };
   // `block-tools pack` requires both `block.components` and `block.meta`. The
   // author edits the placeholder meta before publishing.
@@ -194,6 +199,18 @@ export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown
 export function blockPackageJsonRules(ctx: RunContext): void {
   const v = ctx.blockVars;
 
+  // The kind is a MANDATORY block component: every block must declare exactly
+  // one sibling `kind/` package. Fail loudly otherwise — a kind-less block is
+  // invalid, and this is what surfaces the not-yet-migrated blocks.
+  const kindModules = findModules(ctx, "kind");
+  if (kindModules.length !== 1) {
+    throw new Error(
+      kindModules.length === 0
+        ? `block '${v.facadeName}' declares no kind — every block must have a sibling kind/ package`
+        : `block '${v.facadeName}' declares ${kindModules.length} kinds; exactly one is required`,
+    );
+  }
+
   ensureField("type", "module");
   ensureField("files", ["dist", "block-pack"]);
   ensureField("main", "./dist/index.js");
@@ -212,6 +229,7 @@ export function blockPackageJsonRules(ctx: RunContext): void {
   ensureWorkspaceScopeDevDeps("model");
   ensureWorkspaceScopeDevDeps("ui");
   ensureWorkspaceScopeDevDeps("workflow");
+  ensureWorkspaceScopeDevDeps("kind");
   ensureDevDep("@milaboratories/ts-builder", "sdk:");
   ensureDevDep("@milaboratories/ts-configs", "sdk:");
   ensureDevDep("@platforma-sdk/block-tools", "sdk:");

package/src/structure/rules/kind-package-json.ts

@@ -0,0 +1,117 @@
+// Kind `package.json`: the initial generator and the drift-correcting body,
+// co-located. A kind is a private workspace sibling (like the model): its
+// content ships to the `kinds/` registry tree via `build-kind-manifest`, not to
+// npm. Identity (name/version) stays untouched; the body enforces
+// type/main/exports + canonical scripts + canonical dep sets, then projects
+// canonical field / dependency order (oxfmt-clean, so build->check passes with
+// no prior `pnpm fmt`).
+//
+// A kind builds TWICE, like the model: `dist/index.{js,cjs}` with dependencies
+// external — what a block imports — and the self-contained `dist/kind.js` that
+// the registry publishes and `build-kind-manifest` hashes. The `exports` map
+// points at the externalized pair only, so a kind and the block implementing it
+// share one copy of any dependency they both use; the self-contained bundle is
+// read off disk by the manifest builder and needs no export.
+//
+// All three of `import` / `require` / `default` are spelled out: `block-tools
+// build-model` loads the model via `require()`, and the model `require`s its
+// kind, so the CJS arm has to resolve to real CJS.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDep,
+  ensureDevDeps,
+  ensurePeerDeps,
+  removeScript,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  type RunContext,
+} from "../engine/api";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+
+const KIND_EXPORTS = {
+  ".": {
+    types: "./dist/index.d.ts",
+    sources: "./src/index.ts",
+    import: "./dist/index.js",
+    require: "./dist/index.cjs",
+    default: "./dist/index.js",
+  },
+};
+
+export function kindPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.kind`,
+    private: true,
+    type: "module",
+    // `main` is the CommonJS entry (require fallback), `module` the ESM one —
+    // the model's convention. `dist/kind.js`, the self-contained bundle, is
+    // deliberately not an entry: it exists for the registry, not for importers.
+    main: "./dist/index.cjs",
+    module: "./dist/index.js",
+    types: "./dist/index.d.ts",
+    exports: KIND_EXPORTS,
+    scripts: {
+      fmt: "ts-builder format",
+      watch: "ts-builder build --target block-kind --watch",
+      build: "ts-builder build --target block-kind && block-tools build-kind-manifest",
+      check: "ts-builder check --target block-kind",
+    },
+    // A kind ships a runtime params check, so it is not a types-only package — but the
+    // check is plain TypeScript, held to the contract by its return type, so nothing but
+    // the SDK is needed to write one. An author whose params shape earns a schema library
+    // adds it here themselves; seeding one would make every kind carry it to be deleted.
+    dependencies: {
+      "@platforma-sdk/block-kind": "sdk:",
+    },
+    devDependencies: {
+      "@milaboratories/ts-builder": "sdk:",
+      "@milaboratories/ts-configs": "sdk:",
+      "@platforma-sdk/block-tools": "sdk:",
+    },
+    peerDependencies: {
+      "@types/node": "*",
+      typescript: "*",
+    },
+  };
+}
+
+export function kindPackageJsonRules(): void {
+  // Controlled sibling — workspace-only, never published to npm. `private: true`
+  // makes npm refuse to publish it; the `version` is kept (changesets-owned) and
+  // is what the kind's on-wire `{name}@{version}` reference is baked from.
+  ensureField("private", true);
+
+  ensureField("type", "module");
+  ensureField("main", "./dist/index.cjs");
+  ensureField("module", "./dist/index.js");
+  ensureField("types", "./dist/index.d.ts");
+  ensureField("exports", KIND_EXPORTS);
+
+  ensureScript("fmt", "ts-builder format");
+  ensureScript("watch", "ts-builder build --target block-kind --watch");
+  ensureScript("build", "ts-builder build --target block-kind && block-tools build-kind-manifest");
+  ensureScript("check", "ts-builder check --target block-kind");
+  removeScript("lint");
+
+  ensureDep("@platforma-sdk/block-kind", "sdk:");
+
+  ensureDevDeps({
+    "@milaboratories/ts-builder": "sdk:",
+    "@milaboratories/ts-configs": "sdk:",
+    "@platforma-sdk/block-tools": "sdk:",
+  });
+
+  ensurePeerDeps({
+    "@types/node": "*",
+    typescript: "*",
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/kind.ts

@@ -0,0 +1,29 @@
+// Kind-scope rules. Static config files + managed package.json; the
+// `src/index.ts` seed is dropped by `init` and never touched again (the block
+// author owns the BlockParams contract). The seed is a deliberate non-building
+// sentinel — its BlockParams is undefined, so a scaffolded-but-unmigrated block
+// fails to typecheck until the params contract is chosen on purpose.
+
+import { scope, fixed, managed, seed, file, generate } from "../engine/api";
+import { kindPackageJsonInitial, kindPackageJsonRules } from "./kind-package-json";
+
+export function kindRules(): void {
+  scope("kind", () => {
+    fixed("tsconfig.json", file("kind/tsconfig.json"));
+    fixed(".oxlintrc.json", file("kind/.oxlintrc.json"));
+    fixed(".oxfmtrc.json", file("kind/.oxfmtrc.json"));
+
+    // Minimal-but-real kind: identity imported from the package's own
+    // package.json, plus a non-building BlockParams sentinel the block author
+    // must resolve (via the migration recipe or by hand) before the block builds.
+    seed("src/index.ts", file("kind/src/index.ts"));
+
+    managed(
+      "package.json",
+      generate((ctx) => kindPackageJsonInitial(ctx)),
+      () => {
+        kindPackageJsonRules();
+      },
+    );
+  });
+}

package/src/structure/rules/model-package-json.ts

@@ -15,6 +15,7 @@ import {
   ensureDep,
   ensureDevDep,
   ensureDevDeps,
+  ensureWorkspaceScopeDeps,
   removeDep,
   removeScript,
   removeField,
@@ -25,6 +26,7 @@ import {
   whenFilesExist,
   type RunContext,
 } from "../engine/api";
+import { scopeDepMaps } from "../engine/ctx";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
 import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
 import { removeRetiredToolchainDeps } from "./shared/retired-deps";
@@ -56,6 +58,9 @@ export function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown
     },
     dependencies: {
       "@platforma-sdk/model": "sdk:",
+      // The model imports its block's kind (to bake the kind reference into
+      // model.json), so it depends on the sibling kind package directly.
+      ...scopeDepMaps(ctx, "kind"),
     },
     devDependencies: {
       "@milaboratories/ts-builder": "sdk:",
@@ -95,6 +100,9 @@ export function modelPackageJsonRules(): void {
   ensureScript("check", "ts-builder check --target block-model");
 
   ensureDep("@platforma-sdk/model", "sdk:");
+  // The model imports its block's kind to bake the kind reference — direct
+  // dependency on the sibling kind package.
+  ensureWorkspaceScopeDeps("kind");
 
   ensureDevDeps({
     "@milaboratories/ts-builder": "sdk:",

package/src/structure/rules/model.ts

@@ -2,17 +2,22 @@
 // `src/index.ts` seed is dropped by `init` and never touched again
 // (block author owns it).
 
-import { scope, fixed, managed, seed, file, generate, when, whenFilesExist } from "../engine/api";
+import {
+  scope,
+  fixed,
+  managed,
+  seed,
+  file,
+  tpl,
+  generate,
+  when,
+  whenFilesExist,
+} from "../engine/api";
 import { modelPackageJsonInitial, modelPackageJsonRules } from "./model-package-json";
 import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
 
 export function modelRules(): void {
   scope("model", () => {
-    // Two static end states by co-located-test presence: a test-bearing model
-    // gets node ambient types (`.node.json`) so the tests type-check —
-    // `@types/node` is wired alongside by the package.json rule; a test-less
-    // model stays bare. `fixed` (engine-owned, whole-file overwrite) not
-    // `managed`, so refresh is idempotent by construction — no key-order drift.
     when(
       whenFilesExist(COLOCATED_TEST_GLOB),
       () => fixed("tsconfig.json", file("model/tsconfig.node.json")),
@@ -21,13 +26,10 @@ export function modelRules(): void {
     fixed(".oxlintrc.json", file("model/.oxlintrc.json"));
     fixed(".oxfmtrc.json", file("model/.oxfmtrc.json"));
 
-    // A minimal-but-REAL BlockModelV3: `build-model` rejects a non-model
-    // export ("Malformed model object"), and a bare `.create(dataModel)`
-    // still errors ("Args rendering function not set"). This seed is the
-    // smallest chain that produces a valid `dist/model.json` — empty data
-    // model, identity args, a single "Main" section. The block author owns
-    // and extends it after init.
-    seed("src/index.ts", file("model/src/index.ts"));
+    seed(
+      "src/index.ts",
+      tpl("model/src/index.tpl.ts", (ctx) => ({ kindPkg: `${ctx.blockVars.facadeName}.kind` })),
+    );
 
     managed(
       "package.json",

package/src/structure/rules/shared/pascal-case.ts

@@ -1,7 +1,7 @@
 // `pascalCase(shortName)` → the block-named alias prefix the facade entry
 // template emits (`<PascalName>BlockContract`, …). Splits on any run of
 // non-alphanumeric characters and capitalises each segment's first char:
-//   test-sum-numbers-v3  → TestSumNumbersV3
+//   test-sum-numbers  → TestSumNumbersV3
 //   mixcr-clonotyping-2  → MixcrClonotyping2
 //   samples-and-data     → SamplesAndData
 export function pascalCase(s: string): string {

package/src/structure/structure-definition.ts

@@ -8,6 +8,7 @@ import { rootRules } from "./rules/root";
 import { rootCiRules } from "./rules/root-ci";
 import { blockRules } from "./rules/block";
 import { modelRules } from "./rules/model";
+import { kindRules } from "./rules/kind";
 import { uiRules } from "./rules/ui";
 import { workflowRules } from "./rules/workflow";
 import { testRules } from "./rules/test";
@@ -20,6 +21,7 @@ export const STRUCTURE = defineStructure(() => {
   rootCiRules();
   blockRules();
   modelRules();
+  kindRules();
   uiRules();
   workflowRules();
   testRules();

package/src/structure/templates/static/kind/.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["node_modules/@milaboratories/ts-builder/configs/oxfmt.json"],
+  "ignorePatterns": ["dist", "coverage", "CHANGELOG.md"]
+}

package/src/structure/templates/static/kind/.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["node_modules/@milaboratories/ts-builder/dist/configs/oxlint-node.json"]
+}

package/src/structure/templates/static/kind/src/index.ts

@@ -0,0 +1,49 @@
+import { assertParamsObject, defineBlockKind } from "@platforma-sdk/block-kind";
+import { name, version } from "../package.json" with { type: "json" };
+
+/**
+ * This block's init-params contract — the shape a block of this kind receives
+ * at creation, and exactly what a project template serializes for it.
+ *
+ * TODO(block-kind): replace `NEEDS_BLOCK_PARAMS` with the real params shape, then
+ * wire the model's `init(({ params }) => …)` to consume them. If this block takes
+ * no author-supplied params, set it to `Record<string, never>` deliberately.
+ *
+ * This is an intentional sentinel: `NEEDS_BLOCK_PARAMS` is an undefined type, so
+ * the block fails to typecheck (TS2304) until the contract is chosen on purpose.
+ * A scaffolded-but-unmigrated block must never compile with an empty contract by
+ * default — see the block-kind migration recipe in the `block-dev` skill.
+ */
+export type BlockParams = NEEDS_BLOCK_PARAMS;
+
+/**
+ * The same contract at runtime, for params that arrive from a template file rather than
+ * from typed code — the only point that can catch a hand-written entry being wrong.
+ *
+ * TODO(block-kind): read each key `BlockParams` declares and say what it must be, then
+ * return them. Plain TypeScript is the default here: a kind owes no schema library, and a
+ * check written by hand is held to the contract by the return type. Reach for a validation
+ * library only where the shape earns it, and add it to this package's dependencies yourself.
+ *
+ * Check the fields the contract requires, and stop there. A key the contract does not name
+ * needs no rejection: it is dropped by not being read.
+ *
+ * This is a second intentional sentinel. The function has to return `BlockParams`, so
+ * `return {}` stops compiling the moment the contract declares a required field — the check
+ * cannot drift from the contract by being left behind. Never satisfy it with a cast: `value
+ * as BlockParams` compiles today and checks nothing forever.
+ */
+function parseInitializationParams(value: unknown): BlockParams {
+  assertParamsObject(value);
+
+  return {};
+}
+
+// Identity (`name`/`version`) comes from this package's own `package.json`, so
+// the on-wire `{name}@{version}` reference can never drift from what npm
+// publishes; the bundler inlines the JSON import.
+export const kind = defineBlockKind<BlockParams>({
+  name,
+  version,
+  parseInitializationParams,
+});

package/src/structure/templates/static/kind/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@milaboratories/ts-configs/block/facade",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*", "package.json"],
+  "exclude": ["dist", "node_modules"]
+}

package/src/structure/templates/text/model/src/index.tpl.ts

@@ -0,0 +1,18 @@
+import type { InferOutputsType } from "@platforma-sdk/model";
+import { BlockModelV3, DataModelBuilder } from "@platforma-sdk/model";
+import type { BlockParams } from "${kindPkg}";
+import { kind } from "${kindPkg}";
+
+export type BlockData = BlockParams;
+
+const dataModel = new DataModelBuilder({ kind })
+  .from<BlockData>("v1")
+  .init(({ params }) => params ?? {});
+
+export const platforma = BlockModelV3.create({ dataModel, kind })
+  .args(() => ({}))
+  .templateParams((data) => ({}))
+  .sections(() => [{ type: "link", href: "/", label: "Main" }])
+  .done();
+
+export type BlockOutputs = InferOutputsType<typeof platforma>;

package/src/v2/build_dist.ts

@@ -3,6 +3,7 @@ import type {
   ManifestFileInfo,
 } from "@milaboratories/pl-model-middle-layer";
 import { BlockPackManifest, BlockPackManifestFile } from "@milaboratories/pl-model-middle-layer";
+import type { BlockKindReference } from "@milaboratories/pl-model-common";
 import type { CompiledTemplateV3 } from "@milaboratories/pl-model-backend";
 import type { BlockPackDescriptionAbsolute } from "./model";
 import { consolidateBlockPackDescription } from "./model";
@@ -41,6 +42,33 @@ async function workflowRequiredCapabilities(
   return pack.template.requiredCapabilities;
 }
 
+/**
+ * Returns the block-kind reference the model config declares (baked at the
+ * container level by `BlockModelV3.done()`), or `undefined` for kind-less
+ * blocks or malformed model files — fail-safe, mirroring
+ * {@link workflowRequiredCapabilities}.
+ *
+ * Note: `build-model` writes `JSON.stringify(config)` where `config` is the
+ * `BlockConfigContainer` itself, so `kind` sits at the top level of
+ * `model.json` (not nested under a `config` key).
+ */
+async function modelKindReference(
+  descriptionRelative: BlockPackDescriptionManifest,
+  dst: string,
+): Promise<BlockKindReference | undefined> {
+  // After consolidateBlockPackDescription runs, components.model is always a
+  // `{type: "relative", path: ...}` reference into `dst`.
+  const model = descriptionRelative.components.model;
+  try {
+    const cfg = JSON.parse(await fsp.readFile(path.resolve(dst, model.path), "utf-8")) as {
+      kind?: BlockKindReference;
+    };
+    return cfg.kind ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function buildBlockPackDist(
   description: BlockPackDescriptionAbsolute,
   dst: string,
@@ -71,6 +99,13 @@ export async function buildBlockPackDist(
     };
   }
 
+  // Lift the model's container-level block-kind reference onto the manifest
+  // description (top-level, like featureFlags), so the published manifest
+  // advertises which kind the block implements. Fail-safe undefined leaves
+  // kind-less blocks unprojected.
+  const kindRef = await modelKindReference(descriptionRelative, dst);
+  if (kindRef) descriptionRelative.kind = kindRef;
+
   const filesForManifest = await Promise.all(
     files.map(async (f): Promise<ManifestFileInfo> => {
       const bytes = await fsp.readFile(path.resolve(dst, f));