@milaboratories/pl-model-common 1.26.0 → 1.27.0

package/src/drivers/pframe/linker_columns.test.ts

@@ -98,7 +98,7 @@ describe("Linker columns", () => {
       expect(linkers.map((item) => item.spec.name).sort()).toEqual(params.expected);
     };
 
-    testCase({ from: [axis2], to: [axis3], expected: ["c12", "c13"] });
+    testCase({ from: [axis2], to: [axis3], expected: [] });
     testCase({ from: [axis1], to: [axis2], expected: ["c12"] });
     testCase({ from: [axis1], to: [axis4], expected: [] });
   });
@@ -239,11 +239,13 @@ describe("Linker columns", () => {
 
     const linkersMap = LinkerMap.fromColumns([linker1, linker2]);
 
+    // Forward-only: from group2 we only reach group3 (no back edge to group1)
     expect(
       new Set(
         linkersMap.getReachableByLinkersAxesFromAxesNormalized(group2Normalized).map((a) => a.name),
       ),
-    ).toEqual(new Set([...group1, ...group3].map((a) => a.name)));
+    ).toEqual(new Set([...group3].map((a) => a.name)));
+    // Non-root axes (axisDn, axisBn) don't match linker map keys, so no forward reachability
     expect(linkersMap.getReachableByLinkersAxesFromAxesNormalized([axisDn])).toEqual([]);
     expect(linkersMap.getReachableByLinkersAxesFromAxesNormalized([axisBn])).toEqual([]);
   });
@@ -282,7 +284,7 @@ describe("Linker columns", () => {
           getNormalizedAxesList([axisA, axisB, axisC, axisE]),
         )
         .map((v) => v.name),
-    ).toEqual(["a", "b", "e"]);
+    ).toEqual(["a", "b", "c", "e"]);
 
     expect(
       linkerMap
@@ -290,4 +292,21 @@ describe("Linker columns", () => {
         .map((v) => v.name),
     ).toEqual(["a", "b", "c", "e"]);
   });
+
+  test("getReachableByLinkersAxesFromAxes", () => {
+    const axisA = makeTestAxis({ name: "a" });
+    const axisB = makeTestAxis({ name: "b" });
+    const axisC = makeTestAxis({ name: "c" });
+    const axisD = makeTestAxis({ name: "d" });
+    const linkerMap = LinkerMap.fromColumns([
+      makeLinkerColumn({ name: "linker1", from: [axisA], to: [axisB] }),
+      makeLinkerColumn({ name: "linker2", from: [axisB], to: [axisC] }),
+      makeLinkerColumn({ name: "linker3", from: [axisC], to: [axisD] }),
+    ]);
+
+    expect(linkerMap.getReachableByLinkersAxesFromAxes([axisA])).toEqual(
+      getNormalizedAxesList([axisB, axisC, axisD]),
+    );
+    expect(linkerMap.getReachableByLinkersAxesFromAxes([axisD])).toEqual([]);
+  });
 });

package/src/drivers/pframe/linker_columns.ts

@@ -89,7 +89,6 @@ export class LinkerMap implements LinkersData {
       for (const [keyLeft] of leftKeyVariants) {
         for (const [keyRight] of rightKeyVariants) {
           result.get(keyLeft)?.linkWith.set(keyRight, linker);
-          result.get(keyRight)?.linkWith.set(keyLeft, linker);
         }
       }
     }
@@ -138,7 +137,8 @@ export class LinkerMap implements LinkersData {
               current = previous[current];
             }
             ids.push(current);
-            return ids.map((id: LinkerKey) => this.data.get(id)!.linkWith.get(previous[id])!);
+            // Edge (previous[id] -> id) is stored at the "from" node in one-directional map
+            return ids.map((id: LinkerKey) => this.data.get(previous[id])!.linkWith.get(id)!);
           } else if (!visited.has(availableId)) {
             next.add(availableId);
             visited.add(availableId);

package/src/drivers/pframe/spec/anchored.ts

@@ -8,7 +8,7 @@ import type {
   AnchorAxisRefByIdx,
   AnchoredPColumnId,
   AnchoredPColumnSelector,
-  AxisSelector,
+  LegacyAxisSelector,
   PColumnSelector,
 } from "./selectors";
 import type { AxisId, PColumnSpec } from "./spec";
@@ -323,7 +323,7 @@ export function resolveAnchors(
 function resolveAxisReference(
   anchors: Record<string, PColumnSpec>,
   axisRef: AAxisSelector,
-): AxisSelector {
+): LegacyAxisSelector {
   if (!isAnchorAxisRef(axisRef)) return axisRef;
 
   // It's an anchored reference

package/src/drivers/pframe/spec/selectors.ts

@@ -12,8 +12,14 @@ import { getAxisId } from "./spec";
  *
  * This interface is used in various selection and matching operations
  * throughout the PFrame system, such as column queries and axis lookups.
+ *
+ * @deprecated This selector is part of the legacy column matching API.
+ * The new Columns API (see sdk/model/src/columns/) now handles column and axis
+ * selection via {@link AxisSelector} and {@link ColumnSelector}, providing
+ * stricter matching semantics (StringMatcher-based) and a unified approach
+ * to working with columns, including domain and annotation matching.
  */
-export interface AxisSelector {
+export interface LegacyAxisSelector {
   /**
    * Optional value type to match against.
    * When specified, only axes with this exact type will match.
@@ -94,7 +100,7 @@ export type ADomain = string | AnchorDomainRef;
  * Axis identifier that can be either a direct AxisId or a reference to an axis through an anchor
  * Allows referring to axes in a way that can be resolved in different contexts
  */
-export type AAxisSelector = AxisSelector | AnchorAxisRef;
+export type AAxisSelector = LegacyAxisSelector | AnchorAxisRef;
 
 /**
  * Match resolution strategy for PColumns
@@ -144,7 +150,7 @@ export interface PColumnSelector extends AnchoredPColumnSelector {
   domain?: Record<string, string>;
   contextDomainAnchor?: never;
   contextDomain?: Record<string, string>;
-  axes?: AxisSelector[];
+  axes?: LegacyAxisSelector[];
 }
 
 /**
@@ -187,7 +193,7 @@ export function isAnchoredPColumnId(id: unknown): id is AnchoredPColumnId {
  * @param axis - The AxisId to check against the selector
  * @returns true if the AxisId matches all specified criteria in the selector, false otherwise
  */
-export function matchAxis(selector: AxisSelector, axis: AxisId): boolean {
+export function matchAxis(selector: LegacyAxisSelector, axis: AxisId): boolean {
   // Match name if specified
   if (selector.name !== undefined && selector.name !== axis.name) return false;
 
@@ -298,7 +304,7 @@ export function matchPColumn(pcolumn: PColumnSpec, selector: PColumnSelector): b
  *                              or an array of PColumnSelectors, or a single PColumnSelector
  * @returns A function that takes a PColumnSpec and returns a boolean
  */
-export function selectorsToPredicate(
+export function legacyColumnSelectorsToPredicate(
   predicateOrSelectors: PColumnSelector | PColumnSelector[],
 ): (spec: PObjectSpec) => boolean {
   if (Array.isArray(predicateOrSelectors))

package/src/drivers/pframe/type_util.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 export type AddParameters<
   TParameters extends [...args: any],
   TFunction extends (...args: any) => any,

package/src/drivers/pspec.ts

@@ -0,0 +1,143 @@
+import type { Branded } from "@milaboratories/helpers";
+import type {
+  ValueType,
+  SingleAxisSelector,
+  AxisSpec,
+  PColumnIdAndSpec,
+  PColumnSpec,
+} from "./pframe";
+
+// --- Discover columns types (duplicated from middle-layer internal_api) ---
+
+/** Matches a string value either exactly or by regex pattern */
+export type StringMatcher = { type: "exact"; value: string } | { type: "regex"; value: string };
+
+/** Map of key to array of string matchers (OR-ed per key, AND-ed across keys) */
+export type MatcherMap = Record<string, StringMatcher[]>;
+
+/** Selector for matching axes by various criteria */
+export interface MultiAxisSelector {
+  /** Match any of the axis types listed here */
+  readonly type?: ValueType[];
+  /** Match any of the axis names listed here */
+  readonly name?: StringMatcher[];
+  /** Match requires all the domains listed here */
+  readonly domain?: MatcherMap;
+  /** Match requires all the context domains listed here */
+  readonly contextDomain?: MatcherMap;
+  /** Match requires all the annotations listed here */
+  readonly annotations?: MatcherMap;
+}
+
+/** Column selector for discover columns request, matching columns by various criteria.
+ * Multiple selectors are OR-ed: a column matches if it satisfies any selector. */
+export interface MultiColumnSelector {
+  /** Match any of the value types listed here */
+  readonly type?: ValueType[];
+  /** Match any of the names listed here */
+  readonly name?: StringMatcher[];
+  /** Match requires all the domains listed here */
+  readonly domain?: MatcherMap;
+  /** Match requires all the context domains listed here */
+  readonly contextDomain?: MatcherMap;
+  /** Match requires all the annotations listed here */
+  readonly annotations?: MatcherMap;
+  /** Match any of the axis selectors listed here */
+  readonly axes?: MultiAxisSelector[];
+  /** When true (default), allows matching if only a subset of axes match */
+  readonly partialAxesMatch?: boolean;
+}
+
+/** Qualification applied to a single axis to make it compatible during integration. */
+export interface AxisQualification {
+  /** Axis selector identifying which axis is qualified. */
+  readonly axis: SingleAxisSelector;
+  /** Additional context domain entries applied to the axis. */
+  readonly contextDomain: Record<string, string>;
+}
+
+/** Qualifications needed for both query (already-integrated) columns and the hit column. */
+export interface ColumnAxesWithQualifications {
+  /** Already integrated (query) columns with their qualifications. */
+  axesSpec: AxisSpec[];
+  /** Qualifications for each already integrated (query) column. */
+  qualifications: AxisQualification[];
+}
+
+/** Fine-grained constraints controlling axes matching and qualification behavior */
+export interface DiscoverColumnsConstraints {
+  /** Allow source (query) axes that have no match in the hit column */
+  allowFloatingSourceAxes: boolean;
+  /** Allow hit column axes that have no match in the source (query) */
+  allowFloatingHitAxes: boolean;
+  /** Allow source (query) axes to be qualified (contextDomain extended) */
+  allowSourceQualifications: boolean;
+  /** Allow hit column axes to be qualified (contextDomain extended) */
+  allowHitQualifications: boolean;
+}
+
+/** Request for discovering columns compatible with a given axes integration */
+export interface DiscoverColumnsRequest {
+  /** Column filters (OR-ed); empty array matches all columns */
+  columnFilter?: MultiColumnSelector[];
+  /** Already integrated axes with qualifications */
+  axes: ColumnAxesWithQualifications[];
+  /** Constraints controlling axes matching and qualification behavior */
+  constraints: DiscoverColumnsConstraints;
+}
+
+/** Qualifications info for a discover columns response mapping variant */
+export interface DiscoverColumnsResponseQualifications {
+  /** Qualifications for each query (already-integrated) column set */
+  forQueries: AxisQualification[][];
+  /** Qualifications for the hit column */
+  forHit: AxisQualification[];
+}
+
+/** A single mapping variant describing how a hit column can be integrated */
+export interface DiscoverColumnsMappingVariant {
+  /** Full qualifications needed for integration */
+  qualifications: DiscoverColumnsResponseQualifications;
+  /** Distinctive (minimal) qualifications needed for integration */
+  distinctiveQualifications: DiscoverColumnsResponseQualifications;
+}
+
+/** A single hit in the discover columns response */
+export interface DiscoverColumnsResponseHit {
+  /** The column that was found compatible */
+  hit: PColumnIdAndSpec;
+  /** Possible ways to integrate this column with the existing set */
+  mappingVariants: DiscoverColumnsMappingVariant[];
+}
+
+/** Response from discover columns */
+export interface DiscoverColumnsResponse {
+  /** Columns that could be integrated and possible ways to integrate them */
+  hits: DiscoverColumnsResponseHit[];
+}
+
+// --- Spec driver ---
+
+/** Handle to a spec-only PFrame (no data, synchronous operations). */
+export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
+
+/**
+ * Synchronous driver for spec-level PFrame operations.
+ *
+ * Unlike the async PFrameDriver (which works with data), this driver
+ * operates on column specifications only. All methods are synchronous
+ * because the underlying WASM PFrame computes results immediately.
+ */
+export interface PSpecDriver {
+  /** Create a spec-only PFrame from column specs. Returns a handle. */
+  createSpecFrame(specs: Record<string, PColumnSpec>): SpecFrameHandle;
+
+  /** Discover columns compatible with given axes integration. */
+  specFrameDiscoverColumns(
+    handle: SpecFrameHandle,
+    request: DiscoverColumnsRequest,
+  ): DiscoverColumnsResponse;
+
+  /** Dispose a spec frame, freeing WASM resources. */
+  disposeSpecFrame(handle: SpecFrameHandle): void;
+}

package/src/index.ts

@@ -17,3 +17,4 @@ export * from "./value_or_error";
 export * from "./base64";
 export * from "./util";
 export * from "./httpAuth";
+export * from "./resource_types";

package/src/resource_types.ts

@@ -0,0 +1,47 @@
+/** Well-known resource type names used across the platform. */
+export const ResourceTypeName = {
+  StreamManager: "StreamManager",
+  StdMap: "StdMap",
+  StdMapSlash: "std/map",
+  EphStdMap: "EphStdMap",
+  PFrame: "PFrame",
+  ParquetChunk: "ParquetChunk",
+  BContext: "BContext",
+  BlockPackCustom: "BlockPackCustom",
+  BinaryMap: "BinaryMap",
+  BinaryValue: "BinaryValue",
+  BlobMap: "BlobMap",
+  BResolveSingle: "BResolveSingle",
+  BResolveSingleNoResult: "BResolveSingleNoResult",
+  BQueryResult: "BQueryResult",
+  TengoTemplate: "TengoTemplate",
+  TengoLib: "TengoLib",
+  SoftwareInfo: "SoftwareInfo",
+  Dummy: "Dummy",
+  JsonResourceError: "json/resourceError",
+  JsonObject: "json/object",
+  JsonGzObject: "json-gz/object",
+  JsonString: "json/string",
+  JsonArray: "json/array",
+  JsonNumber: "json/number",
+  BContextEnd: "BContextEnd",
+  FrontendFromUrl: "Frontend/FromUrl",
+  FrontendFromFolder: "Frontend/FromFolder",
+  BObjectSpec: "BObjectSpec",
+  Blob: "Blob",
+  Null: "Null",
+  Binary: "binary",
+  LSProvider: "LSProvider",
+  UserProject: "UserProject",
+  Projects: "Projects",
+  ClientRoot: "ClientRoot",
+} as const;
+
+/** Resource type name prefix constants. */
+export const ResourceTypePrefix = {
+  Blob: "Blob/",
+  BlobUpload: "BlobUpload/",
+  BlobIndex: "BlobIndex/",
+  PColumnData: "PColumnData/",
+  StreamWorkdir: "StreamWorkdir/",
+} as const;