@elaraai/e3-cloud-claude-plugin 1.1.0 → 1.1.1

package/.build/hooks/pre-read.js

@@ -1,4 +1,4 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -6,7 +6,7 @@ function hostText(text) {
   return isCodex ? text.replaceAll("mcp__plugin_east_east__", "").replaceAll("/east:", "$east-codex-plugin:").replaceAll("Claude Code", "Codex") : text;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
 async function readHookInput() {
   let input = "";
   for await (const chunk of process.stdin) {
@@ -34,10 +34,10 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -79,7 +79,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 function preReadReminder(event, options) {
   return options.isCorpusRead(event.tool_name ?? "", event.tool_input ?? {}) ? { decision: "context", text: options.readText } : null;
 }

package/.build/hooks/pre-write.js

@@ -1,10 +1,10 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 import { readFile as readFile2 } from "node:fs/promises";
 import { existsSync as existsSync2, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -12,7 +12,7 @@ function hostText(text) {
   return isCodex ? text.replaceAll("mcp__plugin_east_east__", "").replaceAll("/east:", "$east-codex-plugin:").replaceAll("Claude Code", "Codex") : text;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
 async function readHookInput() {
   let input = "";
   for await (const chunk of process.stdin) {
@@ -40,7 +40,7 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 import { readFile } from "node:fs/promises";
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
@@ -53,7 +53,7 @@ async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
   return tools.some((tool) => raw.includes(`"name":"${tool}"`) || raw.includes(`"name": "${tool}"`));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -95,7 +95,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 async function preWriteGate(event, options) {
   const cwd = event.cwd || process.cwd();
   const filePath = event.tool_input?.file_path;

package/.build/mcp/server.js

@@ -21556,7 +21556,7 @@ var StdioServerTransport = class {
   }
 };
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 import { readFile } from "node:fs/promises";
 
 // ../../node_modules/.pnpm/minisearch@7.2.0/node_modules/minisearch/dist/es/index.js
@@ -23369,7 +23369,7 @@ var objectToNumericMapAsync = async (object3) => {
 var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var SPACE_OR_PUNCTUATION = /[\n\r\p{Z}\p{P}]+/u;
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -23411,7 +23411,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 var MIN_SCORE = 5;
 async function loadIndexes(indexPaths) {
   const entries = [];
@@ -23537,7 +23537,7 @@ function getEntry(index, id) {
   return stored === void 0 ? null : stored;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
 var EAST_PACKAGES = ["east", "east-node-std", "east-node-io", "east-py-datascience", "east-ui", "e3-ui", "e3", "e3-ui-cli", "e3-create"];
 function isLoaded(index) {
   return typeof index.then === "function";
@@ -23610,7 +23610,7 @@ function registerExampleTools(server2, options) {
 import { fileURLToPath } from "node:url";
 var E3_CLOUD_INDEX_PATH = fileURLToPath(new URL("../../index.json", import.meta.url));
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 
 // ../e3-cloud-plugin/dist/lib/names.js

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e3-cloud",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "author": {
     "name": "Elara AI",

package/index.json

@@ -1,13 +1,13 @@
 {
   "version": 2,
   "stats": {
-    "totalEntries": 44,
+    "totalEntries": 47,
     "totalFiles": 2,
     "packages": {
       "e3-cloud-ui": 12,
       "e3-cloud-files": 14,
-      "e3-cloud-cli": 13,
-      "e3-cloud-client": 5
+      "e3-cloud-cli": 15,
+      "e3-cloud-client": 6
     }
   },
   "entries": [
@@ -758,7 +758,7 @@
       "package": "e3-cloud-cli",
       "file": "static",
       "suite": "e3-cloud",
-      "test": "Signing in to a deployment, and who you are there: the e3 CLI's sign-in (`e3 auth login`; there is no `e3 login`), whose credentials the e3-cloud CLI shares",
+      "test": "Signing in to a deployment, and who you are there: the e3 CLI's sign-in (`e3 auth login`; there is no `e3 login`), whose credentials the e3-cloud CLI shares; whoami names the e3 cloud release and e3 the deployment runs beside this CLI's",
       "keywords": [
         "login",
         "sign in",
@@ -771,7 +771,36 @@
         "e3-cloud"
       ],
       "imports": [],
-      "source": "npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli\ne3 auth login https://e3.example.com     # the device flow; e3-cloud reads the same credentials\ne3-cloud whoami https://e3.example.com   # your identity there, and whether you are an admin",
+      "source": "npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli\ne3 auth login https://e3.example.com     # the device flow; e3-cloud reads the same credentials\ne3-cloud whoami https://e3.example.com   # your identity there, whether you are an admin, and the releases (e3-cloud --version, below)",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-cli:static:versions",
+      "skill": "e3-cloud-cli",
+      "package": "e3-cloud-cli",
+      "file": "static",
+      "suite": "e3-cloud --version / whoami",
+      "test": "Which releases a push or a deploy depends on: this CLI's e3 cloud release and the east and e3 it is built with (--version, --json), and the deployment's release and e3 (whoami), with a note where their e3s differ: a package exported with a newer e3 than the deployment's is refused",
+      "keywords": [
+        "version",
+        "--version",
+        "-V",
+        "--json",
+        "whoami",
+        "release",
+        "e3 version",
+        "east version",
+        "deployment",
+        "platform",
+        "lockstep",
+        "compatible",
+        "staged for",
+        "e3-cloud"
+      ],
+      "imports": [],
+      "source": "e3-cloud --version                        # e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101): this CLI, and the east and e3 it is built with\ne3-cloud --version --json                 # {\"e3Cloud\":\"1.1.1\",\"east\":\"1.0.101\",\"e3\":\"1.0.101\"}\ne3-cloud whoami https://e3.example.com\n#   sub: …  email: …  admin: false\n#   deployment: e3-cloud 1.1.1, e3 1.0.101\n#   staged for: e3 1.0.102 (apps deployed with --for-platform)   (only when a bundle is staged for a next e3)\n#   cli: e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101)\n#   note: …   only where the CLI's e3 and the deployment's differ: a package exported with a newer e3 than the deployment's is refused\n# A project builds with the e3 cloud release the deployment runs, beside the east and e3 it pins (npm view @elaraai/e3-cloud-files@1.1.1 peerDependencies)",
       "languages": [
         "typescript"
       ]
@@ -1090,6 +1119,7 @@
         "beast2",
         "typed",
         "unchanged",
+        "dataset",
         "e3-cloud"
       ],
       "imports": [],
@@ -1098,6 +1128,42 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-cli:static:files-push-dataset",
+      "skill": "e3-cloud-cli",
+      "package": "e3-cloud-cli",
+      "file": "static",
+      "suite": "e3-cloud files",
+      "test": "Pushing a workspace's dataset (a task's output, an input or a record) into a source as the file of its value, with no file kept by hand: dataset:<workspace>.<name>, read from the repository --from names (a local path or a repository URL), matched by its name or --as, unchanged for the same stored value, refused in its row when unassigned or not found; a seed's history names the dataset",
+      "keywords": [
+        "files",
+        "push",
+        "dataset",
+        "dataset:",
+        "--from",
+        "task output",
+        "input",
+        "record",
+        "seed",
+        "$seed",
+        "--reset",
+        "--as",
+        "unchanged",
+        "unassigned",
+        "not_found",
+        "local repository",
+        "local workspace",
+        "e3 dataset get",
+        "beast2",
+        "e3-dataset",
+        "e3-cloud"
+      ],
+      "imports": [],
+      "source": "# A local workspace's task output seeding a deployed workspace's record: matched by its name (record:customers), put at its mapping's key\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive\n#   dataset:dev.customers (task output)  → record:customers  seed  3 MiB  put  $init #1  12,004 rows\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive   # the same stored value again: unchanged\ne3 dataflow run ./archive dev                                    # its value changes\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive   # $seed #2 while nothing has mutated the record; kept once something has\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive --reset customers   # its state again, over its mutations\n# --from defaults as e3's [repo] does ($E3_REPO, then .); a repository URL reads a deployed workspace's dataset with your e3 login\ne3-cloud files push ./repo dev dataset:production.price_list --from https://e3.example.com/repos/acme --as prices   # any file or latest mapping, by --as\n# Its bytes are the value's beast2, as `e3 dataset get -f beast2` writes it, read a segment at a time and checked against the mapping's type\n# before anything is put; under a latest prefix it is put as <name>.beast2; a folder or a listing takes no dataset. Refused in its row, the\n# rest going on: unassigned (a task output not produced since the last deploy, an input never set, a record with no state), not_found, ambiguous.\n# The object carries e3-dataset and e3-dataset-hash metadata; the history reads\n# \"Initialised from customers.beast2 (12,004 rows), from dev.customers at 3f9a2b1c4d5e\"",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-client:static:basics",
       "skill": "e3-cloud-client",
@@ -1123,6 +1189,32 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-client:static:versions",
+      "skill": "e3-cloud-client",
+      "package": "e3-cloud-client",
+      "file": "static",
+      "suite": "@elaraai/e3-cloud-client platform",
+      "test": "Which releases a deployment runs, from code: its e3 cloud release, the e3 its platform and runners run, and each next e3 an app's bundle is staged for; null from a deployment that predates it",
+      "keywords": [
+        "platformVersions",
+        "PlatformVersions",
+        "version",
+        "release",
+        "e3 version",
+        "e3Cloud",
+        "staged",
+        "deployment",
+        "/api/platform"
+      ],
+      "imports": [
+        "import { platformVersions } from '@elaraai/e3-cloud-client';"
+      ],
+      "source": "const versions = await platformVersions(url, options);   // anyone signed in may ask\nif (versions === null) console.log('the deployment predates it: it names no release');\nelse {\n  console.log(versions.e3Cloud.type === 'some' ? versions.e3Cloud.value : 'release not stated', versions.e3, versions.staged.join(', '));\n  // A package exported with a newer e3 than versions.e3 is refused: build with the e3 cloud release the deployment runs\n}",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-client:static:app-deploy",
       "skill": "e3-cloud-client",
@@ -1216,7 +1308,7 @@
       "file": "static",
       "id": "e3-cloud-client:static:files",
       "suite": "@elaraai/e3-cloud-client files",
-      "test": "Files from code: deploy a workspace's declarations, bind a source, sync named targets (a seeded record reset) and wait for the sync's report, read what each mapping holds, and plan a push of files from disk",
+      "test": "Files from code: deploy a workspace's declarations, bind a source, sync named targets (a seeded record reset) and wait for the sync's report, read what each mapping holds, and push a file from disk (plan, upload through the platform, sync), or a workspace's dataset as the file of its value",
       "keywords": [
         "getFiles",
         "deployFiles",
@@ -1225,6 +1317,8 @@
         "filesSyncWait",
         "planFilesPush",
         "completeFilesPush",
+        "FilesPushBytes",
+        "uploadFilesPush",
         "FilesTarget",
         "targets",
         "reset",
@@ -1233,18 +1327,21 @@
         "record",
         "mutation",
         "push",
+        "dataset",
         "unchanged",
         "refused",
         "retaken",
         "workspace_protected"
       ],
       "imports": [
+        "import { createReadStream } from 'node:fs';",
+        "import { stat } from 'node:fs/promises';",
         "import { none, some, variant } from '@elaraai/east';",
-        "import { bindFilesSource, completeFilesPush, deployFiles, filesSyncWait, getFiles, planFilesPush, startFilesSync } from '@elaraai/e3-cloud-client';",
+        "import { bindFilesSource, deployFiles, filesSyncWait, getFiles, planFilesPush, startFilesSync, uploadFilesPush, type FilesPushBytes } from '@elaraai/e3-cloud-client';",
         "import { filesPushRefusalText, filesTargetText } from '@elaraai/e3-cloud-types';",
         "import manifest from './files.js';   // export default Files.manifest([upload])"
       ],
-      "source": "// The declarations (checked against the package the workspace runs), then where the source's files are\nconst deployed = await deployFiles(url, 'acme', 'staging', manifest, options);\nif (deployed.type === 'refused') throw new Error(deployed.value.problems.map((p) => p.type).join(', '));\nawait bindFilesSource(url, 'acme', 'staging', { source: 'upload', url: 's3://partner-drop/acme/', region: none, profile: none, latest: none }, options);\n\n// A sync of two targets: the seeded record's file taken as its state again (reset), and the fed mutation's new files\nconst start = await startFilesSync(url, 'acme', 'staging', {\n  targets: [variant('record', 'customers'), variant('mutation', { record: 'price_book', mutation: 'load_prices' })],\n  reset: ['customers'],\n}, options);\nconst id = start.value;   // started, or running: the sync under way, waited on the same way\nconst job = await filesSyncWait(url, 'acme', 'staging', id, options, { deadlineMs: 10 * 60_000 });\nfor (const m of job.report.type === 'some' ? job.report.value.mappings : []) {\n  console.log(filesTargetText(m.target), m.updated ? `written (commit ${m.commit.type === 'some' ? m.commit.value.slice(0, 12) : 'none'})` : 'as it was', m.refused.length === 0 ? '' : `refused ${m.refused[0]!.key}`);\n}\n\n// What each mapping holds now; a record not yet seeded is pending\nconst files = await getFiles(url, 'acme', 'staging', options);\nconsole.log(files.status.mappings.map((m) => `${filesTargetText(m.target)}: ${m.pending ? 'pending' : m.holds.type === 'some' ? m.holds.value.key : 'nothing yet'}`).join(' · '));\n\n// A push from disk: the plan says per file where it goes and how to upload it (a single PUT here); then sync what was put\nconst plan = await planFilesPush(url, 'acme', 'staging', { files: [{ name: 'customers.beast2', directory: none, size: 4096n, sha256, type: some(customerBookType) }], as: none }, options);\nfor (const f of plan.files) {\n  if (f.outcome.type === 'refused') console.warn(f.name, filesPushRefusalText(f.outcome.value));\n  else if (f.outcome.type === 'put' && f.outcome.value.upload.type === 'single') {\n    await fetch(f.outcome.value.upload.value.url, { method: 'PUT', body: bytes, headers: Object.fromEntries(f.outcome.value.upload.value.headers) });\n  } else if (f.outcome.type === 'put' && f.outcome.value.upload.type === 'multipart') {\n    const parts = [];   // each part PUT to its url, its ETag kept\n    await completeFilesPush(url, 'acme', 'staging', { key: f.outcome.value.key, uploadId: f.outcome.value.upload.value.uploadId, parts }, options);\n  }\n}",
+      "source": "// The declarations (checked against the package the workspace runs), then where the source's files are\nconst deployed = await deployFiles(url, 'acme', 'staging', manifest, options);\nif (deployed.type === 'refused') throw new Error(deployed.value.problems.map((p) => p.type).join(', '));\nawait bindFilesSource(url, 'acme', 'staging', { source: 'upload', url: 's3://partner-drop/acme/', region: none, profile: none, latest: none }, options);\n\n// A sync of two targets: the seeded record's file taken as its state again (reset), and the fed mutation's new files\nconst start = await startFilesSync(url, 'acme', 'staging', {\n  targets: [variant('record', 'customers'), variant('mutation', { record: 'price_book', mutation: 'load_prices' })],\n  reset: ['customers'],\n}, options);\nconst id = start.value;   // started, or running: the sync under way, waited on the same way\nconst job = await filesSyncWait(url, 'acme', 'staging', id, options, { deadlineMs: 10 * 60_000 });\nfor (const m of job.report.type === 'some' ? job.report.value.mappings : []) {\n  console.log(filesTargetText(m.target), m.updated ? `written (commit ${m.commit.type === 'some' ? m.commit.value.slice(0, 12) : 'none'})` : 'as it was', m.refused.length === 0 ? '' : `refused ${m.refused[0]!.key}`);\n}\n\n// What each mapping holds now; a record not yet seeded is pending\nconst files = await getFiles(url, 'acme', 'staging', options);\nconsole.log(files.status.mappings.map((m) => `${filesTargetText(m.target)}: ${m.pending ? 'pending' : m.holds.type === 'some' ? m.holds.value.key : 'nothing yet'}`).join(' · '));\n\n// A push from disk: the plan says per file where it goes and how to upload it; uploadFilesPush puts it through the platform\n// (one PUT bound to its SHA-256, or a multipart upload it completes), then one sync of the targets put\nconst path = 'data/customers.beast2';\nconst size = (await stat(path)).size;\nconst plan = await planFilesPush(url, 'acme', 'staging', {\n  files: [{ name: 'customers.beast2', directory: none, size: BigInt(size), sha256, type: some(customerBookType), dataset: none }],   // sha256: hex; type: its beast2 header's\n  as: none,\n}, options);\nconst bytes: FilesPushBytes = { size, ranged: true, read: (start) => createReadStream(path, { start }) };   // a file reads from any offset\nfor (const f of plan.files) {\n  if (f.outcome.type === 'refused') console.warn(f.name, filesPushRefusalText(f.outcome.value));\n  else if (f.outcome.type === 'put') await uploadFilesPush(url, 'acme', 'staging', plan, f.outcome.value, bytes, options);   // an `external` put throws: your own credentials\n}\nawait startFilesSync(url, 'acme', 'staging', { targets: plan.files.flatMap((f) => (f.outcome.type === 'put' ? [f.outcome.value.target] : [])) }, options);\n// A workspace's dataset is offered as the file of its value: dataset: some({ workspace: 'dev', name: 'customers', hash }), its type the value's,\n// its bytes the value's beast2 as `e3 dataset get -f beast2` writes it, streamed (ranged: false: never held whole) and matched by its name.\n// `e3-cloud files push … dataset:dev.customers --from <repo>` does all of it",
       "languages": [
         "typescript"
       ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-cloud-claude-plugin",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/skills/e3-cloud-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-cli
-description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a release carries the package, the apps and the Files declarations; the target keeps its data and bindings), `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`), (8) Files — a solution's inputs from files in a bucket: `e3-cloud files deploy|bind|sync|status`, given a local repository's path or a repository URL (the e3-cloud-files skill declares and decodes them), (9) Walking a solution through its life, step by step — starting it, adding a staging, developing an app's pages, changing the package's tasks and inputs, migrating a record, Files, rehearsing and releasing, rolling back, an emergency change to production, people and roles, schedules, secrets and compute, feedback, the platform's next e3, and retiring an app or a workspace."
+description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares), checking who you are and which e3 cloud release and e3 the deployment runs (`e3-cloud whoami SERVER`), and which this CLI is built with (`e3-cloud --version`, `--json`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a release carries the package, the apps and the Files declarations; the target keeps its data and bindings), `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`), (8) Files — a solution's inputs from files in a bucket: `e3-cloud files deploy|bind|sync|push|status`, given a local repository's path or a repository URL, and `files push` of files from disk or of a workspace's dataset as the file of its value (`dataset:WORKSPACE.NAME`, `--from` a local repository or a URL) (the e3-cloud-files skill declares and decodes them), (9) Walking a solution through its life, step by step — starting it, adding a staging, developing an app's pages, changing the package's tasks and inputs, migrating a record, Files, rehearsing and releasing, rolling back, an emergency change to production, people and roles, schedules, secrets and compute, feedback, the platform's next e3, and retiring an app or a workspace."
 ---
 
 # e3-cloud — the e3 cloud CLI (@elaraai/e3-cloud-cli)
@@ -38,7 +38,7 @@ Nothing is injected for you; the search is the step.
 ```bash
 npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli
 e3 auth login https://e3.example.com
-e3-cloud whoami https://e3.example.com
+e3-cloud whoami https://e3.example.com     # you, the release and e3 the deployment runs, and this CLI's
 
 # An app: build its bundle, check it, deploy it
 e3-cloud app build src/apps/ops.tsx
@@ -190,6 +190,7 @@ e3-cloud files deploy URL staging src/files.ts
 e3-cloud files bind   URL staging upload s3://bucket/acme/staging/
 e3-cloud files sync   URL staging
 e3-cloud files push   URL staging ./data/prices.beast2 ./data/customers.beast2    # from disk: matched by name (or --as), put, synced
+e3-cloud files push   URL staging dataset:dev.customers --from ./repo              # a local workspace's dataset, as the file of its value
 e3-cloud files sync   URL staging --target record:customers --reset customers     # named targets; a seeded record's file as its state again
 e3 dataflow run URL staging
 ```
@@ -414,6 +415,16 @@ a repository URL:
 - `files sync <repo> <ws>` reads only files whose ETag or size changed and
   writes only inputs whose files changed; `--target`, `--reset`, `--dry-run`. It doesn't
   run the dataflow: `e3 dataflow run` does, and the sync prints the command.
+- `files push <repo> <ws> <path…>` puts files from disk, or datasets
+  (`dataset:<ws>.<name>`: a task's output, an input or a record, read from
+  the repository `--from` names, a local path or a URL, default `$E3_REPO`
+  then `.`), into the source each one's mapping reads, then syncs what was
+  put: matched by name or `--as`, checked against the mapping's type before
+  anything is put, `unchanged` when the source holds it already, refused in
+  its row otherwise (`unassigned`, `not_found`, `no_mapping`, `type_mismatch`,
+  …); `--reset`, `--dry-run`, `--profile` (a bucket the platform doesn't
+  write). A seed's or feed's history names the file, and the dataset it was
+  pushed from.
 - `files status <repo> <ws>`: the declarations, the bindings, the last sync.
 
 ## Traps
@@ -432,4 +443,9 @@ a repository URL:
   next run reads the new value.
 - The version is e3 cloud's own, not e3's: use the CLI of the e3 cloud
   release your deployment runs, beside e3's CLI of the e3 that release is
-  built with (its dependencies pin it).
+  built with (its dependencies pin it). `e3-cloud --version` prints
+  `e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101)` (`--json`:
+  `{"e3Cloud":…,"east":…,"e3":…}`); `e3-cloud whoami <server>` prints the
+  deployment's `deployment: e3-cloud 1.1.1, e3 1.0.101` beside it, and a
+  `note:` where the e3s differ: a package exported with a newer e3 than the
+  deployment's is refused.

package/skills/e3-cloud-client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-client
-description: "@elaraai/e3-cloud-client — drive an e3 cloud deployment from TypeScript. Use when: (1) Calling a deployment from code with a token (`whoami`, `RequestOptions`, `ApiError`), (2) Managing a repository's people and business roles (`repoUsers`, `addUser`, `removeUser`, `repoInvitations`, `listRoles`, `putRole`, `myAccess`), (3) Deploying apps from code — `appUpload`, `appDeploy` / `appsDeploy` and `appDeployWait`, `appList`, `appGet`, `appVersions`, `appRemove` — and reading a refusal (`appProblemsText`), (4) Staging, releasing and rolling back — `addStaging` / `stopStaging` (a staging protects the workspace it releases to), `releaseWorkspace`, `rollbackWorkspace` (a plan first, `releasePlanRefusalLines`), `workspaceHistory`, `getRepositoryReleaseSettings`, (5) Secrets, schedules and task configs (`putSecret`, `listSecrets`, `setSchedule`, `setCompute`, `setTimeout`), (6) Records' history and backups (`recordAudit`, `createRecordBackup`, `restoreRecordBackup`) and feedback (`listFeedback`, `closeFeedback`)."
+description: "@elaraai/e3-cloud-client — drive an e3 cloud deployment from TypeScript. Use when: (1) Calling a deployment from code with a token (`whoami`, `RequestOptions`, `ApiError`), (2) Managing a repository's people and business roles (`repoUsers`, `addUser`, `removeUser`, `repoInvitations`, `listRoles`, `putRole`, `myAccess`), (3) Deploying apps from code — `appUpload`, `appDeploy` / `appsDeploy` and `appDeployWait`, `appList`, `appGet`, `appVersions`, `appRemove` — and reading a refusal (`appProblemsText`), (4) Staging, releasing and rolling back — `addStaging` / `stopStaging` (a staging protects the workspace it releases to), `releaseWorkspace`, `rollbackWorkspace` (a plan first, `releasePlanRefusalLines`), `workspaceHistory`, `getRepositoryReleaseSettings`, (5) Secrets, schedules and task configs (`putSecret`, `listSecrets`, `setSchedule`, `setCompute`, `setTimeout`), (6) Records' history and backups (`recordAudit`, `createRecordBackup`, `restoreRecordBackup`) and feedback (`listFeedback`, `closeFeedback`), (7) Files from code — `getFiles`, `deployFiles`, `bindFilesSource`, `startFilesSync` and `filesSyncWait`, and a push: `planFilesPush`, `uploadFilesPush` (a file from disk by ranges, or a workspace's dataset as its value streams, with its type and where it came from), `completeFilesPush`, (8) Which releases a deployment runs (`platformVersions`: its e3 cloud release, its e3, the next e3s bundles are staged for)."
 ---
 
 # @elaraai/e3-cloud-client
@@ -92,13 +92,33 @@ try {
   or `variant('mutation', { record, mutation })`; `reset` names seeded
   records whose file is taken as their state again.
 - `planFilesPush(url, repo, ws, { files, as }, options)` plans a push of
-  files from disk (each offered with its name, size, SHA-256 and beast2
-  header type): per file `put` with its key and how to upload it — `single`
-  (one PUT with the plan's headers), `multipart` (a URL per part, then
-  `completeFilesPush(url, repo, ws, { key, uploadId, parts }, options)`) or
-  `external` (your own credentials) — `unchanged`, or `refused` with why
-  (`filesPushRefusalText`). Then sync the targets put. The CLI's
-  `files push` does all of this.
+  files (each offered with its name, size, SHA-256 and beast2 header type,
+  and `dataset: some({ workspace, name, hash })` for a workspace's dataset
+  offered as the file of its value): per file `put` with its key and how to
+  upload it — `single` (one PUT with the plan's headers), `multipart` (a URL
+  per part, then a completion) or `external` (your own credentials) —
+  `unchanged`, or `refused` with why (`filesPushRefusalText`). A dataset is
+  matched by its name, to the `file` or `latest` mapping filling the input
+  or record of that name.
+- `uploadFilesPush(url, repo, ws, plan, put, bytes, options, refresh?)`
+  uploads one put through the platform, `bytes` a `FilesPushBytes`
+  (`{ size, read(start), ranged }`): a file on disk is `ranged` (its parts
+  sent four at a time, each read from its start), a dataset's value streams
+  from its repository (`ranged: false`, parts one after another, never held
+  whole). A multipart upload is completed under the object's key in its
+  bucket (`completeFilesPush`); a source that throws as its bytes end (a
+  dataset rewritten while it was read) has its last bytes held back, so
+  nothing other than the planned bytes is ever stored. Then sync the targets
+  put. The CLI's `files push` does all of this.
+
+## Versions
+
+- `platformVersions(url, options)` answers what a deployment runs:
+  `{ e3Cloud: some('1.1.1'), e3: '1.0.101', staged: [...] }` (the next e3s
+  an app's bundle is staged for, in the repositories the caller manages), or
+  `null` from a deployment that predates it. A package exported with a newer
+  e3 than the deployment's is refused: compare it with the e3 your project
+  builds with before a deploy.
 
 ## Traps
 

package/skills/e3-cloud-files/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-files
-description: "Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems), an unbound source, a file over its limit, a protected workspace (workspace_protected), (6) Moving declarations to production through staging: a release carries them with the package and apps, a rollback restores them, a copy brings bindings and what each input took, and production's bindings stay its own, (7) Reading Files' East types (FilesManifestType, FilesBindingType, FilesSyncReportType — @elaraai/e3-cloud-types), (8) Taking a beast2 file in as an input of its type with no task in between: file or latest with a type, a collection of any size, (9) Feeding a record's mutation from files with source.mutation(def, spec), def one its record declares (priceBook.mutations.load_prices), each new file applied once, (10) Pushing files from disk into a source and taking them in with e3-cloud files push, matched by name or --as, dry-run, unchanged, (11) Seeding a record from a file with source.record(name, type, spec, parts): e3.record with no initial value, declared whole with its indexes, mutations and migrations, pending until its file, its tasks waiting meanwhile, (12) Syncing or resetting particular targets with --target and --reset."
+description: "Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems), an unbound source, a file over its limit, a protected workspace (workspace_protected), (6) Moving declarations to production through staging: a release carries them with the package and apps, a rollback restores them, a copy brings bindings and what each input took, and production's bindings stay its own, (7) Reading Files' East types (FilesManifestType, FilesBindingType, FilesSyncReportType — @elaraai/e3-cloud-types), (8) Taking a beast2 file in as an input of its type with no task in between: file or latest with a type, a collection of any size, (9) Feeding a record's mutation from files with source.mutation(def, spec), def one its record declares (priceBook.mutations.load_prices), each new file applied once, (10) Pushing files from disk into a source and taking them in with e3-cloud files push, matched by name or --as, dry-run, unchanged, or a workspace's dataset (a task's output, an input, a record) as the file of its value with dataset:workspace.name and --from, local or remote at either end, (11) Seeding a record from a file with source.record(name, type, spec, parts): e3.record with no initial value, declared whole with its indexes, mutations and migrations, pending until its file, its tasks waiting meanwhile, (12) Syncing or resetting particular targets with --target and --reset."
 ---
 
 # e3-cloud-files — files as e3 inputs
@@ -11,8 +11,9 @@ are, a bucket and a prefix, and `e3-cloud files sync` brings in what changed:
 on a local repository with your own cloud credentials, in the cloud with the
 platform's read-only role. A file arrives as it is, a `Blob`, and a task
 decodes it; or, named with a type, a beast2 file arrives as the value it
-holds, with no task in between. `e3-cloud files push` puts files from disk
-into a source and takes them in. Nothing polls: a sync runs when someone asks.
+holds, with no task in between. `e3-cloud files push` puts files from disk,
+or a workspace's datasets as the files of their values, into a source and
+takes them in. Nothing polls: a sync runs when someone asks.
 
 Read `README.md` for the author's guide; this file is the short form.
 
@@ -89,6 +90,7 @@ What do you need?
 │   │   └─ Locally only               → --profile <aws profile>, --latest <n> (each folder's n greatest keys)
 │   ├─ Bring in what changed          → e3-cloud files sync <repo> <ws> [--target t…] [--reset record…] [--dry-run]
 │   ├─ Put files from disk            → e3-cloud files push <repo> <ws> <file|dir>… [--as target] [--dry-run] [--profile p]
+│   ├─ Push a workspace's dataset     → e3-cloud files push <repo> <ws> dataset:<ws>.<name>… [--from <repo>] (a task's output, an input, a record)
 │   ├─ What is declared, bound, held  → e3-cloud files status <repo> <ws> (each mapping, its type, what it holds, pending)
 │   └─ Run the dataflow on it         → e3 dataflow run <repo> <ws> (a sync doesn't run it)
 ├─ Production: a workspace with a staging (a deployed repository's URL)
@@ -175,7 +177,7 @@ file's path under the prefix, in path order.
 e3-cloud files deploy <repo> <workspace> src/files.ts [--dry-run]
 e3-cloud files bind   <repo> <workspace> upload s3://bucket/prefix/ [--region r] [--profile p] [--latest n]
 e3-cloud files sync   <repo> <workspace> [--target name|record:r|mutation:r.m ...] [--reset record...] [--dry-run]
-e3-cloud files push   <repo> <workspace> <file|dir>... [--as target] [--reset record...] [--dry-run] [--profile p]
+e3-cloud files push   <repo> <workspace> <file|dir|dataset:ws.name>... [--from repo] [--as target] [--reset record...] [--dry-run] [--profile p]
 e3-cloud files status <repo> <workspace>
 e3 dataflow run <repo> <workspace>
 ```
@@ -188,7 +190,31 @@ file's SHA-256; your own credentials elsewhere), then syncs what was put. A
 file the source holds already is `unchanged`; refused: `no_mapping`,
 `ambiguous` (name the target with `--as`), `not_included` (the mapping's
 glob leaves it out), `not_latest` (a greater key would shadow it), a typed
-mapping's file of another type or no beast2, one over the limit.
+mapping's file of another type or no beast2, one over the limit. The report
+numbers a record's seeds: `$init #1`, `$seed #2`, …
+
+`dataset:<workspace>.<name>` pushes a value a workspace holds (a task's
+output, an input or a record, by its name) as the file of its value would,
+with no file kept by hand: its bytes are the value's beast2 (as
+`e3 dataset get -f beast2` writes it), read a segment at a time from the
+repository `--from` names (a local path or a repository URL; default
+`$E3_REPO`, then `.`, as e3's `[repo]`). It goes to the `file` or `latest`
+mapping filling the input or record of its name, else `--as` names one; it
+is put at the `file`'s key, or under the `latest`'s prefix as
+`<name>.beast2`; a `folder` or `listing` takes none. The same stored value
+is `unchanged`; refused in their rows: `unassigned` (a task output not
+produced since the workspace's last deploy, an input never set, a record
+with no state), `not_found`, `ambiguous` (two of the workspace's datasets
+have the name); a dataset a run rewrites while it uploads fails in its row
+(push again). The object carries `e3-dataset` and `e3-dataset-hash`
+metadata, and a seed's or feed's history names the dataset: "Initialised
+from customers.beast2 (12,004 rows), from dev.customers at 3f9a2b1c4d5e".
+Files, directories and datasets mix in one push.
+
+```bash
+# A local workspace's task output, seeding a deployed workspace's record
+e3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive
+```
 
 `--target` names an input, `record:<name>` or `mutation:<record>.<name>`
 (split at its last dot); `--reset <record>` takes a seeded record's file as
@@ -223,6 +249,11 @@ keeps only each folder's n greatest keys.
   its file. A deploy that cannot keep it (its type changed) under
   `--schema reset` unassigns it: pending again, seeded by the next version's
   file.
+- A dataset pushed to a seeded record seeds it like a file: again while
+  unmutated (`$seed #n`), `kept` once mutated, over its mutations with
+  `--reset`. A dataset whose value is unchanged since the last push is
+  `unchanged`, nothing put; one never produced since the workspace's last
+  deploy is `unassigned`: run the dataflow first.
 - A record is declared whole: a fed mutation is one its record declares
   (`priceBook.mutations.load_prices`), and a seeded record's indexes,
   mutations and migrations are `upload.record`'s `parts`; an initial value