@milaboratories/pl-middle-layer 1.74.11 → 1.74.12

package/dist/model/project_helper.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"project_helper.cjs","names":["LRUCache","ConsoleLoggerAdapter","BLOCK_STORAGE_FACADE_VERSION","executeSingleLambda","BlockStorageFacadeCallbacks","getDebugFlags"],"sources":["../../src/model/project_helper.ts"],"sourcesContent":["import type { ResultOrError, BlockConfig, BlockStorage, PlRef } from \"@platforma-sdk/model\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport {\n  extractCodeWithInfo,\n  ensureError,\n  BlockStorageFacadeCallbacks,\n  BLOCK_STORAGE_FACADE_VERSION,\n} from \"@platforma-sdk/model\";\nimport { LRUCache } from \"lru-cache\";\nimport type { QuickJSWASMModule } from \"quickjs-emscripten\";\nimport { executeSingleLambda } from \"../js_render\";\nimport type { SignedResourceId } from \"@milaboratories/pl-client\";\nimport { ConsoleLoggerAdapter, type MiLogger } from \"@milaboratories/ts-helpers\";\nimport { getDebugFlags } from \"../debug\";\n\ntype EnrichmentTargetsRequest = {\n  blockConfig: () => BlockConfig;\n  args: () => unknown;\n};\n\ntype EnrichmentTargetsValue = {\n  value: PlRef[] | undefined;\n};\n\n/**\n * Result of VM-based storage migration.\n * Returned by migrateStorageInVM().\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive VM callbacks.\n */\ntype ArgsDeriveResult = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Result of building initial storage from params.\n * Returned by the __pl_storage_initialFromParams VM callback.\n */\ntype ParamsStorageResult =\n  | { error: string }\n  | { error?: undefined; storageJson: StringifiedJson<BlockStorage> };\n\n/**\n * Result of checking params against their kind.\n * Returned by the __pl_initializationParams_validate VM callback.\n */\ntype InitializationParamsValidateResult = { error: string } | { error?: undefined };\n\nexport class ProjectHelper {\n  private readonly enrichmentTargetsCache = new LRUCache<\n    string,\n    EnrichmentTargetsValue,\n    EnrichmentTargetsRequest\n  >({\n    max: 256,\n    memoMethod: (_key, _value, { context }) => {\n      return { value: this.calculateEnrichmentTargets(context) };\n    },\n  });\n\n  constructor(\n    private readonly quickJs: QuickJSWASMModule,\n    public readonly logger: MiLogger = new ConsoleLoggerAdapter(),\n  ) {}\n\n  // =============================================================================\n  // Args Derivation from Storage (V3+)\n  // =============================================================================\n\n  /**\n   * Derives args directly from storage JSON using VM callback.\n   * The VM extracts data from storage and calls the block's args() function.\n   *\n   * This allows the middle layer to work only with storage JSON,\n   * without needing to know the underlying data structure.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived args object, or error if derivation fails\n   */\n  public deriveArgsFromStorage(\n    blockConfig: BlockConfig,\n    storageJson: string,\n  ): ResultOrError<unknown> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\"deriveArgsFromStorage is only supported for model API version 2\"),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.ArgsDerive],\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        return { error: new Error(result.error) };\n      }\n      return { value: result.value };\n    } catch (e) {\n      return { error: new Error(\"Args derivation from storage failed\", { cause: ensureError(e) }) };\n    }\n  }\n\n  /**\n   * Derives prerunArgs directly from storage JSON using VM callback.\n   * Falls back to args() if prerunArgs is not defined in the block model.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived prerunArgs, or undefined if derivation fails\n   */\n  public derivePrerunArgsFromStorage(blockConfig: BlockConfig, storageJson: string): unknown {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"derivePrerunArgsFromStorage is only supported for model API version 2\");\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.PrerunArgsDerive],\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        // Return undefined if derivation fails (skip block in staging)\n        return undefined;\n      }\n      return result.value;\n    } catch {\n      // Return undefined if derivation fails (skip block in staging)\n      return undefined;\n    }\n  }\n\n  /**\n   * Derives this block's template-export params from storage JSON using the VM\n   * callback (`__pl_initializationParams_derive`).\n   *\n   * The template-export counterpart of {@link deriveArgsFromStorage}: instead of\n   * the args a workflow runs on, it returns the params that would recreate the\n   * block — the inverse of the data model's `init`. Params come back exactly as the block\n   * projected them, references included: nothing marks or rewrites them on the way out, so\n   * nothing here has to know a kind's params shape or how a reference is spelled.\n   *\n   * A `{ value: undefined }` result means the block declares no `templateParams`, which only\n   * a block built against an older SDK can do. It does not reach a document: the export walk\n   * requires a mapping and reports anything else as that block's problem, so an entry always\n   * carries params.\n   *\n   * Unlike {@link derivePrerunArgsFromStorage}, a failure here is surfaced rather\n   * than swallowed — a prerun that cannot derive args just skips a block in\n   * staging, whereas an export that silently drops a block produces a template\n   * that does not describe the project.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived params with identifiers wrapped, `undefined` if the block declares\n   *   no lambda, or an error if derivation failed\n   */\n  public deriveTemplateParamsFromStorage(\n    blockConfig: BlockConfig,\n    storageJson: string,\n  ): ResultOrError<unknown> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\n          \"deriveTemplateParamsFromStorage is only supported for model API version 2\",\n        ),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.InitializationParamsDerive];\n\n    // A model built before this callback existed simply has no entry for it. That is\n    // NOT the same as a block declaring no `templateParams`: the block may well have\n    // params, we just have no way to ask for them. Reporting it as `undefined` params\n    // would export the block stripped of its configuration and quietly rebuild a\n    // differently-configured project, so it has to be an error.\n    // The message names the one action available to whoever pressed Export. It\n    // deliberately says nothing about SDKs or callbacks: the person reading it did\n    // not build this block and cannot change how it was built.\n    if (callback === undefined) {\n      return {\n        error: new Error(\n          \"This version of the block cannot be written to a template. Update the block \" +\n            \"to a newer version and export again.\",\n        ),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        return { error: new Error(result.error) };\n      }\n      return { value: result.value };\n    } catch (e) {\n      const cause = ensureError(e);\n      // The reason goes in the message, not only in `cause`: this error is rendered\n      // into a per-block export problem and shown to whoever triggered the export,\n      // and every layer between here and there carries only `message`.\n      return {\n        error: new Error(`Template params derivation from storage failed: ${cause.message}`, {\n          cause,\n        }),\n      };\n    }\n  }\n\n  private calculateEnrichmentTargets(req: EnrichmentTargetsRequest): PlRef[] | undefined {\n    const blockConfig = req.blockConfig();\n    if (blockConfig.enrichmentTargets === undefined) return undefined;\n    const args = req.args();\n    const result = executeSingleLambda(\n      this.quickJs,\n      blockConfig.enrichmentTargets,\n      extractCodeWithInfo(blockConfig),\n      args,\n    ) as PlRef[];\n    return result;\n  }\n\n  public getEnrichmentTargets(\n    blockConfig: () => BlockConfig,\n    args: () => unknown,\n    key?: { argsRid: SignedResourceId; blockPackRid: SignedResourceId },\n  ): PlRef[] | undefined {\n    const req = { blockConfig, args };\n    if (key === undefined) return this.calculateEnrichmentTargets(req);\n    const cacheKey = `${key.argsRid}:${key.blockPackRid}`;\n    return this.enrichmentTargetsCache.memo(cacheKey, { context: req }).value;\n  }\n\n  // =============================================================================\n  // VM-based Storage Operations\n  // =============================================================================\n\n  /**\n   * Creates initial BlockStorage for a new block using VM-based transformation.\n   * This calls the '__pl_storage_initial' callback registered by DataModel which:\n   * - Gets initial data from DataModel.getDefaultData()\n   * - Creates BlockStorage with correct version\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @returns Initial storage as JSON string\n   * @throws Error if storage creation fails\n   */\n  public getInitialStorageInVM(blockConfig: BlockConfig): string {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"getInitialStorageInVM is only supported for model API version 2\");\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageInitial],\n        extractCodeWithInfo(blockConfig),\n      ) as string;\n      return result;\n    } catch (e) {\n      this.logger.error(\n        new Error(\"[ProjectHelper.getInitialStorageInVM] Initial storage creation failed\", {\n          cause: e,\n        }),\n      );\n      throw new Error(`Block initial storage creation failed: ${e}`);\n    }\n  }\n\n  /**\n   * Checks a template entry's params against the block's kind, creating nothing.\n   *\n   * The pre-flight half of {@link getInitialStorageFromParamsInVM}: run once per entry\n   * before a template is applied, so params a kind rejects are reported against the\n   * entry that carries them while there is still no project. Skipping it is safe —\n   * initialization runs the same check — but then the report arrives after earlier\n   * entries have already been created.\n   *\n   * Every kind declares a parser, so a pass here means the params were checked against\n   * the contract — not merely that they were JSON.\n   *\n   * A block whose model predates the callback passes unchecked rather than failing.\n   * Unlike initialization, this method creates nothing, so there is nothing to get wrong\n   * by proceeding, and such a block is refused outright at the point it is applied.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param params The entry's params. Reference ids may be placeholders: what is being\n   *   checked is the shape of the params, not what they point at\n   * @returns Nothing, or why the params were rejected\n   */\n  public validateTemplateParamsInVM(\n    blockConfig: BlockConfig,\n    params: unknown,\n  ): ResultOrError<undefined> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\"validateTemplateParamsInVM is only supported for model API version 2\"),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.InitializationParamsValidate];\n    if (callback === undefined) return { value: undefined };\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        JSON.stringify(params ?? {}),\n      ) as InitializationParamsValidateResult;\n\n      if (result.error !== undefined) return { error: new Error(result.error) };\n      return { value: undefined };\n    } catch (e) {\n      const cause = ensureError(e);\n      return { error: new Error(`Params check failed to run: ${cause.message}`, { cause }) };\n    }\n  }\n\n  /**\n   * Creates initial BlockStorage for a block being created from template params.\n   *\n   * The inverse of {@link deriveTemplateParamsFromStorage}, and the reason a block\n   * can be created by anything other than the UI: it hands the params to the\n   * block's own init factory inside the model VM, so the resulting storage is\n   * whatever that block considers a correctly-initialized state.\n   *\n   * **Pointing the entry's references at this project happens in the same call**, before the\n   * factory sees them — inside the block's bundle, because recognizing a reference means\n   * knowing the reference system and a template engine deliberately does not. Params reach\n   * here exactly as the file held them.\n   *\n   * One call and not two: every VM call builds a fresh runtime and re-evaluates the whole\n   * model bundle, so asking the block to relocate and then asking it to initialize would parse\n   * it twice per entry, for an intermediate value nothing else reads.\n   *\n   * `blockIds` holds the entries created so far, so an id it does not name is left as it is —\n   * a reference to an entry further down the file keeps pointing at nothing, and the applied\n   * block reports itself as missing references rather than being wired to a block below it.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param params The entry's params, as the document held them\n   * @param blockIds template-local entry id → the block id that entry was given\n   * @returns The initial storage as JSON string, or why the params yield none\n   */\n  public getInitialStorageFromParamsInVM(\n    blockConfig: BlockConfig,\n    params: unknown,\n    blockIds: ReadonlyMap<string, string>,\n  ): ResultOrError<string> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\n          \"getInitialStorageFromParamsInVM is only supported for model API version 2\",\n        ),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageInitialFromParams];\n\n    // A model built before this callback existed has no entry for it. Falling back to the\n    // params-less initializer is not an option: it would produce a default-configured block\n    // that looks like a successful apply, so the block the user gets would silently differ\n    // from the one the template describes. Nor could its params be used as written — they name\n    // the blocks of the project the template came from, and only this callback knows which of\n    // the values in there are references at all.\n    //\n    // The message offers the two actions available to whoever applied the file. The\n    // second one is the reason this branch is reachable at all: kind resolution only\n    // ever returns a block that declares a kind, and such a block is new enough to\n    // support this — but an entry may pin an exact block version instead, bypassing\n    // resolution, and that pin can name anything ever published.\n    if (callback === undefined) {\n      return {\n        error: new Error(\n          \"This version of the block cannot be created from a template. Use a newer \" +\n            \"version of the block, or remove the pinned block version from the template \" +\n            \"entry so a supported one is chosen automatically.\",\n        ),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        // Params cross the VM boundary as text, like storage does. `undefined` would\n        // stringify to nothing at all, and an entry with no params must go through\n        // the params-less initializer rather than reaching this method.\n        JSON.stringify(params ?? {}),\n        JSON.stringify(Object.fromEntries(blockIds)),\n      ) as ParamsStorageResult;\n\n      if (result.error !== undefined) return { error: new Error(result.error) };\n      return { value: result.storageJson };\n    } catch (e) {\n      const cause = ensureError(e);\n      // The reason goes in the message, not only in `cause`: this error becomes a\n      // per-entry apply problem shown to whoever triggered the import, and every\n      // layer in between carries only `message`.\n      return {\n        error: new Error(`Initial storage creation from params failed: ${cause.message}`, {\n          cause,\n        }),\n      };\n    }\n  }\n\n  /**\n   * Applies a state update using VM-based transformation.\n   * This calls the model's `__pl_storage_applyUpdate` callback which:\n   * - Normalizes current storage\n   * - Updates state while preserving other fields (version, plugins)\n   * - Returns the updated storage as JSON string\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param currentStorageJson Current storage as JSON string (must be defined)\n   * @param newState New state from developer\n   * @returns Updated storage as JSON string\n   * @throws Error if storage update fails\n   */\n  public applyStorageUpdateInVM(\n    blockConfig: BlockConfig,\n    currentStorageJson: string,\n    payload: { operation: string; value: unknown },\n  ): string {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"applyStorageUpdateInVM is only supported for model API version 2\");\n    }\n\n    if (getDebugFlags().logJsExecStat) {\n      this.logger.info(\n        `[ProjectHelper.applyStorageUpdateInVM] currentStorageJson=${currentStorageJson.length}B, payload=${JSON.stringify(payload).length}B, operation=${payload.operation}`,\n      );\n    }\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageApplyUpdate],\n        extractCodeWithInfo(blockConfig),\n        currentStorageJson,\n        payload,\n      ) as string;\n      return result;\n    } catch (e) {\n      const payloadJson = JSON.stringify(payload);\n      this.logger.error(\n        new Error(\n          `[ProjectHelper.applyStorageUpdateInVM] Storage update failed (currentStorageJson=${currentStorageJson.length}B, payload=${payloadJson.length}B, operation=${payload.operation})`,\n          { cause: e },\n        ),\n      );\n      throw new Error(`Block storage update failed: ${e}`);\n    }\n  }\n\n  // =============================================================================\n  // Block State Migrations\n  // =============================================================================\n\n  /**\n   * Runs block state migrations via VM-based transformation.\n   * This calls the model's `__pl_storage_migrate` callback which:\n   * - Normalizes current storage to get state and version\n   * - Applies DataModel upgrade to reach target version key\n   * - Runs all necessary migrations sequentially\n   * - Returns new storage with updated state and version\n   *\n   * The middle layer doesn't need to know about dataVersion or storage internals.\n   * All migration logic is encapsulated in the model.\n   *\n   * @param blockConfig The NEW block configuration (provides the model code with migrations)\n   * @param currentStorageJson Current storage as JSON string (or undefined)\n   * @returns MigrationResult with new storage or skip/error info\n   */\n  public migrateStorageInVM(\n    blockConfig: BlockConfig,\n    currentStorageJson: string | undefined,\n  ): MigrationResult {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return { error: \"migrateStorageInVM is only supported for model API version 2\" };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageMigrate],\n        extractCodeWithInfo(blockConfig),\n        currentStorageJson,\n      ) as MigrationResult;\n      return result;\n    } catch (e) {\n      this.logger.error(\n        new Error(\"[ProjectHelper.migrateStorageInVM] Migration failed\", { cause: e }),\n      );\n      return { error: `VM execution failed: ${e}` };\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"project_helper.cjs","names":["LRUCache","ConsoleLoggerAdapter","BLOCK_STORAGE_FACADE_VERSION","executeSingleLambda","BlockStorageFacadeCallbacks","extractCodeWithInfo","ensureError","getDebugFlags"],"sources":["../../src/model/project_helper.ts"],"sourcesContent":["import type { ResultOrError, BlockConfig, BlockStorage, PlRef } from \"@platforma-sdk/model\";\nimport type { StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport {\n  extractCodeWithInfo,\n  ensureError,\n  BlockStorageFacadeCallbacks,\n  BLOCK_STORAGE_FACADE_VERSION,\n} from \"@platforma-sdk/model\";\nimport { LRUCache } from \"lru-cache\";\nimport type { QuickJSWASMModule } from \"quickjs-emscripten\";\nimport { executeSingleLambda } from \"../js_render\";\nimport type { SignedResourceId } from \"@milaboratories/pl-client\";\nimport { ConsoleLoggerAdapter, type MiLogger } from \"@milaboratories/ts-helpers\";\nimport { getDebugFlags } from \"../debug\";\n\ntype EnrichmentTargetsRequest = {\n  blockConfig: () => BlockConfig;\n  args: () => unknown;\n};\n\ntype EnrichmentTargetsValue = {\n  value: PlRef[] | undefined;\n};\n\n/**\n * Result of VM-based storage migration.\n * Returned by migrateStorageInVM().\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive VM callbacks.\n */\ntype ArgsDeriveResult = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Result of building initial storage from params.\n * Returned by the __pl_storage_initialFromParams VM callback.\n */\ntype ParamsStorageResult =\n  | { error: string }\n  | { error?: undefined; storageJson: StringifiedJson<BlockStorage> };\n\n/**\n * Result of checking params against their kind.\n * Returned by the __pl_initializationParams_validate VM callback.\n */\ntype InitializationParamsValidateResult = { error: string } | { error?: undefined };\n\nexport class ProjectHelper {\n  private readonly enrichmentTargetsCache = new LRUCache<\n    string,\n    EnrichmentTargetsValue,\n    EnrichmentTargetsRequest\n  >({\n    max: 256,\n    memoMethod: (_key, _value, { context }) => {\n      return { value: this.calculateEnrichmentTargets(context) };\n    },\n  });\n\n  constructor(\n    private readonly quickJs: QuickJSWASMModule,\n    public readonly logger: MiLogger = new ConsoleLoggerAdapter(),\n  ) {}\n\n  // =============================================================================\n  // Args Derivation from Storage (V3+)\n  // =============================================================================\n\n  /**\n   * Derives args directly from storage JSON using VM callback.\n   * The VM extracts data from storage and calls the block's args() function.\n   *\n   * This allows the middle layer to work only with storage JSON,\n   * without needing to know the underlying data structure.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived args object, or error if derivation fails\n   */\n  public deriveArgsFromStorage(\n    blockConfig: BlockConfig,\n    storageJson: string,\n  ): ResultOrError<unknown> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\"deriveArgsFromStorage is only supported for model API version 2\"),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.ArgsDerive],\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        return { error: new Error(result.error) };\n      }\n      return { value: result.value };\n    } catch (e) {\n      return { error: new Error(\"Args derivation from storage failed\", { cause: ensureError(e) }) };\n    }\n  }\n\n  /**\n   * Derives prerunArgs directly from storage JSON using VM callback.\n   * Falls back to args() if prerunArgs is not defined in the block model.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived prerunArgs, or undefined if derivation fails\n   */\n  public derivePrerunArgsFromStorage(blockConfig: BlockConfig, storageJson: string): unknown {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"derivePrerunArgsFromStorage is only supported for model API version 2\");\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.PrerunArgsDerive],\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        // Return undefined if derivation fails (skip block in staging)\n        return undefined;\n      }\n      return result.value;\n    } catch {\n      // Return undefined if derivation fails (skip block in staging)\n      return undefined;\n    }\n  }\n\n  /**\n   * Derives this block's template-export params from storage JSON using the VM\n   * callback (`__pl_initializationParams_derive`).\n   *\n   * The template-export counterpart of {@link deriveArgsFromStorage}: instead of\n   * the args a workflow runs on, it returns the params that would recreate the\n   * block — the inverse of the data model's `init`. Params come back exactly as the block\n   * projected them, references included: nothing marks or rewrites them on the way out, so\n   * nothing here has to know a kind's params shape or how a reference is spelled.\n   *\n   * A `{ value: undefined }` result means the block declares no `templateParams`, which only\n   * a block built against an older SDK can do. It does not reach a document: the export walk\n   * requires a mapping and reports anything else as that block's problem, so an entry always\n   * carries params.\n   *\n   * Unlike {@link derivePrerunArgsFromStorage}, a failure here is surfaced rather\n   * than swallowed — a prerun that cannot derive args just skips a block in\n   * staging, whereas an export that silently drops a block produces a template\n   * that does not describe the project.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param storageJson Storage as JSON string\n   * @returns The derived params with identifiers wrapped, `undefined` if the block declares\n   *   no lambda, or an error if derivation failed\n   */\n  public deriveTemplateParamsFromStorage(\n    blockConfig: BlockConfig,\n    storageJson: string,\n  ): ResultOrError<unknown> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\n          \"deriveTemplateParamsFromStorage is only supported for model API version 2\",\n        ),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.InitializationParamsDerive];\n\n    // A model built before this callback existed simply has no entry for it. That is\n    // NOT the same as a block declaring no `templateParams`: the block may well have\n    // params, we just have no way to ask for them. Reporting it as `undefined` params\n    // would export the block stripped of its configuration and quietly rebuild a\n    // differently-configured project, so it has to be an error.\n    // The message names the one action available to whoever pressed Export. It\n    // deliberately says nothing about SDKs or callbacks: the person reading it did\n    // not build this block and cannot change how it was built.\n    if (callback === undefined) {\n      return {\n        error: new Error(\n          \"This version of the block cannot be written to a template. Update the block \" +\n            \"to a newer version and export again.\",\n        ),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        storageJson,\n      ) as ArgsDeriveResult;\n\n      if (result.error !== undefined) {\n        return { error: new Error(result.error) };\n      }\n      return { value: result.value };\n    } catch (e) {\n      const cause = ensureError(e);\n      // The reason goes in the message, not only in `cause`: this error is rendered\n      // into a per-block export problem and shown to whoever triggered the export,\n      // and every layer between here and there carries only `message`.\n      return {\n        error: new Error(`Template params derivation from storage failed: ${cause.message}`, {\n          cause,\n        }),\n      };\n    }\n  }\n\n  private calculateEnrichmentTargets(req: EnrichmentTargetsRequest): PlRef[] | undefined {\n    const blockConfig = req.blockConfig();\n    if (blockConfig.enrichmentTargets === undefined) return undefined;\n    const args = req.args();\n    const result = executeSingleLambda(\n      this.quickJs,\n      blockConfig.enrichmentTargets,\n      extractCodeWithInfo(blockConfig),\n      args,\n    ) as PlRef[];\n    return result;\n  }\n\n  public getEnrichmentTargets(\n    blockConfig: () => BlockConfig,\n    args: () => unknown,\n    key?: { argsRid: SignedResourceId; blockPackRid: SignedResourceId },\n  ): PlRef[] | undefined {\n    const req = { blockConfig, args };\n    if (key === undefined) return this.calculateEnrichmentTargets(req);\n    const cacheKey = `${key.argsRid}:${key.blockPackRid}`;\n    return this.enrichmentTargetsCache.memo(cacheKey, { context: req }).value;\n  }\n\n  // =============================================================================\n  // VM-based Storage Operations\n  // =============================================================================\n\n  /**\n   * Creates initial BlockStorage for a new block using VM-based transformation.\n   * This calls the '__pl_storage_initial' callback registered by DataModel which:\n   * - Gets initial data from DataModel.getDefaultData()\n   * - Creates BlockStorage with correct version\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @returns Initial storage as JSON string\n   * @throws Error if storage creation fails\n   */\n  public getInitialStorageInVM(blockConfig: BlockConfig): string {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"getInitialStorageInVM is only supported for model API version 2\");\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageInitial],\n        extractCodeWithInfo(blockConfig),\n      ) as string;\n      return result;\n    } catch (e) {\n      this.logger.error(\n        new Error(\"[ProjectHelper.getInitialStorageInVM] Initial storage creation failed\", {\n          cause: e,\n        }),\n      );\n      throw new Error(`Block initial storage creation failed: ${e}`);\n    }\n  }\n\n  /**\n   * Checks a template entry's params against the block's kind, creating nothing.\n   *\n   * The pre-flight half of {@link getInitialStorageFromParamsInVM}: run once per entry\n   * before a template is applied, so params a kind rejects are reported against the\n   * entry that carries them while there is still no project. Skipping it is safe —\n   * initialization runs the same check — but then the report arrives after earlier\n   * entries have already been created.\n   *\n   * Every kind declares a parser, so a pass here means the params were checked against\n   * the contract — not merely that they were JSON.\n   *\n   * A block whose model predates the callback passes unchecked rather than failing.\n   * Unlike initialization, this method creates nothing, so there is nothing to get wrong\n   * by proceeding, and such a block is refused outright at the point it is applied.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param params The entry's params. Reference ids may be placeholders: what is being\n   *   checked is the shape of the params, not what they point at\n   * @returns Nothing, or why the params were rejected\n   */\n  public validateTemplateParamsInVM(\n    blockConfig: BlockConfig,\n    params: unknown,\n  ): ResultOrError<undefined> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\"validateTemplateParamsInVM is only supported for model API version 2\"),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.InitializationParamsValidate];\n    if (callback === undefined) return { value: undefined };\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        JSON.stringify(params ?? {}),\n      ) as InitializationParamsValidateResult;\n\n      if (result.error !== undefined) return { error: new Error(result.error) };\n      return { value: undefined };\n    } catch (e) {\n      const cause = ensureError(e);\n      return { error: new Error(`Params check failed to run: ${cause.message}`, { cause }) };\n    }\n  }\n\n  /**\n   * Creates initial BlockStorage for a block being created from template params.\n   *\n   * The inverse of {@link deriveTemplateParamsFromStorage}, and the reason a block\n   * can be created by anything other than the UI: it hands the params to the\n   * block's own init factory inside the model VM, so the resulting storage is\n   * whatever that block considers a correctly-initialized state.\n   *\n   * **Pointing the entry's references at this project happens in the same call**, before the\n   * factory sees them — inside the block's bundle, because recognizing a reference means\n   * knowing the reference system and a template engine deliberately does not. Params reach\n   * here exactly as the file held them.\n   *\n   * One call and not two: every VM call builds a fresh runtime and re-evaluates the whole\n   * model bundle, so asking the block to relocate and then asking it to initialize would parse\n   * it twice per entry, for an intermediate value nothing else reads.\n   *\n   * `blockIds` holds the entries created so far, so an id it does not name is left as it is —\n   * a reference to an entry further down the file keeps pointing at nothing, and the applied\n   * block reports itself as missing references rather than being wired to a block below it.\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param params The entry's params, as the document held them\n   * @param blockIds template-local entry id → the block id that entry was given\n   * @returns The initial storage as JSON string, or why the params yield none\n   */\n  public getInitialStorageFromParamsInVM(\n    blockConfig: BlockConfig,\n    params: unknown,\n    blockIds: ReadonlyMap<string, string>,\n  ): ResultOrError<string> {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return {\n        error: new Error(\n          \"getInitialStorageFromParamsInVM is only supported for model API version 2\",\n        ),\n      };\n    }\n\n    const callback =\n      blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageInitialFromParams];\n\n    // A model built before this callback existed has no entry for it. Falling back to the\n    // params-less initializer is not an option: it would produce a default-configured block\n    // that looks like a successful apply, so the block the user gets would silently differ\n    // from the one the template describes. Nor could its params be used as written — they name\n    // the blocks of the project the template came from, and only this callback knows which of\n    // the values in there are references at all.\n    //\n    // The message offers the two actions available to whoever applied the file. The\n    // second one is the reason this branch is reachable at all: kind resolution only\n    // ever returns a block that declares a kind, and such a block is new enough to\n    // support this — but an entry may pin an exact block version instead, bypassing\n    // resolution, and that pin can name anything ever published.\n    if (callback === undefined) {\n      return {\n        error: new Error(\n          \"This version of the block cannot be created from a template. Use a newer \" +\n            \"version of the block, or remove the pinned block version from the template \" +\n            \"entry so a supported one is chosen automatically.\",\n        ),\n      };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        callback,\n        extractCodeWithInfo(blockConfig),\n        // Params cross the VM boundary as text, like storage does. `undefined` would\n        // stringify to nothing at all, and an entry with no params must go through\n        // the params-less initializer rather than reaching this method.\n        JSON.stringify(params ?? {}),\n        JSON.stringify(Object.fromEntries(blockIds)),\n      ) as ParamsStorageResult;\n\n      if (result.error !== undefined) return { error: new Error(result.error) };\n      return { value: result.storageJson };\n    } catch (e) {\n      const cause = ensureError(e);\n      // The reason goes in the message, not only in `cause`: this error becomes a\n      // per-entry apply problem shown to whoever triggered the import, and every\n      // layer in between carries only `message`.\n      return {\n        error: new Error(`Initial storage creation from params failed: ${cause.message}`, {\n          cause,\n        }),\n      };\n    }\n  }\n\n  /**\n   * Applies a state update using VM-based transformation.\n   * This calls the model's `__pl_storage_applyUpdate` callback which:\n   * - Normalizes current storage\n   * - Updates state while preserving other fields (version, plugins)\n   * - Returns the updated storage as JSON string\n   *\n   * @param blockConfig The block configuration (provides the model code)\n   * @param currentStorageJson Current storage as JSON string (must be defined)\n   * @param newState New state from developer\n   * @returns Updated storage as JSON string\n   * @throws Error if storage update fails\n   */\n  public applyStorageUpdateInVM(\n    blockConfig: BlockConfig,\n    currentStorageJson: string,\n    payload: { operation: string; value: unknown },\n  ): string {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new Error(\"applyStorageUpdateInVM is only supported for model API version 2\");\n    }\n\n    if (getDebugFlags().logJsExecStat) {\n      this.logger.info(\n        `[ProjectHelper.applyStorageUpdateInVM] currentStorageJson=${currentStorageJson.length}B, payload=${JSON.stringify(payload).length}B, operation=${payload.operation}`,\n      );\n    }\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageApplyUpdate],\n        extractCodeWithInfo(blockConfig),\n        currentStorageJson,\n        payload,\n      ) as string;\n      return result;\n    } catch (e) {\n      const payloadJson = JSON.stringify(payload);\n      this.logger.error(\n        new Error(\n          `[ProjectHelper.applyStorageUpdateInVM] Storage update failed (currentStorageJson=${currentStorageJson.length}B, payload=${payloadJson.length}B, operation=${payload.operation})`,\n          { cause: e },\n        ),\n      );\n      throw new Error(`Block storage update failed: ${e}`);\n    }\n  }\n\n  // =============================================================================\n  // Block State Migrations\n  // =============================================================================\n\n  /**\n   * Runs block state migrations via VM-based transformation.\n   * This calls the model's `__pl_storage_migrate` callback which:\n   * - Normalizes current storage to get state and version\n   * - Applies DataModel upgrade to reach target version key\n   * - Runs all necessary migrations sequentially\n   * - Returns new storage with updated state and version\n   *\n   * The middle layer doesn't need to know about dataVersion or storage internals.\n   * All migration logic is encapsulated in the model.\n   *\n   * @param blockConfig The NEW block configuration (provides the model code with migrations)\n   * @param currentStorageJson Current storage as JSON string (or undefined)\n   * @returns MigrationResult with new storage or skip/error info\n   */\n  public migrateStorageInVM(\n    blockConfig: BlockConfig,\n    currentStorageJson: string | undefined,\n  ): MigrationResult {\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      return { error: \"migrateStorageInVM is only supported for model API version 2\" };\n    }\n\n    try {\n      const result = executeSingleLambda(\n        this.quickJs,\n        blockConfig.blockLifecycleCallbacks[BlockStorageFacadeCallbacks.StorageMigrate],\n        extractCodeWithInfo(blockConfig),\n        currentStorageJson,\n      ) as MigrationResult;\n      return result;\n    } catch (e) {\n      this.logger.error(\n        new Error(\"[ProjectHelper.migrateStorageInVM] Migration failed\", { cause: e }),\n      );\n      return { error: `VM execution failed: ${e}` };\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/model/project_helper.d.ts

@@ -3,7 +3,6 @@ import { MiLogger } from "@milaboratories/ts-helpers";
 import { StringifiedJson } from "@milaboratories/pl-model-common";
 import { SignedResourceId } from "@milaboratories/pl-client";
 import { QuickJSWASMModule } from "quickjs-emscripten";
-//#region src/model/project_helper.d.ts
 /**
  * Result of VM-based storage migration.
  * Returned by migrateStorageInVM().
@@ -169,5 +168,4 @@ export declare class ProjectHelper {
    */
   migrateStorageInVM(blockConfig: BlockConfig, currentStorageJson: string | undefined): MigrationResult;
 }
-//#endregion
 //# sourceMappingURL=project_helper.d.ts.map

package/dist/model/project_helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project_helper.d.ts","names":[],"sources":["../../src/model/project_helper.ts"],"mappings":";;;;;;;;;;;;;YA+BY;EACN;;EACA;EAAmB,gBAAgB,gBAAgB;EAAe;;qBAsB3D;mBAaQ;WACD,QAAQ;mBAbT;EAWjB,YACmB,SAAS,mBACV,SAAQ;;;;;;;;;;;;EAkBnB,sBACL,aAAa,aACb,sBACC;;;;;;;;;EAgCI,4BAA4B,aAAa,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDtD,gCACL,aAAa,aACb,sBACC;UAsDK;EAaD,qBACL,mBAAmB,aACnB,qBACA;IAAQ,SAAS;IAAkB,cAAc;MAChD;;;;;;;;;;;EAqBI,sBAAsB,aAAa;;;;;;;;;;;;;;;;;;;;;;EA2CnC,2BACL,aAAa,aACb,kBACC;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqDI,gCACL,aAAa,aACb,iBACA,UAAU,8BACT;;;;;;;;;;;;;;EA0EI,uBACL,aAAa,aACb,4BACA;IAAW;IAAmB;;;;;;;;;;;;;;;;;EAmDzB,mBACL,aAAa,aACb,yCACC"}
+{"version":3,"file":"project_helper.d.ts","names":[],"sources":["../../src/model/project_helper.ts"],"mappings":";;;;;;;;;;;;YA+BY;EACN;;EACA;EAAmB,gBAAgB,gBAAgB;EAAe;;qBAsB3D;mBAaQ;WACD,QAAQ;mBAbT;EAWjB,YACmB,SAAS,mBACV,SAAQ;;;;;;;;;;;;EAkBnB,sBACL,aAAa,aACb,sBACC;;;;;;;;;EAgCI,4BAA4B,aAAa,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDtD,gCACL,aAAa,aACb,sBACC;UAsDK;EAaD,qBACL,mBAAmB,aACnB,qBACA;IAAQ,SAAS;IAAkB,cAAc;MAChD;;;;;;;;;;;EAqBI,sBAAsB,aAAa;;;;;;;;;;;;;;;;;;;;;;EA2CnC,2BACL,aAAa,aACb,kBACC;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqDI,gCACL,aAAa,aACb,iBACA,UAAU,8BACT;;;;;;;;;;;;;;EA0EI,uBACL,aAAa,aACb,4BACA;IAAW;IAAmB;;;;;;;;;;;;;;;;;EAmDzB,mBACL,aAAa,aACb,yCACC"}

package/dist/model/project_helper.js

@@ -3,7 +3,7 @@ import { executeSingleLambda } from "../js_render/index.js";
 import { BLOCK_STORAGE_FACADE_VERSION, BlockStorageFacadeCallbacks, ensureError, extractCodeWithInfo } from "@platforma-sdk/model";
 import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 import { LRUCache } from "lru-cache";
-//#region src/model/project_helper.ts
+// src/model/project_helper.ts
 var ProjectHelper = class {
 	quickJs;
 	logger;
@@ -250,7 +250,6 @@ var ProjectHelper = class {
 		}
 	}
 };
-//#endregion
 export { ProjectHelper };
 
 //# sourceMappingURL=project_helper.js.map

package/dist/model/project_model.cjs

@@ -1,4 +1,4 @@
-//#region src/model/project_model.ts
+// src/model/project_model.ts
 const InitialBlockStructure = { groups: [{
 	id: "default",
 	label: "Default",
@@ -53,7 +53,6 @@ function parseProjectField(name) {
 		fieldName
 	};
 }
-//#endregion
 exports.BlockArgsAuthorKeyPrefix = BlockArgsAuthorKeyPrefix;
 exports.BlockRenderingStateKey = BlockRenderingStateKey;
 exports.FieldsToDuplicate = FieldsToDuplicate;

package/dist/model/project_model.d.ts

@@ -2,7 +2,6 @@ import "@platforma-sdk/model";
 import { ProjectListEntry, ProjectMeta } from "@milaboratories/pl-model-middle-layer";
 import { ProjectId as ProjectId$1 } from "@milaboratories/pl-model-common";
 import { ResourceType } from "@milaboratories/pl-client";
-//#region src/model/project_model.d.ts
 interface ProjectListEntry$1 extends Omit<ProjectListEntry, "id"> {
   /** Unique project identifier in middle layer. Use to operate with given project. */
   id: ProjectId$1;
@@ -20,6 +19,5 @@ export interface ProjectField {
   blockId: string;
   fieldName: "blockPack" | "blockSettings" | "blockStorage" | "prodArgs" | "currentArgs" | "currentPrerunArgs" | "prodChainCtx" | "prodCtx" | "prodUiCtx" | "prodOutput" | "prodCtxPrevious" | "prodUiCtxPrevious" | "prodOutputPrevious" | "stagingCtx" | "stagingUiCtx" | "stagingOutput" | "stagingCtxPrevious" | "stagingUiCtxPrevious" | "stagingOutputPrevious";
 }
-//#endregion
 export { type ProjectId$1 as ProjectId, ProjectListEntry$1 as ProjectListEntry };
 //# sourceMappingURL=project_model.d.ts.map

package/dist/model/project_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project_model.d.ts","names":[],"sources":["../../src/model/project_model.ts"],"mappings":";;;;;UAUiB,2BAAyB,KAAK;;EAE7C,IAAI;;qBA+DO,qBAAqB;qBAErB;qBAGA;qBAEA;qBACA;qBACA;qBACA;qBAGA;qBAOA;iBAQI;EACf;EACA"}
+{"version":3,"file":"project_model.d.ts","names":["ProjectListEntry","ProjectListEntryFromModel","ProjectId"],"sources":["../../src/model/project_model.ts"],"mappings":";;;;UAUiBA,2BAAyB,KAAKC;;EAE7C,IAAIC;;qBA+DO,qBAAqB;qBAErB;qBAGA;qBAEA;qBACA;qBACA;qBACA;qBAGA;qBAOA;iBAQI;EACf;EACA"}

package/dist/model/project_model.js

@@ -1,4 +1,4 @@
-//#region src/model/project_model.ts
+// src/model/project_model.ts
 const InitialBlockStructure = { groups: [{
 	id: "default",
 	label: "Default",
@@ -53,7 +53,6 @@ function parseProjectField(name) {
 		fieldName
 	};
 }
-//#endregion
 export { BlockArgsAuthorKeyPrefix, BlockRenderingStateKey, FieldsToDuplicate, InitialBlockMeta, InitialBlockStructure, InitialProjectRenderingState, ProjectCreatedTimestamp, ProjectLastModifiedTimestamp, ProjectMetaKey, ProjectResourceType, ProjectStructureAuthorKey, ProjectStructureKey, SchemaVersionCurrent, SchemaVersionKey, ServiceTemplateCacheFieldPrefix, blockArgsAuthorKey, getServiceTemplateField, parseProjectField, projectFieldName };
 
 //# sourceMappingURL=project_model.js.map

package/dist/model/project_model_util.cjs

@@ -1,5 +1,5 @@
 const require_args = require("./args.cjs");
-//#region src/model/project_model_util.ts
+// src/model/project_model_util.ts
 function allBlocks(structure) {
 	return { *[Symbol.iterator]() {
 		for (const g of structure.groups) for (const b of g.blocks) yield b;
@@ -127,7 +127,6 @@ function graphDiff(a, b) {
 		different
 	};
 }
-//#endregion
 exports.BlockGraph = BlockGraph;
 exports.allBlocks = allBlocks;
 exports.graphDiff = graphDiff;

package/dist/model/project_model_util.js

@@ -1,5 +1,5 @@
 import { inferAllReferencedBlocks } from "./args.js";
-//#region src/model/project_model_util.ts
+// src/model/project_model_util.ts
 function allBlocks(structure) {
 	return { *[Symbol.iterator]() {
 		for (const g of structure.groups) for (const b of g.blocks) yield b;
@@ -127,7 +127,6 @@ function graphDiff(a, b) {
 		different
 	};
 }
-//#endregion
 export { BlockGraph, allBlocks, graphDiff, productionGraph, stagingGraph };
 
 //# sourceMappingURL=project_model_util.js.map

package/dist/model/project_model_v1.cjs

@@ -1,6 +1,5 @@
-//#region src/model/project_model_v1.ts
+// src/model/project_model_v1.ts
 const BlockFrontendStateKeyPrefixV1 = "BlockFrontendState/";
-//#endregion
 exports.BlockFrontendStateKeyPrefixV1 = BlockFrontendStateKeyPrefixV1;
 
 //# sourceMappingURL=project_model_v1.cjs.map

package/dist/model/project_model_v1.js

@@ -1,6 +1,5 @@
-//#region src/model/project_model_v1.ts
+// src/model/project_model_v1.ts
 const BlockFrontendStateKeyPrefixV1 = "BlockFrontendState/";
-//#endregion
 export { BlockFrontendStateKeyPrefixV1 };
 
 //# sourceMappingURL=project_model_v1.js.map

package/dist/model/sharing_model.cjs

@@ -1,6 +1,6 @@
 let _milaboratories_pl_client = require("@milaboratories/pl-client");
 let node_crypto = require("node:crypto");
-//#region src/model/sharing_model.ts
+// src/model/sharing_model.ts
 /** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
 function newShareId() {
 	return (0, node_crypto.randomUUID)();
@@ -155,7 +155,6 @@ const ReadableSchemaVersions = {
 	1: true,
 	2: true
 };
-//#endregion
 exports.EnvelopeSchemaVersionCurrent = EnvelopeSchemaVersionCurrent;
 exports.HiddenFieldPrefix = HiddenFieldPrefix;
 exports.SharedEnvelopeResourceType = SharedEnvelopeResourceType;

package/dist/model/sharing_model.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sharing_model.cjs","names":["RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type {\n  Branded,\n  ProjectId,\n  ProjectTemplateV1,\n  TemplateId,\n} from \"@milaboratories/pl-model-common\";\nimport type { FolderId } from \"@milaboratories/pl-model-middle-layer\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Identity of one share. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the recipient's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/** Mints a fresh {@link ProjectFieldUuid} for one snapshot. */\nexport function newProjectFieldUuid(): ProjectFieldUuid {\n  return randomUUID() as ProjectFieldUuid;\n}\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in a\n *  `projects` {@link EnvelopePayload}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the share lists render without traversing into the project\n  source: ProjectId; // donor's source projectId; what a prior share of the same project is matched on\n  updatedAt: number; // ms epoch of the last (re)snapshot\n  /** What the project said about itself when it was snapshotted, carried for the same reason as\n   *  `label`. Absent when it had none, and on envelopes written before it was carried. */\n  description?: string;\n}\n\n/**\n * Identifier of a folder inside one envelope.\n *\n * Local to the envelope, because the recipient's own folder document mints its own ids and the\n * donor's mean nothing there. What travels is the shape of the subtree, not its identity.\n */\nexport type EnvelopeFolderId = Branded<string, \"EnvelopeFolderId\">;\n\n/** Mints a fresh {@link EnvelopeFolderId} for one folder of the envelope being built. */\nexport function newEnvelopeFolderId(): EnvelopeFolderId {\n  return randomUUID() as EnvelopeFolderId;\n}\n\n/** One folder of a shared subtree. */\nexport interface EnvelopeFolder {\n  name: string;\n  /** Absent for the subtree's root — the folder that was shared. */\n  parent?: EnvelopeFolderId;\n  /** What the donor wrote about the folder. Absent when there is none. */\n  description?: string;\n}\n\n/** A project of a shared subtree: an {@link EnvelopeProject} placed in the subtree. */\nexport interface EnvelopeFolderProject extends EnvelopeProject {\n  folder: EnvelopeFolderId;\n}\n\n/** A template of a shared subtree. The document rides here whole, exactly as a `template`\n *  payload carries it — a template is never snapshotted. */\nexport interface EnvelopeFolderTemplate {\n  document: ProjectTemplateV1;\n  /** Label to give the template among the recipient's templates. */\n  label: string;\n  /** What the template says about itself. Absent when the donor described it with nothing. */\n  description?: string;\n  folder: EnvelopeFolderId;\n}\n\n/**\n * What a share carries. The discriminant is what a reader checks before anything else: a\n * client that does not know a kind hides the share instead of offering something it cannot\n * act on.\n *\n * `projects` snapshots ride as `project/{uuid}` fields on the envelope and this map only\n * describes them; a `template` payload has no fields at all — the document is right here.\n */\nexport type EnvelopePayload =\n  | { kind: \"projects\"; projects: Record<ProjectFieldUuid, EnvelopeProject> }\n  | {\n      kind: \"template\";\n      document: ProjectTemplateV1;\n      /** Donor's own id of the shared template; what a prior share of the same template is\n       *  matched on. It names nothing in the recipient's tree, and envelopes written before it\n       *  existed carry none — those match no later share of anything. */\n      source?: TemplateId;\n      /** Label to give the template among the recipient's templates. */\n      label: string;\n      /** What the template says about itself, carried to the recipient's copy. Absent when the\n       *  donor described it with nothing. */\n      description?: string;\n      /** Donor login, kept on each copy of the template as its provenance. */\n      from: string;\n    }\n  | {\n      kind: \"folder\";\n      /** Donor's own id of the shared folder; what a prior share of the same folder is matched\n       *  on. It names nothing in the recipient's tree. */\n      source: FolderId;\n      /** The shared subtree. Exactly one folder has no parent, and that one is its root. */\n      folders: Record<EnvelopeFolderId, EnvelopeFolder>;\n      /** Project snapshots, each tagged with the folder of the subtree holding it. Their\n       *  `project/{uuid}` fields are the same ones a `projects` payload describes. */\n      projects: Record<ProjectFieldUuid, EnvelopeFolderProject>;\n      /** Templates of the subtree, documents and all. Nothing of a template is snapshotted. */\n      templates: EnvelopeFolderTemplate[];\n      /** Donor login, kept on each copied template as its provenance. */\n      from: string;\n    };\n\nexport type EnvelopePayloadKind = EnvelopePayload[\"kind\"];\n\n/** Every envelope schema version this build can read. Adding a version here is what makes\n *  {@link normalizeEnvelopeData} accept it; bumping {@link EnvelopeSchemaVersionCurrent} to a\n *  version missing from this union is a compile error. */\nexport type EnvelopeSchemaVersion = 1 | 2;\n\n/** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */\nexport const EnvelopeSchemaVersionCurrent = 2 satisfies EnvelopeSchemaVersion;\n\n/**\n * Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated.\n *\n * Always the current version in memory: a v1 envelope (project map at the top level, no\n * `payload` field) is upcast on read by {@link normalizeEnvelopeData}, so no reader past the\n * decode has to know that two shapes ever existed.\n */\nexport interface EnvelopeData {\n  schemaVersion: typeof EnvelopeSchemaVersionCurrent;\n  shareId: ShareId; // donor-generated UUID; identity of this share alone\n  sharedAt: number; // ms epoch; when the share was created\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the recipient's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  payload: EnvelopePayload; // what the share carries\n}\n\n/** The project map of a projects-payload envelope, or `{}` for any other payload — the one\n *  place a project-shaped reader turns a payload into the map it expects. */\nexport function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject> {\n  return data.payload.kind === \"projects\" ? data.payload.projects : {};\n}\n\n/**\n * The shared folder itself: the one folder of the subtree that has no parent.\n *\n * Derived rather than stored, so it cannot disagree with the folders beside it. `undefined` for\n * a subtree with no root or more than one, which is an envelope nothing can be reconstructed\n * from — the copy reports it rather than guessing which folder was meant.\n */\nexport function envelopeFolderRoot(\n  folders: Record<EnvelopeFolderId, EnvelopeFolder>,\n): EnvelopeFolderId | undefined {\n  const roots = (Object.keys(folders) as EnvelopeFolderId[]).filter(\n    (id) => folders[id].parent === undefined,\n  );\n  return roots.length === 1 ? roots[0] : undefined;\n}\n\n/**\n * Dynamic field on SharingState, one per share this user has hidden, keyed by shareId.\n *\n * Hiding is private to the recipient and reversible: the field is written to put a share out of\n * sight and removed to bring it back. It says nothing to the donor and nothing about whether\n * anything was ever copied out of the share — a share can be copied from any number of times,\n * before or after being hidden.\n *\n * The field name keeps its original `decision/` prefix. Records written before hiding replaced\n * accept/reject carry a different value under the same key, and every reader treats the presence\n * of the field as the whole answer: someone who accepted or rejected a share back then does not\n * want to see it, which is exactly what hidden means.\n */\nexport const HiddenFieldPrefix = \"decision/\";\nexport const hiddenField = (shareId: ShareId) => `${HiddenFieldPrefix}${shareId}`;\nexport const isHiddenField = (name: string) => name.startsWith(HiddenFieldPrefix);\nexport const hiddenFieldShareId = (name: string): ShareId =>\n  asShareId(name.slice(HiddenFieldPrefix.length));\n\nexport interface ShareHidden {\n  hidden: true;\n  timestamp: number; // ms epoch — when the recipient hid it\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path decodes the same JSON with `getDataAsJson` and normalizes it with\n * {@link normalizeEnvelopeData} — both paths must, so neither sees the raw v1 shape.\n *\n * `undefined` for an envelope this build cannot act on; see {@link normalizeEnvelopeData}.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData | undefined {\n  return normalizeEnvelopeData(JSON.parse(Buffer.from(data).toString(\"utf-8\")));\n}\n\n/**\n * Brings a decoded envelope blob to the current shape, or reports that this build cannot act\n * on it by returning `undefined` — an unknown `schemaVersion` or an unknown payload kind. A\n * caller hides such a share rather than offering the recipient something it cannot handle.\n *\n * A v1 envelope carried its project map at the top level and had no `payload` field; it reads\n * here as a `projects` payload, so envelopes written before the discriminant existed keep\n * working unchanged.\n */\nexport function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined {\n  if (typeof raw !== \"object\" || raw === null) return undefined;\n  const e = raw as RawEnvelopeData;\n  if (!Object.hasOwn(ReadableSchemaVersions, e.schemaVersion)) return undefined;\n\n  const payload =\n    e.payload ??\n    (e.projects !== undefined ? ({ kind: \"projects\", projects: e.projects } as const) : undefined);\n  if (payload === undefined) return undefined;\n  if (!Object.hasOwn(KnownPayloadKinds, payload.kind)) return undefined;\n\n  return {\n    schemaVersion: EnvelopeSchemaVersionCurrent,\n    shareId: e.shareId,\n    sharedAt: e.sharedAt,\n    expiresAt: e.expiresAt,\n    mode: e.mode,\n    sender: e.sender,\n    title: e.title,\n    payload,\n  };\n}\n\n/**\n * Who a share is granted to: named recipients XOR everyone — two clean variants, not one struct\n * with mutually exclusive optional fields.\n *\n * The everyone variant issues a single make-public grant, and the envelope's `expiresAt` is `null`,\n * so it never expires. The recipients variant grants each named login, and the envelope expires\n * after the default TTL.\n */\nexport type ShareAudience =\n  | { recipients: string[] } // recipient logins\n  | { everyone: true }; // every user on the server\n\n/**\n * Options every share takes: the audience, the title recipients see it under, and the prior\n * shares it replaces.\n */\nexport type ShareOptions = ShareAudience & {\n  title: string;\n  replace?: ShareReplaceOption;\n};\n\n/**\n * Prior shares the new one supersedes: each is deleted in the same transaction that creates the\n * replacement, so the outbox never holds both.\n *\n * The set is the caller's, never inferred here. The author is shown the shares that will go and\n * agrees to that list, so what was shown has to be what is deleted — an overlap rule computed on\n * this side would diverge from it. Ids that no longer resolve are skipped: a share revoked between\n * the dialog opening and the confirm is nothing to undo.\n *\n * The replacement is a new {@link ShareId}: a recipient who had hidden the old share sees the new\n * one, and copies already taken from the old share are untouched.\n */\nexport type ShareReplaceOption = ShareId[];\n\n/** Options for {@link MiddleLayer.shareProjects}: the common ones, plus what the recipient's app\n *  does with the projects. */\nexport type ShareProjectsOptions = ShareOptions & { mode: EnvelopeMode };\n\n/** Options for {@link MiddleLayer.shareTemplate}. */\nexport type ShareTemplateOptions = ShareOptions;\n\n/** Options for {@link MiddleLayer.shareFolder}. */\nexport type ShareFolderOptions = ShareOptions;\n\n/** What creating a share hands back: the id of the share just created. */\nexport type ShareOutcome = { readonly shareId: ShareId };\n\n//\n// Internals\n//\n\n/** Every payload kind this build can act on; anything else is hidden rather than offered.\n *  Keyed by {@link EnvelopePayloadKind}, so adding a kind to {@link EnvelopePayload} without\n *  teaching the decoder about it is a compile error, not a share that silently disappears. */\nconst KnownPayloadKinds: Record<EnvelopePayloadKind, true> = {\n  projects: true,\n  template: true,\n  folder: true,\n};\n\n/** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by\n *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape\n *  is upcast is a compile error. */\nconst ReadableSchemaVersions: Record<EnvelopeSchemaVersion, true> = {\n  1: true,\n  2: true,\n};\n\n/**\n * The envelope blob as it comes off the wire, before {@link normalizeEnvelopeData} decides\n * whether this build can act on it: the version is any number, the payload may be missing,\n * and `projects` is the v1 top-level project map.\n */\ntype RawEnvelopeData = Omit<EnvelopeData, \"schemaVersion\" | \"payload\"> & {\n  schemaVersion: number;\n  payload?: EnvelopePayload;\n  projects?: Record<ProjectFieldUuid, EnvelopeProject>;\n};\n"],"mappings":";;;;AAqBA,SAAgB,aAAsB;CACpC,QAAA,GAAA,YAAA,WAAA,CAAkB;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;AAS3F,SAAgB,sBAAwC;CACtD,QAAA,GAAA,YAAA,WAAA,CAAkB;AACpB;;;;;;;AAQA,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAsBA,SAAgB,sBAAwC;CACtD,QAAA,GAAA,YAAA,WAAA,CAAkB;AACpB;;AA4EA,MAAa,+BAA+B;;;AAsB5C,SAAgB,mBAAmB,MAA+D;CAChG,OAAO,KAAK,QAAQ,SAAS,aAAa,KAAK,QAAQ,WAAW,CAAC;AACrE;;;;;;;;AASA,SAAgB,mBACd,SAC8B;CAC9B,MAAM,QAAS,OAAO,KAAK,OAAO,CAAC,CAAwB,QACxD,OAAO,QAAQ,GAAG,CAAC,WAAW,KAAA,CACjC;CACA,OAAO,MAAM,WAAW,IAAI,MAAM,KAAK,KAAA;AACzC;;;;;;;;;;;;;;AAeA,MAAa,oBAAoB;AACjC,MAAa,eAAe,YAAqB,GAAG,oBAAoB;AACxE,MAAa,iBAAiB,SAAiB,KAAK,WAAW,iBAAiB;AAChF,MAAa,sBAAsB,SACjC,UAAU,KAAK,MAAM,CAAwB,CAAC;;;;;;;;;;AAgBhD,SAAgB,mBAAmB,MAA4C;CAC7E,OAAO,sBAAsB,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC;AAC9E;;;;;;;;;;AAWA,SAAgB,sBAAsB,KAAwC;CAC5E,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM,OAAO,KAAA;CACpD,MAAM,IAAI;CACV,IAAI,CAAC,OAAO,OAAO,wBAAwB,EAAE,aAAa,GAAG,OAAO,KAAA;CAEpE,MAAM,UACJ,EAAE,YACD,EAAE,aAAa,KAAA,IAAa;EAAE,MAAM;EAAY,UAAU,EAAE;CAAS,IAAc,KAAA;CACtF,IAAI,YAAY,KAAA,GAAW,OAAO,KAAA;CAClC,IAAI,CAAC,OAAO,OAAO,mBAAmB,QAAQ,IAAI,GAAG,OAAO,KAAA;CAE5D,OAAO;EACL,eAAA;EACA,SAAS,EAAE;EACX,UAAU,EAAE;EACZ,WAAW,EAAE;EACb,MAAM,EAAE;EACR,QAAQ,EAAE;EACV,OAAO,EAAE;EACT;CACF;AACF;;;;AAyDA,MAAM,oBAAuD;CAC3D,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;AAKA,MAAM,yBAA8D;CAClE,GAAG;CACH,GAAG;AACL"}
+{"version":3,"file":"sharing_model.cjs","names":["randomUUID","RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type {\n  Branded,\n  ProjectId,\n  ProjectTemplateV1,\n  TemplateId,\n} from \"@milaboratories/pl-model-common\";\nimport type { FolderId } from \"@milaboratories/pl-model-middle-layer\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Identity of one share. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the recipient's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/** Mints a fresh {@link ProjectFieldUuid} for one snapshot. */\nexport function newProjectFieldUuid(): ProjectFieldUuid {\n  return randomUUID() as ProjectFieldUuid;\n}\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in a\n *  `projects` {@link EnvelopePayload}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the share lists render without traversing into the project\n  source: ProjectId; // donor's source projectId; what a prior share of the same project is matched on\n  updatedAt: number; // ms epoch of the last (re)snapshot\n  /** What the project said about itself when it was snapshotted, carried for the same reason as\n   *  `label`. Absent when it had none, and on envelopes written before it was carried. */\n  description?: string;\n}\n\n/**\n * Identifier of a folder inside one envelope.\n *\n * Local to the envelope, because the recipient's own folder document mints its own ids and the\n * donor's mean nothing there. What travels is the shape of the subtree, not its identity.\n */\nexport type EnvelopeFolderId = Branded<string, \"EnvelopeFolderId\">;\n\n/** Mints a fresh {@link EnvelopeFolderId} for one folder of the envelope being built. */\nexport function newEnvelopeFolderId(): EnvelopeFolderId {\n  return randomUUID() as EnvelopeFolderId;\n}\n\n/** One folder of a shared subtree. */\nexport interface EnvelopeFolder {\n  name: string;\n  /** Absent for the subtree's root — the folder that was shared. */\n  parent?: EnvelopeFolderId;\n  /** What the donor wrote about the folder. Absent when there is none. */\n  description?: string;\n}\n\n/** A project of a shared subtree: an {@link EnvelopeProject} placed in the subtree. */\nexport interface EnvelopeFolderProject extends EnvelopeProject {\n  folder: EnvelopeFolderId;\n}\n\n/** A template of a shared subtree. The document rides here whole, exactly as a `template`\n *  payload carries it — a template is never snapshotted. */\nexport interface EnvelopeFolderTemplate {\n  document: ProjectTemplateV1;\n  /** Label to give the template among the recipient's templates. */\n  label: string;\n  /** What the template says about itself. Absent when the donor described it with nothing. */\n  description?: string;\n  folder: EnvelopeFolderId;\n}\n\n/**\n * What a share carries. The discriminant is what a reader checks before anything else: a\n * client that does not know a kind hides the share instead of offering something it cannot\n * act on.\n *\n * `projects` snapshots ride as `project/{uuid}` fields on the envelope and this map only\n * describes them; a `template` payload has no fields at all — the document is right here.\n */\nexport type EnvelopePayload =\n  | { kind: \"projects\"; projects: Record<ProjectFieldUuid, EnvelopeProject> }\n  | {\n      kind: \"template\";\n      document: ProjectTemplateV1;\n      /** Donor's own id of the shared template; what a prior share of the same template is\n       *  matched on. It names nothing in the recipient's tree, and envelopes written before it\n       *  existed carry none — those match no later share of anything. */\n      source?: TemplateId;\n      /** Label to give the template among the recipient's templates. */\n      label: string;\n      /** What the template says about itself, carried to the recipient's copy. Absent when the\n       *  donor described it with nothing. */\n      description?: string;\n      /** Donor login, kept on each copy of the template as its provenance. */\n      from: string;\n    }\n  | {\n      kind: \"folder\";\n      /** Donor's own id of the shared folder; what a prior share of the same folder is matched\n       *  on. It names nothing in the recipient's tree. */\n      source: FolderId;\n      /** The shared subtree. Exactly one folder has no parent, and that one is its root. */\n      folders: Record<EnvelopeFolderId, EnvelopeFolder>;\n      /** Project snapshots, each tagged with the folder of the subtree holding it. Their\n       *  `project/{uuid}` fields are the same ones a `projects` payload describes. */\n      projects: Record<ProjectFieldUuid, EnvelopeFolderProject>;\n      /** Templates of the subtree, documents and all. Nothing of a template is snapshotted. */\n      templates: EnvelopeFolderTemplate[];\n      /** Donor login, kept on each copied template as its provenance. */\n      from: string;\n    };\n\nexport type EnvelopePayloadKind = EnvelopePayload[\"kind\"];\n\n/** Every envelope schema version this build can read. Adding a version here is what makes\n *  {@link normalizeEnvelopeData} accept it; bumping {@link EnvelopeSchemaVersionCurrent} to a\n *  version missing from this union is a compile error. */\nexport type EnvelopeSchemaVersion = 1 | 2;\n\n/** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */\nexport const EnvelopeSchemaVersionCurrent = 2 satisfies EnvelopeSchemaVersion;\n\n/**\n * Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated.\n *\n * Always the current version in memory: a v1 envelope (project map at the top level, no\n * `payload` field) is upcast on read by {@link normalizeEnvelopeData}, so no reader past the\n * decode has to know that two shapes ever existed.\n */\nexport interface EnvelopeData {\n  schemaVersion: typeof EnvelopeSchemaVersionCurrent;\n  shareId: ShareId; // donor-generated UUID; identity of this share alone\n  sharedAt: number; // ms epoch; when the share was created\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the recipient's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  payload: EnvelopePayload; // what the share carries\n}\n\n/** The project map of a projects-payload envelope, or `{}` for any other payload — the one\n *  place a project-shaped reader turns a payload into the map it expects. */\nexport function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject> {\n  return data.payload.kind === \"projects\" ? data.payload.projects : {};\n}\n\n/**\n * The shared folder itself: the one folder of the subtree that has no parent.\n *\n * Derived rather than stored, so it cannot disagree with the folders beside it. `undefined` for\n * a subtree with no root or more than one, which is an envelope nothing can be reconstructed\n * from — the copy reports it rather than guessing which folder was meant.\n */\nexport function envelopeFolderRoot(\n  folders: Record<EnvelopeFolderId, EnvelopeFolder>,\n): EnvelopeFolderId | undefined {\n  const roots = (Object.keys(folders) as EnvelopeFolderId[]).filter(\n    (id) => folders[id].parent === undefined,\n  );\n  return roots.length === 1 ? roots[0] : undefined;\n}\n\n/**\n * Dynamic field on SharingState, one per share this user has hidden, keyed by shareId.\n *\n * Hiding is private to the recipient and reversible: the field is written to put a share out of\n * sight and removed to bring it back. It says nothing to the donor and nothing about whether\n * anything was ever copied out of the share — a share can be copied from any number of times,\n * before or after being hidden.\n *\n * The field name keeps its original `decision/` prefix. Records written before hiding replaced\n * accept/reject carry a different value under the same key, and every reader treats the presence\n * of the field as the whole answer: someone who accepted or rejected a share back then does not\n * want to see it, which is exactly what hidden means.\n */\nexport const HiddenFieldPrefix = \"decision/\";\nexport const hiddenField = (shareId: ShareId) => `${HiddenFieldPrefix}${shareId}`;\nexport const isHiddenField = (name: string) => name.startsWith(HiddenFieldPrefix);\nexport const hiddenFieldShareId = (name: string): ShareId =>\n  asShareId(name.slice(HiddenFieldPrefix.length));\n\nexport interface ShareHidden {\n  hidden: true;\n  timestamp: number; // ms epoch — when the recipient hid it\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path decodes the same JSON with `getDataAsJson` and normalizes it with\n * {@link normalizeEnvelopeData} — both paths must, so neither sees the raw v1 shape.\n *\n * `undefined` for an envelope this build cannot act on; see {@link normalizeEnvelopeData}.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData | undefined {\n  return normalizeEnvelopeData(JSON.parse(Buffer.from(data).toString(\"utf-8\")));\n}\n\n/**\n * Brings a decoded envelope blob to the current shape, or reports that this build cannot act\n * on it by returning `undefined` — an unknown `schemaVersion` or an unknown payload kind. A\n * caller hides such a share rather than offering the recipient something it cannot handle.\n *\n * A v1 envelope carried its project map at the top level and had no `payload` field; it reads\n * here as a `projects` payload, so envelopes written before the discriminant existed keep\n * working unchanged.\n */\nexport function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined {\n  if (typeof raw !== \"object\" || raw === null) return undefined;\n  const e = raw as RawEnvelopeData;\n  if (!Object.hasOwn(ReadableSchemaVersions, e.schemaVersion)) return undefined;\n\n  const payload =\n    e.payload ??\n    (e.projects !== undefined ? ({ kind: \"projects\", projects: e.projects } as const) : undefined);\n  if (payload === undefined) return undefined;\n  if (!Object.hasOwn(KnownPayloadKinds, payload.kind)) return undefined;\n\n  return {\n    schemaVersion: EnvelopeSchemaVersionCurrent,\n    shareId: e.shareId,\n    sharedAt: e.sharedAt,\n    expiresAt: e.expiresAt,\n    mode: e.mode,\n    sender: e.sender,\n    title: e.title,\n    payload,\n  };\n}\n\n/**\n * Who a share is granted to: named recipients XOR everyone — two clean variants, not one struct\n * with mutually exclusive optional fields.\n *\n * The everyone variant issues a single make-public grant, and the envelope's `expiresAt` is `null`,\n * so it never expires. The recipients variant grants each named login, and the envelope expires\n * after the default TTL.\n */\nexport type ShareAudience =\n  | { recipients: string[] } // recipient logins\n  | { everyone: true }; // every user on the server\n\n/**\n * Options every share takes: the audience, the title recipients see it under, and the prior\n * shares it replaces.\n */\nexport type ShareOptions = ShareAudience & {\n  title: string;\n  replace?: ShareReplaceOption;\n};\n\n/**\n * Prior shares the new one supersedes: each is deleted in the same transaction that creates the\n * replacement, so the outbox never holds both.\n *\n * The set is the caller's, never inferred here. The author is shown the shares that will go and\n * agrees to that list, so what was shown has to be what is deleted — an overlap rule computed on\n * this side would diverge from it. Ids that no longer resolve are skipped: a share revoked between\n * the dialog opening and the confirm is nothing to undo.\n *\n * The replacement is a new {@link ShareId}: a recipient who had hidden the old share sees the new\n * one, and copies already taken from the old share are untouched.\n */\nexport type ShareReplaceOption = ShareId[];\n\n/** Options for {@link MiddleLayer.shareProjects}: the common ones, plus what the recipient's app\n *  does with the projects. */\nexport type ShareProjectsOptions = ShareOptions & { mode: EnvelopeMode };\n\n/** Options for {@link MiddleLayer.shareTemplate}. */\nexport type ShareTemplateOptions = ShareOptions;\n\n/** Options for {@link MiddleLayer.shareFolder}. */\nexport type ShareFolderOptions = ShareOptions;\n\n/** What creating a share hands back: the id of the share just created. */\nexport type ShareOutcome = { readonly shareId: ShareId };\n\n//\n// Internals\n//\n\n/** Every payload kind this build can act on; anything else is hidden rather than offered.\n *  Keyed by {@link EnvelopePayloadKind}, so adding a kind to {@link EnvelopePayload} without\n *  teaching the decoder about it is a compile error, not a share that silently disappears. */\nconst KnownPayloadKinds: Record<EnvelopePayloadKind, true> = {\n  projects: true,\n  template: true,\n  folder: true,\n};\n\n/** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by\n *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape\n *  is upcast is a compile error. */\nconst ReadableSchemaVersions: Record<EnvelopeSchemaVersion, true> = {\n  1: true,\n  2: true,\n};\n\n/**\n * The envelope blob as it comes off the wire, before {@link normalizeEnvelopeData} decides\n * whether this build can act on it: the version is any number, the payload may be missing,\n * and `projects` is the v1 top-level project map.\n */\ntype RawEnvelopeData = Omit<EnvelopeData, \"schemaVersion\" | \"payload\"> & {\n  schemaVersion: number;\n  payload?: EnvelopePayload;\n  projects?: Record<ProjectFieldUuid, EnvelopeProject>;\n};\n"],"mappings":";;;;AAqBA,SAAgB,aAAsB;CACpC,QAAA,GAAOA,YAAAA,WAAAA,CAAW;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;AAS3F,SAAgB,sBAAwC;CACtD,QAAA,GAAOA,YAAAA,WAAAA,CAAW;AACpB;;;;;;;AAQA,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKC,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAsBA,SAAgB,sBAAwC;CACtD,QAAA,GAAOD,YAAAA,WAAAA,CAAW;AACpB;;AA4EA,MAAa,+BAA+B;;;AAsB5C,SAAgB,mBAAmB,MAA+D;CAChG,OAAO,KAAK,QAAQ,SAAS,aAAa,KAAK,QAAQ,WAAW,CAAC;AACrE;;;;;;;;AASA,SAAgB,mBACd,SAC8B;CAC9B,MAAM,QAAS,OAAO,KAAK,OAAO,CAAC,CAAwB,QACxD,OAAO,QAAQ,GAAG,CAAC,WAAW,KAAA,CACjC;CACA,OAAO,MAAM,WAAW,IAAI,MAAM,KAAK,KAAA;AACzC;;;;;;;;;;;;;;AAeA,MAAa,oBAAoB;AACjC,MAAa,eAAe,YAAqB,GAAG,oBAAoB;AACxE,MAAa,iBAAiB,SAAiB,KAAK,WAAW,iBAAiB;AAChF,MAAa,sBAAsB,SACjC,UAAU,KAAK,MAAM,CAAwB,CAAC;;;;;;;;;;AAgBhD,SAAgB,mBAAmB,MAA4C;CAC7E,OAAO,sBAAsB,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC;AAC9E;;;;;;;;;;AAWA,SAAgB,sBAAsB,KAAwC;CAC5E,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM,OAAO,KAAA;CACpD,MAAM,IAAI;CACV,IAAI,CAAC,OAAO,OAAO,wBAAwB,EAAE,aAAa,GAAG,OAAO,KAAA;CAEpE,MAAM,UACJ,EAAE,YACD,EAAE,aAAa,KAAA,IAAa;EAAE,MAAM;EAAY,UAAU,EAAE;CAAS,IAAc,KAAA;CACtF,IAAI,YAAY,KAAA,GAAW,OAAO,KAAA;CAClC,IAAI,CAAC,OAAO,OAAO,mBAAmB,QAAQ,IAAI,GAAG,OAAO,KAAA;CAE5D,OAAO;EACL,eAAA;EACA,SAAS,EAAE;EACX,UAAU,EAAE;EACZ,WAAW,EAAE;EACb,MAAM,EAAE;EACR,QAAQ,EAAE;EACV,OAAO,EAAE;EACT;CACF;AACF;;;;AAyDA,MAAM,oBAAuD;CAC3D,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;AAKA,MAAM,yBAA8D;CAClE,GAAG;CACH,GAAG;AACL"}

package/dist/model/sharing_model.d.ts

@@ -1,7 +1,6 @@
 import { FolderId } from "@milaboratories/pl-model-middle-layer";
 import { Branded, ProjectId, ProjectTemplateV1, TemplateId } from "@milaboratories/pl-model-common";
 import { ResourceType, Role } from "@milaboratories/pl-client";
-//#region src/model/sharing_model.d.ts
 /**
  * Identity of one share. A donor-generated UUID string,
  * branded so it cannot be silently confused with a project id, a login, or a raw field
@@ -249,5 +248,4 @@ export type ShareFolderOptions = ShareOptions;
 export type ShareOutcome = {
   readonly shareId: ShareId;
 };
-//#endregion
 //# sourceMappingURL=sharing_model.d.ts.map

package/dist/model/sharing_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharing_model.d.ts","names":[],"sources":["../../src/model/sharing_model.ts"],"mappings":";;;;;;;;;;;YAkBY,UAAU;;wBAGN,cAAc;;;wBAMd,UAAU,aAAa;;qBAY1B;;qBAEA;qBAEA,2BAA2B;qBAC3B,4BAA4B;qBAC5B,0BAA0B;YAE3B;;;YAIA,mBAAmB;;wBAGf,uBAAuB;;;;;;;wBAUvB,mBAAmB,MAAM;;;;;;;;;;wBAmBzB,eAAe,MAAM;;;iBAYpB;EACf;EACA,QAAQ;EACR;;;EAGA;;;;;;;;YASU,mBAAmB;;wBAGf,uBAAuB;;iBAKtB;EACf;;EAEA,SAAS;;EAET;;;iBAIe,8BAA8B;EAC7C,QAAQ;;;;iBAKO;EACf,UAAU;;EAEV;;EAEA;EACA,QAAQ;;;;;;;;;;YAWE;EACN;EAAkB,UAAU,OAAO,kBAAkB;;EAErD;EACA,UAAU;;;;EAIV,SAAS;;EAET;;;EAGA;;EAEA;;EAGA;;;EAGA,QAAQ;;EAER,SAAS,OAAO,kBAAkB;;;EAGlC,UAAU,OAAO,kBAAkB;;EAEnC,WAAW;;EAEX;;YAGM,sBAAsB;;;;YAKtB;;qBAGC;;;;;;;;iBASI;EACf,sBAAsB;EACtB,SAAS;EACT;EACA;EACA,MAAM;EACN;EACA;EACA,SAAS;;;;wBAKK,mBAAmB,MAAM,eAAe,OAAO,kBAAkB;;;;;;;;wBAWjE,mBACd,SAAS,OAAO,kBAAkB,kBACjC;;;;;;;;;;;;;;qBAoBU;qBACA,cAAW,SAAa;qBACxB,gBAAa;qBACb,qBAAkB,iBAAmB;iBAGjC;EACf;EACA;;;;;;;;;;;wBAYc,mBAAmB,MAAM,aAAa;;;;;;;;;;wBAatC,sBAAsB,eAAe;;;;;;;;;YA+BzC;EACN;;EACA;;;;;;YAMM,eAAe;EACzB;EACA,UAAU;;;;;;;;;;;;;;YAeA,qBAAqB;;;YAIrB,uBAAuB;EAAiB,MAAM;;;YAG9C,uBAAuB;;YAGvB,qBAAqB;;YAGrB;WAA0B,SAAS"}
+{"version":3,"file":"sharing_model.d.ts","names":[],"sources":["../../src/model/sharing_model.ts"],"mappings":";;;;;;;;;;YAkBY,UAAU;;wBAGN,cAAc;;;wBAMd,UAAU,aAAa;;qBAY1B;;qBAEA;qBAEA,2BAA2B;qBAC3B,4BAA4B;qBAC5B,0BAA0B;YAE3B;;;YAIA,mBAAmB;;wBAGf,uBAAuB;;;;;;;wBAUvB,mBAAmB,MAAM;;;;;;;;;;wBAmBzB,eAAe,MAAM;;;iBAYpB;EACf;EACA,QAAQ;EACR;;;EAGA;;;;;;;;YASU,mBAAmB;;wBAGf,uBAAuB;;iBAKtB;EACf;;EAEA,SAAS;;EAET;;;iBAIe,8BAA8B;EAC7C,QAAQ;;;;iBAKO;EACf,UAAU;;EAEV;;EAEA;EACA,QAAQ;;;;;;;;;;YAWE;EACN;EAAkB,UAAU,OAAO,kBAAkB;;EAErD;EACA,UAAU;;;;EAIV,SAAS;;EAET;;;EAGA;;EAEA;;EAGA;;;EAGA,QAAQ;;EAER,SAAS,OAAO,kBAAkB;;;EAGlC,UAAU,OAAO,kBAAkB;;EAEnC,WAAW;;EAEX;;YAGM,sBAAsB;;;;YAKtB;;qBAGC;;;;;;;;iBASI;EACf,sBAAsB;EACtB,SAAS;EACT;EACA;EACA,MAAM;EACN;EACA;EACA,SAAS;;;;wBAKK,mBAAmB,MAAM,eAAe,OAAO,kBAAkB;;;;;;;;wBAWjE,mBACd,SAAS,OAAO,kBAAkB,kBACjC;;;;;;;;;;;;;;qBAoBU;qBACA,cAAW,SAAa;qBACxB,gBAAa;qBACb,qBAAkB,iBAAmB;iBAGjC;EACf;EACA;;;;;;;;;;;wBAYc,mBAAmB,MAAM,aAAa;;;;;;;;;;wBAatC,sBAAsB,eAAe;;;;;;;;;YA+BzC;EACN;;EACA;;;;;;YAMM,eAAe;EACzB;EACA,UAAU;;;;;;;;;;;;;;YAeA,qBAAqB;;;YAIrB,uBAAuB;EAAiB,MAAM;;;YAG9C,uBAAuB;;YAGvB,qBAAqB;;YAGrB;WAA0B,SAAS"}

package/dist/model/sharing_model.js

@@ -1,6 +1,6 @@
 import { Role } from "@milaboratories/pl-client";
 import { randomUUID } from "node:crypto";
-//#region src/model/sharing_model.ts
+// src/model/sharing_model.ts
 /** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
 function newShareId() {
 	return randomUUID();
@@ -155,7 +155,6 @@ const ReadableSchemaVersions = {
 	1: true,
 	2: true
 };
-//#endregion
 export { EnvelopeSchemaVersionCurrent, HiddenFieldPrefix, SharedEnvelopeResourceType, SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, asShareId, canGrantToEveryone, canImpersonate, decodeEnvelopeData, envelopeFolderRoot, envelopeProjectMap, hiddenField, hiddenFieldShareId, isHiddenField, newEnvelopeFolderId, newProjectFieldUuid, newShareId, normalizeEnvelopeData };
 
 //# sourceMappingURL=sharing_model.js.map

package/dist/model/template_apply.cjs

@@ -4,7 +4,7 @@ let _platforma_sdk_block_tools = require("@platforma-sdk/block-tools");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
 let semver = require("semver");
 semver = require_runtime.__toESM(semver, 1);
-//#region src/model/template_apply.ts
+// src/model/template_apply.ts
 /**
 * One entry the file describes in a way this project cannot honour.
 *
@@ -60,7 +60,6 @@ function kindMismatch(asked, declared) {
 	if (wanted.name !== has.name) return `This entry asks for kind '${wanted.name}', but the block resolved for it implements '${has.name}'`;
 	if (!semver.satisfies(has.version, (0, _platforma_sdk_block_tools.selectorToRange)(wanted.selector))) return `This entry asks for '${asked}', but the block resolved for it implements version ${has.version} of that kind`;
 }
-//#endregion
 exports.TemplateEntryRejected = TemplateEntryRejected;
 exports.kindMismatch = kindMismatch;
 

package/dist/model/template_apply.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"template_apply.cjs","names":[],"sources":["../../src/model/template_apply.ts"],"sourcesContent":["import type {\n  BlockKindReference,\n  BlockKindSelectorReference,\n} from \"@milaboratories/pl-model-common\";\nimport { parseKindRef, parseKindSelectorReference } from \"@milaboratories/pl-model-common\";\nimport { selectorToRange } from \"@platforma-sdk/block-tools\";\nimport { ensureError } from \"@platforma-sdk/model\";\nimport * as semver from \"semver\";\n\n/**\n * One entry the file describes in a way this project cannot honour.\n *\n * Thrown, not returned, and that is the whole failure policy: an apply either creates every\n * entry or creates none. It travels out through the open transaction, which is therefore\n * never committed, so a rejected file leaves the project exactly as it was. The caller turns\n * it into a {@link TemplateApplyProblem}; anything else reaching that caller is an outage\n * rather than a statement about the file, and keeps propagating.\n */\nexport class TemplateEntryRejected extends Error {\n  constructor(\n    readonly entryId: string,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"TemplateEntryRejected\";\n  }\n}\n\n/**\n * Something that stopped one entry from being applied.\n *\n * Every stage of an apply reports in this shape — resolution, validation,\n * construction — so a caller assembles one list and the reader sees which entry in\n * their file each problem belongs to. `error` is a finished sentence for the person\n * who applied the file, not a code.\n */\nexport type TemplateApplyProblem = {\n  /** The template-local id of the entry the problem belongs to. */\n  readonly entryId: string;\n  readonly error: string;\n};\n\n/** One entry that made it into the project. */\nexport type AppliedEntry = {\n  /** The entry's id in the file. */\n  readonly templateLocalId: string;\n  /** The project-local id the block was given. */\n  readonly blockId: string;\n};\n\n/**\n * What a whole apply — reading, checking, resolving, placing — left behind.\n *\n * One shape for every stage's findings, because the reader does not care which stage\n * objected. `problems` empty means the project holds exactly what the document described;\n * otherwise `added` is empty, because no stage creates anything until every entry has passed.\n *\n * A stage that checks reports every problem it found, so a file with three mistakes takes one\n * pass to fix. Placement stops at the first one — hence at most one problem from there.\n */\nexport type TemplateApplyReport = {\n  readonly added: readonly AppliedEntry[];\n  readonly problems: readonly TemplateApplyProblem[];\n};\n\n/**\n * Why the block prepared for an entry cannot serve it, or `undefined` when it can.\n *\n * An entry's `kind` is the contract its params are written against, so the block that ends up\n * installed has to implement it. Only one of the three routes to a block gives that for free:\n * kind resolution, where the kind's own projection picks the block. The two overrides do not —\n * a location's folder can change without the file changing, and a pinned version names a\n * package with no reference to a kind at all.\n *\n * So this belongs here, with the apply's other per-entry checks, and not in resolution: it is\n * asked once, of the block that was actually prepared, whichever route found it. Resolution\n * could answer it for a location — `byLocation` reads the block's config anyway — and doing so\n * there would have been a second place stating the same invariant, with the pinned-version\n * route still uncovered. One caller is the point.\n *\n * It is also the check that makes the params check meaningful, so it is asked first: params are\n * checked by the INSTALLED block's kind parser, which against a block of the wrong kind would\n * hold params written for one contract against another.\n *\n * Version comparison goes through the same selector-to-range translation the registry resolver\n * uses, so \"this resolves locally\" and \"this would resolve once published\" cannot disagree\n * about the version math.\n *\n * Messages name no route, so a caller adds whichever locator the entry carried.\n */\nexport function kindMismatch(\n  asked: BlockKindSelectorReference,\n  declared: BlockKindReference | undefined,\n): string | undefined {\n  if (declared === undefined) {\n    return (\n      \"The block resolved for this entry declares no kind, so it cannot be the \" +\n      \"implementation it asks for\"\n    );\n  }\n\n  let wanted: { name: string; selector: { op: \"exact\" | \"patch\" | \"minor\"; version: string } };\n  let has: { name: string; version: string };\n  try {\n    wanted = parseKindSelectorReference(asked);\n    has = parseKindRef(declared);\n  } catch (e) {\n    // The entry's own selector was checked when the document was parsed, so this is the\n    // block's stored reference being unreadable.\n    return `The block resolved for this entry declares an unreadable kind: ${ensureError(e).message}`;\n  }\n\n  if (wanted.name !== has.name) {\n    return (\n      `This entry asks for kind '${wanted.name}', but the block resolved for it ` +\n      `implements '${has.name}'`\n    );\n  }\n\n  if (!semver.satisfies(has.version, selectorToRange(wanted.selector))) {\n    return (\n      `This entry asks for '${asked}', but the block resolved for it implements ` +\n      `version ${has.version} of that kind`\n    );\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,IAAa,wBAAb,cAA2C,MAAM;CAEpC;CADX,YACE,SACA,SACA;EACA,MAAM,OAAO;EAHJ,KAAA,UAAA;EAIT,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,aACd,OACA,UACoB;CACpB,IAAI,aAAa,KAAA,GACf,OACE;CAKJ,IAAI;CACJ,IAAI;CACJ,IAAI;EACF,UAAA,GAAA,gCAAA,2BAAA,CAAoC,KAAK;EACzC,OAAA,GAAA,gCAAA,aAAA,CAAmB,QAAQ;CAC7B,SAAS,GAAG;EAGV,OAAO,mEAAA,GAAA,qBAAA,YAAA,CAA8E,CAAC,CAAC,CAAC;CAC1F;CAEA,IAAI,OAAO,SAAS,IAAI,MACtB,OACE,6BAA6B,OAAO,KAAK,+CAC1B,IAAI,KAAK;CAI5B,IAAI,CAAC,OAAO,UAAU,IAAI,UAAA,GAAA,2BAAA,gBAAA,CAAyB,OAAO,QAAQ,CAAC,GACjE,OACE,wBAAwB,MAAM,sDACnB,IAAI,QAAQ;AAK7B"}
+{"version":3,"file":"template_apply.cjs","names":["parseKindSelectorReference","parseKindRef","ensureError","selectorToRange"],"sources":["../../src/model/template_apply.ts"],"sourcesContent":["import type {\n  BlockKindReference,\n  BlockKindSelectorReference,\n} from \"@milaboratories/pl-model-common\";\nimport { parseKindRef, parseKindSelectorReference } from \"@milaboratories/pl-model-common\";\nimport { selectorToRange } from \"@platforma-sdk/block-tools\";\nimport { ensureError } from \"@platforma-sdk/model\";\nimport * as semver from \"semver\";\n\n/**\n * One entry the file describes in a way this project cannot honour.\n *\n * Thrown, not returned, and that is the whole failure policy: an apply either creates every\n * entry or creates none. It travels out through the open transaction, which is therefore\n * never committed, so a rejected file leaves the project exactly as it was. The caller turns\n * it into a {@link TemplateApplyProblem}; anything else reaching that caller is an outage\n * rather than a statement about the file, and keeps propagating.\n */\nexport class TemplateEntryRejected extends Error {\n  constructor(\n    readonly entryId: string,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"TemplateEntryRejected\";\n  }\n}\n\n/**\n * Something that stopped one entry from being applied.\n *\n * Every stage of an apply reports in this shape — resolution, validation,\n * construction — so a caller assembles one list and the reader sees which entry in\n * their file each problem belongs to. `error` is a finished sentence for the person\n * who applied the file, not a code.\n */\nexport type TemplateApplyProblem = {\n  /** The template-local id of the entry the problem belongs to. */\n  readonly entryId: string;\n  readonly error: string;\n};\n\n/** One entry that made it into the project. */\nexport type AppliedEntry = {\n  /** The entry's id in the file. */\n  readonly templateLocalId: string;\n  /** The project-local id the block was given. */\n  readonly blockId: string;\n};\n\n/**\n * What a whole apply — reading, checking, resolving, placing — left behind.\n *\n * One shape for every stage's findings, because the reader does not care which stage\n * objected. `problems` empty means the project holds exactly what the document described;\n * otherwise `added` is empty, because no stage creates anything until every entry has passed.\n *\n * A stage that checks reports every problem it found, so a file with three mistakes takes one\n * pass to fix. Placement stops at the first one — hence at most one problem from there.\n */\nexport type TemplateApplyReport = {\n  readonly added: readonly AppliedEntry[];\n  readonly problems: readonly TemplateApplyProblem[];\n};\n\n/**\n * Why the block prepared for an entry cannot serve it, or `undefined` when it can.\n *\n * An entry's `kind` is the contract its params are written against, so the block that ends up\n * installed has to implement it. Only one of the three routes to a block gives that for free:\n * kind resolution, where the kind's own projection picks the block. The two overrides do not —\n * a location's folder can change without the file changing, and a pinned version names a\n * package with no reference to a kind at all.\n *\n * So this belongs here, with the apply's other per-entry checks, and not in resolution: it is\n * asked once, of the block that was actually prepared, whichever route found it. Resolution\n * could answer it for a location — `byLocation` reads the block's config anyway — and doing so\n * there would have been a second place stating the same invariant, with the pinned-version\n * route still uncovered. One caller is the point.\n *\n * It is also the check that makes the params check meaningful, so it is asked first: params are\n * checked by the INSTALLED block's kind parser, which against a block of the wrong kind would\n * hold params written for one contract against another.\n *\n * Version comparison goes through the same selector-to-range translation the registry resolver\n * uses, so \"this resolves locally\" and \"this would resolve once published\" cannot disagree\n * about the version math.\n *\n * Messages name no route, so a caller adds whichever locator the entry carried.\n */\nexport function kindMismatch(\n  asked: BlockKindSelectorReference,\n  declared: BlockKindReference | undefined,\n): string | undefined {\n  if (declared === undefined) {\n    return (\n      \"The block resolved for this entry declares no kind, so it cannot be the \" +\n      \"implementation it asks for\"\n    );\n  }\n\n  let wanted: { name: string; selector: { op: \"exact\" | \"patch\" | \"minor\"; version: string } };\n  let has: { name: string; version: string };\n  try {\n    wanted = parseKindSelectorReference(asked);\n    has = parseKindRef(declared);\n  } catch (e) {\n    // The entry's own selector was checked when the document was parsed, so this is the\n    // block's stored reference being unreadable.\n    return `The block resolved for this entry declares an unreadable kind: ${ensureError(e).message}`;\n  }\n\n  if (wanted.name !== has.name) {\n    return (\n      `This entry asks for kind '${wanted.name}', but the block resolved for it ` +\n      `implements '${has.name}'`\n    );\n  }\n\n  if (!semver.satisfies(has.version, selectorToRange(wanted.selector))) {\n    return (\n      `This entry asks for '${asked}', but the block resolved for it implements ` +\n      `version ${has.version} of that kind`\n    );\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,IAAa,wBAAb,cAA2C,MAAM;CAEpC;CADX,YACE,SACA,SACA;EACA,MAAM,OAAO;EAHJ,KAAA,UAAA;EAIT,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,aACd,OACA,UACoB;CACpB,IAAI,aAAa,KAAA,GACf,OACE;CAKJ,IAAI;CACJ,IAAI;CACJ,IAAI;EACF,UAAA,GAASA,gCAAAA,2BAAAA,CAA2B,KAAK;EACzC,OAAA,GAAMC,gCAAAA,aAAAA,CAAa,QAAQ;CAC7B,SAAS,GAAG;EAGV,OAAO,mEAAA,GAAkEC,qBAAAA,YAAAA,CAAY,CAAC,CAAC,CAAC;CAC1F;CAEA,IAAI,OAAO,SAAS,IAAI,MACtB,OACE,6BAA6B,OAAO,KAAK,+CAC1B,IAAI,KAAK;CAI5B,IAAI,CAAC,OAAO,UAAU,IAAI,UAAA,GAASC,2BAAAA,gBAAAA,CAAgB,OAAO,QAAQ,CAAC,GACjE,OACE,wBAAwB,MAAM,sDACnB,IAAI,QAAQ;AAK7B"}

package/dist/model/template_apply.d.ts

@@ -1,5 +1,4 @@
 import { BlockKindReference, BlockKindSelectorReference } from "@milaboratories/pl-model-common";
-//#region src/model/template_apply.d.ts
 /**
  * One entry the file describes in a way this project cannot honour.
  *
@@ -47,5 +46,4 @@ export type TemplateApplyReport = {
   readonly added: readonly AppliedEntry[];
   readonly problems: readonly TemplateApplyProblem[];
 };
-//#endregion
 //# sourceMappingURL=template_apply.d.ts.map

package/dist/model/template_apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template_apply.d.ts","names":[],"sources":["../../src/model/template_apply.ts"],"mappings":";;;;;;;;;;;qBAkBa,8BAA8B;WAE9B;EADX,YACW,iBACT;;;;;;;;;;YAeQ;;WAED;WACA;;;YAIC;;WAED;;WAEA;;;;;;;;;;;;YAaC;WACD,gBAAgB;WAChB,mBAAmB"}
+{"version":3,"file":"template_apply.d.ts","names":[],"sources":["../../src/model/template_apply.ts"],"mappings":";;;;;;;;;;qBAkBa,8BAA8B;WAE9B;EADX,YACW,iBACT;;;;;;;;;;YAeQ;;WAED;WACA;;;YAIC;;WAED;;WAEA;;;;;;;;;;;;YAaC;WACD,gBAAgB;WAChB,mBAAmB"}

package/dist/model/template_apply.js

@@ -2,7 +2,7 @@ import { ensureError } from "@platforma-sdk/model";
 import { selectorToRange } from "@platforma-sdk/block-tools";
 import { parseKindRef, parseKindSelectorReference } from "@milaboratories/pl-model-common";
 import * as semver from "semver";
-//#region src/model/template_apply.ts
+// src/model/template_apply.ts
 /**
 * One entry the file describes in a way this project cannot honour.
 *
@@ -58,7 +58,6 @@ function kindMismatch(asked, declared) {
 	if (wanted.name !== has.name) return `This entry asks for kind '${wanted.name}', but the block resolved for it implements '${has.name}'`;
 	if (!semver.satisfies(has.version, selectorToRange(wanted.selector))) return `This entry asks for '${asked}', but the block resolved for it implements version ${has.version} of that kind`;
 }
-//#endregion
 export { TemplateEntryRejected, kindMismatch };
 
 //# sourceMappingURL=template_apply.js.map

package/dist/model/template_export.cjs

@@ -1,5 +1,5 @@
 const require_project_model_util = require("./project_model_util.cjs");
-//#region src/model/template_export.ts
+// src/model/template_export.ts
 /**
 * Walk a project's blocks in dependency order, collecting each one's
 * template-descriptor output.
@@ -80,7 +80,6 @@ function typeName(value) {
 	if (Array.isArray(value)) return "an array";
 	return `a ${typeof value}`;
 }
-//#endregion
 exports.walkProjectForTemplateExport = walkProjectForTemplateExport;
 
 //# sourceMappingURL=template_export.cjs.map

package/dist/model/template_export.d.ts

@@ -1,5 +1,4 @@
 import "./project_model.js";
-//#region src/model/template_export.d.ts
 /** Why one block could not be exported. */
 export type TemplateExportProblem = {
   readonly blockId: string;
@@ -8,5 +7,4 @@ export type TemplateExportProblem = {
   readonly blockLabel: string;
   readonly error: string;
 };
-//#endregion
 //# sourceMappingURL=template_export.d.ts.map

package/dist/model/template_export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template_export.d.ts","names":[],"sources":["../../src/model/template_export.ts"],"mappings":";;;YAoCY;WACD;;;WAGA;WACA"}
+{"version":3,"file":"template_export.d.ts","names":[],"sources":["../../src/model/template_export.ts"],"mappings":";;YAoCY;WACD;;;WAGA;WACA"}

package/dist/model/template_export.js

@@ -1,5 +1,5 @@
 import { allBlocks } from "./project_model_util.js";
-//#region src/model/template_export.ts
+// src/model/template_export.ts
 /**
 * Walk a project's blocks in dependency order, collecting each one's
 * template-descriptor output.
@@ -80,7 +80,6 @@ function typeName(value) {
 	if (Array.isArray(value)) return "an array";
 	return `a ${typeof value}`;
 }
-//#endregion
 export { walkProjectForTemplateExport };
 
 //# sourceMappingURL=template_export.js.map

package/dist/model/template_parser.cjs

@@ -2,7 +2,7 @@ const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
 let yaml = require("yaml");
 yaml = require_runtime.__toESM(yaml, 1);
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
-//#region src/model/template_parser.ts
+// src/model/template_parser.ts
 /**
 * Read `template-v1` YAML text into a document.
 *
@@ -68,7 +68,6 @@ function describeIssues(issues) {
 	const lines = issues.map((issue) => `- ${(0, _milaboratories_pl_model_common.formatTemplateParseIssue)(issue)}`);
 	return [lines.length === 1 ? "The template file has a problem:" : `The template file has ${lines.length} problems:`, ...lines].join("\n");
 }
-//#endregion
 exports.parseProjectTemplateV1Yaml = parseProjectTemplateV1Yaml;
 
 //# sourceMappingURL=template_parser.cjs.map

package/dist/model/template_parser.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"template_parser.cjs","names":["YAML","PROJECT_TEMPLATE_SCHEMA_V1"],"sources":["../../src/model/template_parser.ts"],"sourcesContent":["import YAML from \"yaml\";\nimport type { ProjectTemplateV1, TemplateParseIssue } from \"@milaboratories/pl-model-common\";\nimport {\n  PROJECT_TEMPLATE_SCHEMA_V1,\n  formatTemplateParseIssue,\n  readProjectTemplateV1,\n} from \"@milaboratories/pl-model-common\";\n\n/**\n * A template file read, or why it could not be.\n *\n * A single message rather than a list of per-entry problems: until the document\n * parses there are no entries to attach anything to, and a file that does not parse\n * has one problem — it is not a template. Per-entry reporting starts at the stage\n * after this one. The message may span several lines when the file has several\n * fixable issues, so that fixing it takes one pass.\n */\nexport type TemplateParseOutcome =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly error: string };\n\n/**\n * Read `template-v1` YAML text into a document.\n *\n * The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the\n * export side — and, like it, living here rather than in `pl-model-common`, which ships\n * in every block-model and UI bundle and takes no `yaml` dependency. The document half\n * is `parseProjectTemplateV1`, shared with export so that what export writes is by\n * construction what import reads.\n *\n * JSON is accepted for free: every JSON document is also YAML.\n *\n * **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is\n * deliberate on both ends: quoting against the stricter ruleset makes a file we write\n * mean the same thing to any reader, and reading with the looser one means a bare\n * `yes` or `1:30` in a hand-written file stays the string it looks like instead of\n * silently becoming `true` or `90`.\n *\n * Nothing here checks that references point anywhere or that a kind can be resolved —\n * those are later stages, and both need more than the file to answer.\n */\nexport function parseProjectTemplateV1Yaml(text: string): TemplateParseOutcome {\n  let value: unknown;\n  try {\n    value = YAML.parse(text);\n  } catch (e) {\n    // The library's message already carries \"at line L, column C\"; what follows it is\n    // a code frame of the offending lines, dropped here because whoever is fixing the\n    // file has it open and the position is what they need.\n    const first = e instanceof Error ? e.message.split(\"\\n\")[0] : String(e);\n    return { ok: false, error: `The file is not valid YAML: ${first}` };\n  }\n\n  // Empty input, blank lines and a file of nothing but comments all parse to null.\n  // Left to the schema, this reads as \"expected object, received null\", which says\n  // nothing about the actual mistake.\n  if (value === null || value === undefined) {\n    return { ok: false, error: \"The file is empty.\" };\n  }\n\n  if (typeof value !== \"object\" || Array.isArray(value)) {\n    return {\n      ok: false,\n      error:\n        \"The file does not describe a template: expected a mapping with 'schema' and \" +\n        \"'blocks' at the top level.\",\n    };\n  }\n\n  // Checked ahead of the document reader because it is the likeliest mistake by far — the\n  // wrong file was picked — and deserves a sentence about that rather than one about a field\n  // whose value is not what was expected.\n  const marker = (value as { schema?: unknown }).schema;\n  if (marker !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    return {\n      ok: false,\n      error:\n        marker === undefined\n          ? `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.`\n          : `This file says it is '${String(marker)}', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`,\n    };\n  }\n\n  const outcome = readProjectTemplateV1(value);\n  return outcome.ok\n    ? { ok: true, document: outcome.document }\n    : { ok: false, error: describeIssues(outcome.issues) };\n}\n\n/**\n * Turn the reader's issues into something a person can act on, all of them at once.\n *\n * The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader\n * throws, so a problem reads the same whether it reached a person through this outcome or\n * through a log. What is added here is the headline, which is the one part that belongs to\n * this stage: it says the FILE is at fault, which a caller that has one can say and the\n * document reader cannot.\n */\nfunction describeIssues(issues: readonly TemplateParseIssue[]): string {\n  const lines = issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`);\n\n  const headline =\n    lines.length === 1\n      ? \"The template file has a problem:\"\n      : `The template file has ${lines.length} problems:`;\n\n  return [headline, ...lines].join(\"\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,2BAA2B,MAAoC;CAC7E,IAAI;CACJ,IAAI;EACF,QAAQA,KAAAA,QAAK,MAAM,IAAI;CACzB,SAAS,GAAG;EAKV,OAAO;GAAE,IAAI;GAAO,OAAO,+BADb,aAAa,QAAQ,EAAE,QAAQ,MAAM,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC;EACJ;CACpE;CAKA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;EAAE,IAAI;EAAO,OAAO;CAAqB;CAGlD,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAClD,OAAO;EACL,IAAI;EACJ,OACE;CAEJ;CAMF,MAAM,SAAU,MAA+B;CAC/C,IAAI,WAAWC,gCAAAA,4BACb,OAAO;EACL,IAAI;EACJ,OACE,WAAW,KAAA,IACP,mDAAmDA,gCAAAA,2BAA2B,cAC9E,yBAAyB,OAAO,MAAM,EAAE,SAASA,gCAAAA,2BAA2B;CACpF;CAGF,MAAM,WAAA,GAAA,gCAAA,sBAAA,CAAgC,KAAK;CAC3C,OAAO,QAAQ,KACX;EAAE,IAAI;EAAM,UAAU,QAAQ;CAAS,IACvC;EAAE,IAAI;EAAO,OAAO,eAAe,QAAQ,MAAM;CAAE;AACzD;;;;;;;;;;AAWA,SAAS,eAAe,QAA+C;CACrE,MAAM,QAAQ,OAAO,KAAK,UAAU,MAAA,GAAA,gCAAA,yBAAA,CAA8B,KAAK,GAAG;CAO1E,OAAO,CAJL,MAAM,WAAW,IACb,qCACA,yBAAyB,MAAM,OAAO,aAE1B,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI;AACvC"}
+{"version":3,"file":"template_parser.cjs","names":["YAML","PROJECT_TEMPLATE_SCHEMA_V1","readProjectTemplateV1","formatTemplateParseIssue"],"sources":["../../src/model/template_parser.ts"],"sourcesContent":["import YAML from \"yaml\";\nimport type { ProjectTemplateV1, TemplateParseIssue } from \"@milaboratories/pl-model-common\";\nimport {\n  PROJECT_TEMPLATE_SCHEMA_V1,\n  formatTemplateParseIssue,\n  readProjectTemplateV1,\n} from \"@milaboratories/pl-model-common\";\n\n/**\n * A template file read, or why it could not be.\n *\n * A single message rather than a list of per-entry problems: until the document\n * parses there are no entries to attach anything to, and a file that does not parse\n * has one problem — it is not a template. Per-entry reporting starts at the stage\n * after this one. The message may span several lines when the file has several\n * fixable issues, so that fixing it takes one pass.\n */\nexport type TemplateParseOutcome =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly error: string };\n\n/**\n * Read `template-v1` YAML text into a document.\n *\n * The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the\n * export side — and, like it, living here rather than in `pl-model-common`, which ships\n * in every block-model and UI bundle and takes no `yaml` dependency. The document half\n * is `parseProjectTemplateV1`, shared with export so that what export writes is by\n * construction what import reads.\n *\n * JSON is accepted for free: every JSON document is also YAML.\n *\n * **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is\n * deliberate on both ends: quoting against the stricter ruleset makes a file we write\n * mean the same thing to any reader, and reading with the looser one means a bare\n * `yes` or `1:30` in a hand-written file stays the string it looks like instead of\n * silently becoming `true` or `90`.\n *\n * Nothing here checks that references point anywhere or that a kind can be resolved —\n * those are later stages, and both need more than the file to answer.\n */\nexport function parseProjectTemplateV1Yaml(text: string): TemplateParseOutcome {\n  let value: unknown;\n  try {\n    value = YAML.parse(text);\n  } catch (e) {\n    // The library's message already carries \"at line L, column C\"; what follows it is\n    // a code frame of the offending lines, dropped here because whoever is fixing the\n    // file has it open and the position is what they need.\n    const first = e instanceof Error ? e.message.split(\"\\n\")[0] : String(e);\n    return { ok: false, error: `The file is not valid YAML: ${first}` };\n  }\n\n  // Empty input, blank lines and a file of nothing but comments all parse to null.\n  // Left to the schema, this reads as \"expected object, received null\", which says\n  // nothing about the actual mistake.\n  if (value === null || value === undefined) {\n    return { ok: false, error: \"The file is empty.\" };\n  }\n\n  if (typeof value !== \"object\" || Array.isArray(value)) {\n    return {\n      ok: false,\n      error:\n        \"The file does not describe a template: expected a mapping with 'schema' and \" +\n        \"'blocks' at the top level.\",\n    };\n  }\n\n  // Checked ahead of the document reader because it is the likeliest mistake by far — the\n  // wrong file was picked — and deserves a sentence about that rather than one about a field\n  // whose value is not what was expected.\n  const marker = (value as { schema?: unknown }).schema;\n  if (marker !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    return {\n      ok: false,\n      error:\n        marker === undefined\n          ? `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.`\n          : `This file says it is '${String(marker)}', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`,\n    };\n  }\n\n  const outcome = readProjectTemplateV1(value);\n  return outcome.ok\n    ? { ok: true, document: outcome.document }\n    : { ok: false, error: describeIssues(outcome.issues) };\n}\n\n/**\n * Turn the reader's issues into something a person can act on, all of them at once.\n *\n * The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader\n * throws, so a problem reads the same whether it reached a person through this outcome or\n * through a log. What is added here is the headline, which is the one part that belongs to\n * this stage: it says the FILE is at fault, which a caller that has one can say and the\n * document reader cannot.\n */\nfunction describeIssues(issues: readonly TemplateParseIssue[]): string {\n  const lines = issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`);\n\n  const headline =\n    lines.length === 1\n      ? \"The template file has a problem:\"\n      : `The template file has ${lines.length} problems:`;\n\n  return [headline, ...lines].join(\"\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,2BAA2B,MAAoC;CAC7E,IAAI;CACJ,IAAI;EACF,QAAQA,KAAAA,QAAK,MAAM,IAAI;CACzB,SAAS,GAAG;EAKV,OAAO;GAAE,IAAI;GAAO,OAAO,+BADb,aAAa,QAAQ,EAAE,QAAQ,MAAM,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC;EACJ;CACpE;CAKA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;EAAE,IAAI;EAAO,OAAO;CAAqB;CAGlD,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAClD,OAAO;EACL,IAAI;EACJ,OACE;CAEJ;CAMF,MAAM,SAAU,MAA+B;CAC/C,IAAI,WAAWC,gCAAAA,4BACb,OAAO;EACL,IAAI;EACJ,OACE,WAAW,KAAA,IACP,mDAAmDA,gCAAAA,2BAA2B,cAC9E,yBAAyB,OAAO,MAAM,EAAE,SAASA,gCAAAA,2BAA2B;CACpF;CAGF,MAAM,WAAA,GAAUC,gCAAAA,sBAAAA,CAAsB,KAAK;CAC3C,OAAO,QAAQ,KACX;EAAE,IAAI;EAAM,UAAU,QAAQ;CAAS,IACvC;EAAE,IAAI;EAAO,OAAO,eAAe,QAAQ,MAAM;CAAE;AACzD;;;;;;;;;;AAWA,SAAS,eAAe,QAA+C;CACrE,MAAM,QAAQ,OAAO,KAAK,UAAU,MAAA,GAAKC,gCAAAA,yBAAAA,CAAyB,KAAK,GAAG;CAO1E,OAAO,CAJL,MAAM,WAAW,IACb,qCACA,yBAAyB,MAAM,OAAO,aAE1B,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI;AACvC"}