@elaraai/e3-types 1.0.79 → 1.0.81

package/dist/src/lock.d.ts

@@ -5,18 +5,19 @@
 /**
  * Lock state type definitions.
  *
- * A lock provides exclusive access to a workspace. The state tracks:
- * - What operation acquired the lock (dataflow, deployment, etc.)
- * - Who holds the lock (East text-encoded string)
- * - When it was acquired
- * - Optional expiry (for cloud TTL-based locks)
+ * A lock gives exclusive or shared access to a resource: a workspace, a
+ * workspace's dataflow, the repository's tasks, or one dataset's ref. The state
+ * records:
+ * - what operation acquired the lock (dataflow, deployment, etc.);
+ * - who holds it: a local process, or a cloud function;
+ * - when it was acquired;
+ * - when it expires, for a cloud backend's lease.
  *
- * Lock file location: workspaces/<name>.lock
+ * 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.
  *
- * The holder field is an East text-encoded string, allowing different backends
- * to encode their own holder identification. Common patterns:
- * - Local: `.process (pid=1234, bootId="abc-123", startTime=98765, command="e3 start")`
- * - Cloud: `.lambda (requestId="req-123", functionName="e3-api")`
+ * A local repository keeps each resource's locks in `locks/<resource>/`.
  */
 import { VariantType, StructType, StringType, IntegerType, DateTimeType, OptionType, NullType, ValueTypeOf } from '@elaraai/east';
 /**
@@ -36,8 +37,8 @@ export declare const LockOperationType: VariantType<{
 }>;
 export type LockOperation = ValueTypeOf<typeof LockOperationType>;
 /**
- * Process holder schema - for local filesystem backends.
- * Used to encode/decode the holder string.
+ * A local process holding a lock: alive while a process of this pid and start
+ * time runs under this boot.
  */
 export declare const ProcessHolderType: StructType<{
     /** Process ID */
@@ -51,14 +52,44 @@ export declare const ProcessHolderType: StructType<{
 }>;
 export type ProcessHolder = ValueTypeOf<typeof ProcessHolderType>;
 /**
- * Lock state stored in workspaces/<name>.lock
- *
- * Represents an advisory lock on a workspace. The actual locking mechanism
- * is platform-specific (flock on Linux, DynamoDB conditional writes in cloud),
- * but the lock content follows this schema.
+ * A cloud function holding a lock, which the lock's lease bounds.
+ */
+export declare const LambdaHolderType: StructType<{
+    /** The invocation's request ID */
+    readonly requestId: StringType;
+    /** The function's name */
+    readonly functionName: StringType;
+}>;
+export type LambdaHolder = ValueTypeOf<typeof LambdaHolderType>;
+/**
+ * Who holds a lock.
+ */
+export declare const LockHolderVariantType: VariantType<{
+    /** A local process */
+    readonly process: StructType<{
+        /** Process ID */
+        readonly pid: IntegerType;
+        /** System boot ID (from /proc/sys/kernel/random/boot_id) */
+        readonly bootId: StringType;
+        /** Process start time in jiffies since boot */
+        readonly startTime: IntegerType;
+        /** Command that acquired the lock (for debugging) */
+        readonly command: StringType;
+    }>;
+    /** A cloud function */
+    readonly lambda: StructType<{
+        /** The invocation's request ID */
+        readonly requestId: StringType;
+        /** The function's name */
+        readonly functionName: StringType;
+    }>;
+}>;
+export type LockHolderVariant = ValueTypeOf<typeof LockHolderVariantType>;
+/**
+ * The state of a held lock.
  *
- * The holder field is an East text-encoded string representing a variant value.
- * Use `printFor`/`parseInferred` from @elaraai/east to encode/decode.
+ * The locking itself is the backend's — an atomically created file locally, a
+ * conditional write in the cloud — and every backend records this state.
  */
 export declare const LockStateType: StructType<{
     /** What operation acquired the lock */
@@ -74,12 +105,213 @@ export declare const LockStateType: StructType<{
         /** Exporting a workspace */
         readonly export: NullType;
     }>;
-    /** Who holds the lock - East text-encoded variant (e.g., `.process (...)`) */
-    readonly holder: StringType;
+    /** Who holds the lock */
+    readonly holder: VariantType<{
+        /** A local process */
+        readonly process: StructType<{
+            /** Process ID */
+            readonly pid: IntegerType;
+            /** System boot ID (from /proc/sys/kernel/random/boot_id) */
+            readonly bootId: StringType;
+            /** Process start time in jiffies since boot */
+            readonly startTime: IntegerType;
+            /** Command that acquired the lock (for debugging) */
+            readonly command: StringType;
+        }>;
+        /** A cloud function */
+        readonly lambda: StructType<{
+            /** The invocation's request ID */
+            readonly requestId: StringType;
+            /** The function's name */
+            readonly functionName: StringType;
+        }>;
+    }>;
     /** When the lock was acquired */
     readonly acquiredAt: DateTimeType;
     /** When the lock expires (for cloud TTL-based locks) */
     readonly expiresAt: OptionType<DateTimeType>;
 }>;
 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 declare const LockProgressType: VariantType<{
+    /** A deploy: its file sources and its records */
+    readonly deployment: StructType<{
+        readonly package: StructType<{
+            readonly name: StringType;
+            readonly version: StringType;
+        }>;
+        readonly startedAt: DateTimeType;
+        readonly files: import("@elaraai/east").ArrayType<StructType<{
+            readonly path: StringType;
+            readonly step: VariantType<{
+                readonly waiting: NullType;
+                readonly hashing: NullType;
+                readonly taking_in: StructType<{
+                    readonly pieces: IntegerType;
+                    readonly done: IntegerType;
+                }>;
+                readonly done: VariantType<{
+                    readonly known: NullType;
+                    readonly carried: NullType;
+                    readonly taken: import("@elaraai/east").ArrayType<StringType>;
+                }>;
+            }>;
+            readonly bytes: IntegerType;
+            readonly total: IntegerType;
+        }>>;
+        readonly records: import("@elaraai/east").ArrayType<StructType<{
+            readonly plan: StructType<{
+                readonly record: StringType;
+                readonly action: VariantType<{
+                    readonly mint: NullType;
+                    readonly keep: StructType<{
+                        readonly deploy: import("@elaraai/east").BooleanType;
+                    }>;
+                    readonly migrate: StructType<{
+                        readonly steps: import("@elaraai/east").ArrayType<StringType>;
+                    }>;
+                    readonly reset: StructType<{
+                        readonly reason: StringType;
+                    }>;
+                    readonly drop: NullType;
+                    readonly refused: StructType<{
+                        readonly reason: StringType;
+                    }>;
+                }>;
+            }>;
+            readonly indexes: import("@elaraai/east").ArrayType<StringType>;
+            readonly step: VariantType<{
+                readonly waiting: NullType;
+                readonly migrating: StructType<{
+                    readonly name: StringType;
+                    readonly step: IntegerType;
+                    readonly steps: IntegerType;
+                }>;
+                readonly indexing: StructType<{
+                    readonly index: StringType;
+                    readonly build: IntegerType;
+                    readonly builds: IntegerType;
+                }>;
+                readonly done: NullType;
+            }>;
+        }>>;
+    }>;
+}>;
+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 declare const LockStatusType: StructType<{
+    /** The lock's state: the operation, its holder, and when it was acquired */
+    readonly state: StructType<{
+        /** What operation acquired the lock */
+        readonly operation: VariantType<{
+            /** Running a dataflow */
+            readonly dataflow: NullType;
+            /** Deploying a package to the workspace */
+            readonly deployment: NullType;
+            /** Removing the workspace */
+            readonly removal: NullType;
+            /** Writing to a dataset */
+            readonly dataset_write: NullType;
+            /** Exporting a workspace */
+            readonly export: NullType;
+        }>;
+        /** Who holds the lock */
+        readonly holder: VariantType<{
+            /** A local process */
+            readonly process: StructType<{
+                /** Process ID */
+                readonly pid: IntegerType;
+                /** System boot ID (from /proc/sys/kernel/random/boot_id) */
+                readonly bootId: StringType;
+                /** Process start time in jiffies since boot */
+                readonly startTime: IntegerType;
+                /** Command that acquired the lock (for debugging) */
+                readonly command: StringType;
+            }>;
+            /** A cloud function */
+            readonly lambda: StructType<{
+                /** The invocation's request ID */
+                readonly requestId: StringType;
+                /** The function's name */
+                readonly functionName: StringType;
+            }>;
+        }>;
+        /** When the lock was acquired */
+        readonly acquiredAt: DateTimeType;
+        /** When the lock expires (for cloud TTL-based locks) */
+        readonly expiresAt: OptionType<DateTimeType>;
+    }>;
+    /** What the holder last reported of its progress; `none` until it reports */
+    readonly progress: OptionType<VariantType<{
+        /** A deploy: its file sources and its records */
+        readonly deployment: StructType<{
+            readonly package: StructType<{
+                readonly name: StringType;
+                readonly version: StringType;
+            }>;
+            readonly startedAt: DateTimeType;
+            readonly files: import("@elaraai/east").ArrayType<StructType<{
+                readonly path: StringType;
+                readonly step: VariantType<{
+                    readonly waiting: NullType;
+                    readonly hashing: NullType;
+                    readonly taking_in: StructType<{
+                        readonly pieces: IntegerType;
+                        readonly done: IntegerType;
+                    }>;
+                    readonly done: VariantType<{
+                        readonly known: NullType;
+                        readonly carried: NullType;
+                        readonly taken: import("@elaraai/east").ArrayType<StringType>;
+                    }>;
+                }>;
+                readonly bytes: IntegerType;
+                readonly total: IntegerType;
+            }>>;
+            readonly records: import("@elaraai/east").ArrayType<StructType<{
+                readonly plan: StructType<{
+                    readonly record: StringType;
+                    readonly action: VariantType<{
+                        readonly mint: NullType;
+                        readonly keep: StructType<{
+                            readonly deploy: import("@elaraai/east").BooleanType;
+                        }>;
+                        readonly migrate: StructType<{
+                            readonly steps: import("@elaraai/east").ArrayType<StringType>;
+                        }>;
+                        readonly reset: StructType<{
+                            readonly reason: StringType;
+                        }>;
+                        readonly drop: NullType;
+                        readonly refused: StructType<{
+                            readonly reason: StringType;
+                        }>;
+                    }>;
+                }>;
+                readonly indexes: import("@elaraai/east").ArrayType<StringType>;
+                readonly step: VariantType<{
+                    readonly waiting: NullType;
+                    readonly migrating: StructType<{
+                        readonly name: StringType;
+                        readonly step: IntegerType;
+                        readonly steps: IntegerType;
+                    }>;
+                    readonly indexing: StructType<{
+                        readonly index: StringType;
+                        readonly build: IntegerType;
+                        readonly builds: IntegerType;
+                    }>;
+                    readonly done: NullType;
+                }>;
+            }>>;
+        }>;
+    }>>;
+}>;
+export type LockStatus = ValueTypeOf<typeof LockStatusType>;
 //# sourceMappingURL=lock.d.ts.map

package/dist/src/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,yBAAyB;;IAEzB,2CAA2C;;IAE3C,6BAA6B;;IAE7B,2BAA2B;;IAE3B,4BAA4B;;EAE5B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,iBAAiB;;IAEjB,4DAA4D;;IAE5D,+CAA+C;;IAE/C,qDAAqD;;EAErD,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;IACxB,uCAAuC;;QA1CvC,yBAAyB;;QAEzB,2CAA2C;;QAE3C,6BAA6B;;QAE7B,2BAA2B;;QAE3B,4BAA4B;;;IAoC5B,8EAA8E;;IAE9E,iCAAiC;;IAEjC,wDAAwD;;EAExD,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,WAAW,EACZ,MAAM,eAAe,CAAC;AAGvB;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,yBAAyB;;IAEzB,2CAA2C;;IAE3C,6BAA6B;;IAE7B,2BAA2B;;IAE3B,4BAA4B;;EAE5B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,iBAAiB;;IAEjB,4DAA4D;;IAE5D,+CAA+C;;IAE/C,qDAAqD;;EAErD,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B,kCAAkC;;IAElC,0BAA0B;;EAE1B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,sBAAsB;;QA5BtB,iBAAiB;;QAEjB,4DAA4D;;QAE5D,+CAA+C;;QAE/C,qDAAqD;;;IAwBrD,uBAAuB;;QAdvB,kCAAkC;;QAElC,0BAA0B;;;EAc1B,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,aAAa;IACxB,uCAAuC;;QA9DvC,yBAAyB;;QAEzB,2CAA2C;;QAE3C,6BAA6B;;QAE7B,2BAA2B;;QAE3B,4BAA4B;;;IAwD5B,yBAAyB;;QAjBzB,sBAAsB;;YA5BtB,iBAAiB;;YAEjB,4DAA4D;;YAE5D,+CAA+C;;YAE/C,qDAAqD;;;QAwBrD,uBAAuB;;YAdvB,kCAAkC;;YAElC,0BAA0B;;;;IA6B1B,iCAAiC;;IAEjC,wDAAwD;;EAExD,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEjD,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB,4EAA4E;;QA5B5E,uCAAuC;;YA9DvC,yBAAyB;;YAEzB,2CAA2C;;YAE3C,6BAA6B;;YAE7B,2BAA2B;;YAE3B,4BAA4B;;;QAwD5B,yBAAyB;;YAjBzB,sBAAsB;;gBA5BtB,iBAAiB;;gBAEjB,4DAA4D;;gBAE5D,+CAA+C;;gBAE/C,qDAAqD;;;YAwBrD,uBAAuB;;gBAdvB,kCAAkC;;gBAElC,0BAA0B;;;;QA6B1B,iCAAiC;;QAEjC,wDAAwD;;;IAwBxD,6EAA6E;;QAb7E,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAejD,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/src/lock.js

@@ -5,20 +5,22 @@
 /**
  * Lock state type definitions.
  *
- * A lock provides exclusive access to a workspace. The state tracks:
- * - What operation acquired the lock (dataflow, deployment, etc.)
- * - Who holds the lock (East text-encoded string)
- * - When it was acquired
- * - Optional expiry (for cloud TTL-based locks)
+ * A lock gives exclusive or shared access to a resource: a workspace, a
+ * workspace's dataflow, the repository's tasks, or one dataset's ref. The state
+ * records:
+ * - what operation acquired the lock (dataflow, deployment, etc.);
+ * - who holds it: a local process, or a cloud function;
+ * - when it was acquired;
+ * - when it expires, for a cloud backend's lease.
  *
- * Lock file location: workspaces/<name>.lock
+ * 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.
  *
- * The holder field is an East text-encoded string, allowing different backends
- * to encode their own holder identification. Common patterns:
- * - Local: `.process (pid=1234, bootId="abc-123", startTime=98765, command="e3 start")`
- * - Cloud: `.lambda (requestId="req-123", functionName="e3-api")`
+ * A local repository keeps each resource's locks in `locks/<resource>/`.
  */
 import { VariantType, StructType, StringType, IntegerType, DateTimeType, OptionType, NullType, } from '@elaraai/east';
+import { DeployProgressType } from './api.js';
 /**
  * Lock operation - what acquired the lock.
  */
@@ -35,8 +37,8 @@ export const LockOperationType = VariantType({
     export: NullType,
 });
 /**
- * Process holder schema - for local filesystem backends.
- * Used to encode/decode the holder string.
+ * A local process holding a lock: alive while a process of this pid and start
+ * time runs under this boot.
  */
 export const ProcessHolderType = StructType({
     /** Process ID */
@@ -49,23 +51,55 @@ export const ProcessHolderType = StructType({
     command: StringType,
 });
 /**
- * Lock state stored in workspaces/<name>.lock
- *
- * Represents an advisory lock on a workspace. The actual locking mechanism
- * is platform-specific (flock on Linux, DynamoDB conditional writes in cloud),
- * but the lock content follows this schema.
+ * A cloud function holding a lock, which the lock's lease bounds.
+ */
+export const LambdaHolderType = StructType({
+    /** The invocation's request ID */
+    requestId: StringType,
+    /** The function's name */
+    functionName: StringType,
+});
+/**
+ * Who holds a lock.
+ */
+export const LockHolderVariantType = VariantType({
+    /** A local process */
+    process: ProcessHolderType,
+    /** A cloud function */
+    lambda: LambdaHolderType,
+});
+/**
+ * The state of a held lock.
  *
- * The holder field is an East text-encoded string representing a variant value.
- * Use `printFor`/`parseInferred` from @elaraai/east to encode/decode.
+ * The locking itself is the backend's — an atomically created file locally, a
+ * conditional write in the cloud — and every backend records this state.
  */
 export const LockStateType = StructType({
     /** What operation acquired the lock */
     operation: LockOperationType,
-    /** Who holds the lock - East text-encoded variant (e.g., `.process (...)`) */
-    holder: StringType,
+    /** Who holds the lock */
+    holder: LockHolderVariantType,
     /** When the lock was acquired */
     acquiredAt: DateTimeType,
     /** When the lock expires (for cloud TTL-based locks) */
     expiresAt: OptionType(DateTimeType),
 });
+/**
+ * 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,
+});
+/**
+ * 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),
+});
 //# sourceMappingURL=lock.js.map

package/dist/src/lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,GAET,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;IAC3C,yBAAyB;IACzB,QAAQ,EAAE,QAAQ;IAClB,2CAA2C;IAC3C,UAAU,EAAE,QAAQ;IACpB,6BAA6B;IAC7B,OAAO,EAAE,QAAQ;IACjB,2BAA2B;IAC3B,aAAa,EAAE,QAAQ;IACvB,4BAA4B;IAC5B,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;IAC1C,iBAAiB;IACjB,GAAG,EAAE,WAAW;IAChB,4DAA4D;IAC5D,MAAM,EAAE,UAAU;IAClB,+CAA+C;IAC/C,SAAS,EAAE,WAAW;IACtB,qDAAqD;IACrD,OAAO,EAAE,UAAU;CACpB,CAAC,CAAC;AAIH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;IACtC,uCAAuC;IACvC,SAAS,EAAE,iBAAiB;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,UAAU;IAClB,iCAAiC;IACjC,UAAU,EAAE,YAAY;IACxB,wDAAwD;IACxD,SAAS,EAAE,UAAU,CAAC,YAAY,CAAC;CACpC,CAAC,CAAC"}
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,GAET,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;IAC3C,yBAAyB;IACzB,QAAQ,EAAE,QAAQ;IAClB,2CAA2C;IAC3C,UAAU,EAAE,QAAQ;IACpB,6BAA6B;IAC7B,OAAO,EAAE,QAAQ;IACjB,2BAA2B;IAC3B,aAAa,EAAE,QAAQ;IACvB,4BAA4B;IAC5B,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;IAC1C,iBAAiB;IACjB,GAAG,EAAE,WAAW;IAChB,4DAA4D;IAC5D,MAAM,EAAE,UAAU;IAClB,+CAA+C;IAC/C,SAAS,EAAE,WAAW;IACtB,qDAAqD;IACrD,OAAO,EAAE,UAAU;CACpB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;IACzC,kCAAkC;IAClC,SAAS,EAAE,UAAU;IACrB,0BAA0B;IAC1B,YAAY,EAAE,UAAU;CACzB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;IAC/C,sBAAsB;IACtB,OAAO,EAAE,iBAAiB;IAC1B,uBAAuB;IACvB,MAAM,EAAE,gBAAgB;CACzB,CAAC,CAAC;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;IACtC,uCAAuC;IACvC,SAAS,EAAE,iBAAiB;IAC5B,yBAAyB;IACzB,MAAM,EAAE,qBAAqB;IAC7B,iCAAiC;IACjC,UAAU,EAAE,YAAY;IACxB,wDAAwD;IACxD,SAAS,EAAE,UAAU,CAAC,YAAY,CAAC;CACpC,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;IAC1C,iDAAiD;IACjD,UAAU,EAAE,kBAAkB;CAC/B,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACvC,4EAA4E;IAC5E,KAAK,EAAE,aAAa;IACpB,6EAA6E;IAC7E,QAAQ,EAAE,UAAU,CAAC,gBAAgB,CAAC;CACvC,CAAC,CAAC"}

package/dist/src/names.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The rule for the names e3 makes paths of: a repository's name where a server
+ * keeps several, a workspace's name, a package's name and version, and a
+ * lock's resource. One place holds it, so the SDK, the CLI, the API server and
+ * the stores refuse the same names.
+ */
+/** What a name names. */
+export type NamedKind = 'repository' | 'workspace' | 'package' | 'package version' | 'lock';
+/**
+ * Why a name cannot be one path segment, or `null` when it can.
+ *
+ * @param kind - What the name names
+ * @param name - The name
+ * @returns The problem, in words that follow the name, or `null`
+ */
+export declare function nameProblem(kind: NamedKind, name: string): string | null;
+//# sourceMappingURL=names.d.ts.map

package/dist/src/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/names.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,yBAAyB;AACzB,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAU5F;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQxE"}

package/dist/src/names.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** What no name may hold: a path separator, a character a Windows file name
+ *  refuses, or a control character. */
+const REFUSED = /[/\\:*?"<>|\u0000-\u001f]/;
+/** What a workspace's name may not hold besides: the characters that join the
+ *  parts of its locks' names. */
+const REFUSED_IN_WORKSPACE = /[#~]/;
+/**
+ * Why a name cannot be one path segment, or `null` when it can.
+ *
+ * @param kind - What the name names
+ * @param name - The name
+ * @returns The problem, in words that follow the name, or `null`
+ */
+export function nameProblem(kind, name) {
+    if (name === '')
+        return 'is empty';
+    if (name === '.' || name === '..')
+        return 'is a path of its own';
+    const refused = REFUSED.exec(name);
+    if (refused !== null)
+        return `holds ${JSON.stringify(refused[0])}, which a file name cannot`;
+    const joiner = kind === 'workspace' ? REFUSED_IN_WORKSPACE.exec(name) : null;
+    if (joiner !== null)
+        return `holds ${JSON.stringify(joiner[0])}, which joins the parts of a lock's name`;
+    return null;
+}
+//# sourceMappingURL=names.js.map

package/dist/src/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/names.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;uCACuC;AACvC,MAAM,OAAO,GAAG,2BAA2B,CAAC;AAE5C;iCACiC;AACjC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe,EAAE,IAAY;IACvD,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IACnC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,sBAAsB,CAAC;IACjE,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,4BAA4B,CAAC;IAC7F,MAAM,MAAM,GAAG,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,0CAA0C,CAAC;IACzG,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/package.d.ts

@@ -88,73 +88,6 @@ export declare const PackageDataType: StructType<{
 }>;
 export type PackageDataType = typeof PackageDataType;
 export type PackageData = ValueTypeOf<typeof PackageDataType>;
-/** @deprecated Use PackageDataType instead */
-export declare const PackageDatasetsType: StructType<{
-    /** Structure defining tree shape (what's a group vs dataset) */
-    readonly structure: import("@elaraai/east").RecursiveType<VariantType<{
-        readonly value: StructType<{
-            readonly type: import("@elaraai/east").RecursiveType<VariantType<{
-                readonly Never: NullType;
-                readonly Null: NullType;
-                readonly Boolean: NullType;
-                readonly Integer: NullType;
-                readonly Float: NullType;
-                readonly String: NullType;
-                readonly DateTime: NullType;
-                readonly Blob: NullType;
-                readonly Ref: import("@elaraai/east").RecursiveTypeMarker;
-                readonly Array: import("@elaraai/east").RecursiveTypeMarker;
-                readonly Set: import("@elaraai/east").RecursiveTypeMarker;
-                readonly Dict: StructType<{
-                    readonly key: import("@elaraai/east").RecursiveTypeMarker;
-                    readonly value: import("@elaraai/east").RecursiveTypeMarker;
-                }>;
-                readonly Struct: import("@elaraai/east").ArrayType<StructType<{
-                    readonly name: StringType;
-                    readonly type: import("@elaraai/east").RecursiveTypeMarker;
-                }>>;
-                readonly Variant: import("@elaraai/east").ArrayType<StructType<{
-                    readonly name: StringType;
-                    readonly type: import("@elaraai/east").RecursiveTypeMarker;
-                }>>;
-                readonly Recursive: VariantType<{
-                    readonly ref: IntegerType;
-                    readonly wrapper: StructType<{
-                        readonly id: IntegerType;
-                        readonly inner: import("@elaraai/east").RecursiveTypeMarker;
-                    }>;
-                }>;
-                readonly Function: StructType<{
-                    readonly inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
-                    readonly output: import("@elaraai/east").RecursiveTypeMarker;
-                }>;
-                readonly AsyncFunction: StructType<{
-                    readonly inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
-                    readonly output: import("@elaraai/east").RecursiveTypeMarker;
-                }>;
-                readonly Vector: import("@elaraai/east").RecursiveTypeMarker;
-                readonly Matrix: import("@elaraai/east").RecursiveTypeMarker;
-            }>>;
-            readonly writable: import("@elaraai/east").BooleanType;
-        }>;
-        readonly struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
-    }>>;
-    /** Per-dataset refs: refPath (e.g. "inputs/greeting") -> DatasetRef */
-    readonly refs: DictType<StringType, VariantType<{
-        readonly unassigned: NullType;
-        readonly null: StructType<{
-            readonly versions: DictType<StringType, StringType>;
-        }>;
-        readonly value: StructType<{
-            readonly hash: StringType;
-            readonly versions: DictType<StringType, StringType>;
-        }>;
-    }>>;
-}>;
-/** @deprecated Use PackageData instead */
-export type PackageDatasetsType = PackageDataType;
-/** @deprecated Use PackageData instead */
-export type PackageDatasets = PackageData;
 /**
  * Package object stored in the object store.
  *
@@ -270,12 +203,9 @@ export declare const PackageObjectType: StructType<{
     }>;
     /** Functions defined in this package: name -> FunctionObject hash. */
     readonly functions: DictType<StringType, StringType>;
-    /** Records defined in this package: name -> RecordObject hash.
-     *  BEAST2 encodes struct fields positionally in declaration order, so new
-     *  fields MUST be appended LAST — never inserted between existing fields. */
+    /** Records defined in this package: name -> RecordObject hash. */
     readonly records: DictType<StringType, StringType>;
-    /** Unresolved dataset sources: refPath (e.g. "inputs/table") -> descriptor.
-     *  Appended LAST, per the positional rule above. */
+    /** Unresolved dataset sources: refPath (e.g. "inputs/table") -> descriptor. */
     readonly sources: DictType<StringType, VariantType<{
         /** A path on the machine that DEPLOYS the package, resolved at deploy. */
         readonly file: StructType<{
@@ -286,13 +216,16 @@ export declare const PackageObjectType: StructType<{
 export type PackageObjectType = typeof PackageObjectType;
 export type PackageObject = ValueTypeOf<typeof PackageObjectType>;
 /**
- * Decode a `PackageObject` from BEAST2 bytes, tolerating the older wire
- * formats (dual-decode migration).
+ * Decode a `PackageObject` from BEAST2 bytes.
+ *
+ * @remarks
+ * A package-borne wire, so it changes by hard cutover: a package exported by
+ * an older SDK is re-exported with the current one, and this says so.
  *
- * Every package-read path — local AND cloud — must use this instead of
- * `decodeBeast2For(PackageObjectType)` directly, so packages exported before
- * the `sources`/`records`/`functions` fields existed keep decoding. Older
- * bytes decode with the missing maps defaulted to empty.
+ * @param data - the stored bytes
+ * @returns the package object
+ * @throws {Error} When the bytes are not a current package object — a package
+ *   exported by an older SDK, which is re-exported with the current one.
  */
 export declare function decodePackageObject(data: Uint8Array): PackageObject;
 export declare const PackageTransferInitRequestType: StructType<{

package/dist/src/package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAC;AAInI;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;IAC1B,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEhE,uEAAuE;;;;;;;;;;;EAEvE,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;IAChC,0EAA0E;;;;EAE1E,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC;AACjE,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,iBAAiB;IAC5B,8DAA8D;;IAE9D,wCAAwC;;QA1DxC,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAEhE,uEAAuE;;;;;;;;;;;;IA0DvE,sEAAsE;;IAEtE,kEAAkE;;IAElE,+EAA+E;;QAf/E,0EAA0E;;;;;EAiB1E,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAIlE;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CASnE;AAMD,eAAO,MAAM,8BAA8B;;EAEzC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE5F,eAAO,MAAM,+BAA+B;;;EAG1C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE9F,eAAO,MAAM,sBAAsB;;EAEjC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,uBAAuB;;;;;EAKlC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,eAAO,MAAM,uBAAuB;;;EAGlC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,eAAO,MAAM,yBAAyB;;;;;;EAIpC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;EAMlC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,eAAO,MAAM,yBAAyB;;;;;;EAIpC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAMlC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC"}