@acsetra/runner 0.1.88 → 0.1.90

package/bin/runner.js

@@ -190,7 +190,7 @@ async function main() {
   const argv = process.argv.slice(2);
   if (!argv.length || ["-h", "--help"].includes(argv[0])) { console.log(renderTop()); return 0; }
   const [cmd, ...rest] = argv;
-  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.88"); return 0; }
+  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.90"); return 0; }
 
   // help — top-level, `help <topic>`, and per-verb `<cmd> … --help` (lexical, before toOp)
   if (cmd === "help") {

package/lib/grammar.json

@@ -7,18 +7,25 @@
     "config_schema",
     "decls",
     "input",
+    "items",
     "meta",
     "overrides",
     "parts",
+    "patches",
     "props",
+    "replace_meta",
+    "requires",
     "schema",
     "spec",
     "storage",
+    "targets",
+    "tests",
     "tree"
   ],
   "int_args": [
     "at",
     "days",
+    "limit",
     "max_bytes",
     "ordinal",
     "rate",
@@ -30,11 +37,16 @@
     "backoff"
   ],
   "bool_args": [
+    "all_routes",
+    "atomic",
     "auth_flow",
     "autoplay",
     "controls",
+    "disabled",
     "enabled",
     "force",
+    "if_absent",
+    "include_deleted",
     "keep",
     "map",
     "muted",
@@ -53,7 +65,9 @@
     "component.set": "tree",
     "component.set_route": "props",
     "behavior.attach": "config",
-    "head.set": "attrs"
+    "head.set": "attrs",
+    "record.transact": "targets",
+    "record.commit": "patches"
   },
   "pos": {
     "set.create": [
@@ -191,6 +205,44 @@
     ],
     "head.remove": [
       "code"
+    ],
+    "record.get": [
+      "set_code",
+      "code"
+    ],
+    "record.commit": [
+      "set_code",
+      "code"
+    ],
+    "record.transact": [
+      "operation_id"
+    ],
+    "record.replay": [
+      "operation_namespace",
+      "operation_id"
+    ],
+    "schedule.set": [
+      "code",
+      "pipeline",
+      "cron"
+    ],
+    "schedule.show": [
+      "code"
+    ],
+    "schedule.occurrences": [
+      "code"
+    ],
+    "schedule.pause": [
+      "code"
+    ],
+    "schedule.resume": [
+      "code"
+    ],
+    "schedule.run_now": [
+      "code"
+    ],
+    "schedule.remove": [
+      "code"
     ]
   },
   "planes": [
@@ -199,6 +251,8 @@
     "component",
     "css",
     "head",
+    "record",
+    "schedule",
     "set"
   ],
   "short": {
@@ -484,6 +538,58 @@
         "validate",
         "head.validate"
       ]
+    ],
+    "record": [
+      [
+        "get",
+        "record.get"
+      ],
+      [
+        "commit",
+        "record.commit"
+      ],
+      [
+        "transact",
+        "record.transact"
+      ],
+      [
+        "replay",
+        "record.replay"
+      ]
+    ],
+    "schedule": [
+      [
+        "set",
+        "schedule.set"
+      ],
+      [
+        "list",
+        "schedule.list"
+      ],
+      [
+        "show",
+        "schedule.show"
+      ],
+      [
+        "occurrences",
+        "schedule.occurrences"
+      ],
+      [
+        "pause",
+        "schedule.pause"
+      ],
+      [
+        "resume",
+        "schedule.resume"
+      ],
+      [
+        "run_now",
+        "schedule.run_now"
+      ],
+      [
+        "remove",
+        "schedule.remove"
+      ]
     ]
   },
   "group_aliases": {
@@ -494,7 +600,7 @@
   },
   "ops_doc": {
     "set.create": {
-      "desc": "create a value set (mint your own plane/registry)",
+      "desc": "create a value set (mint your own plane/registry) — born a keyed record set: point reads, field patches, revisions/etags, durable receipts; never the legacy whole-collection path",
       "kw": [
         "label",
         "kind",
@@ -502,12 +608,13 @@
       ]
     },
     "set.put": {
-      "desc": "write/merge a row (--json is the row meta; MERGES unless --replace)",
+      "desc": "write/merge a row (--json is the row meta). Every set you mint is a keyed record set: each sent key lands as ONE atomic field patch (disjoint edits compose, a stale edit of a changed field conflicts); MERGES unless --replace; --etag makes the write conditional",
       "kw": [
         "label",
         "ordinal",
         "enabled",
-        "replace"
+        "replace",
+        "etag"
       ]
     },
     "set.declare_schema": {
@@ -853,6 +960,91 @@
     "head.validate": {
       "desc": "re-check every head entry",
       "kw": []
+    },
+    "record.get": {
+      "desc": "ONE row by code with its record_id / revision / etag (the keyed point read)",
+      "kw": [
+        "include_deleted"
+      ]
+    },
+    "record.commit": {
+      "desc": "atomic commit on one record (--json is the patches list: [{op:set|unset|increment|add_unique|remove_value|test, path:'/field', value}]); action create|patch|replace|delete|restore; expected_etag makes it conditional; items=[…] is a one-row batch with per-item outcomes",
+      "kw": [
+        "action",
+        "tests",
+        "items",
+        "batch_policy",
+        "expected_etag",
+        "expected_revision",
+        "operation_id",
+        "label",
+        "ordinal",
+        "replace_meta",
+        "if_absent"
+      ]
+    },
+    "record.transact": {
+      "desc": "several records, ONE operation: <operation_id> names it (a uuid you mint; retry = replay), --json is the targets list [{set_code, code, action?, patches?|items?, expected_etag?, requires?:[{target, item_id?}]}]; --atomic is all-or-none, else one outcome per target",
+      "kw": [
+        "atomic"
+      ]
+    },
+    "record.replay": {
+      "desc": "the stored terminal result of an operation (namespace + id)",
+      "kw": []
+    },
+    "schedule.set": {
+      "desc": "create/update an org-catalog five-field cron schedule for the explicit target scope",
+      "scope": "required",
+      "kw": [
+        "label",
+        "timezone",
+        "input",
+        "overlap",
+        "misfire",
+        "disabled"
+      ]
+    },
+    "schedule.list": {
+      "desc": "list schedules for this target; --all-routes lists the org catalog",
+      "scope": "required",
+      "kw": [
+        "all_routes"
+      ]
+    },
+    "schedule.show": {
+      "desc": "show one target-addressed schedule",
+      "scope": "required",
+      "kw": []
+    },
+    "schedule.occurrences": {
+      "desc": "list durable occurrence and launch receipts, newest first",
+      "scope": "required",
+      "kw": [
+        "limit"
+      ]
+    },
+    "schedule.pause": {
+      "desc": "pause one schedule and clear its next firing",
+      "scope": "required",
+      "kw": []
+    },
+    "schedule.resume": {
+      "desc": "revalidate and resume one schedule, rebinding its routed pipeline when detached",
+      "scope": "required",
+      "kw": []
+    },
+    "schedule.run_now": {
+      "desc": "enqueue once without moving the cron clock; --operation-id makes retries idempotent",
+      "scope": "required",
+      "kw": [
+        "operation_id"
+      ]
+    },
+    "schedule.remove": {
+      "desc": "delete one schedule and its occurrence history",
+      "scope": "required",
+      "kw": []
     }
   },
   "verbs_doc": {
@@ -949,8 +1141,8 @@
       "desc": "reconstruct a pipeline from its rows"
     },
     "run": {
-      "usage": "run <pipeline> -i '{json}'",
-      "desc": "test-run a pipeline with input"
+      "usage": "run <pipeline> [-i '{json}'] [--at scope | -S scope]",
+      "desc": "test-run a pipeline; --at/-S deterministically selects the deepest ancestor route, while an unscoped run selects the globally deepest route and errors on a deepest tie"
     },
     "runs": {
       "usage": "runs <launch_id>",
@@ -990,7 +1182,10 @@
         "  llm       [--provider openai] [--model M]   one model call (keys injected server-side)",
         "            [--system-from K] [--user-from ask] [-k/--keys a,b]",
         "  pipeline  -P/--calls CODE|SCOPE/CODE        run an EXISTING pipeline of this org as this step",
-        "            (a real child launch; -s '{\"pick\":[\u2026],\"input\":{\u2026}}' shapes its input)"
+        "            (a real child launch; -s '{\"pick\":[…],\"input\":{…}}' shapes its input)",
+        "  batch     -s '{\"over\":\"items\",\"each\":{\"tier\":…,\"spec\":{…}},\"concurrency\":8}'",
+        "            ONE run fans a sub-worker over a list: bounded (default 8, max 32), one item's",
+        "            failure is its own {error,index}, the answer counts ok/failed — never loop ctx.run"
       ]
     },
     "op": {
@@ -1026,7 +1221,9 @@
     },
     "backend": {
       "groups": [
-        "set"
+        "set",
+        "record",
+        "schedule"
       ],
       "verbs": [
         "signin",

package/lib/grammar_info.js

@@ -2,7 +2,7 @@
 // Node mirror of acsetra_cli/grammar_info.py: reads the INSTALLED manifest
 // (lib/grammar.json), renders one JSON payload with every operation's positional
 // order, the named argument a bare `--json` fills, `-b` bodies, flag coercion
-// types, and short aliases. grammar_version is the sha256 of the manifest bytes
+// types, scope requirement, and short aliases. grammar_version is the sha256 of the manifest bytes
 // — the same hash the server's context pack reports.
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -33,6 +33,7 @@ function opEntry(op) {
     pos: [...(GRAMMAR.pos[op] || [])],
     json: op in GRAMMAR.primary_json ? GRAMMAR.primary_json[op] : null,
     body: Boolean(doc.body),
+    scope: doc.scope || "optional",
     flags: Object.fromEntries(kw.map(k => [k, vtype(k)])),
     short: Object.fromEntries(kw.filter(k => k in rev)
       .map(k => ["-" + rev[k], "--" + k.replace(/_/g, "-")])),

package/lib/help.js

@@ -54,7 +54,7 @@ export function renderOp(op) {
   if (prim) parts.push(`--json '{${prim}}'`);
   if (body) parts.push("-b <code|->");
   for (const k of kw) parts.push(usageFlag(k));
-  parts.push("[-S scope]");
+  parts.push(doc.scope === "required" ? "-S <scope>" : "[-S scope]");
 
   const out = ["Usage:", "  " + parts.join(" "), ""];
   if (doc.desc) out.push(doc.desc, "");
@@ -115,7 +115,7 @@ export function renderTop() {
   out.push("Authoring (planes — run `r <group> --help` for subcommands)",
            "  r app create <name> ; r apps",
            "  r auth <app>           require home.acsetra.com sign-in to use an app",
-           "  r set | css | asset | behavior | component | head  <subverb> …",
+           "  r set | css | asset | behavior | component | head | schedule  <subverb> …",
            "  r pipe <code> -S <scope> -w c:l ; r w <code> <tier> …",
            "  r ls | inspect <set> | read <code> | show <pipe>",
            "  r run <pipe> -i '{…}' ; r runs <id> ; r doctor <app> ; r compile <app>",

package/lib/verbs.js

@@ -45,7 +45,9 @@ function walk(rest) {
     if (tok === "--json") {
       const blob = rest[++i]; i++;
       const obj = blob.startsWith("@") ? JSON.parse(fs.readFileSync(blob.slice(1), "utf8")) : JSON.parse(blob);
-      flags.__json = Object.assign(flags.__json || {}, obj); continue;
+      if (!Array.isArray(obj) && flags.__json && !Array.isArray(flags.__json)) Object.assign(flags.__json, obj);
+      else flags.__json = obj;   // an object, or a LIST primary (patches / targets)
+      continue;
     }
     if (tok.startsWith("--") || (tok.startsWith("-") && tok.length === 2 && !/\d/.test(tok[1]))) {
       let name = tok.replace(/^-+/, "").replace(/-/g, "_");
@@ -75,7 +77,8 @@ function assemble(op, positionals, flags) {
     const blob = flags.__json; delete flags.__json;
     const prim = PRIMARY_JSON[op];
     if (prim && !(prim in args)) args[prim] = blob;
-    else Object.assign(args, blob);
+    else if (!Array.isArray(blob)) Object.assign(args, blob);
+    else throw new VerbError(`\`${op}\` takes --json as an object of named args (a list is only the primary payload of ops like record.commit / record.transact)`);
   }
   delete flags.__body;
   for (const [k, v] of Object.entries(flags)) args[k] = coerce(k, v);
@@ -123,6 +126,12 @@ export function toOp(verb, rest) {
     const { positionals, flags } = walk(rest);
     const args = { pipeline: positionals[0] || flags.pipeline };
     if ("input" in flags) args.input = coerce("input", flags.input);
+    if (flags.scope !== undefined && flags.at !== undefined && flags.scope !== flags.at) {
+      throw new VerbError("run received different --at and -S/--scope values");
+    }
+    if (flags.scope !== undefined || flags.at !== undefined) {
+      args.scope = flags.scope !== undefined ? flags.scope : flags.at;
+    }
     return ["run", args];
   }
   if (verb === "runs") { const { positionals } = walk(rest); return ["runs", { launch: positionals[0] }]; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acsetra/runner",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "description": "Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).",
   "keywords": ["runner", "acsetra", "cli", "agent", "low-code"],
   "license": "MIT",