@elaraai/e3-types 1.0.79 → 1.0.81

package/src/api.ts

@@ -36,7 +36,10 @@ import {
 } from '@elaraai/east';
 
 import { StructureType, TreePathType } from './structure.js';
+import { IntakeFileType } from './intake.js';
 import { RunnerType } from './runner.js';
+import { TaskBodyType, TaskInputType, TaskOutputType, TaskRoleType } from './task.js';
+import { RequeueReasonType, StageUnitType } from './dataflow.js';
 
 // =============================================================================
 // Error Types
@@ -78,6 +81,13 @@ export const DatasetTypeMismatchErrorType = StructType({
   path: StringType,
   message: StringType,
 });
+/** A name e3 would make a path of that cannot be one path segment: a
+ *  repository's, a workspace's, or a package's name or version. */
+export const InvalidNameErrorType = StructType({
+  kind: StringType,
+  name: StringType,
+  message: StringType,
+});
 
 export const ErrorType = VariantType({
   repository_not_found: RepositoryNotFoundErrorType,
@@ -96,9 +106,8 @@ export const ErrorType = VariantType({
   dataflow_aborted: NullType,
   permission_denied: PermissionDeniedErrorType,
   internal: InternalErrorType,
-  // Appended last: BEAST2 encodes a variant case by index, so a case added at
-  // the end leaves every existing payload decodable.
   dataset_type_mismatch: DatasetTypeMismatchErrorType,
+  invalid_name: InvalidNameErrorType,
 });
 
 // =============================================================================
@@ -134,10 +143,16 @@ export const RepositoryStatusType = StructType({
  *
  * @property dryRun - If true, report what would be deleted without deleting
  * @property minAge - Minimum age in milliseconds for objects to be considered for deletion
+ * @property keepRuns - The runs of each workspace kept however old, the latest
+ *   first; the server's default when `none`
+ * @property keepDays - The days of runs and executions kept however many; the
+ *   server's default when `none`
  */
 export const GcRequestType = StructType({
   dryRun: BooleanType,
   minAge: OptionType(IntegerType),
+  keepRuns: OptionType(IntegerType),
+  keepDays: OptionType(IntegerType),
 });
 
 /**
@@ -148,6 +163,9 @@ export const GcRequestType = StructType({
  * @property retainedObjects - Number of objects still referenced
  * @property skippedYoung - Number of objects skipped due to minAge
  * @property bytesFreed - Total bytes freed by deletion
+ * @property deletedRuns - Number of dataflow run records deleted
+ * @property deletedExecutions - Number of execution attempts deleted, each with
+ *   its owner record and logs
  */
 export const GcResultType = StructType({
   deletedObjects: IntegerType,
@@ -155,6 +173,8 @@ export const GcResultType = StructType({
   retainedObjects: IntegerType,
   skippedYoung: IntegerType,
   bytesFreed: IntegerType,
+  deletedRuns: IntegerType,
+  deletedExecutions: IntegerType,
 });
 
 // =============================================================================
@@ -269,13 +289,164 @@ export const WorkspaceInfoType = StructType({
   packageVersion: OptionType(StringType),
 });
 
+/**
+ * What a deploy does with a record it cannot keep as it is.
+ *
+ * - `migrate`: run the migrations the workspace has not applied, and refuse a
+ *   record no migration carries to the package's type
+ * - `fail`: run none, and refuse a record with migrations to run, for a
+ *   workspace whose migrations go through their own change control
+ * - `reset`: reset a record it can neither keep nor migrate to the package's
+ *   initial value, under a `$reset` commit, so the reset is in its history
+ */
+export const SchemaPolicyType = VariantType({
+  migrate: NullType,
+  fail: 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 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
  */
 export const WorkspaceDeployRequestType = StructType({
   packageRef: StringType,
+  schema: SchemaPolicyType,
+  allowDropRecords: BooleanType,
+  plan: BooleanType,
+});
+
+/**
+ * What a deploy decided for one record.
+ *
+ * @property record - The record's dataset ref path
+ * @property action - What the deploy does to it:
+ *   - `mint`: the workspace does not hold it, so it is minted from the
+ *     package's initial value
+ *   - `keep`: kept as the workspace holds it; `deploy` when the package under
+ *     it changed, which a `$deploy` commit records in its history
+ *   - `migrate`: migrated by the steps the workspace has not applied, in order
+ *   - `reset`: reset to the package's initial value under the `reset` policy,
+ *     and why it could not be kept or migrated
+ *   - `drop`: the package does not declare it, so it is dropped, with its
+ *     state and history
+ *   - `refused`: refused, and why, with the fix: the deploy writes nothing
+ */
+export const RecordPlanType = StructType({
+  record: StringType,
+  action: VariantType({
+    mint: NullType,
+    keep: StructType({ deploy: BooleanType }),
+    migrate: StructType({ steps: ArrayType(StringType) }),
+    reset: StructType({ reason: StringType }),
+    drop: NullType,
+    refused: StructType({ reason: StringType }),
+  }),
+});
+
+/**
+ * What a deploy decided for one of a record's indexes.
+ *
+ * @property record - The record's dataset ref path
+ * @property index - The index's name
+ * @property action - `build` when the state names no index under the
+ *   package's declaration, `drop` when it names one the package does not
+ *   declare, and `keep` when the two agree and nothing runs
+ */
+export const RecordIndexPlanType = StructType({
+  record: StringType,
+  index: StringType,
+  action: VariantType({
+    build: NullType,
+    drop: NullType,
+    keep: NullType,
+  }),
+});
+
+/**
+ * The step a deploy is at with one record.
+ *
+ * - `waiting`: its turn has not come, or it needs nothing but the deploy's
+ *   commit
+ * - `migrating`: running migration step `step` of the `steps` it owes, `name`
+ * - `indexing`: building `index`, the `build`th of the `builds` it owes
+ * - `done`: its migrations and index builds have run
+ */
+export const RecordDeployStepType = VariantType({
+  waiting: NullType,
+  migrating: StructType({ name: StringType, step: IntegerType, steps: IntegerType }),
+  indexing: StructType({ index: StringType, build: IntegerType, builds: IntegerType }),
+  done: NullType,
+});
+
+/**
+ * One record a deploy is deploying.
+ *
+ * @property plan - What the deploy decided for it
+ * @property indexes - The indexes the package declares for it
+ * @property step - How far the deploy has got with it
+ */
+export const RecordDeployStateType = StructType({
+  plan: RecordPlanType,
+  indexes: ArrayType(StringType),
+  step: RecordDeployStepType,
+});
+
+/**
+ * How far a deploy has got, for a client to show while it runs.
+ *
+ * @property package - The package it deploys
+ * @property startedAt - When it began taking its files in
+ * @property files - Each file source it takes in, in the package's order
+ * @property records - Each record it deploys, in the package's order, and
+ *   each it drops
+ */
+export const DeployProgressType = StructType({
+  package: StructType({ name: StringType, version: StringType }),
+  startedAt: DateTimeType,
+  files: ArrayType(IntakeFileType),
+  records: ArrayType(RecordDeployStateType),
+});
+
+/**
+ * What a deploy did, or under `plan` would do.
+ *
+ * @property records - What it decided for each record
+ * @property indexes - What it decided for each index of the records it keeps
+ * @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),
+  warnings: ArrayType(StringType),
+});
+
+/**
+ * A deploy job's progress: `pending` until it starts, then `deploying`, with
+ * how far it has got once it has said.
+ */
+export const WorkspaceDeployProgressType = VariantType({
+  pending: NullType,
+  deploying: OptionType(DeployProgressType),
+});
+
+/**
+ * A deploy job's status.
+ *
+ * - `processing`: still running, and how far it has got
+ * - `completed`: what the deploy did
+ * - `failed`: why it did not
+ */
+export const WorkspaceDeployStatusType = VariantType({
+  processing: WorkspaceDeployProgressType,
+  completed: WorkspaceDeployResultType,
+  failed: StructType({ message: StringType }),
 });
 
 /**
@@ -391,6 +562,9 @@ export const DatasetStatusInfoType = StructType({
  * @property inputs - Dataset paths this task reads from
  * @property output - Dataset path this task writes to
  * @property dependsOn - Names of tasks that must complete before this one
+ * @property peakBytes - The highest peak resident memory, in bytes, a runner
+ *   of the execution the status comes from reached: the one the output came
+ *   from, or the failure; `none` when it recorded none, or while it runs
  */
 export const TaskStatusInfoType = StructType({
   name: StringType,
@@ -399,6 +573,7 @@ export const TaskStatusInfoType = StructType({
   inputs: ArrayType(StringType),
   output: StringType,
   dependsOn: ArrayType(StringType),
+  peakBytes: OptionType(IntegerType),
 });
 
 /**
@@ -451,31 +626,34 @@ export const WorkspaceStatusResultType = StructType({
  *
  * @property name - Task name
  * @property hash - Task definition hash
- * @property kind - Task kind: "ui" (e3-ui `ui()`), other future kinds; none for plain tasks / old packages
+ * @property role - What the task's output is for: data, or a ui with what it
+ *   binds
  */
 export const TaskListItemType = StructType({
   name: StringType,
   hash: StringType,
-  kind: OptionType(StringType),
+  role: TaskRoleType,
 });
 
 /**
- * Detailed task information.
+ * Detailed task information: the task object's fields.
  *
  * @property name - Task name
  * @property hash - Task definition hash
- * @property commandIr - East IR for the task's command
- * @property inputs - Tree paths for task inputs
- * @property output - Tree path for task output
+ * @property body - What the task runs: an East program, or a command
+ * @property runner - The runtime it runs on
+ * @property inputs - The datasets it reads, each with its partition
+ * @property output - Where its output goes, and how it is made
+ * @property role - What its output is for: data, or a ui with what it binds
  */
 export const TaskDetailsType = StructType({
   name: StringType,
   hash: StringType,
-  commandIr: StringType,
-  inputs: ArrayType(TreePathType),
-  output: TreePathType,
-  kind: OptionType(StringType),
-  metadata: OptionType(BlobType),
+  body: TaskBodyType,
+  runner: RunnerType,
+  inputs: ArrayType(TaskInputType),
+  output: TaskOutputType,
+  role: TaskRoleType,
 });
 
 // =============================================================================
@@ -483,14 +661,13 @@ export const TaskDetailsType = StructType({
 // =============================================================================
 
 /**
- * Request to start dataflow execution.
+ * Request to start dataflow execution. The run takes the server's budget of
+ * cores and memory, which it shares with everything else the server runs.
  *
- * @property concurrency - Maximum parallel tasks (default: 4)
  * @property force - Force re-execution of all tasks
  * @property filter - Filter to specific task names (glob pattern)
  */
 export const DataflowRequestType = StructType({
-  concurrency: OptionType(IntegerType),
   force: BooleanType,
   filter: OptionType(StringType),
 });
@@ -561,11 +738,15 @@ export const DataflowResultType = StructType({
  * Dataflow event types for API polling.
  *
  * - `start`: Task started executing
- * - `complete`: Task executed and succeeded
+ * - `complete`: Task executed and succeeded, with the highest peak memory its
+ *   runners reached when they reported one
  * - `cached`: Task result retrieved from cache (no execution)
  * - `failed`: Task exited with non-zero code
  * - `error`: Internal error during task execution
  * - `input_unavailable`: Task couldn't run because inputs not available
+ * - `requeued`: A unit of a split task was stopped — by the budget's guard, or
+ *   its cgroup's cap — and runs again once the memory it reserves fits: the
+ *   unit, why, the most it was measured using and what it reserves, in bytes
  */
 export const DataflowEventType = VariantType({
   start: StructType({
@@ -576,6 +757,7 @@ export const DataflowEventType = VariantType({
     task: StringType,
     timestamp: StringType,
     duration: FloatType,
+    peakBytes: OptionType(IntegerType),
   }),
   cached: StructType({
     task: StringType,
@@ -597,6 +779,14 @@ export const DataflowEventType = VariantType({
     timestamp: StringType,
     reason: StringType,
   }),
+  requeued: StructType({
+    task: StringType,
+    timestamp: StringType,
+    unit: StageUnitType,
+    reason: RequeueReasonType,
+    peak: IntegerType,
+    reserves: IntegerType,
+  }),
 });
 
 /**
@@ -628,6 +818,55 @@ export const DataflowExecutionSummaryType = StructType({
   duration: FloatType,
 });
 
+/**
+ * A server's budget of cores and memory, which every runner it spawns takes
+ * from, and what its runners hold of it now.
+ *
+ * @property cores - Runner processes at once
+ * @property memory - Bytes of memory the runners may hold between them
+ * @property coresInUse - Runner processes holding the budget now
+ * @property memoryInUse - Bytes the runners hold now, each at the larger of
+ *   its reservation and what it was last measured using
+ */
+export const DataflowBudgetType = StructType({
+  cores: IntegerType,
+  memory: IntegerType,
+  coresInUse: IntegerType,
+  memoryInUse: IntegerType,
+});
+
+/**
+ * A task, or a unit of a split task, waiting for room in the server's budget.
+ *
+ * @property task - The task
+ * @property unit - The unit, for a split task's; `none` for a task run as one
+ * @property needs - The memory, in bytes, it waits to reserve; 0 when it
+ *   waits for a core alone
+ * @property since - ISO timestamp when it began waiting
+ */
+export const UnitWaitType = StructType({
+  task: StringType,
+  unit: OptionType(StageUnitType),
+  needs: IntegerType,
+  since: StringType,
+});
+
+/**
+ * A split task's progress through the stage it is in.
+ *
+ * @property task - The task
+ * @property merge - The merge level, from 1, and the levels the merges take;
+ *   `none` while its pieces run
+ * @property done - The stage's units that have finished
+ * @property units - The stage's units
+ */
+export const SplitProgressType = StructType({
+  task: StringType,
+  merge: OptionType(StructType({ level: IntegerType, levels: IntegerType })),
+  done: IntegerType,
+  units: IntegerType,
+});
+
 /**
  * Dataflow execution state returned by API polling.
  *
@@ -643,6 +882,12 @@ export const DataflowExecutionSummaryType = StructType({
  * @property summary - Execution summary (available when complete)
  * @property events - Task events (may be paginated via offset/limit)
  * @property totalEvents - Total number of events (for pagination)
+ * @property budget - The server's budget now, where it has one: a server whose
+ *   runners hold none, as a remote backend's, serves `none`
+ * @property waiting - The tasks and units of the run waiting for room, while it
+ *   runs; nothing stores them
+ * @property splits - Each split task's progress, while the run runs; nothing
+ *   stores it
  */
 export const ApiDataflowExecutionStateType = StructType({
   status: ApiExecutionStatusType,
@@ -651,6 +896,9 @@ export const ApiDataflowExecutionStateType = StructType({
   summary: OptionType(DataflowExecutionSummaryType),
   events: ArrayType(DataflowEventType),
   totalEvents: IntegerType,
+  budget: OptionType(DataflowBudgetType),
+  waiting: ArrayType(UnitWaitType),
+  splits: ArrayType(SplitProgressType),
 });
 
 // =============================================================================
@@ -658,13 +906,17 @@ export const ApiDataflowExecutionStateType = StructType({
 // =============================================================================
 
 /**
- * Execution status for history listing.
+ * Execution status for history listing: `cancelled` when e3 stopped the
+ * execution because its run was aborted, `interrupted` when the orchestrator
+ * that owned it exited before it finished.
  */
 export const ExecutionHistoryStatusType = VariantType({
   running: NullType,
   success: NullType,
   failed: NullType,
   error: NullType,
+  cancelled: NullType,
+  interrupted: NullType,
 });
 
 /**
@@ -677,6 +929,8 @@ export const ExecutionHistoryStatusType = VariantType({
  * @property completedAt - ISO timestamp when execution finished (if done)
  * @property duration - Execution duration in milliseconds (if done)
  * @property exitCode - Process exit code (if failed)
+ * @property peakBytes - The highest peak resident memory, in bytes, a runner
+ *   of the execution reached, when it succeeded or failed and one reported it
  */
 export const ExecutionListItemType = StructType({
   inputsHash: StringType,
@@ -686,6 +940,7 @@ export const ExecutionListItemType = StructType({
   completedAt: OptionType(StringType),
   duration: OptionType(IntegerType),
   exitCode: OptionType(IntegerType),
+  peakBytes: OptionType(IntegerType),
 });
 
 // =============================================================================
@@ -703,7 +958,9 @@ export const TreeKindType = VariantType({ struct: NullType });
  * A list entry -- either a dataset leaf or a tree branch.
  *
  * Used by the `?list=true&status=true` endpoints to return both
- * tree structure entries and dataset leaves in a single flat list.
+ * tree structure entries and dataset leaves in a single flat list. A dataset's
+ * `size` is what its value weighs in the store, as its status reports it: for
+ * a collection, its segments and its manifest.
  */
 export const ListEntryType = VariantType({
   dataset: StructType({
@@ -729,7 +986,8 @@ export const ListEntryType = VariantType({
  * @property type - East type of the dataset
  * @property refType - Ref type: "unassigned", "null", or "value"
  * @property hash - Object hash (None if unassigned/null)
- * @property size - Size in bytes (None if unassigned)
+ * @property size - Bytes the value weighs in the store: for a collection, its
+ *   segments and its manifest (None if unassigned)
  */
 export const DatasetStatusDetailType = StructType({
   path: StringType,
@@ -737,10 +995,9 @@ export const DatasetStatusDetailType = StructType({
   refType: StringType,
   hash: OptionType(StringType),
   size: OptionType(IntegerType),
-  /** Segment and element counts of a stored collection, read from the blob's
-   *  trailing index — so a re-pointed input is inspectable without decoding
-   *  it. `none` for a non-collection or an unset dataset. Appended LAST, per
-   *  the positional struct rule. */
+  /** Segment and element counts of a stored collection, read from its
+   *  manifest — so a re-pointed input is inspectable without decoding it.
+   *  `none` for a non-collection or an unset dataset. */
   segments: OptionType(IntegerType),
   rows: OptionType(IntegerType),
 });
@@ -834,6 +1091,10 @@ export const OneShotRequestType = StructType({
 /**
  * A record mutation call. Positional args (after the implicit current state),
  * one beast2-encoded value per declared parameter.
+ *
+ * Of the limits, `timeoutMs` bounds each run of the mutation's program and
+ * `maxLogBytes` the stderr a failure returns. `maxResultBytes` does not apply:
+ * a mutation's output is stored as segments and never read whole.
  */
 export const MutationCallRequestType = StructType({
   args:   ArrayType(BlobType),
@@ -846,32 +1107,49 @@ export const MutationCallRequestType = StructType({
  *
  * - `committed`: the new commit + state hashes
  * - `invalid`: record/mutation lookup or arity error; nothing ran
- * - `failed`: the reducer process exited non-zero (incl. a reducer `$.error`; see stderr)
- * - `too_large`: the new state exceeded the result cap
- * - `timed_out`: the reducer exceeded its time budget
- * - `conflict`: the compare-and-swap lost the race `attempts` times
+ * - `failed`: the mutation's program failed (incl. a body's `$.error`; see stderr)
+ * - `timed_out`: the program exceeded its time budget
+ * - `conflict`: the compare-and-swap lost the race `attempts` times, or the
+ *   write disagreed with the state it landed on — then `detail` names the key,
+ *   and resubmitting the same write cannot help
  */
 export const MutationResultType = StructType({
   outcome: VariantType({
     committed: StructType({ commitHash: StringType, stateHash: StringType }),
     invalid:   StructType({ message: StringType }),
     failed:    StructType({ exitCode: IntegerType, stderr: StringType }),
-    too_large: StructType({ bytes: IntegerType, limit: IntegerType, stderr: StringType }),
     timed_out: StructType({ ms: IntegerType, stderr: StringType }),
-    conflict:  StructType({ attempts: IntegerType }),
+    conflict:  StructType({ attempts: IntegerType, detail: OptionType(StringType) }),
   }),
 });
 
 /**
  * A record's callable surface, returned by `describe` so dynamic callers can
- * encode mutation arguments. The mutation `argTypes` are the EXTRA parameters
- * after the implicit current state.
+ * encode mutation arguments and read through its indexes. The mutation
+ * `argTypes` are the EXTRA parameters after the implicit current state.
  */
 export const RecordSignatureType = StructType({
   name: StringType,
   mutations: ArrayType(StructType({
     name:     StringType,
     argTypes: ArrayType(EastTypeType),
+    /** The write form — `reduce`, `edit` or `patch` — which says what the
+     *  arguments MEAN: a `patch` mutation's one argument is a
+     *  `PatchType(State)`, not a value of the record's own type. */
+    form:     StringType,
+  })),
+  /** The indexes the record declares. A page read through one is decoded by
+   *  `indexWindowType(K, keyType, valueType, V)` over the record's
+   *  `Dict<K, V>`, and a key search through one takes a `keyType` key. */
+  indexes: ArrayType(StructType({
+    name:      StringType,
+    /** The index key's type. */
+    keyType:   EastTypeType,
+    /** The covering projection's type: `Null` when the index projects
+     *  nothing, and a read joins the rows instead. */
+    valueType: EastTypeType,
+    /** Whether a row may hold several index keys. */
+    multi:     BooleanType,
   })),
 });
 
@@ -883,6 +1161,9 @@ export const RecordCommitInfoType = StructType({
   mutation: StringType,
   actor:    StringType,
   at:       DateTimeType,
+  /** The delta this commit applied, when it wrote one — so history shows WHAT
+   *  changed without diffing two states. */
+  delta:    OptionType(StringType),
 });
 
 /** A page of a record's commit history, newest first. */
@@ -907,6 +1188,16 @@ export type PackageDetails = ValueTypeOf<typeof PackageDetailsType>;
 export type WorkspaceInfo = ValueTypeOf<typeof WorkspaceInfoType>;
 export type WorkspaceCreateRequest = ValueTypeOf<typeof WorkspaceCreateRequestType>;
 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'];
+export type RecordPlan = ValueTypeOf<typeof RecordPlanType>;
+export type RecordIndexPlan = ValueTypeOf<typeof RecordIndexPlanType>;
+export type RecordDeployStep = ValueTypeOf<typeof RecordDeployStepType>;
+export type RecordDeployState = ValueTypeOf<typeof RecordDeployStateType>;
+export type DeployProgress = ValueTypeOf<typeof DeployProgressType>;
+export type WorkspaceDeployResult = ValueTypeOf<typeof WorkspaceDeployResultType>;
+export type WorkspaceDeployProgress = ValueTypeOf<typeof WorkspaceDeployProgressType>;
+export type WorkspaceDeployStatus = ValueTypeOf<typeof WorkspaceDeployStatusType>;
 export type DatasetStatus = ValueTypeOf<typeof DatasetStatusType>;
 export type TaskStatus = ValueTypeOf<typeof TaskStatusType>;
 export type DatasetStatusInfo = ValueTypeOf<typeof DatasetStatusInfoType>;
@@ -922,6 +1213,9 @@ export type DataflowResult = ValueTypeOf<typeof DataflowResultType>;
 export type DataflowEvent = ValueTypeOf<typeof DataflowEventType>;
 export type ApiExecutionStatus = ValueTypeOf<typeof ApiExecutionStatusType>;
 export type DataflowExecutionSummary = ValueTypeOf<typeof DataflowExecutionSummaryType>;
+export type DataflowBudget = ValueTypeOf<typeof DataflowBudgetType>;
+export type UnitWait = ValueTypeOf<typeof UnitWaitType>;
+export type SplitProgress = ValueTypeOf<typeof SplitProgressType>;
 export type ApiDataflowExecutionState = ValueTypeOf<typeof ApiDataflowExecutionStateType>;
 export type ExecutionHistoryStatus = ValueTypeOf<typeof ExecutionHistoryStatusType>;
 export type ExecutionListItem = ValueTypeOf<typeof ExecutionListItemType>;

package/src/collection-manifest.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.
+ */
+
+/**
+ * The segment-object layout: a collection dataset is a **manifest naming
+ * standalone segment objects**, not one segmented blob.
+ *
+ * The type itself lives in `east`, beside the container it describes, because
+ * every runtime must read it: a task input staged as a manifest is one file
+ * naming sibling segment files, and a body that iterates it pays for the
+ * segments it touches rather than for a splice of the whole value. This module
+ * re-exports it for the e3 packages and adds what only a store cares about.
+ *
+ * Three properties are why records at millions of entries are affordable, and
+ * every one of them is about successive states SHARING storage rather than
+ * about indexing, which the trailing index already gave:
+ *
+ * - **A one-row edit costs one segment.** The new state names the same objects
+ *   as the old one bar the segment that changed, so a commit's new storage is
+ *   the touched segments plus a manifest — not the whole value.
+ * - **Two states diff in O(changed segments)**, by comparing entry hashes. No
+ *   value is decoded to find out what moved, which is what index maintenance
+ *   and the mutation delta are built on.
+ * - **A segment can be checked against its own hash**, which a ranged read of
+ *   one blob can never offer: no digest exists for a byte range. No reader
+ *   checks it — a segment is trusted as stored, like any other object.
+ *
+ * The manifest is the envelope the garbage collector recognizes, which is why
+ * its `kind` is a stored field rather than something inferred: an object whose
+ * entries name other objects MUST be traversable by shape, or the first sweep
+ * deletes a record's segments.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  COLLECTION_MANIFEST_KIND,
+  CollectionManifestType,
+  CollectionManifestEntryType,
+  type CollectionManifest,
+  type CollectionManifestEntry,
+  type Beast2ManifestSource,
+  isCollectionManifestType,
+  isCollectionManifest,
+  isBeast2ManifestSource,
+  encodeCollectionManifest,
+  decodeCollectionManifest,
+  readBeast2Manifest,
+  manifestElementCount,
+  manifestByteSize,
+} from '@elaraai/east';