@milaboratories/pl-model-common 1.46.4 → 1.47.0

package/dist/drivers/pframe/spec/discovered_column.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovered_column.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/discovered_column.ts"],"mappings":";;;;;KAKY,iBAAA;EACV,MAAA,EAAQ,SAAA;EACR,IAAA,GAAO,QAAA;EACP,oBAAA,GAAuB,iBAAA;EACvB,qBAAA,GAAwB,MAAA,CAAO,SAAA,EAAW,iBAAA;AAAA;AAAA,KAGhC,mBAAA,GAAsB,OAAO,CAAC,SAAA;AAAA,KAErC,QAAA;EACH,IAAA;EACA,MAAA,EAAQ,SAAS;AAAA;AAAA,iBAGH,mBAAA,CAAoB,GAAA,YAAe,GAAA,IAAO,iBAAiB;AAAA,iBAW3D,wBAAA,CAAyB,KAAA,EAAO,iBAAA,GAAoB,iBAAiB;AAAA,iBAerE,yBAAA,CAA0B,KAAA;EACxC,MAAA,EAAQ,SAAA;EACR,IAAA,GAAO,QAAA;EACP,oBAAA,GAAuB,iBAAA;EACvB,qBAAA,GAAwB,MAAA,CAAO,SAAA,EAAW,iBAAA;AAAA,IACxC,mBAAA;AAAA,iBAIY,wBAAA,CAAyB,EAAA,EAAI,mBAAA,GAAsB,iBAAiB;AAAA,iBAapE,4BAAA,CAA6B,EAAA,EAAI,iBAAA,GAGhC,mBAAmB"}
+{"version":3,"file":"discovered_column.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/discovered_column.ts"],"mappings":";;;;;;;UAMiB,mBAAA;EACf,cAAA;EACA,MAAA,EAAQ,iBAAA;EACR,IAAA,GAAO,QAAA;EACP,oBAAA,GAAuB,iBAAA;EACvB,qBAAA,GAAwB,MAAA,CAAO,SAAA,EAAW,iBAAA;AAAA;AAAA,KAGhC,kBAAA,GAAqB,OAAA,CAC/B,iBAAA,CAAkB,mBAAA;AAAA,KAIf,QAAA;EACH,IAAA;EACA,MAAA,EAAQ,iBAAiB;AAAA;AAAA,iBAGX,qBAAA,CAAsB,GAAA,YAAe,GAAA,IAAO,mBAAmB;AAAA,iBAI/D,oBAAA,CAAqB,GAAA,YAAe,GAAA,IAAO,kBAAkB;AAAA,iBAK7D,0BAAA,CAA2B,KAAA,EAAO,mBAAA,GAAsB,mBAAmB;AAAA,iBAgB3E,wBAAA,CAAyB,KAAA;EACvC,MAAA,EAAQ,iBAAA;EACR,IAAA,GAAO,QAAA;EACP,oBAAA,GAAuB,iBAAA;EACvB,qBAAA,GAAwB,MAAA,CAAO,SAAA,EAAW,iBAAA;AAAA,IACxC,kBAAA;AAAA,iBAIY,yBAAA,CAA0B,KAAA;EACxC,MAAA,EAAQ,iBAAA;EACR,IAAA,GAAO,QAAA;EACP,oBAAA,GAAuB,iBAAA;EACvB,qBAAA,GAAwB,MAAA,CAAO,SAAA,EAAW,iBAAA;AAAA,IACxC,mBAAA;AAAA,iBAIY,uBAAA,CAAwB,EAAA,EAAI,kBAAA,GAAqB,mBAAmB;AAAA,iBAapE,2BAAA,CACd,EAAA,EAAI,IAAA,CAAK,mBAAA,sBACR,kBAAA"}

package/dist/drivers/pframe/spec/discovered_column.js

@@ -1,32 +1,46 @@
-import { canonicalizeJson } from "../../../json.js";
+import { canonicalizeJson, parseJsonSafely } from "../../../json.js";
 import { throwError } from "@milaboratories/helpers";
 //#region src/drivers/pframe/spec/discovered_column.ts
-function isDiscoveredPColumn(obj) {
-	return typeof obj === "object" && obj !== null && "path" in obj && "column" in obj && "columnQualifications" in obj && "queriesQualifications" in obj;
+function isColumnDiscoveredKey(obj) {
+	return typeof obj === "object" && obj !== null && "__isDiscovered" in obj;
 }
-function distillDiscoveredPColumn(props) {
+function isColumnDiscoveredId(str) {
+	if (typeof str !== "string") return false;
+	return isColumnDiscoveredKey(parseJsonSafely(str));
+}
+function distillColumnDiscoveredKey(props) {
 	return {
+		__isDiscovered: true,
 		column: props.column,
 		path: Array.isArray(props.path) && props.path.length > 0 ? props.path : void 0,
 		columnQualifications: Array.isArray(props.columnQualifications) && props.columnQualifications.length > 0 ? props.columnQualifications : void 0,
 		queriesQualifications: props.queriesQualifications && Object.keys(props.queriesQualifications).length > 0 ? props.queriesQualifications : void 0
 	};
 }
-function createDiscoveredPColumnId(props) {
-	return stringifyDiscoveredPColumnId(props);
+function createColumnDiscoveredId(props) {
+	return stringifyColumnDiscoveredId(props);
+}
+function createColumnDiscoveredKey(props) {
+	return distillColumnDiscoveredKey({
+		__isDiscovered: true,
+		...props
+	});
 }
-function parseDiscoveredPColumnId(id) {
+function parseColumnDiscoveredId(id) {
 	try {
 		const parsed = JSON.parse(id);
-		return isDiscoveredPColumn(parsed) ? parsed : throwError("Parsed object is not a valid DiscoveredPColumn");
+		return isColumnDiscoveredKey(parsed) ? parsed : throwError("Parsed object is not a valid DiscoveredPColumn");
 	} catch {
-		throw new Error("Invalid DiscoveredPColumnId: not a valid JSON or does not conform to DiscoveredPColumn structure");
+		throw new Error("Invalid ColumnDiscoveredId: not a valid JSON or does not conform to DiscoveredPColumn structure");
 	}
 }
-function stringifyDiscoveredPColumnId(id) {
-	return canonicalizeJson(distillDiscoveredPColumn(id));
+function stringifyColumnDiscoveredId(id) {
+	return canonicalizeJson(distillColumnDiscoveredKey({
+		__isDiscovered: true,
+		...id
+	}));
 }
 //#endregion
-export { createDiscoveredPColumnId, distillDiscoveredPColumn, isDiscoveredPColumn, parseDiscoveredPColumnId, stringifyDiscoveredPColumnId };
+export { createColumnDiscoveredId, createColumnDiscoveredKey, distillColumnDiscoveredKey, isColumnDiscoveredId, isColumnDiscoveredKey, parseColumnDiscoveredId, stringifyColumnDiscoveredId };
 
 //# sourceMappingURL=discovered_column.js.map

package/dist/drivers/pframe/spec/discovered_column.js.map

@@ -1 +1 @@
-{"version":3,"file":"discovered_column.js","names":[],"sources":["../../../../src/drivers/pframe/spec/discovered_column.ts"],"sourcesContent":["import { Branded, throwError } from \"@milaboratories/helpers\";\nimport { PObjectId } from \"../../../pool\";\nimport { AxisQualification } from \"./selectors\";\nimport { canonicalizeJson } from \"../../../json\";\n\nexport type DiscoveredPColumn = {\n  column: PObjectId;\n  path?: PathItem[];\n  columnQualifications?: AxisQualification[];\n  queriesQualifications?: Record<PObjectId, AxisQualification[]>;\n};\n\nexport type DiscoveredPColumnId = Branded<PObjectId, \"DiscoveredPColumnId\">; // CanonicalizedJson<DiscoveredPColumn>;\n\ntype PathItem = {\n  type: \"linker\";\n  column: PObjectId;\n};\n\nexport function isDiscoveredPColumn(obj: unknown): obj is DiscoveredPColumn {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"path\" in obj &&\n    \"column\" in obj &&\n    \"columnQualifications\" in obj &&\n    \"queriesQualifications\" in obj\n  );\n}\n\nexport function distillDiscoveredPColumn(props: DiscoveredPColumn): DiscoveredPColumn {\n  return {\n    column: props.column,\n    path: Array.isArray(props.path) && props.path.length > 0 ? props.path : undefined,\n    columnQualifications:\n      Array.isArray(props.columnQualifications) && props.columnQualifications.length > 0\n        ? props.columnQualifications\n        : undefined,\n    queriesQualifications:\n      props.queriesQualifications && Object.keys(props.queriesQualifications).length > 0\n        ? props.queriesQualifications\n        : undefined,\n  };\n}\n\nexport function createDiscoveredPColumnId(props: {\n  column: PObjectId;\n  path?: PathItem[];\n  columnQualifications?: AxisQualification[];\n  queriesQualifications?: Record<PObjectId, AxisQualification[]>;\n}): DiscoveredPColumnId {\n  return stringifyDiscoveredPColumnId(props);\n}\n\nexport function parseDiscoveredPColumnId(id: DiscoveredPColumnId): DiscoveredPColumn {\n  try {\n    const parsed = JSON.parse(id);\n    return isDiscoveredPColumn(parsed)\n      ? parsed\n      : throwError(\"Parsed object is not a valid DiscoveredPColumn\");\n  } catch {\n    throw new Error(\n      \"Invalid DiscoveredPColumnId: not a valid JSON or does not conform to DiscoveredPColumn structure\",\n    );\n  }\n}\n\nexport function stringifyDiscoveredPColumnId(id: DiscoveredPColumn) {\n  return canonicalizeJson<DiscoveredPColumn>(\n    distillDiscoveredPColumn(id),\n  ) as string as DiscoveredPColumnId;\n}\n"],"mappings":";;;AAmBA,SAAgB,oBAAoB,KAAwC;CAC1E,OACE,OAAO,QAAQ,YACf,QAAQ,QACR,UAAU,OACV,YAAY,OACZ,0BAA0B,OAC1B,2BAA2B;AAE/B;AAEA,SAAgB,yBAAyB,OAA6C;CACpF,OAAO;EACL,QAAQ,MAAM;EACd,MAAM,MAAM,QAAQ,MAAM,IAAI,KAAK,MAAM,KAAK,SAAS,IAAI,MAAM,OAAO,KAAA;EACxE,sBACE,MAAM,QAAQ,MAAM,oBAAoB,KAAK,MAAM,qBAAqB,SAAS,IAC7E,MAAM,uBACN,KAAA;EACN,uBACE,MAAM,yBAAyB,OAAO,KAAK,MAAM,qBAAqB,CAAC,CAAC,SAAS,IAC7E,MAAM,wBACN,KAAA;CACR;AACF;AAEA,SAAgB,0BAA0B,OAKlB;CACtB,OAAO,6BAA6B,KAAK;AAC3C;AAEA,SAAgB,yBAAyB,IAA4C;CACnF,IAAI;EACF,MAAM,SAAS,KAAK,MAAM,EAAE;EAC5B,OAAO,oBAAoB,MAAM,IAC7B,SACA,WAAW,gDAAgD;CACjE,QAAQ;EACN,MAAM,IAAI,MACR,kGACF;CACF;AACF;AAEA,SAAgB,6BAA6B,IAAuB;CAClE,OAAO,iBACL,yBAAyB,EAAE,CAC7B;AACF"}
+{"version":3,"file":"discovered_column.js","names":[],"sources":["../../../../src/drivers/pframe/spec/discovered_column.ts"],"sourcesContent":["import { type Branded, throwError } from \"@milaboratories/helpers\";\nimport { type CanonicalizedJson, canonicalizeJson, parseJsonSafely } from \"../../../json\";\nimport { PObjectId } from \"../../../pool\";\nimport { AxisQualification } from \"./selectors\";\nimport { ColumnUniversalId } from \"./ids\";\n\nexport interface ColumnDiscoveredKey {\n  __isDiscovered: true;\n  column: ColumnUniversalId;\n  path?: PathItem[];\n  columnQualifications?: AxisQualification[];\n  queriesQualifications?: Record<PObjectId, AxisQualification[]>;\n}\n\nexport type ColumnDiscoveredId = Branded<\n  CanonicalizedJson<ColumnDiscoveredKey>,\n  \"ColumnDiscoveredId\"\n>;\n\ntype PathItem = {\n  type: \"linker\";\n  column: ColumnUniversalId;\n};\n\nexport function isColumnDiscoveredKey(obj: unknown): obj is ColumnDiscoveredKey {\n  return typeof obj === \"object\" && obj !== null && \"__isDiscovered\" in obj;\n}\n\nexport function isColumnDiscoveredId(str: unknown): str is ColumnDiscoveredId {\n  if (typeof str !== \"string\") return false;\n  return isColumnDiscoveredKey(parseJsonSafely(str));\n}\n\nexport function distillColumnDiscoveredKey(props: ColumnDiscoveredKey): ColumnDiscoveredKey {\n  return {\n    __isDiscovered: true,\n    column: props.column,\n    path: Array.isArray(props.path) && props.path.length > 0 ? props.path : undefined,\n    columnQualifications:\n      Array.isArray(props.columnQualifications) && props.columnQualifications.length > 0\n        ? props.columnQualifications\n        : undefined,\n    queriesQualifications:\n      props.queriesQualifications && Object.keys(props.queriesQualifications).length > 0\n        ? props.queriesQualifications\n        : undefined,\n  };\n}\n\nexport function createColumnDiscoveredId(props: {\n  column: ColumnUniversalId;\n  path?: PathItem[];\n  columnQualifications?: AxisQualification[];\n  queriesQualifications?: Record<PObjectId, AxisQualification[]>;\n}): ColumnDiscoveredId {\n  return stringifyColumnDiscoveredId(props);\n}\n\nexport function createColumnDiscoveredKey(props: {\n  column: ColumnUniversalId;\n  path?: PathItem[];\n  columnQualifications?: AxisQualification[];\n  queriesQualifications?: Record<PObjectId, AxisQualification[]>;\n}): ColumnDiscoveredKey {\n  return distillColumnDiscoveredKey({ __isDiscovered: true, ...props });\n}\n\nexport function parseColumnDiscoveredId(id: ColumnDiscoveredId): ColumnDiscoveredKey {\n  try {\n    const parsed = JSON.parse(id);\n    return isColumnDiscoveredKey(parsed)\n      ? parsed\n      : throwError(\"Parsed object is not a valid DiscoveredPColumn\");\n  } catch {\n    throw new Error(\n      \"Invalid ColumnDiscoveredId: not a valid JSON or does not conform to DiscoveredPColumn structure\",\n    );\n  }\n}\n\nexport function stringifyColumnDiscoveredId(\n  id: Omit<ColumnDiscoveredKey, \"__isDiscovered\">,\n): ColumnDiscoveredId {\n  return canonicalizeJson<ColumnDiscoveredKey>(\n    distillColumnDiscoveredKey({ __isDiscovered: true, ...id }),\n  ) as ColumnDiscoveredId;\n}\n"],"mappings":";;;AAwBA,SAAgB,sBAAsB,KAA0C;CAC9E,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,oBAAoB;AACxE;AAEA,SAAgB,qBAAqB,KAAyC;CAC5E,IAAI,OAAO,QAAQ,UAAU,OAAO;CACpC,OAAO,sBAAsB,gBAAgB,GAAG,CAAC;AACnD;AAEA,SAAgB,2BAA2B,OAAiD;CAC1F,OAAO;EACL,gBAAgB;EAChB,QAAQ,MAAM;EACd,MAAM,MAAM,QAAQ,MAAM,IAAI,KAAK,MAAM,KAAK,SAAS,IAAI,MAAM,OAAO,KAAA;EACxE,sBACE,MAAM,QAAQ,MAAM,oBAAoB,KAAK,MAAM,qBAAqB,SAAS,IAC7E,MAAM,uBACN,KAAA;EACN,uBACE,MAAM,yBAAyB,OAAO,KAAK,MAAM,qBAAqB,CAAC,CAAC,SAAS,IAC7E,MAAM,wBACN,KAAA;CACR;AACF;AAEA,SAAgB,yBAAyB,OAKlB;CACrB,OAAO,4BAA4B,KAAK;AAC1C;AAEA,SAAgB,0BAA0B,OAKlB;CACtB,OAAO,2BAA2B;EAAE,gBAAgB;EAAM,GAAG;CAAM,CAAC;AACtE;AAEA,SAAgB,wBAAwB,IAA6C;CACnF,IAAI;EACF,MAAM,SAAS,KAAK,MAAM,EAAE;EAC5B,OAAO,sBAAsB,MAAM,IAC/B,SACA,WAAW,gDAAgD;CACjE,QAAQ;EACN,MAAM,IAAI,MACR,iGACF;CACF;AACF;AAEA,SAAgB,4BACd,IACoB;CACpB,OAAO,iBACL,2BAA2B;EAAE,gBAAgB;EAAM,GAAG;CAAG,CAAC,CAC5D;AACF"}

package/dist/drivers/pframe/spec/filtered_column.cjs

@@ -1,13 +1,59 @@
+const require_json = require("../../../json.cjs");
 //#region src/drivers/pframe/spec/filtered_column.ts
 /**
 * Checks if a given value is a FilteredPColumn
 * @param id - The value to check
 * @returns True if the value is a FilteredPColumn, false otherwise
+* @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form
 */
 function isFilteredPColumn(id) {
 	return typeof id === "object" && id !== null && "source" in id && "axisFilters" in id;
 }
+function stringifyColumnFilteredId(key) {
+	return require_json.canonicalizeJson(createColumnFilteredKey(key));
+}
+function isColumnFilteredKey(obj) {
+	return typeof obj === "object" && obj !== null && "__isFiltered" in obj;
+}
+function isColumnFilteredId(id) {
+	if (typeof id !== "string") return false;
+	return isColumnFilteredKey(require_json.parseJsonSafely(id));
+}
+function createColumnFilteredId(props) {
+	return stringifyColumnFilteredId(props);
+}
+function createColumnFilteredKey(props) {
+	const axisFilters = props.axisFilters.toSorted((a, b) => a[0] - b[0]);
+	return {
+		__isFiltered: true,
+		source: props.source,
+		axisFilters
+	};
+}
+/**
+* Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s
+* `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`
+* unchanged when there are no filters.
+*
+* Single source of the Filtered-layer spec math — shared by
+* `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`
+* (sandbox, recipe-graph walking).
+*/
+function applyAxisFilters(spec, axisFilters) {
+	if (axisFilters.length === 0) return spec;
+	const fixed = new Set(axisFilters.map(([i]) => i));
+	return {
+		...spec,
+		axesSpec: spec.axesSpec.filter((_, i) => !fixed.has(i))
+	};
+}
 //#endregion
+exports.applyAxisFilters = applyAxisFilters;
+exports.createColumnFilteredId = createColumnFilteredId;
+exports.createColumnFilteredKey = createColumnFilteredKey;
+exports.isColumnFilteredId = isColumnFilteredId;
+exports.isColumnFilteredKey = isColumnFilteredKey;
 exports.isFilteredPColumn = isFilteredPColumn;
+exports.stringifyColumnFilteredId = stringifyColumnFilteredId;
 
 //# sourceMappingURL=filtered_column.cjs.map

package/dist/drivers/pframe/spec/filtered_column.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"filtered_column.cjs","names":[],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"sourcesContent":["import type { AnchoredPColumnId } from \"./selectors\";\n\n/** Value of an axis filter */\nexport type AxisFilterValue = number | string;\n\n/** Axis filter by index */\nexport type AxisFilterByIdx = [number, AxisFilterValue];\n\n/** Axis filter by name */\nexport type AxisFilterByName = [string, AxisFilterValue];\n\n/** Axis filter */\nexport type AxisFilter = AxisFilterByIdx | AxisFilterByName;\n\n/**\n * Identifies a column derived from a CanonicalPColumnId by fixing values on certain axes,\n * thus effectively reducing the dimensionality of the original column.\n */\nexport type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {\n  /** The original column identifier */\n  source: CID;\n\n  /**\n   * List of fixed axes and their corresponding values.\n   * Each entry fixes one axis to a specific value, creating a slice of the multidimensional data.\n   * This effectively reduces the dimensionality by one for each fixed axis.\n   * Ordered by the axis index in canonical case.\n   */\n  axisFilters: AFI[];\n};\n\nexport type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;\n\n/**\n * Checks if a given value is a FilteredPColumn\n * @param id - The value to check\n * @returns True if the value is a FilteredPColumn, false otherwise\n */\nexport function isFilteredPColumn(id: unknown): id is FilteredPColumn {\n  return typeof id === \"object\" && id !== null && \"source\" in id && \"axisFilters\" in id;\n}\n"],"mappings":";;;;;;AAsCA,SAAgB,kBAAkB,IAAoC;CACpE,OAAO,OAAO,OAAO,YAAY,OAAO,QAAQ,YAAY,MAAM,iBAAiB;AACrF"}
+{"version":3,"file":"filtered_column.cjs","names":["canonicalizeJson","parseJsonSafely"],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"sourcesContent":["import { type Branded } from \"@milaboratories/helpers\";\nimport { type CanonicalizedJson, canonicalizeJson, parseJsonSafely } from \"../../../json\";\nimport type { AnchoredPColumnId } from \"./selectors\";\nimport { ColumnUniversalId } from \"./ids\";\nimport type { PColumnSpec } from \"./spec\";\n\n/** Value of an axis filter */\nexport type AxisFilterValue = number | string;\n\n/** Axis filter by index */\nexport type AxisFilterByIdx = [number, AxisFilterValue];\n\n/** Axis filter by name */\nexport type AxisFilterByName = [string, AxisFilterValue];\n\n/** Axis filter */\nexport type AxisFilter = AxisFilterByIdx | AxisFilterByName;\n\n/**\n * Identifies a column derived from a CanonicalPColumnId by fixing values on certain axes,\n * thus effectively reducing the dimensionality of the original column.\n */\nexport type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {\n  /** The original column identifier */\n  source: CID;\n\n  /**\n   * List of fixed axes and their corresponding values.\n   * Each entry fixes one axis to a specific value, creating a slice of the multidimensional data.\n   * This effectively reduces the dimensionality by one for each fixed axis.\n   * Ordered by the axis index in canonical case.\n   */\n  axisFilters: AFI[];\n};\n\n/** @deprecated */\nexport type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;\n\n/**\n * Checks if a given value is a FilteredPColumn\n * @param id - The value to check\n * @returns True if the value is a FilteredPColumn, false otherwise\n * @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form\n */\nexport function isFilteredPColumn(id: unknown): id is FilteredPColumn {\n  return typeof id === \"object\" && id !== null && \"source\" in id && \"axisFilters\" in id;\n}\n\n/**\n * `source` is either a leaf {@link PObjectId} or a {@link ColumnDiscoveredId}.\n * Filtered never nests inside Filtered (flat-merge invariant), and Filtered is\n * never the outer wrapper around Overridden — Overridden is always outermost.\n */\nexport interface ColumnFilteredKey {\n  __isFiltered: true;\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}\n\nexport type ColumnFilteredId = Branded<CanonicalizedJson<ColumnFilteredKey>, \"ColumnFilteredId\">;\n\nexport function stringifyColumnFilteredId(\n  key: Omit<ColumnFilteredKey, \"__isFiltered\">,\n): ColumnFilteredId {\n  return canonicalizeJson<ColumnFilteredKey>(createColumnFilteredKey(key)) as ColumnFilteredId;\n}\n\nexport function isColumnFilteredKey(obj: unknown): obj is ColumnFilteredKey {\n  return typeof obj === \"object\" && obj !== null && \"__isFiltered\" in obj;\n}\n\nexport function isColumnFilteredId(id: unknown): id is ColumnFilteredId {\n  if (typeof id !== \"string\") return false;\n  return isColumnFilteredKey(parseJsonSafely(id));\n}\n\nexport function createColumnFilteredId(props: {\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}): ColumnFilteredId {\n  return stringifyColumnFilteredId(props);\n}\n\nexport function createColumnFilteredKey(props: {\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}): ColumnFilteredKey {\n  // `axisFilters` must be ordered by axis index so logically\n  // identical filtered columns produce one canonical id.\n  const axisFilters = props.axisFilters.toSorted((a, b) => a[0] - b[0]);\n  return { __isFiltered: true, source: props.source, axisFilters };\n}\n\n/**\n * Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s\n * `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`\n * unchanged when there are no filters.\n *\n * Single source of the Filtered-layer spec math — shared by\n * `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`\n * (sandbox, recipe-graph walking).\n */\nexport function applyAxisFilters(spec: PColumnSpec, axisFilters: AxisFilterByIdx[]): PColumnSpec {\n  if (axisFilters.length === 0) return spec;\n  const fixed = new Set(axisFilters.map(([i]) => i));\n  return { ...spec, axesSpec: spec.axesSpec.filter((_, i) => !fixed.has(i)) };\n}\n"],"mappings":";;;;;;;;AA4CA,SAAgB,kBAAkB,IAAoC;CACpE,OAAO,OAAO,OAAO,YAAY,OAAO,QAAQ,YAAY,MAAM,iBAAiB;AACrF;AAeA,SAAgB,0BACd,KACkB;CAClB,OAAOA,aAAAA,iBAAoC,wBAAwB,GAAG,CAAC;AACzE;AAEA,SAAgB,oBAAoB,KAAwC;CAC1E,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,kBAAkB;AACtE;AAEA,SAAgB,mBAAmB,IAAqC;CACtE,IAAI,OAAO,OAAO,UAAU,OAAO;CACnC,OAAO,oBAAoBC,aAAAA,gBAAgB,EAAE,CAAC;AAChD;AAEA,SAAgB,uBAAuB,OAGlB;CACnB,OAAO,0BAA0B,KAAK;AACxC;AAEA,SAAgB,wBAAwB,OAGlB;CAGpB,MAAM,cAAc,MAAM,YAAY,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;CACpE,OAAO;EAAE,cAAc;EAAM,QAAQ,MAAM;EAAQ;CAAY;AACjE;;;;;;;;;;AAWA,SAAgB,iBAAiB,MAAmB,aAA6C;CAC/F,IAAI,YAAY,WAAW,GAAG,OAAO;CACrC,MAAM,QAAQ,IAAI,IAAI,YAAY,KAAK,CAAC,OAAO,CAAC,CAAC;CACjD,OAAO;EAAE,GAAG;EAAM,UAAU,KAAK,SAAS,QAAQ,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;CAAE;AAC5E"}

package/dist/drivers/pframe/spec/filtered_column.d.ts

@@ -1,4 +1,8 @@
+import { CanonicalizedJson } from "../../../json.js";
+import { PColumnSpec } from "./spec.js";
+import { ColumnUniversalId } from "./ids.js";
 import { AnchoredPColumnId } from "./selectors.js";
+import { Branded } from "@milaboratories/helpers";
 
 //#region src/drivers/pframe/spec/filtered_column.d.ts
 /** Value of an axis filter */
@@ -23,13 +27,47 @@ type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {
    */
   axisFilters: AFI[];
 };
+/** @deprecated */
 type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;
 /**
  * Checks if a given value is a FilteredPColumn
  * @param id - The value to check
  * @returns True if the value is a FilteredPColumn, false otherwise
+ * @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form
  */
 declare function isFilteredPColumn(id: unknown): id is FilteredPColumn;
+/**
+ * `source` is either a leaf {@link PObjectId} or a {@link ColumnDiscoveredId}.
+ * Filtered never nests inside Filtered (flat-merge invariant), and Filtered is
+ * never the outer wrapper around Overridden — Overridden is always outermost.
+ */
+interface ColumnFilteredKey {
+  __isFiltered: true;
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}
+type ColumnFilteredId = Branded<CanonicalizedJson<ColumnFilteredKey>, "ColumnFilteredId">;
+declare function stringifyColumnFilteredId(key: Omit<ColumnFilteredKey, "__isFiltered">): ColumnFilteredId;
+declare function isColumnFilteredKey(obj: unknown): obj is ColumnFilteredKey;
+declare function isColumnFilteredId(id: unknown): id is ColumnFilteredId;
+declare function createColumnFilteredId(props: {
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}): ColumnFilteredId;
+declare function createColumnFilteredKey(props: {
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}): ColumnFilteredKey;
+/**
+ * Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s
+ * `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`
+ * unchanged when there are no filters.
+ *
+ * Single source of the Filtered-layer spec math — shared by
+ * `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`
+ * (sandbox, recipe-graph walking).
+ */
+declare function applyAxisFilters(spec: PColumnSpec, axisFilters: AxisFilterByIdx[]): PColumnSpec;
 //#endregion
-export { AxisFilter, AxisFilterByIdx, AxisFilterByName, AxisFilterValue, FilteredPColumn, FilteredPColumnId, isFilteredPColumn };
+export { AxisFilter, AxisFilterByIdx, AxisFilterByName, AxisFilterValue, ColumnFilteredId, ColumnFilteredKey, FilteredPColumn, FilteredPColumnId, applyAxisFilters, createColumnFilteredId, createColumnFilteredKey, isColumnFilteredId, isColumnFilteredKey, isFilteredPColumn, stringifyColumnFilteredId };
 //# sourceMappingURL=filtered_column.d.ts.map

package/dist/drivers/pframe/spec/filtered_column.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered_column.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"mappings":";;;;KAGY,eAAA;AAAZ;AAAA,KAGY,eAAA,YAA2B,eAAe;;KAG1C,gBAAA,YAA4B,eAAe;AAN5B;AAAA,KASf,UAAA,GAAa,eAAA,GAAkB,gBAAgB;;;;AANL;KAY1C,eAAA,OAAsB,iBAAA,QAAyB,UAAA;EAT/B,qCAW1B,MAAA,EAAQ,GAAA;EAX6C;AAAA;AAGvD;;;;EAgBE,WAAA,EAAa,GAAA;AAAA;AAAA,KAGH,iBAAA,GAAoB,eAAA,CAAgB,iBAAA,EAAmB,eAAA;;;;;;iBAOnD,iBAAA,CAAkB,EAAA,YAAc,EAAA,IAAM,eAAe"}
+{"version":3,"file":"filtered_column.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"mappings":";;;;;;;;KAOY,eAAA;AAAZ;AAAA,KAGY,eAAA,YAA2B,eAAe;;KAG1C,gBAAA,YAA4B,eAAe;AAN5B;AAAA,KASf,UAAA,GAAa,eAAA,GAAkB,gBAAgB;;;;AANL;KAY1C,eAAA,OAAsB,iBAAA,QAAyB,UAAA;EAT/B,qCAW1B,MAAA,EAAQ,GAAA;EAX6C;AAAA;AAGvD;;;;EAgBE,WAAA,EAAa,GAAA;AAAA;;KAIH,iBAAA,GAAoB,eAAA,CAAgB,iBAAA,EAAmB,eAAA;;;;;;;iBAQnD,iBAAA,CAAkB,EAAA,YAAc,EAAA,IAAM,eAAe;;;;;;UASpD,iBAAA;EACf,YAAA;EACA,MAAA,EAAQ,iBAAA;EACR,WAAA,EAAa,eAAe;AAAA;AAAA,KAGlB,gBAAA,GAAmB,OAAA,CAAQ,iBAAA,CAAkB,iBAAA;AAAA,iBAEzC,yBAAA,CACd,GAAA,EAAK,IAAA,CAAK,iBAAA,oBACT,gBAAA;AAAA,iBAIa,mBAAA,CAAoB,GAAA,YAAe,GAAA,IAAO,iBAAiB;AAAA,iBAI3D,kBAAA,CAAmB,EAAA,YAAc,EAAA,IAAM,gBAAgB;AAAA,iBAKvD,sBAAA,CAAuB,KAAA;EACrC,MAAA,EAAQ,iBAAA;EACR,WAAA,EAAa,eAAA;AAAA,IACX,gBAAA;AAAA,iBAIY,uBAAA,CAAwB,KAAA;EACtC,MAAA,EAAQ,iBAAA;EACR,WAAA,EAAa,eAAA;AAAA,IACX,iBAAA;AA1CJ;;;;;;;;AAAqE;AAArE,iBA0DgB,gBAAA,CAAiB,IAAA,EAAM,WAAA,EAAa,WAAA,EAAa,eAAA,KAAoB,WAAA"}

package/dist/drivers/pframe/spec/filtered_column.js

@@ -1,13 +1,53 @@
+import { canonicalizeJson, parseJsonSafely } from "../../../json.js";
 //#region src/drivers/pframe/spec/filtered_column.ts
 /**
 * Checks if a given value is a FilteredPColumn
 * @param id - The value to check
 * @returns True if the value is a FilteredPColumn, false otherwise
+* @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form
 */
 function isFilteredPColumn(id) {
 	return typeof id === "object" && id !== null && "source" in id && "axisFilters" in id;
 }
+function stringifyColumnFilteredId(key) {
+	return canonicalizeJson(createColumnFilteredKey(key));
+}
+function isColumnFilteredKey(obj) {
+	return typeof obj === "object" && obj !== null && "__isFiltered" in obj;
+}
+function isColumnFilteredId(id) {
+	if (typeof id !== "string") return false;
+	return isColumnFilteredKey(parseJsonSafely(id));
+}
+function createColumnFilteredId(props) {
+	return stringifyColumnFilteredId(props);
+}
+function createColumnFilteredKey(props) {
+	const axisFilters = props.axisFilters.toSorted((a, b) => a[0] - b[0]);
+	return {
+		__isFiltered: true,
+		source: props.source,
+		axisFilters
+	};
+}
+/**
+* Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s
+* `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`
+* unchanged when there are no filters.
+*
+* Single source of the Filtered-layer spec math — shared by
+* `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`
+* (sandbox, recipe-graph walking).
+*/
+function applyAxisFilters(spec, axisFilters) {
+	if (axisFilters.length === 0) return spec;
+	const fixed = new Set(axisFilters.map(([i]) => i));
+	return {
+		...spec,
+		axesSpec: spec.axesSpec.filter((_, i) => !fixed.has(i))
+	};
+}
 //#endregion
-export { isFilteredPColumn };
+export { applyAxisFilters, createColumnFilteredId, createColumnFilteredKey, isColumnFilteredId, isColumnFilteredKey, isFilteredPColumn, stringifyColumnFilteredId };
 
 //# sourceMappingURL=filtered_column.js.map

package/dist/drivers/pframe/spec/filtered_column.js.map

@@ -1 +1 @@
-{"version":3,"file":"filtered_column.js","names":[],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"sourcesContent":["import type { AnchoredPColumnId } from \"./selectors\";\n\n/** Value of an axis filter */\nexport type AxisFilterValue = number | string;\n\n/** Axis filter by index */\nexport type AxisFilterByIdx = [number, AxisFilterValue];\n\n/** Axis filter by name */\nexport type AxisFilterByName = [string, AxisFilterValue];\n\n/** Axis filter */\nexport type AxisFilter = AxisFilterByIdx | AxisFilterByName;\n\n/**\n * Identifies a column derived from a CanonicalPColumnId by fixing values on certain axes,\n * thus effectively reducing the dimensionality of the original column.\n */\nexport type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {\n  /** The original column identifier */\n  source: CID;\n\n  /**\n   * List of fixed axes and their corresponding values.\n   * Each entry fixes one axis to a specific value, creating a slice of the multidimensional data.\n   * This effectively reduces the dimensionality by one for each fixed axis.\n   * Ordered by the axis index in canonical case.\n   */\n  axisFilters: AFI[];\n};\n\nexport type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;\n\n/**\n * Checks if a given value is a FilteredPColumn\n * @param id - The value to check\n * @returns True if the value is a FilteredPColumn, false otherwise\n */\nexport function isFilteredPColumn(id: unknown): id is FilteredPColumn {\n  return typeof id === \"object\" && id !== null && \"source\" in id && \"axisFilters\" in id;\n}\n"],"mappings":";;;;;;AAsCA,SAAgB,kBAAkB,IAAoC;CACpE,OAAO,OAAO,OAAO,YAAY,OAAO,QAAQ,YAAY,MAAM,iBAAiB;AACrF"}
+{"version":3,"file":"filtered_column.js","names":[],"sources":["../../../../src/drivers/pframe/spec/filtered_column.ts"],"sourcesContent":["import { type Branded } from \"@milaboratories/helpers\";\nimport { type CanonicalizedJson, canonicalizeJson, parseJsonSafely } from \"../../../json\";\nimport type { AnchoredPColumnId } from \"./selectors\";\nimport { ColumnUniversalId } from \"./ids\";\nimport type { PColumnSpec } from \"./spec\";\n\n/** Value of an axis filter */\nexport type AxisFilterValue = number | string;\n\n/** Axis filter by index */\nexport type AxisFilterByIdx = [number, AxisFilterValue];\n\n/** Axis filter by name */\nexport type AxisFilterByName = [string, AxisFilterValue];\n\n/** Axis filter */\nexport type AxisFilter = AxisFilterByIdx | AxisFilterByName;\n\n/**\n * Identifies a column derived from a CanonicalPColumnId by fixing values on certain axes,\n * thus effectively reducing the dimensionality of the original column.\n */\nexport type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {\n  /** The original column identifier */\n  source: CID;\n\n  /**\n   * List of fixed axes and their corresponding values.\n   * Each entry fixes one axis to a specific value, creating a slice of the multidimensional data.\n   * This effectively reduces the dimensionality by one for each fixed axis.\n   * Ordered by the axis index in canonical case.\n   */\n  axisFilters: AFI[];\n};\n\n/** @deprecated */\nexport type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;\n\n/**\n * Checks if a given value is a FilteredPColumn\n * @param id - The value to check\n * @returns True if the value is a FilteredPColumn, false otherwise\n * @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form\n */\nexport function isFilteredPColumn(id: unknown): id is FilteredPColumn {\n  return typeof id === \"object\" && id !== null && \"source\" in id && \"axisFilters\" in id;\n}\n\n/**\n * `source` is either a leaf {@link PObjectId} or a {@link ColumnDiscoveredId}.\n * Filtered never nests inside Filtered (flat-merge invariant), and Filtered is\n * never the outer wrapper around Overridden — Overridden is always outermost.\n */\nexport interface ColumnFilteredKey {\n  __isFiltered: true;\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}\n\nexport type ColumnFilteredId = Branded<CanonicalizedJson<ColumnFilteredKey>, \"ColumnFilteredId\">;\n\nexport function stringifyColumnFilteredId(\n  key: Omit<ColumnFilteredKey, \"__isFiltered\">,\n): ColumnFilteredId {\n  return canonicalizeJson<ColumnFilteredKey>(createColumnFilteredKey(key)) as ColumnFilteredId;\n}\n\nexport function isColumnFilteredKey(obj: unknown): obj is ColumnFilteredKey {\n  return typeof obj === \"object\" && obj !== null && \"__isFiltered\" in obj;\n}\n\nexport function isColumnFilteredId(id: unknown): id is ColumnFilteredId {\n  if (typeof id !== \"string\") return false;\n  return isColumnFilteredKey(parseJsonSafely(id));\n}\n\nexport function createColumnFilteredId(props: {\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}): ColumnFilteredId {\n  return stringifyColumnFilteredId(props);\n}\n\nexport function createColumnFilteredKey(props: {\n  source: ColumnUniversalId;\n  axisFilters: AxisFilterByIdx[];\n}): ColumnFilteredKey {\n  // `axisFilters` must be ordered by axis index so logically\n  // identical filtered columns produce one canonical id.\n  const axisFilters = props.axisFilters.toSorted((a, b) => a[0] - b[0]);\n  return { __isFiltered: true, source: props.source, axisFilters };\n}\n\n/**\n * Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s\n * `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`\n * unchanged when there are no filters.\n *\n * Single source of the Filtered-layer spec math — shared by\n * `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`\n * (sandbox, recipe-graph walking).\n */\nexport function applyAxisFilters(spec: PColumnSpec, axisFilters: AxisFilterByIdx[]): PColumnSpec {\n  if (axisFilters.length === 0) return spec;\n  const fixed = new Set(axisFilters.map(([i]) => i));\n  return { ...spec, axesSpec: spec.axesSpec.filter((_, i) => !fixed.has(i)) };\n}\n"],"mappings":";;;;;;;;AA4CA,SAAgB,kBAAkB,IAAoC;CACpE,OAAO,OAAO,OAAO,YAAY,OAAO,QAAQ,YAAY,MAAM,iBAAiB;AACrF;AAeA,SAAgB,0BACd,KACkB;CAClB,OAAO,iBAAoC,wBAAwB,GAAG,CAAC;AACzE;AAEA,SAAgB,oBAAoB,KAAwC;CAC1E,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,kBAAkB;AACtE;AAEA,SAAgB,mBAAmB,IAAqC;CACtE,IAAI,OAAO,OAAO,UAAU,OAAO;CACnC,OAAO,oBAAoB,gBAAgB,EAAE,CAAC;AAChD;AAEA,SAAgB,uBAAuB,OAGlB;CACnB,OAAO,0BAA0B,KAAK;AACxC;AAEA,SAAgB,wBAAwB,OAGlB;CAGpB,MAAM,cAAc,MAAM,YAAY,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;CACpE,OAAO;EAAE,cAAc;EAAM,QAAQ,MAAM;EAAQ;CAAY;AACjE;;;;;;;;;;AAWA,SAAgB,iBAAiB,MAAmB,aAA6C;CAC/F,IAAI,YAAY,WAAW,GAAG,OAAO;CACrC,MAAM,QAAQ,IAAI,IAAI,YAAY,KAAK,CAAC,OAAO,CAAC,CAAC;CACjD,OAAO;EAAE,GAAG;EAAM,UAAU,KAAK,SAAS,QAAQ,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;CAAE;AAC5E"}

package/dist/drivers/pframe/spec/ids.cjs

@@ -1,25 +1,77 @@
-const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
-let canonicalize = require("canonicalize");
-canonicalize = require_runtime.__toESM(canonicalize, 1);
+const require_json = require("../../../json.cjs");
+const require_filtered_column = require("./filtered_column.cjs");
+const require_spec = require("../../../pool/spec.cjs");
+require("../../../pool/index.cjs");
+const require_discovered_column = require("./discovered_column.cjs");
+const require_overridden = require("./overridden.cjs");
+let _milaboratories_helpers = require("@milaboratories/helpers");
+let es_toolkit = require("es-toolkit");
 //#region src/drivers/pframe/spec/ids.ts
 /**
-* Canonically serializes a {@link UniversalPColumnId} to a string.
-* @param id - The column identifier to serialize
-* @returns The canonically serialized string
+* Canonically serializes a column key to a branded string id. Accepts both
+* the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}
+* (anchored / old filtered object form).
 */
 function stringifyColumnId(id) {
-	return (0, canonicalize.default)(id);
+	return require_json.canonicalizeJson(id);
 }
 /**
-* Parses a canonically serialized {@link UniversalPColumnId} from a string.
-* @param str - The string to parse
-* @returns The parsed column identifier
+* Parses a canonically serialized column id back to its key form.
 */
 function parseColumnId(str) {
 	return JSON.parse(str);
 }
+function parseColumnIdSafely(str, fallback = void 0) {
+	try {
+		return JSON.parse(str);
+	} catch {
+		return fallback;
+	}
+}
+/**
+* Walk a rich column id down to its terminal leaf {@link PObjectId}.
+*/
+function extractPObjectId(id) {
+	if ((0, es_toolkit.isString)(id)) {
+		if (require_spec.isPObjectId(id)) return id;
+		return extractPObjectId(parseColumnIdSafely(id) ?? (0, _milaboratories_helpers.throwError)(`extractPObjectId: id "${id}" is not a valid canonical column id`));
+	}
+	if (require_spec.isPObjectKey(id)) return require_spec.createPObjectId(id);
+	if (require_filtered_column.isColumnFilteredKey(id)) return extractPObjectId(id.source);
+	if (require_overridden.isColumnOverriddenKey(id)) return extractPObjectId(id.source);
+	if (require_discovered_column.isColumnDiscoveredKey(id)) return extractPObjectId(id.column);
+	throw new Error(`extractPObjectId: unrecognized column id structure: ${JSON.stringify(id)}`);
+}
+/**
+* Reconstruct the effective {@link PColumnSpec} for a rich column id by walking
+* the id chain from leaf to outermost wrapper, applying each layer's spec
+* transformation in the same order the corresponding recipe would.
+*
+* Layer semantics:
+* - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.
+* - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.
+* - {@link ColumnFilteredKey}: drops the axes whose positional index appears in
+*   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors
+*   `ColumnFilteredRecipe.getSpec()`.
+* - {@link ColumnOverriddenKey}: applies `specOverrides` via
+*   {@link applySpecOverrides} on top of the inner spec.
+*/
+function reconstructSpecFromId(baseSpec, id) {
+	if ((0, es_toolkit.isString)(id)) {
+		if (require_spec.isPObjectId(id)) return baseSpec;
+		return reconstructSpecFromId(baseSpec, parseColumnIdSafely(id) ?? (0, _milaboratories_helpers.throwError)(`reconstructSpecFromId: id "${id}" is not a valid canonical column id`));
+	}
+	if (require_spec.isPObjectKey(id)) return baseSpec;
+	if (require_discovered_column.isColumnDiscoveredKey(id)) return reconstructSpecFromId(baseSpec, id.column);
+	if (require_filtered_column.isColumnFilteredKey(id)) return require_filtered_column.applyAxisFilters(reconstructSpecFromId(baseSpec, id.source), id.axisFilters);
+	if (require_overridden.isColumnOverriddenKey(id)) return require_overridden.applySpecOverrides(reconstructSpecFromId(baseSpec, id.source), id.specOverrides);
+	throw new Error(`reconstructSpecFromId: unrecognized column id structure: ${JSON.stringify(id)}`);
+}
 //#endregion
+exports.extractPObjectId = extractPObjectId;
 exports.parseColumnId = parseColumnId;
+exports.parseColumnIdSafely = parseColumnIdSafely;
+exports.reconstructSpecFromId = reconstructSpecFromId;
 exports.stringifyColumnId = stringifyColumnId;
 
 //# sourceMappingURL=ids.cjs.map

package/dist/drivers/pframe/spec/ids.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ids.cjs","names":[],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"sourcesContent":["import type { Branded } from \"../../../branding\";\nimport type { AnchoredPColumnId } from \"./selectors\";\nimport type { FilteredPColumnId } from \"./filtered_column\";\nimport canonicalize from \"canonicalize\";\nimport type { PObjectId } from \"../../../pool\";\nimport { DiscoveredPColumn } from \"./discovered_column\";\n\n/**\n * Universal column identifier optionally anchored and optionally filtered.\n */\nexport type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId | DiscoveredPColumn;\n\n/**\n * Canonically serialized {@link UniversalPColumnId}.\n */\nexport type SUniversalPColumnId = Branded<PObjectId, \"SUniversalPColumnId\", \"__pl_model_brand_2__\">;\n\n/**\n * Canonically serializes a {@link UniversalPColumnId} to a string.\n * @param id - The column identifier to serialize\n * @returns The canonically serialized string\n */\nexport function stringifyColumnId(id: UniversalPColumnId): SUniversalPColumnId {\n  return canonicalize(id)! as SUniversalPColumnId;\n}\n\n/**\n * Parses a canonically serialized {@link UniversalPColumnId} from a string.\n * @param str - The string to parse\n * @returns The parsed column identifier\n */\nexport function parseColumnId(str: SUniversalPColumnId): UniversalPColumnId {\n  return JSON.parse(str) as UniversalPColumnId;\n}\n"],"mappings":";;;;;;;;;AAsBA,SAAgB,kBAAkB,IAA6C;CAC7E,QAAA,GAAA,aAAA,QAAA,CAAoB,EAAE;AACxB;;;;;;AAOA,SAAgB,cAAc,KAA8C;CAC1E,OAAO,KAAK,MAAM,GAAG;AACvB"}
+{"version":3,"file":"ids.cjs","names":["canonicalizeJson","isPObjectId","isPObjectKey","createPObjectId","isColumnFilteredKey","isColumnOverriddenKey","isColumnDiscoveredKey","applyAxisFilters","applySpecOverrides"],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"sourcesContent":["import type { AnchoredPColumnId } from \"./selectors\";\nimport {\n  applyAxisFilters,\n  isColumnFilteredKey,\n  type ColumnFilteredId,\n  type ColumnFilteredKey,\n  type FilteredPColumnId,\n} from \"./filtered_column\";\nimport {\n  createPObjectId,\n  isPObjectId,\n  isPObjectKey,\n  LocalPObjectKey,\n  type GlobalPObjectId,\n  type GlobalPObjectKey,\n  type LocalPObjectId,\n  type PObjectId,\n} from \"../../../pool\";\nimport {\n  isColumnDiscoveredKey,\n  type ColumnDiscoveredId,\n  type ColumnDiscoveredKey,\n} from \"./discovered_column\";\nimport { throwError } from \"@milaboratories/helpers\";\nimport {\n  applySpecOverrides,\n  isColumnOverriddenKey,\n  type ColumnOverriddenId,\n  type ColumnOverriddenKey,\n} from \"./overridden\";\nimport { canonicalizeJson } from \"../../../json\";\nimport { AxisSpec, PColumnSpec } from \"./spec\";\nimport { isString } from \"es-toolkit\";\n\n/**\n * Per-axis patches keyed by positional index in the base spec's `axesSpec`.\n *\n * Using position rather than `name` lets us disambiguate linker-style specs\n * that carry multiple axes with the same `name` differentiated by `domain` /\n * `contextDomain` (e.g. a `group`, `group/primary`, `group/secondary` triple).\n *\n * A patch at index `>= base.axesSpec.length` appends a new axis at that slot.\n */\nexport type AxisPatches = Record<number, Partial<AxisSpec>>;\n\n/**\n * Universal column identifier optionally anchored and optionally filtered.\n * @deprecated use {@link ColumnUniversalKey}\n */\nexport type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId;\n\n/**\n * Canonically serialized {@link UniversalPColumnId}.\n * @deprecated use {@link ColumnUniversalId}\n */\nexport type SUniversalPColumnId = ColumnUniversalId;\n// export type SUniversalPColumnId = Branded<PObjectId, \"SUniversalPColumnId\", \"__pl_model_brand_2__\">;\n\nexport type ColumnUniversalKey =\n  | LocalPObjectKey\n  | GlobalPObjectKey\n  | ColumnFilteredKey\n  | ColumnDiscoveredKey\n  | ColumnOverriddenKey;\n\nexport type ColumnUniversalId =\n  | LocalPObjectId\n  | GlobalPObjectId\n  | ColumnFilteredId\n  | ColumnDiscoveredId\n  | ColumnOverriddenId;\n\n/**\n * Canonically serializes a column key to a branded string id. Accepts both\n * the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}\n * (anchored / old filtered object form).\n */\nexport function stringifyColumnId(id: ColumnUniversalKey | UniversalPColumnId): ColumnUniversalId {\n  return canonicalizeJson(id) as ColumnUniversalId;\n}\n\n/**\n * Parses a canonically serialized column id back to its key form.\n */\nexport function parseColumnId(str: ColumnUniversalId): ColumnUniversalKey {\n  return JSON.parse(str) as ColumnUniversalKey;\n}\n\nexport function parseColumnIdSafely(\n  str: ColumnUniversalId,\n  fallback = undefined,\n): ColumnUniversalKey | typeof fallback {\n  try {\n    return JSON.parse(str) as ColumnUniversalKey;\n  } catch {\n    return fallback;\n  }\n}\n\n/**\n * Walk a rich column id down to its terminal leaf {@link PObjectId}.\n */\nexport function extractPObjectId(id: ColumnUniversalId | ColumnUniversalKey): PObjectId {\n  if (isString(id)) {\n    if (isPObjectId(id)) return id;\n\n    const parsed =\n      parseColumnIdSafely(id) ??\n      throwError(`extractPObjectId: id \"${id}\" is not a valid canonical column id`);\n    return extractPObjectId(parsed);\n  }\n\n  if (isPObjectKey(id)) return createPObjectId(id);\n  if (isColumnFilteredKey(id)) return extractPObjectId(id.source);\n  if (isColumnOverriddenKey(id)) return extractPObjectId(id.source);\n  if (isColumnDiscoveredKey(id)) return extractPObjectId(id.column);\n\n  throw new Error(`extractPObjectId: unrecognized column id structure: ${JSON.stringify(id)}`);\n}\n\n/**\n * Reconstruct the effective {@link PColumnSpec} for a rich column id by walking\n * the id chain from leaf to outermost wrapper, applying each layer's spec\n * transformation in the same order the corresponding recipe would.\n *\n * Layer semantics:\n * - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.\n * - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.\n * - {@link ColumnFilteredKey}: drops the axes whose positional index appears in\n *   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors\n *   `ColumnFilteredRecipe.getSpec()`.\n * - {@link ColumnOverriddenKey}: applies `specOverrides` via\n *   {@link applySpecOverrides} on top of the inner spec.\n */\nexport function reconstructSpecFromId(\n  baseSpec: PColumnSpec,\n  id: ColumnUniversalId | ColumnUniversalKey,\n): PColumnSpec {\n  if (isString(id)) {\n    if (isPObjectId(id)) return baseSpec;\n\n    const parsed =\n      parseColumnIdSafely(id) ??\n      throwError(`reconstructSpecFromId: id \"${id}\" is not a valid canonical column id`);\n    return reconstructSpecFromId(baseSpec, parsed);\n  }\n\n  if (isPObjectKey(id)) return baseSpec;\n  if (isColumnDiscoveredKey(id)) return reconstructSpecFromId(baseSpec, id.column);\n  if (isColumnFilteredKey(id)) {\n    return applyAxisFilters(reconstructSpecFromId(baseSpec, id.source), id.axisFilters);\n  }\n  if (isColumnOverriddenKey(id)) {\n    const inner = reconstructSpecFromId(baseSpec, id.source);\n    return applySpecOverrides(inner, id.specOverrides);\n  }\n\n  throw new Error(`reconstructSpecFromId: unrecognized column id structure: ${JSON.stringify(id)}`);\n}\n"],"mappings":";;;;;;;;;;;;;;AA6EA,SAAgB,kBAAkB,IAAgE;CAChG,OAAOA,aAAAA,iBAAiB,EAAE;AAC5B;;;;AAKA,SAAgB,cAAc,KAA4C;CACxE,OAAO,KAAK,MAAM,GAAG;AACvB;AAEA,SAAgB,oBACd,KACA,WAAW,KAAA,GAC2B;CACtC,IAAI;EACF,OAAO,KAAK,MAAM,GAAG;CACvB,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,SAAgB,iBAAiB,IAAuD;CACtF,KAAA,GAAA,WAAA,SAAA,CAAa,EAAE,GAAG;EAChB,IAAIC,aAAAA,YAAY,EAAE,GAAG,OAAO;EAK5B,OAAO,iBAFL,oBAAoB,EAAE,MAAA,GAAA,wBAAA,WAAA,CACX,yBAAyB,GAAG,qCAAqC,CAChD;CAChC;CAEA,IAAIC,aAAAA,aAAa,EAAE,GAAG,OAAOC,aAAAA,gBAAgB,EAAE;CAC/C,IAAIC,wBAAAA,oBAAoB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAC9D,IAAIC,mBAAAA,sBAAsB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAChE,IAAIC,0BAAAA,sBAAsB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAEhE,MAAM,IAAI,MAAM,uDAAuD,KAAK,UAAU,EAAE,GAAG;AAC7F;;;;;;;;;;;;;;;AAgBA,SAAgB,sBACd,UACA,IACa;CACb,KAAA,GAAA,WAAA,SAAA,CAAa,EAAE,GAAG;EAChB,IAAIL,aAAAA,YAAY,EAAE,GAAG,OAAO;EAK5B,OAAO,sBAAsB,UAF3B,oBAAoB,EAAE,MAAA,GAAA,wBAAA,WAAA,CACX,8BAA8B,GAAG,qCAAqC,CACtC;CAC/C;CAEA,IAAIC,aAAAA,aAAa,EAAE,GAAG,OAAO;CAC7B,IAAII,0BAAAA,sBAAsB,EAAE,GAAG,OAAO,sBAAsB,UAAU,GAAG,MAAM;CAC/E,IAAIF,wBAAAA,oBAAoB,EAAE,GACxB,OAAOG,wBAAAA,iBAAiB,sBAAsB,UAAU,GAAG,MAAM,GAAG,GAAG,WAAW;CAEpF,IAAIF,mBAAAA,sBAAsB,EAAE,GAE1B,OAAOG,mBAAAA,mBADO,sBAAsB,UAAU,GAAG,MACnB,GAAG,GAAG,aAAa;CAGnD,MAAM,IAAI,MAAM,4DAA4D,KAAK,UAAU,EAAE,GAAG;AAClG"}

package/dist/drivers/pframe/spec/ids.d.ts

@@ -1,29 +1,62 @@
-import { Branded } from "../../../branding.js";
-import { FilteredPColumnId } from "./filtered_column.js";
-import { DiscoveredPColumn } from "./discovered_column.js";
+import { ColumnDiscoveredId, ColumnDiscoveredKey } from "./discovered_column.js";
+import { AxisSpec, PColumnSpec } from "./spec.js";
+import { ColumnOverriddenId, ColumnOverriddenKey } from "./overridden.js";
+import { ColumnFilteredId, ColumnFilteredKey, FilteredPColumnId } from "./filtered_column.js";
 import { AnchoredPColumnId } from "./selectors.js";
-import { PObjectId } from "../../../pool/spec.js";
+import { GlobalPObjectId, GlobalPObjectKey, LocalPObjectId, LocalPObjectKey, PObjectId } from "../../../pool/spec.js";
 //#region src/drivers/pframe/spec/ids.d.ts
+/**
+ * Per-axis patches keyed by positional index in the base spec's `axesSpec`.
+ *
+ * Using position rather than `name` lets us disambiguate linker-style specs
+ * that carry multiple axes with the same `name` differentiated by `domain` /
+ * `contextDomain` (e.g. a `group`, `group/primary`, `group/secondary` triple).
+ *
+ * A patch at index `>= base.axesSpec.length` appends a new axis at that slot.
+ */
+type AxisPatches = Record<number, Partial<AxisSpec>>;
 /**
  * Universal column identifier optionally anchored and optionally filtered.
+ * @deprecated use {@link ColumnUniversalKey}
  */
-type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId | DiscoveredPColumn;
+type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId;
 /**
  * Canonically serialized {@link UniversalPColumnId}.
+ * @deprecated use {@link ColumnUniversalId}
+ */
+type SUniversalPColumnId = ColumnUniversalId;
+type ColumnUniversalKey = LocalPObjectKey | GlobalPObjectKey | ColumnFilteredKey | ColumnDiscoveredKey | ColumnOverriddenKey;
+type ColumnUniversalId = LocalPObjectId | GlobalPObjectId | ColumnFilteredId | ColumnDiscoveredId | ColumnOverriddenId;
+/**
+ * Canonically serializes a column key to a branded string id. Accepts both
+ * the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}
+ * (anchored / old filtered object form).
+ */
+declare function stringifyColumnId(id: ColumnUniversalKey | UniversalPColumnId): ColumnUniversalId;
+/**
+ * Parses a canonically serialized column id back to its key form.
  */
-type SUniversalPColumnId = Branded<PObjectId, "SUniversalPColumnId", "__pl_model_brand_2__">;
+declare function parseColumnId(str: ColumnUniversalId): ColumnUniversalKey;
+declare function parseColumnIdSafely(str: ColumnUniversalId, fallback?: undefined): ColumnUniversalKey | typeof fallback;
 /**
- * Canonically serializes a {@link UniversalPColumnId} to a string.
- * @param id - The column identifier to serialize
- * @returns The canonically serialized string
+ * Walk a rich column id down to its terminal leaf {@link PObjectId}.
  */
-declare function stringifyColumnId(id: UniversalPColumnId): SUniversalPColumnId;
+declare function extractPObjectId(id: ColumnUniversalId | ColumnUniversalKey): PObjectId;
 /**
- * Parses a canonically serialized {@link UniversalPColumnId} from a string.
- * @param str - The string to parse
- * @returns The parsed column identifier
+ * Reconstruct the effective {@link PColumnSpec} for a rich column id by walking
+ * the id chain from leaf to outermost wrapper, applying each layer's spec
+ * transformation in the same order the corresponding recipe would.
+ *
+ * Layer semantics:
+ * - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.
+ * - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.
+ * - {@link ColumnFilteredKey}: drops the axes whose positional index appears in
+ *   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors
+ *   `ColumnFilteredRecipe.getSpec()`.
+ * - {@link ColumnOverriddenKey}: applies `specOverrides` via
+ *   {@link applySpecOverrides} on top of the inner spec.
  */
-declare function parseColumnId(str: SUniversalPColumnId): UniversalPColumnId;
+declare function reconstructSpecFromId(baseSpec: PColumnSpec, id: ColumnUniversalId | ColumnUniversalKey): PColumnSpec;
 //#endregion
-export { SUniversalPColumnId, UniversalPColumnId, parseColumnId, stringifyColumnId };
+export { AxisPatches, ColumnUniversalId, ColumnUniversalKey, SUniversalPColumnId, UniversalPColumnId, extractPObjectId, parseColumnId, parseColumnIdSafely, reconstructSpecFromId, stringifyColumnId };
 //# sourceMappingURL=ids.d.ts.map

package/dist/drivers/pframe/spec/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"mappings":";;;;;;;;;KAUY,kBAAA,GAAqB,iBAAA,GAAoB,iBAAA,GAAoB,iBAAA;;;;KAK7D,mBAAA,GAAsB,OAAO,CAAC,SAAA;;;;;;iBAO1B,iBAAA,CAAkB,EAAA,EAAI,kBAAA,GAAqB,mBAAmB;;AAZY;AAK1F;;;iBAgBgB,aAAA,CAAc,GAAA,EAAK,mBAAA,GAAsB,kBAAkB"}
+{"version":3,"file":"ids.d.ts","names":[],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"mappings":";;;;;;;;;;AA2CA;;;;;;KAAY,WAAA,GAAc,MAAA,SAAe,OAAA,CAAQ,QAAA;;;;;KAMrC,kBAAA,GAAqB,iBAAA,GAAoB,iBAAiB;AANb;AAMzD;;;AANyD,KAY7C,mBAAA,GAAsB,iBAAiB;AAAA,KAGvC,kBAAA,GACR,eAAA,GACA,gBAAA,GACA,iBAAA,GACA,mBAAA,GACA,mBAAA;AAAA,KAEQ,iBAAA,GACR,cAAA,GACA,eAAA,GACA,gBAAA,GACA,kBAAA,GACA,kBAAA;;;;AAf+C;AAGnD;iBAmBgB,iBAAA,CAAkB,EAAA,EAAI,kBAAA,GAAqB,kBAAA,GAAqB,iBAAA;;;;iBAOhE,aAAA,CAAc,GAAA,EAAK,iBAAA,GAAoB,kBAAkB;AAAA,iBAIzD,mBAAA,CACd,GAAA,EAAK,iBAAA,EACL,QAAA,eACC,kBAAA,UAA4B,QAAA;;;;iBAWf,gBAAA,CAAiB,EAAA,EAAI,iBAAA,GAAoB,kBAAA,GAAqB,SAAA;;;;;;AAvCvD;AAEvB;;;;;;;;iBAqEgB,qBAAA,CACd,QAAA,EAAU,WAAA,EACV,EAAA,EAAI,iBAAA,GAAoB,kBAAA,GACvB,WAAA"}

package/dist/drivers/pframe/spec/ids.js

@@ -1,22 +1,73 @@
-import canonicalize from "canonicalize";
+import { canonicalizeJson } from "../../../json.js";
+import { applyAxisFilters, isColumnFilteredKey } from "./filtered_column.js";
+import { createPObjectId, isPObjectId, isPObjectKey } from "../../../pool/spec.js";
+import "../../../pool/index.js";
+import { isColumnDiscoveredKey } from "./discovered_column.js";
+import { applySpecOverrides, isColumnOverriddenKey } from "./overridden.js";
+import { throwError } from "@milaboratories/helpers";
+import { isString } from "es-toolkit";
 //#region src/drivers/pframe/spec/ids.ts
 /**
-* Canonically serializes a {@link UniversalPColumnId} to a string.
-* @param id - The column identifier to serialize
-* @returns The canonically serialized string
+* Canonically serializes a column key to a branded string id. Accepts both
+* the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}
+* (anchored / old filtered object form).
 */
 function stringifyColumnId(id) {
-	return canonicalize(id);
+	return canonicalizeJson(id);
 }
 /**
-* Parses a canonically serialized {@link UniversalPColumnId} from a string.
-* @param str - The string to parse
-* @returns The parsed column identifier
+* Parses a canonically serialized column id back to its key form.
 */
 function parseColumnId(str) {
 	return JSON.parse(str);
 }
+function parseColumnIdSafely(str, fallback = void 0) {
+	try {
+		return JSON.parse(str);
+	} catch {
+		return fallback;
+	}
+}
+/**
+* Walk a rich column id down to its terminal leaf {@link PObjectId}.
+*/
+function extractPObjectId(id) {
+	if (isString(id)) {
+		if (isPObjectId(id)) return id;
+		return extractPObjectId(parseColumnIdSafely(id) ?? throwError(`extractPObjectId: id "${id}" is not a valid canonical column id`));
+	}
+	if (isPObjectKey(id)) return createPObjectId(id);
+	if (isColumnFilteredKey(id)) return extractPObjectId(id.source);
+	if (isColumnOverriddenKey(id)) return extractPObjectId(id.source);
+	if (isColumnDiscoveredKey(id)) return extractPObjectId(id.column);
+	throw new Error(`extractPObjectId: unrecognized column id structure: ${JSON.stringify(id)}`);
+}
+/**
+* Reconstruct the effective {@link PColumnSpec} for a rich column id by walking
+* the id chain from leaf to outermost wrapper, applying each layer's spec
+* transformation in the same order the corresponding recipe would.
+*
+* Layer semantics:
+* - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.
+* - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.
+* - {@link ColumnFilteredKey}: drops the axes whose positional index appears in
+*   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors
+*   `ColumnFilteredRecipe.getSpec()`.
+* - {@link ColumnOverriddenKey}: applies `specOverrides` via
+*   {@link applySpecOverrides} on top of the inner spec.
+*/
+function reconstructSpecFromId(baseSpec, id) {
+	if (isString(id)) {
+		if (isPObjectId(id)) return baseSpec;
+		return reconstructSpecFromId(baseSpec, parseColumnIdSafely(id) ?? throwError(`reconstructSpecFromId: id "${id}" is not a valid canonical column id`));
+	}
+	if (isPObjectKey(id)) return baseSpec;
+	if (isColumnDiscoveredKey(id)) return reconstructSpecFromId(baseSpec, id.column);
+	if (isColumnFilteredKey(id)) return applyAxisFilters(reconstructSpecFromId(baseSpec, id.source), id.axisFilters);
+	if (isColumnOverriddenKey(id)) return applySpecOverrides(reconstructSpecFromId(baseSpec, id.source), id.specOverrides);
+	throw new Error(`reconstructSpecFromId: unrecognized column id structure: ${JSON.stringify(id)}`);
+}
 //#endregion
-export { parseColumnId, stringifyColumnId };
+export { extractPObjectId, parseColumnId, parseColumnIdSafely, reconstructSpecFromId, stringifyColumnId };
 
 //# sourceMappingURL=ids.js.map

package/dist/drivers/pframe/spec/ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"ids.js","names":[],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"sourcesContent":["import type { Branded } from \"../../../branding\";\nimport type { AnchoredPColumnId } from \"./selectors\";\nimport type { FilteredPColumnId } from \"./filtered_column\";\nimport canonicalize from \"canonicalize\";\nimport type { PObjectId } from \"../../../pool\";\nimport { DiscoveredPColumn } from \"./discovered_column\";\n\n/**\n * Universal column identifier optionally anchored and optionally filtered.\n */\nexport type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId | DiscoveredPColumn;\n\n/**\n * Canonically serialized {@link UniversalPColumnId}.\n */\nexport type SUniversalPColumnId = Branded<PObjectId, \"SUniversalPColumnId\", \"__pl_model_brand_2__\">;\n\n/**\n * Canonically serializes a {@link UniversalPColumnId} to a string.\n * @param id - The column identifier to serialize\n * @returns The canonically serialized string\n */\nexport function stringifyColumnId(id: UniversalPColumnId): SUniversalPColumnId {\n  return canonicalize(id)! as SUniversalPColumnId;\n}\n\n/**\n * Parses a canonically serialized {@link UniversalPColumnId} from a string.\n * @param str - The string to parse\n * @returns The parsed column identifier\n */\nexport function parseColumnId(str: SUniversalPColumnId): UniversalPColumnId {\n  return JSON.parse(str) as UniversalPColumnId;\n}\n"],"mappings":";;;;;;;AAsBA,SAAgB,kBAAkB,IAA6C;CAC7E,OAAO,aAAa,EAAE;AACxB;;;;;;AAOA,SAAgB,cAAc,KAA8C;CAC1E,OAAO,KAAK,MAAM,GAAG;AACvB"}
+{"version":3,"file":"ids.js","names":[],"sources":["../../../../src/drivers/pframe/spec/ids.ts"],"sourcesContent":["import type { AnchoredPColumnId } from \"./selectors\";\nimport {\n  applyAxisFilters,\n  isColumnFilteredKey,\n  type ColumnFilteredId,\n  type ColumnFilteredKey,\n  type FilteredPColumnId,\n} from \"./filtered_column\";\nimport {\n  createPObjectId,\n  isPObjectId,\n  isPObjectKey,\n  LocalPObjectKey,\n  type GlobalPObjectId,\n  type GlobalPObjectKey,\n  type LocalPObjectId,\n  type PObjectId,\n} from \"../../../pool\";\nimport {\n  isColumnDiscoveredKey,\n  type ColumnDiscoveredId,\n  type ColumnDiscoveredKey,\n} from \"./discovered_column\";\nimport { throwError } from \"@milaboratories/helpers\";\nimport {\n  applySpecOverrides,\n  isColumnOverriddenKey,\n  type ColumnOverriddenId,\n  type ColumnOverriddenKey,\n} from \"./overridden\";\nimport { canonicalizeJson } from \"../../../json\";\nimport { AxisSpec, PColumnSpec } from \"./spec\";\nimport { isString } from \"es-toolkit\";\n\n/**\n * Per-axis patches keyed by positional index in the base spec's `axesSpec`.\n *\n * Using position rather than `name` lets us disambiguate linker-style specs\n * that carry multiple axes with the same `name` differentiated by `domain` /\n * `contextDomain` (e.g. a `group`, `group/primary`, `group/secondary` triple).\n *\n * A patch at index `>= base.axesSpec.length` appends a new axis at that slot.\n */\nexport type AxisPatches = Record<number, Partial<AxisSpec>>;\n\n/**\n * Universal column identifier optionally anchored and optionally filtered.\n * @deprecated use {@link ColumnUniversalKey}\n */\nexport type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId;\n\n/**\n * Canonically serialized {@link UniversalPColumnId}.\n * @deprecated use {@link ColumnUniversalId}\n */\nexport type SUniversalPColumnId = ColumnUniversalId;\n// export type SUniversalPColumnId = Branded<PObjectId, \"SUniversalPColumnId\", \"__pl_model_brand_2__\">;\n\nexport type ColumnUniversalKey =\n  | LocalPObjectKey\n  | GlobalPObjectKey\n  | ColumnFilteredKey\n  | ColumnDiscoveredKey\n  | ColumnOverriddenKey;\n\nexport type ColumnUniversalId =\n  | LocalPObjectId\n  | GlobalPObjectId\n  | ColumnFilteredId\n  | ColumnDiscoveredId\n  | ColumnOverriddenId;\n\n/**\n * Canonically serializes a column key to a branded string id. Accepts both\n * the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}\n * (anchored / old filtered object form).\n */\nexport function stringifyColumnId(id: ColumnUniversalKey | UniversalPColumnId): ColumnUniversalId {\n  return canonicalizeJson(id) as ColumnUniversalId;\n}\n\n/**\n * Parses a canonically serialized column id back to its key form.\n */\nexport function parseColumnId(str: ColumnUniversalId): ColumnUniversalKey {\n  return JSON.parse(str) as ColumnUniversalKey;\n}\n\nexport function parseColumnIdSafely(\n  str: ColumnUniversalId,\n  fallback = undefined,\n): ColumnUniversalKey | typeof fallback {\n  try {\n    return JSON.parse(str) as ColumnUniversalKey;\n  } catch {\n    return fallback;\n  }\n}\n\n/**\n * Walk a rich column id down to its terminal leaf {@link PObjectId}.\n */\nexport function extractPObjectId(id: ColumnUniversalId | ColumnUniversalKey): PObjectId {\n  if (isString(id)) {\n    if (isPObjectId(id)) return id;\n\n    const parsed =\n      parseColumnIdSafely(id) ??\n      throwError(`extractPObjectId: id \"${id}\" is not a valid canonical column id`);\n    return extractPObjectId(parsed);\n  }\n\n  if (isPObjectKey(id)) return createPObjectId(id);\n  if (isColumnFilteredKey(id)) return extractPObjectId(id.source);\n  if (isColumnOverriddenKey(id)) return extractPObjectId(id.source);\n  if (isColumnDiscoveredKey(id)) return extractPObjectId(id.column);\n\n  throw new Error(`extractPObjectId: unrecognized column id structure: ${JSON.stringify(id)}`);\n}\n\n/**\n * Reconstruct the effective {@link PColumnSpec} for a rich column id by walking\n * the id chain from leaf to outermost wrapper, applying each layer's spec\n * transformation in the same order the corresponding recipe would.\n *\n * Layer semantics:\n * - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.\n * - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.\n * - {@link ColumnFilteredKey}: drops the axes whose positional index appears in\n *   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors\n *   `ColumnFilteredRecipe.getSpec()`.\n * - {@link ColumnOverriddenKey}: applies `specOverrides` via\n *   {@link applySpecOverrides} on top of the inner spec.\n */\nexport function reconstructSpecFromId(\n  baseSpec: PColumnSpec,\n  id: ColumnUniversalId | ColumnUniversalKey,\n): PColumnSpec {\n  if (isString(id)) {\n    if (isPObjectId(id)) return baseSpec;\n\n    const parsed =\n      parseColumnIdSafely(id) ??\n      throwError(`reconstructSpecFromId: id \"${id}\" is not a valid canonical column id`);\n    return reconstructSpecFromId(baseSpec, parsed);\n  }\n\n  if (isPObjectKey(id)) return baseSpec;\n  if (isColumnDiscoveredKey(id)) return reconstructSpecFromId(baseSpec, id.column);\n  if (isColumnFilteredKey(id)) {\n    return applyAxisFilters(reconstructSpecFromId(baseSpec, id.source), id.axisFilters);\n  }\n  if (isColumnOverriddenKey(id)) {\n    const inner = reconstructSpecFromId(baseSpec, id.source);\n    return applySpecOverrides(inner, id.specOverrides);\n  }\n\n  throw new Error(`reconstructSpecFromId: unrecognized column id structure: ${JSON.stringify(id)}`);\n}\n"],"mappings":";;;;;;;;;;;;;;AA6EA,SAAgB,kBAAkB,IAAgE;CAChG,OAAO,iBAAiB,EAAE;AAC5B;;;;AAKA,SAAgB,cAAc,KAA4C;CACxE,OAAO,KAAK,MAAM,GAAG;AACvB;AAEA,SAAgB,oBACd,KACA,WAAW,KAAA,GAC2B;CACtC,IAAI;EACF,OAAO,KAAK,MAAM,GAAG;CACvB,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,SAAgB,iBAAiB,IAAuD;CACtF,IAAI,SAAS,EAAE,GAAG;EAChB,IAAI,YAAY,EAAE,GAAG,OAAO;EAK5B,OAAO,iBAFL,oBAAoB,EAAE,KACtB,WAAW,yBAAyB,GAAG,qCAAqC,CAChD;CAChC;CAEA,IAAI,aAAa,EAAE,GAAG,OAAO,gBAAgB,EAAE;CAC/C,IAAI,oBAAoB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAC9D,IAAI,sBAAsB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAChE,IAAI,sBAAsB,EAAE,GAAG,OAAO,iBAAiB,GAAG,MAAM;CAEhE,MAAM,IAAI,MAAM,uDAAuD,KAAK,UAAU,EAAE,GAAG;AAC7F;;;;;;;;;;;;;;;AAgBA,SAAgB,sBACd,UACA,IACa;CACb,IAAI,SAAS,EAAE,GAAG;EAChB,IAAI,YAAY,EAAE,GAAG,OAAO;EAK5B,OAAO,sBAAsB,UAF3B,oBAAoB,EAAE,KACtB,WAAW,8BAA8B,GAAG,qCAAqC,CACtC;CAC/C;CAEA,IAAI,aAAa,EAAE,GAAG,OAAO;CAC7B,IAAI,sBAAsB,EAAE,GAAG,OAAO,sBAAsB,UAAU,GAAG,MAAM;CAC/E,IAAI,oBAAoB,EAAE,GACxB,OAAO,iBAAiB,sBAAsB,UAAU,GAAG,MAAM,GAAG,GAAG,WAAW;CAEpF,IAAI,sBAAsB,EAAE,GAE1B,OAAO,mBADO,sBAAsB,UAAU,GAAG,MACnB,GAAG,GAAG,aAAa;CAGnD,MAAM,IAAI,MAAM,4DAA4D,KAAK,UAAU,EAAE,GAAG;AAClG"}