@milaboratories/pl-model-common 1.47.3 → 1.49.0

package/dist/template/project_template_v1.js

@@ -0,0 +1,225 @@
+import { splitVersionedName } from "../bmodel/block_kind_ref.js";
+import { parseKindSelector, parseKindSelectorReference } from "./kind_selector.js";
+//#region src/template/project_template_v1.ts
+/**
+* Value of a template file's `schema` field — the format marker every
+* `template-v1` document opens with.
+*/
+const PROJECT_TEMPLATE_SCHEMA_V1 = "template-v1";
+/**
+* Split a {@link BlockPackReference} into `{ name, version }`.
+*
+* @throws if the reference carries no version segment or the version is not
+*   exactly `X.Y.Z`
+*/
+function parseBlockPackReference(ref) {
+	const { name, version } = splitVersionedName(ref, "block package reference", "{name}@X.Y.Z");
+	const selector = parseKindSelector(version);
+	if (selector.op !== "exact") throw new Error(`A 'block' override must pin an exact version (expected '{name}@X.Y.Z'): ${ref}`);
+	return {
+		name,
+		version: selector.version
+	};
+}
+/**
+* Read the scheme off a {@link BlockPackLocationReference}, which is all the
+* document layer knows about it — resolving the rest belongs to whoever can reach
+* the scheme.
+*
+* A scheme is required. Accepting a bare path would mean reading it relative to
+* whatever directory the application happens to have been started from, which is
+* exactly the ambiguity a locator exists to remove.
+*
+* @throws if the value carries no scheme
+*/
+function parseBlockPackLocation(ref) {
+	const match = LocationSchemePattern.exec(ref);
+	if (!match) throw new Error(`A 'location' must be an absolute URI with a scheme (expected e.g. 'file:///path/to/block'), got: ${ref}`);
+	return { scheme: match.groups.scheme.toLowerCase() };
+}
+/**
+* Scheme grammar, with one deliberate narrowing: a scheme is at least TWO
+* characters, while the URI grammar allows one.
+*
+* `C:\blocks\my-block` is a valid single-letter-scheme URI, so a Windows path
+* pasted into the field would otherwise be accepted with scheme `c` and then fail
+* far away from the mistake. Rejecting it here means the error names the actual
+* problem, and the fix — `file:///C:/blocks/my-block` — is spelled out.
+*/
+const LocationSchemePattern = /^(?<scheme>[A-Za-z][A-Za-z0-9+.-]+):/;
+/**
+* One issue as a line: `blocks[2].kind: Expected a kind reference, got nothing.`
+*
+* Indexes read as they are written in the file — `blocks[2]`, not `blocks.2` — so the place
+* can be found by reading rather than by counting.
+*/
+function formatTemplateParseIssue(issue) {
+	const path = issue.path.reduce((acc, segment) => typeof segment === "number" ? `${acc}[${segment}]` : acc === "" ? segment : `${acc}.${segment}`, "");
+	return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+/**
+* Every problem a document has, thrown once so a caller fixes the file in one pass.
+*
+* The issues are in `message` as well as on `issues`, because a throw that escapes to a log is
+* read as its message and nothing else.
+*/
+var ProjectTemplateV1ParseError = class extends Error {
+	issues;
+	constructor(issues) {
+		super([`The template document could not be read (${issues.length} problem(s)):`, ...issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`)].join("\n"));
+		this.issues = issues;
+		this.name = "ProjectTemplateV1ParseError";
+	}
+};
+const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Keys an entry may carry. Anything else is a mistake, not an extension point. */
+const ENTRY_KEYS = [
+	"id",
+	"kind",
+	"block",
+	"location",
+	"params"
+];
+/**
+* Read an already-decoded template document — the value a YAML or JSON reader returns.
+*
+* Checks the format marker, every entry's shape, the reference grammars and id uniqueness,
+* and settles an omitted `params` to `{}`. Unknown keys are refused rather than ignored: a
+* misspelled key that was silently dropped would apply a file that does not say what its
+* author meant.
+*
+* It does NOT check what an entry's params point at, and nothing downstream of it does
+* either. Which values in there carry block ids is knowable only to the block, in its own
+* bundle, where the params are relocated onto the project being built — so a reference to an
+* entry listed later, or to the entry holding it, is not refused here. It survives into the
+* applied project as a block whose references name nothing, which is how a reference to a
+* deleted block already behaves.
+*
+* Collects rather than stops: a file with three mistakes should take one pass to fix.
+*/
+function readProjectTemplateV1(value) {
+	const issues = [];
+	const fail = (path, message) => issues.push({
+		path,
+		message
+	});
+	if (!isMapping(value)) return {
+		ok: false,
+		issues: [{
+			path: [],
+			message: "A template must be a mapping with 'schema' and 'blocks'."
+		}]
+	};
+	for (const key of Object.keys(value)) if (key !== "schema" && key !== "blocks") fail([], `Unrecognized key: '${key}'`);
+	if (value.schema !== "template-v1") fail(["schema"], `Expected '${PROJECT_TEMPLATE_SCHEMA_V1}', got ${describe(value.schema)}. This is the format marker every template opens with.`);
+	if (!Array.isArray(value.blocks)) {
+		fail(["blocks"], `Expected a list of entries, got ${describe(value.blocks)}.`);
+		return {
+			ok: false,
+			issues
+		};
+	}
+	const blocks = [];
+	const seen = /* @__PURE__ */ new Set();
+	value.blocks.forEach((raw, i) => {
+		const entry = readEntry(raw, ["blocks", i], fail);
+		if (entry === void 0) return;
+		if (seen.has(entry.id)) fail([
+			"blocks",
+			i,
+			"id"
+		], `Duplicate template-local id: ${entry.id}`);
+		seen.add(entry.id);
+		blocks.push(entry);
+	});
+	if (issues.length > 0) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		document: {
+			schema: PROJECT_TEMPLATE_SCHEMA_V1,
+			blocks
+		}
+	};
+}
+/**
+* One entry, or `undefined` when it is not even a mapping — in which case its own fields are
+* not reported on top, since a reader given "this entry is not a mapping" does not also need
+* to hear that its `id` is missing.
+*/
+function readEntry(raw, at, fail) {
+	if (!isMapping(raw)) {
+		fail(at, `Expected an entry mapping, got ${describe(raw)}.`);
+		return;
+	}
+	for (const key of Object.keys(raw)) if (!ENTRY_KEYS.includes(key)) fail(at, `Unrecognized key: '${key}'`);
+	let ok = true;
+	if (typeof raw.id !== "string" || raw.id.length === 0) {
+		fail([...at, "id"], `Expected a non-empty id, got ${describe(raw.id)}.`);
+		ok = false;
+	}
+	if (typeof raw.kind !== "string") {
+		fail([...at, "kind"], `Expected a kind reference, got ${describe(raw.kind)}.`);
+		ok = false;
+	} else ok = check([...at, "kind"], () => parseKindSelectorReference(raw.kind), fail) && ok;
+	if (raw.block !== void 0) if (typeof raw.block !== "string") {
+		fail([...at, "block"], `Expected a block package reference, got ${describe(raw.block)}.`);
+		ok = false;
+	} else ok = check([...at, "block"], () => parseBlockPackReference(raw.block), fail) && ok;
+	if (raw.location !== void 0) if (typeof raw.location !== "string") {
+		fail([...at, "location"], `Expected a locator URI, got ${describe(raw.location)}.`);
+		ok = false;
+	} else ok = check([...at, "location"], () => parseBlockPackLocation(raw.location), fail) && ok;
+	if (raw.block !== void 0 && raw.location !== void 0) {
+		fail([...at, "location"], "An entry cannot carry both 'block' and 'location': the first pins which version to install, the second pins where to install it from. Keep the one that is actually meant.");
+		ok = false;
+	}
+	if (raw.params !== void 0 && !isMapping(raw.params)) {
+		fail([...at, "params"], `Expected a mapping of params, got ${describe(raw.params)}.`);
+		ok = false;
+	}
+	if (!ok) return void 0;
+	return {
+		id: raw.id,
+		kind: raw.kind,
+		...raw.block !== void 0 ? { block: raw.block } : {},
+		...raw.location !== void 0 ? { location: raw.location } : {},
+		params: raw.params ?? {}
+	};
+}
+/** Run a grammar check, turning its throw into an issue at `path`. */
+function check(path, grammar, fail) {
+	try {
+		grammar();
+		return true;
+	} catch (e) {
+		fail(path, e instanceof Error ? e.message : String(e));
+		return false;
+	}
+}
+/** A value named the way an error message should name it, without printing its contents. */
+function describe(value) {
+	if (value === void 0) return "nothing";
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "a list";
+	if (typeof value === "string") return `'${value}'`;
+	if (typeof value === "object") return "a mapping";
+	return String(value);
+}
+/**
+* {@link readProjectTemplateV1} for a caller that treats an unreadable document as
+* exceptional — export, which asserts on every run that what it wrote can be read back.
+*
+* @throws {ProjectTemplateV1ParseError} carrying every problem found
+*/
+function parseProjectTemplateV1(value) {
+	const outcome = readProjectTemplateV1(value);
+	if (!outcome.ok) throw new ProjectTemplateV1ParseError(outcome.issues);
+	return outcome.document;
+}
+//#endregion
+export { PROJECT_TEMPLATE_SCHEMA_V1, ProjectTemplateV1ParseError, formatTemplateParseIssue, parseBlockPackLocation, parseBlockPackReference, parseProjectTemplateV1, readProjectTemplateV1 };
+
+//# sourceMappingURL=project_template_v1.js.map

package/dist/template/project_template_v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_template_v1.js","names":[],"sources":["../../src/template/project_template_v1.ts"],"sourcesContent":["import type { Branded } from \"@milaboratories/helpers\";\nimport { splitVersionedName } from \"../bmodel/block_kind_ref\";\nimport type { BlockKindSelectorReference } from \"./kind_selector\";\nimport { parseKindSelector, parseKindSelectorReference } from \"./kind_selector\";\n\n/**\n * Value of a template file's `schema` field — the format marker every\n * `template-v1` document opens with.\n */\nexport const PROJECT_TEMPLATE_SCHEMA_V1 = \"template-v1\";\nexport type ProjectTemplateSchemaV1 = typeof PROJECT_TEMPLATE_SCHEMA_V1;\n\n/**\n * On-wire reference to one exact block package version, `{name}@X.Y.Z`.\n *\n * The `block` override's value type. Exact only — the override exists to pin an\n * implementation, so a range would defeat it. Mapping this to the structured\n * `BlockPackId` (`{ organization, name, version }`) is import-side work; the\n * organization lives inside the npm scope here, as it does for kind names.\n */\nexport type BlockPackReference = Branded<string, \"BlockPackReference\">;\n\n/**\n * Split a {@link BlockPackReference} into `{ name, version }`.\n *\n * @throws if the reference carries no version segment or the version is not\n *   exactly `X.Y.Z`\n */\nexport function parseBlockPackReference(ref: BlockPackReference): {\n  name: string;\n  version: string;\n} {\n  const { name, version } = splitVersionedName(ref, \"block package reference\", \"{name}@X.Y.Z\");\n  const selector = parseKindSelector(version);\n  if (selector.op !== \"exact\") {\n    throw new Error(\n      `A 'block' override must pin an exact version (expected '{name}@X.Y.Z'): ${ref}`,\n    );\n  }\n  return { name, version: selector.version };\n}\n\n/**\n * On-wire locator naming WHERE one entry's block implementation comes from, as an\n * absolute URI: `file:///abs/path/to/block`.\n *\n * The third way an entry can reach an implementation, and the only one that names a\n * place rather than a name. It exists for a block that is built but not published —\n * the implementation lives in a folder and no registry knows it, so neither `kind`\n * resolution nor a `block` version pin can find it.\n *\n * A URI rather than a bare path because the question \"where\" is not limited to the\n * filesystem, and because scheme dispatch is how the rest of the toolchain already\n * answers it. Which schemes an environment can actually serve is that environment's\n * business: this type fixes only the grammar, so a document remains readable by a\n * consumer that cannot fetch every scheme.\n */\nexport type BlockPackLocationReference = Branded<string, \"BlockPackLocationReference\">;\n\n/**\n * Read the scheme off a {@link BlockPackLocationReference}, which is all the\n * document layer knows about it — resolving the rest belongs to whoever can reach\n * the scheme.\n *\n * A scheme is required. Accepting a bare path would mean reading it relative to\n * whatever directory the application happens to have been started from, which is\n * exactly the ambiguity a locator exists to remove.\n *\n * @throws if the value carries no scheme\n */\nexport function parseBlockPackLocation(ref: BlockPackLocationReference): { scheme: string } {\n  const match = LocationSchemePattern.exec(ref);\n  if (!match) {\n    throw new Error(\n      `A 'location' must be an absolute URI with a scheme (expected e.g. ` +\n        `'file:///path/to/block'), got: ${ref}`,\n    );\n  }\n  return { scheme: match.groups!.scheme.toLowerCase() };\n}\n\n/**\n * Scheme grammar, with one deliberate narrowing: a scheme is at least TWO\n * characters, while the URI grammar allows one.\n *\n * `C:\\blocks\\my-block` is a valid single-letter-scheme URI, so a Windows path\n * pasted into the field would otherwise be accepted with scheme `c` and then fail\n * far away from the mistake. Rejecting it here means the error names the actual\n * problem, and the fix — `file:///C:/blocks/my-block` — is spelled out.\n */\nconst LocationSchemePattern = /^(?<scheme>[A-Za-z][A-Za-z0-9+.-]+):/;\n\n/**\n * One block in a template file.\n *\n * `kind` is always required: it carries the params contract the entry is typed against, and\n * whichever of the three routes finds the block, what that block declares is checked against\n * it — so params written for one contract cannot reach an implementation of another.\n *\n * A file may omit `params`, which is terseness and not an escape from the contract: the parser\n * reads the omission as `{}`, so an entry that leaves it out still fails for a kind whose\n * contract has required fields. Past the parser there is only one spelling, and no reader has\n * to normalize. There is no `label` field: a template\n * does not name block instances for display.\n *\n * An entry may also carry one locator override — see {@link BlockPackLocatorOverride} for\n * what each answers. Either one is resolved on its own and kind resolution is skipped\n * entirely; carrying both would state two different things with no way to reconcile them, so\n * the type admits at most one.\n */\nexport type ProjectTemplateV1Entry = {\n  /**\n   * Template-local identifier, unique within the file. Names the entry for\n   * inter-block references; on export it is the block's project-local UUID,\n   * reused verbatim.\n   */\n  readonly id: string;\n  readonly kind: BlockKindSelectorReference;\n  /**\n   * The block's `BlockParams` instance, exactly as the block projected it — opaque here\n   * and typed by the kind. Always present: an entry whose file omitted it parses as `{}`.\n   *\n   * **Nothing here looks inside.** Not for a reference, not for a marker: values travel from\n   * the block that projected them to the block that receives them verbatim, and which of them\n   * carry block ids is recognized in the receiving block's own bundle. A document layer that\n   * recognized a reference would have to model the whole reference system to do it.\n   *\n   * That is also what lets a hand-written file spell a reference readably. A block stores\n   * `{ __isRef: true, blockId, name }` and an export writes that, but a person may write\n   * `{ block: <entry id>, name: … }` instead — see `TemplatePlRef`. Both arrive at the block as\n   * the same reference; neither is understood here.\n   */\n  readonly params: Record<string, unknown>;\n} & BlockPackLocatorOverride;\n\n/**\n * The locator override an entry may carry: a version pin, a place, or neither.\n *\n * Two arms rather than two optional fields, so \"not both\" is a property of the type and not\n * only of the parser. Each arm forbids the other's field by typing it `never`, which is what\n * makes `{ block, location }` match neither — and both arms leave their own field optional, so\n * an entry that pins nothing satisfies either.\n *\n * Readers are unaffected: every arm declares both keys, so `entry.block` and `entry.location`\n * stay directly readable without narrowing.\n */\nexport type BlockPackLocatorOverride =\n  | {\n      /**\n       * WHICH VERSION to install, leaving it to the environment to decide which registry\n       * serves it — so an entry pinned this way stays portable.\n       *\n       * Exact only, `{name}@X.Y.Z` (see {@link BlockPackReference}): the override exists to\n       * pin one implementation, and a range would defeat that. Export never writes it, because\n       * it already records the exact version the block implements, leaving a pin nothing to\n       * add — so this is a hand-written field.\n       */\n      readonly block?: BlockPackReference;\n      /** Excluded: this arm is the version pin. */\n      readonly location?: never;\n    }\n  | {\n      /** Excluded: this arm is the place. */\n      readonly block?: never;\n      /**\n       * WHICH PLACE to install from, as an absolute URI (see\n       * {@link BlockPackLocationReference}).\n       *\n       * Names a concrete, possibly unpublished implementation, and is therefore only\n       * meaningful where that place exists: a `file:` locator written on one machine says\n       * nothing on another. That is the trade it makes — it is the only answer for a block\n       * that is built but not published, which no registry can find and no kind can resolve\n       * to. Export writes it for every block installed from the filesystem, since omitting it\n       * would describe a project that cannot be recreated at all.\n       */\n      readonly location?: BlockPackLocationReference;\n    };\n\n/**\n * A `template-v1` document — the primitive form of a template.\n *\n * `blocks` order is the instantiation order, so every entry must appear after\n * the entries it references. This type is the shared contract for both\n * directions of the round trip: export emits exactly this, import parses\n * exactly this.\n *\n * Scope note: this package owns the *document*, i.e. the shape of the value a\n * YAML (or JSON) reader hands back. The text layer stays out on purpose —\n * pl-model-common is in every block-model and UI bundle and takes no `yaml`\n * dependency; serializing to YAML bytes belongs with the caller that already\n * has one (pl-middle-layer).\n */\nexport type ProjectTemplateV1 = {\n  readonly schema: ProjectTemplateSchemaV1;\n  readonly blocks: readonly ProjectTemplateV1Entry[];\n};\n\n//\n// Reading a decoded document.\n//\n// Hand-written rather than schema-driven, for what a reader of a hand-written file gets out\n// of it. A template is a file a person edits, so the parser's output is a bug report: every\n// problem at once, each located the way the file is written, worded as the edit to make. That\n// means owning the wording, which a schema library gives away — and the values here need\n// checks a schema cannot express anyway (the reference grammars are functions, and the locator\n// exclusion is a rule about two fields), so the schema was carrying the trivial half while the\n// interesting half sat in refinements beside it.\n//\n\n/** One thing wrong with a document, and where in it. */\nexport type TemplateParseIssue = {\n  /** Location in the decoded value: `[\"blocks\", 2, \"kind\"]`. */\n  readonly path: readonly (string | number)[];\n  /** What is wrong, worded for whoever is editing the file. */\n  readonly message: string;\n};\n\n/**\n * One issue as a line: `blocks[2].kind: Expected a kind reference, got nothing.`\n *\n * Indexes read as they are written in the file — `blocks[2]`, not `blocks.2` — so the place\n * can be found by reading rather than by counting.\n */\nexport function formatTemplateParseIssue(issue: TemplateParseIssue): string {\n  const path = issue.path.reduce<string>(\n    (acc, segment) =>\n      typeof segment === \"number\"\n        ? `${acc}[${segment}]`\n        : acc === \"\"\n          ? segment\n          : `${acc}.${segment}`,\n    \"\",\n  );\n  return path === \"\" ? issue.message : `${path}: ${issue.message}`;\n}\n\n/**\n * Every problem a document has, thrown once so a caller fixes the file in one pass.\n *\n * The issues are in `message` as well as on `issues`, because a throw that escapes to a log is\n * read as its message and nothing else.\n */\nexport class ProjectTemplateV1ParseError extends Error {\n  constructor(readonly issues: readonly TemplateParseIssue[]) {\n    super(\n      [\n        `The template document could not be read (${issues.length} problem(s)):`,\n        ...issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`),\n      ].join(\"\\n\"),\n    );\n    this.name = \"ProjectTemplateV1ParseError\";\n  }\n}\n\n/** A document, or everything wrong with the value that was supposed to be one. */\nexport type ProjectTemplateV1ReadResult =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly issues: readonly TemplateParseIssue[] };\n\nconst isMapping = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\n/** Keys an entry may carry. Anything else is a mistake, not an extension point. */\nconst ENTRY_KEYS = [\"id\", \"kind\", \"block\", \"location\", \"params\"] as const;\n\n/**\n * Read an already-decoded template document — the value a YAML or JSON reader returns.\n *\n * Checks the format marker, every entry's shape, the reference grammars and id uniqueness,\n * and settles an omitted `params` to `{}`. Unknown keys are refused rather than ignored: a\n * misspelled key that was silently dropped would apply a file that does not say what its\n * author meant.\n *\n * It does NOT check what an entry's params point at, and nothing downstream of it does\n * either. Which values in there carry block ids is knowable only to the block, in its own\n * bundle, where the params are relocated onto the project being built — so a reference to an\n * entry listed later, or to the entry holding it, is not refused here. It survives into the\n * applied project as a block whose references name nothing, which is how a reference to a\n * deleted block already behaves.\n *\n * Collects rather than stops: a file with three mistakes should take one pass to fix.\n */\nexport function readProjectTemplateV1(value: unknown): ProjectTemplateV1ReadResult {\n  const issues: TemplateParseIssue[] = [];\n  const fail = (path: readonly (string | number)[], message: string) =>\n    issues.push({ path, message });\n\n  if (!isMapping(value)) {\n    return {\n      ok: false,\n      issues: [{ path: [], message: \"A template must be a mapping with 'schema' and 'blocks'.\" }],\n    };\n  }\n\n  for (const key of Object.keys(value)) {\n    if (key !== \"schema\" && key !== \"blocks\") fail([], `Unrecognized key: '${key}'`);\n  }\n\n  if (value.schema !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    fail(\n      [\"schema\"],\n      `Expected '${PROJECT_TEMPLATE_SCHEMA_V1}', got ${describe(value.schema)}. This is the ` +\n        `format marker every template opens with.`,\n    );\n  }\n\n  if (!Array.isArray(value.blocks)) {\n    fail([\"blocks\"], `Expected a list of entries, got ${describe(value.blocks)}.`);\n    return { ok: false, issues };\n  }\n\n  const blocks: ProjectTemplateV1Entry[] = [];\n  const seen = new Set<string>();\n\n  value.blocks.forEach((raw, i) => {\n    const entry = readEntry(raw, [\"blocks\", i], fail);\n    if (entry === undefined) return;\n    if (seen.has(entry.id)) fail([\"blocks\", i, \"id\"], `Duplicate template-local id: ${entry.id}`);\n    seen.add(entry.id);\n    blocks.push(entry);\n  });\n\n  if (issues.length > 0) return { ok: false, issues };\n  return { ok: true, document: { schema: PROJECT_TEMPLATE_SCHEMA_V1, blocks } };\n}\n\n/**\n * One entry, or `undefined` when it is not even a mapping — in which case its own fields are\n * not reported on top, since a reader given \"this entry is not a mapping\" does not also need\n * to hear that its `id` is missing.\n */\nfunction readEntry(\n  raw: unknown,\n  at: readonly (string | number)[],\n  fail: (path: readonly (string | number)[], message: string) => void,\n): ProjectTemplateV1Entry | undefined {\n  if (!isMapping(raw)) {\n    fail(at, `Expected an entry mapping, got ${describe(raw)}.`);\n    return undefined;\n  }\n\n  for (const key of Object.keys(raw)) {\n    if (!(ENTRY_KEYS as readonly string[]).includes(key)) {\n      fail(at, `Unrecognized key: '${key}'`);\n    }\n  }\n\n  let ok = true;\n\n  if (typeof raw.id !== \"string\" || raw.id.length === 0) {\n    fail([...at, \"id\"], `Expected a non-empty id, got ${describe(raw.id)}.`);\n    ok = false;\n  }\n\n  if (typeof raw.kind !== \"string\") {\n    fail([...at, \"kind\"], `Expected a kind reference, got ${describe(raw.kind)}.`);\n    ok = false;\n  } else {\n    // The grammars are functions, and their messages already name the fix, so they are\n    // reported as they come rather than restated.\n    ok = check([...at, \"kind\"], () => parseKindSelectorReference(raw.kind as never), fail) && ok;\n  }\n\n  if (raw.block !== undefined) {\n    if (typeof raw.block !== \"string\") {\n      fail([...at, \"block\"], `Expected a block package reference, got ${describe(raw.block)}.`);\n      ok = false;\n    } else {\n      ok = check([...at, \"block\"], () => parseBlockPackReference(raw.block as never), fail) && ok;\n    }\n  }\n\n  if (raw.location !== undefined) {\n    if (typeof raw.location !== \"string\") {\n      fail([...at, \"location\"], `Expected a locator URI, got ${describe(raw.location)}.`);\n      ok = false;\n    } else {\n      ok =\n        check([...at, \"location\"], () => parseBlockPackLocation(raw.location as never), fail) && ok;\n    }\n  }\n\n  if (raw.block !== undefined && raw.location !== undefined) {\n    fail(\n      [...at, \"location\"],\n      `An entry cannot carry both 'block' and 'location': the first pins which version to ` +\n        `install, the second pins where to install it from. Keep the one that is actually meant.`,\n    );\n    ok = false;\n  }\n\n  if (raw.params !== undefined && !isMapping(raw.params)) {\n    fail([...at, \"params\"], `Expected a mapping of params, got ${describe(raw.params)}.`);\n    ok = false;\n  }\n\n  if (!ok) return undefined;\n\n  return {\n    id: raw.id as string,\n    kind: raw.kind as BlockKindSelectorReference,\n    ...(raw.block !== undefined ? { block: raw.block as BlockPackReference } : {}),\n    ...(raw.location !== undefined ? { location: raw.location as BlockPackLocationReference } : {}),\n    // Omissible in the file, settled here: every reader downstream gets a mapping.\n    params: (raw.params ?? {}) as Record<string, unknown>,\n  } as ProjectTemplateV1Entry;\n}\n\n/** Run a grammar check, turning its throw into an issue at `path`. */\nfunction check(\n  path: readonly (string | number)[],\n  grammar: () => unknown,\n  fail: (path: readonly (string | number)[], message: string) => void,\n): boolean {\n  try {\n    grammar();\n    return true;\n  } catch (e) {\n    fail(path, e instanceof Error ? e.message : String(e));\n    return false;\n  }\n}\n\n/** A value named the way an error message should name it, without printing its contents. */\nfunction describe(value: unknown): string {\n  if (value === undefined) return \"nothing\";\n  if (value === null) return \"null\";\n  if (Array.isArray(value)) return \"a list\";\n  if (typeof value === \"string\") return `'${value}'`;\n  if (typeof value === \"object\") return \"a mapping\";\n  return String(value);\n}\n\n/**\n * {@link readProjectTemplateV1} for a caller that treats an unreadable document as\n * exceptional — export, which asserts on every run that what it wrote can be read back.\n *\n * @throws {ProjectTemplateV1ParseError} carrying every problem found\n */\nexport function parseProjectTemplateV1(value: unknown): ProjectTemplateV1 {\n  const outcome = readProjectTemplateV1(value);\n  if (!outcome.ok) throw new ProjectTemplateV1ParseError(outcome.issues);\n  return outcome.document;\n}\n"],"mappings":"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"}

package/dist/template/template_ref_form.cjs

@@ -0,0 +1,73 @@
+//#region src/template/template_ref_form.ts
+/**
+* Whether `value` is a reference in the readable spelling.
+*
+* Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`
+* and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two
+* are told apart by shape and never overlap.
+*/
+function isTemplatePlRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length !== 2 || !keys.includes("block") || !keys.includes("name")) return false;
+	const { block, name } = value;
+	return typeof block === "string" && typeof name === "string";
+}
+/**
+* Expand every readable reference form in `params` into the form the system stores.
+*
+* Named for the job and not for today's only case. One readable form exists so far —
+* {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to
+* follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and
+* overridden column keys, whose long forms are far worse to type than a `PlRef`'s.
+*
+* **Adding one is a recognizer plus an expander**, checked before the generic object case, the
+* way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to
+* respect, both consequences of how the stored forms are built:
+*
+* - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an
+*   object, so the inner reference must be expanded and serialized before the outer key can be
+*   assembled. Descending after building the outer form would leave the inner spelling inside a
+*   string nothing looks at again.
+* - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled
+*   with keys in another order is a different identifier for the same column.
+*
+* What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a
+* template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},
+* which runs right after and treats an expanded reference exactly like one the file spelled out
+* in full.
+*
+* Needs nothing but the params. That is a property of the forms, not a coincidence: a readable
+* spelling carries the same information as the form it stands for, so expansion is a rewrite and
+* never a lookup. A form that needed the document to expand — a reference by position, say —
+* would have to be resolved somewhere that knows the document, and would drag that knowledge
+* into every caller of this. Keep them information-preserving.
+*/
+function expandTemplateRefs(params) {
+	const walk = (node) => {
+		if (isTemplatePlRef(node)) return expandTemplatePlRef(node);
+		if (Array.isArray(node)) return node.map(walk);
+		if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));
+		return node;
+	};
+	return walk(params);
+}
+/**
+* The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.
+*
+* An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming
+* nothing and an id naming an entry created later are indistinguishable, and both are meant to
+* arrive at a block that reports itself as missing references.
+*/
+function expandTemplatePlRef(ref) {
+	return {
+		__isRef: true,
+		blockId: ref.block,
+		name: ref.name
+	};
+}
+//#endregion
+exports.expandTemplateRefs = expandTemplateRefs;
+exports.isTemplatePlRef = isTemplatePlRef;
+
+//# sourceMappingURL=template_ref_form.cjs.map

package/dist/template/template_ref_form.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_ref_form.cjs","names":[],"sources":["../../src/template/template_ref_form.ts"],"sourcesContent":["import type { PlRef } from \"../ref\";\n\n/**\n * A reference as a person writes it: the entry it points at, and the output name.\n *\n * The readable spelling of a {@link PlRef}, and input only. The two say the same thing, and\n * differ only in what a reader has to carry:\n *\n * ```yaml\n * # what an export writes, and what a block holds\n * sources:\n *   - __isRef: true\n *     blockId: samples\n *     name: numbers\n *\n * # the same reference, written by hand\n * sources:\n *   - { block: samples, name: numbers }\n * ```\n *\n * `block` is a template-local entry id — the same thing a `PlRef`'s `blockId` holds inside a\n * template file. Nothing else: this form exists to drop the `__isRef` marker and the word\n * `blockId`, not to introduce a second way of naming an entry.\n *\n * Export never emits it — a block holds live `PlRef`s and a template holds what the block\n * holds. It is expanded on the way in, inside the block's own bundle and before the kind's\n * parser runs, so a kind's params contract is written against `PlRef` alone and never learns\n * this type exists.\n */\nexport type TemplatePlRef = {\n  /** The template-local id of the entry this points at. */\n  readonly block: string;\n  /** The upstream output's name, exactly as a `PlRef` spells it. */\n  readonly name: string;\n};\n\n/**\n * Whether `value` is a reference in the readable spelling.\n *\n * Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`\n * and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two\n * are told apart by shape and never overlap.\n */\nexport function isTemplatePlRef(value: unknown): value is TemplatePlRef {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const keys = Object.keys(value);\n  if (keys.length !== 2 || !keys.includes(\"block\") || !keys.includes(\"name\")) return false;\n  const { block, name } = value as { block: unknown; name: unknown };\n  return typeof block === \"string\" && typeof name === \"string\";\n}\n\n/**\n * Expand every readable reference form in `params` into the form the system stores.\n *\n * Named for the job and not for today's only case. One readable form exists so far —\n * {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to\n * follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and\n * overridden column keys, whose long forms are far worse to type than a `PlRef`'s.\n *\n * **Adding one is a recognizer plus an expander**, checked before the generic object case, the\n * way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to\n * respect, both consequences of how the stored forms are built:\n *\n * - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an\n *   object, so the inner reference must be expanded and serialized before the outer key can be\n *   assembled. Descending after building the outer form would leave the inner spelling inside a\n *   string nothing looks at again.\n * - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled\n *   with keys in another order is a different identifier for the same column.\n *\n * What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a\n * template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},\n * which runs right after and treats an expanded reference exactly like one the file spelled out\n * in full.\n *\n * Needs nothing but the params. That is a property of the forms, not a coincidence: a readable\n * spelling carries the same information as the form it stands for, so expansion is a rewrite and\n * never a lookup. A form that needed the document to expand — a reference by position, say —\n * would have to be resolved somewhere that knows the document, and would drag that knowledge\n * into every caller of this. Keep them information-preserving.\n */\nexport function expandTemplateRefs<T>(params: T): T {\n  const walk = (node: unknown): unknown => {\n    // One line per readable form, before the generic object case: a form IS an object, and\n    // descending into one would rewrite its parts instead of expanding it as a whole.\n    if (isTemplatePlRef(node)) return expandTemplatePlRef(node);\n\n    if (Array.isArray(node)) return node.map(walk);\n\n    if (typeof node === \"object\" && node !== null) {\n      return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));\n    }\n\n    return node;\n  };\n  return walk(params) as T;\n}\n\n/**\n * The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.\n *\n * An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming\n * nothing and an id naming an entry created later are indistinguishable, and both are meant to\n * arrive at a block that reports itself as missing references.\n */\nfunction expandTemplatePlRef(ref: TemplatePlRef): PlRef {\n  return { __isRef: true, blockId: ref.block, name: ref.name };\n}\n"],"mappings":";;;;;;;;AA2CA,SAAgB,gBAAgB,OAAwC;CACtE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG,OAAO;CAChF,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,IAAI,KAAK,WAAW,KAAK,CAAC,KAAK,SAAS,OAAO,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,OAAO;CACnF,MAAM,EAAE,OAAO,SAAS;CACxB,OAAO,OAAO,UAAU,YAAY,OAAO,SAAS;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,mBAAsB,QAAc;CAClD,MAAM,QAAQ,SAA2B;EAGvC,IAAI,gBAAgB,IAAI,GAAG,OAAO,oBAAoB,IAAI;EAE1D,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAK,IAAI,IAAI;EAE7C,IAAI,OAAO,SAAS,YAAY,SAAS,MACvC,OAAO,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;EAG9E,OAAO;CACT;CACA,OAAO,KAAK,MAAM;AACpB;;;;;;;;AASA,SAAS,oBAAoB,KAA2B;CACtD,OAAO;EAAE,SAAS;EAAM,SAAS,IAAI;EAAO,MAAM,IAAI;CAAK;AAC7D"}

package/dist/template/template_ref_form.d.ts

@@ -0,0 +1,75 @@
+//#region src/template/template_ref_form.d.ts
+/**
+ * A reference as a person writes it: the entry it points at, and the output name.
+ *
+ * The readable spelling of a {@link PlRef}, and input only. The two say the same thing, and
+ * differ only in what a reader has to carry:
+ *
+ * ```yaml
+ * # what an export writes, and what a block holds
+ * sources:
+ *   - __isRef: true
+ *     blockId: samples
+ *     name: numbers
+ *
+ * # the same reference, written by hand
+ * sources:
+ *   - { block: samples, name: numbers }
+ * ```
+ *
+ * `block` is a template-local entry id — the same thing a `PlRef`'s `blockId` holds inside a
+ * template file. Nothing else: this form exists to drop the `__isRef` marker and the word
+ * `blockId`, not to introduce a second way of naming an entry.
+ *
+ * Export never emits it — a block holds live `PlRef`s and a template holds what the block
+ * holds. It is expanded on the way in, inside the block's own bundle and before the kind's
+ * parser runs, so a kind's params contract is written against `PlRef` alone and never learns
+ * this type exists.
+ */
+export type TemplatePlRef = {
+  /** The template-local id of the entry this points at. */
+  readonly block: string;
+  /** The upstream output's name, exactly as a `PlRef` spells it. */
+  readonly name: string;
+};
+/**
+ * Whether `value` is a reference in the readable spelling.
+ *
+ * Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`
+ * and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two
+ * are told apart by shape and never overlap.
+ */
+export declare function isTemplatePlRef(value: unknown): value is TemplatePlRef;
+/**
+ * Expand every readable reference form in `params` into the form the system stores.
+ *
+ * Named for the job and not for today's only case. One readable form exists so far —
+ * {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to
+ * follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and
+ * overridden column keys, whose long forms are far worse to type than a `PlRef`'s.
+ *
+ * **Adding one is a recognizer plus an expander**, checked before the generic object case, the
+ * way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to
+ * respect, both consequences of how the stored forms are built:
+ *
+ * - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an
+ *   object, so the inner reference must be expanded and serialized before the outer key can be
+ *   assembled. Descending after building the outer form would leave the inner spelling inside a
+ *   string nothing looks at again.
+ * - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled
+ *   with keys in another order is a different identifier for the same column.
+ *
+ * What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a
+ * template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},
+ * which runs right after and treats an expanded reference exactly like one the file spelled out
+ * in full.
+ *
+ * Needs nothing but the params. That is a property of the forms, not a coincidence: a readable
+ * spelling carries the same information as the form it stands for, so expansion is a rewrite and
+ * never a lookup. A form that needed the document to expand — a reference by position, say —
+ * would have to be resolved somewhere that knows the document, and would drag that knowledge
+ * into every caller of this. Keep them information-preserving.
+ */
+export declare function expandTemplateRefs<T>(params: T): T;
+//#endregion
+//# sourceMappingURL=template_ref_form.d.ts.map

package/dist/template/template_ref_form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_ref_form.d.ts","names":[],"sources":["../../src/template/template_ref_form.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;YA6BY;;WAED;;WAEA;;;;;;;;;wBAUK,gBAAgB,iBAAiB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAsC1C,mBAAmB,GAAG,QAAQ,IAAI"}

package/dist/template/template_ref_form.js

@@ -0,0 +1,72 @@
+//#region src/template/template_ref_form.ts
+/**
+* Whether `value` is a reference in the readable spelling.
+*
+* Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`
+* and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two
+* are told apart by shape and never overlap.
+*/
+function isTemplatePlRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length !== 2 || !keys.includes("block") || !keys.includes("name")) return false;
+	const { block, name } = value;
+	return typeof block === "string" && typeof name === "string";
+}
+/**
+* Expand every readable reference form in `params` into the form the system stores.
+*
+* Named for the job and not for today's only case. One readable form exists so far —
+* {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to
+* follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and
+* overridden column keys, whose long forms are far worse to type than a `PlRef`'s.
+*
+* **Adding one is a recognizer plus an expander**, checked before the generic object case, the
+* way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to
+* respect, both consequences of how the stored forms are built:
+*
+* - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an
+*   object, so the inner reference must be expanded and serialized before the outer key can be
+*   assembled. Descending after building the outer form would leave the inner spelling inside a
+*   string nothing looks at again.
+* - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled
+*   with keys in another order is a different identifier for the same column.
+*
+* What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a
+* template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},
+* which runs right after and treats an expanded reference exactly like one the file spelled out
+* in full.
+*
+* Needs nothing but the params. That is a property of the forms, not a coincidence: a readable
+* spelling carries the same information as the form it stands for, so expansion is a rewrite and
+* never a lookup. A form that needed the document to expand — a reference by position, say —
+* would have to be resolved somewhere that knows the document, and would drag that knowledge
+* into every caller of this. Keep them information-preserving.
+*/
+function expandTemplateRefs(params) {
+	const walk = (node) => {
+		if (isTemplatePlRef(node)) return expandTemplatePlRef(node);
+		if (Array.isArray(node)) return node.map(walk);
+		if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));
+		return node;
+	};
+	return walk(params);
+}
+/**
+* The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.
+*
+* An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming
+* nothing and an id naming an entry created later are indistinguishable, and both are meant to
+* arrive at a block that reports itself as missing references.
+*/
+function expandTemplatePlRef(ref) {
+	return {
+		__isRef: true,
+		blockId: ref.block,
+		name: ref.name
+	};
+}
+//#endregion
+export { expandTemplateRefs, isTemplatePlRef };
+
+//# sourceMappingURL=template_ref_form.js.map

package/dist/template/template_ref_form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_ref_form.js","names":[],"sources":["../../src/template/template_ref_form.ts"],"sourcesContent":["import type { PlRef } from \"../ref\";\n\n/**\n * A reference as a person writes it: the entry it points at, and the output name.\n *\n * The readable spelling of a {@link PlRef}, and input only. The two say the same thing, and\n * differ only in what a reader has to carry:\n *\n * ```yaml\n * # what an export writes, and what a block holds\n * sources:\n *   - __isRef: true\n *     blockId: samples\n *     name: numbers\n *\n * # the same reference, written by hand\n * sources:\n *   - { block: samples, name: numbers }\n * ```\n *\n * `block` is a template-local entry id — the same thing a `PlRef`'s `blockId` holds inside a\n * template file. Nothing else: this form exists to drop the `__isRef` marker and the word\n * `blockId`, not to introduce a second way of naming an entry.\n *\n * Export never emits it — a block holds live `PlRef`s and a template holds what the block\n * holds. It is expanded on the way in, inside the block's own bundle and before the kind's\n * parser runs, so a kind's params contract is written against `PlRef` alone and never learns\n * this type exists.\n */\nexport type TemplatePlRef = {\n  /** The template-local id of the entry this points at. */\n  readonly block: string;\n  /** The upstream output's name, exactly as a `PlRef` spells it. */\n  readonly name: string;\n};\n\n/**\n * Whether `value` is a reference in the readable spelling.\n *\n * Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`\n * and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two\n * are told apart by shape and never overlap.\n */\nexport function isTemplatePlRef(value: unknown): value is TemplatePlRef {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const keys = Object.keys(value);\n  if (keys.length !== 2 || !keys.includes(\"block\") || !keys.includes(\"name\")) return false;\n  const { block, name } = value as { block: unknown; name: unknown };\n  return typeof block === \"string\" && typeof name === \"string\";\n}\n\n/**\n * Expand every readable reference form in `params` into the form the system stores.\n *\n * Named for the job and not for today's only case. One readable form exists so far —\n * {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to\n * follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and\n * overridden column keys, whose long forms are far worse to type than a `PlRef`'s.\n *\n * **Adding one is a recognizer plus an expander**, checked before the generic object case, the\n * way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to\n * respect, both consequences of how the stored forms are built:\n *\n * - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an\n *   object, so the inner reference must be expanded and serialized before the outer key can be\n *   assembled. Descending after building the outer form would leave the inner spelling inside a\n *   string nothing looks at again.\n * - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled\n *   with keys in another order is a different identifier for the same column.\n *\n * What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a\n * template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},\n * which runs right after and treats an expanded reference exactly like one the file spelled out\n * in full.\n *\n * Needs nothing but the params. That is a property of the forms, not a coincidence: a readable\n * spelling carries the same information as the form it stands for, so expansion is a rewrite and\n * never a lookup. A form that needed the document to expand — a reference by position, say —\n * would have to be resolved somewhere that knows the document, and would drag that knowledge\n * into every caller of this. Keep them information-preserving.\n */\nexport function expandTemplateRefs<T>(params: T): T {\n  const walk = (node: unknown): unknown => {\n    // One line per readable form, before the generic object case: a form IS an object, and\n    // descending into one would rewrite its parts instead of expanding it as a whole.\n    if (isTemplatePlRef(node)) return expandTemplatePlRef(node);\n\n    if (Array.isArray(node)) return node.map(walk);\n\n    if (typeof node === \"object\" && node !== null) {\n      return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));\n    }\n\n    return node;\n  };\n  return walk(params) as T;\n}\n\n/**\n * The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.\n *\n * An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming\n * nothing and an id naming an entry created later are indistinguishable, and both are meant to\n * arrive at a block that reports itself as missing references.\n */\nfunction expandTemplatePlRef(ref: TemplatePlRef): PlRef {\n  return { __isRef: true, blockId: ref.block, name: ref.name };\n}\n"],"mappings":";;;;;;;;AA2CA,SAAgB,gBAAgB,OAAwC;CACtE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG,OAAO;CAChF,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,IAAI,KAAK,WAAW,KAAK,CAAC,KAAK,SAAS,OAAO,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,OAAO;CACnF,MAAM,EAAE,OAAO,SAAS;CACxB,OAAO,OAAO,UAAU,YAAY,OAAO,SAAS;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,mBAAsB,QAAc;CAClD,MAAM,QAAQ,SAA2B;EAGvC,IAAI,gBAAgB,IAAI,GAAG,OAAO,oBAAoB,IAAI;EAE1D,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAK,IAAI,IAAI;EAE7C,IAAI,OAAO,SAAS,YAAY,SAAS,MACvC,OAAO,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;EAG9E,OAAO;CACT;CACA,OAAO,KAAK,MAAM;AACpB;;;;;;;;AASA,SAAS,oBAAoB,KAA2B;CACtD,OAAO;EAAE,SAAS;EAAM,SAAS,IAAI;EAAO,MAAM,IAAI;CAAK;AAC7D"}

package/dist/template/template_relocate.cjs

@@ -0,0 +1,67 @@
+const require_spec = require("../drivers/pframe/spec/spec.cjs");
+const require_ids = require("../drivers/pframe/spec/ids.cjs");
+require("../drivers/index.cjs");
+let es_toolkit = require("es-toolkit");
+//#region src/template/template_relocate.ts
+/**
+* Point every column identifier in a block's params at the blocks of the project being built.
+*
+* The whole of what a template does about references, and it lives here — in the package the
+* block's own bundle imports — because knowing which values carry block ids is knowing the
+* reference system. The engine carrying the params neither marks them, reads them, nor
+* rewrites them: it hands the block its params and this map, and takes back what comes out.
+*
+* Params travel verbatim precisely so that this is possible. A file holds a `PlRef` as the
+* object the block stored and a column id as the canonical string the block stored, with no
+* marker of any kind, and the identifiers are found here by recognizing them — the same way
+* the project's own dependency detector finds them in live args.
+*
+* Rewriting is structural, never textual: an identifier is taken apart, its `blockId` fields
+* are replaced, and it is rebuilt canonically. That is what keeps a value that merely *looks*
+* like an id — an axis filter, a domain this package can see belongs to an identifier it
+* knows — from being rewritten along with it, and what re-sorts a qualifications map whose
+* keys are identifiers.
+*
+* A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is
+* qualified by the block that produced it. Only the domain keys known to name a block are
+* repointed — matching an entry id is not on its own evidence of a reference.
+*
+* An id the map does not mention is left as it is. That is the ordering rule doing its work:
+* a caller building the map as it creates blocks passes only the entries already created, so
+* a reference to an entry further down the file stays pointing at a block that does not
+* exist, and the applied block reports itself as missing references rather than being wired
+* to something below it.
+*
+* @param params Whatever the block projected, as the document stored it
+* @param blockIds template-local entry id → the block id that entry was given
+*/
+function relocateBlockIds(params, blockIds) {
+	if (blockIds.size === 0) return params;
+	const remapBlockId = (blockId) => blockIds.get(blockId) ?? blockId;
+	const walk = (node) => {
+		if (typeof node === "string") return require_ids.remapColumnIdBlockIds(node, remapBlockId);
+		if (require_ids.isColumnUniversalKey(node)) return require_ids.remapColumnIdBlockIds(node, remapBlockId);
+		if (Array.isArray(node)) return node.map(walk);
+		if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([key, value]) => [require_ids.remapColumnIdBlockIds(key, remapBlockId), key === "domain" && (0, es_toolkit.isPlainObject)(value) ? relocateDomain(value) : walk(value)]));
+		return node;
+	};
+	/**
+	* The block-naming entries of a domain, repointed at the project being built: an axis a block
+	* produced names that block in its domain, so those are references like any other.
+	*
+	* Only the keys {@link BlockScopedDomain} lists, because a template's entry ids are arbitrary
+	* non-empty strings — a hand-written template may name an entry `closest`, and a qualifier
+	* reading `closest` is not a reference to it. Matching the map is not on its own enough to
+	* tell one from the other; the key is.
+	*
+	* Reached only from the generic object case — inside an identifier this package recognizes a
+	* domain is spec data and stays as it is, which is what keeps an overridden column's
+	* `specOverrides.domain` untouched.
+	*/
+	const relocateDomain = (domain) => Object.fromEntries(Object.entries(domain).map(([key, value]) => [key, typeof value === "string" && require_spec.BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value)]));
+	return walk(params);
+}
+//#endregion
+exports.relocateBlockIds = relocateBlockIds;
+
+//# sourceMappingURL=template_relocate.cjs.map

package/dist/template/template_relocate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_relocate.cjs","names":["remapColumnIdBlockIds","isColumnUniversalKey","BlockScopedDomain"],"sources":["../../src/template/template_relocate.ts"],"sourcesContent":["import { isPlainObject } from \"es-toolkit\";\n\nimport { BlockScopedDomain, isColumnUniversalKey, remapColumnIdBlockIds } from \"../drivers\";\n\n/**\n * Point every column identifier in a block's params at the blocks of the project being built.\n *\n * The whole of what a template does about references, and it lives here — in the package the\n * block's own bundle imports — because knowing which values carry block ids is knowing the\n * reference system. The engine carrying the params neither marks them, reads them, nor\n * rewrites them: it hands the block its params and this map, and takes back what comes out.\n *\n * Params travel verbatim precisely so that this is possible. A file holds a `PlRef` as the\n * object the block stored and a column id as the canonical string the block stored, with no\n * marker of any kind, and the identifiers are found here by recognizing them — the same way\n * the project's own dependency detector finds them in live args.\n *\n * Rewriting is structural, never textual: an identifier is taken apart, its `blockId` fields\n * are replaced, and it is rebuilt canonically. That is what keeps a value that merely *looks*\n * like an id — an axis filter, a domain this package can see belongs to an identifier it\n * knows — from being rewritten along with it, and what re-sorts a qualifications map whose\n * keys are identifiers.\n *\n * A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is\n * qualified by the block that produced it. Only the domain keys known to name a block are\n * repointed — matching an entry id is not on its own evidence of a reference.\n *\n * An id the map does not mention is left as it is. That is the ordering rule doing its work:\n * a caller building the map as it creates blocks passes only the entries already created, so\n * a reference to an entry further down the file stays pointing at a block that does not\n * exist, and the applied block reports itself as missing references rather than being wired\n * to something below it.\n *\n * @param params Whatever the block projected, as the document stored it\n * @param blockIds template-local entry id → the block id that entry was given\n */\nexport function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, string>): T {\n  if (blockIds.size === 0) return params;\n  const remapBlockId = (blockId: string) => blockIds.get(blockId) ?? blockId;\n\n  const walk = (node: unknown): unknown => {\n    // Any string may be an identifier under any amount of escaping; one that is not comes\n    // back as the very same string, so this needs no test of its own here.\n    if (typeof node === \"string\") return remapColumnIdBlockIds(node, remapBlockId);\n\n    // Before the generic object case: an identifier IS an object, and descending into one\n    // would rewrite the strings nested in it piecemeal instead of rebuilding the whole id —\n    // losing the bottom-up canonicalization that keeps the result a valid identifier.\n    if (isColumnUniversalKey(node)) return remapColumnIdBlockIds(node, remapBlockId);\n\n    if (Array.isArray(node)) return node.map(walk);\n\n    if (typeof node === \"object\" && node !== null) {\n      // Keys as well as values: params may be keyed by column id — per-column settings, say\n      // — and a key is exactly as much of a reference as a value is.\n      return Object.fromEntries(\n        Object.entries(node).map(([key, value]) => [\n          remapColumnIdBlockIds(key, remapBlockId),\n          key === \"domain\" && isPlainObject(value) ? relocateDomain(value) : walk(value),\n        ]),\n      );\n    }\n\n    return node;\n  };\n\n  /**\n   * The block-naming entries of a domain, repointed at the project being built: an axis a block\n   * produced names that block in its domain, so those are references like any other.\n   *\n   * Only the keys {@link BlockScopedDomain} lists, because a template's entry ids are arbitrary\n   * non-empty strings — a hand-written template may name an entry `closest`, and a qualifier\n   * reading `closest` is not a reference to it. Matching the map is not on its own enough to\n   * tell one from the other; the key is.\n   *\n   * Reached only from the generic object case — inside an identifier this package recognizes a\n   * domain is spec data and stays as it is, which is what keeps an overridden column's\n   * `specOverrides.domain` untouched.\n   */\n  const relocateDomain = (domain: Record<string, unknown>): Record<string, unknown> =>\n    Object.fromEntries(\n      Object.entries(domain).map(([key, value]) => [\n        key,\n        typeof value === \"string\" && BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value),\n      ]),\n    );\n\n  return walk(params) as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,iBAAoB,QAAW,UAA0C;CACvF,IAAI,SAAS,SAAS,GAAG,OAAO;CAChC,MAAM,gBAAgB,YAAoB,SAAS,IAAI,OAAO,KAAK;CAEnE,MAAM,QAAQ,SAA2B;EAGvC,IAAI,OAAO,SAAS,UAAU,OAAOA,YAAAA,sBAAsB,MAAM,YAAY;EAK7E,IAAIC,YAAAA,qBAAqB,IAAI,GAAG,OAAOD,YAAAA,sBAAsB,MAAM,YAAY;EAE/E,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAK,IAAI,IAAI;EAE7C,IAAI,OAAO,SAAS,YAAY,SAAS,MAGvC,OAAO,OAAO,YACZ,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACzCA,YAAAA,sBAAsB,KAAK,YAAY,GACvC,QAAQ,aAAA,GAAA,WAAA,cAAA,CAA0B,KAAK,IAAI,eAAe,KAAK,IAAI,KAAK,KAAK,CAC/E,CAAC,CACH;EAGF,OAAO;CACT;;;;;;;;;;;;;;CAeA,MAAM,kBAAkB,WACtB,OAAO,YACL,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAC3C,KACA,OAAO,UAAU,YAAYE,aAAAA,kBAAkB,IAAI,GAAG,IAAI,aAAa,KAAK,IAAI,KAAK,KAAK,CAC5F,CAAC,CACH;CAEF,OAAO,KAAK,MAAM;AACpB"}