@abloatai/ablo 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- **Client observability — `debug` / `logLevel`, off by default.** The SDK used to
+  emit a `debug` line per model and per property during schema registration (a
+  firehose). It now defaults to a quiet `warn` threshold and exposes two new
+  `Ablo()` options to opt back in:
+  - `logLevel: 'debug' | 'info' | 'warn' | 'error' | 'silent'` — `'info'` surfaces
+    coordination and connection events without the per-model registration noise;
+    `'debug'` is everything. Precedence: explicit `logLevel` → `debug: true` →
+    `ABLO_LOG_LEVEL` env → default `warn`. Supplying your own `logger` bypasses both.
+  - `debug: boolean` — shorthand for `logLevel: 'debug'`.
+
+  Coordination is now traceable at `info`: claims that are **rejected** or **lost**
+  (preempted/expired), and your position **advancing in a claim queue**, each log
+  once per change with a readable target (`documents:abc.title`) — quiet lowercase
+  lines, no shouty tags.
+
+  **New: canonical wire-egress contract export.** `errorEnvelope`, `statusForType`,
+  and the `ErrorEnvelope` type are now exported from the package root. Server
+  consumers (e.g. a self-hosted sync server) can assert against the one source of
+  truth for the error-envelope shape and the `AbloError`-subclass→HTTP-status
+  table instead of keeping a copy that silently drifts.
+
+  **Structured CLI error rendering.** CLI failures render as a titled block with a
+  reason code and per-code remediation (`--verbose` for the stack) instead of a
+  console wall-of-text; `AbloError.toString()` produces a leak-proof one-liner.
+
+  **`ABLO_API_KEY` resolution + sandbox key scopes.** The key is now resolved from
+  `.env.local` / `.env` (not just the process env), and sandbox keys are granted
+  `schema:push` by default so `ablo push` works out of the box in a fresh sandbox.
+
 ## 0.17.0
 
 ### Minor Changes

package/dist/BaseSyncedStore.d.ts

@@ -505,10 +505,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);

package/dist/BaseSyncedStore.js

@@ -739,9 +739,21 @@ export class BaseSyncedStore {
                 // A throw = transient (offline / mint endpoint unreachable / 5xx). The
                 // login may be perfectly valid; never sign out for this — back off and
                 // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
-                getContext().logger.warn('[BaseSyncedStore] Access-credential re-mint failed (transient)', {
-                    error: error?.message,
-                });
+                const message = error?.message ?? String(error);
+                // A relative-URL resolver invoked server-side (Node fetch has no origin
+                // to resolve against) emits the opaque "Failed to parse URL" / "Only
+                // absolute URLs are supported". Translate it into something actionable
+                // instead of a mystery transient blip — the proactive refresh is now
+                // browser-only, so hitting this means the resolver fired from SSR/RSC or
+                // a server route.
+                if (typeof window === 'undefined' && /parse URL|absolute URLs?/i.test(message)) {
+                    getContext().logger.warn('credential resolver ran on the server with a relative URL — Node fetch needs an absolute URL. ' +
+                        'Refresh the Ablo client in the browser, or build an absolute URL server-side ' +
+                        "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
+                }
+                else {
+                    getContext().logger.warn('access-credential re-mint failed (transient)', { error: message });
+                }
                 return 'network_error';
             }
         })();
@@ -769,10 +781,11 @@ export class BaseSyncedStore {
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);
@@ -807,14 +820,25 @@ export class BaseSyncedStore {
             // 'network_error' → transient (offline / mint hiccup); the next timer tick
             // or the FSM's own probe retries. Never sign out for it.
         };
-        // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
-        // is recovered by the next, or by the reactive probe. The timer is the sole
-        // proactive PRE-ROLL — it keeps the key warm ahead of expiry even while the
-        // socket sits healthy-`connected` (a state the FSM never probes unprompted).
-        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-        const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
-        const teardowns = [() => clearInterval(timer)];
+        const teardowns = [];
+        // The ENTIRE proactive pre-roll is BROWSER-ONLY. On the server (Next.js
+        // SSR/RSC evaluating the `providers` module) there is no live socket to keep
+        // warm AND the scaffolded credential resolver is browser-oriented (a
+        // relative-URL `fetch('/api/ablo-session')`). Arming the timer server-side
+        // fires that resolver in Node, where fetch has no origin to resolve a
+        // relative URL against → "Failed to parse URL" on every tick. Browser-only
+        // refresh is the unanimous vendor model (Supabase `autoRefreshToken: isBrowser()`,
+        // Clerk/Ably/Stripe refresh client-side). The reactive re-mint hook
+        // (`setCredentialRefresher` above) stays UNCONDITIONAL: it only fires on a
+        // real connection probe, which can't happen during a bare SSR module eval.
         if (typeof window !== 'undefined') {
+            // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled)
+            // tick is recovered by the next, or by the reactive probe. The timer is
+            // the sole proactive PRE-ROLL — it keeps the key warm ahead of expiry even
+            // while the socket sits healthy-`connected` (a state the FSM never probes).
+            const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+            const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+            teardowns.push(() => clearInterval(timer));
             // OS-wake (desktop only): the Electron shell bridges `powerMonitor`
             // 'resume' to this DOM event. This is the ONE event-trigger the lifecycle
             // still owns, because `visibilitychange` does NOT fire on wake-from-sleep

package/dist/NetworkMonitor.js

@@ -31,7 +31,9 @@ export class NetworkMonitor extends EventEmitter {
         const wasOnline = this.isOnline;
         this.isOnline = false;
         if (wasOnline) {
-            getContext().logger.warn('Network connection lost');
+            // Symmetric with 'Network connection restored' (info) — expected,
+            // transient connectivity state, not an actionable warning.
+            getContext().logger.info('Network connection lost');
             this.emit('offline');
         }
     };

package/dist/cli.cjs

@@ -276700,7 +276700,7 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 };
 
 // src/cli/index.ts
-var import_picocolors18 = __toESM(require_picocolors(), 1);
+var import_picocolors19 = __toESM(require_picocolors(), 1);
 var import_fs12 = require("fs");
 var import_path7 = require("path");
 var import_child_process2 = require("child_process");
@@ -277009,6 +277009,18 @@ var ERROR_CODES = {
   invalid_schema: wire("validation", 400, false, "The submitted schema could not be parsed."),
   incompatible_change: wire("conflict", 409, false, "The schema change is incompatible with the current schema.")
 };
+function errorCodeSpec(code) {
+  return ERROR_CODES[code];
+}
+function classifyRecovery(code) {
+  const spec = errorCodeSpec(code);
+  if (!spec) return "none";
+  if (spec.recovery) return spec.recovery;
+  if (spec.retryable) return "transient";
+  if (spec.httpStatus === 403) return "permission";
+  if (spec.category === "auth") return "auth_blocked";
+  return "none";
+}
 
 // src/coordination/schema.ts
 init_cjs_shims();
@@ -277331,6 +277343,20 @@ var AbloError = class extends Error {
       ...this.details ?? {}
     };
   }
+  /**
+   * A single, leak-proof line for logs and `String(err)` / template
+   * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+   *
+   * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+   * makes `console.error(richError)` an unreadable wall of text. The structured
+   * payload stays available via {@link toJSON}; this is the human one-liner.
+   */
+  toString() {
+    const code = this.code ? ` [${this.code}]` : "";
+    const docs = this.docUrl ? ` (see ${this.docUrl})` : "";
+    const req = this.requestId ? ` [request_id: ${this.requestId}]` : "";
+    return `${this.name}${code}: ${this.message}${docs}${req}`;
+  }
 };
 function docUrlForCode(code) {
   return `https://docs.abloatai.com/errors#${code}`;
@@ -279530,6 +279556,16 @@ function readProjectDatabaseUrl(cwd = process.cwd()) {
   }
   return null;
 }
+function readProjectApiKey(cwd = process.cwd()) {
+  if (process.env.ABLO_API_KEY) return { key: process.env.ABLO_API_KEY, source: "env" };
+  for (const name of [".env.local", ".env"]) {
+    const path = (0, import_path.resolve)(cwd, name);
+    if (!(0, import_fs2.existsSync)(path)) continue;
+    const match = (0, import_fs2.readFileSync)(path, "utf8").match(/^ABLO_API_KEY=(.+)$/m);
+    if (match?.[1]) return { key: match[1].trim().replace(/^["']|["']$/g, ""), source: name };
+  }
+  return null;
+}
 
 // src/cli/migrate.ts
 var import_schema3 = require("@abloatai/ablo/schema");
@@ -279886,6 +279922,21 @@ async function loadSchema(schemaPath, exportName) {
   }
   return schema;
 }
+function maskKey(key) {
+  return key ? `${key.slice(0, 12)}\u2026` : "(none)";
+}
+function describeKeySource(source) {
+  switch (source) {
+    case "env":
+      return "ABLO_API_KEY (environment)";
+    case ".env.local":
+      return ".env.local";
+    case ".env":
+      return ".env";
+    case "login":
+      return "`ablo login` (stored sandbox config)";
+  }
+}
 async function push(argv) {
   let args;
   try {
@@ -279894,7 +279945,17 @@ async function push(argv) {
     console.error(import_picocolors2.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
-  if (!args.apiKey) args.apiKey = resolveApiKey();
+  let keySource = "env";
+  if (!args.apiKey) {
+    const fromProject = readProjectApiKey();
+    if (fromProject) {
+      args.apiKey = fromProject.key;
+      keySource = fromProject.source;
+    } else {
+      args.apiKey = resolveApiKey();
+      keySource = "login";
+    }
+  }
   if (!args.apiKey) {
     console.error(
       import_picocolors2.default.red(`  No API key.`) + import_picocolors2.default.dim(
@@ -279953,6 +280014,7 @@ async function push(argv) {
     const code = body.code ?? body.reason;
     const serverMsg = body.message ?? body.reason;
     console.error(import_picocolors2.default.red(`  Forbidden${code ? ` [${code}]` : ""}: ${serverMsg ?? "permission denied"}`));
+    console.error(import_picocolors2.default.dim(`  Push used ${import_picocolors2.default.bold(maskKey(args.apiKey))} from ${describeKeySource(keySource)}.`));
     if (code === "database_role_cannot_enforce_rls") {
       console.error(
         import_picocolors2.default.dim(
@@ -279971,6 +280033,12 @@ async function push(argv) {
           `  Schema pushes need a SECRET key: ${import_picocolors2.default.bold("sk_test_")} (sandbox dev loop) or a dashboard ${import_picocolors2.default.bold("sk_live_")} (production deploy: ${import_picocolors2.default.bold("ABLO_API_KEY=sk_live_\u2026 npx ablo push")}).`
         )
       );
+    } else {
+      console.error(
+        import_picocolors2.default.dim(
+          `  This key isn't authorized to push schema (needs ${import_picocolors2.default.bold("schema:push")}). ` + (keySource === "login" ? `It's your stored ${import_picocolors2.default.bold("ablo login")} sandbox key \u2014 a key in ${import_picocolors2.default.bold(".env.local")} or ${import_picocolors2.default.bold("ABLO_API_KEY")} takes precedence, so put a schema:push key there (sandbox ${import_picocolors2.default.bold("sk_test_")} or production ${import_picocolors2.default.bold("sk_live_")}) and re-push. ` : `Use a schema:push key \u2014 a sandbox ${import_picocolors2.default.bold("sk_test_")} or production ${import_picocolors2.default.bold("sk_live_")}. `) + `Manage keys at https://abloatai.com`
+        )
+      );
     }
   } else {
     console.error(import_picocolors2.default.red(`  Push failed (${status2}): ${body.message ?? body.reason ?? bodyText}`));
@@ -282500,9 +282568,86 @@ async function drizzlePull(argv) {
   );
 }
 
+// src/cli/renderError.ts
+init_cjs_shims();
+var import_picocolors18 = __toESM(require_picocolors(), 1);
+var RECOVERY_HINT = {
+  transient: "This looks transient \u2014 retry in a moment.",
+  permission: "Your key isn't allowed to do this \u2014 check its scopes or role.",
+  session_expiry: "Your session expired \u2014 sign in again.",
+  access_credential_expiry: "Your access credential expired \u2014 refresh it and retry.",
+  auth_blocked: "Authentication was blocked."
+};
+function titleForType(type) {
+  const core = type.replace(/^Ablo/, "").replace(/Error$/, "");
+  const spaced = core.replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim();
+  if (!spaced) return "Error";
+  return /error$/i.test(spaced) ? spaced : `${spaced} error`;
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x2) => typeof x2 === "string");
+}
+function renderKnownDetails(details, line) {
+  if (!details) return;
+  const { retryAfterSeconds, missingIds, requiredCapability, unexecutable, errors } = details;
+  if (typeof retryAfterSeconds === "number") line(`    ${import_picocolors18.default.dim("retry")}  after ${retryAfterSeconds}s`);
+  if (isStringArray(missingIds) && missingIds.length > 0) {
+    const shown = missingIds.slice(0, 5).join(", ");
+    const more = missingIds.length > 5 ? ` (+${missingIds.length - 5} more)` : "";
+    line(`    ${import_picocolors18.default.dim("missing")} ${shown}${more}`);
+  }
+  if (typeof requiredCapability === "string") line(`    ${import_picocolors18.default.dim("needs")}  ${requiredCapability}`);
+  if (Array.isArray(unexecutable) && unexecutable.length > 0) {
+    line(`    ${import_picocolors18.default.dim("blocked")} ${unexecutable.length} change(s) can't be applied \u2014 see \`unexecutable\` (--verbose)`);
+  }
+  if (Array.isArray(errors)) {
+    for (const e2 of errors.slice(0, 8)) {
+      if (e2 && typeof e2 === "object") {
+        const rec = e2;
+        const where = typeof rec.param === "string" ? `${rec.param}: ` : "";
+        const msg = typeof rec.message === "string" ? rec.message : "";
+        if (msg) line(`    ${import_picocolors18.default.dim("\xB7")} ${where}${msg}`);
+      }
+    }
+  }
+}
+function renderCliError(err, opts = {}) {
+  const line = opts.write ?? ((l2) => console.error(l2));
+  const verbose = opts.verbose ?? (process.argv.includes("--verbose") || process.env.ABLO_VERBOSE === "1");
+  if (err instanceof AbloError) {
+    const codeTag = err.code ? `  ${import_picocolors18.default.dim(`[${err.code}]`)}` : "";
+    line("");
+    line(`  ${brand("ablo")} ${import_picocolors18.default.red("\u2717")} ${import_picocolors18.default.bold(titleForType(err.type))}${codeTag}`);
+    line("");
+    line(`    ${err.message}`);
+    if (err.param) line(`    ${import_picocolors18.default.dim("field")}  ${err.param}`);
+    renderKnownDetails(err.details, line);
+    const hint = err.code ? RECOVERY_HINT[classifyRecovery(err.code)] : void 0;
+    if (hint) line(`    ${import_picocolors18.default.dim(hint)}`);
+    if (err.docUrl) line(`    ${import_picocolors18.default.dim("docs")}   ${err.docUrl}`);
+    if (err.requestId) line(`    ${import_picocolors18.default.dim("ref")}    ${err.requestId}`);
+    if (verbose) {
+      if (err.details && Object.keys(err.details).length > 0) {
+        line(`    ${import_picocolors18.default.dim("details")} ${JSON.stringify(err.details)}`);
+      }
+      if (err.stack) line(import_picocolors18.default.dim(err.stack));
+    }
+    line("");
+    process.exitCode = 1;
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  line("");
+  line(`  ${brand("ablo")} ${import_picocolors18.default.red("\u2717")} ${message}`);
+  if (verbose && err instanceof Error && err.stack) line(import_picocolors18.default.dim(err.stack));
+  else line(`    ${import_picocolors18.default.dim("Run with --verbose for the full error.")}`);
+  line("");
+  process.exitCode = 1;
+}
+
 // src/cli/index.ts
 var LOGO = `
-  ${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}
+  ${brand("ablo")} ${import_picocolors19.default.dim("sync engine")}
 `;
 var SUBCOMMAND_USAGE = {
   connect: CONNECT_USAGE,
@@ -282537,7 +282682,7 @@ async function main() {
     const devArgs = process.argv.slice(3);
     const oneShot = devArgs.includes("--no-watch");
     console.log(
-      import_picocolors18.default.dim(
+      import_picocolors19.default.dim(
         oneShot ? "  `ablo dev --no-watch` is `ablo push` (push once, no watcher) \u2014 running that." : "  `ablo dev` is now `ablo push --watch` \u2014 running that."
       )
     );
@@ -282564,14 +282709,14 @@ async function main() {
     const guard = guardActiveProjectKey();
     if (!guard.ok && guard.available.length > 0 && !rest.includes("--url")) {
       console.error(
-        `  ${import_picocolors18.default.yellow("\u26A0")} active project ${import_picocolors18.default.bold(guard.activeProfile)} has no stored key ${import_picocolors18.default.dim(
+        `  ${import_picocolors19.default.yellow("\u26A0")} active project ${import_picocolors19.default.bold(guard.activeProfile)} has no stored key ${import_picocolors19.default.dim(
           `(you have keys for: ${guard.available.join(", ")})`
         )}`
       );
       const loginCmd = guard.activeProfile === "default" ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
       console.error(
-        import_picocolors18.default.dim(
-          `    Mint one with ${import_picocolors18.default.bold(loginCmd)}, or switch with ${import_picocolors18.default.bold("ablo projects use <slug>")}.`
+        import_picocolors19.default.dim(
+          `    Mint one with ${import_picocolors19.default.bold(loginCmd)}, or switch with ${import_picocolors19.default.bold("ablo projects use <slug>")}.`
         )
       );
       process.exitCode = 1;
@@ -282589,13 +282734,13 @@ async function main() {
     await generate(process.argv.slice(3));
   } else if (command === "schema") {
     console.error(
-      `  ${import_picocolors18.default.red("\u2717")} \`ablo schema push\` was renamed to \`${brand("ablo push")}\`.`
+      `  ${import_picocolors19.default.red("\u2717")} \`ablo schema push\` was renamed to \`${brand("ablo push")}\`.`
     );
     console.error(`    Run \`ablo push${process.argv.slice(4).join(" ") ? " " + process.argv.slice(4).join(" ") : ""}\` instead.`);
     process.exitCode = 1;
   } else {
     console.log(LOGO);
-    console.log(`  ${import_picocolors18.default.bold("Usage:")}`);
+    console.log(`  ${import_picocolors19.default.bold("Usage:")}`);
     console.log(`    npx ablo init                          Scaffold ablo/ directory + starter schema`);
     console.log(`    npx ablo init --yes [--framework nextjs] Non-interactive (agents/CI): no prompts, flag-driven`);
     console.log(`                  [--auth apikey] [--storage direct|endpoint] [--project <slug>] [--no-project]`);
@@ -282630,10 +282775,10 @@ async function main() {
     console.log(`    npx ablo generate                      Emit TypeScript types from your schema`);
     console.log(`    npx ablo generate --out path.ts        Write generated types to a path`);
     console.log();
-    console.log(`  ${import_picocolors18.default.bold("Schema workflow:")}`);
+    console.log(`  ${import_picocolors19.default.bold("Schema workflow:")}`);
     console.log(`    The server holds its own copy of your schema \u2014 edit ${brand("ablo/schema.ts")}, then`);
     console.log(`    run ${brand("ablo push")} (or keep ${brand("ablo dev")} running) before the server will accept`);
-    console.log(`    writes to new or changed models. Skip it and writes fail with ${import_picocolors18.default.yellow("server_execute_unknown_model")}.`);
+    console.log(`    writes to new or changed models. Skip it and writes fail with ${import_picocolors19.default.yellow("server_execute_unknown_model")}.`);
     console.log();
   }
 }
@@ -282684,7 +282829,7 @@ async function ensureInitProject(opts) {
   const ensured = await ensureProject(slug);
   if (ensured) {
     console.log(
-      `  ${import_picocolors18.default.green("\u2713")} ${ensured.created ? "Created" : "Using"} project ${import_picocolors18.default.bold(ensured.slug)} ${import_picocolors18.default.dim(`(${ensured.id})`)} \u2014 keys you mint for it are isolated from the org's other apps.`
+      `  ${import_picocolors19.default.green("\u2713")} ${ensured.created ? "Created" : "Using"} project ${import_picocolors19.default.bold(ensured.slug)} ${import_picocolors19.default.dim(`(${ensured.id})`)} \u2014 keys you mint for it are isolated from the org's other apps.`
     );
   }
 }
@@ -282726,7 +282871,7 @@ async function chooseBool(flagValue, fallback, interactive, prompt) {
 async function init(args = []) {
   const opts = parseInitArgs(args);
   const interactive = Boolean(process.stdin.isTTY) && !opts.yes && !process.env.CI;
-  Ie(`${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}`);
+  Ie(`${brand("ablo")} ${import_picocolors19.default.dim("sync engine")}`);
   if (!(0, import_fs12.existsSync)("package.json")) {
     xe("No package.json found. Run this from your project root.");
     process.exit(1);
@@ -282811,7 +282956,7 @@ async function init(args = []) {
   if (pullExisting) {
     const dbUrl = process.env.DATABASE_URL ?? process.env.ABLO_DATABASE_URL;
     if (!dbUrl) {
-      schemaNote = import_picocolors18.default.dim(" (no DATABASE_URL \u2014 wrote starter; run `ablo pull` later)");
+      schemaNote = import_picocolors19.default.dim(" (no DATABASE_URL \u2014 wrote starter; run `ablo pull` later)");
     } else {
       try {
         const pulled = await buildSchemaSourceFromDb({
@@ -282821,12 +282966,12 @@ async function init(args = []) {
         });
         if (pulled.models.length > 0) {
           schemaSource = pulled.source;
-          schemaNote = import_picocolors18.default.dim(` (pulled ${pulled.models.length} models)`);
+          schemaNote = import_picocolors19.default.dim(` (pulled ${pulled.models.length} models)`);
         } else {
-          schemaNote = import_picocolors18.default.dim(" (no adoptable tables \u2014 wrote starter)");
+          schemaNote = import_picocolors19.default.dim(" (no adoptable tables \u2014 wrote starter)");
         }
       } catch {
-        schemaNote = import_picocolors18.default.dim(" (pull failed \u2014 wrote starter)");
+        schemaNote = import_picocolors19.default.dim(" (pull failed \u2014 wrote starter)");
       }
     }
   }
@@ -282852,14 +282997,14 @@ async function init(args = []) {
     const existing = (0, import_fs12.readFileSync)(envFile, "utf-8");
     if (!existing.includes("ABLO_")) {
       (0, import_fs12.writeFileSync)(envFile, existing + "\n" + envBody);
-      created.push(`${envFile} ${import_picocolors18.default.dim("(appended)")}`);
+      created.push(`${envFile} ${import_picocolors19.default.dim("(appended)")}`);
     } else {
-      created.push(`${envFile} ${import_picocolors18.default.dim("(already configured)")}`);
+      created.push(`${envFile} ${import_picocolors19.default.dim("(already configured)")}`);
     }
   }
   if (wireRealKey && resolvedKey) {
     wireEnvLocal(resolvedKey);
-    created.push(`.env.local ${import_picocolors18.default.dim("(ABLO_API_KEY set from your login)")}`);
+    created.push(`.env.local ${import_picocolors19.default.dim("(ABLO_API_KEY set from your login)")}`);
   }
   if (agent) {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "agent.ts"), generateAgent());
@@ -282874,17 +283019,17 @@ async function init(args = []) {
     }
     const providersPath = (0, import_path7.join)(layout.appBase, "providers.tsx");
     (0, import_fs12.writeFileSync)(providersPath, generateProviders());
-    created.push(`${providersPath} ${import_picocolors18.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
+    created.push(`${providersPath} ${import_picocolors19.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
     const sessionDir = (0, import_path7.join)(layout.appBase, "api", "ablo-session");
     (0, import_fs12.mkdirSync)(sessionDir, { recursive: true });
     (0, import_fs12.writeFileSync)((0, import_path7.join)(sessionDir, "route.ts"), generateSessionRoute());
-    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors18.default.dim("(wire your auth)")}`);
+    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors19.default.dim("(wire your auth)")}`);
   }
   if (framework !== "vanilla") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "TaskList.tsx"), generateComponent());
     created.push(`${abloDir}/TaskList.tsx`);
   }
-  Me(created.map((f) => `${import_picocolors18.default.green("\u2713")} ${f}`).join("\n"), "Created");
+  Me(created.map((f) => `${import_picocolors19.default.green("\u2713")} ${f}`).join("\n"), "Created");
   const pm = detectPackageManager();
   if (opts.install) {
     const s = Y2();
@@ -282893,45 +283038,45 @@ async function init(args = []) {
       (0, import_child_process2.execSync)(`${pm} add @abloatai/ablo`, { stdio: "ignore" });
       s.stop("Installed @abloatai/ablo");
     } catch {
-      s.stop(`${import_picocolors18.default.yellow("!")} Couldn't auto-install \u2014 run ${import_picocolors18.default.bold(`${pm} install @abloatai/ablo`)}`);
+      s.stop(`${import_picocolors19.default.yellow("!")} Couldn't auto-install \u2014 run ${import_picocolors19.default.bold(`${pm} install @abloatai/ablo`)}`);
     }
   }
   const steps = [
-    `Get a ${import_picocolors18.default.bold("sk_test_")} key at ${import_picocolors18.default.cyan("https://abloatai.com")}`,
-    `Run ${import_picocolors18.default.bold("npx ablo login")} (or add ${import_picocolors18.default.bold("ABLO_API_KEY")} to ${import_picocolors18.default.bold(envFile)})`,
-    `Set ${import_picocolors18.default.bold("DATABASE_URL")} in ${import_picocolors18.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
-    `Run ${import_picocolors18.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
+    `Get a ${import_picocolors19.default.bold("sk_test_")} key at ${import_picocolors19.default.cyan("https://abloatai.com")}`,
+    `Run ${import_picocolors19.default.bold("npx ablo login")} (or add ${import_picocolors19.default.bold("ABLO_API_KEY")} to ${import_picocolors19.default.bold(envFile)})`,
+    `Set ${import_picocolors19.default.bold("DATABASE_URL")} in ${import_picocolors19.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
+    `Run ${import_picocolors19.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
     ...storage === "direct" ? [
-      `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
+      `Provision your DB: ${import_picocolors19.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
     ] : [
-      `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors18.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors18.default.bold("/api/ablo/source")}`
+      `Provision your DB: ${import_picocolors19.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors19.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors19.default.bold("/api/ablo/source")}`
     ],
     ...framework === "nextjs" ? [
-      `Wrap ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors18.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
+      `Wrap ${import_picocolors19.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors19.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors19.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
     ] : [],
-    `Run ${import_picocolors18.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
+    `Run ${import_picocolors19.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
     ...agent ? [
-      `Run ${import_picocolors18.default.bold(`npx tsx ${abloDir}/agent.ts`)} \u2014 an AI teammate edits the same tasks`,
-      `Run ${import_picocolors18.default.bold("npx ablo logs")} to watch human + agent commits stream by`
+      `Run ${import_picocolors19.default.bold(`npx tsx ${abloDir}/agent.ts`)} \u2014 an AI teammate edits the same tasks`,
+      `Run ${import_picocolors19.default.bold("npx ablo logs")} to watch human + agent commits stream by`
     ] : []
   ];
   Me(steps.map((s, i) => `${i + 1}. ${s}`).join("\n"), "Next steps");
   const existingKey = resolveApiKey("sandbox");
   if (existingKey) {
     await ensureInitProject(opts);
-    Se(`Already authorized ${import_picocolors18.default.dim(`(${existingKey.slice(0, 11)}\u2026)`)} \u2014 run ${import_picocolors18.default.bold("npx ablo push")} next. ${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+    Se(`Already authorized ${import_picocolors19.default.dim(`(${existingKey.slice(0, 11)}\u2026)`)} \u2014 run ${import_picocolors19.default.bold("npx ablo push")} next. ${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
     return;
   }
   if (interactive && opts.login) {
     const loginNow = await ye({ message: "Log in now? (opens your browser)", initialValue: true });
     if (!pD(loginNow) && loginNow) {
-      Se(`${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+      Se(`${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
       await login();
       await ensureInitProject(opts);
       return;
     }
   }
-  Se(`Run ${import_picocolors18.default.bold("npx ablo login")} when ready. ${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+  Se(`Run ${import_picocolors19.default.bold("npx ablo login")} when ready. ${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
 }
 function generateSchema() {
   return `import { defineSchema, model, relation, z } from '@abloatai/ablo/schema';
@@ -283209,7 +283354,9 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error(err);
+  // Ablo errors stringify to one clean line (code + message + docs link),
+  // never a stack/object dump \u2014 see AbloError.toString().
+  console.error(String(err));
   process.exit(1);
 });
 `;
@@ -283296,22 +283443,33 @@ export function Providers({ children }: { children: React.ReactNode }) {
 `;
 }
 function generateSessionRoute() {
-  return `import { sync } from '@/ablo';
+  return `import { headers } from 'next/headers';
+import { sync } from '@/ablo';
+import { auth } from '@/lib/auth'; // your server-side betterAuth({ ... }) instance
 
 // Mints the browser's session token. The browser never sees your sk_ key \u2014 it
-// only gets this token, which already names your org + the user you assert here.
-// Replace getCurrentUser() with your real auth (NextAuth / Clerk / Better Auth / \u2026).
+// only gets this short-lived token, already scoped to your org + the user you
+// assert here. The browser fetches THIS route at a relative URL
+// ('/api/ablo-session') \u2014 that's correct + best practice (same-origin, cookies
+// flow automatically); the SDK refreshes it in the browser only.
 export async function POST(): Promise<Response> {
-  const user = await getCurrentUser(); // \u2190 your auth: who is making this request?
+  const user = await getCurrentUser();
   if (!user) return new Response('Unauthorized', { status: 401 });
 
   const { token } = await sync.sessions.create({ user: { id: user.id } });
   return Response.json({ token });
 }
 
-// TODO: replace with your auth provider's "current user" lookup.
+// Validate the signed-in user SERVER-SIDE. This ships wired for Better Auth;
+// \`getSession\` is the server method \u2014 pass the request headers (async in current
+// Next.js), it does NOT read cookies implicitly. Using a different provider?
+// Replace the body:
+//   \u2022 NextAuth:  const s = await auth();            return s?.user ? { id: s.user.id } : null;
+//   \u2022 Clerk:     const { userId } = await auth();   return userId ? { id: userId } : null;
+//   \u2022 Supabase:  const { data } = await supabase.auth.getUser(); return data.user ? { id: data.user.id } : null;
 async function getCurrentUser(): Promise<{ id: string } | null> {
-  return null;
+  const session = await auth.api.getSession({ headers: await headers() });
+  return session?.user ? { id: session.user.id } : null;
 }
 `;
 }
@@ -283321,7 +283479,10 @@ function detectPackageManager() {
   if ((0, import_fs12.existsSync)("bun.lockb")) return "bun";
   return "npm";
 }
-main().catch(console.error);
+main().catch((err) => {
+  renderCliError(err);
+  process.exit(process.exitCode ?? 1);
+});
 /*! Bundled license information:
 
 @ts-morph/common/dist/typescript.js:

package/dist/client/Ablo.d.ts

@@ -133,6 +133,22 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims requested / queued / granted / released, agent
+     * handovers, connection state — so you can SEE the human+agent coordination
+     * you built while debugging. Omitted/`false` keeps the quiet default (only
+     * warnings + errors). For a middle ground use {@link logLevel}. Env override:
+     * `ABLO_LOG_LEVEL`. Ignored if a custom logger is supplied.
+     */
+    debug?: boolean | undefined;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
@@ -242,8 +258,24 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `apiKey` only; the server handles capability issuance.
      */
     capabilityToken?: string;
-    /** Custom logger (default: console) */
+    /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
     logger?: SyncLogger;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims acquired / queued / granted / released, agent
+     * handovers, connection state — plus internal lifecycle, so you can SEE the
+     * human+agent coordination you built. Omitted/`false` keeps the quiet default
+     * (only warnings + errors). For a middle ground use {@link logLevel}.
+     * Env override: `ABLO_LOG_LEVEL`. Ignored if a custom {@link logger} is passed.
+     */
+    debug?: boolean;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
     /** ObjectPool size limit (default: 10000) */
     maxPoolSize?: number;
     /**

package/dist/client/Ablo.js

@@ -519,7 +519,17 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
     return ModelClass;
 }
 const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
-function resolveLogLevel() {
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+function resolveLogLevel(opts) {
+    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
+        return opts.logLevel;
+    if (opts?.debug === true)
+        return 'debug';
     // `globalThis.process` guard keeps this safe in browser/edge runtimes that
     // have no `process` binding — there we fall through to the default.
     const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
@@ -528,12 +538,16 @@ function resolveLogLevel() {
         return normalized;
     return 'warn';
 }
-const consoleLogger = (() => {
-    const threshold = LOG_LEVEL_RANK[resolveLogLevel()];
-    const emit = (level, fn, args) => {
-        if (typeof console === 'undefined' || LOG_LEVEL_RANK[level] < threshold)
+/**
+ * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
+ * with a console full of other tools' logs can see at a glance what's ours.
+ */
+function createConsoleLogger(level) {
+    const threshold = LOG_LEVEL_RANK[level];
+    const emit = (lvl, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
             return;
-        fn('[sync]', ...args);
+        fn('[Ablo]', ...args);
     };
     return {
         debug: (...args) => emit('debug', console.debug, args),
@@ -541,7 +555,7 @@ const consoleLogger = (() => {
         warn: (...args) => emit('warn', console.warn, args),
         error: (...args) => emit('error', console.error, args),
     };
-})();
+}
 // `readProcessEnv` lives in `./auth` alongside the other resolvers
 // that read it. Re-exported there for use elsewhere in the file.
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
@@ -725,7 +739,10 @@ export function Ablo(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
-    const { logger = consoleLogger } = internalOptions;
+    // Custom logger wins; otherwise build the default `[Ablo]` logger at the level
+    // resolved from `debug`/`logLevel`/`ABLO_LOG_LEVEL` (default `warn`).
+    const logger = internalOptions.logger ??
+        createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
     warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));

package/dist/client/auth.js

@@ -83,7 +83,7 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
     if (warn)
         warn(message);
     else if (typeof console !== 'undefined')
-        console.warn('[sync]', message);
+        console.warn('[Ablo]', message);
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;

package/dist/core/StoreManager.js

@@ -274,7 +274,9 @@ export class StoreManager {
      * Clear all stores
      */
     async clearAllStores() {
-        getContext().logger.warn('Clearing all stores');
+        // Lifecycle chatter (logout / identity switch / reset) — NOT a warning.
+        // `debug` so it's silent under the default `warn` threshold.
+        getContext().logger.debug('Clearing all stores');
         const promises = Array.from(this.stores.values()).map((store) => store.clear());
         await Promise.all(promises);
         getContext().logger.info('All stores cleared');

package/dist/errors.d.ts

@@ -77,6 +77,15 @@ export declare class AbloError extends Error {
         request_id?: string;
         [key: string]: unknown;
     };
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString(): string;
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention

package/dist/errors.js

@@ -91,6 +91,20 @@ export class AbloError extends Error {
             ...(this.details ?? {}),
         };
     }
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString() {
+        const code = this.code ? ` [${this.code}]` : '';
+        const docs = this.docUrl ? ` (see ${this.docUrl})` : '';
+        const req = this.requestId ? ` [request_id: ${this.requestId}]` : '';
+        return `${this.name}${code}: ${this.message}${docs}${req}`;
+    }
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention

package/dist/index.d.ts

@@ -62,6 +62,8 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
+export type { ErrorEnvelope } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 export type { Environment, KeyPrefixEnvironment } from './environment.js';

package/dist/index.js

@@ -85,6 +85,11 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+// Canonical wire-egress contract (dependency-free): the error envelope shape +
+// the AbloError-subclass→HTTP-status table. Re-exported so server consumers
+// (e.g. apps/sync-server, which keeps its own self-contained copy) can assert
+// against the ONE source instead of silently drifting. See wire/errorEnvelope.ts.
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every

package/dist/policy/types.d.ts

@@ -122,18 +122,32 @@ export type ConflictDecision = {
  */
 export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite(), agentsReject())`
+ * applied to every model — so a developer who wants different behaviour just
+ * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
+ * …) and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `system` → `allow`  — automation principals at the root of a trust chain
+ *                           behave like humans here (matches `mayBypassClaims`)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 export declare const defaultPolicy: (conflict: Conflict) => ConflictDecision;
 /**
@@ -172,8 +186,9 @@ export interface ConflictAxis {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
+ *                   committer is allowed (never blocked), an agent rejects on a
+ *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/policy/types.js

@@ -7,18 +7,32 @@
  * Adding new shapes is additive on the discriminated union.
  */
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite(), agentsReject())`
+ * applied to every model — so a developer who wants different behaviour just
+ * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
+ * …) and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `system` → `allow`  — automation principals at the root of a trust chain
+ *                           behave like humans here (matches `mayBypassClaims`)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 // Typed by its real SYNCHRONOUS shape (via `satisfies`) rather than the
 // async-permissive `ConflictPolicy` alias, so sync callers like
@@ -26,8 +40,14 @@
 // `ConflictDecision` back (not `… | Promise<…>`). Still assignable to
 // `ConflictPolicy` everywhere it's used as a policy.
 export const defaultPolicy = ((conflict) => {
-    if (conflict.kind !== 'stale_context') {
-        return { action: 'reject', reason: 'claim_conflict' };
+    if (conflict.kind === 'claim_held') {
+        // Law 7 universal default: principals (human / system) are never blocked;
+        // agents yield. Keeping `agent → reject` here is what makes the no-bypass
+        // invariant hold even on the registry/default resolution path (which, unlike
+        // the declared-axis path, has no separate agent-degradation guard).
+        return conflict.committer.kind === 'agent'
+            ? { action: 'reject', reason: 'claim_conflict' }
+            : { action: 'allow', note: 'principal:not-blocked' };
     }
     return conflict.requestedMode === 'notify'
         ? { action: 'notify', reason: 'stale_notify_hold' }
@@ -53,8 +73,9 @@ export const capabilityPreemptPolicy = (conflict) => {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
+ *                   committer is allowed (never blocked), an agent rejects on a
+ *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/surface.d.ts

@@ -23,7 +23,7 @@ export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "g
 export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
 /** Public keys of `AbloOptions`. `schema` is required; the rest are optional
  *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -51,6 +51,8 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'databaseUrl',
     'persistence',
     'transport',
+    'debug',
+    'logLevel',
     'authToken',
     'baseURL',
     'fetch',

package/dist/sync/SyncWebSocket.js

@@ -177,7 +177,7 @@ export class SyncWebSocket extends EventEmitter {
         // which is unreliable but the only signal available; in Node it returns true
         // (assume online) so the sidecar/agent path doesn't short-circuit here.
         if (!getContext().onlineStatus.isOnline()) {
-            getContext().logger.warn('onlineStatus reports offline, but attempting connection anyway');
+            getContext().logger.debug('onlineStatus reports offline, but attempting connection anyway');
         }
         this.isConnecting = true;
         this.isManualClose = false;

package/dist/sync/awaitClaimGrant.js

@@ -13,6 +13,7 @@
  * fake; `SyncWebSocket` satisfies it structurally.
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { getContext } from '../context.js';
 export function awaitClaimGrant(transport, claimId, options) {
     return new Promise((resolve, reject) => {
         const unsubs = [];
@@ -28,12 +29,18 @@ export function awaitClaimGrant(transport, claimId, options) {
         // we waited in line, and reached the head → `claim_granted`. Either frame
         // means the lease is now ours; `waited` records which path it was.
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
                 settle(() => resolve({ waited: false }));
+            }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                // Promoted to the head of the line — the creator's "it's the agent's
+                // turn now" moment after waiting behind a holder.
+                getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
                 settle(() => resolve({ waited: true }));
+            }
         }));
         if (options?.maxQueueDepth !== undefined) {
             const max = options.maxQueueDepth;

package/dist/sync/createClaimStream.js

@@ -24,6 +24,11 @@
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
 import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { getContext } from '../context.js';
+/** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
+function claimLabel(type, id, field) {
+    return field ? `${type}:${id}.${field}` : `${type}:${id}`;
+}
 export function createClaimStream(config, transport = null) {
     const { participantId } = config;
     // ── State: others' open claims, keyed by claimId ───────────────
@@ -37,6 +42,9 @@ export function createClaimStream(config, transport = null) {
     const queueByEntity = new Map();
     const entityKey = (type, id) => `${type}:${id}`;
     const EMPTY_QUEUE = Object.freeze([]);
+    // Last queue position we logged per own-claim, so advancing in line is traced
+    // once per change (not re-logged on every server re-fan of the same line).
+    const lastLoggedQueuePos = new Map();
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
@@ -122,6 +130,12 @@ export function createClaimStream(config, transport = null) {
         unsubs.push(t.subscribe('claim_rejected', (rejection) => {
             if (!rejection.claimId)
                 return;
+            if (ownClaims.has(rejection.claimId)) {
+                const tgt = rejection.target
+                    ? claimLabel(rejection.target.entityType, rejection.target.entityId, rejection.target.field)
+                    : rejection.claimId;
+                getContext().logger.info(`claim: rejected ${tgt}${rejection.heldBy ? ` — held by ${rejection.heldBy}` : ''}`, { claimId: rejection.claimId, reason: rejection.reason });
+            }
             // Drop the rejected own-claim so reconnect doesn't re-announce
             // a claim the server already rejected (would just spam both
             // sides with conflicts).
@@ -141,6 +155,10 @@ export function createClaimStream(config, transport = null) {
             const lost = payload;
             if (!lost.claimId)
                 return;
+            if (ownClaims.has(lost.claimId)) {
+                const c = ownClaims.get(lost.claimId);
+                getContext().logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });
+            }
             // Drop the lost own-claim so reconnect doesn't re-announce a lease we
             // no longer hold.
             ownClaims.delete(lost.claimId);
@@ -166,6 +184,16 @@ export function createClaimStream(config, transport = null) {
                 queueByEntity.delete(key);
             else
                 queueByEntity.set(key, Object.freeze([...line]));
+            // If WE are in this line, trace our position (the "agent queued behind a
+            // claim" moment) — once per position change, so advancing is visible.
+            const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
+            if (ourIndex >= 0) {
+                const ourId = line[ourIndex].id;
+                if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
+                    lastLoggedQueuePos.set(ourId, ourIndex);
+                    getContext().logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });
+                }
+            }
             notifyListeners();
         }));
         // (3) On reconnect, re-announce every open self-claim — the
@@ -251,6 +279,9 @@ export function createClaimStream(config, transport = null) {
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
+        // Coordination trace (info): the creator can SEE their human/agent claims.
+        getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
+            (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
         const revoke = () => {
             if (revoked)
@@ -258,6 +289,7 @@ export function createClaimStream(config, transport = null) {
             revoked = true;
             ownClaims.delete(claimId);
             sendAbandon(claimId, claim);
+            getContext().logger.info(`claim: released ${claimLabel(claim.entityType, claim.entityId, claim.field)}`, { claimId });
         };
         return {
             object: 'claim',

package/dist/wire/errorEnvelope.d.ts

@@ -8,6 +8,19 @@ export interface ErrorEnvelope {
     readonly message: string;
     readonly doc_url?: string;
     readonly request_id?: string;
+    /** Aggregate field-level failures — so one 4xx can report EVERY invalid input
+     *  at once (schema push, batch commit, CLI-arg validation) instead of failing
+     *  on the first. `param` stays the single-field convenience case. (RFC 9457
+     *  `errors[]` / JSON:API `errors[]` / Google `BadRequest.fieldViolations[]`.) */
+    readonly errors?: ReadonlyArray<{
+        readonly code?: string;
+        readonly message: string;
+        readonly param?: string;
+    }>;
+    /** Typed-details slot: `AbloError.toJSON()` spreads its `details` (e.g.
+     *  `missingIds`, `conflicts`, `retryAfterSeconds`) as top-level members.
+     *  Consumers MUST ignore members they don't recognize (forward-compat). */
+    readonly [key: string]: unknown;
 }
 /** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
  *  match status semantics (a validation error is a 400, a permission error a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",