@elaraai/e3-cloud-types 1.0.94 → 1.1.0

package/dist/src/files-types.js

@@ -4,28 +4,47 @@
  */
 /**
  * Files: a solution's inputs that come from files in a bucket, as East
- * values.
+ * values; and a record's seed, and a record's mutation fed, from
+ * files.
  *
  * A solution declares, with `@elaraai/e3-cloud-files`, which of its inputs a
  * source's files fill: one file, the newest under a prefix, every file under
- * a prefix, or a listing of them ({@link FilesShapeType}). The declarations
- * are a {@link FilesManifestType}, deployed beside the package and checked
+ * a prefix, or a listing of them ({@link FilesShapeType}); a `file` or
+ * `latest` shape may name a **type**, and the file is then taken in as the
+ * beast2 value it holds rather than as a `Blob`. What a mapping fills is its
+ * **target** ({@link FilesTargetType}): an input, a record (the file is the
+ * record's state: its genesis, then a seed again), or a record's mutation
+ * (each new file is the mutation's one argument). The declarations are a
+ * {@link FilesManifestType}, deployed beside the package and checked
  * against it. Each workspace binds a source to where its files are
  * ({@link FilesBindingType}); a sync brings in what changed and answers a
- * {@link FilesSyncReportType}. The checks answer {@link FilesProblemType}s,
- * each rendered as a line by {@link filesProblemText}.
+ * {@link FilesSyncReportType}; a push ({@link FilesPushRequestType}) puts
+ * files from disk into a source and syncs their targets. The checks answer
+ * {@link FilesProblemType}s, each rendered as a line by
+ * {@link filesProblemText}.
  *
- * A file arrives as it is, a `Blob`: nothing here parses it.
+ * A file with no type arrives as it is, a `Blob`: nothing here parses it. A
+ * typed file is beast2, whose root type must be the mapping's.
+ *
+ * @remarks
+ * WIRE COMPAT: the manifest, the reports, the ledgers and a sync's job are
+ * stored (the platform's `FILES/`, `FILESJOB/` and `RELEASE/` items and its
+ * `files-sync/` objects; a local repository's `.e3-cloud/files/<ws>.json`).
+ * Their first version (a mapping by `input`, a refusal's reason a string) is
+ * read through
+ * `@elaraai/e3-cloud-files/compat`, which keeps the first version's types
+ * and lifts a value into these; every store writes these. The API's own
+ * request and response types ship with the client and CLI.
  */
-import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, EastTypeType, IntegerType, NullType, OptionType, StringType, StructType, VariantType, printTypeValueSummary, } from '@elaraai/east';
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, EastTypeType, IntegerType, NullType, OptionType, StringType, StructType, VariantType, equalFor, printTypeValueSummary, variant, } from '@elaraai/east';
 /**
  * Room a file's value leaves in its frame or segment for what beast2 adds:
  * the lengths before the bytes and, in a folder, the file's path.
  */
 const FILES_ENCODING_ROOM_BYTES = 64 * 1024;
 /**
- * The largest file `file` and `latest` take: beast2's largest frame, 1 GiB,
- * less the room its encoding takes (1 GiB less 64 KiB).
+ * The largest file `file` and `latest` take as a `Blob`: beast2's largest
+ * frame, 1 GiB, less the room its encoding takes (1 GiB less 64 KiB).
  */
 export const FILES_FILE_MAX_BYTES = 1024 * 1024 * 1024 - FILES_ENCODING_ROOM_BYTES;
 /**
@@ -33,6 +52,22 @@ export const FILES_FILE_MAX_BYTES = 1024 * 1024 * 1024 - FILES_ENCODING_ROOM_BYT
  * the room its path and lengths take (64 MiB less 64 KiB).
  */
 export const FILES_FOLDER_ENTRY_MAX_BYTES = 64 * 1024 * 1024 - FILES_ENCODING_ROOM_BYTES;
+/**
+ * The largest typed file whose value is no collection, and the largest file
+ * a mutation is fed: beast2's largest frame, 1 GiB, which a sandbox holds
+ * whole. A typed collection has no limit but its segments'.
+ */
+export const FILES_TYPED_VALUE_MAX_BYTES = 1024 * 1024 * 1024;
+/**
+ * The largest segment of a typed collection: beast2's, 64 MiB. A file
+ * written with a larger one is refused, naming the fix (write it again
+ * with a current writer).
+ */
+export const FILES_SEGMENT_MAX_BYTES = 64 * 1024 * 1024;
+/** The most files one push plans. */
+export const FILES_PUSH_MAX_FILES = 1000;
+/** The part a push's multipart upload is cut in, and the most one PUT sends: 64 MiB. */
+export const FILES_PUSH_PART_BYTES = 64 * 1024 * 1024;
 /** A file's row in a `listing` input. */
 export const FilesListingRowType = StructType({
     /** Its size in bytes */
@@ -42,7 +77,7 @@ export const FilesListingRowType = StructType({
     /** Its ETag: changes whenever its bytes do */
     etag: StringType,
 });
-/** The input type of a `file` or `latest` mapping: the file's bytes. */
+/** The input type of a `file` or `latest` mapping with no type: the file's bytes. */
 export const FilesFileType = BlobType;
 /** The input type of a `folder` mapping: each file's path, relative to the prefix, to its bytes. */
 export const FilesFolderType = DictType(StringType, BlobType);
@@ -52,9 +87,10 @@ export const FilesListingType = DictType(StringType, FilesListingRowType);
  * What a mapping selects from its source, relative to where the workspace
  * binds the source.
  *
- * - `file`: one key, as a `Blob`.
+ * - `file`: one key. As a `Blob`, or, with `type`, as the beast2 value of
+ *   that type the file holds.
  * - `latest`: the greatest key under a prefix that matches `include`, as a
- *   `Blob`.
+ *   `Blob` or, with `type`, as the value it holds.
  * - `folder`: every key under a prefix that matches `include`, as a
  *   `Dict<String, Blob>` keyed by its path relative to the prefix.
  * - `listing`: the same keys' sizes, times and ETags, without their bytes.
@@ -63,22 +99,102 @@ export const FilesListingType = DictType(StringType, FilesListingRowType);
  * within one segment of the path, `**` across segments, `?` one character,
  * `[abc]`, `[a-z]` and `[!abc]` one character of a set, and `{csv,json}` any
  * of its alternatives, each a glob itself.
+ *
+ * A record's or a mutation's mapping selects one file (`file` or `latest`)
+ * and names its type: the record's state type, or the mutation's one
+ * argument's.
  */
 export const FilesShapeType = VariantType({
-    file: StructType({ key: StringType }),
-    latest: StructType({ prefix: StringType, include: OptionType(StringType) }),
+    file: StructType({ key: StringType, type: OptionType(EastTypeType) }),
+    latest: StructType({ prefix: StringType, include: OptionType(StringType), type: OptionType(EastTypeType) }),
     folder: StructType({ prefix: StringType, include: OptionType(StringType) }),
     listing: StructType({ prefix: StringType, include: OptionType(StringType) }),
 });
-/** One input a source's files fill. */
-export const FilesMappingType = StructType({
-    /** The input's name: the dataset `.inputs.<input>` */
+/**
+ * What a mapping fills.
+ *
+ * - `input`: the dataset `.inputs.<name>`.
+ * - `record`: the record `.records.<name>`, seeded: its file is its first
+ *   state (its genesis), and a changed file its state again while nothing
+ *   has mutated it since.
+ * - `mutation`: one of a record's mutations, fed: each new file is the
+ *   mutation's one argument, applied once.
+ */
+export const FilesTargetType = VariantType({
     input: StringType,
+    record: StringType,
+    mutation: StructType({ record: StringType, mutation: StringType }),
+});
+/** Whether two targets are the same. */
+export const sameFilesTarget = equalFor(FilesTargetType);
+/**
+ * A target as one text: `orders`, `record:customers`,
+ * `mutation:prices.load_prices`. What the CLI takes (`--as`, `--target`) and
+ * prints, and what {@link parseFilesTarget} reads back.
+ *
+ * @param target - The target
+ * @returns Its text
+ */
+export function filesTargetText(target) {
+    switch (target.type) {
+        case 'input': return target.value;
+        case 'record': return `record:${target.value}`;
+        case 'mutation': return `mutation:${target.value.record}.${target.value.mutation}`;
+    }
+}
+/**
+ * A target, from its text ({@link filesTargetText}): a bare name is an
+ * input's. A mutation's text is split at its last dot (e3 lets a name hold
+ * one): a record's name may hold a dot, and a mutation whose name holds one
+ * cannot be named in this form, only as a structured target (a sync
+ * request's `targets`).
+ *
+ * @param text - `name`, `input:name`, `record:name` or `mutation:record.name`
+ * @returns The target, or null for text of another form
+ */
+export function parseFilesTarget(text) {
+    const colon = text.indexOf(':');
+    if (colon < 0)
+        return text === '' ? null : variant('input', text);
+    const kind = text.slice(0, colon);
+    const rest = text.slice(colon + 1);
+    if (rest === '')
+        return null;
+    switch (kind) {
+        case 'input': return variant('input', rest);
+        case 'record': return variant('record', rest);
+        case 'mutation': {
+            const dot = rest.lastIndexOf('.');
+            if (dot <= 0 || dot === rest.length - 1)
+                return null;
+            return variant('mutation', { record: rest.slice(0, dot), mutation: rest.slice(dot + 1) });
+        }
+        default: return null;
+    }
+}
+/**
+ * A target in words: `input orders`, `record customers`,
+ * `mutation load_prices of customers`.
+ *
+ * @param target - The target
+ * @returns The words
+ */
+export function filesTargetWords(target) {
+    switch (target.type) {
+        case 'input': return `input ${target.value}`;
+        case 'record': return `record ${target.value}`;
+        case 'mutation': return `mutation ${target.value.mutation} of ${target.value.record}`;
+    }
+}
+/** One target a source's files fill. */
+export const FilesMappingType = StructType({
+    /** What the files fill */
+    target: FilesTargetType,
     /** The source's name */
     source: StringType,
     shape: FilesShapeType,
 });
-/** A solution's declarations: its sources, and the inputs they fill. */
+/** A solution's declarations: its sources, and the targets they fill. */
 export const FilesManifestType = StructType({
     /** The sources' names, in the order they were declared */
     sources: ArrayType(StringType),
@@ -100,14 +216,52 @@ export const FilesBindingType = StructType({
     profile: OptionType(StringType),
     latest: OptionType(IntegerType),
 });
+/**
+ * Why a sync did not take a file.
+ *
+ * - `too_large`: over its shape's limit, in bytes.
+ * - `segment_too_large`: a typed collection written with a segment over
+ *   beast2's 64 MiB; written again with a current writer, it is taken.
+ * - `unreadable`: the source would not give it (archived, changed since it
+ *   was listed, closed to the reader).
+ * - `not_beast2`: a typed mapping's file that is no beast2 container.
+ * - `type_mismatch`: a typed mapping's file holding a value of another
+ *   type than the mapping's.
+ * - `mutation`: a feed the mutation did not commit: its outcome
+ *   (`invalid`, `timed_out`, `failed`) and what it said; tried again once
+ *   the file changes.
+ * - `missing`: the file the mapping names is not there.
+ * - `other`: a reason stored before these were told apart.
+ */
+export const FilesRefusalReasonType = VariantType({
+    too_large: StructType({ size: IntegerType, limit: IntegerType }),
+    segment_too_large: StructType({ bytes: IntegerType, limit: IntegerType }),
+    unreadable: StringType,
+    not_beast2: StringType,
+    type_mismatch: StructType({ expected: EastTypeType, actual: EastTypeType }),
+    mutation: StructType({ outcome: StringType, message: StringType }),
+    missing: StringType,
+    other: StringType,
+});
 /** A file a sync did not take, and why. */
 export const FilesRefusalType = StructType({
     key: StringType,
-    reason: StringType,
+    reason: FilesRefusalReasonType,
+});
+/** A typed file a sync took in: the value it holds. */
+export const FilesTakenType = StructType({
+    /** The file's key */
+    key: StringType,
+    /** The value's type: the mapping's */
+    type: EastTypeType,
+    /** The collection's rows, where the store counts them */
+    rows: OptionType(IntegerType),
+    /** `carried` whole, or `split` into pieces by intake units */
+    how: VariantType({ carried: NullType, split: NullType }),
 });
 /** What one sync did for one mapping. */
 export const FilesMappingReportType = StructType({
-    input: StringType,
+    target: FilesTargetType,
     /** Files new since the last sync */
     added: IntegerType,
     /** Files whose bytes changed */
@@ -116,12 +270,20 @@ export const FilesMappingReportType = StructType({
     removed: IntegerType,
     /** Files as they were */
     unchanged: IntegerType,
-    /** Files not taken: too large, or unreadable */
+    /** Files not taken, and why */
     refused: ArrayType(FilesRefusalType),
     /** The bytes taken in */
     bytes: IntegerType,
-    /** Whether the input's value changed */
+    /** Whether the target's value changed */
     updated: BooleanType,
+    /** The typed value taken in, for a typed mapping that took its file */
+    taken: OptionType(FilesTakenType),
+    /** The commit a seed or a feed made: `$init`, `$seed`, or the mutation's */
+    commit: OptionType(StringType),
+    /** Why a seed was not applied: the record has been mutated since its seed */
+    kept: OptionType(StringType),
+    /** Why a feed waits: its record has no state yet; tried again by the next sync */
+    waiting: OptionType(StringType),
 });
 /** What one sync did. */
 export const FilesSyncReportType = StructType({
@@ -131,25 +293,66 @@ export const FilesSyncReportType = StructType({
     dryRun: BooleanType,
     mappings: ArrayType(FilesMappingReportType),
 });
+/** What a target took of one file. */
+export const FilesLedgerEntryType = StructType({
+    etag: StringType,
+    size: IntegerType,
+    /** The file's SHA-256, where the sync hashed it (a typed file, a push) */
+    sha256: OptionType(StringType),
+    /** When the file was last written, as its listing said */
+    modified: OptionType(DateTimeType),
+});
 /**
- * What an input took last: each file's ETag and size by its key, the value the
- * sync wrote (its hash), and what it was taken under: the mapping's shape and
- * where its source was bound, as one text. A sync trusts it only while the
- * input still holds that value and the mapping and binding are as they were,
- * so a ledger a sync wrote under other declarations, or from elsewhere, is
+ * What a target took last: each file's ETag, size and hash by its key, the
+ * value the sync wrote (its hash) or the commit it made, and what it was
+ * taken under: the mapping's shape and where its source was bound, as one
+ * text. A sync trusts it only while the target still holds that value (or
+ * that commit is its head) and the mapping and binding are as they were, so
+ * a ledger a sync wrote under other declarations, or from elsewhere, is
  * never read against these. The CLI keeps it in a local repository's state
  * file, the platform in its store.
  */
 export const FilesLedgerType = StructType({
-    entries: DictType(StringType, StructType({ etag: StringType, size: IntegerType })),
+    entries: DictType(StringType, FilesLedgerEntryType),
+    /** The value the sync wrote, its hash: an input's */
     value: OptionType(StringType),
     under: OptionType(StringType),
+    /** The commit the sync made: a record's seed, a mutation's last feed */
+    commit: OptionType(StringType),
+    /** The SHA-256 of a feed the mutation refused: not tried again until the file changes */
+    tried: OptionType(StringType),
+    /**
+     * A typed intake under way across rounds: the file (its key and ETag, so
+     * another file is never resumed as it), its SHA-256 once its bytes are
+     * placed in the store (the delivery its intake resumes), else where its
+     * staging stood (the platform's own progress, as text)
+     */
+    taking: OptionType(StructType({ key: StringType, etag: StringType, sha256: OptionType(StringType), staging: OptionType(StringType) })),
+});
+/** What a mapping holds, from its ledger: the file it took last. */
+export const FilesHeldType = StructType({
+    key: StringType,
+    size: IntegerType,
+    modified: OptionType(DateTimeType),
+    sha256: OptionType(StringType),
+    /** The commit it made, for a record or a mutation */
+    commit: OptionType(StringType),
 });
-/** A workspace's Files: its declarations, its bindings and its last sync. */
+/** A mapping's state: what it holds, and whether its record is pending. */
+export const FilesMappingStatusType = StructType({
+    target: FilesTargetType,
+    /** The file it holds; none before its first sync, or for a folder or listing */
+    holds: OptionType(FilesHeldType),
+    /** A record mapping whose record has no state yet: seeded by the next sync */
+    pending: BooleanType,
+});
+/** A workspace's Files: its declarations, its bindings, its last sync, and what each mapping holds. */
 export const FilesStatusType = StructType({
     manifest: OptionType(FilesManifestType),
     bindings: ArrayType(FilesBindingType),
     lastSync: OptionType(FilesSyncReportType),
+    /** Each declared mapping's state, in the declarations' order; none without declarations */
+    mappings: ArrayType(FilesMappingStatusType),
 });
 /**
  * A bucket a deployment lets a repository's bindings point into, and the
@@ -168,7 +371,7 @@ export const FilesPackageType = StructType({
 });
 /** A deployed workspace's Files, as `GET …/files` answers them. */
 export const FilesWorkspaceType = StructType({
-    /** Its declarations, its bindings and its last sync */
+    /** Its declarations, its bindings, its last sync and what each mapping holds */
     status: FilesStatusType,
     /** Where the repository's bindings may point */
     granted: ArrayType(FilesGrantType),
@@ -192,8 +395,10 @@ export const FilesDeployRequestType = StructType({
 export const FilesSyncRequestType = StructType({
     /** List what a sync would take, and take nothing */
     dryRun: BooleanType,
-    /** Only these inputs; every declared input when none */
-    inputs: OptionType(ArrayType(StringType)),
+    /** Only these targets; every declared target when none */
+    targets: OptionType(ArrayType(FilesTargetType)),
+    /** Records whose file is taken as their state again (`$seed`) whatever has mutated them since */
+    reset: ArrayType(StringType),
 });
 /** What a sync's request did: started a sync, its id; or found one under way, its id, and started nothing. */
 export const FilesSyncStartType = VariantType({
@@ -217,19 +422,104 @@ export const FilesSyncJobType = StructType({
     /** Who asked for it: their email, else their subject */
     by: StringType,
     dryRun: BooleanType,
-    inputs: OptionType(ArrayType(StringType)),
+    targets: OptionType(ArrayType(FilesTargetType)),
+    reset: ArrayType(StringType),
     state: FilesSyncStateType,
     startedAt: DateTimeType,
     finishedAt: OptionType(DateTimeType),
-    /** What it has taken, per input; whole once it has ended */
+    /** What it has taken, per target; whole once it has ended */
     report: OptionType(FilesSyncReportType),
 });
+/** A file a push offers: its name, where it came from, its size, its hash and its beast2 type. */
+export const FilesPushFileType = StructType({
+    /** Its name: a file's own, or its path relative to the directory it came from */
+    name: StringType,
+    /** The directory it came from, its own name, when a directory was pushed */
+    directory: OptionType(StringType),
+    size: IntegerType,
+    /** Its SHA-256, hex */
+    sha256: StringType,
+    /** The root type its beast2 header declares; none for a file that is no beast2 */
+    type: OptionType(EastTypeType),
+});
+/** A push's plan asked for (`POST …/files/push`): the files, and the target they are all for, if named. */
+export const FilesPushRequestType = StructType({
+    files: ArrayType(FilesPushFileType),
+    /** The target every file is for ({@link filesTargetText}; a bare name when unique across kinds); none to match each by its name */
+    as: OptionType(StringType),
+});
+/**
+ * How a planned file is put: one presigned PUT bound to its SHA-256; a
+ * multipart upload the platform created, a presigned URL per part,
+ * completed by `POST …/files/push/complete`; or `external`, a bucket the
+ * platform does not write, which the client puts with its own credentials.
+ */
+export const FilesPushUploadType = VariantType({
+    single: StructType({ url: StringType, headers: DictType(StringType, StringType) }),
+    multipart: StructType({
+        uploadId: StringType,
+        /** Each part's bytes but the last's */
+        partBytes: IntegerType,
+        parts: ArrayType(StructType({ number: IntegerType, url: StringType })),
+    }),
+    external: NullType,
+});
+/**
+ * Why a push does not put a file.
+ *
+ * - `no_mapping`: no mapping takes a file of its name.
+ * - `ambiguous`: several would; name one with `as`.
+ * - `unknown_target`: `as` names no mapping.
+ * - `shape_mismatch`: a directory for a mapping that takes one file, or a
+ *   file for one that takes a folder (`directory`: which was offered).
+ * - `not_included`: a file the mapping's `include` glob leaves out, which
+ *   no sync would take.
+ * - `not_latest`: a `latest` mapping whose source holds a greater key.
+ * - `type_mismatch`, `not_beast2`, `too_large`: as a sync refuses them.
+ */
+export const FilesPushRefusalType = VariantType({
+    no_mapping: NullType,
+    ambiguous: ArrayType(FilesTargetType),
+    unknown_target: StringType,
+    shape_mismatch: StructType({ target: FilesTargetType, directory: BooleanType }),
+    not_included: StructType({ target: FilesTargetType, include: StringType }),
+    not_latest: StructType({ target: FilesTargetType, greatest: StringType }),
+    type_mismatch: StructType({ target: FilesTargetType, expected: EastTypeType, actual: EastTypeType }),
+    not_beast2: StructType({ target: FilesTargetType, expected: EastTypeType }),
+    too_large: StructType({ target: FilesTargetType, size: IntegerType, limit: IntegerType }),
+});
+/** What a push does with one file: puts it at a key, finds it there already, or refuses it. */
+export const FilesPushOutcomeType = VariantType({
+    put: StructType({ target: FilesTargetType, source: StringType, key: StringType, upload: FilesPushUploadType }),
+    unchanged: StructType({ target: FilesTargetType, source: StringType, key: StringType }),
+    refused: FilesPushRefusalType,
+});
+/** A push's plan: each file's outcome, and the bindings the puts go to. */
+export const FilesPushPlanType = StructType({
+    /** The bindings of the sources any file is put to */
+    bindings: ArrayType(FilesBindingType),
+    files: ArrayType(StructType({ name: StringType, directory: OptionType(StringType), outcome: FilesPushOutcomeType })),
+});
+/** The completion of a multipart upload a plan created (`POST …/files/push/complete`). */
+export const FilesPushCompleteRequestType = StructType({
+    key: StringType,
+    uploadId: StringType,
+    parts: ArrayType(StructType({ number: IntegerType, etag: StringType })),
+});
+/** A completed upload: the object's ETag. */
+export const FilesPushCompleteResponseType = StructType({ etag: StringType });
 /**
  * Why declarations do not fit a package, or a binding does not fit them.
  *
- * - Against the package: `input_missing`, `input_not_writable`, `input_type`.
- * - The declarations themselves: `duplicate_input` (two mappings fill one
- *   input), `invalid_name` (a name e3 refuses), `invalid_key` (a key or
+ * - Against the package: `input_missing`, `input_not_writable`,
+ *   `input_type`; `record_missing`, `record_type`; `mutation_missing`,
+ *   `mutation_arity` (a fed mutation takes exactly one argument),
+ *   `mutation_patch` (a `patch` mutation takes a patch, not a value),
+ *   `mutation_type`.
+ * - The declarations themselves: `duplicate_target` (two mappings fill one
+ *   target), `target_shape` (a record or mutation mapped to a folder or a
+ *   listing), `target_untyped` (a record or mutation mapping naming no
+ *   type), `invalid_name` (a name e3 refuses), `invalid_key` (a key or
  *   prefix that is empty or not relative), `invalid_include` (a glob that
  *   matches nothing well-formed).
  * - Bindings: `source_unknown` (bound, but not declared), `source_unbound`
@@ -237,7 +527,7 @@ export const FilesSyncJobType = StructType({
  *   `not_granted` (the deployment grants no source holding the URL), and
  *   `local_only` (`profile` or `latest`, on a deployed workspace).
  *
- * Types are compared exactly: `expected` is the shape's, `actual` the
+ * Types are compared exactly: `expected` is the mapping's, `actual` the
  * package's.
  *
  * @remarks
@@ -248,10 +538,18 @@ export const FilesProblemType = VariantType({
     input_missing: StructType({ input: StringType, expected: EastTypeType }),
     input_not_writable: StructType({ input: StringType }),
     input_type: StructType({ input: StringType, expected: EastTypeType, actual: EastTypeType }),
-    duplicate_input: StructType({ input: StringType }),
+    record_missing: StructType({ record: StringType, expected: EastTypeType }),
+    record_type: StructType({ record: StringType, expected: EastTypeType, actual: EastTypeType }),
+    mutation_missing: StructType({ record: StringType, mutation: StringType }),
+    mutation_arity: StructType({ record: StringType, mutation: StringType, arity: IntegerType }),
+    mutation_patch: StructType({ record: StringType, mutation: StringType }),
+    mutation_type: StructType({ record: StringType, mutation: StringType, expected: EastTypeType, actual: EastTypeType }),
+    duplicate_target: StructType({ target: FilesTargetType }),
+    target_shape: StructType({ target: FilesTargetType }),
+    target_untyped: StructType({ target: FilesTargetType }),
     invalid_name: StructType({ kind: StringType, name: StringType, reason: StringType }),
-    invalid_key: StructType({ input: StringType, key: StringType, reason: StringType }),
-    invalid_include: StructType({ input: StringType, include: StringType, reason: StringType }),
+    invalid_key: StructType({ target: FilesTargetType, key: StringType, reason: StringType }),
+    invalid_include: StructType({ target: FilesTargetType, include: StringType, reason: StringType }),
     source_unknown: StructType({ source: StringType }),
     source_unbound: StructType({ source: StringType }),
     invalid_url: StructType({ source: StringType, url: StringType, reason: StringType }),
@@ -259,28 +557,59 @@ export const FilesProblemType = VariantType({
     local_only: StructType({ source: StringType, option: StringType }),
 });
 /**
- * What a deploy of declarations did: kept them, with the inputs whose
+ * What a deploy of declarations did: kept them, with the targets whose
  * declaration changed, which the next sync takes again whole; checked them
  * and kept nothing (a dry run); or refused them, naming every problem. Each
  * names the package the workspace runs, which they were checked against.
  */
 export const FilesDeployResponseType = VariantType({
-    deployed: StructType({ package: FilesPackageType, retaken: ArrayType(StringType) }),
+    deployed: StructType({ package: FilesPackageType, retaken: ArrayType(FilesTargetType) }),
     checked: StructType({ package: FilesPackageType }),
     refused: StructType({ package: FilesPackageType, problems: ArrayType(FilesProblemType) }),
 });
 /**
- * What a bind did: kept the binding, with the inputs the next sync takes
+ * What a bind did: kept the binding, with the targets the next sync takes
  * again whole when it moved; or refused it, naming every problem.
  */
 export const FilesBindResponseType = VariantType({
-    bound: StructType({ retaken: ArrayType(StringType) }),
+    bound: StructType({ retaken: ArrayType(FilesTargetType) }),
     refused: ArrayType(FilesProblemType),
 });
-/** A type, briefly, as the problems print it. */
-function typeWords(type) {
+/**
+ * A type, briefly, as the problems and refusals print it.
+ *
+ * @param type - The type
+ * @returns Its summary, a few levels deep
+ */
+export function filesTypeWords(type) {
     return printTypeValueSummary(type, 3, 4);
 }
+/**
+ * A refusal's reason as words that follow the file's key.
+ *
+ * @param reason - The reason
+ * @returns The words
+ */
+export function filesRefusalText(reason) {
+    switch (reason.type) {
+        case 'too_large':
+            return `is ${reason.value.size} bytes, over the ${reason.value.limit} its mapping takes`;
+        case 'segment_too_large':
+            return `holds a segment of ${reason.value.bytes} bytes, over beast2's ${reason.value.limit}: write it again with a current writer`;
+        case 'unreadable':
+            return reason.value;
+        case 'not_beast2':
+            return `is not a beast2 file (${reason.value})`;
+        case 'type_mismatch':
+            return `holds ${filesTypeWords(reason.value.actual)}; its mapping declares ${filesTypeWords(reason.value.expected)}`;
+        case 'mutation':
+            return `was not applied: the mutation answered ${reason.value.outcome}${reason.value.message === '' ? '' : ` (${reason.value.message})`}`;
+        case 'missing':
+            return reason.value;
+        case 'other':
+            return reason.value;
+    }
+}
 /**
  * A problem as one line, which the CLI prints and an error's message carries.
  *
@@ -290,19 +619,35 @@ function typeWords(type) {
 export function filesProblemText(problem) {
     switch (problem.type) {
         case 'input_missing':
-            return `input ${problem.value.input}: the package has no such input (a ${typeWords(problem.value.expected)} is declared)`;
+            return `input ${problem.value.input}: the package has no such input (a ${filesTypeWords(problem.value.expected)} is declared)`;
         case 'input_not_writable':
             return `input ${problem.value.input}: it isn't an input the package lets anything write, so no file can fill it`;
         case 'input_type':
-            return `input ${problem.value.input}: the package declares ${typeWords(problem.value.actual)}, but its files fill a ${typeWords(problem.value.expected)}`;
-        case 'duplicate_input':
-            return `input ${problem.value.input}: more than one mapping fills it`;
+            return `input ${problem.value.input}: the package declares ${filesTypeWords(problem.value.actual)}, but its files fill a ${filesTypeWords(problem.value.expected)}`;
+        case 'record_missing':
+            return `record ${problem.value.record}: the package has no such record (a ${filesTypeWords(problem.value.expected)} is declared)`;
+        case 'record_type':
+            return `record ${problem.value.record}: the package declares its state ${filesTypeWords(problem.value.actual)}, but its file holds a ${filesTypeWords(problem.value.expected)}`;
+        case 'mutation_missing':
+            return `mutation ${problem.value.mutation} of ${problem.value.record}: the package has no such mutation on the record`;
+        case 'mutation_arity':
+            return `mutation ${problem.value.mutation} of ${problem.value.record}: it takes ${problem.value.arity} arguments, and a fed mutation takes exactly one`;
+        case 'mutation_patch':
+            return `mutation ${problem.value.mutation} of ${problem.value.record}: a patch mutation takes a patch, not a value, so no file can feed it`;
+        case 'mutation_type':
+            return `mutation ${problem.value.mutation} of ${problem.value.record}: its argument is ${filesTypeWords(problem.value.actual)}, but its file holds a ${filesTypeWords(problem.value.expected)}`;
+        case 'duplicate_target':
+            return `${filesTargetWords(problem.value.target)}: more than one mapping fills it`;
+        case 'target_shape':
+            return `${filesTargetWords(problem.value.target)}: a record or a mutation takes one file (file or latest), not a folder or a listing`;
+        case 'target_untyped':
+            return `${filesTargetWords(problem.value.target)}: its mapping names no type, and a record's or a mutation's file is a typed value`;
         case 'invalid_name':
             return `${problem.value.kind} ${problem.value.name}: ${problem.value.reason}`;
         case 'invalid_key':
-            return `input ${problem.value.input}: '${problem.value.key}' ${problem.value.reason}`;
+            return `${filesTargetWords(problem.value.target)}: '${problem.value.key}' ${problem.value.reason}`;
         case 'invalid_include':
-            return `input ${problem.value.input}: include '${problem.value.include}' ${problem.value.reason}`;
+            return `${filesTargetWords(problem.value.target)}: include '${problem.value.include}' ${problem.value.reason}`;
         case 'source_unknown':
             return `source ${problem.value.source}: the declarations have no such source`;
         case 'source_unbound':
@@ -315,4 +660,34 @@ export function filesProblemText(problem) {
             return `source ${problem.value.source}: ${problem.value.option} applies to a local repository only`;
     }
 }
+/**
+ * A push's refusal as words that follow the file's name.
+ *
+ * @param refusal - The refusal
+ * @returns The words
+ */
+export function filesPushRefusalText(refusal) {
+    switch (refusal.type) {
+        case 'no_mapping':
+            return 'no mapping takes a file of this name: name its target with --as';
+        case 'ambiguous':
+            return `several mappings would take it (${refusal.value.map(filesTargetText).join(', ')}): name one with --as`;
+        case 'unknown_target':
+            return `no mapping fills ${refusal.value}`;
+        case 'shape_mismatch':
+            return refusal.value.directory
+                ? `${filesTargetWords(refusal.value.target)} takes one file, not a directory`
+                : `${filesTargetWords(refusal.value.target)} takes a folder of files, not one file`;
+        case 'not_included':
+            return `${filesTargetWords(refusal.value.target)} takes only files matching '${refusal.value.include}', which this name does not`;
+        case 'not_latest':
+            return `${filesTargetWords(refusal.value.target)} takes the greatest key under its prefix, and ${refusal.value.greatest} is greater`;
+        case 'type_mismatch':
+            return `holds ${filesTypeWords(refusal.value.actual)}; ${filesTargetWords(refusal.value.target)} declares ${filesTypeWords(refusal.value.expected)}`;
+        case 'not_beast2':
+            return `is not a beast2 file, and ${filesTargetWords(refusal.value.target)} takes a ${filesTypeWords(refusal.value.expected)}`;
+        case 'too_large':
+            return `is ${refusal.value.size} bytes, over the ${refusal.value.limit} ${filesTargetWords(refusal.value.target)} takes`;
+    }
+}
 //# sourceMappingURL=files-types.js.map