deepline 0.3.466 → 0.3.467

package/dist/bundling-sources/sdk/src/client-core.ts

@@ -1,8 +1,12 @@
 import type {
   BillingEntitlements,
+  IncludedCompute,
   BillingBenefitValues,
 } from '../../shared_libs/integration-contracts/billing-entitlements';
-export type { BillingEntitlements } from '../../shared_libs/integration-contracts/billing-entitlements';
+export type {
+  BillingEntitlements,
+  IncludedCompute,
+} from '../../shared_libs/integration-contracts/billing-entitlements';
 import type {
   PlaySettingsResult,
   PlaySettingsPatch,
@@ -2300,6 +2304,20 @@ export type WorkspaceCreateResult = {
 
 /** Deliberate workspace lifecycle operations. */
 export type WorkspacesNamespace = {
+  /** One page of current workspace memberships and effective grants. */
+  members: (options?: { cursor?: string }) => Promise<{
+    members: { id: string; userId: string; role: string; grants: string[] }[];
+    cursor: string | null;
+  }>;
+  /** Replace a member's grants. Requires admin; ownership changes require owner. */
+  setMemberGrants: (
+    memberId: string,
+    grants: string[],
+  ) => Promise<{
+    ok: boolean;
+    memberId: string;
+    role: string;
+  }>;
   /** Create an additional workspace and provision its active PAYG Contract. */
   create: (options: {
     name: string;
@@ -2453,6 +2471,10 @@ export type BillingNamespace = {
   quote: (input: BillingQuoteRequest) => Promise<BillingQuoteResult>;
   /** Current workspace provider benefits; discovery does not authorize a call. */
   entitlements: () => Promise<BillingEntitlements>;
+  /** Play compute pricing and this period's sandbox minutes by day. */
+  includedCompute: () => Promise<IncludedCompute>;
+  /** Turn on included compute for the workspace. It cannot be turned off again. */
+  enableIncludedCompute: () => Promise<IncludedCompute>;
   /** Charge the saved payment method and add Deepline credits to the active workspace. */
   topUp: (options: {
     credits: number;
@@ -2906,6 +2928,9 @@ export class DeeplineClient {
       quote: (input) =>
         this.http.post<BillingQuoteResult>('/api/v2/billing/quote', input),
       entitlements: () => this.http.get('/api/v2/billing/entitlements'),
+      includedCompute: () => this.http.get('/api/v2/billing/included-compute'),
+      enableIncludedCompute: () =>
+        this.http.post<IncludedCompute>('/api/v2/billing/included-compute', {}),
       topUp: (options) => this.topUpBillingBalance(options),
       topUpWithReceipt: (options) =>
         this.topUpBillingBalanceWithReceipt(options),
@@ -2944,6 +2969,17 @@ export class DeeplineClient {
         this.createTargetBillingPortalSession(options),
     };
     this.workspaces = {
+      members: (options) => {
+        const query = options?.cursor
+          ? `?cursor=${encodeURIComponent(options.cursor)}`
+          : '';
+        return this.http.get(`/api/v2/auth/workspace/members${query}`);
+      },
+      setMemberGrants: (memberId, grants) =>
+        this.http.patch(
+          `/api/v2/auth/workspace/members/${encodeURIComponent(memberId)}/role`,
+          { role: grants.join(',') },
+        ),
       create: (options) => this.createWorkspace(options),
     };
     this.monitors = {
@@ -3095,7 +3131,10 @@ export class DeeplineClient {
   }
 
   /** The explicit way to change who can see an existing page. */
-  async setPageVisibility(name: string, isPublic: boolean): Promise<HostedPage> {
+  async setPageVisibility(
+    name: string,
+    isPublic: boolean,
+  ): Promise<HostedPage> {
     return await this.http.post<HostedPage>(
       `/api/v2/pages/${encodeURIComponent(name)}/visibility`,
       { public: isPublic },

package/dist/bundling-sources/sdk/src/release.ts

@@ -205,7 +205,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.466',
+  version: '0.3.467',
   updateSummary: {
     introducedIn: '0.3.90',
     summary:

package/dist/bundling-sources/shared_libs/integration-contracts/billing-entitlements.ts

@@ -69,3 +69,20 @@ export type BillingEntitlements = {
     };
   };
 };
+
+/** `GET`/`POST /api/v2/billing/included-compute`. */
+export type IncludedCompute = {
+  /** `unavailable`: the workspace is outside the November pricing rollout. */
+  status: 'on' | 'off' | 'unavailable';
+  /** Credits per minute of sandbox runtime in force; null at provider cost. */
+  credits_per_minute: number | null;
+  included_minutes: number;
+  /** What turning included compute on gives this workspace's plan. */
+  plan: { included_minutes: number; credits_per_minute: number };
+  period_start_at: string;
+  period_end_at: string;
+  resets_on: 'calendar_month' | 'billing_cycle';
+  included_minutes_used: number;
+  minutes_used: number;
+  days: Array<{ day: string; minutes: number }>;
+};

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -33,8 +33,10 @@ import {
   type JobChangeStatus,
 } from '../plays/extractor-targets';
 import {
+  LIST_NAMES,
   fieldOfName,
   fieldPaths,
+  isFieldId,
   resolveFieldName,
   type FieldBinding,
 } from '../plays/field-catalog';
@@ -50,6 +52,7 @@ import type {
   ToolResultListMetadata,
   ToolResultEnvelope,
   ToolResultMetadataInput,
+  ToolResultRow,
   ToolResultTargetAccessor,
   ToolResultTargetMetadata,
 } from '../plays/tool-result-types';
@@ -1551,69 +1554,341 @@ function listTableNamespace(
   }
 }
 
-/**
- * The outputs of a result that are catalog fields: declared extractors whose
- * meaning is known, from the tool's own `means` or the name's one meaning.
- * Values found by guessing at keys are never bindings.
- */
-function resultFieldBindings(
-  result: ToolExecuteResult | BasicToolExecuteResult,
+/** What a result or one of its rows knows, for reading fields from it. */
+type FieldSource = {
+  toolId: string;
+  bindings: FieldBinding[];
+  outputs: string[];
+  values(output: string): unknown[];
+  /** The list an output belongs to, when only its items can answer `.value`. */
+  itemList?(output: string): string | undefined;
+};
+
+/** The one value, or null. Returning one of several would miss the rest. */
+function oneValue(values: unknown[], toolId: string, name: string): unknown {
+  if (values.length > 1) {
+    throw new Error(
+      `${toolId} has ${values.length} values for "${name}". Read ${name}.values.`,
+    );
+  }
+  return values[0] ?? null;
+}
+
+function extractorBindings(
+  extractors: Record<string, ToolResultExtractorDescriptor>,
 ): FieldBinding[] {
-  const extractors = result._metadata.extractors ?? {};
   return Object.entries(extractors).flatMap(([name, descriptor]) => {
-    if (!result.extractedValues[name]) return [];
     const id = fieldOfName(name, descriptor.means);
     return id ? [{ name, id }] : [];
   });
 }
 
-function resultOutputNames(
+/** Reads an id or short name, ending in `.value`, `.values` or neither. */
+function readField(source: FieldSource, name: string): unknown {
+  const ending = /^(.*)\.(value|values)$/.exec(name);
+  const base = ending?.[1] ?? name;
+  const target = isFieldId(`${base}.value`) ? `${base}.value` : base;
+  const binding = resolveFieldName(target, source.bindings, source.outputs);
+  if (!binding) {
+    const ids = [...new Set(source.bindings.map((known) => known.id))];
+    throw new Error(
+      `${source.toolId} has no field "${name}". ${ids.length > 0 ? `Its fields: ${ids.join(', ')}.` : 'It declares no catalog fields.'} Other values are in response.`,
+    );
+  }
+  if (ending?.[2] === 'values') return source.values(binding.name);
+  const list = source.itemList?.(binding.name);
+  if (list) {
+    throw new Error(
+      `"${base}" is a field of each item on ${source.toolId}. Read it from result.rows('${list}').`,
+    );
+  }
+  return oneValue(source.values(binding.name), source.toolId, base);
+}
+
+/** One place in `fields`. Only the key it serializes as appears in JSON. */
+type FieldPlace = {
+  parent: string[];
+  value(): unknown;
+  values(): unknown;
+  serializes?: 'value' | 'values';
+};
+
+function buildFieldTree(places: FieldPlace[]): Record<string, unknown> {
+  const tree: Record<string, unknown> = {};
+  for (const { parent, value, values, serializes } of places) {
+    const node = parent.reduce(
+      (at, key) => (at[key] ??= {}) as Record<string, unknown>,
+      tree,
+    );
+    Object.defineProperties(node, {
+      value: { get: value, enumerable: serializes === 'value' },
+      values: { get: values, enumerable: serializes === 'values' },
+    });
+  }
+  return tree;
+}
+
+/** The places of a source's fields. Ambiguous ones throw and never serialize. */
+function fieldPlaces(
+  source: FieldSource,
+  serializes: (output: string) => FieldPlace['serializes'],
+  lists: readonly string[] = [],
+): FieldPlace[] {
+  return fieldPaths(source.bindings, source.outputs, lists)
+    .filter((entry) => !entry.list)
+    .map((entry) => ({
+      parent: entry.path.slice(0, -1),
+      value: () => readField(source, entry.name),
+      values: () =>
+        entry.output === null
+          ? readField(source, entry.name)
+          : source.values(entry.output),
+      serializes: entry.output === null ? undefined : serializes(entry.output),
+    }));
+}
+
+/**
+ * Every value one extractor finds under `root`, from the first of its paths
+ * that finds any. Later paths are fallbacks, not more values.
+ */
+function extractorValues(
+  root: unknown,
+  name: string,
+  descriptor: ToolResultExtractorDescriptor,
+  paths: readonly string[],
+): unknown[] {
+  for (const path of paths) {
+    for (const candidate of candidateResultPaths(path)) {
+      const found = getValuesAtPath(root, candidate)
+        .flat()
+        .flatMap((value) => {
+          const accepted = acceptedTargetValue(name, value);
+          return accepted === undefined ? [] : [accepted];
+        });
+      if (found.length > 0) {
+        return found.map((value) =>
+          coerceToEnum(applyExtractorTransforms(value, descriptor), descriptor),
+        );
+      }
+    }
+  }
+  return [];
+}
+
+/** A value computed from several provider fields, so never more than one. */
+function isComputedValue(descriptor: ToolResultExtractorDescriptor): boolean {
+  return Boolean(descriptor.emailStatus || descriptor.overrides?.length);
+}
+
+function presentValues(value: unknown): unknown[] {
+  return value === null || value === undefined ? [] : [value];
+}
+
+function firstFound(readers: Array<() => unknown[]>): unknown[] {
+  for (const read of readers) {
+    const found = read();
+    if (found.length > 0) return found;
+  }
+  return [];
+}
+
+/**
+ * The lists a tool declares, whatever this response holds. Paths ending in
+ * the same name are one list, and a list is called by its alias when it has
+ * one (`{ people: 'data' }`).
+ */
+function declaredListNames(
   result: ToolExecuteResult | BasicToolExecuteResult,
 ): string[] {
+  const aliasOf = new Map(
+    Object.entries(result._metadata.listExtractorAliases ?? {}).map(
+      ([alias, source]) => [source, alias],
+    ),
+  );
   return [
-    ...Object.keys(result._metadata.extractors ?? {}),
-    ...Object.keys(result.extractedLists),
+    ...new Set(
+      (result._metadata.listExtractorPaths ?? []).flatMap((path) => {
+        const name = listNameFromDeclaredPath(path);
+        return name ? [aliasOf.get(name) ?? name] : [];
+      }),
+    ),
   ];
 }
 
-function readResultField(
+function resultFieldSource(
   result: ToolExecuteResult | BasicToolExecuteResult,
-  name: string,
-): unknown {
-  const bindings = resultFieldBindings(result);
-  const binding = resolveFieldName(name, bindings, resultOutputNames(result));
-  if (!binding) {
-    const ids = [...new Set(bindings.map((known) => known.id))];
-    throw new Error(
-      `${result._metadata.toolId} has no field "${name}". ${ids.length > 0 ? `Its fields: ${ids.join(', ')}.` : 'It declares no catalog fields.'} Other values are in result.response.`,
+): FieldSource {
+  const extractors = result._metadata.extractors ?? {};
+  const root = resultRootOf(result);
+  const getter = (output: string) =>
+    presentValues(result.extractedValues[output]?.get());
+  // A path with a wildcard may read a clipped preview, so rows answer first.
+  const atRoot = (output: string) => {
+    const descriptor = extractors[output]!;
+    return extractorValues(
+      root,
+      output,
+      descriptor,
+      descriptor.paths.filter((path) => !path.includes('[*]')),
     );
-  }
-  return result.extractedValues[binding.name]!.get();
+  };
+  // Only a tool with one list can answer across its items; with several,
+  // which list a value came from would be lost.
+  const inRows = (output: string) => {
+    if (declaredListNames(result).length !== 1) return [];
+    const id = fieldOfName(output, extractors[output]!.means)!;
+    return readResultRows(result).flatMap(
+      (row) => row.field(id.replace(/\.value$/, '.values')) as unknown[],
+    );
+  };
+  return {
+    toolId: result._metadata.toolId,
+    bindings: extractorBindings(extractors),
+    outputs: [
+      ...Object.keys(extractors),
+      ...Object.keys(result.extractedLists),
+    ],
+    values(output) {
+      const descriptor = extractors[output]!;
+      return isComputedValue(descriptor)
+        ? getter(output)
+        : firstFound([
+            () => atRoot(output),
+            () => inRows(output),
+            () => extractorValues(root, output, descriptor, descriptor.paths),
+            () => getter(output),
+          ]);
+    },
+    itemList(output) {
+      const onResult =
+        isComputedValue(extractors[output]!) || atRoot(output).length > 0;
+      const named = declaredListNames(result).filter((name) =>
+        (LIST_NAMES as readonly string[]).includes(name),
+      );
+      return onResult ? undefined : named[0];
+    },
+  };
 }
 
-/** `result.fields`, laid out by `fieldPaths`; each value reads on access. */
-function buildResultFields(
+function resultFields(
   result: ToolExecuteResult | BasicToolExecuteResult,
 ): Record<string, unknown> {
-  const tree: Record<string, unknown> = {};
+  const source = resultFieldSource(result);
   const lists = Object.keys(result.extractedLists);
-  for (const entry of fieldPaths(
-    resultFieldBindings(result),
-    resultOutputNames(result),
-    lists,
-  )) {
-    let node = tree;
-    for (const key of entry.path.slice(0, -1)) {
-      node = (node[key] ??= {}) as Record<string, unknown>;
-    }
-    Object.defineProperty(node, entry.path[entry.path.length - 1]!, {
-      get: entry.list
-        ? () => result.extractedLists[entry.name]!.get()
-        : () => readResultField(result, entry.name),
-      enumerable: true,
-    });
+  return buildFieldTree([
+    ...fieldPlaces(source, () => 'value', lists),
+    ...lists.map((name) => ({
+      parent: [name],
+      value: () => oneValue(resultListItems(result, name), source.toolId, name),
+      values: () => result.extractedLists[name]!.get(),
+      serializes: 'values' as const,
+    })),
+  ]);
+}
+
+/** An extractor's paths as they read from one list item. */
+function rowExtractorPaths(paths: readonly string[]): string[] {
+  return [
+    ...new Set(
+      paths.flatMap((path) => {
+        const wildcard = path.indexOf('[*].');
+        return wildcard < 0 ? [path] : [path, path.slice(wildcard + 4)];
+      }),
+    ),
+  ];
+}
+
+function createToolResultRow(
+  toolId: string,
+  item: unknown,
+  extractors: Record<string, ToolResultExtractorDescriptor>,
+): ToolResultRow {
+  const descriptors = Object.fromEntries(
+    Object.entries(extractors).map(([name, descriptor]) => [
+      name,
+      { ...descriptor, paths: rowExtractorPaths(descriptor.paths) },
+    ]),
+  );
+  const root = { toolResponse: { raw: item } };
+  const targets = buildTargets(root, descriptors);
+  const values = (output: string) => {
+    const descriptor = descriptors[output]!;
+    const target = () => presentValues(targets[output]?.value);
+    return isComputedValue(descriptor)
+      ? target()
+      : firstFound([
+          () => extractorValues(root, output, descriptor, descriptor.paths),
+          target,
+        ]);
+  };
+  const source: FieldSource = {
+    toolId,
+    bindings: extractorBindings(extractors),
+    outputs: Object.keys(extractors),
+    values,
+  };
+  const row = {
+    fields: buildFieldTree(
+      fieldPlaces(source, (output) =>
+        values(output).length > 1 ? 'values' : 'value',
+      ),
+    ),
+    response: item,
+  };
+  Object.defineProperty(row, 'field', {
+    value: (name: string) => readField(source, name),
+    enumerable: false,
+  });
+  return row as unknown as ToolResultRow;
+}
+
+function resultListItems(
+  result: ToolExecuteResult | BasicToolExecuteResult,
+  name: string,
+): unknown[] {
+  // The array view gives complete provider items, or throws for a lazy or
+  // incomplete list, in every edition.
+  return projectToolResultListGetters(
+    result as ToolExecuteResult,
+    'array',
+  ).extractedLists[name]!.get();
+}
+
+/**
+ * The one list `rows()` reads. A tool that declares several lists always needs
+ * a name, whatever this response holds, and a name never reads two lists.
+ */
+function selectResultList(
+  result: ToolExecuteResult | BasicToolExecuteResult,
+  list?: string,
+): string {
+  const toolId = result._metadata.toolId;
+  const declared = declaredListNames(result);
+  if (list === undefined && declared.length > 1) {
+    throw new Error(
+      `${toolId} has several lists: ${declared.join(', ')}. Name one with result.rows('${declared[0]}').`,
+    );
   }
-  return tree;
+  const wanted = list ?? declared[0];
+  if (wanted !== undefined && result.extractedLists[wanted]) return wanted;
+  if (wanted !== undefined && !declared.includes(wanted)) {
+    throw new Error(
+      `${toolId} has no list "${wanted}". Its lists: ${declared.join(', ') || 'none'}.`,
+    );
+  }
+  throw new Error(
+    `${toolId} returned no declared list; a missing list is not an empty one. Read result.response.`,
+  );
+}
+
+function readResultRows(
+  result: ToolExecuteResult | BasicToolExecuteResult,
+  list?: string,
+): ToolResultRow[] {
+  const { toolId, extractors = {} } = result._metadata;
+  return resultListItems(result, selectResultList(result, list)).map((item) =>
+    createToolResultRow(toolId, item, extractors),
+  );
 }
 
 export function createToolExecuteResult<TResult = unknown>(input: {
@@ -1707,13 +1982,19 @@ export function createToolExecuteResult<TResult = unknown>(input: {
     },
     fields: {
       get(this: ToolExecuteResult) {
-        return buildResultFields(this);
+        return resultFields(this);
       },
       enumerable: false,
     },
     field: {
       value(this: ToolExecuteResult, name: string) {
-        return readResultField(this, name);
+        return readField(resultFieldSource(this), name);
+      },
+      enumerable: false,
+    },
+    rows: {
+      value(this: ToolExecuteResult, list?: string) {
+        return readResultRows(this, list);
       },
       enumerable: false,
     },

package/dist/bundling-sources/shared_libs/plays/field-catalog.ts

@@ -428,6 +428,21 @@ function isOtherThing(id: string): boolean {
   );
 }
 
+/**
+ * What a list holds, the same on every tool. A tool's list has one of these
+ * names by its path or by `listExtractorAliases` (`{ people: 'data' }`). Its
+ * extractors then describe items, and its other declared paths are other
+ * places the same list can appear.
+ */
+export const LIST_NAMES = [
+  'people',
+  'companies',
+  'job_postings',
+  'posts',
+  'podcasts',
+  'pages',
+] as const;
+
 /** One output of a tool, and the catalog field it is. */
 export type FieldBinding = { name: string; id: string };
 

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -5,8 +5,20 @@ import type { FIELD_CATALOG } from './field-catalog';
 
 type Catalog = typeof FIELD_CATALOG;
 
+/** One place in `fields`: the one value or null, or every value. */
+export type ToolResultFieldValue<T> = {
+  readonly value: T | null;
+  readonly values: T[];
+};
+
 type GroupLeaves<TGroup> = TGroup extends { leaves: infer TLeaves }
-  ? { readonly [Leaf in keyof TLeaves]?: unknown }
+  ? {
+      readonly [Leaf in keyof TLeaves]?: Leaf extends 'value'
+        ? unknown
+        : ToolResultFieldValue<unknown>;
+    } & (TLeaves extends { value: unknown }
+      ? { readonly values?: unknown[] }
+      : unknown)
   : unknown;
 
 type CatalogGroupFields<TGroup> = GroupLeaves<TGroup> &
@@ -35,7 +47,7 @@ export type CatalogFields = {
  * The values a result is known to have, by field catalog id and short name,
  * each ending in a leaf: `fields.person.email.value`,
  * `fields.person.email.work.value`, `fields.email.value`. Declared lists are
- * at `fields.<list>.value`, as their getter returns them. A value whose
+ * at `fields.<list>.values`, as their getter returns them. A value whose
  * meaning is not known is absent; read it from `response`. Reading a field
  * two outputs could be throws, naming both.
  */
@@ -43,8 +55,13 @@ export type ToolResultFields<
   TExtracted extends Record<string, unknown>,
   TListValues extends Record<string, unknown>,
 > = CatalogFields & {
-  readonly [K in keyof TExtracted]?: { readonly value: TExtracted[K] | null };
-} & { readonly [K in keyof TListValues]?: { readonly value: TListValues[K] } };
+  readonly [K in keyof TExtracted]?: ToolResultFieldValue<TExtracted[K]>;
+} & {
+  readonly [K in keyof TListValues]?: {
+    readonly value: unknown;
+    readonly values: TListValues[K];
+  };
+};
 
 /**
  * Customer pricing reported by the execution API, never provider spend.
@@ -209,6 +226,20 @@ export type BasicToolExecuteResult<
 > = BasicToolExecuteResultBase<TResult, TMeta> &
   BasicToolExecuteResultAccessors<TExtracted, TLists>;
 
+/**
+ * One list item in a format that does not depend on the provider. `fields`
+ * has every declared field, null when this item has no value. `response` is
+ * the provider's whole item, for anything else.
+ */
+export type ToolResultRow<
+  TFields = CatalogFields &
+    Partial<Record<string, ToolResultFieldValue<unknown>>>,
+> = {
+  readonly fields: TFields;
+  readonly response: unknown;
+  field(name: string): unknown;
+};
+
 export type ToolResultMetadataInput = {
   toolId: string;
   extractors?: Record<string, ToolResultExtractorDescriptor>;
@@ -308,8 +339,18 @@ export type ToolExecuteResultBase<
   toolResponse: ToolResponseEnvelope<TResult, TMeta>;
   extractedValues: Record<string, ToolResultTargetAccessor>;
   extractedLists: Record<string, ToolResultListAccessor>;
-  /** One field by id or short name, as `fields` resolves it. */
+  /**
+   * One field by id or short name, as `fields` resolves it.
+   * `field('person.email.value')` is the one value, or null, and throws when
+   * there are several. `field('person.email.values')` is always an array.
+   */
   field(name: string): unknown;
+  /**
+   * One consistent record per item of a list: `rows('people')`. A bare
+   * `rows()` works when the tool declares one list. Throws when the list is
+   * missing, lazy or incomplete; an absent list is not an empty one.
+   */
+  rows(list?: string): ToolResultRow[];
   /** The complete parsed provider response (`toolResponse.rawV2`). */
   readonly response: unknown;
   /** Convenience alias for play code. Serialized output uses toolResponse. */
@@ -359,10 +400,14 @@ export type ToolExecuteResultAccessors<
  * Known values: `fields.person.email.value`, `fields.email.value`, and a
  * declared list at `fields.<list>.value`; or `field('person.email.value')`.
  * A value whose meaning is not known is absent: read it from `response`, the
- * complete provider response. Metadata: `toolResponse.meta`. The older
+ * complete provider response (also `toolResponse.rawV2`). Metadata: `toolResponse.meta`. The older
  * getters `extractedValues.<name>.get()` and `extractedLists.<name>.get()`
  * return the same values and keep working.
  *
+ * One record per list item: `rows()`, each with `fields`, `field()` and
+ * `response`. `.value` is the one value or null, and throws when there are
+ * several rather than miss data. `.values` is always an array.
+ *
  * Edition 10 and later Plays receive ordinary arrays from
  * list `.get()` synchronously; persist explicitly with deepline.dataset. Lazy or
  * incomplete lists throw: use readList(result, path) for explicit dataset access.