@milaboratories/pl-model-common 1.23.0 → 1.24.1

package/src/block_state.ts

@@ -31,3 +31,20 @@ export type BlockState<
 
   readonly author: AuthorMarker | undefined;
 };
+
+export type BlockStateV3<
+  Outputs extends BlockOutputsBase = BlockOutputsBase,
+  _Data = unknown,
+  Href extends `/${string}` = `/${string}`,
+> = {
+  /** Block storage persisted in the block state */
+  blockStorage: unknown;
+
+  /** Outputs rendered with block config */
+  outputs: Outputs;
+
+  /** Current navigation state */
+  navigationState: NavigationState<Href>;
+
+  readonly author: AuthorMarker | undefined;
+};

package/src/bmodel/block_config.ts

@@ -4,6 +4,86 @@ import type { BlockCodeFeatureFlags } from '../flags';
 import type { BlockCodeWithInfo, Code } from './code';
 import type { BlockRenderingMode } from './types';
 
+/**
+ * Descriptor for a state migration function.
+ * Unlike ConfigRenderLambda, migrations are not rendered reactively -
+ * they are one-time synchronous transformations called during block pack updates.
+ */
+export type MigrationDescriptor = {
+  /** Index of this migration in the migrations callback array */
+  readonly index: number;
+};
+
+/**
+ * BroadActiveHandleDescriptor = TypedConfigOrConfigLambda,
+ * NarrowActiveHandleDescriptor = ConfigRenderLambda
+ */
+export type BlockConfigV4Generic<
+  _Args = unknown,
+  _Data extends Record<string, unknown> = Record<string, unknown>,
+  BroadActiveHandleDescriptor = unknown,
+  NarrowActiveHandleDescriptor extends BroadActiveHandleDescriptor = BroadActiveHandleDescriptor,
+  Outputs extends Record<string, BroadActiveHandleDescriptor> = Record<string, BroadActiveHandleDescriptor>,
+> = {
+  /** Discriminator to identify config version */
+  readonly configVersion: 4;
+
+  readonly modelAPIVersion: 2;
+
+  /** SDK version used by the block */
+  readonly sdkVersion: string;
+
+  /** Main rendering mode for the block */
+  readonly renderingMode: BlockRenderingMode;
+
+  /** Lambda to derive block args from state */
+  readonly args: NarrowActiveHandleDescriptor;
+
+  /**
+   * Lambda to derive prerun args from state (optional).
+   * If not defined, defaults to using the args() result.
+   * Used for staging/prerun phase.
+   */
+  readonly prerunArgs?: NarrowActiveHandleDescriptor;
+
+  /** Lambda to get initial data when block is added to the project */
+  readonly initialData: NarrowActiveHandleDescriptor;
+
+  /** Lambda to derive list of sections for the left overview panel */
+  readonly sections: NarrowActiveHandleDescriptor;
+
+  /** Lambda to derive block title */
+  readonly title?: NarrowActiveHandleDescriptor;
+
+  /** Lambda to derive block subtitle, shown below the title */
+  readonly subtitle?: NarrowActiveHandleDescriptor;
+
+  /** Lambda returning array of tags for search functionality */
+  readonly tags?: BroadActiveHandleDescriptor;
+
+  /**
+   * Lambda returning list of upstream blocks this block enriches with its exports,
+   * influences dependency graph construction
+   * */
+  readonly enrichmentTargets?: NarrowActiveHandleDescriptor;
+
+  /** Configuration for the output cells */
+  readonly outputs: Outputs;
+
+  /**
+   * Array of migration descriptors for state version upgrades.
+   * Each migration transforms state from version N to N+1.
+   * Migrations are NOT rendered reactively - they run synchronously during block pack updates.
+   */
+  readonly migrations?: MigrationDescriptor[];
+
+  /** Config code bundle */
+  readonly code?: Code;
+
+  /** Feature flags for the block Model and UI code. */
+  readonly featureFlags?: BlockCodeFeatureFlags;
+};
+
 /**
  * BroadActiveHandleDescriptor = TypedConfigOrConfigLambda,
  * NarrowActiveHandleDescriptor = ConfigRenderLambda
@@ -15,6 +95,11 @@ export type BlockConfigV3Generic<
   NarrowActiveHandleDescriptor extends BroadActiveHandleDescriptor = BroadActiveHandleDescriptor,
   Outputs extends Record<string, BroadActiveHandleDescriptor> = Record<string, BroadActiveHandleDescriptor>,
 > = {
+  /** Discriminator to identify config version */
+  readonly configVersion: 3;
+
+  readonly modelAPIVersion: 1;
+
   /** SDK version used by the block */
   readonly sdkVersion: string;
 
@@ -63,10 +148,10 @@ export type BlockConfigV3Generic<
   readonly featureFlags?: BlockCodeFeatureFlags;
 };
 
-export type BlockConfigGeneric = BlockConfigV3Generic;
+export type BlockConfigGeneric = BlockConfigV3Generic | BlockConfigV4Generic;
 
-export function extractCodeWithInfo(cfg: BlockConfigV3Generic): BlockCodeWithInfo {
-  if (cfg.code === undefined) throw new Error('No code bundle');
+export function extractCodeWithInfo(cfg: BlockConfigGeneric): BlockCodeWithInfo {
+  if (cfg.code === undefined) throw new Error('extractCodeWithInfo: No code bundle');
   return {
     code: cfg.code,
     sdkVersion: cfg.sdkVersion,

package/src/bmodel/container.ts

@@ -1,11 +1,12 @@
-import type { BlockConfigV3Generic } from './block_config';
+import type { BlockConfigV3Generic, BlockConfigV4Generic } from './block_config';
 import type { Code } from './code';
 import type { BlockRenderingMode } from './types';
 
 /** Container simplifying maintenance of forward and backward compatibility */
 export type BlockConfigContainer = {
+  readonly v4?: Omit<BlockConfigV4Generic, 'code'>;
   /** Actual config */
-  readonly v3: Omit<BlockConfigV3Generic, 'code'>;
+  readonly v3?: Omit<BlockConfigV3Generic, 'code'>;
 
   /** Config code bundle. Actually is required, but we keep it optional for backward compatibility */
   readonly code?: Code;

package/src/bmodel/normalization.ts

@@ -16,12 +16,32 @@ function upgradeCfgOrLambda(
 /**
  * Takes universal config, and converts it into latest config structure.
  *
- * **Important**: This operation is not meant to be executed recusively.
+ * **Important**: This operation is not meant to be executed recursively.
  *                In no circumstance result of this function should be persisted!
  * */
 export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGeneric {
-  if (cfg.v3 !== undefined) {
-    // version 3
+  if (cfg.v4 !== undefined) {
+    // version 4 (BlockModelV3) - inputsValid is derived from args() success/failure
+    const { args, prerunArgs, initialData, outputs, renderingMode, sdkVersion, featureFlags, sections, title, enrichmentTargets, migrations } = cfg.v4;
+    const { code } = cfg;
+    return {
+      configVersion: 4,
+      modelAPIVersion: 2,
+      args,
+      prerunArgs,
+      initialData,
+      outputs,
+      renderingMode,
+      sdkVersion,
+      featureFlags,
+      sections,
+      title,
+      enrichmentTargets,
+      migrations,
+      code,
+    };
+  } else if (cfg.v3 !== undefined) {
+    // version 3 (BlockModel v1)
     const {
       initialArgs,
       initialUiState,
@@ -38,6 +58,8 @@ export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGene
     } = cfg.v3;
     const { code } = cfg;
     return {
+      configVersion: 3,
+      modelAPIVersion: 1,
       initialArgs,
       initialUiState,
       inputsValid,
@@ -53,7 +75,7 @@ export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGene
       enrichmentTargets,
     };
   } else if (cfg.inputsValid !== undefined) {
-    // version 2
+    // version 2 (legacy) - normalize to v3 format
     const { sdkVersion, renderingMode, outputs, inputsValid, sections, initialArgs, code } = cfg;
     const fields = Object.keys(cfg);
     if (
@@ -68,6 +90,8 @@ export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGene
         `Malformed config v2. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`,
       );
     return {
+      configVersion: 3,
+      modelAPIVersion: 1,
       sdkVersion,
       renderingMode,
       initialArgs,
@@ -80,7 +104,7 @@ export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGene
       code,
     };
   } else if (cfg.renderingMode !== undefined) {
-    // version 1
+    // version 1 (legacy) - normalize to v3 format
     const { sdkVersion, canRun, renderingMode, outputs, sections, initialArgs, code } = cfg;
     const fields = Object.keys(cfg);
     if (
@@ -94,6 +118,8 @@ export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGene
         `Malformed config v1. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`,
       );
     return {
+      configVersion: 3,
+      modelAPIVersion: 1,
       sdkVersion: sdkVersion ?? 'unknown',
       renderingMode,
       initialArgs,

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

@@ -76,11 +76,17 @@ export function readMetadataJson<M extends Metadata, T extends keyof MetadataJso
 export const Domain = {
   Alphabet: 'pl7.app/alphabet',
   BlockId: 'pl7.app/blockId',
+  VDJ: {
+    ScClonotypeChain: {
+      Index: 'pl7.app/vdj/scClonotypeChain/index',
+    },
+  },
 } as const;
 
 export type Domain = Metadata & Partial<{
-  [Domain.Alphabet]: 'nucleotide' | 'aminoacid' | string;
+  [Domain.Alphabet]: 'nucleotide' | 'aminoacid' | (string & {});
   [Domain.BlockId]: string;
+  [Domain.VDJ.ScClonotypeChain.Index]: 'primary' | 'secondary' | (string & {});
 }>;
 
 export type DomainJson = MetadataJson<Domain>;
@@ -152,11 +158,14 @@ export const Annotation = {
     Visibility: 'pl7.app/table/visibility',
   },
   Trace: 'pl7.app/trace',
+  VDJ: {
+    IsAssemblingFeature: 'pl7.app/vdj/isAssemblingFeature',
+  },
 } as const;
 
 export type Annotation = Metadata & Partial<{
-  [Annotation.Alphabet]: 'nucleotide' | 'aminoacid' | string;
-  [Annotation.AxisNature]: 'homogeneous' | 'heterogeneous' | 'scaleCompatible' | string;
+  [Annotation.Alphabet]: 'nucleotide' | 'aminoacid' | (string & {});
+  [Annotation.AxisNature]: 'homogeneous' | 'heterogeneous' | 'scaleCompatible' | (string & {});
   [Annotation.Description]: string;
   [Annotation.DiscreteValues]: StringifiedJson<number[]> | StringifiedJson<string[]>;
   [Annotation.Format]: string;
@@ -169,8 +178,8 @@ export type Annotation = Metadata & Partial<{
   [Annotation.Graph.Palette]: StringifiedJson<{ mapping: Record<string, number>; name: string }>;
   [Annotation.Graph.Thresholds]: StringifiedJson<{ columnId: { valueType: ValueType; name: string }; value: number }[]>;
   [Annotation.Graph.TreatAbsentValuesAs]: StringifiedJson<number>;
-  [Annotation.HideDataFromUi]: StringifiedJson<boolean>;
   [Annotation.HideDataFromGraphs]: StringifiedJson<boolean>;
+  [Annotation.HideDataFromUi]: StringifiedJson<boolean>;
   [Annotation.IsDiscreteFilter]: StringifiedJson<boolean>;
   [Annotation.IsLinkerColumn]: StringifiedJson<boolean>;
   [Annotation.IsSubset]: StringifiedJson<boolean>;
@@ -183,8 +192,9 @@ export type Annotation = Metadata & Partial<{
   [Annotation.Sequence.IsAnnotation]: StringifiedJson<boolean>;
   [Annotation.Table.FontFamily]: string;
   [Annotation.Table.OrderPriority]: StringifiedJson<number>;
-  [Annotation.Table.Visibility]: 'hidden' | 'optional' | string;
+  [Annotation.Table.Visibility]: 'hidden' | 'optional' | (string & {});
   [Annotation.Trace]: StringifiedJson<Record<string, unknown>>;
+  [Annotation.VDJ.IsAssemblingFeature]: StringifiedJson<boolean>;
 }>;
 
 // export const AxisSpec = z.object({
@@ -236,6 +246,7 @@ export const AnnotationJson: AnnotationJson = {
   [Annotation.Sequence.IsAnnotation]: z.boolean(),
   [Annotation.Table.OrderPriority]: z.number(),
   [Annotation.Trace]: z.record(z.string(), z.unknown()),
+  [Annotation.VDJ.IsAssemblingFeature]: z.boolean(),
 };
 
 /// Helper function for reading plain annotation values
@@ -503,6 +514,19 @@ export const PColumnName = {
   Table: {
     RowSelection: 'pl7.app/table/row-selection',
   },
+  VDJ: {
+    Sequence: 'pl7.app/vdj/sequence',
+  },
+} as const;
+
+/// Well-known axis names
+export const PAxisName = {
+  VDJ: {
+    Assay: {
+      SequenceId: 'pl7.app/vdj/assay/sequenceId',
+    },
+    ScClonotypeKey: 'pl7.app/vdj/scClonotypeKey',
+  },
 } as const;
 
 export function isLabelColumn(column: PColumnSpec) {