@xanots/sdk 0.0.5 → 0.0.7

package/dist/internal.js

@@ -33,7 +33,7 @@ import {
   taskKind,
   toolKind,
   workflowTestKind
-} from "./chunk-FN4OQT2J.js";
+} from "./chunk-JUHKEAHJ.js";
 import {
   GENERATED_SPECS,
   GENERATED_STATEMENT_NAMES,
@@ -55,14 +55,15 @@ import {
   registerSpec,
   triggerKind,
   workspaceKind
-} from "./chunk-CYJ7R3AD.js";
+} from "./chunk-2V3JUXTF.js";
 import {
   COMMANDS,
   FLAGS,
   GLOBAL_FLAGS,
   flagKey,
-  flagSummary
-} from "./chunk-F5T45NAM.js";
+  flagSummary,
+  visibleFlags
+} from "./chunk-OKNSR7MT.js";
 import {
   DECODE_ONLY_STATEMENTS,
   FILTER_NAMES,
@@ -108,7 +109,7 @@ import {
   serializeBundle,
   tableKind,
   toNestedFields
-} from "./chunk-YUPQOLFX.js";
+} from "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import {
   encodeStatement,
@@ -136,7 +137,7 @@ import {
   resolveRef,
   serializeLock,
   validateLockModel
-} from "./chunk-YUBJLB6G.js";
+} from "./chunk-7JDT4PBU.js";
 
 // src/statements/byte-evidence.ts
 var UNCONFIRMED_STATEMENTS = /* @__PURE__ */ new Set([]);
@@ -167,15 +168,15 @@ function buildCli() {
       out.push({
         command: name,
         ...argGrammar(spec.args) !== void 0 ? { args: argGrammar(spec.args) } : {},
-        ...flagsOf(spec.flags) !== void 0 ? { flags: flagsOf(spec.flags) } : {},
+        ...flagsOf(visibleFlags(spec)) !== void 0 ? { flags: flagsOf(visibleFlags(spec)) } : {},
         description
       });
       continue;
     }
     for (const [subName, sub] of subs) {
-      if (sub.removed !== void 0) continue;
+      if (sub.removed !== void 0 || sub.unreleased !== void 0) continue;
       const args = argGrammar(sub.args ?? spec.args);
-      const flags = flagsOf(sub.flags ?? spec.flags);
+      const flags = flagsOf(sub.flags !== void 0 ? visibleFlags(sub) : visibleFlags(spec));
       out.push({
         command: `${name} ${subName}`,
         ...args !== void 0 ? { args } : {},
@@ -218,7 +219,7 @@ var KIND_DESCRIPTORS = [
   { kind: "realtime_server", payloadKey: "realtime_server", authorFactory: "realtimeServer", description: "A realtime (websocket) server: the canonical-addressed container that owns realtime channels. Off until `enabled: true`. Returns a handle with `getUrl(baseUrl)`/`getPath()` for the client's socket URL (`wss://<host>/ws/<canonical>`).", registerMethod: "registerRealtimeServers" },
   { kind: "channel", payloadKey: "channel", authorFactory: "realtimeChannel", description: "A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.", registerMethod: "registerRealtimeChannels" },
   { kind: "message", payloadKey: "message", authorFactory: "realtimeMessage", description: "A realtime message handler: a named message type on a channel with its own typed payload and stack \u2014 the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.", registerMethod: "registerRealtimeMessages" },
-  { kind: "microservice", payloadKey: "microservice", authorFactory: "microservice", description: "A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` \u2014 passing both throws. EARLY SURFACE, expected to change \u2014 every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form \u2014 they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG \u2014 `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material \u2014 keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env(\"NAME\")`.", registerMethod: "registerMicroservices" },
+  { kind: "microservice", payloadKey: "microservice", authorFactory: "microservice", description: "A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.", registerMethod: "registerMicroservices" },
   {
     kind: "knowledge",
     payloadKey: "knowledge",
@@ -786,9 +787,18 @@ function renderSections(m) {
   lines.push(`# ${m.name} v${m.version}`, "");
   lines.push(`> ${m.description}`, "");
   lines.push(
-    "Author a Xano workspace in TypeScript: build typed objects, register them on a",
-    "`new Xano()` instance, and call `.export()` to get one importable bundle. Compile",
-    "with `xanots export ./xano/index.js`.",
+    "Xano is a hosted backend platform: one WORKSPACE serves a managed PostgreSQL",
+    "database, HTTP API endpoints, background tasks, realtime websocket channels, AI",
+    "agents and MCP servers, file storage, and redis. This SDK authors that workspace in",
+    "TypeScript \u2014 typed def objects registered on a `workspace(name)` \u2014 compiled to one",
+    "importable bundle by `xanots export ./xano/index.ts`, shipped live by `xanots deploy`.",
+    "",
+    "Def modules execute at BUILD time only: `s.*` factories return data, and the engine",
+    "runs the compiled stack per request \u2014 statements in order, a statement's `as:`",
+    "naming a runtime variable, `response` the HTTP body. Every dynamic operand is a",
+    'TAGGED value \u2014 `ref("x")` a stack variable, `inp("x")` an input, `auth("id")` the',
+    "caller, `c.*` a constant \u2014 resolved at request time; JS operators over them do not",
+    "compute (see Gotchas). Requests share no memory \u2014 state persists in tables or redis.",
     "",
     `Coverage: object kinds ${m.coverage.objectKinds.implemented}/${m.coverage.objectKinds.total}, statement surfaces ${m.coverage.statements.implemented}/${m.coverage.statements.total}, filters ${m.coverage.filters.total} (${m.coverage.filters.typed} typed).`,
     // The shortfall by name: an agent that cannot see WHICH kinds are missing
@@ -801,7 +811,7 @@ function renderSections(m) {
     "exhaustive per-entry detail in NEITHER \u2014 a statement's full field schema with engine",
     "defaults, a filter's complete argument list, the engine `storedName` mapping \u2014 do a",
     "TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;",
-    "it is ~55k tokens, so never read it whole). Its top-level keys are `" + Object.keys(m).join("`, `") + "`. `statements` and `filters` are ARRAYS, not maps \u2014 SELECT, do not index:",
+    "it is ~65k tokens, so never read it whole). Its top-level keys are `" + Object.keys(m).join("`, `") + "`. `statements` and `filters` are ARRAYS, not maps \u2014 SELECT, do not index:",
     `  jq '.statements[] | select(.sPath=="db.get")' manifest.json`,
     `  jq '.filters[]    | select(.name=="json_decode")' manifest.json`,
     `Select a statement on \`sPath\` (the \`s.*\` path you write), NOT \`surface\` (the XanoScript term): ${m.statements.filter((s) => s.surface !== s.sPath).length} of ${m.statements.length} differ \u2014 \`var\`\u2192\`set_var\`, \`break\`\u2192\`foreach_break\`, \`foreach.remove\`\u2192\`foreach_remove\`, and every \`expect.*\`.`,
@@ -880,26 +890,18 @@ function renderSections(m) {
     "pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):",
     "every warning becomes a hard failure. Same bundle bytes either way.",
     "",
-    "Identity: object guids derive from `(type, name)`, so renames change identity.",
-    "`xanots export <entry> --lock` freezes every guid + api-group/toolset canonical in a lock",
-    "file written BESIDE THE ENTRY FILE \u2014 `xano/xano.lock` for the standard scaffold, NOT the",
-    "project root \u2014 which you commit (auto-read once present; CI guard `--frozen-lock` fails",
-    "instead of changing the lock). Fix-up subcommands:",
-    "`xanots lock rename <kind> <old> <new>` (kind = payloadKey or table/api_group),",
-    "`xanots lock prune <entry-file> [keys\u2026] --yes` \u2014 finding orphans RUNS the entry's module scope",
-    "(env assertions included); `--no-verify --yes <kind:name>\u2026` prunes named keys with no evaluation",
-    "and no orphan check,",
-    "`xanots lock adopt <live-bundle.json> [--yes]` \u2014 all accept `--lock=<path>`.",
-    "Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing",
-    "any def module \u2014 references bake guids at import time, so late seeding is a",
-    "silent no-op (`resetLockOverrides` exists for tests).",
-    "Development workflow: opt in EARLY \u2014 run `xanots export ./xano/index.ts --lock` once and COMMIT",
-    "`xano.lock` beside the entry file; every later export then keeps identities",
-    "stable across renames and environments. To rename an object: rename in code,",
-    "export (stderr prints the exact fix-up), run `xanots lock rename <kind> <old>",
-    "<new>`, export again \u2014 the original guid is emitted under the new name, so the",
-    "engine renames in place instead of delete+create. Taking over an existing",
-    "workspace: `xanots lock adopt <its-packageExport.json>` first, then export.",
+    "Identity: object guids derive from `(type, name)` \u2014 a query's from `(api group,",
+    "verb, name)` \u2014 so renames change identity.",
+    "Opt in EARLY: `xanots export ./xano/index.ts --lock` freezes every guid +",
+    "api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE \u2014",
+    "`xano/xano.lock` for the standard scaffold, NOT the project root \u2014 which you COMMIT",
+    "(auto-read once present; CI guard `--frozen-lock` fails instead of changing it).",
+    "To rename an object: rename in code, export (stderr prints the exact fix-up), run",
+    "`xanots lock rename <kind> <old> <new>`, export again \u2014 the original guid is emitted",
+    "under the new name, so the engine renames in place instead of delete+create. Taking",
+    "over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then",
+    "export. Pruning, programmatic seeding, and which commands write the lock:",
+    "`llms/lock.md`.",
     "",
     "## Deploy",
     "",
@@ -930,14 +932,6 @@ function renderSections(m) {
     "  (previewed against live). `--prune` deletes only what `xano.lock` records this",
     "  project released, and refuses without a lock.",
     "",
-    "Nothing from a DEPLOY is written back into `xano.lock` (an ephemeral/sandbox is a",
-    "separate workspace, so its identities must not pollute yours). The one write-back is",
-    "`release --replace`, which mints fresh identities in the workspace the lock describes:",
-    "it re-pins the lock from the rebuilt workspace, because otherwise the next release",
-    "matches nothing and duplicates every object. Deploying an ENTRY",
-    "FILE still updates the local lock via the shared compile step, exactly as `export`",
-    "does \u2014 only when a lock exists or `--lock` is passed.",
-    "",
     "**Frontend wiring.** `--static <dir>` injects the DEPLOYED env's backend URL as",
     "`window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,",
     "so the frontend needs no rebuild to target an env. Every document, not just the root:",
@@ -987,6 +981,12 @@ function renderSections(m) {
     "- **Reference-helper picker:** `ref` = stack var (`as:` output), `inp` = input,",
     '  `col` = table column (in `db.query` `where`), `auth("id")` = the caller,',
     "  `c.*` = a constant. Pick by what you're pointing at.",
+    "- **Tagged values are DATA \u2014 a JS template literal cannot compose them.** `${ref(...)}`",
+    '  (or `"a" + ref(...)`) stringifies the tag object at BUILD time: ``c.text(`Hi ${ref("u.name")}`)``',
+    "  type-checks and encodes the literal text `Hi [object Object]`, served verbatim.",
+    "  `export()` warns; `--strict` fails. Compose at RUNTIME:",
+    '  `withFilters(c.text("Hi "), fl.concat(ref("u.name")))`, an `obj({...})`/record member,',
+    "  or `c.expression('\"Hi, \" ~ $var.u.name')`.",
     "- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are",
     "  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach",
     "  the target, so one in a query/function/task deploys clean and then answers the first",
@@ -1067,15 +1067,16 @@ function renderSections(m) {
     "- **Self-referencing tables** need the bare-name form: inside `tweets`'s own",
     '  schema, write `f.tableRef("tweets", { type: "int" })` \u2014 the `const tweets`',
     `  handle isn't assigned yet, so the handle form throws "used before declaration".`,
-    "- **Same-name siblings collide.** Object guids derive from `(type, name)` and",
-    "  ignore a query's `verb`, so a `GET` and `POST` both named `posts` clash;",
-    "  `export()` throws on the collision \u2014 give them DISTINCT names (`posts` and",
-    "  `posts/create`; the verb still carries the semantics). A distinct explicit",
-    "  `guid` on each clears that throw but is NOT a lasting fix: a lock entry is",
-    "  keyed by `(type, name)` too and cannot hold two guids, so `export --lock`",
-    "  refuses the pair \u2014 and a committed lock is the recommended workflow.",
-    "  `export()` warns on a same-name pair even unlocked. An explicit `guid` is",
-    "  for pinning identity across a rename, not for sharing a name.",
+    "- **Same-name siblings collide \u2014 queries excepted: their identity carries group + verb.**",
+    "  Guids derive from `(type, name)`, so two functions (or tables, toolsets, \u2026) sharing",
+    "  a name derive ONE guid and `export()` throws \u2014 give them DISTINCT names. A QUERY",
+    "  derives from `(api group, verb, name)`, the engine's own uniqueness: `GET items` +",
+    "  `POST items`, and `items` across two groups, coexist, and the lock keys the same",
+    "  composed identity (`query:blog|GET|items`) \u2014 changing a query's verb or group",
+    "  changes its identity. An explicit `guid` on a colliding pair clears the throw but",
+    "  is NOT a lasting fix: a lock entry cannot hold two guids, so `export --lock`",
+    "  refuses the pair (`export()` warns even unlocked); it is for pinning identity",
+    "  across a rename, not for sharing a name.",
     "- **`export()` vs `emitBundle()` vs `writeBundle()`:** `writeBundle(app, path)`",
     "  writes it to disk; `export()` returns the bundle object;",
     "  `emitBundle()` returns the pretty JSON string. All three run the SAME build-time",
@@ -1242,7 +1243,8 @@ function renderSections(m) {
     "The def-object passed to each factory. `?` = optional. `input` is keyed by",
     "input name (`input.<type>(opts?)`); `stack` is `Statement[]` (`s.*`); `response`",
     "is a `ResponseDef` (see **Responses** below). Object identity is `guid?` \u2014",
-    "omit it and it derives from `name` (set it to survive a rename).",
+    "omit it and it derives from `name` (for a query, from group + verb + name; set it",
+    "to survive a rename).",
     "",
     "- `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`",
     "- `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })`",
@@ -1497,6 +1499,14 @@ function renderSections(m) {
     "`input.list(element)` for arrays \u2014 wrap any element constructor, e.g.",
     "`input.list(input.text())` or `input.list(input.object({ id: f.int() }))`. Prefer the",
     "typed forms over `input.json()` when the shape is known.",
+    "**A file reaches a column in two steps.** `input.file` is the RAW upload (the request's",
+    "multipart/base64 bytes) and cannot be written to a file column directly: store it first \u2014",
+    '`s.storage.create_image({ as: "img", value: ref("input.avatar"), access: "public" })`',
+    '(the request input bag is read as a dotted `ref("input.<name>")` here) \u2014 then write',
+    '`ref("img")` into the `f.image()` cell with `s.db.add`/`edit`. `access` defaults to',
+    '`"public"` (a guessable URL): pass `"private"` and hand out `s.storage.sign_private_url`',
+    "results for anything user-scoped. `create_video`/`create_audio`/`create_attachment` are",
+    "the same shape for the other file columns.",
     "**Typed inputs validate/coerce on bind, before your stack runs** \u2014 so reach for the",
     "specific type instead of hand-rolling checks. `input.email({ required: true })` rejects a",
     'malformed address with a 400 (and trims; add `methods: ["lower"]` to downcase) \u2014 no',
@@ -1644,7 +1654,8 @@ function renderSections(m) {
     "- `s.db.del({ table, fieldName?, fieldValue, as? })` \u2014 delete by field match.",
     "- `s.db.add({ table, row?, data?, output?, as? })` \u2014 insert; `row` is a partial keyed by column.",
     '  - A row CELL takes a tagged `Value`, a nested object of sub-keys, or a bare JS literal typed against that column: `row: { is_hidden: true, notes: "\u2026" }` encodes exactly as `{ is_hidden: c.bool(true), notes: c.text("\u2026") }`. The tag comes from the COLUMN, not the literal \u2014 `10` on an `f.decimal()` column is `const:decimal`, not `const:int` \u2014 so a literal contradicting its column is a compile error on a `f.*`-schema table (`{ is_hidden: "yes" }` on an `f.bool()` column) and throws at encode on a raw-`ColumnDef[]` one. An `f.enum()` column keeps its member union. A column with no literal form \u2014 obj/json/list/geo/vector/file \u2014 still needs `c.obj`/`c.array`.',
-    "  - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` \u2014 a write OF null, not the same as omitting the key (omitted takes the column's type default on `add`: `[]` for a list, `{}` for obj/json, else `null`; on `edit` it is left untouched). A column's `nullable` is not consulted; the engine refuses a null it forbids.",
+    "  - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` \u2014 a write OF null, not the same as omitting the key. A column's `nullable` is not consulted at encode; the engine refuses a null it forbids.",
+    "  - Omitting a key on `add` writes the column's type default \u2014 declared `default` if set, `[]` for a list, `{}` for obj/json, else `null`. That `null` is EMITTED, not what the row holds: the engine applies the column's nullability, so a `nullable` column keeps `null` and a non-nullable one lands on its type's zero value (`\"\"`, `0`, `false`). Set the cell when the stored value matters. On `edit` an omitted key keeps its stored value.",
     "  - An `f.password()` cell takes the PLAINTEXT \u2014 the column hashes on write, so a pre-hashed value, or a hashing filter on the cell, stores a hash of a hash that `security.check_password` can never match.",
     "- `s.db.edit({ table, fieldName?, fieldValue, row?, data?, output?, as? })` \u2014 update by field match.",
     "- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` \u2014 merge a partial (`data` is an object value).",
@@ -1733,24 +1744,64 @@ function renderSections(m) {
     '- **Workspace environment variables** set a tenant\'s env vars through the workspace object: `workspaceConfig({ env: { STRIPE_KEY: process.env.STRIPE_KEY!, APP_BASE_URL: "https://\u2026" } })`. Author them as a name\u2192value MAP. Read a var back with `env("NAME")` (\u2192 `$env.NAME`), which compiles to tag "setting" with the plain name. Values are SECRETS: prefer sourcing from `process.env` over committing literals, and don\'t commit a compiled bundle with real values. `deploy` REPLACES the tenant\'s env with the declared map; `release` (merge) is ADD-ONLY \u2014 it creates missing keys but does NOT update or remove existing ones, so changing a value in code and releasing leaves the live value unchanged. Omit `env` to leave existing env untouched. The separate `settings` field is a plain object.',
     ""
   ];
+  const lock = [
+    "## Lock file",
+    "",
+    "`xano.lock` pins each object's guid and each api-group/toolset canonical, so renames",
+    "stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,",
+    "verb, name)`). Created by `xanots export <entry> --lock`, auto-read once present,",
+    "committed. A query's entry is keyed by that composed identity \u2014",
+    "`query:<group>|<verb>|<name>` \u2014 the same seed its guid derives from; a legacy",
+    "`query:<name>` entry keeps pinning and is migrated by the next locked export (the",
+    "old key drops automatically once its guid re-lands under the composed one).",
+    "",
+    "- `xanots lock rename <kind> <old> <new>` \u2014 `kind` is the payload key (or `table`/`api_group`).",
+    "  Run it after renaming in code; the next export emits the original guid under the new name.",
+    "- `xanots lock prune <entry-file> [keys\u2026] --yes` \u2014 drops orphaned entries. Finding orphans",
+    "  RUNS the entry's module scope (env assertions included); `--no-verify --yes <kind:name>\u2026`",
+    "  prunes named keys with no evaluation and no orphan check.",
+    "- `xanots lock adopt <live-bundle.json> [--yes]` \u2014 seed the lock from an engine",
+    "  packageExport when taking over an existing workspace.",
+    "- Every lock subcommand accepts `--lock=<path>`. `rename`/`adopt` take no entry file, so",
+    "  from outside the lock's directory pass `--lock` (or `--entry=<entry-file>` to derive it).",
+    "- Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def",
+    "  module \u2014 references bake guids at import time, so late seeding is a silent no-op",
+    "  (`resetLockOverrides` exists for tests).",
+    "",
+    "What writes the lock: `export`/`deploy` of an ENTRY FILE update it via the shared compile",
+    "step \u2014 only when a lock exists or `--lock` is passed. Nothing from a DEPLOY is written",
+    "back beyond that (an ephemeral/sandbox is a separate workspace, so its identities must",
+    "not pollute yours). The one write-back is `release --replace`, which mints fresh",
+    "identities in the workspace the lock describes: it re-pins the lock from the rebuilt",
+    "workspace, because otherwise the next release matches nothing and duplicates every",
+    "object. CI: `--frozen-lock` fails instead of changing the lock.",
+    ""
+  ];
   const stmtCalls = [
     "Auth & calls:",
     "",
     "- `s.security.create_auth_token({ table, id, extras?, expiration?, as? })` \u2014 `extras` defaults to `{}`, `expiration` to `86400`s (`0` = never).",
+    '- **Marketplace first:** `@xanots/auth` registers a complete auth surface \u2014 signup/login/me endpoints plus their `user`/`account`/`event_log` tables \u2014 via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `xanots marketplace details @xanots/auth --prompt`.',
+    "- **The auth loop end to end** \u2014 what that module implements; author it directly for a custom flow. An auth TABLE (`table({ auth: true })`) backs identity; a PUBLIC login query verifies and mints a token; every protected query names that table as `auth:` and reads the caller with `auth(...)`.",
+    '  - Signup: `s.db.add({ table: users, row: { email: inp("email"), password: inp("password") } })` \u2014 the `f.password()` column hashes on write; take the submission as `input.text()` on signup AND login (see Gotchas on double-hashing).',
+    '  - Login: `s.db.get({ table: users, fieldName: "email", fieldValue: inp("email"), output: ["id", "password"], as: "u" })` \u2014 the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) \u2192 `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("No such user."), error_type: "notfound" })` \u2192 `s.security.check_password({ text_password: inp("password"), hash_password: ref("u.password"), as: "ok" })` \u2192 precondition on `ok` \u2192 `s.security.create_auth_token({ table: users, id: ref("u.id"), as: "token" })` \u2192 `response: { token: ref("token") }`.',
+    '  - Client: send it as an `Authorization: Bearer <token>` header. A `query({ auth: users })` refuses a request without a valid one before its stack runs; inside the stack `auth("id")` is the caller\'s row id (`response: { id: auth("id") }` is the whole `me` endpoint).',
     "- `s.security.create_guid({ as? })` \u2014 bind a fresh GUID string. Takes nothing else.",
     "- `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` \u2014 run another function; `input` is keyed by the target's input names.",
     '  - `runtime?` runs it in the BACKGROUND: `{ mode: "async-shared" }` or `{ mode: "async-dedicated", cpu?, memory?, timeout?, maxRetry? }` (resources read at dedicated only). An async call DOES NOT return the result \u2014 it dispatches and continues, so `as` binds nothing; collect with `s.await({ ids })`. Omit for a normal call. Same block on `s.ai.agent.run`.',
-    '- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`\'s \u2014 a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) \u2014 elsewhere it deploys clean and 500s the first real request.',
+    '- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused, because a query\'s identity is composed from its api group, verb, and name. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`\'s \u2014 a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) \u2014 elsewhere it deploys clean and 500s the first real request.',
     '- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` \u2014 external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`: `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH), `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter \u2014 the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (\u2192 query string for GET/HEAD/OPTIONS, body otherwise), `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines \u2014 prefer a header over a `?key=` query param for a credential \u2014 a URL travels into access logs, proxies and `Referer`. \u26A0 Neither spelling is envelope-safe: the `as` envelope\'s `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request \u2014 read `response.result`. A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record\'s key order, `timeout` a `number` in seconds (1\u201386400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate\u2194private_key, ca_certificate\u2192verify_peer) are checked at build time when statically provable, else by the engine at runtime. The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.',
     "- `s.stream.from_request({ url, method?, \u2026tls, as? })` \u2014 streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED \u2014 it shares `api.request`'s engine declaration, which has no default.",
     "- `s.webflow.request({ path, method?, \u2026tls, as? })` \u2014 Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED \u2014 the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.",
     "- `s.task.call` / `s.tool.call` / `s.trigger.call` / `s.middleware.call` / `s.addon.call` \u2014 same `{ <target>, input?, as? }` shape against the named kind. `s.task.call` and `s.trigger.call` are WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`); `s.tool.call`, `s.middleware.call` and `s.addon.call` run from any stack.",
-    "- `s.action.call({ action, package?, input?, as? })` / `s.action.package.call(\u2026)` \u2014 invoke a marketplace action; `package` is its slug.",
+    "- `s.action.call({ actionId, input?, registry?, as? })` / `s.action.package.call({ traceId, versionId, slug, input?, registry?, as? })` \u2014 invoke an installed action. Ids are SUPPLIED, never derived from a name: an action is installed onto the instance, so its identity is assigned at install and differs per instance \u2014 read them off a call in a pulled workspace. The package form needs all three parts; they are one composite and two of them address nothing. `registry` is the action's own settings, `input` the per-call arguments.",
     "- `s.cloud.job({ image, command, args?, secret?, template?, await?, as? })` \u2014 launch a containerized job. `image`/`command` are REQUIRED; omitted \u2192 `Missing param`. \u26A0 `await` is SECONDS (default 60), not a boolean.",
     "- `s.cloud.job.status({ id, as? })` \xB7 `s.cloud.job.await({ ids, timeout, as? })` \u2014 poll one job, or block on several (`ids` a list `Value`, `timeout` in seconds; both required).",
     "",
     "Microservices (the `microservice()` def and the statement that calls it):",
     "",
+    "- `microservice({ name, kind, \u2026 })` \u2014 two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` \u2014 passing both throws. EARLY SURFACE, expected to change \u2014 every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form \u2014 they need not match the microservice name, which is what a stack addresses.",
+    '- SECRETS RIDE ALONG \u2014 `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material \u2014 keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.',
     '- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` \u2014 in-cluster microservice call (`mvp:microservice_request`); no TLS fields. ONLY `host`+`path` required; the rest default to the engine\'s values (`GET`/`{}`/`[]`/`10`/`true`), always emitted. Pass the `microservice()` DEF as `host` \u2014 it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy. `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it. A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice. `tenantDeploy: "manual"` on the def imports the row without starting the workload.',
     "- `s.workflow_test.call({ workflowTest, datasource?, as? })` \u2014 run another workflow test from inside one, which is the only place it runs (see Gotchas in `llms.txt`). The odd one out: NO `input` (a workflow test takes none), and it carries `datasource?` instead \u2014 same clone caveat as the kind's own field.",
     ""
@@ -1845,6 +1896,7 @@ function renderSections(m) {
   );
   return {
     router: lines,
+    lock,
     legacy,
     objectKinds,
     kindsCore,
@@ -1880,7 +1932,7 @@ function renderDocs(m) {
     {
       path: "llms/object-kinds.md",
       title: "Object kinds",
-      readWhen: "Read when you need the full catalog of authorable primitives \u2014 which factory builds each, which register method takes it, and which payload key it lands under. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.",
+      readWhen: "Read when deciding WHAT to build \u2014 every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, \u2026), what each is, and which factory + register method build it. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.",
       body: s.objectKinds,
       dropLeadingHeading: true
     },
@@ -1938,7 +1990,7 @@ function renderDocs(m) {
     {
       path: "llms/statements-calls.md",
       title: "Auth, cross-object calls, and microservices",
-      readWhen: "Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.",
+      readWhen: "Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.",
       body: s.stmtCalls
     },
     {
@@ -1965,14 +2017,21 @@ function renderDocs(m) {
     {
       path: "llms/lambda.md",
       title: "Lambda bodies (JavaScript)",
-      readWhen: "Read when writing a JavaScript body, or weighing whether to reach for one at all \u2014 `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, each surface binds a different set of identifiers, and the hazards are not guessable.",
+      readWhen: "Read when writing a JavaScript body, or weighing whether to reach for one at all \u2014 `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.",
       body: s.lambda,
       dropLeadingHeading: true
     },
+    {
+      path: "llms/lock.md",
+      title: "Lock file",
+      readWhen: "Read when a `xano.lock` exists or should \u2014 renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.",
+      body: s.lock,
+      dropLeadingHeading: true
+    },
     {
       path: "llms/legacy.md",
       title: "Legacy paradigms and retired statements",
-      readWhen: 'Read when the code was PULLED from an existing Xano instance rather than authored here \u2014 how a codegen\'d tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:\u2026" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list. None of the retired names are authorable for new code.',
+      readWhen: 'Read when the code was PULLED from an existing Xano instance rather than authored here \u2014 how a codegen\'d tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:\u2026" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.',
       body: s.legacy,
       dropLeadingHeading: true
     },
@@ -1988,9 +2047,8 @@ function renderDocs(m) {
     "",
     "Each line is a condition on the task. Open the files whose condition matches and",
     "skip the rest \u2014 paths are relative to this file (`node_modules/@xanots/sdk/` once",
-    "installed), so they resolve with a plain file read and always match the version you",
-    `have. \`${LLMS_FULL_TXT}\` is this file and every one below concatenated \u2014 for a reader`,
-    "that wants one fetch, not for an agent that can open the two files it needs.",
+    `installed), so a plain file read resolves them at the version you have.`,
+    `\`${LLMS_FULL_TXT}\` is everything concatenated \u2014 one fetch, for a reader that cannot open files.`,
     "",
     ...topics.map((t) => `- [${t.title}](${t.path}): ${t.readWhen}`),
     ""

package/dist/{io-7VIA5SON.js → io-M7XZEMK7.js}

@@ -1,11 +1,11 @@
 import {
   readLockFile,
   writeLockFile
-} from "./chunk-MFIHIS6B.js";
+} from "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
-import "./chunk-YUBJLB6G.js";
+import "./chunk-7JDT4PBU.js";
 export {
   readLockFile,
   writeLockFile
 };
-//# sourceMappingURL=io-7VIA5SON.js.map
+//# sourceMappingURL=io-M7XZEMK7.js.map

package/dist/live-diff-QK4KC2FJ.js

@@ -0,0 +1,12 @@
+import {
+  compareToLive,
+  diffAgainstLive,
+  sharedSchemaChanges
+} from "./chunk-5HCDZ2XN.js";
+import "./chunk-ZOYMZZ3S.js";
+export {
+  compareToLive,
+  diffAgainstLive,
+  sharedSchemaChanges
+};
+//# sourceMappingURL=live-diff-QK4KC2FJ.js.map

package/dist/{lock-KXOJIGCG.js → lock-GFXD6G2E.js}

@@ -4,9 +4,11 @@ import {
   LOCK_VERSION,
   WORKSPACE_KEY,
   adoptFromBundle,
+  appNamesByGuid,
   createLockContext,
   emptyLock,
   lockKey,
+  lockNameForObject,
   mergeObserved,
   mintCanonical,
   parseLock,
@@ -15,16 +17,18 @@ import {
   resolvePayloadKey,
   serializeLock,
   validateLockModel
-} from "./chunk-YUBJLB6G.js";
+} from "./chunk-7JDT4PBU.js";
 export {
   CANONICAL_PAYLOAD_KEYS,
   LOCK_PAYLOAD_KEYS,
   LOCK_VERSION,
   WORKSPACE_KEY,
   adoptFromBundle,
+  appNamesByGuid,
   createLockContext,
   emptyLock,
   lockKey,
+  lockNameForObject,
   mergeObserved,
   mintCanonical,
   parseLock,
@@ -34,4 +38,4 @@ export {
   serializeLock,
   validateLockModel
 };
-//# sourceMappingURL=lock-KXOJIGCG.js.map
+//# sourceMappingURL=lock-GFXD6G2E.js.map

package/dist/{lock-commands-6UONZW26.js → lock-commands-7VJKAXV6.js}

@@ -1,22 +1,22 @@
 import {
   loadDefault
-} from "./chunk-MS3BRZAZ.js";
+} from "./chunk-CL2H2WYE.js";
 import {
   UsageError,
   missingArgument,
   unknownSubcommand
-} from "./chunk-IVP6TS26.js";
+} from "./chunk-JQLR64UC.js";
 import {
   readLockFile,
   writeLockFile
-} from "./chunk-MFIHIS6B.js";
+} from "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import "./chunk-EZG76F7R.js";
 import {
   Xano
-} from "./chunk-BPEEGJJA.js";
-import "./chunk-F5T45NAM.js";
-import "./chunk-YUPQOLFX.js";
+} from "./chunk-FAWNUE2U.js";
+import "./chunk-OKNSR7MT.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import {
@@ -27,7 +27,7 @@ import {
   resetLockOverrides,
   resolvePayloadKey,
   seedLockOverrides
-} from "./chunk-YUBJLB6G.js";
+} from "./chunk-7JDT4PBU.js";
 
 // src/emit/lock-commands.ts
 import { existsSync, readFileSync } from "fs";
@@ -229,4 +229,4 @@ ${lines}
 export {
   runLockCommand
 };
-//# sourceMappingURL=lock-commands-6UONZW26.js.map
+//# sourceMappingURL=lock-commands-7VJKAXV6.js.map

package/dist/{login-command-SG7IWTHW.js → login-command-DFCURZLC.js}

@@ -5,10 +5,10 @@ import {
 } from "./chunk-W5NOKYEG.js";
 import {
   promptLine
-} from "./chunk-PGBK64U5.js";
+} from "./chunk-4PTSTDIG.js";
 import {
   envMetaCredentialVarsSet
-} from "./chunk-SG4UBJ47.js";
+} from "./chunk-3QW5NFZJ.js";
 import {
   CALLBACK_PATH,
   DEFAULT_PORT,
@@ -23,10 +23,10 @@ import {
   resolveAuthHost,
   resolveScope,
   writeCredential
-} from "./chunk-LLWK6H77.js";
+} from "./chunk-BKDJN76G.js";
 import {
   UsageError
-} from "./chunk-IVP6TS26.js";
+} from "./chunk-JQLR64UC.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -37,7 +37,7 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-F5T45NAM.js";
+import "./chunk-OKNSR7MT.js";
 
 // src/emit/login-command.ts
 import * as client from "openid-client";
@@ -267,4 +267,4 @@ async function acquireByPaste(p) {
 export {
   runLoginCommand
 };
-//# sourceMappingURL=login-command-SG7IWTHW.js.map
+//# sourceMappingURL=login-command-DFCURZLC.js.map

package/dist/{logout-command-J2AG5NKC.js → logout-command-WXVZQCAV.js}

@@ -5,7 +5,7 @@ import {
   readCredential,
   resolveAuthFilePath,
   resolveScope
-} from "./chunk-LLWK6H77.js";
+} from "./chunk-BKDJN76G.js";
 import "./chunk-GNPVYOPB.js";
 import {
   detail,
@@ -65,4 +65,4 @@ async function runLogoutCommand(args) {
 export {
   runLogoutCommand
 };
-//# sourceMappingURL=logout-command-J2AG5NKC.js.map
+//# sourceMappingURL=logout-command-WXVZQCAV.js.map

package/dist/{marketplace-command-NKTQ3VPS.js → marketplace-command-BCOAAN2I.js}

@@ -15,7 +15,7 @@ import {
   UsageError,
   indentBlock,
   missingArgument
-} from "./chunk-IVP6TS26.js";
+} from "./chunk-JQLR64UC.js";
 import {
   blank,
   detail,
@@ -26,7 +26,7 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-F5T45NAM.js";
+import "./chunk-OKNSR7MT.js";
 
 // src/emit/marketplace-catalogue.ts
 var DEFAULT_BASE_URL = "https://xare-rvr8-mnnt.dev.xano.io";
@@ -362,4 +362,4 @@ export {
   runMarketplaceListCommand,
   runMarketplaceSearchCommand
 };
-//# sourceMappingURL=marketplace-command-NKTQ3VPS.js.map
+//# sourceMappingURL=marketplace-command-BCOAAN2I.js.map

package/dist/{meta-client-OW5WKWW7.js → meta-client-57ZWVHST.js}

@@ -1,6 +1,6 @@
 import {
   importWorkspaceArchive
-} from "./chunk-5WGEURVI.js";
+} from "./chunk-6AAT2AYQ.js";
 import {
   createEphemeral,
   deleteEphemeral,
@@ -167,4 +167,4 @@ ${text}`);
 export {
   MetaClient
 };
-//# sourceMappingURL=meta-client-OW5WKWW7.js.map
+//# sourceMappingURL=meta-client-57ZWVHST.js.map