@elaraai/e3-types 1.0.86 → 1.0.88

package/src/api.ts

@@ -217,6 +217,29 @@ export const GcStatusResultType = StructType({
   error: OptionType(StringType),
 });
 
+/**
+ * A repository's removal, as the route a server names while it runs answers
+ * it.
+ *
+ * A server whose removal outlasts a request answers `DELETE /repos/:repo`
+ * `202 Accepted`, with a `Location` naming that route and a `Retry-After`;
+ * one that removes the repository within the request answers 200. The route
+ * answers:
+ *
+ * - `removing`: the removal runs, and is asked of again after the answer's
+ *   `Retry-After`
+ * - `removed`: the repository is gone
+ * - `failed`: the removal stopped, and why
+ *
+ * A route of a repository that is gone may answer `repository_not_found`
+ * instead of `removed`.
+ */
+export const RepositoryRemovalType = VariantType({
+  removing: NullType,
+  removed: NullType,
+  failed: StructType({ message: StringType }),
+});
+
 // =============================================================================
 // Package Types
 // =============================================================================
@@ -275,6 +298,16 @@ export const WorkspaceCreateRequestType = StructType({
   name: StringType,
 });
 
+/**
+ * Request to copy a workspace within its repository.
+ *
+ * @property to - The workspace the copy makes, or replaces whole: it becomes
+ *   the workspace copied as it is now
+ */
+export const WorkspaceCopyRequestType = StructType({
+  to: StringType,
+});
+
 /**
  * Workspace summary information.
  *
@@ -306,11 +339,30 @@ export const SchemaPolicyType = VariantType({
   reset: NullType,
 });
 
+/**
+ * What a deploy does with an input someone set: one whose value in the
+ * workspace is not the value the deployed package gave it.
+ *
+ * - `reset`: give it the new package's value, as every other input takes
+ * - `keep-edited`: keep it while its type is the new package's; one whose type
+ *   changed takes the new package's value, and the plan says it was reset
+ *
+ * An input the new package takes from a file takes its file under either. One
+ * the deployed package took from a file takes the new package's value under
+ * either, since a value set since cannot be told from the file's, and so does
+ * one the new package declares as a dataset people do not set.
+ */
+export const InputPolicyType = VariantType({
+  'keep-edited': NullType,
+  reset: NullType,
+});
+
 /**
  * Request to deploy a package to a workspace.
  *
  * @property packageRef - Package reference in format "name" or "name@version"
  * @property schema - What the deploy does with a record it cannot keep as it is
+ * @property inputs - What the deploy does with an input someone set
  * @property allowDropRecords - Whether a record the package no longer declares
  *   may be dropped, with its state and history
  * @property plan - Say what the deploy would do, and write nothing
@@ -318,6 +370,7 @@ export const SchemaPolicyType = VariantType({
 export const WorkspaceDeployRequestType = StructType({
   packageRef: StringType,
   schema: SchemaPolicyType,
+  inputs: InputPolicyType,
   allowDropRecords: BooleanType,
   plan: BooleanType,
 });
@@ -369,6 +422,39 @@ export const RecordIndexPlanType = StructType({
   }),
 });
 
+/**
+ * What a deploy decided for one input: a dataset its package marks writable,
+ * which people set.
+ *
+ * @property input - The input's dataset ref path
+ * @property action - What the deploy does to it:
+ *   - `package`: it takes the new package's value: the workspace holds the
+ *     value the deployed package gave it, or does not hold the input
+ *   - `keep`: kept as the workspace holds it: someone set it, and its type is
+ *     the new package's (`keep-edited`)
+ *   - `reset`: it takes the new package's value in place of one someone may
+ *     have set, and why: its type changed; the deployed package took it from a
+ *     file, so a value set since cannot be told from the file's; the new
+ *     package no longer marks it as an input; or the deploy resets what people
+ *     set (`reset`), when `policy` is true, which `keep-edited` would keep
+ *   - `file`: it takes the file the new package names, as every deploy does:
+ *     the deploy takes it in, or, when `taken` is false, reads no file
+ *     (`resolveFileSources: false`, as a server deploying for a client does)
+ *     and leaves it unassigned for the client to complete over the dataset
+ *     transfer protocol
+ *   - `drop`: the new package does not declare it, so it goes, with its value
+ */
+export const InputPlanType = StructType({
+  input: StringType,
+  action: VariantType({
+    package: NullType,
+    keep: NullType,
+    reset: StructType({ reason: StringType, policy: BooleanType }),
+    file: StructType({ path: StringType, taken: BooleanType }),
+    drop: NullType,
+  }),
+});
+
 /**
  * The step a deploy is at with one record.
  *
@@ -419,12 +505,15 @@ export const DeployProgressType = StructType({
  *
  * @property records - What it decided for each record
  * @property indexes - What it decided for each index of the records it keeps
+ * @property inputs - What it decided for each input, the package's first and
+ *   then each it drops
  * @property warnings - The inputs it left unassigned, and why: a server never
  *   reads a `file` source, whose path is on the client's machine
  */
 export const WorkspaceDeployResultType = StructType({
   records: ArrayType(RecordPlanType),
   indexes: ArrayType(RecordIndexPlanType),
+  inputs: ArrayType(InputPlanType),
   warnings: ArrayType(StringType),
 });
 
@@ -825,15 +914,21 @@ export const DataflowEventType = VariantType({
  * Execution status for API polling responses.
  *
  * - `running`: Execution is in progress
+ * - `stopping`: Execution was asked to stop, and its tasks have not all
+ *   stopped yet: it holds its workspace until they have
  * - `completed`: Execution finished successfully
  * - `failed`: Execution finished with failures
  * - `aborted`: Execution was cancelled
  *
+ * `stopping` is named to sort after every case before it, so its tag is the
+ * last and a poll a server answered before it read as itself.
+ *
  * Note: Named "Api*" to distinguish from the on-disk ExecutionStatusType
  * in execution.ts which tracks individual task execution states.
  */
 export const ApiExecutionStatusType = VariantType({
   running: NullType,
+  stopping: NullType,
   completed: NullType,
   failed: NullType,
   aborted: NullType,
@@ -1476,16 +1571,21 @@ export type GcResult = ValueTypeOf<typeof GcResultType>;
 export type AsyncOperationStatus = ValueTypeOf<typeof AsyncOperationStatusType>;
 export type GcStartResult = ValueTypeOf<typeof GcStartResultType>;
 export type GcStatusResult = ValueTypeOf<typeof GcStatusResultType>;
+export type RepositoryRemoval = ValueTypeOf<typeof RepositoryRemovalType>;
 export type PackageListItem = ValueTypeOf<typeof PackageListItemType>;
 export type PackageInfo = ValueTypeOf<typeof PackageInfoType>;
 export type PackageDetails = ValueTypeOf<typeof PackageDetailsType>;
 export type WorkspaceInfo = ValueTypeOf<typeof WorkspaceInfoType>;
 export type WorkspaceCreateRequest = ValueTypeOf<typeof WorkspaceCreateRequestType>;
+export type WorkspaceCopyRequest = ValueTypeOf<typeof WorkspaceCopyRequestType>;
 export type WorkspaceDeployRequest = ValueTypeOf<typeof WorkspaceDeployRequestType>;
 /** A {@link SchemaPolicyType} by its name, as a deploy's options take it. */
 export type SchemaPolicy = ValueTypeOf<typeof SchemaPolicyType>['type'];
+/** An {@link InputPolicyType} by its name, as a deploy's options take it. */
+export type InputPolicy = ValueTypeOf<typeof InputPolicyType>['type'];
 export type RecordPlan = ValueTypeOf<typeof RecordPlanType>;
 export type RecordIndexPlan = ValueTypeOf<typeof RecordIndexPlanType>;
+export type InputPlan = ValueTypeOf<typeof InputPlanType>;
 export type RecordDeployStep = ValueTypeOf<typeof RecordDeployStepType>;
 export type RecordDeployState = ValueTypeOf<typeof RecordDeployStateType>;
 export type DeployProgress = ValueTypeOf<typeof DeployProgressType>;

package/src/dataflow.ts

@@ -598,6 +598,9 @@ export function decodeDataflowExecutionState(data: Uint8Array): DataflowExecutio
  * run. A store may keep it beside the state, written with each change of the
  * state; one that reads the whole state anyway derives it
  * ({@link executionStateSummary}).
+ *
+ * Nothing stores the summary as this type: a store that keeps one beside the
+ * state keeps it in its own form.
  */
 export const ExecutionStateSummaryType = StructType({
   /** The run's id, a UUIDv7 */
@@ -620,6 +623,11 @@ export const ExecutionStateSummaryType = StructType({
   error: OptionType(StringType),
   /** The sequence number of the run's last event: 0 while it has none */
   lastSeq: IntegerType,
+  /** Whether a cancel of the run is recorded that the run has not yet applied:
+   *  a run asked to stop, whose tasks run in other processes or machines, that
+   *  has not yet stopped. A poll answers such a run `stopping`. A store whose
+   *  runs a cancel stops in place records none. */
+  cancelRequested: BooleanType,
 });
 export type ExecutionStateSummary = ValueTypeOf<typeof ExecutionStateSummaryType>;
 
@@ -644,7 +652,9 @@ export function lastEventSeq(state: Pick<DataflowExecutionState, 'events' | 'eve
  *
  * @param state - The run's state
  * @returns Its summary: its last event's sequence number is the last event's
- *   own ({@link lastEventSeq}), however the event was recorded
+ *   own ({@link lastEventSeq}), however the event was recorded; and no cancel
+ *   requested, since the state records none — a run a cancel stops in place
+ *   ends `cancelled`
  */
 export function executionStateSummary(state: DataflowExecutionState): ExecutionStateSummary {
   return {
@@ -658,6 +668,7 @@ export function executionStateSummary(state: DataflowExecutionState): ExecutionS
     completedAt: state.completedAt,
     error: state.error,
     lastSeq: lastEventSeq(state),
+    cancelRequested: false,
   };
 }
 

package/src/dataset-type.spec.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { IntegerType, StringType, StructType, variant, type EastTypeValue } from '@elaraai/east';
+import { checkDatasetType } from './dataset-type.js';
+
+/** A tree of `head`s, its wrapper numbered `id`, as a build or a header numbers it. */
+const tree = (id: bigint, head: EastTypeValue): EastTypeValue => variant('Recursive', variant('wrapper', {
+  id,
+  inner: variant('Struct', [
+    { name: 'head', type: head },
+    { name: 'kids', type: variant('Array', variant('Recursive', variant('ref', id))) },
+  ]),
+}));
+const integer: EastTypeValue = variant('Integer', null);
+const string: EastTypeValue = variant('String', null);
+
+describe('checkDatasetType', () => {
+  it('passes the declared type, and names the first difference of another', () => {
+    const Row = StructType({ id: IntegerType, name: StringType });
+    assert.equal(checkDatasetType("dataset '.inputs.rows'", 'the value', Row, Row), null);
+    const mismatch = checkDatasetType("dataset '.inputs.rows'", 'the value', Row, StructType({ id: IntegerType, name: IntegerType }));
+    assert.match(mismatch?.message ?? '', /^dataset '\.inputs\.rows' declares .* but the value carries .* — first difference at /);
+  });
+
+  it('reads a recursive type by its structure: one id on both sides is not one type (#1233)', () => {
+    assert.notEqual(checkDatasetType("dataset '.inputs.tree'", 'the value', tree(0n, integer), tree(0n, string)), null,
+      'a tree of strings is not a tree of integers, whatever id each gives its wrapper');
+    assert.equal(checkDatasetType("dataset '.inputs.tree'", 'the value', tree(228n, integer), tree(0n, integer)), null,
+      "a build's ids and a header's name one structure");
+  });
+});

package/src/dataset-type.ts

@@ -24,14 +24,22 @@
  *
  * **Equality, not assignability.** A runner decodes the object *by the declared
  * type* and beast2 decoding is type-directed, so a blob that is merely a
- * subtype still decodes wrong. `isTypeValueEqual` is the relation.
+ * subtype still decodes wrong.
+ *
+ * **Read by structure.** The bytes may come from another build than the
+ * package's — an app's UI deployed apart from its package, any client — and
+ * each build numbers its recursive types by its own counter, so a recursive
+ * type edited between two builds can keep its id. `isTypeValueEqual` takes one
+ * id as one type without reading it; `isTypeValueStructurallyEqual`, the
+ * relation here, reads it, at under a millisecond for a type as large as a UI
+ * component's.
  *
  * @packageDocumentation
  */
 
 import {
   diffTypeValues,
-  isTypeValueEqual,
+  isTypeValueStructurallyEqual,
   isVariant,
   printTypeValueSummary,
   renderTypeDiff,
@@ -85,7 +93,7 @@ export function checkDatasetType(
 ): DatasetTypeMismatch | null {
   const declaredValue = asTypeValue(declared);
   const givenValue = asTypeValue(given);
-  if (isTypeValueEqual(declaredValue, givenValue)) return null;
+  if (isTypeValueStructurallyEqual(declaredValue, givenValue)) return null;
 
   // Equality failed, so a diff normally localizes it — except where the two are
   // assignable but unequal (a subtype, or the same struct fields in another

package/src/index.ts

@@ -325,17 +325,21 @@ export {
   AsyncOperationStatusType,
   GcStartResultType,
   GcStatusResultType,
+  RepositoryRemovalType,
   // Packages
   PackageListItemType,
   PackageInfoType,
   PackageDetailsType,
   // Workspaces
   WorkspaceCreateRequestType,
+  WorkspaceCopyRequestType,
   WorkspaceInfoType,
   SchemaPolicyType,
+  InputPolicyType,
   WorkspaceDeployRequestType,
   RecordPlanType,
   RecordIndexPlanType,
+  InputPlanType,
   RecordDeployStepType,
   RecordDeployStateType,
   DeployProgressType,
@@ -418,15 +422,19 @@ export {
   type AsyncOperationStatus,
   type GcStartResult,
   type GcStatusResult,
+  type RepositoryRemoval,
   type PackageListItem,
   type PackageInfo,
   type PackageDetails,
   type WorkspaceInfo,
   type WorkspaceCreateRequest,
+  type WorkspaceCopyRequest,
   type WorkspaceDeployRequest,
   type SchemaPolicy,
+  type InputPolicy,
   type RecordPlan,
   type RecordIndexPlan,
+  type InputPlan,
   type RecordDeployStep,
   type RecordDeployState,
   type DeployProgress,

package/src/lock.ts

@@ -35,6 +35,11 @@ import { DeployProgressType } from './api.js';
 
 /**
  * Lock operation - what acquired the lock.
+ *
+ * @remarks
+ * A lock's state is stored, so a case it gains is named to sort after every
+ * case before it: its tag is then the last, and a lock an earlier release left
+ * still reads as itself.
  */
 export const LockOperationType = VariantType({
   /** Running a dataflow */
@@ -47,6 +52,9 @@ export const LockOperationType = VariantType({
   dataset_write: NullType,
   /** Exporting a workspace */
   export: NullType,
+  /** Copying a workspace: the one copied, held shared, and the one it is
+   *  copied onto, held exclusively */
+  workspace_copy: NullType,
 });
 
 export type LockOperation = ValueTypeOf<typeof LockOperationType>;

package/src/release.ts

@@ -17,7 +17,7 @@
  */
 
 /** The release of e3 this build is. */
-export const E3_RELEASE = '1.0.86';
+export const E3_RELEASE = '1.0.88';
 
 /** A semantic version: its core, a pre-release, and build metadata. */
 const RELEASE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;

package/src/task.ts

@@ -91,7 +91,9 @@ export type TaskOutput = ValueTypeOf<typeof TaskOutputType>;
  *
  * @property paths - Dataset paths it reads or writes through `Data.bind`,
  *   including each bound record's own path, so the record's current value is
- *   preloaded and polled like any dataset.
+ *   preloaded and polled like any dataset — but a record it also reads a
+ *   window at a time (`pages`), which is never preloaded or polled whole
+ *   (#1199).
  * @property functions - Package functions it calls through `Func.bind`.
  * @property records - Records it binds through `Record.bind`.
  * @property pages - Dataset paths it reads a window at a time through