@milaboratories/pl-model-common 1.47.2 → 1.48.0

package/dist/template/project_template_v1.d.ts

@@ -0,0 +1,215 @@
+import { BlockKindSelectorReference } from "./kind_selector.js";
+import { Branded } from "@milaboratories/helpers";
+
+//#region src/template/project_template_v1.d.ts
+/**
+ * Value of a template file's `schema` field — the format marker every
+ * `template-v1` document opens with.
+ */
+declare const PROJECT_TEMPLATE_SCHEMA_V1 = "template-v1";
+type ProjectTemplateSchemaV1 = typeof PROJECT_TEMPLATE_SCHEMA_V1;
+/**
+ * On-wire reference to one exact block package version, `{name}@X.Y.Z`.
+ *
+ * The `block` override's value type. Exact only — the override exists to pin an
+ * implementation, so a range would defeat it. Mapping this to the structured
+ * `BlockPackId` (`{ organization, name, version }`) is import-side work; the
+ * organization lives inside the npm scope here, as it does for kind names.
+ */
+type BlockPackReference = Branded<string, "BlockPackReference">;
+/**
+ * Split a {@link BlockPackReference} into `{ name, version }`.
+ *
+ * @throws if the reference carries no version segment or the version is not
+ *   exactly `X.Y.Z`
+ */
+declare function parseBlockPackReference(ref: BlockPackReference): {
+  name: string;
+  version: string;
+};
+/**
+ * On-wire locator naming WHERE one entry's block implementation comes from, as an
+ * absolute URI: `file:///abs/path/to/block`.
+ *
+ * The third way an entry can reach an implementation, and the only one that names a
+ * place rather than a name. It exists for a block that is built but not published —
+ * the implementation lives in a folder and no registry knows it, so neither `kind`
+ * resolution nor a `block` version pin can find it.
+ *
+ * A URI rather than a bare path because the question "where" is not limited to the
+ * filesystem, and because scheme dispatch is how the rest of the toolchain already
+ * answers it. Which schemes an environment can actually serve is that environment's
+ * business: this type fixes only the grammar, so a document remains readable by a
+ * consumer that cannot fetch every scheme.
+ */
+type BlockPackLocationReference = Branded<string, "BlockPackLocationReference">;
+/**
+ * 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
+ */
+declare function parseBlockPackLocation(ref: BlockPackLocationReference): {
+  scheme: string;
+};
+/**
+ * One block in a template file.
+ *
+ * `kind` is always required: it carries the params contract the entry is typed against, and
+ * whichever of the three routes finds the block, what that block declares is checked against
+ * it — so params written for one contract cannot reach an implementation of another.
+ *
+ * A file may omit `params`, which is terseness and not an escape from the contract: the parser
+ * reads the omission as `{}`, so an entry that leaves it out still fails for a kind whose
+ * contract has required fields. Past the parser there is only one spelling, and no reader has
+ * to normalize. There is no `label` field: a template
+ * does not name block instances for display.
+ *
+ * An entry may also carry one locator override — see {@link BlockPackLocatorOverride} for
+ * what each answers. Either one is resolved on its own and kind resolution is skipped
+ * entirely; carrying both would state two different things with no way to reconcile them, so
+ * the type admits at most one.
+ */
+type ProjectTemplateV1Entry = {
+  /**
+   * Template-local identifier, unique within the file. Names the entry for
+   * inter-block references; on export it is the block's project-local UUID,
+   * reused verbatim.
+   */
+  readonly id: string;
+  readonly kind: BlockKindSelectorReference;
+  /**
+   * The block's `BlockParams` instance, exactly as the block projected it — opaque here
+   * and typed by the kind. Always present: an entry whose file omitted it parses as `{}`.
+   *
+   * **Nothing here looks inside.** Not for a reference, not for a marker: values travel from
+   * the block that projected them to the block that receives them verbatim, and which of them
+   * carry block ids is recognized in the receiving block's own bundle. A document layer that
+   * recognized a reference would have to model the whole reference system to do it.
+   *
+   * That is also what lets a hand-written file spell a reference readably. A block stores
+   * `{ __isRef: true, blockId, name }` and an export writes that, but a person may write
+   * `{ block: <entry id>, name: … }` instead — see `TemplatePlRef`. Both arrive at the block as
+   * the same reference; neither is understood here.
+   */
+  readonly params: Record<string, unknown>;
+} & BlockPackLocatorOverride;
+/**
+ * The locator override an entry may carry: a version pin, a place, or neither.
+ *
+ * Two arms rather than two optional fields, so "not both" is a property of the type and not
+ * only of the parser. Each arm forbids the other's field by typing it `never`, which is what
+ * makes `{ block, location }` match neither — and both arms leave their own field optional, so
+ * an entry that pins nothing satisfies either.
+ *
+ * Readers are unaffected: every arm declares both keys, so `entry.block` and `entry.location`
+ * stay directly readable without narrowing.
+ */
+type BlockPackLocatorOverride = {
+  /**
+   * WHICH VERSION to install, leaving it to the environment to decide which registry
+   * serves it — so an entry pinned this way stays portable.
+   *
+   * Exact only, `{name}@X.Y.Z` (see {@link BlockPackReference}): the override exists to
+   * pin one implementation, and a range would defeat that. Export never writes it, because
+   * it already records the exact version the block implements, leaving a pin nothing to
+   * add — so this is a hand-written field.
+   */
+  readonly block?: BlockPackReference; /** Excluded: this arm is the version pin. */
+  readonly location?: never;
+} | {
+  /** Excluded: this arm is the place. */readonly block?: never;
+  /**
+   * WHICH PLACE to install from, as an absolute URI (see
+   * {@link BlockPackLocationReference}).
+   *
+   * Names a concrete, possibly unpublished implementation, and is therefore only
+   * meaningful where that place exists: a `file:` locator written on one machine says
+   * nothing on another. That is the trade it makes — it is the only answer for a block
+   * that is built but not published, which no registry can find and no kind can resolve
+   * to. Export writes it for every block installed from the filesystem, since omitting it
+   * would describe a project that cannot be recreated at all.
+   */
+  readonly location?: BlockPackLocationReference;
+};
+/**
+ * A `template-v1` document — the primitive form of a template.
+ *
+ * `blocks` order is the instantiation order, so every entry must appear after
+ * the entries it references. This type is the shared contract for both
+ * directions of the round trip: export emits exactly this, import parses
+ * exactly this.
+ *
+ * Scope note: this package owns the *document*, i.e. the shape of the value a
+ * YAML (or JSON) reader hands back. The text layer stays out on purpose —
+ * pl-model-common is in every block-model and UI bundle and takes no `yaml`
+ * dependency; serializing to YAML bytes belongs with the caller that already
+ * has one (pl-middle-layer).
+ */
+type ProjectTemplateV1 = {
+  readonly schema: ProjectTemplateSchemaV1;
+  readonly blocks: readonly ProjectTemplateV1Entry[];
+};
+/** One thing wrong with a document, and where in it. */
+type TemplateParseIssue = {
+  /** Location in the decoded value: `["blocks", 2, "kind"]`. */readonly path: readonly (string | number)[]; /** What is wrong, worded for whoever is editing the file. */
+  readonly message: string;
+};
+/**
+ * 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.
+ */
+declare function formatTemplateParseIssue(issue: TemplateParseIssue): string;
+/**
+ * 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.
+ */
+declare class ProjectTemplateV1ParseError extends Error {
+  readonly issues: readonly TemplateParseIssue[];
+  constructor(issues: readonly TemplateParseIssue[]);
+}
+/** A document, or everything wrong with the value that was supposed to be one. */
+type ProjectTemplateV1ReadResult = {
+  readonly ok: true;
+  readonly document: ProjectTemplateV1;
+} | {
+  readonly ok: false;
+  readonly issues: readonly TemplateParseIssue[];
+};
+/**
+ * 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.
+ */
+declare function readProjectTemplateV1(value: unknown): ProjectTemplateV1ReadResult;
+/**
+ * {@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
+ */
+declare function parseProjectTemplateV1(value: unknown): ProjectTemplateV1;
+//#endregion
+export { BlockPackLocationReference, BlockPackLocatorOverride, BlockPackReference, PROJECT_TEMPLATE_SCHEMA_V1, ProjectTemplateSchemaV1, ProjectTemplateV1, ProjectTemplateV1Entry, ProjectTemplateV1ParseError, ProjectTemplateV1ReadResult, TemplateParseIssue, formatTemplateParseIssue, parseBlockPackLocation, parseBlockPackReference, parseProjectTemplateV1, readProjectTemplateV1 };
+//# sourceMappingURL=project_template_v1.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project_template_v1.d.ts","names":[],"sources":["../../src/template/project_template_v1.ts"],"mappings":";;;;;;AASA;;cAAa,0BAAA;AAAA,KACD,uBAAA,UAAiC,0BAA0B;AADhC;AACvC;;;;AAAuE;AAUvE;;AAXuC,KAW3B,kBAAA,GAAqB,OAAO;;AAAA;AAQxC;;;;iBAAgB,uBAAA,CAAwB,GAAA,EAAK,kBAAkB;EAC7D,IAAA;EACA,OAAA;AAAA;;AAAO;AA2BT;;;;AAAgD;AAahD;;;;;;;;KAbY,0BAAA,GAA6B,OAAO;AAqDhD;;;;;;;;;;;AAAA,iBAxCgB,sBAAA,CAAuB,GAAA,EAAK,0BAA0B;EAAK,MAAA;AAAA;;AA+D/C;AAa5B;;;;;;;;;;;AA6BoD;AAiBpD;;;;KAlFY,sBAAA;EAmFO;;;;AAC+B;EAD/B,SA7ER,EAAA;EAAA,SACA,IAAA,EAAM,0BAAA;;;AAiGC;AASlB;;;;AAAkE;AAmBlE;;;;;;WA9GW,MAAA,EAAQ,MAAA;AAAA,IACf,wBAAA;;;;;;;;AA8GwD;AAY5D;;;KA7GY,wBAAA;EA8GG;;;;;;;AACuD;AAyBtE;EA1Be,SAnGA,KAAA,GAAQ,kBAAA;WAER,QAAA;AAAA;EAwRC,gDApRD,KAAA;;;AAoR0D;;;;;;;;;WAxQ1D,QAAA,GAAW,0BAA0B;AAAA;;;;;;;;;;;;;;;KAiBxC,iBAAA;EAAA,SACD,MAAA,EAAQ,uBAAA;EAAA,SACR,MAAA,WAAiB,sBAAsB;AAAA;;KAgBtC,kBAAA;yEAED,IAAA;WAEA,OAAO;AAAA;;;;;;;iBASF,wBAAA,CAAyB,KAAyB,EAAlB,kBAAkB;;;;;;;cAmBrD,2BAAA,SAAoC,KAAA;EAAA,SAC1B,MAAA,WAAiB,kBAAA;cAAjB,MAAA,WAAiB,kBAAA;AAAA;;KAY5B,2BAAA;EAAA,SACG,EAAA;EAAA,SAAmB,QAAA,EAAU,iBAAA;AAAA;EAAA,SAC7B,EAAA;EAAA,SAAoB,MAAA,WAAiB,kBAAkB;AAAA;;;;;;;;;;;;;;;;;;iBAyBtD,qBAAA,CAAsB,KAAA,YAAiB,2BAA2B;;;;;;;iBA6JlE,sBAAA,CAAuB,KAAA,YAAiB,iBAAiB"}

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,74 @@
+//#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.
+ */
+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.
+ */
+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.
+ */
+declare function expandTemplateRefs<T>(params: T): T;
+//#endregion
+export { TemplatePlRef, expandTemplateRefs, isTemplatePlRef };
+//# sourceMappingURL=template_ref_form.d.ts.map