@elaraai/e3-types 1.0.80 → 1.0.81

package/src/index.ts

@@ -204,8 +204,21 @@ export {
   type LockHolderVariant,
   LockStateType,
   type LockState,
+  LockProgressType,
+  type LockProgress,
+  LockStatusType,
+  type LockStatus,
 } from './lock.js';
 
+// How far a file being taken into the store has got: a deploy's file source,
+// or an upload's delivery as its commit takes it in
+export {
+  IntakeStepType,
+  type IntakeStep,
+  IntakeFileType,
+  type IntakeFile,
+} from './intake.js';
+
 // The repository's own records
 export {
   RepositoryRecordType,
@@ -316,6 +329,9 @@ export {
   WorkspaceDeployRequestType,
   RecordPlanType,
   RecordIndexPlanType,
+  RecordDeployStepType,
+  RecordDeployStateType,
+  DeployProgressType,
   WorkspaceDeployResultType,
   WorkspaceDeployProgressType,
   WorkspaceDeployStatusType,
@@ -386,6 +402,9 @@ export {
   type SchemaPolicy,
   type RecordPlan,
   type RecordIndexPlan,
+  type RecordDeployStep,
+  type RecordDeployState,
+  type DeployProgress,
   type WorkspaceDeployResult,
   type WorkspaceDeployProgress,
   type WorkspaceDeployStatus,

package/src/intake.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * How far a file being taken into the store has got: a deploy's file source,
+ * or an upload's delivery as its commit takes it in.
+ *
+ * A file is hashed first, since its SHA-256 is how the store knows a delivery
+ * it already holds, and then taken in: a collection by intake units on the
+ * runners, a piece of its segments each, and any other value as the object the
+ * file is.
+ */
+
+import { ArrayType, IntegerType, NullType, StringType, StructType, VariantType, type ValueTypeOf } from '@elaraai/east';
+
+/**
+ * The step a file being taken in is at.
+ */
+export const IntakeStepType = VariantType({
+  /** Not started: a deploy takes a bounded number of files in at once */
+  waiting: NullType,
+  /** Being read for its SHA-256, by which the store knows a delivery it
+   *  already holds */
+  hashing: NullType,
+  /** Being taken in by intake units: its `pieces`, and how many are `done` */
+  taking_in: StructType({ pieces: IntegerType, done: IntegerType }),
+  /** In the store: one it already held; a value that is not a collection,
+   *  carried as the object the file is; or a collection, taken in by the
+   *  runners named, in the order each first took a piece in — none when every
+   *  piece was taken in before, by an intake that stopped part way */
+  done: VariantType({ known: NullType, carried: NullType, taken: ArrayType(StringType) }),
+});
+
+export type IntakeStep = ValueTypeOf<typeof IntakeStepType>;
+
+/**
+ * A file being taken into the store.
+ */
+export const IntakeFileType = StructType({
+  /** The dataset it becomes, as `inputs/<name>` */
+  path: StringType,
+  /** The step it is at */
+  step: IntakeStepType,
+  /** Bytes of the file its step has covered: read for its hash, or covered by
+   *  the pieces taken in; its size once it is done */
+  bytes: IntegerType,
+  /** The file's size */
+  total: IntegerType,
+});
+
+export type IntakeFile = ValueTypeOf<typeof IntakeFileType>;

package/src/lock.ts

@@ -14,6 +14,10 @@
  * - when it was acquired;
  * - when it expires, for a cloud backend's lease.
  *
+ * An exclusive holder may also report how far its operation has got, for
+ * another process to read while it holds the lock: a deploy taking its file
+ * sources in and deploying its records.
+ *
  * A local repository keeps each resource's locks in `locks/<resource>/`.
  */
 
@@ -27,6 +31,7 @@ import {
   NullType,
   ValueTypeOf,
 } from '@elaraai/east';
+import { DeployProgressType } from './api.js';
 
 /**
  * Lock operation - what acquired the lock.
@@ -105,3 +110,27 @@ export const LockStateType = StructType({
 });
 
 export type LockState = ValueTypeOf<typeof LockStateType>;
+
+/**
+ * How far the operation holding a lock exclusively has got, as its holder
+ * reports it for another process to read while it holds the lock.
+ */
+export const LockProgressType = VariantType({
+  /** A deploy: its file sources and its records */
+  deployment: DeployProgressType,
+});
+
+export type LockProgress = ValueTypeOf<typeof LockProgressType>;
+
+/**
+ * A resource's exclusive lock as another process reads it while it is held:
+ * what holds it, and how far that operation says it has got.
+ */
+export const LockStatusType = StructType({
+  /** The lock's state: the operation, its holder, and when it was acquired */
+  state: LockStateType,
+  /** What the holder last reported of its progress; `none` until it reports */
+  progress: OptionType(LockProgressType),
+});
+
+export type LockStatus = ValueTypeOf<typeof LockStatusType>;

package/src/release.ts

@@ -17,7 +17,7 @@
  */
 
 /** The release of e3 this build is. */
-export const E3_RELEASE = '1.0.79';
+export const E3_RELEASE = '1.0.81';
 
 /** 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/transfer.ts

@@ -16,7 +16,8 @@
  * newer server that speak one version work together.
  */
 
-import { VariantType, StructType, StringType, IntegerType, NullType, DictType, type ValueTypeOf } from '@elaraai/east';
+import { VariantType, StructType, StringType, IntegerType, NullType, DictType, OptionType, type ValueTypeOf } from '@elaraai/east';
+import { IntakeFileType } from './intake.js';
 
 /**
  * The dataset transfer protocol version this build speaks, and the only one.
@@ -25,10 +26,10 @@ import { VariantType, StructType, StringType, IntegerType, NullType, DictType, t
  * The server plans an upload as parts — each sent to its own URL with the
  * request headers the server names, so an object store can bind a checksum to
  * a single PUT or take a multipart upload larger than one PUT allows — and a
- * commit may answer `processing` while the server verifies the bytes, for the
- * client to poll.
+ * commit may answer `processing` while the server verifies the bytes and takes
+ * them in, with how far it has got, for the client to poll.
  */
-export const TRANSFER_PROTOCOL_VERSION = 2;
+export const TRANSFER_PROTOCOL_VERSION = 3;
 
 /**
  * How many parts an upload of `size` bytes has when planned with `partBytes`.
@@ -118,14 +119,15 @@ export type TransferPartResponse = ValueTypeOf<typeof TransferPartResponseType>;
  *
  * - `completed`: Hash verified, object stored, dataset ref updated
  * - `error`: Hash mismatch or other failure
- * - `processing`: the server is still verifying the bytes; poll
- *   `GET …/upload/<id>` until it answers `completed` or `error`
+ * - `processing`: the server is still verifying the bytes or taking them in,
+ *   with how far it has got once it has said; poll `GET …/upload/<id>` until
+ *   it answers `completed` or `error`
  */
 export const TransferDoneResponseType = VariantType({
   completed: NullType,
   error: StructType({
     message: StringType,
   }),
-  processing: NullType,
+  processing: OptionType(IntakeFileType),
 });
 export type TransferDoneResponse = ValueTypeOf<typeof TransferDoneResponseType>;