@elaraai/e3-cloud-codex-plugin 1.0.97 → 1.1.0

package/.build/hooks/codex-tools.js

@@ -1,11 +1,11 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
 import { readFile as readFile2 } from "node:fs/promises";
 import { existsSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join, resolve as resolve3 } from "node:path";
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-tools.js
 import { resolve } from "node:path";
 function patchFiles(command, cwd) {
   const files = [];
@@ -43,7 +43,7 @@ function shellReadPaths(command, cwd) {
   return [...paths];
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/bash-writes.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/bash-writes.js
 import { resolve as resolve2 } from "node:path";
 function isRealPath(token) {
   if (token === "" || token.startsWith("&"))
@@ -92,7 +92,7 @@ function writtenPaths(command, cwd) {
   return [...found];
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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) {
@@ -105,7 +105,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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",
@@ -147,7 +147,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
 function codexToolCall(event) {
   const cwd = event.cwd || process.cwd();
   const input = event.tool_input ?? {};
@@ -199,7 +199,7 @@ async function codexSearchGate(event, options, call = codexToolCall(event)) {
   return context.length > 0 ? { decision: "context", text: context.join("\n\n") } : null;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync as existsSync2 } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync2(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -207,7 +207,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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) {
@@ -235,7 +235,7 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 function writeSearchHookReply(hookEventName, reply) {
   if (reply.decision === "deny")
     writeHookDecision(hookEventName, "deny", reply.text);

package/.build/mcp/server.js

@@ -15140,7 +15140,7 @@ function object(shape, params) {
   return new ZodMiniObject(def);
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
 function isZ4Schema(s) {
   const schema = s;
   return !!schema._zod;
@@ -15995,7 +15995,7 @@ function preprocess(fn, schema) {
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v4/classic/external.js
 config(en_default2());
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
 var LATEST_PROTOCOL_VERSION = "2025-11-25";
 var SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"];
 var RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task";
@@ -17526,7 +17526,7 @@ var UrlElicitationRequiredError = class extends McpError {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
 function isTerminal(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
@@ -18815,7 +18815,7 @@ var zodToJsonSchema = (schema, options) => {
   return combined;
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
 function mapMiniTarget(t) {
   if (!t)
     return "draft-7";
@@ -18857,7 +18857,7 @@ function parseWithCompat(schema, data) {
   return result.data;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
 var DEFAULT_REQUEST_TIMEOUT_MSEC = 6e4;
 var Protocol = class {
   constructor(_options) {
@@ -19834,7 +19834,7 @@ function mergeCapabilities(base, additional) {
   return result;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
 var import_ajv = __toESM(require_ajv(), 1);
 var import_ajv_formats = __toESM(require_dist(), 1);
 function createDefaultAjvInstance() {
@@ -19902,7 +19902,7 @@ var AjvJsonSchemaValidator = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
 var ExperimentalServerTasks = class {
   constructor(_server) {
     this._server = _server;
@@ -20115,7 +20115,7 @@ var ExperimentalServerTasks = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
 function assertToolsCallTaskCapability(requests, method, entityName) {
   if (!requests) {
     throw new Error(`${entityName} does not support task creation (required for ${method})`);
@@ -20150,7 +20150,7 @@ function assertClientRequestTaskCapability(requests, method, entityName) {
   }
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
 var Server = class extends Protocol {
   /**
    * Initializes this server with the given name and version information.
@@ -20521,7 +20521,7 @@ var Server = class extends Protocol {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
 var COMPLETABLE_SYMBOL = /* @__PURE__ */ Symbol.for("mcp.completable");
 function isCompletable(schema) {
   return !!schema && typeof schema === "object" && COMPLETABLE_SYMBOL in schema;
@@ -20535,7 +20535,7 @@ var McpZodTypeKind;
   McpZodTypeKind2["Completable"] = "McpCompletable";
 })(McpZodTypeKind || (McpZodTypeKind = {}));
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
 var TOOL_NAME_REGEX = /^[A-Za-z0-9._-]{1,128}$/;
 function validateToolName(name) {
   const warnings = [];
@@ -20593,7 +20593,7 @@ function validateAndWarnToolName(name) {
   return result.isValid;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
 var ExperimentalMcpServerTasks = class {
   constructor(_mcpServer) {
     this._mcpServer = _mcpServer;
@@ -20608,7 +20608,7 @@ var ExperimentalMcpServerTasks = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
 function toolInputElementCount(value, max) {
   let count = 0;
   const stack = [value];
@@ -20657,6 +20657,15 @@ var McpServer = class {
     this._promptHandlersInitialized = false;
     this.server = new Server(serverInfo, options);
     this._maxToolInputElements = resolveMaxToolInputElements(options?.maxToolInputElements);
+    if (options?.capabilities?.tools) {
+      this.setToolRequestHandlers();
+    }
+    if (options?.capabilities?.resources) {
+      this.setResourceRequestHandlers();
+    }
+    if (options?.capabilities?.prompts) {
+      this.setPromptRequestHandlers();
+    }
   }
   /**
    * Access experimental features.
@@ -21440,10 +21449,10 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 import process from "node:process";
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
   constructor(options) {
@@ -21480,7 +21489,7 @@ function serializeMessage(message) {
   return JSON.stringify(message) + "\n";
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
   constructor(_stdin = process.stdin, _stdout = process.stdout, options) {
     this._stdin = _stdin;
@@ -21547,7 +21556,7 @@ var StdioServerTransport = class {
   }
 };
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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
@@ -23360,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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",
@@ -23402,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 var MIN_SCORE = 5;
 async function loadIndexes(indexPaths) {
   const entries = [];
@@ -23444,6 +23453,7 @@ function normalizePackage(filter, scopes = EAST_SCOPES) {
   const scope = scopes.find((s) => name.startsWith(`${s.toLowerCase()}/`));
   return scope === void 0 ? name : name.slice(scope.length + 1);
 }
+var OPT_IN_PACKAGES = /* @__PURE__ */ new Set(["east-values"]);
 function searchExamples(index, request) {
   const known = index.packages;
   const filter = request.package;
@@ -23453,7 +23463,7 @@ function searchExamples(index, request) {
   }
   const options = {
     limit: request.limit,
-    ...pkg === void 0 ? {} : { filter: (r) => r.package === pkg || r.skill === pkg }
+    filter: (r) => OPT_IN_PACKAGES.has(r.package) ? r.package === pkg : pkg === void 0 || r.package === pkg || r.skill === pkg
   };
   const hits = index.search.search(request.query, options);
   return { entries: hits.filter((r) => r.score >= MIN_SCORE).slice(0, request.limit), known };
@@ -23527,7 +23537,7 @@ function getEntry(index, id) {
   return stored === void 0 ? null : stored;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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";
@@ -23548,7 +23558,7 @@ function registerExampleTools(server2, options) {
     language: languageArg,
     format: external_exports.enum(["summary", "full"]).default("summary").describe(`"summary" (default) lists the hits in one line each; "full" includes each hit's code in the requested language`),
     limit: external_exports.number().int().min(1).max(20).default(5).describe("Maximum number of results to return (default 5, max 20)"),
-    package: external_exports.string().optional().describe(`Filter results to one package by its bare name \u2014 ${packages.join(", ")} \u2014 ${scopesNamed}; an unknown name is reported with the indexed names`)
+    package: external_exports.string().optional().describe(`Filter results to one package by its bare name \u2014 ${packages.join(", ")} \u2014 ${scopesNamed}; an unknown name is reported with the indexed names${packages.includes("east-values") ? '. "east-values" is east-py code working with East values directly (eager methods on python values, not an East function), and is searched only when named here' : ""}`)
   }, async ({ query, language, format, limit, package: packageFilter }) => {
     const index = await indexPromise;
     const { entries, unknownPackage, known } = searchExamples(index, { query, limit, package: packageFilter, scopes });
@@ -23600,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.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.100_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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e3-cloud-codex-plugin",
-  "version": "1.0.97",
+  "version": "1.1.0",
   "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": 40,
+    "totalEntries": 44,
     "totalFiles": 2,
     "packages": {
       "e3-cloud-ui": 12,
-      "e3-cloud-files": 11,
+      "e3-cloud-files": 14,
       "e3-cloud-cli": 13,
-      "e3-cloud-client": 4
+      "e3-cloud-client": 5
     }
   },
   "entries": [
@@ -183,7 +183,7 @@
       "package": "e3-cloud-ui",
       "file": "packages/e3-cloud-ui/test/pages.examples.tsx",
       "suite": "Functions and records",
-      "test": "Changing a record from a page: Record.bind(orders, [approve]) names the mutations the page may run, and o.mutate.approve(id) commits one",
+      "test": "Changing a record from a page: Record.bind(orders, ['approve']) names the mutations the page may run, by the names the record declares them under, and o.mutate.approve(id) commits one",
       "keywords": [
         "Record.bind",
         "mutate",
@@ -203,7 +203,7 @@
       "languages": [
         "tsx"
       ],
-      "source": "// Changing a record from a page: Record.bind(orders, [approve]) names the mutations the page may run, and o.mutate.approve(id) commits one\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations. */\nconst orders = e3.record('orders', DictType(StringType, Order), new Map());\n\n/** Approves an order by its id. */\nconst approve = e3.mutation.reduce('approve', orders,\n  East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n  { runner: RUNNER });\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const o = $.let(Record.bind(orders, [approve]));\n      const approveA17 = $.const(East.function([], NullType, $ => { $(o.mutate.approve('A-17')); }));\n      return <Button onClick={approveA17}>Approve A-17</Button>;\n    }}</Reactive>\n  ))"
+      "source": "// Changing a record from a page: Record.bind(orders, ['approve']) names the mutations the page may run, by the names the record declares them under, and o.mutate.approve(id) commits one\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations, declared whole with its index and its mutation. */\nconst orders = e3.record('orders', DictType(StringType, Order), {\n  initial: new Map(),\n  indexes: (index) => ({\n    /** The orders by line. */\n    by_line: index.key(East.function([StringType, Order], StringType, (_$, _id, o) => o.line)),\n  }),\n  mutations: (mutation) => ({\n    /** Approves an order by its id. */\n    approve: mutation.reduce(\n      East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n      { runner: RUNNER }),\n  }),\n});\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const o = $.let(Record.bind(orders, ['approve']));\n      const approveA17 = $.const(East.function([], NullType, $ => { $(o.mutate.approve('A-17')); }));\n      return <Button onClick={approveA17}>Approve A-17</Button>;\n    }}</Reactive>\n  ))"
     },
     {
       "id": "e3-cloud-ui:pages.examples.tsx:pageReadsARecordThroughAnIndex",
@@ -211,11 +211,11 @@
       "package": "e3-cloud-ui",
       "file": "packages/e3-cloud-ui/test/pages.examples.tsx",
       "suite": "Functions and records",
-      "test": "Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: byLine }) given the index's declaration, its rows the index key and the order's id",
+      "test": "Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: 'by_line' }) given the name the record declares the index under, its rows the index key and the order's id",
       "keywords": [
         "Data.bindPaged",
         "index",
-        "recordIndex",
+        "indexes",
         "record",
         "paged",
         "Table",
@@ -232,7 +232,7 @@
       "languages": [
         "tsx"
       ],
-      "source": "// Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: byLine }) given the index's declaration, its rows the index key and the order's id\n// inputs: []\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations. */\nconst orders = e3.record('orders', DictType(StringType, Order), new Map());\n\n/** The orders by line. */\nconst byLine = e3.recordIndex('by_line', orders,\n  { key: East.function([StringType, Order], StringType, (_$, _id, o) => o.line) });\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const mine = $.let(Data.bindPaged(orders, { index: byLine }));\n      return <Table data={mine} columns={['ik', 'key']} />;\n    }}</Reactive>\n  ))"
+      "source": "// Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: 'by_line' }) given the name the record declares the index under, its rows the index key and the order's id\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations, declared whole with its index and its mutation. */\nconst orders = e3.record('orders', DictType(StringType, Order), {\n  initial: new Map(),\n  indexes: (index) => ({\n    /** The orders by line. */\n    by_line: index.key(East.function([StringType, Order], StringType, (_$, _id, o) => o.line)),\n  }),\n  mutations: (mutation) => ({\n    /** Approves an order by its id. */\n    approve: mutation.reduce(\n      East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n      { runner: RUNNER }),\n  }),\n});\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const mine = $.let(Data.bindPaged(orders, { index: 'by_line' }));\n      return <Table data={mine} columns={['ik', 'key']} />;\n    }}</Reactive>\n  ))"
     },
     {
       "id": "e3-cloud-files:decode.examples.ts:fileAsJson",
@@ -314,6 +314,34 @@
       ],
       "source": "// A text file input's lines, trimmed, blank ones left out\n// inputs: [utf8('first\\n\\n  second  \\nthird\\n')]  returns: ['first', 'second', 'third']\nEast.function([BlobType], ArrayType(StringType), (_$, file) =>\n    file.decodeUtf8().split('\\n').map((_$, line) => line.trim()).filter((_$, line) => line.notEquals('')))"
     },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:typedFileAsItsValue",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A typed file: no decoding",
+      "test": "A typed input needs no decoding: what upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) }) fills is the beast2 file's value itself, an Array<Price> the task takes as any dataset, here counted",
+      "keywords": [
+        "Files",
+        "typed",
+        "type",
+        "beast2",
+        "file",
+        "latest",
+        "no decoding",
+        "ArrayType",
+        "size",
+        "task"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// A typed input needs no decoding: what upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) }) fills is the beast2 file's value itself, an Array<Price> the task takes as any dataset, here counted\n// inputs: [[{ sku: 'A1', price: 1.5 }, { sku: 'B2', price: 2.25 }, { sku: 'C3', price: 9 }]]  returns: 3n\nconst Price = StructType({ sku: StringType, price: FloatType });\n\nEast.function([ArrayType(Price)], IntegerType, (_$, prices) => prices.size())"
+    },
     {
       "id": "e3-cloud-files:decode.examples.ts:folderAsOneArray",
       "skill": "e3-cloud-files",
@@ -593,35 +621,104 @@
       ]
     },
     {
-      "id": "e3-cloud-files:static:typed",
+      "id": "e3-cloud-files:static:typed-input",
       "skill": "e3-cloud-files",
       "package": "e3-cloud-files",
       "file": "static",
       "suite": "Files",
-      "test": "A beast2 file as an input of its type with no task in between (file or latest with a type), and a record's mutation fed by each new file: the declarations, the package, and what a sync does with them",
+      "test": "A beast2 file as an input of its type with no task in between: file or latest with a type, a collection of any size, its header checked before any other byte, a file of another type refused naming both types, the same bytes under a new ETag changing nothing",
       "keywords": [
         "Files",
         "type",
         "beast2",
         "typed",
+        "typed input",
         "ArrayType",
         "upload.file",
         "upload.latest",
-        "upload.mutation",
-        "mutation",
-        "feed",
-        "record",
-        "e3.mutation.reduce",
         "encodeBeast2For",
+        "Beast2ElementWriter",
         "collection",
+        "type_mismatch",
+        "not_beast2",
+        "e3-cloud-files"
+      ],
+      "imports": [
+        "import { East, ArrayType, FloatType, IntegerType, StringType, StructType } from '@elaraai/east';",
+        "import e3, { type Runner } from '@elaraai/e3';",
+        "import { Files } from '@elaraai/e3-cloud-files';"
+      ],
+      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nexport const upload = Files.source('upload');\n// A beast2 file of Array<Price> (encodeBeast2For(ArrayType(Price)), a Beast2ElementWriter for a collection of any size, east-py, e3 convert):\n// an input of that type, taken in as the value it holds, its header checked before any other byte is read; a file of another type is\n// refused naming both types (type_mismatch), no beast2 at all as not_beast2, and the input keeps its value. The same bytes again under\n// a new ETag give the same value: nothing downstream runs\nexport const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });\nexport const stock = upload.latest('stock', { prefix: 'stock/', include: '*.beast2', type: ArrayType(Price) });   // the greatest key, typed\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n// Used as any dataset: no decoding, the value is the file's\nexport const summary = e3.task('price_summary', [prices, stock], East.function([ArrayType(Price), ArrayType(Price)], IntegerType, (_$, rows, latest) => rows.size().add(latest.size())), { runner });\nexport default e3.package('typed', '1.0.0', summary);\n\n// src/files.ts\nexport default Files.manifest([upload]);",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-files:static:record-seed",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "Files",
+      "test": "A record seeded from a file: upload.record(name, type, spec, parts) is e3.record(name, type, parts) with no initial value, declared whole with its indexes, mutations and migrations, pending until its file arrives (its first state, $init), seeded again by a changed file while nothing has mutated it since ($seed) or on --reset, kept once mutated; the tasks over it wait meanwhile, and its history names the file",
+      "keywords": [
+        "Files",
+        "record",
+        "seed",
+        "seeded",
+        "upload.record",
+        "pending",
+        "$init",
+        "$seed",
+        "--reset",
+        "genesis",
+        "no initial value",
+        "e3.record",
+        "declared whole",
+        "mutations",
+        "kept",
+        "waiting",
         "e3-cloud-files"
       ],
       "imports": [
-        "import { East, ArrayType, DictType, FloatType, IntegerType, StringType, StructType } from '@elaraai/east';",
+        "import { East, DictType, IntegerType, StringType, StructType } from '@elaraai/east';",
         "import e3, { type Runner } from '@elaraai/e3';",
         "import { Files } from '@elaraai/e3-cloud-files';"
       ],
-      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nconst PriceBook = DictType(StringType, FloatType);\nexport const upload = Files.source('upload');\n// A beast2 file of Array<Price> (encodeBeast2For(ArrayType(Price)), east-py, e3 convert): an input of that type, taken in as the\n// value it holds, a collection of any size, its header checked first; a file of another type is refused naming both types\nexport const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });\nexport const stock = upload.latest('stock', { prefix: 'stock/', include: '*.beast2', type: ArrayType(Price) });   // the greatest key, typed\n// A record the app's users edit, and a mutation of one argument that loads a delivery into it\nexport const priceBook = e3.record('price_book', PriceBook, new Map());\nexport const loadPrices = e3.mutation.reduce('load_prices', priceBook, East.function([PriceBook, ArrayType(Price)], PriceBook, ($, state, rows) => {\n  const next = $.let(state.copy());   // the book as it is (a mutation's state is immutable), each delivered price over its sku's\n  $.for(rows, ($, row) => { $(next.insertOrUpdate(row.sku, row.price, (_$, _existing, delivered) => delivered)); });\n  return next;\n}));\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\nexport const summary = e3.task('price_summary', [prices, priceBook], East.function([ArrayType(Price), PriceBook], IntegerType, (_$, rows, book) => rows.size().add(book.size())), { runner });\nexport default e3.package('typed', '1.0.0', summary, loadPrices);\n\n// src/files.ts: each new delta file under deltas/ calls load_prices once with its value, by the file's hash; a refused file is\n// tried again only once it changes; a feed of a record with no state yet waits for it\nupload.mutation(loadPrices, { prefix: 'deltas/', include: '*.beast2' });\nexport default Files.manifest([upload]);",
+      "source": "// src/package.ts\nconst Customer = StructType({ name: StringType, tier: IntegerType });\nconst CustomerBook = DictType(StringType, Customer);\nexport const upload = Files.source('upload');\n// e3.record('customers', CustomerBook, parts) with no initial value: pending until customers.beast2 arrives, which is its first state ($init:\n// nothing runs on an empty state first, and the tasks over it wait as on an unset input, the run completing without them); a changed\n// file while nothing has mutated it since is its state again ($seed); once mutated it is kept, until `files sync --reset customers`\n// (or `files push --reset customers`) takes the file as its state over whatever was done. The workspace page shows it Pending, its page\n// what seeds it, `files status` prints pending; its history reads \"Initialised from customers.beast2 (2 rows)\" and \"Seeded again from …\"\n// Declared whole, as any record is: its indexes, mutations and migrations are the fourth argument, as e3.record takes them (an initial\n// value there is refused). Its mutations are any record's: after one, the file no longer seeds it until a reset\nexport const customers = upload.record('customers', CustomerBook, { key: 'customers.beast2' }, {\n  mutations: (mutation) => ({\n    set_tier: mutation.reduce(East.function([CustomerBook, StringType, IntegerType], CustomerBook, ($, state, key, tier) => {\n      const next = $.let(state.copy());\n      $(next.insertOrUpdate(key, { name: key, tier }, (_$, existing, _given) => ({ name: existing.name, tier })));\n      return next;\n    })),\n  }),\n});\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\nexport const customerCount = e3.task('customer_count', [customers], East.function([CustomerBook], IntegerType, (_$, book) => book.size()), { runner });\n// The record carries its mutation: the package takes the task over it\nexport default e3.package('typed', '1.0.0', customerCount);\n\n// src/files.ts\nexport default Files.manifest([upload]);\n\n// A deploy that cannot keep the record (its type changed) under --schema reset unassigns it: pending again, seeded by the next\n// version's file once the new declarations are deployed",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-files:static:mutation-feed",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "Files",
+      "test": "A record's mutation fed by files: upload.mutation(def, spec), def one the record declares (priceBook.mutations.load_prices), applies each new file the spec selects, in key order, once by its bytes' hash, as the mutation's one argument; a refused file is tried again only once it changes, a feed of a pending record waits, and each commit names its file",
+      "keywords": [
+        "Files",
+        "mutation",
+        "feed",
+        "fed",
+        "upload.mutation",
+        "mutation.reduce",
+        "mutations",
+        "one argument",
+        "idempotent",
+        "once per file",
+        "key order",
+        "refused",
+        "waiting",
+        "deltas",
+        "e3-cloud-files"
+      ],
+      "imports": [
+        "import { East, ArrayType, DictType, FloatType, StringType, StructType } from '@elaraai/east';",
+        "import e3 from '@elaraai/e3';",
+        "import { Files } from '@elaraai/e3-cloud-files';"
+      ],
+      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nconst PriceBook = DictType(StringType, FloatType);\nexport const upload = Files.source('upload');\n// A record the app's users edit, declared whole with a mutation of one argument that loads a delivery into it: the record's own\n// reduce (or edit; a patch cannot be fed), its rules deciding what a delivery does. A delivery holding a price below zero is refused\n// whole: the mutation fails, the book is kept, and the file is tried again only once it changes, the files after it waiting\nexport const priceBook = e3.record('price_book', PriceBook, {\n  initial: new Map(),\n  mutations: (mutation) => ({\n    load_prices: mutation.reduce(East.function([PriceBook, ArrayType(Price)], PriceBook, ($, state, rows) => {\n      const next = $.let(state.copy());   // the book as it is (a mutation's state is immutable), each delivered price over its sku's\n      $.for(rows, ($, row) => {\n        $.if(row.price.lessThan(0), ($) => $.error(East.str`a price below zero: ${row.sku}`));\n        $(next.insertOrUpdate(row.sku, row.price, (_$, _existing, delivered) => delivered));\n      });\n      return next;\n    })),\n  }),\n});\n// The record carries its mutation: the package takes the record\nexport default e3.package('typed', '1.0.0', priceBook);\n\n// src/files.ts: each new delta file under deltas/ calls load_prices once with its value, by the file's hash (a sync run again\n// applies nothing twice; the same bytes under another name are applied no more); a feed of a record with no state yet waits for\n// it; a sync seeds records before it feeds mutations. The commit reads in the record's history as any mutation's, through the\n// files channel, naming the file it was fed\nupload.mutation(priceBook.mutations.load_prices, { prefix: 'deltas/', include: '*.beast2' });\nexport default Files.manifest([upload]);",
       "languages": [
         "typescript"
       ]
@@ -909,7 +1006,10 @@
         "restore",
         "backup-pull",
         "commit",
-        "audit"
+        "audit",
+        "pending",
+        "$seed",
+        "seeded from a file"
       ],
       "imports": [],
       "source": "e3-cloud records list https://e3.example.com/repos/acme production\ne3-cloud records history https://e3.example.com/repos/acme production orders --limit 50\ne3-cloud records show https://e3.example.com/repos/acme production orders <commit> -o orders.beast2\ne3-cloud records backup https://e3.example.com/repos/acme production orders --note \"before the import\"\ne3-cloud records rollback https://e3.example.com/repos/acme production orders <commit>    # a new commit holding that state",
@@ -1109,6 +1209,45 @@
       "languages": [
         "typescript"
       ]
+    },
+    {
+      "skill": "e3-cloud-client",
+      "package": "e3-cloud-client",
+      "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",
+      "keywords": [
+        "getFiles",
+        "deployFiles",
+        "bindFilesSource",
+        "startFilesSync",
+        "filesSyncWait",
+        "planFilesPush",
+        "completeFilesPush",
+        "FilesTarget",
+        "targets",
+        "reset",
+        "pending",
+        "seeded",
+        "record",
+        "mutation",
+        "push",
+        "unchanged",
+        "refused",
+        "retaken",
+        "workspace_protected"
+      ],
+      "imports": [
+        "import { none, some, variant } from '@elaraai/east';",
+        "import { bindFilesSource, completeFilesPush, deployFiles, filesSyncWait, getFiles, planFilesPush, startFilesSync } 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}",
+      "languages": [
+        "typescript"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-cloud-codex-plugin",
-  "version": "1.0.97",
+  "version": "1.1.0",
   "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

@@ -163,9 +163,9 @@ e3 dataflow run URL staging
 
 ### 5. Migrate a record
 
-A record's new type comes with a migration in the package: e3's
-`e3.migration.value`, `rows` or `rekey`, each step naming the one before it
-with `after` (the e3 skill). Then, in staging:
+A record's new type comes with a migration in its own declaration: a step
+added at the end of its `migrations` (`migration.value`, `rows` or `rekey`,
+each named, the list's order the chain; the e3 skill). Then, in staging:
 
 ```bash
 e3-cloud records backup URL staging orders --note "before orders v2"
@@ -193,6 +193,8 @@ e3-cloud release URL staging production --plan
 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 sync   URL staging --target record:customers --reset customers     # named targets; a seeded record's file as its state again
 e3 dataflow run URL staging
 ```
 
@@ -317,8 +319,9 @@ e3-cloud app deploy URL staging --from-source src/apps/ops.tsx --for-platform 1.
 e3-cloud release URL staging production
 ```
 
-- Build with the next release's packages and stage the bundle beside the
-  live app: it goes live when the platform moves to that e3. A release
+- Build with the e3 cloud release built with the next e3 (its packages pin
+  it) and stage the bundle beside the live app: it goes live when the
+  platform moves to that e3. A release
   carries staging's staged bundles, so production gets them through its
   staging.
 
@@ -413,7 +416,7 @@ a repository URL:
   changes them, and a source may be bound before a release brings the
   declarations that read it.
 - `files sync <repo> <ws>` reads only files whose ETag or size changed and
-  writes only inputs whose files changed; `--input`, `--dry-run`. It doesn't
+  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 status <repo> <ws>`: the declarations, the bindings, the last sync.
 
@@ -431,5 +434,6 @@ a repository URL:
   hasn't bound: bind it in the target first.
 - `secrets set` reads the value from stdin unless `--value` is given; the
   next run reads the new value.
-- The version is the @elaraai lockstep: use the CLI of the release your
-  deployment runs.
+- 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).

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

@@ -67,10 +67,44 @@ try {
   and its `undoes` lists forced changes it undoes. `rollbackWorkspace` takes
   an entry of `workspaceHistory`.
 
+## Files
+
+- `getFiles(url, repo, ws, options)` answers a workspace's Files: its
+  declarations (`manifest`), where each source is bound (`bindings`), the
+  last sync, a sync under way, and `status` — per mapping, what it holds and
+  whether its record is `pending` (seeded from a file, its file not yet
+  arrived).
+- `deployFiles(url, repo, ws, manifest, options `{ dryRun?, force? }`)` deploys declarations
+  (`Files.manifest(...)` from `@elaraai/e3-cloud-files`): `deployed` with
+  the targets the next sync takes again whole (`retaken`), `checked` for a
+  dry run, or `refused` with every problem. A workspace with a staging
+  refuses it (`workspace_protected`) unless an admin forces it.
+- `bindFilesSource(url, repo, ws, binding, options)` says where a source's
+  files are (`s3://bucket/prefix/`): `bound` with what the next sync takes
+  again, or `refused` (a bucket the deployment does not let the repository
+  bind). Bindings are each workspace's own; a release never changes them.
+- `startFilesSync(url, repo, ws, { dryRun?, targets?, reset? }, options)`
+  answers `started` with the sync's id, or `running` with the one under way;
+  `filesSyncWait(url, repo, ws, id, options, { deadlineMs?, refresh?, signal? })`
+  polls it to its end and answers the job, its `report` per target (what was
+  taken, the commit a seed or feed made, what was refused and why, what
+  waits). `targets` are `variant('input', name)`, `variant('record', name)`
+  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.
+
 ## Traps
 
 - The URL is the deployment's origin, not `…/api`: the client adds the path.
 - A refusal of a release or an app deploy is an answer (`refused`), not a
   throw; a request the server cannot take at all throws `ApiError`.
-- The version is the @elaraai lockstep: use the client of the release the
-  deployment runs.
+- The version is e3 cloud's own, shared by every e3 cloud package and
+  independent of e3's: use the client of the e3 cloud release the deployment
+  runs, beside the east and e3 it pins.

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

@@ -5,7 +5,7 @@ description: "Files for e3 cloud — a solution's inputs that come from files in
 
 ## Detailed skill scope
 
-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), 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) Syncing or resetting particular targets with --target and --reset.
+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.
 
 # e3-cloud-files — files as e3 inputs
 
@@ -74,7 +74,8 @@ What do you need?
 │   ├─ A beast2 file as its value     → source.file(input, { key, type: ArrayType(Row) })  input: Array<Row>, no task between
 │   ├─ The newest of a folder         → source.latest(input, { prefix, include? })     input: Blob, the greatest key
 │   ├─ The newest, typed              → source.latest(input, { prefix, include?, type })
-│   ├─ Feed a record's mutation       → source.mutation(def, { key } | { prefix, include? })  each new file calls it once
+│   ├─ A record's first state         → source.record(name, type, { key } | { prefix, include? }, parts?)  e3.record(name, type, parts): pending until its file
+│   ├─ Feed a record's mutation       → source.mutation(record.mutations.<name>, { key } | { prefix, include? })  every new file, in key order, once
 │   ├─ Every file of a folder         → source.folder(input, { prefix, include? })     input: Dict<String, Blob> by path
 │   ├─ A folder's files, not bytes    → source.listing(input, { prefix, include? })    input: Dict<String, {size, modified, etag}>
 │   ├─ Subfolders' files too          → include: '**/*.csv' ('*.csv' is the top level only)
@@ -122,6 +123,9 @@ export const rates  = upload.file('rates', { key: 'rates.json' });
 export const stock  = upload.latest('stock', { prefix: 'stock/', include: '*.json' });    // input: Blob, the greatest key
 export const orders = upload.folder('orders', { prefix: 'orders/', include: '*.json' });  // input: Dict<String, Blob>
 export const orderFiles = upload.listing('order_files', { prefix: 'orders/' });           // input: each file's size, modified, etag
+export const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });      // input: Array<Price>: the beast2 file's value, any size
+export const customers = upload.record('customers', CustomerBook, { key: 'customers.beast2' });    // a record, e3.record('customers', CustomerBook): pending until its file
+upload.mutation(priceBook.mutations.load_prices, { prefix: 'deltas/', include: '*.beast2' });       // each new delta file fed to the record's mutation, in key order
 
 export default Files.manifest([upload]);       // what e3-cloud files deploy deploys
 ```
@@ -131,9 +135,22 @@ export default Files.manifest([upload]);       // what e3-cloud files deploy dep
   `file` or `latest` with a `type` is an input of that type: the file must be
   beast2 of it (`encodeBeast2For(T)`, east-py, `e3 convert`), a collection of
   any size, checked by its header before any other byte is read.
-- `source.mutation(def, spec)` feeds a record's mutation: `def` is the
-  package's `e3.mutation.reduce` or `edit` taking exactly one argument, and
-  each new file is applied once, by its hash.
+- `source.record(name, type, spec, parts?)` is `e3.record(name, type, parts)`
+  with no initial value. It is declared whole: its indexes, mutations and
+  migrations are `parts`, as `e3.record` takes them
+  (`{ mutations: (mutation) => ({ set_tier: mutation.reduce(fn) }) }`), and an
+  initial value is refused. It is pending until its file arrives, which is
+  its first state (`$init`; nothing runs on an empty state first, and the
+  tasks over it wait as on an unset input, the run completing without them).
+  A changed file while nothing has mutated it since is its state again
+  (`$seed`); mutated since, it is kept until `files sync --reset <record>`.
+- `source.mutation(def, spec)` feeds a record's mutation: `def` is one the
+  record declares, `record.mutations.<name>`, a `reduce` or an `edit` taking
+  exactly one argument. Every new file the spec selects (one key, or each
+  under the prefix its glob matches) is applied in key order, once by its
+  bytes' hash, so the same bytes under another name are applied no more; a
+  file the mutation refuses holds the ones after it until it changes; a busy
+  record leaves the file to the next sync.
 - Keys and prefixes are relative to where a workspace binds the source; a
   prefix is `''` or ends with `/`.
 - `include` is a glob over the path under the prefix: `*` within one folder,
@@ -172,7 +189,14 @@ name, a `latest` under its prefix, a directory to the `folder`; `--as` names
 one), checks its type and size, puts it where the source is bound (the
 platform signs the upload into the deployment's own bucket, bound to the
 file's SHA-256; your own credentials elsewhere), then syncs what was put. A
-file the source holds already is `unchanged`.
+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.
+
+`--target` names an input, `record:<name>` or `mutation:<record>.<name>`
+(split at its last dot); `--reset <record>` takes a seeded record's file as
+its state again, whatever mutated it since.
 
 `<repo>` is a local repository's path or a repository URL. Deploy the package
 first (`e3 workspace deploy`), then the declarations, which are checked
@@ -193,9 +217,20 @@ keeps only each folder's n greatest keys.
   (`type_mismatch` with both types, `not_beast2`): the input keeps its value.
   A typed value that is no collection is at most 1 GiB; a collection's
   segments at most 64 MiB (`segment_too_large`: write it again).
-- A seeded record (`upload.record`) waits for the e3 release that lets a
-  record be declared with no initial value; the rest of typed files, feeds
-  and push is here now.
+- A seeded record (`upload.record(name, type, { key })`) is pending until
+  its file, which is its first state (`$init`); a changed file seeds it
+  again while unmutated (`$seed`), `--reset` does whatever was done since;
+  the tasks over it wait meanwhile. The workspace page shows it Pending, its
+  page says what seeds it, `files status` prints `pending`; its seeds read
+  "Initialised from customers.beast2 (12,004 rows)" / "Seeded again from …"
+  in its history (the record page, `e3-cloud records history`), a feed names
+  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 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
+  there is refused, its file being its first state.
 - A file over 1 GiB less 64 KiB (`file`, `latest`), or over 64 MiB less
   64 KiB in a folder, is refused and named in the report, never truncated.
   So is a file the sync can't read (archived, under a key it may not use,
@@ -213,7 +248,9 @@ keeps only each folder's n greatest keys.
 - Bindings never travel with a release; a copy carries them. A staging
   started as a copy of production reads production's files until you bind it
   elsewhere.
-- The version is the @elaraai lockstep: use the same version as east and e3.
+- The version is e3 cloud's own, not e3's: install the release built with the
+  e3 the deployment runs, its peers (east, e3) at exactly the versions it
+  names, and the `e3-cloud` CLI of the same release.
 
 ## Related skills
 

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

@@ -64,7 +64,10 @@ const overview = Page('overview', { title: 'Overview', icon: 'gauge-high' },
 - The function's **one argument is the page's params** (or none). Never write
   the type separately: TypeScript takes it from the function.
 - Bind data exactly as a `ui()` body does: `Data.bind`, `Data.bindPaged`,
-  `Func.bind`, `Record.bind`. Pass the defs, never names.
+  `Func.bind`, `Record.bind`. Pass the defs, never a dataset's or a
+  function's name; a record's mutations and indexes are named as the record
+  declares them: `Record.bind(orders, ['approve'])`,
+  `Data.bindPaged(orders, { index: 'by_line' })`.
 - `meta.parent` makes the crumbs and lights the menu item.
 - Bind event handlers once: `const go = $.const(East.function([], NullType, $ => { $(Nav.go(line, key)); }))`.
 
@@ -103,6 +106,12 @@ on the workspace fits.
 - A body written without the thunk can only link to pages defined above it.
 - A page that writes a task's output or a record through `Data.bind` is
   refused: write inputs; change records through their mutations.
+- A record is declared whole: its indexes, mutations and migrations in its
+  own `e3.record(name, type, { initial, indexes, mutations, migrations })`.
+  `e3.package` takes the record, never one of its parts.
 - `Page.task` needs a task in the `ui` role (`ui()`), and its output shows only
   after the workspace's next dataflow run.
-- The version is the @elaraai lockstep: use the same version as east and e3.
+- The version is e3 cloud's own, not e3's: install the release built with the
+  e3 the deployment runs, its peers (east, east-ui, e3, e3-ui) at exactly the
+  versions it names. An app built with another e3 than the platform's is
+  refused, naming both.