@xanots/sdk 0.0.6 → 0.0.7

package/dist/node.js

@@ -5,7 +5,7 @@ import {
 import {
   TEST_EXPECT_TYPES,
   expect
-} from "./chunk-JRGDLAEA.js";
+} from "./chunk-JAVB27HL.js";
 import {
   addon,
   agent,
@@ -17,7 +17,7 @@ import {
   task,
   tool,
   workflowTest
-} from "./chunk-CU5VOSTW.js";
+} from "./chunk-JUHKEAHJ.js";
 import {
   actionCall,
   actionPackageCall,
@@ -100,7 +100,7 @@ import {
   workflowTestCall,
   workspaceConfig,
   workspaceTrigger
-} from "./chunk-GC7ZQHW7.js";
+} from "./chunk-2V3JUXTF.js";
 import {
   exportBundleJson,
   loadDefault,
@@ -108,18 +108,18 @@ import {
   run,
   writeArtifact,
   writeBundle
-} from "./chunk-SOCYCBYG.js";
+} from "./chunk-CL2H2WYE.js";
 import "./chunk-JQLR64UC.js";
 import {
   readLockFile,
   writeLockFile
-} from "./chunk-OLQLJY5T.js";
+} from "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import "./chunk-EZG76F7R.js";
 import {
   Xano,
   workspace
-} from "./chunk-3FQD3QME.js";
+} from "./chunk-FAWNUE2U.js";
 import "./chunk-OKNSR7MT.js";
 import {
   LAMBDA_BINDINGS,
@@ -167,7 +167,7 @@ import {
   toSearchParams,
   toolset,
   withFilters
-} from "./chunk-CQBJNFDK.js";
+} from "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import {
   annotate,
@@ -176,7 +176,7 @@ import {
 import {
   resetLockOverrides,
   seedLockOverrides
-} from "./chunk-EFH4NFPY.js";
+} from "./chunk-7JDT4PBU.js";
 
 // src/values/lambda-file.ts
 import { readFileSync } from "fs";

package/dist/{profile-command-ZPC2DPFV.js → profile-command-QJAAUZIV.js}

@@ -1,7 +1,7 @@
 import {
   getAccessToken
-} from "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+} from "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import {
   isMachineOutput,
   writeJson
@@ -74,4 +74,4 @@ export {
   fetchProfile,
   runProfileCommand
 };
-//# sourceMappingURL=profile-command-ZPC2DPFV.js.map
+//# sourceMappingURL=profile-command-QJAAUZIV.js.map

package/dist/{release-command-V4K4IORX.js → release-command-3IET7YII.js}

@@ -6,7 +6,7 @@ import {
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-QVSUMHNN.js";
+} from "./chunk-7BUTRVKA.js";
 import {
   sharedSchemaChanges
 } from "./chunk-5HCDZ2XN.js";
@@ -24,8 +24,8 @@ import {
 } from "./chunk-4PTSTDIG.js";
 import {
   getAccessToken
-} from "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+} from "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import {
   encodeWorkspaceArchive
 } from "./chunk-ZUTSMMAG.js";
@@ -37,14 +37,14 @@ import {
 import "./chunk-3IGNIP6R.js";
 import {
   resolveLockPath
-} from "./chunk-SOCYCBYG.js";
+} from "./chunk-CL2H2WYE.js";
 import {
   UsageError,
   assertWritableDest
 } from "./chunk-JQLR64UC.js";
 import {
   readLockFile
-} from "./chunk-OLQLJY5T.js";
+} from "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -55,15 +55,15 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-3FQD3QME.js";
+import "./chunk-FAWNUE2U.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-CQBJNFDK.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import {
   REFERENCEABLE_KIND_PAYLOAD_KEYS,
   lockKey
-} from "./chunk-EFH4NFPY.js";
+} from "./chunk-7JDT4PBU.js";
 
 // src/emit/release-command.ts
 import { existsSync } from "fs";
@@ -179,12 +179,24 @@ function payloadKeyFor(type) {
   return REFERENCEABLE_KIND_PAYLOAD_KEYS[type] ?? type;
 }
 function splitPruneDeletes(plan, tracked) {
+  const ownedQueryNames = /* @__PURE__ */ new Set();
+  for (const key of tracked) {
+    if (!key.startsWith("query:")) continue;
+    const lockName = key.slice("query:".length);
+    const lastSep = lockName.lastIndexOf("|");
+    ownedQueryNames.add(lastSep === -1 ? lockName : lockName.slice(lastSep + 1));
+  }
+  const isOwned = (op) => {
+    const payloadKey = payloadKeyFor(op.type);
+    if (payloadKey === "query") return ownedQueryNames.has(op.name);
+    return tracked.has(lockKey(payloadKey, op.name));
+  };
   const collateral = [];
   const owned = [];
   for (const op of plan.operations) {
     if (op.action !== "delete") continue;
     if (IDENTITY_EXEMPT_TYPES.has(op.type)) continue;
-    (tracked.has(lockKey(payloadKeyFor(op.type), op.name)) ? owned : collateral).push(op);
+    (isOwned(op) ? owned : collateral).push(op);
   }
   return { collateral, owned };
 }
@@ -206,8 +218,8 @@ async function reconcileLockAfterReplace(args, auth, workspaceId) {
     return;
   }
   try {
-    const { adoptFromBundle } = await import("./lock-PDFCNYUW.js");
-    const { readLockFile: readLockFile2, writeLockFile } = await import("./io-65CJNLYI.js");
+    const { adoptFromBundle } = await import("./lock-GFXD6G2E.js");
+    const { readLockFile: readLockFile2, writeLockFile } = await import("./io-M7XZEMK7.js");
     const { lock, added, changed } = adoptFromBundle(readLockFile2(lockPath), live, lockPath);
     writeLockFile(lockPath, lock);
     const touched = added.length + changed.length;
@@ -431,7 +443,7 @@ async function runReleaseCommand(args) {
     { withSeed: req.records === true }
   );
   if (args.static !== void 0) {
-    const { assertNoSeedLeaks } = await import("./deploy-command-MTQQXPOO.js");
+    const { assertNoSeedLeaks } = await import("./deploy-command-HM57BINV.js");
     await assertNoSeedLeaks(args.static, nonPublicSeedValues, args.allowSeedInStatic);
   }
   const workspaceId = auth.workspaceId;
@@ -573,7 +585,7 @@ Retry, or drop \`--backup-branch\` to release without one.`,
     ...backupLabel !== void 0 ? { backupBranch: backupLabel } : {}
   };
   if (args.static !== void 0) {
-    const { buildStaticEnv, deployStaticTo } = await import("./deploy-command-MTQQXPOO.js");
+    const { buildStaticEnv, deployStaticTo } = await import("./deploy-command-HM57BINV.js");
     const env = buildStaticEnv(auth.instance, args.staticEnv);
     const explicit = Object.keys(args.staticEnv).length > 0;
     summary.static = await deployStaticTo(
@@ -592,4 +604,4 @@ Retry, or drop \`--backup-branch\` to release without one.`,
 export {
   runReleaseCommand
 };
-//# sourceMappingURL=release-command-V4K4IORX.js.map
+//# sourceMappingURL=release-command-3IET7YII.js.map

package/dist/{sandbox-details-command-DMY2KGA2.js → sandbox-details-command-EDO56IY3.js}

@@ -2,10 +2,10 @@ import {
   fetchSandboxDetails,
   runSandboxDetailsCommand,
   sandboxBaseUrl
-} from "./chunk-OR43PDCW.js";
+} from "./chunk-3EYUR3TX.js";
 import "./chunk-NDZFBZHC.js";
-import "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+import "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import "./chunk-NUQCEOKA.js";
 import "./chunk-3IGNIP6R.js";
 import "./chunk-GNPVYOPB.js";
@@ -15,4 +15,4 @@ export {
   runSandboxDetailsCommand,
   sandboxBaseUrl
 };
-//# sourceMappingURL=sandbox-details-command-DMY2KGA2.js.map
+//# sourceMappingURL=sandbox-details-command-EDO56IY3.js.map

package/dist/{sandbox-export-command-R6QMEK3D.js → sandbox-export-command-MO6DEZ7Z.js}

@@ -3,11 +3,11 @@ import {
   fetchSandboxMultidoc,
   resolveOutputTarget,
   runSandboxExportCommand
-} from "./chunk-AAFBSOSD.js";
-import "./chunk-OR43PDCW.js";
+} from "./chunk-JQJPFUZI.js";
+import "./chunk-3EYUR3TX.js";
 import "./chunk-NDZFBZHC.js";
-import "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+import "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import "./chunk-QTNO2WD6.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
@@ -21,4 +21,4 @@ export {
   resolveOutputTarget,
   runSandboxExportCommand
 };
-//# sourceMappingURL=sandbox-export-command-R6QMEK3D.js.map
+//# sourceMappingURL=sandbox-export-command-MO6DEZ7Z.js.map

package/dist/{store-BJONDJoZ.d.ts → store-DfuWu1tE.d.ts}

@@ -5979,7 +5979,7 @@ interface QueryDef<I extends Record<string, InputDescriptor> = Record<string, In
      * Captured as a literal so `getPath({ params })` types its keys from it.
      */
     name: N;
-    /** Explicit Xano `guid` (this object's identity). Defaults to a guid derived from `name`; set it to keep identity across a rename or to match an existing object. */
+    /** Explicit Xano `guid` (this object's identity). Defaults to a guid derived from `(apiGroup, verb, name)` — a query's engine uniqueness — so a `GET`/`POST` pair on one path, and one path across two groups, are distinct objects. Set it to keep identity across a rename or to match an existing object. */
     guid?: string;
     /**
      * The HTTP method, UPPERCASE — one of `GET`, `POST`, `PUT`, `PATCH`,

package/dist/{test-command-OEBIGOPP.js → test-command-S7SMRWMP.js}

@@ -1,13 +1,13 @@
 import {
   resolveMetaTarget
-} from "./chunk-CEFYM6N5.js";
-import "./chunk-WJYB7DSI.js";
-import "./chunk-OR43PDCW.js";
+} from "./chunk-H2DEDWQF.js";
+import "./chunk-MDXR5E5Q.js";
+import "./chunk-3EYUR3TX.js";
 import "./chunk-NDZFBZHC.js";
 import {
   getAccessToken
-} from "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+} from "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import {
   isMachineOutput,
   writeJson
@@ -380,4 +380,4 @@ export {
   runSuite,
   runTestCommand
 };
-//# sourceMappingURL=test-command-OEBIGOPP.js.map
+//# sourceMappingURL=test-command-S7SMRWMP.js.map

package/dist/{upgrade-command-52AAZ3NV.js → upgrade-command-TZYSGXP7.js}

@@ -7,8 +7,8 @@ import {
 } from "./chunk-NUQCEOKA.js";
 import {
   refreshAgentFiles
-} from "./chunk-P5OAM3G2.js";
-import "./chunk-2SUCC4DV.js";
+} from "./chunk-QIWBCS7N.js";
+import "./chunk-4PE4ZAB7.js";
 import {
   runNpm
 } from "./chunk-ZSYZTGJH.js";
@@ -22,10 +22,10 @@ import {
   registryUrl,
   suppressUpdateNotice,
   upgradeCommand
-} from "./chunk-Y7BARS25.js";
-import "./chunk-SOCYCBYG.js";
+} from "./chunk-FDKR4YMN.js";
+import "./chunk-CL2H2WYE.js";
 import "./chunk-JQLR64UC.js";
-import "./chunk-OLQLJY5T.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -35,12 +35,12 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-3FQD3QME.js";
+import "./chunk-FAWNUE2U.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-CQBJNFDK.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-EFH4NFPY.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/upgrade-command.ts
 import { readFileSync, writeFileSync } from "fs";
@@ -174,4 +174,4 @@ function messageOf(err) {
 export {
   runUpgradeCommand
 };
-//# sourceMappingURL=upgrade-command-52AAZ3NV.js.map
+//# sourceMappingURL=upgrade-command-TZYSGXP7.js.map

package/dist/{validate-command-KTLPSSH7.js → validate-command-MMXEVHH3.js}

@@ -1,10 +1,10 @@
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-QVSUMHNN.js";
-import "./chunk-SOCYCBYG.js";
+} from "./chunk-7BUTRVKA.js";
+import "./chunk-CL2H2WYE.js";
 import "./chunk-JQLR64UC.js";
-import "./chunk-OLQLJY5T.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -14,12 +14,12 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-3FQD3QME.js";
+import "./chunk-FAWNUE2U.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-CQBJNFDK.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-EFH4NFPY.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/validate-command.ts
 var EXIT_VALIDATION_FAILED = 2;
@@ -119,4 +119,4 @@ function fmt(v) {
 export {
   runValidateCommand
 };
-//# sourceMappingURL=validate-command-KTLPSSH7.js.map
+//# sourceMappingURL=validate-command-MMXEVHH3.js.map

package/dist/{workspace-command-LX5S5N2H.js → workspace-command-X6L7HTXO.js}

@@ -1,12 +1,12 @@
 import {
   fetchWorkspaceBundle,
   runCodegenCommand
-} from "./chunk-TYBB7ON3.js";
+} from "./chunk-5PDOAR77.js";
 import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
-} from "./chunk-AAFBSOSD.js";
-import "./chunk-OR43PDCW.js";
+} from "./chunk-JQJPFUZI.js";
+import "./chunk-3EYUR3TX.js";
 import {
   printMicroserviceSection,
   readMicroservices
@@ -14,35 +14,35 @@ import {
 import {
   ENV_WORKSPACE,
   getAccessToken
-} from "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+} from "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import "./chunk-QTNO2WD6.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-4HDOP7LH.js";
+import "./chunk-DBHE35JM.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
-import "./chunk-2SUCC4DV.js";
+import "./chunk-4PE4ZAB7.js";
 import "./chunk-ZSYZTGJH.js";
 import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import "./chunk-JRGDLAEA.js";
+import "./chunk-JAVB27HL.js";
 import "./chunk-LU7TRWMC.js";
 import "./chunk-MU3O43L2.js";
 import "./chunk-P5C2YKAM.js";
 import "./chunk-Q77KNEUL.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-GC7ZQHW7.js";
-import "./chunk-SOCYCBYG.js";
+import "./chunk-2V3JUXTF.js";
+import "./chunk-CL2H2WYE.js";
 import {
   removedSubcommand,
   unknownSubcommand
 } from "./chunk-JQLR64UC.js";
-import "./chunk-OLQLJY5T.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   formatFields,
@@ -50,12 +50,12 @@ import {
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-3FQD3QME.js";
+import "./chunk-FAWNUE2U.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-CQBJNFDK.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-EFH4NFPY.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/workspace-command.ts
 import { writeFileSync } from "fs";
@@ -70,7 +70,7 @@ async function runWorkspaceCommand(args) {
     case "codegen":
       return runCodegenCommand(args, { kind: "workspace" });
     case "branch": {
-      const { runBranchCommand } = await import("./branch-commands-R4FR75UW.js");
+      const { runBranchCommand } = await import("./branch-commands-PBQ36L4A.js");
       return runBranchCommand(args);
     }
     case "deploy":
@@ -160,4 +160,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-LX5S5N2H.js.map
+//# sourceMappingURL=workspace-command-X6L7HTXO.js.map

package/guides/environment.md

@@ -65,8 +65,10 @@ Every top-level object carries a stable `guid` — Xano's identity anchor. On a
 the engine matches an incoming object to an existing one **by guid** and updates it in
 place; no match means a new object. So re-running `export`/`deploy` on the same code maps
 cleanly onto the same workspace — **no duplicates**. By default the guid derives from the
-object's `name`; set an explicit `guid` to pin identity across a rename, or to adopt an
-existing workspace object into code.
+object's `name` — for a **query**, from its api group, verb, and name together, which is
+the engine's own uniqueness for an endpoint, so `GET items` and `POST items` are distinct
+objects and a path may repeat across groups. Set an explicit `guid` to pin identity across
+a rename, or to adopt an existing workspace object into code.
 
 The opt-in **`xano.lock`** freezes the whole workspace's identities at once — every
 auto-derived guid, plus the `canonical` URL tokens of API groups and toolsets (which the
@@ -81,7 +83,8 @@ guard. Adopt it early either way: once identities have drifted, the only way bac
 Precedence at emit is always **explicit in-code value → lock entry → name derivation**.
 
 **When the lock is actually load-bearing.** Because the default derivation is deterministic
-— `md5("<type>:<name>")` — a project that created all of its own objects can regenerate a
+— `md5("<type>:<name>")`, and `md5("query:<group>|<verb>|<name>")` for a query — a project
+that created all of its own objects can regenerate a
 byte-identical lock from its own source. Delete that lock, release again, and the same guids
 come back: the objects match and update in place. For that project the lock is a *cache*, and
 losing it costs nothing.

package/llms/fields.md

@@ -57,6 +57,14 @@ the entry's own name. `hidden: ["created_at"]` drops columns from that expansion
 `input.list(element)` for arrays — 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 —
+`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) — 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** — 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) — no

package/llms/kinds-core.md

@@ -5,7 +5,8 @@
 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?` —
-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? })`

package/llms/lambda.md

@@ -1,6 +1,6 @@
 # Lambda bodies (JavaScript)
 
-> Read when writing a JavaScript body, or weighing whether to reach for one at all — `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.
+> Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
 
 **A lambda is an escape hatch, not a default.** The body runs outside the request's own
 runtime, and a workspace has a BOUNDED pool of lambda workers every lambda in it shares

package/llms/legacy.md

@@ -1,6 +1,6 @@
 # Legacy paradigms and retired statements
 
-> Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list. None of the retired names are authorable for new code.
+> Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 
 Older paradigms this SDK still supports and still emits when it decodes an existing
 workspace. **Do not author these.** They are listed by name only so you recognize them

package/llms/lock.md

@@ -0,0 +1,32 @@
+# Lock file
+
+> Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+
+`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 —
+`query:<group>|<verb>|<name>` — 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>` — `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…] --yes` — drops orphaned entries. Finding orphans
+  RUNS the entry's module scope (env assertions included); `--no-verify --yes <kind:name>…`
+  prunes named keys with no evaluation and no orphan check.
+- `xanots lock adopt <live-bundle.json> [--yes]` — 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 — 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 — 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.

package/llms/object-kinds.md

@@ -1,6 +1,6 @@
 # Object kinds
 
-> Read when you need the full catalog of authorable primitives — 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.
+> Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), 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.
 
 Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
 
@@ -27,6 +27,6 @@ Author with the factory, register on the Xano instance, lands under the payload
 - realtime_server: `realtimeServer` → `Xano.registerRealtimeServers` → payload `realtime_server` — 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>`).
 - channel: `realtimeChannel` → `Xano.registerRealtimeChannels` → payload `channel` — 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.
 - message: `realtimeMessage` → `Xano.registerRealtimeMessages` → payload `message` — A realtime message handler: a named message type on a channel with its own typed payload and stack — the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.
-- microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — 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` — passing both throws. EARLY SURFACE, expected to change — 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 — they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG — `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 — 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")`.
+- microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — 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`.
 - knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown the workspace's AI agents read before they act — an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
 - workspace: `workspaceConfig` → `Xano.registerWorkspace` → payload `workspace` — Workspace-level configuration such as default middleware chains and request-history defaults per host kind.

package/llms/statements-calls.md

@@ -1,14 +1,19 @@
 # Auth, cross-object calls, and microservices
 
-> Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
+> 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.
 
 Auth & calls:
 
 - `s.security.create_auth_token({ table, id, extras?, expiration?, as? })` — `extras` defaults to `{}`, `expiration` to `86400`s (`0` = never).
+- **Marketplace first:** `@xanots/auth` registers a complete auth surface — signup/login/me endpoints plus their `user`/`account`/`event_log` tables — via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `xanots marketplace details @xanots/auth --prompt`.
+- **The auth loop end to end** — 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") } })` — 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" })` — the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) → `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("No such user."), error_type: "notfound" })` → `s.security.check_password({ text_password: inp("password"), hash_password: ref("u.password"), as: "ok" })` → precondition on `ok` → `s.security.create_auth_token({ table: users, id: ref("u.id"), as: "token" })` → `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? })` — bind a fresh GUID string. Takes nothing else.
 - `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` — 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 — 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? })` — invoke an endpoint. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s — 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 — 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`) — elsewhere it deploys clean and 500s the first real request.
+- `s.api.call({ api, input?, headers?, auth?, as? })` — invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) — 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 — 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 — 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`) — 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? })` — 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 — 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` (→ 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 — prefer a header over a `?key=` query param for a credential — a URL travels into access logs, proxies and `Referer`. ⚠ 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 — 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–86400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate↔private_key, ca_certificate→verify_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?, …tls, as? })` — streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED — it shares `api.request`'s engine declaration, which has no default.
 - `s.webflow.request({ path, method?, …tls, as? })` — Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED — the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.
@@ -19,5 +24,7 @@ Auth & calls:
 
 Microservices (the `microservice()` def and the statement that calls it):
 
+- `microservice({ name, kind, … })` — 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` — passing both throws. EARLY SURFACE, expected to change — 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 — they need not match the microservice name, which is what a stack addresses.
+- SECRETS RIDE ALONG — `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 — 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? })` — 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` — 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? })` — 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 — same clone caveat as the kind's own field.