@platforma-sdk/block-tools 2.10.16 → 2.10.18

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

@@ -51,5 +51,5 @@ export type RunContext = {
 };
 export type { ContentForm, ManagedBody, RunMode, Structure, TriggerFn };
 export { defineStructure, scope, when, whenFilesExist, onUpdateDeps, onInitOrUpdate, fixed, managed, scaffold, seed, remove, rename, file, binaryFile, text, tpl, generate, blockVars, } from './builders';
-export { ensureField, removeField, requireField, ensureFieldEntries, ensureScript, removeScript, ensureDep, ensureDevDep, ensurePeerDep, ensureOptionalDep, removeDep, ensureDeps, ensureDevDeps, ensurePeerDeps, ensureOptionalDeps, ensureWorkspaceScopeDeps, ensureWorkspaceScopeDevDeps, ensureWorkspaceScopePeerDeps, pruneKeysMatching, pruneKeysMatchingAt, enforceFieldOrder, enforceFieldOrderAt, enforceAlphabeticalOrder, transformAt, ensureWorkspaceModulePaths, ensureCatalogVersion, pinCatalogTo, ensureCatalogLatest, ensureCatalogAbsent, ensureGitignoreEntries, removeGitignoreEntries, withManagedBody, withManagedYaml, withManagedLines, } from './content-rules';
+export { ensureField, removeField, requireField, ensureFieldEntries, ensureScript, removeScript, ensureDep, ensureDevDep, ensurePeerDep, ensureOptionalDep, removeDep, ensureDeps, ensureDevDeps, ensurePeerDeps, ensureOptionalDeps, ensureWorkspaceScopeDeps, ensureWorkspaceScopeDevDeps, ensureWorkspaceScopePeerDeps, pruneKeysMatching, pruneKeysMatchingAt, enforceFieldOrder, enforceFieldOrderAt, enforceAlphabeticalOrder, transformAt, ensureWorkspaceModulePaths, ensureCatalogVersion, pinCatalogTo, pinCatalogToDependencyOf, ensureCatalogLatest, ensureCatalogAbsent, ensureGitignoreEntries, removeGitignoreEntries, withManagedBody, withManagedYaml, withManagedLines, } from './content-rules';
 export type { DepVersion } from './content-rules';

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

@@ -30,17 +30,17 @@ type InnerWhenHandler = (trigger: TriggerFn, body: () => void) => boolean;
  *  `content-rules.ts` at load time to avoid a circular import). */
 export declare function registerInnerWhenHandler(h: InnerWhenHandler): void;
 /**
- * Conditionally run `body`. Two dispatch modes by active state:
- *  - inside `defineStructure(...)` → push a `WhenFrame` into the tree;
- *    trigger fires later at runner time per `FlatItem`.
- *  - inside a `managed(...)` body → evaluate `trigger` immediately
- *    against the runner-supplied `TriggerContext`; run/skip `body`
- *    synchronously.
+ * Conditionally run `body`, with an optional `elseBody`. One `when` symbol for
+ * both layers — `dispatchWhen` picks the timing:
+ *  - inside `defineStructure(...)` → register a `WhenFrame`; its trigger fires
+ *    later, per module, at runner time.
+ *  - inside a `managed(...)` body → evaluate the trigger against the live block
+ *    now and run/skip synchronously.
  *
- * One `when` symbol for both layers — same user contract, dispatch
- * picks the matching execution timing.
+ * `else` is just the negated trigger dispatched the same way, so exactly one
+ * branch applies (in either layer).
  */
-export declare function when(trigger: TriggerFn, body: () => void): void;
+export declare function when(trigger: TriggerFn, body: () => void, elseBody?: () => void): void;
 /** Trigger factory: true when at least one file in the leaf's module
  *  matches `glob` (module-relative — see `TriggerContext.filesMatch`). Use
  *  to gate a rule on the presence of co-located files, e.g. add a vitest

package/dist/structure/engine/content-rules.d.ts

@@ -35,6 +35,9 @@ export type WithManagedYamlOpts = WithManagedOpts & {
     /** Sync accessor for prefetched latest versions. Required for
      *  `ensureCatalogLatest` to take effect. */
     getLatestVersion?: (packageName: string) => string | undefined;
+    /** Sync accessor for prefetched derived catalog pins. Required for
+     *  `pinCatalogToDependencyOf` to take effect. */
+    getDerivedDependencyPin?: (catalogEntry: string) => string | undefined;
 };
 /** Engine-internal: run `body` with `doc` as the active YAML state (for
  *  `pnpm-workspace.yaml`); returns the mutated document. Exported for tests. */
@@ -140,6 +143,20 @@ export declare function pinCatalogTo(name: string, version: string): void;
  *  and refreshes a present one, and on `init` it overwrites the
  *  placeholder with the real latest. */
 export declare function ensureCatalogLatest(name: string): void;
+/** Pin `catalog.<catalogEntry>` to the EXACT version that package `opts.of`
+ *  declares for `catalogEntry` in its own manifest (read at npm latest, or at
+ *  `opts.ofVersion` if given). The value is resolved by the runner's
+ *  prefetched `getDerivedDependencyPin` accessor (the caller pre-resolves and
+ *  validates — exact-version-only — at prefetch time; no network here).
+ *  OVERWRITES like `pinCatalogTo` (not add-if-absent): a pre-existing loose
+ *  entry (`vue: ^3.5.24`) is tightened to the exact derived version. No-op
+ *  when no derived-pin lookup is available — default refresh/check pass none,
+ *  leaving the entry exactly as the lockfile has it; the resolution leaves
+ *  live in the `onInitOrUpdate` frame. */
+export declare function pinCatalogToDependencyOf(catalogEntry: string, _opts: {
+    of: string;
+    ofVersion?: string;
+}): void;
 /** Remove `catalog.<name>` if present; no-op when absent. */
 export declare function ensureCatalogAbsent(name: string): void;
 /** Append each `entry` if not already present (comment-aware equality). */

package/dist/structure/engine/registry-client.d.ts

@@ -1,5 +1,10 @@
 export interface RegistryClient {
     getLatestVersion(packageName: string): Promise<string>;
+    /** Read the version `packageName@version` declares for `depName` in its
+     *  published manifest. `version` may be "latest" (resolved via the
+     *  dist-tags). Looks in `dependencies` first, then `peerDependencies`.
+     *  Returns `undefined` when the dep is declared in neither section. */
+    getDeclaredDependency(packageName: string, version: string, depName: string): Promise<string | undefined>;
 }
 /** Parse the HTTP Retry-After header (RFC 9110): either a delay in
  *  seconds or an absolute HTTP-date. Returns the delay in ms, or null
@@ -7,8 +12,10 @@ export interface RegistryClient {
 export declare function parseRetryAfter(header: string | null): number | null;
 /** Live npm registry client. Hits the network on each call. */
 export declare function createRealRegistryClient(): RegistryClient;
-/** In-memory client backed by a fixed `name → version` map. */
-export declare function createMockRegistryClient(versions: Record<string, string>): RegistryClient;
+/** In-memory client backed by a fixed `name → version` map. The optional
+ *  `manifests` map (`pkg@version` → declared deps) backs
+ *  `getDeclaredDependency`; "latest" keys resolve via the `versions` map. */
+export declare function createMockRegistryClient(versions: Record<string, string>, manifests?: Record<string, Record<string, string>>): RegistryClient;
 /** Resolve a batch of `name → latest` entries in parallel. */
 export declare function prefetchLatestVersions(client: RegistryClient, packageNames: readonly string[]): Promise<Map<string, string>>;
 /** Build a sync lookup function (the shape `withManagedYaml` consumes)
@@ -32,3 +39,24 @@ export declare function matchesBumpPattern(name: string): boolean;
  *  (callers that require the network — `init` — let it propagate).
  *  `client` defaults to the live npm client; tests inject a mock. */
 export declare function buildRegistryLookupForNames(names: readonly string[], client?: RegistryClient): Promise<(packageName: string) => string | undefined>;
+/** A catalog entry whose version is DERIVED from the version another
+ *  package declares for it. `entry` is the catalog key (== the dep name in
+ *  the source manifest); `of` is the package whose manifest is read; the
+ *  optional `ofVersion` pins which release of `of` to read (default: npm
+ *  latest, the same release the catalog bump pins `of` to). Consumed by
+ *  `pinCatalogToDependencyOf`. */
+export type DerivedCatalogPin = {
+    entry: string;
+    of: string;
+    ofVersion?: string;
+};
+/** Prefetch every derived pin and build the sync lookup the runner passes
+ *  to `pinCatalogToDependencyOf` (`entry → exact version`). Reads
+ *  `pin.of`'s manifest (at `pin.ofVersion`, default npm latest) and the
+ *  version it declares for `pin.entry`. Policy (b): THROWS at prefetch time
+ *  if the source declares the dep as a non-exact (ranged) version or does
+ *  not declare it at all — a derived pin must resolve to an exact version
+ *  or it is a configuration error. Empty list → a lookup that resolves
+ *  nothing (no network). A registry failure REJECTS. `client` defaults to
+ *  the live npm client; tests inject a mock. */
+export declare function buildDerivedPinLookupForPins(pins: readonly DerivedCatalogPin[], client?: RegistryClient): Promise<(entry: string) => string | undefined>;

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

@@ -32,6 +32,12 @@ export type RunOptions = {
      *  and passes the resulting sync map here; unit tests pass a mock.
      *  Absent → `ensureCatalogLatest` is a no-op (default refresh). */
     registryLookup?: (packageName: string) => string | undefined;
+    /** Sync accessor for prefetched derived catalog pins
+     *  (`catalogEntry → exact version`), consumed by `pinCatalogToDependencyOf`
+     *  inside `onInitOrUpdate` managed bodies. The CLI / init constructor
+     *  prefetches + validates these before the run (network). Absent →
+     *  `pinCatalogToDependencyOf` is a no-op (default refresh). */
+    derivedPinLookup?: (catalogEntry: string) => string | undefined;
 };
 export declare class RecheckError extends Error {
     readonly failing: Change;

package/dist/structure/rules/root-pnpm-workspace.d.ts

@@ -1,4 +1,5 @@
 import { RunContext } from '../engine/api';
+import { DerivedCatalogPin } from '../engine/registry-client';
 /** SDK packages that live in the catalog (membership only — no versions).
  *  Init fetches npm latest for each; refresh leaves them as the lockfile has
  *  them. */
@@ -6,6 +7,18 @@ export declare const SDK_CATALOG_PACKAGES: readonly string[];
 /** Infra / tooling — a `~`-floored curated set. Not exact-pinned on refresh
  *  and not bumped by update-deps. */
 export declare const INFRA_CATALOG_FLOOR: Record<string, string>;
+/** Catalog entries whose exact version is DERIVED from the version another
+ *  package declares for them (see `pinCatalogToDependencyOf`). Resolved on
+ *  init + update-deps and OVERWRITES the on-disk entry.
+ *
+ *  `vue`: the seeded ui depends on `vue` (catalog:). `@platforma-sdk/ui-vue`
+ *  pins vue as an EXACT regular dependency (not a peer), so the block must
+ *  pin the SAME exact version — a floated `~` lets the ui resolve a newer
+ *  3.5.x than ui-vue's, yielding two vue instances and a SdkPluginV3-vs-Plugin
+ *  type clash in `main.ts`. Deriving the pin from ui-vue's declared dep keeps
+ *  the block in lockstep with whatever vue ui-vue's npm-latest pins, with no
+ *  hand-maintained version here. */
+export declare const DERIVED_CATALOG_PINS: readonly DerivedCatalogPin[];
 /** Catalog name of the python runenv. Added to a block's catalog only when
  *  the block carries a software module. Pinned to an EXACT version — updating
  *  the python runenv is an explicit author decision, never automatic. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.10.16",
+  "version": "2.10.18",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -35,11 +35,11 @@
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/pl-model-middle-layer": "1.30.6",
-    "@milaboratories/pl-model-backend": "1.4.7",
-    "@milaboratories/resolve-helper": "1.1.3",
     "@milaboratories/pl-model-common": "1.46.1",
-    "@milaboratories/ts-helpers-oclif": "1.1.42",
+    "@milaboratories/resolve-helper": "1.1.3",
+    "@milaboratories/pl-model-backend": "1.4.7",
     "@milaboratories/ts-helpers": "1.8.3",
+    "@milaboratories/ts-helpers-oclif": "1.1.42",
     "@platforma-sdk/blocks-deps-updater": "2.2.0"
   },
   "devDependencies": {
@@ -57,8 +57,8 @@
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^4.1.3",
     "@milaboratories/oclif-index": "1.1.1",
-    "@milaboratories/ts-builder": "1.5.0",
     "@milaboratories/ts-configs": "1.2.3",
+    "@milaboratories/ts-builder": "1.5.2",
     "@milaboratories/build-configs": "2.0.0"
   },
   "oclif": {

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

@@ -34,8 +34,7 @@ const EXPECTED_MODEL_PACKAGE_JSON = `{
   "devDependencies": {
     "@milaboratories/ts-builder": "catalog:",
     "@milaboratories/ts-configs": "catalog:",
-    "@platforma-sdk/block-tools": "catalog:",
-    "vitest": "catalog:"
+    "@platforma-sdk/block-tools": "catalog:"
   },
   "peerDependencies": {
     "@types/node": "*",

package/src/structure/__tests__/tsconfig-idempotency.test.ts

@@ -0,0 +1,94 @@
+// Regression: a test-bearing model/ui scope migrating from a LEGACY tsconfig
+// must converge in a single pass.
+//
+// History: the tsconfig used to be a `managed` file whose body did
+// `removeField("compilerOptions")`, conditionally re-added
+// `compilerOptions.types: ["node"]`, then `ensureField("include", …)`. On a
+// legacy tsconfig with no `include`, pass 1 appended `include` AFTER the
+// re-added `compilerOptions` → `{extends, compilerOptions, include}`, while the
+// body's fixpoint was `{extends, include, compilerOptions}`. The two differed
+// only in key order, so the engine's post-run recheck saw a phantom diff and
+// `refresh` aborted with a non-idempotency RecheckError on EVERY test-bearing
+// block migrating off a legacy (vite-era) tsconfig.
+//
+// Now the tsconfig is a `fixed` file with two static end states selected by a
+// `when`/else on co-located-test presence (`tsconfig.node.json` vs
+// `tsconfig.json`). There is no imperative body and no insertion-order side
+// effect, so single-pass idempotency holds by construction. This test guards
+// that property.
+
+import { describe, test, expect } from "vitest";
+import { simulateInit, defaultTemplateProvider } from "../engine/testing";
+import { run as engineRun } from "../engine/runner";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { STRUCTURE } from "../structure-definition";
+import { SDK_CATALOG_PACKAGES } from "../rules/root-pnpm-workspace";
+import type { BlockVars } from "../engine/api";
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+const mockLookup = (name: string): string | undefined =>
+  SDK_CATALOG_PACKAGES.includes(name) ? "9.9.9" : undefined;
+
+// `refresh` runs the full engine INCLUDING the post-run recheck (via
+// `rediscover`); a non-idempotent rule set makes this throw.
+function refresh(fs: ReturnType<typeof simulateInit>["fs"]) {
+  const ctx = discoverRunContext({ fs, isSdkInternal: false });
+  engineRun(STRUCTURE, fs, ctx, {
+    templates: defaultTemplateProvider(),
+    rediscover: () => discoverRunContext({ fs, isSdkInternal: false, dryRun: true }),
+  });
+}
+
+const CANONICAL_ORDER = ["extends", "compilerOptions", "include"];
+
+describe("tsconfig first-pass idempotency on legacy (no-include) tsconfig", () => {
+  test("model + ui co-located tests, legacy tsconfig without `include` → refresh converges in one pass", () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+
+    // Co-located unit tests in both scopes -> the conditional node-types re-add fires.
+    fs.write("model/src/m.test.ts", `import { test } from "vitest";\ntest("x", () => {});\n`);
+    fs.write("ui/src/u.test.ts", `import { test } from "vitest";\ntest("x", () => {});\n`);
+
+    // Legacy tsconfigs as a vite-era block carried them: a `compilerOptions`
+    // block and NO top-level `include`. This is what made pass 1 append
+    // `include` after the re-added `compilerOptions`.
+    fs.write(
+      "model/tsconfig.json",
+      JSON.stringify({
+        extends: "@milaboratories/ts-configs/block/model",
+        compilerOptions: { strict: true },
+      }),
+    );
+    fs.write(
+      "ui/tsconfig.json",
+      JSON.stringify({
+        extends: "@milaboratories/ts-configs/block/ui",
+        compilerOptions: { strict: true },
+      }),
+    );
+
+    // Without the fix this throws RecheckError (rule set not idempotent).
+    expect(() => refresh(fs)).not.toThrow();
+
+    for (const scope of ["model", "ui"]) {
+      const ts = JSON.parse(fs.read(`${scope}/tsconfig.json`)) as {
+        extends: string;
+        include: string[];
+        compilerOptions: { types: string[] };
+      };
+      // Canonical, deterministic key order.
+      expect(Object.keys(ts)).toEqual(CANONICAL_ORDER);
+      expect(ts.extends).toBe(`@milaboratories/ts-configs/block/${scope}`);
+      expect(ts.include).toEqual(["src/**/*"]);
+      // node types wired (co-located test present); legacy `strict` pruned.
+      expect(ts.compilerOptions).toEqual({ types: ["node"] });
+    }
+  });
+});

package/src/structure/cli/run-structure.ts

@@ -11,8 +11,12 @@ import { NodeTemplateProvider } from "../engine/templates";
 import { run as engineRun, type Change } from "../engine/runner";
 import { discoverRunContext } from "../engine/discovery-fs";
 import { STRUCTURE } from "../structure-definition";
-import { matchesBumpPattern, buildRegistryLookupForNames } from "../engine/registry-client";
-import { SDK_CATALOG_PACKAGES } from "../rules/root-pnpm-workspace";
+import {
+  matchesBumpPattern,
+  buildRegistryLookupForNames,
+  buildDerivedPinLookupForPins,
+} from "../engine/registry-client";
+import { SDK_CATALOG_PACKAGES, DERIVED_CATALOG_PINS } from "../rules/root-pnpm-workspace";
 
 export type StructureMode = "check" | "refresh";
 
@@ -60,10 +64,16 @@ export async function runStructureForPath(input: RunStructureInput): Promise<Run
   });
 
   const registryLookup = input.updateDepsOnly ? await buildRegistryLookup() : undefined;
+  // Derived catalog pins (e.g. vue ← ui-vue's declared dep) resolve on the
+  // same prefetch budget as the SDK latest bump; absent on a default refresh.
+  const derivedPinLookup = input.updateDepsOnly
+    ? await buildDerivedPinLookupForPins(DERIVED_CATALOG_PINS)
+    : undefined;
 
   const result = engineRun(STRUCTURE, fs, ctx, {
     templates,
     registryLookup,
+    derivedPinLookup,
     // Fresh re-discovery for the post-run recheck (default refresh only)
     // — re-reads the just-written tree so a rename that shifted the
     // module map is observed.

package/src/structure/engine/__tests__/content-rules/pin-catalog-to-dependency-of.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "vitest";
+import { pinCatalogToDependencyOf, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+
+// The builder is sync: it reads a value the runner pre-resolved + validated
+// into `getDerivedDependencyPin`. These tests inject that accessor directly.
+const lookup =
+  (m: Record<string, string>) =>
+  (entry: string): string | undefined =>
+    m[entry];
+
+describe("pinCatalogToDependencyOf (mocked derived-pin lookup)", () => {
+  test("overwrites a present LOOSE entry with the derived exact version", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ vue: "3.5.24" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("3.5.24");
+  });
+
+  test("creates an absent entry", () => {
+    const doc = parseYaml("catalog:\n  unrelated: 1.0.0\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ vue: "3.5.24" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("3.5.24");
+    expect(cat.unrelated).toBe("1.0.0");
+  });
+
+  test("no-op when no derived-pin lookup is provided (default refresh)", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }));
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("^3.5.24");
+  });
+
+  test("no-op when the entry was not prefetched (lookup returns undefined)", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ other: "1.0.0" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("^3.5.24");
+  });
+
+  test("idempotent — second run produces the same YAML", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    const opts = { getDerivedDependencyPin: lookup({ vue: "3.5.24" }) };
+    withManagedYaml(
+      doc,
+      () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }),
+      opts,
+    );
+    const once = stringifyYaml(doc);
+    withManagedYaml(
+      doc,
+      () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }),
+      opts,
+    );
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/when-inner.test.ts

@@ -222,6 +222,36 @@ describe("when() — inner-mode dispatch inside managed bodies", () => {
     ).toThrow(/outside defineStructure.*outside any managed/);
   });
 
+  test("else branch: predicate=true runs body, skips else", () => {
+    const out = withManagedBody(
+      {} as JsonObject,
+      () => {
+        when(
+          ({ pathExists }) => pathExists("tests/"),
+          () => ensureField("branch", "if"),
+          () => ensureField("branch", "else"),
+        );
+      },
+      { triggerContext: makeTctx({ paths: new Set(["tests/"]) }) },
+    );
+    expect(out.branch).toBe("if");
+  });
+
+  test("else branch: predicate=false runs else, skips body", () => {
+    const out = withManagedBody(
+      {} as JsonObject,
+      () => {
+        when(
+          ({ pathExists }) => pathExists("tests/"),
+          () => ensureField("branch", "if"),
+          () => ensureField("branch", "else"),
+        );
+      },
+      { triggerContext: makeTctx({ paths: new Set() }) },
+    );
+    expect(out.branch).toBe("else");
+  });
+
   test("idempotent — double-run yields the same parsed state", () => {
     const body = () => {
       ensureField("type", "module");

package/src/structure/engine/__tests__/derived-pin-lookup.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "vitest";
+import { buildDerivedPinLookupForPins, createMockRegistryClient } from "../registry-client";
+
+describe("buildDerivedPinLookupForPins (mocked registry)", () => {
+  test("resolves the catalog entry to the source's declared exact dep version", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { vue: "3.5.24" } },
+    );
+    const lookup = await buildDerivedPinLookupForPins(
+      [{ entry: "vue", of: "@platforma-sdk/ui-vue" }],
+      client,
+    );
+    expect(lookup("vue")).toBe("3.5.24");
+    expect(lookup("unrelated")).toBeUndefined();
+  });
+
+  test("reads from a pinned source version when `ofVersion` is given", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "9.9.9" }, // latest — must NOT be used
+      { "@platforma-sdk/ui-vue@1.79.3": { vue: "3.5.20" } },
+    );
+    const lookup = await buildDerivedPinLookupForPins(
+      [{ entry: "vue", of: "@platforma-sdk/ui-vue", ofVersion: "1.79.3" }],
+      client,
+    );
+    expect(lookup("vue")).toBe("3.5.20");
+  });
+
+  test("empty pin list → lookup returns undefined for everything", async () => {
+    const lookup = await buildDerivedPinLookupForPins([], createMockRegistryClient({}));
+    expect(lookup("vue")).toBeUndefined();
+  });
+
+  test("policy (b): throws when the source declares a NON-EXACT range", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { vue: "^3.5.24" } },
+    );
+    await expect(
+      buildDerivedPinLookupForPins([{ entry: "vue", of: "@platforma-sdk/ui-vue" }], client),
+    ).rejects.toThrow(/not an exact version/i);
+  });
+
+  test("policy (b): throws when the source declares no such dependency", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { react: "19.0.0" } },
+    );
+    await expect(
+      buildDerivedPinLookupForPins([{ entry: "vue", of: "@platforma-sdk/ui-vue" }], client),
+    ).rejects.toThrow(/declares no/i);
+  });
+});

package/src/structure/engine/api.ts

@@ -117,6 +117,7 @@ export {
   ensureWorkspaceModulePaths,
   ensureCatalogVersion,
   pinCatalogTo,
+  pinCatalogToDependencyOf,
   ensureCatalogLatest,
   ensureCatalogAbsent,
   // Lines managed builders

package/src/structure/engine/builders.ts

@@ -193,34 +193,49 @@ export function registerInnerWhenHandler(h: InnerWhenHandler): void {
 }
 
 /**
- * Conditionally run `body`. Two dispatch modes by active state:
- *  - inside `defineStructure(...)` → push a `WhenFrame` into the tree;
- *    trigger fires later at runner time per `FlatItem`.
- *  - inside a `managed(...)` body → evaluate `trigger` immediately
- *    against the runner-supplied `TriggerContext`; run/skip `body`
- *    synchronously.
+ * Conditionally run `body`, with an optional `elseBody`. One `when` symbol for
+ * both layers — `dispatchWhen` picks the timing:
+ *  - inside `defineStructure(...)` → register a `WhenFrame`; its trigger fires
+ *    later, per module, at runner time.
+ *  - inside a `managed(...)` body → evaluate the trigger against the live block
+ *    now and run/skip synchronously.
  *
- * One `when` symbol for both layers — same user contract, dispatch
- * picks the matching execution timing.
+ * `else` is just the negated trigger dispatched the same way, so exactly one
+ * branch applies (in either layer).
  */
-export function when(trigger: TriggerFn, body: () => void): void {
+export function when(trigger: TriggerFn, body: () => void, elseBody?: () => void): void {
+  dispatchWhen(trigger, body);
+  if (elseBody) dispatchWhen((tctx) => !trigger(tctx), elseBody);
+}
+
+/** Single-branch dispatch shared by both `when` branches. In a managed body the
+ *  handler runs `body` iff its trigger holds and returns whether a managed-body
+ *  context existed; no context — and not tree-build either — means `when()` was
+ *  called outside both layers, a misuse. */
+function dispatchWhen(trigger: TriggerFn, body: () => void): void {
   if (activeTree) {
-    const t = activeTree;
-    const frame: WhenFrame = { kind: "when", trigger, children: [] };
-    t.stack[t.stack.length - 1]!.push(frame);
-    t.stack.push(frame.children);
-    try {
-      body();
-    } finally {
-      t.stack.pop();
-    }
+    pushWhenFrame(trigger, body);
     return;
   }
-  if (innerWhenHandler && innerWhenHandler(trigger, body)) return;
-  throw new Error(
-    "when() called outside defineStructure() and outside any managed(...) body. " +
-      "Place this call inside one of the two.",
-  );
+  const handled = innerWhenHandler?.(trigger, body) ?? false;
+  if (!handled) {
+    throw new Error(
+      "when() called outside defineStructure() and outside any managed(...) body. " +
+        "Place this call inside one of the two.",
+    );
+  }
+}
+
+function pushWhenFrame(trigger: TriggerFn, body: () => void): void {
+  const t = activeTree!;
+  const frame: WhenFrame = { kind: "when", trigger, children: [] };
+  t.stack[t.stack.length - 1]!.push(frame);
+  t.stack.push(frame.children);
+  try {
+    body();
+  } finally {
+    t.stack.pop();
+  }
 }
 
 /** Trigger factory: true when at least one file in the leaf's module

package/src/structure/engine/content-rules.ts

@@ -83,6 +83,9 @@ type YamlState = {
   triggerContext?: TriggerContext;
   /** Synchronous accessor for prefetched npm latest versions. */
   getLatestVersion?: (packageName: string) => string | undefined;
+  /** Synchronous accessor for prefetched derived catalog pins
+   *  (`catalogEntry → exact version`); see `pinCatalogToDependencyOf`. */
+  getDerivedDependencyPin?: (catalogEntry: string) => string | undefined;
 };
 
 type LinesState = {
@@ -177,6 +180,9 @@ export type WithManagedYamlOpts = WithManagedOpts & {
   /** Sync accessor for prefetched latest versions. Required for
    *  `ensureCatalogLatest` to take effect. */
   getLatestVersion?: (packageName: string) => string | undefined;
+  /** Sync accessor for prefetched derived catalog pins. Required for
+   *  `pinCatalogToDependencyOf` to take effect. */
+  getDerivedDependencyPin?: (catalogEntry: string) => string | undefined;
 };
 
 /** Engine-internal: run `body` with `doc` as the active YAML state (for
@@ -193,6 +199,7 @@ export function withManagedYaml(
     ctx: opts.ctx,
     triggerContext: opts.triggerContext,
     getLatestVersion: opts.getLatestVersion,
+    getDerivedDependencyPin: opts.getDerivedDependencyPin,
   };
   try {
     body();
@@ -579,6 +586,28 @@ export function ensureCatalogLatest(name: string): void {
   state.doc.setIn(["catalog", name], latest);
 }
 
+/** Pin `catalog.<catalogEntry>` to the EXACT version that package `opts.of`
+ *  declares for `catalogEntry` in its own manifest (read at npm latest, or at
+ *  `opts.ofVersion` if given). The value is resolved by the runner's
+ *  prefetched `getDerivedDependencyPin` accessor (the caller pre-resolves and
+ *  validates — exact-version-only — at prefetch time; no network here).
+ *  OVERWRITES like `pinCatalogTo` (not add-if-absent): a pre-existing loose
+ *  entry (`vue: ^3.5.24`) is tightened to the exact derived version. No-op
+ *  when no derived-pin lookup is available — default refresh/check pass none,
+ *  leaving the entry exactly as the lockfile has it; the resolution leaves
+ *  live in the `onInitOrUpdate` frame. */
+export function pinCatalogToDependencyOf(
+  catalogEntry: string,
+  _opts: { of: string; ofVersion?: string },
+): void {
+  const state = requireYaml("pinCatalogToDependencyOf");
+  if (!state.getDerivedDependencyPin) return;
+  const version = state.getDerivedDependencyPin(catalogEntry);
+  if (version === undefined) return;
+  if (readCatalogString(state, catalogEntry) === version) return;
+  state.doc.setIn(["catalog", catalogEntry], version);
+}
+
 /** Remove `catalog.<name>` if present; no-op when absent. */
 export function ensureCatalogAbsent(name: string): void {
   const state = requireYaml("ensureCatalogAbsent");