@versionone/agility-sdk 1.0.0-alpha.0 → 1.0.0-alpha.3

package/dist/index.cjs

@@ -35,6 +35,8 @@ __export(index_exports, {
   TypeCache: () => TypeCache,
   UNGUARDABLE_TYPES: () => UNGUARDABLE_TYPES,
   UnguardableError: () => UnguardableError,
+  UsageError: () => UsageError,
+  WrappedError: () => WrappedError,
   assetApi: () => assetApi_exports,
   assetStateOf: () => assetStateOf,
   attachment: () => attachment_exports,
@@ -43,11 +45,13 @@ __export(index_exports, {
   guard: () => guard,
   isAssetNumber: () => isAssetNumber,
   isOidToken: () => isOidToken,
+  kindOf: () => kindOf,
   loc2: () => loc2_exports,
   meta: () => meta_exports,
   momentless: () => momentless,
   namesOf: () => namesOf,
   parseOid: () => parseOid,
+  parseViolation: () => parseViolation,
   queryV1: () => queryV1_exports,
   resolveNumbers: () => resolveNumbers,
   resolveRef: () => resolveRef,
@@ -67,16 +71,61 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/core/errors.ts
+function kindOf(status, code) {
+  switch (code) {
+    case "ABORTED":
+      return "aborted";
+    case "TIMEOUT":
+    case "NETWORK_ERROR":
+      return "transient";
+    case "BAD_JSON":
+    case "BAD_RESPONSE":
+      return "protocol";
+    case "USAGE":
+      return "usage";
+    case "CommandFailure":
+      return "commandFailure";
+    case "QUERY_REJECTED":
+    case "TOO_LARGE":
+      return "invalid";
+    case "NOT_FOUND":
+      return "notFound";
+  }
+  if (status === 401) return "auth";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "notFound";
+  if (status === 408 || status === 429 || status >= 500) return "transient";
+  if (status >= 400) return "invalid";
+  return "unknown";
+}
+var causeOf = (details) => details && typeof details === "object" && "cause" in details ? details.cause : void 0;
 var ApiError = class extends Error {
+  /** The HTTP status; 0 when no answer came back (network, timeout, abort, usage). */
   status;
   code;
   details;
-  constructor(message, status, code, details) {
-    super(message);
+  kind;
+  constructor(message, status, code, details, kind = kindOf(status, code)) {
+    const cause = causeOf(details);
+    super(message, cause === void 0 ? void 0 : { cause });
     this.name = "ApiError";
     this.status = status;
     this.code = code;
     this.details = details;
+    this.kind = kind;
+  }
+};
+var UsageError = class extends ApiError {
+  constructor(message, details) {
+    super(message, 0, "USAGE", details, "usage");
+    this.name = "UsageError";
+  }
+};
+var WrappedError = class extends ApiError {
+  constructor(message, code, cause, details) {
+    const inner = cause instanceof ApiError ? cause : void 0;
+    super(message, inner?.status ?? 0, code, { ...details, cause }, inner?.kind ?? "unknown");
+    this.name = "WrappedError";
   }
 };
 
@@ -216,7 +265,7 @@ function isOidToken(value) {
 }
 function parseOid(token) {
   const m = OID_TOKEN.exec(token);
-  if (!m) throw new Error(`"${token}" is not an OID token (Story:1234)`);
+  if (!m) throw new UsageError(`"${token}" is not an OID token (Story:1234)`);
   return { type: m[1], id: Number(m[2]), moment: m[3] === void 0 ? null : Number(m[3]) };
 }
 function momentless(token) {
@@ -240,6 +289,7 @@ __export(assetApi_exports, {
   mergeOutcome: () => mergeOutcome,
   momentless: () => momentless,
   outcomeOf: () => outcomeOf,
+  parseViolation: () => parseViolation,
   preview: () => preview,
   queries: () => queries,
   query: () => query,
@@ -405,11 +455,20 @@ function toNumber(value) {
   const n = typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
   return Number.isNaN(n) ? value : n;
 }
+function parseViolation(message) {
+  const parts = message.trim().split("'");
+  if (parts[0] !== "Violation" || !parts[1]) return null;
+  const rule = parts[1], rest = parts.slice(2).filter((p) => p !== "");
+  if (rest[0] === "AttributeDefinition" && rest[1] && rest[2]) return { rule, attribute: `${rest[2]}.${rest[1]}`, tag: rest.join("'") };
+  const token = rest.length === 1 && /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9_]*$/.test(rest[0]) ? rest[0] : null;
+  return { rule, attribute: token, tag: rest.length ? rest.join("'") : null };
+}
 function failuresOf(response) {
   return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => ({
     index: typeof error === "object" && error && typeof error.sourceCommandIndex === "number" ? error.sourceCommandIndex : null,
     message: typeof error === "string" ? error : error?.message || "command failed",
-    echoed
+    echoed,
+    violation: parseViolation(typeof error === "string" ? error : error?.message || "")
   }));
 }
 function outcomeOf(response) {
@@ -435,11 +494,14 @@ function mergeOutcome(into, done, offset) {
 var CommandFailureError = class extends ApiError {
   failures;
   response;
+  /** What the batch did, in the model's terms: the commands that succeeded are committed. */
+  outcome;
   constructor(response, failures = failuresOf(response)) {
     super(failures.map((f) => f.message).join("; ") || "command failed", 200, "CommandFailure", failures);
     this.name = "CommandFailureError";
     this.failures = failures;
     this.response = response;
+    this.outcome = outcomeOf(response);
   }
 };
 var bodyOf = (c) => {
@@ -475,7 +537,7 @@ async function send(transport, commands, options = {}) {
   const results = response.queryResult?.results ?? [];
   let aligned = realign(queries3, results, failed);
   if (!aligned) {
-    if (!failures.some((f) => f.index === null)) throw new Error(`api/asset returned ${results.length} query results for ${queries3.filter((q) => !failed.has(q.index)).length} queries that did not fail; cannot tell which result belongs to which query`);
+    if (!failures.some((f) => f.index === null)) throw new ApiError(`api/asset returned ${results.length} query results for ${queries3.filter((q) => !failed.has(q.index)).length} queries that did not fail; cannot tell which result belongs to which query`, 200, "BAD_RESPONSE", response);
     aligned = queries3.map(() => null);
   }
   const contextOf = (i) => {
@@ -497,7 +559,7 @@ async function query(transport, q, options = {}) {
   return rows ?? [];
 }
 async function queryPage(transport, q, options = {}) {
-  if (!q.page) throw new Error(`query of ${q.from} without a page: every api/asset read must be bounded`);
+  if (!q.page) throw new UsageError(`query of ${q.from} without a page: every api/asset read must be bounded`);
   const response = await send(transport, [{ ...q, needTotal: true }], { ...options, throwOnFailure: true });
   const rows = response.queryResult.results[0] ?? [];
   const reported = response.queryResult.resultMetaData?.[0]?.total;
@@ -505,7 +567,7 @@ async function queryPage(transport, q, options = {}) {
   return { rows, total, more: total === null ? rows.length === q.page.size : q.page.start + rows.length < total };
 }
 async function queries(transport, qs, options = {}) {
-  for (const q of qs) if (!q.page) throw new Error(`query of ${q.from} without a page: every api/asset read must be bounded`);
+  for (const q of qs) if (!q.page) throw new UsageError(`query of ${q.from} without a page: every api/asset read must be bounded`);
   const response = await send(transport, qs, { ...options, throwOnFailure: true });
   return qs.map((_, i) => response.queryResult.results[i] ?? []);
 }
@@ -543,7 +605,7 @@ function fromBase64(text) {
 }
 function numericId(spec) {
   const m = /^(?:[A-Za-z]+:)?(\d+)(?::\d+)?$/.exec(String(spec).trim());
-  if (!m) throw new TypeError(`"${spec}" is not an asset id (5678, or an OID token such as Attachment:5678)`);
+  if (!m) throw new UsageError(`"${spec}" is not an asset id (5678, or an OID token such as Attachment:5678)`);
   return m[1];
 }
 var join = (baseUrl, path) => `${baseUrl.replace(/\/+$/, "")}/${path}`;
@@ -639,9 +701,9 @@ async function get(transport, id) {
   const file = await getFile(transport, meta.id);
   return { ...meta, bytes: file.bytes, contentType: file.contentType ?? meta.contentType, recordedContentType: meta.contentType };
 }
-var AttachmentUploadError = class extends Error {
+var AttachmentUploadError = class extends WrappedError {
   constructor(attachment, cause) {
-    super(`${attachment.oid} was created on its asset with no content, and uploading the file failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    super(`${attachment.oid} was created on its asset with no content, and uploading the file failed: ${cause instanceof Error ? cause.message : String(cause)}`, "ATTACHMENT_UPLOAD", cause);
     this.attachment = attachment;
     this.name = "AttachmentUploadError";
   }
@@ -674,7 +736,7 @@ async function remove(transport, id) {
 // src/services/guard.ts
 var CHUNK = 100;
 var UNGUARDABLE_TYPES = ["Idea", "IdeaChangeSet", "IdeaStatus", "IdeaComment", "IdeaCategory", "IdeaForum", "IdeaUser"];
-var UnguardableError = class extends Error {
+var UnguardableError = class extends UsageError {
   reasons;
   constructor(reasons) {
     super(`cannot guard this batch: ${reasons.map((r) => `command ${r.index}: ${r.reason}`).join("; ")}`);
@@ -740,7 +802,7 @@ function guard(projected, stamps) {
       unstamped.push(x.oid);
       continue;
     }
-    if (!STAMP.test(stamp)) throw new Error(`${x.oid}: ChangeDate ${JSON.stringify(stamp)} is not a timestamp; refusing to put it in a filter`);
+    if (!STAMP.test(stamp)) throw new ApiError(`${x.oid}: ChangeDate ${JSON.stringify(stamp)} is not a timestamp; refusing to put it in a filter`, 200, "BAD_RESPONSE", { oid: x.oid, stamp });
     const scope = { from: typeOfOid(x.oid), filter: ["ID=$oid", `ChangeDate='${stamp}'`], with: { $oid: x.oid } };
     commands.push(x.update ? { ...scope, update: x.update } : { ...scope, execute: x.execute });
   }
@@ -757,16 +819,14 @@ function passesOf(projected) {
   }
   return passes;
 }
-var GuardedPassError = class extends Error {
+var GuardedPassError = class extends WrappedError {
   constructor(cause, outcome, sent, pass) {
-    super(`guarded send failed in pass ${pass + 1}${pass ? " (earlier passes applied)" : ""}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-    this.cause = cause;
+    super(`guarded send failed in pass ${pass + 1}${pass ? " (earlier passes applied)" : ""}: ${cause instanceof Error ? cause.message : String(cause)}`, "GUARDED_PASS", cause);
     this.outcome = outcome;
     this.sent = sent;
     this.pass = pass;
     this.name = "GuardedPassError";
   }
-  cause;
   outcome;
   sent;
   pass;
@@ -889,9 +949,46 @@ async function snapshot(transport, described) {
   }
   return before;
 }
-var INVERSE = { Inactivate: "Reactivate", Reactivate: "Inactivate", Delete: "Undelete", Undelete: "Delete" };
-function reverseOf(described, before, done) {
+var INVERSE = { Inactivate: "Reactivate", QuickClose: "Reactivate", Reactivate: "Inactivate", Delete: "Undelete", Undelete: "Delete" };
+var CASCADING = /* @__PURE__ */ new Set(["Inactivate", "QuickClose"]);
+var CASCADE_DEPTH = 8;
+async function openDescendantsOf(transport, schema, roots) {
+  const out = {};
+  const rootOf = new Map(roots.map((r) => [momentless(r), momentless(r)]));
+  const seen = new Set(rootOf.keys());
+  let frontier = [...rootOf.keys()];
+  for (let depth = 0; depth < CASCADE_DEPTH && frontier.length; depth += 1) {
+    const children = /* @__PURE__ */ new Map();
+    for (const [type, list3] of byType(frontier)) {
+      await schema.load(type);
+      if (!schema.attribute(type, "Children")) continue;
+      for (const part of chunks(list3)) {
+        const rows = await query(transport, { from: type, select: ["Children"], filter: ["ID=$oids"], with: { $oids: part }, page: { size: part.length, start: 0 } });
+        for (const r of rows) {
+          const parent = momentless(r._oid);
+          for (const c of [].concat(plain(r.Children) ?? [])) {
+            const child = momentless(String(c));
+            if (seen.has(child)) continue;
+            seen.add(child);
+            children.set(child, rootOf.get(parent));
+          }
+        }
+      }
+    }
+    const states = children.size ? await statesOf(transport, [...children.keys()]) : {};
+    frontier = [];
+    for (const [child, root] of children) {
+      if (states[child] === void 0 || isClosed(states[child])) continue;
+      rootOf.set(child, root);
+      (out[root] ??= []).push(child);
+      frontier.push(child);
+    }
+  }
+  return out;
+}
+function reverseOf(described, before, done, context = {}) {
   const commands = [], notes = [];
+  const cannot = (oid, op) => context.canOperate?.(typeOfOid(oid), op) === false;
   const modified = new Set(done.modified.map(momentless)), operated = new Set(done.operated.map(momentless));
   for (const u of described.updates) {
     if (!modified.has(u.oid)) continue;
@@ -916,26 +1013,48 @@ function reverseOf(described, before, done) {
   for (const e of described.executes) {
     if (!operated.has(e.oid)) continue;
     const inverse = INVERSE[e.op];
-    if (inverse) commands.push({ from: e.oid, execute: inverse });
-    else notes.push(`${e.oid}: ${e.op} has no known inverse (was ${String(before[e.oid]?.AssetState ?? "?")})`);
+    if (!inverse) {
+      notes.push(`${e.oid}: ${e.op} has no known inverse (was ${String(before[e.oid]?.AssetState ?? "?")})`);
+      continue;
+    }
+    if (cannot(e.oid, inverse)) {
+      notes.push(`${e.oid}: ${typeOfOid(e.oid)} has no ${inverse} operation, so its ${e.op} is not reversed`);
+      continue;
+    }
+    commands.push({ from: e.oid, execute: inverse });
+    if (!CASCADING.has(e.op)) continue;
+    const open = context.openDescendants?.[e.oid] ?? [];
+    const closed = context.cascaded ? context.cascaded[e.oid] ?? [] : void 0;
+    if (closed === void 0) {
+      if (open.length) notes.push(`${e.oid}: ${e.op} may also have closed ${open.length} open descendant${open.length === 1 ? "" : "s"} (${open.join(", ")}); they could not be read back, so they are not reopened`);
+      continue;
+    }
+    for (const d of closed) {
+      if (cannot(d, "Reactivate")) notes.push(`${d}: closed with ${e.oid}, but ${typeOfOid(d)} has no Reactivate operation`);
+      else commands.push({ from: d, execute: "Reactivate" });
+    }
+    if (closed.length) notes.push(`${e.oid}: ${e.op} also closed ${closed.join(", ")}; reopened after it`);
+  }
+  for (const oid of [...done.created].reverse().map(momentless)) {
+    if (cannot(oid, "Delete")) notes.push(`${oid}: ${typeOfOid(oid)} has no Delete operation, so it is not deleted${typeOfOid(oid) === "Conversation" ? " (the server removes a Conversation once its last Expression is deleted)" : ""}`);
+    else commands.push({ from: oid, execute: "Delete" });
   }
-  for (const oid of [...done.created].reverse()) commands.push({ from: momentless(oid), execute: "Delete" });
   for (const d of described.deferred ?? []) notes.push(`command ${d.index} (${d.alias}): an aliased ${d.kind} of ${d.from}, sent as written with no snapshot; not reversed`);
   if (commands.length) notes.unshift("restores the state recorded at snapshotAt; anything that changed between then and sentAt is not reflected, and a scalar restored to null is cleared, not unset");
   return { commands, notes };
 }
-var BatchRecordError = class extends Error {
+var BatchRecordError = class extends WrappedError {
   receipt;
   constructor(cause, receipt) {
-    super(`the batch was sent and its outcome recorded, but reading the assets back afterwards failed, so receipt.after is incomplete: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    super(`the batch was sent and its outcome recorded, but reading the assets back afterwards failed, so receipt.after is incomplete: ${cause instanceof Error ? cause.message : String(cause)}`, "BATCH_RECORD", cause);
     this.name = "BatchRecordError";
     this.receipt = receipt;
   }
 };
-var BatchSendError = class extends Error {
+var BatchSendError = class extends WrappedError {
   receipt;
   constructor(cause, receipt) {
-    super(`the batch send failed; whether the server applied it is unknown: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    super(`the batch send failed; whether the server applied it is unknown: ${cause instanceof Error ? cause.message : String(cause)}`, "BATCH_SEND", cause);
     this.name = "BatchSendError";
     this.receipt = receipt;
   }
@@ -943,7 +1062,7 @@ var BatchSendError = class extends Error {
 var now = () => (/* @__PURE__ */ new Date()).toISOString();
 async function runBatch(transport, schema, commands, options = {}) {
   const useGuard = options.guard ?? true;
-  if (!commands.length) throw new Error("the batch is empty");
+  if (!commands.length) throw new UsageError("the batch is empty");
   const refused = unguardable(commands);
   const fatal = refused.filter((r) => r.reason.includes("rejected by the server"));
   if (fatal.length || useGuard && refused.length) throw new UnguardableError(useGuard ? refused : fatal);
@@ -954,12 +1073,14 @@ async function runBatch(transport, schema, commands, options = {}) {
   const described = describe(commands, projected);
   const touched = touchedBy(projected);
   const names = await namesOf(transport, schema, touched, noteFailure);
-  const receipt = { receipt: 1, request: commands, previewedAt, preview: projected, described, names: Object.fromEntries(names), before: {}, sent: false, guarded: false, created: [], touched: [], after: {}, skipped: [], reverse: { commands: [], notes: [] }, notes };
+  const receipt = { receipt: 1, request: commands, previewedAt, preview: projected, described, names: Object.fromEntries(names), before: {}, sent: false, guarded: false, created: [], touched: [], after: {}, skipped: [], failed: [], openDescendants: {}, cascaded: {}, reverse: { commands: [], notes: [] }, notes };
   const nothing = !described.creates.length && !described.updates.length && !described.executes.length && !described.queries.length && !described.deferred.length;
   if (nothing) return receipt;
   for (const d of described.deferred) notes.push(`command ${d.index} (${d.alias}): an aliased ${d.kind}, which preview does not expand; sent as written, not snapshotted, not reversible`);
   receipt.snapshotAt = now();
   receipt.before = await snapshot(transport, described);
+  const closing = described.executes.filter((e) => CASCADING.has(e.op)).map((e) => e.oid);
+  if (closing.length) receipt.openDescendants = await openDescendantsOf(transport, schema, closing);
   if (options.dryRun) return receipt;
   if (options.confirm && !await options.confirm(receipt)) return receipt;
   let unstamped = [];
@@ -991,13 +1112,29 @@ async function runBatch(transport, schema, commands, options = {}) {
   const unnamed = { number: null, name: null };
   receipt.created = done.created.map((oid, i) => ({ alias: described.creates[i]?.alias ?? null, type: described.creates[i]?.type ?? typeOfOid(oid), oid, ...unnamed }));
   receipt.touched = hit.map((oid) => ({ oid, ...names.get(oid) ?? unnamed }));
-  receipt.skipped = useGuard ? [.../* @__PURE__ */ new Set([...unstamped, ...touched.filter((oid) => !hit.includes(oid))])] : [];
-  receipt.reverse = reverseOf(described, receipt.before, done);
+  const sentAs = receipt.sentCommands ?? [];
+  const oidOfSent = (i) => {
+    const body = i === null ? void 0 : sentAs[i] ? bodyOf3(sentAs[i]) : void 0;
+    const id = body?.with?.$oid ?? body?.from;
+    return typeof id === "string" && id.includes(":") ? momentless(id) : null;
+  };
+  receipt.failed = [...new Set(done.failures.map((f) => oidOfSent(f.index)).filter((oid) => !!oid && touched.includes(oid) && !hit.includes(oid)))];
+  receipt.skipped = useGuard ? [.../* @__PURE__ */ new Set([...unstamped, ...touched.filter((oid) => !hit.includes(oid) && !receipt.failed.includes(oid))])] : [];
+  for (const type of new Set([...done.created, ...hit].map((oid) => typeOfOid(momentless(oid))))) await schema.load(type).catch(() => null);
+  const canOperate = (type, op) => schema.canOperate(type, op);
+  const operatedNow = new Set(done.operated.map(momentless));
+  const closed = Object.keys(receipt.openDescendants).filter((oid) => operatedNow.has(oid) && receipt.openDescendants[oid].length);
+  receipt.reverse = reverseOf(described, receipt.before, done, { openDescendants: receipt.openDescendants, cascaded: closed.length ? void 0 : {}, canOperate });
   try {
+    if (closed.length) {
+      const states = await statesOf(transport, closed.flatMap((oid) => receipt.openDescendants[oid]));
+      receipt.cascaded = Object.fromEntries(closed.map((oid) => [oid, receipt.openDescendants[oid].filter((d) => isClosed(states[d]))]));
+      receipt.reverse = reverseOf(described, receipt.before, done, { openDescendants: receipt.openDescendants, cascaded: receipt.cascaded, canOperate });
+    }
     const more = await namesOf(transport, schema, [...done.created, ...hit.filter((oid) => !names.has(oid))], noteFailure);
     receipt.created = receipt.created.map((c) => ({ ...c, ...more.get(c.oid) ?? unnamed }));
     receipt.touched = receipt.touched.map((t) => names.has(t.oid) ? t : { ...t, ...more.get(t.oid) ?? unnamed });
-    const all = [...done.created, ...hit];
+    const all = [.../* @__PURE__ */ new Set([...done.created, ...hit, ...Object.values(receipt.cascaded).flat()])];
     receipt.after = all.length ? await stampsOf(transport, all) : {};
   } catch (error) {
     throw new BatchRecordError(error, receipt);
@@ -1096,7 +1233,7 @@ async function resolveNumbers(transport, numbers, options = {}) {
   for (const n of numbers) if (!firsts.has(n.trim().toUpperCase())) firsts.set(n.trim().toUpperCase(), n.trim());
   const asked = [...firsts.values()];
   const invalid = asked.filter((n) => !isAssetNumber(n));
-  if (invalid.length) throw new TypeError(`not asset numbers (expected a prefix and digits, S-1234): ${invalid.join(", ")}`);
+  if (invalid.length) throw new UsageError(`not asset numbers (expected a prefix and digits, S-1234): ${invalid.join(", ")}`);
   const byNumber = /* @__PURE__ */ new Map();
   for (let i = 0; i < asked.length; i += CHUNK3) {
     for (const r of await askRoots(transport, asked.slice(i, i + CHUNK3), options.types)) {
@@ -1117,7 +1254,7 @@ async function resolveRef(transport, spec, options = {}) {
     return { number: null, oid, type: typeOfOid(oid), name: null, assetState: null };
   }
   if (isAssetNumber(text)) return (await resolveNumbers(transport, [text], options)).found[0] ?? null;
-  throw new TypeError(`"${spec}" is neither an asset number (S-1234) nor an OID token (Story:1234)`);
+  throw new UsageError(`"${spec}" is neither an asset number (S-1234) nor an OID token (Story:1234)`);
 }
 
 // src/wire/meta.ts
@@ -1161,7 +1298,8 @@ function toAssetType(doc) {
     ...doc.DefaultOrderBy ? { DefaultOrderBy: doc.DefaultOrderBy.tokenref } : {},
     ...doc.DefaultDisplayBy ? { DefaultDisplayBy: doc.DefaultDisplayBy.tokenref } : {},
     ...doc.ShortName ? { ShortName: doc.ShortName.tokenref } : {},
-    Attributes: Object.fromEntries(Object.entries(doc.Attributes ?? {}).map(([key, value]) => [key, toAttributeDefinition(value)]))
+    Attributes: Object.fromEntries(Object.entries(doc.Attributes ?? {}).map(([key, value]) => [key, toAttributeDefinition(value)])),
+    ...doc.Operations ? { Operations: Object.keys(doc.Operations).map((token) => token.slice(token.indexOf(".") + 1)) } : {}
   };
 }
 function toMetamodel(doc) {
@@ -1178,7 +1316,7 @@ async function getAssetType(transport, token) {
 }
 async function getAttributeDefinition(transport, tokenref) {
   const [type, attribute] = tokenref.split(".");
-  if (!type || !attribute) throw new Error(`"${tokenref}" is not an attribute token ("Story.Name")`);
+  if (!type || !attribute) throw new UsageError(`"${tokenref}" is not an attribute token ("Story.Name")`);
   return toAttributeDefinition(await transport.request({ method: "GET", path: `/meta.v1/${encodeURIComponent(type)}/${encodeURIComponent(attribute)}`, responseType: "json" }));
 }
 
@@ -1225,6 +1363,15 @@ var Schema = class _Schema {
   attribute(type, name) {
     return attributeOf(this, type, name);
   }
+  /**
+   * Can the type do this operation (Delete, Reactivate, …)? Undefined when
+   * the type is not loaded or its definition carries no operations, so a
+   * caller can tell "no" from "don't know".
+   */
+  canOperate(type, op) {
+    const t = this.assetType(type);
+    return t?.Operations ? t.Operations.includes(op) : void 0;
+  }
   /** The tokens loaded so far. */
   get loaded() {
     return [...this.types.entries()].filter(([, t]) => t !== null).map(([token]) => token);
@@ -1296,7 +1443,7 @@ async function localize(transport, tags, options = {}) {
   const encoded = encodeURIComponent(toLson(unique));
   const headers = options.culture ? { "Accept-Language": options.culture } : void 0;
   const result = encoded.length <= (options.maxGetLength ?? DEFAULT_MAX_GET_LENGTH) ? await transport.request({ method: "GET", path: `/loc-2.v1?${encoded}`, headers, responseType: "json" }) : await transport.request({ method: "POST", path: "/loc-2.v1", headers, body: encoded, contentType: "application/x-www-form-urlencoded", responseType: "json", idempotent: true });
-  if (!result || typeof result !== "object" || Array.isArray(result)) throw new Error(`loc-2.v1 answered an array of tags with ${JSON.stringify(result)?.slice(0, 100)}, not an object`);
+  if (!result || typeof result !== "object" || Array.isArray(result)) throw new ApiError(`loc-2.v1 answered an array of tags with ${JSON.stringify(result)?.slice(0, 100)}, not an object`, 200, "BAD_RESPONSE", result);
   return result;
 }
 async function localizeOne(transport, tag, options = {}) {
@@ -1316,7 +1463,7 @@ function rejected(error) {
   return messages.length ? new ApiError(messages.join("; "), error.status, "QUERY_REJECTED", error.details) : error;
 }
 async function queries2(transport, qs, options = {}) {
-  for (const q of qs) if (!q.page) throw new Error(`query of ${q.from} without a page: every query.v1 read must be bounded`);
+  for (const q of qs) if (!q.page) throw new UsageError(`query of ${q.from} without a page: every query.v1 read must be bounded`);
   if (!qs.length) return [];
   let response;
   try {
@@ -1377,8 +1524,8 @@ function fromAssetDocument(doc, { history: history2 = false } = {}) {
 }
 function toQuery(params) {
   return {
-    sel: params.sel?.join(","),
-    where: params.where?.length ? params.where.join(";") : void 0,
+    sel: (params.select ?? params.sel)?.join(","),
+    where: (params.filter ?? params.where)?.length ? (params.filter ?? params.where).join(";") : void 0,
     with: params.with ? Object.entries(params.with).map(([k, v]) => `${k}=${[].concat(v).join(",")}`).join("|") : void 0,
     find: params.find,
     findin: params.findin?.join(","),
@@ -1390,14 +1537,14 @@ function toQuery(params) {
   };
 }
 async function read(transport, path, params, history2) {
-  if (!params.page) throw new Error(`rest-1 read of ${path} without a page: every read must be bounded`);
+  if (!params.page) throw new UsageError(`rest-1 read of ${path} without a page: every read must be bounded`);
   const doc = await transport.request({ method: "GET", path, query: toQuery(params), responseType: "json" });
   return { rows: (doc.Assets ?? []).map((a) => fromAssetDocument(a, { history: history2 })), total: typeof doc.total === "number" && doc.total >= 0 ? doc.total : null, pageSize: doc.pageSize, pageStart: doc.pageStart };
 }
 var list2 = (transport, type, params) => read(transport, `/rest-1.v1/Data/${encodeURIComponent(type)}`, params, false);
-async function get2(transport, oid, sel) {
+async function get2(transport, oid, select) {
   const [type, id] = momentless(oid).split(":");
-  const doc = await transport.request({ method: "GET", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { sel: sel?.join(",") }, responseType: "json" });
+  const doc = await transport.request({ method: "GET", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { sel: select?.join(",") }, responseType: "json" });
   return fromAssetDocument(doc);
 }
 var history = (transport, target, params) => {
@@ -1407,6 +1554,8 @@ var history = (transport, target, params) => {
 };
 
 // src/client.ts
+var DEFAULT_LIMIT = 1e3;
+var ME_SELECT = ["Name", "Username", "Nickname", "Email"];
 var AgilityApiClient = class _AgilityApiClient {
   transport;
   schema;
@@ -1438,6 +1587,48 @@ var AgilityApiClient = class _AgilityApiClient {
     const transport = { request: (options) => base.request({ ...options, signal: options.signal ?? signal }) };
     return new _AgilityApiClient(this.config, { transport, schema: this.schema });
   }
+  async query(q) {
+    await this.schema.ensureFor([q]);
+    return query2(this.transport, q, { lookup: this.schema });
+  }
+  async queries(qs) {
+    await this.schema.ensureFor(qs);
+    return queries2(this.transport, [...qs], { lookup: this.schema });
+  }
+  async get(oid, select) {
+    const rows = await this.query({ from: momentless(oid), ...select ? { select } : {}, page: { size: 1, start: 0 } });
+    return rows[0] ?? null;
+  }
+  async queryPage(q) {
+    await this.schema.ensureFor([q]);
+    return queryPage(this.transport, q, { lookup: this.schema });
+  }
+  async *pages(q, options = {}) {
+    if (!q.page) throw new UsageError(`query of ${q.from} without a page: every read must be bounded`);
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const size = q.page.size;
+    let start = q.page.start, read2 = 0;
+    while (read2 < limit) {
+      const want = Math.min(size, limit - read2);
+      const rows = await this.query({ ...q, page: { size: want, start } });
+      if (rows.length) yield rows;
+      read2 += rows.length;
+      start += rows.length;
+      if (rows.length < want) return;
+    }
+  }
+  async all(q, options = {}) {
+    const out = [];
+    for await (const page2 of this.pages(q, options)) out.push(...page2);
+    return out;
+  }
+  /** The member these credentials belong to (Member.IsSelf, live 2026-11-12): what a comment's Author is. */
+  async me() {
+    const [row] = await this.query({ from: "Member", select: ME_SELECT, filter: ["IsSelf='true'"], page: { size: 1, start: 0 } });
+    if (!row) throw new ApiError("the server knows no member for these credentials", 0, "NOT_FOUND");
+    return row;
+  }
+  // ---- the endpoints behind the reads -----------------------------------------------
   /** meta.v1: the instance's schema, raw. (The translated, cached view is `schema`.) */
   meta = {
     metamodel: () => getMetamodel(this.transport),
@@ -1446,12 +1637,65 @@ var AgilityApiClient = class _AgilityApiClient {
   };
   /**
    * loc-2.v1: labels for tags, in one request (meta's DisplayName values are
-   * tags). An unmatched tag comes back as itself; the server never says
-   * "missing", so neither does this.
+   * tags, and so is a violation's `tag`). An unmatched tag comes back as
+   * itself; the server never says "missing", so neither does this.
    */
   localize(tags, options) {
     return localize(this.transport, tags, options);
   }
+  /**
+   * rest-1.v1, for what query.v1 cannot do: deleted assets (`deleted:
+   * true`), one asset by OID without a page, and history (one row per
+   * moment). Parameters are spelled as a query's (`select`, `filter`).
+   */
+  data = {
+    list: (type, params) => list2(this.transport, type, params),
+    get: (oid, select) => get2(this.transport, oid, select),
+    history: (target, params) => history(this.transport, target, params)
+  };
+  /** @deprecated since 1.0.0-alpha.3: `client.query` / `client.queries` read through query.v1. Removed in 1.0.0. */
+  queryV1 = {
+    query: (q) => this.query(q),
+    queries: (qs) => this.queries(qs)
+  };
+  // ---- writes -----------------------------------------------------------------------
+  /** api/asset: batches, answered in the model's terms. */
+  assets = {
+    /**
+     * Send a batch. The Outcome says what it did — created, modified and
+     * operated OIDs, failures by index (each with its parsed violation),
+     * query rows per query command — and never the envelope. api/asset
+     * commits per command and answers 200 either way, so a failed command
+     * is in `failures`, or thrown as a CommandFailureError with
+     * `throwOnFailure` (the error carries the same Outcome).
+     */
+    send: async (commands, options) => {
+      await this.schema.ensureFor(commands);
+      return outcomeOf(await send(this.transport, commands, { ...options, lookup: this.schema }));
+    },
+    /** The server's projection of a batch: one command per asset it would touch, nothing applied. */
+    preview: (commands) => preview(this.transport, commands),
+    /**
+     * Send as a compare-and-set: each asset is changed only if nobody has
+     * changed it since the preview read it; the rest come back `skipped`.
+     * Throws UnguardableError, before any request, for shapes it cannot
+     * cover.
+     */
+    sendGuarded: async (commands, options) => {
+      await this.schema.ensureFor(commands);
+      return sendGuarded(this.transport, commands, { ...options, lookup: this.schema });
+    },
+    /** @deprecated since 1.0.0-alpha.3: use `client.query` (or `client.queryPage` for a total). Removed in 1.0.0. */
+    query: async (q) => {
+      await this.schema.ensureFor([q]);
+      return query(this.transport, q, { lookup: this.schema });
+    },
+    /** @deprecated since 1.0.0-alpha.3: use `client.queries`. Removed in 1.0.0. */
+    queries: async (qs) => {
+      await this.schema.ensureFor(qs);
+      return queries(this.transport, qs, { lookup: this.schema });
+    }
+  };
   /**
    * Services: what a person types, turned into assets. Numbers resolve in
    * one api/asset request across every number root; an OID token is taken
@@ -1474,7 +1718,7 @@ var AgilityApiClient = class _AgilityApiClient {
   /**
    * The files attached to assets: metadata on Attachment assets, bytes
    * through attachment.img. `add` sends a small file inline (one request)
-   * and a large one in two steps; `url` is where a browser opens one.
+   * and a large one in two steps.
    */
   attachments = {
     list: (asset, options) => list(this.transport, asset, options),
@@ -1484,7 +1728,8 @@ var AgilityApiClient = class _AgilityApiClient {
     add: (asset, data, options) => add(this.transport, asset, data, options),
     put: (id, data, contentType) => put(this.transport, id, data, contentType),
     remove: (id) => remove(this.transport, id),
-    url: (id) => attachmentUrl(this.config.baseUrl, id)
+    /** @deprecated since 1.0.0-alpha.3: `client.urls.attachment`. Removed in 1.0.0. */
+    url: (id) => this.urls.attachment(id)
   };
   /**
    * Images embedded in an asset's rich text (Description and other long
@@ -1494,55 +1739,16 @@ var AgilityApiClient = class _AgilityApiClient {
    */
   embeddedImages = {
     upload: (asset, data, options) => uploadEmbeddedImage(this.transport, asset, data, options),
-    url: (id) => embeddedImageUrl(this.config.baseUrl, id),
+    /** @deprecated since 1.0.0-alpha.3: `client.urls.embeddedImage`. Removed in 1.0.0. */
+    url: (id) => this.urls.embeddedImage(id),
     normalize: (html) => normalizeEmbeddedImageUrls(html, this.config.baseUrl)
   };
-  /** rest-1.v1: bounded reads, one asset, history. */
-  data = {
-    list: (type, params) => list2(this.transport, type, params),
-    get: (oid, sel) => get2(this.transport, oid, sel),
-    history: (target, params) => history(this.transport, target, params)
-  };
-  /**
-   * query.v1: reads only, the same query bodies as assets.query, rows
-   * translated the same way. The endpoint cannot write, so it is the safe
-   * place to explore a query; its requests may be retried like a GET.
-   */
-  queryV1 = {
-    query: async (q) => {
-      await this.schema.ensureFor([q]);
-      return query2(this.transport, q, { lookup: this.schema });
-    },
-    queries: async (qs) => {
-      await this.schema.ensureFor(qs);
-      return queries2(this.transport, qs, { lookup: this.schema });
-    }
-  };
-  /** api/asset: batches and queries, rows translated through the schema. */
-  assets = {
-    send: async (commands, options) => {
-      await this.schema.ensureFor(commands);
-      return send(this.transport, commands, { ...options, lookup: this.schema });
-    },
-    preview: (commands) => preview(this.transport, commands),
-    /**
-     * Send as a compare-and-set: each asset is changed only if nobody has
-     * changed it since the preview read it; the rest come back `skipped`.
-     * Throws UnguardableError, before any request, for shapes it cannot
-     * cover.
-     */
-    sendGuarded: async (commands, options) => {
-      await this.schema.ensureFor(commands);
-      return sendGuarded(this.transport, commands, { ...options, lookup: this.schema });
-    },
-    query: async (q) => {
-      await this.schema.ensureFor([q]);
-      return query(this.transport, q, { lookup: this.schema });
-    },
-    queries: async (qs) => {
-      await this.schema.ensureFor(qs);
-      return queries(this.transport, qs, { lookup: this.schema });
-    }
+  /** Where a browser opens things on this instance: an asset's page, an attachment's bytes, an embedded image. */
+  urls = {
+    /** The asset's page: assetdetail.v1 redirects to the type's own detail page (live 2026-11-12). */
+    asset: (oid) => `${this.config.baseUrl.replace(/\/+$/, "")}/assetdetail.v1?oid=${momentless(oid)}`,
+    attachment: (id) => attachmentUrl(this.config.baseUrl, id),
+    embeddedImage: (id) => embeddedImageUrl(this.config.baseUrl, id)
   };
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1562,6 +1768,8 @@ var AgilityApiClient = class _AgilityApiClient {
   TypeCache,
   UNGUARDABLE_TYPES,
   UnguardableError,
+  UsageError,
+  WrappedError,
   assetApi,
   assetStateOf,
   attachment,
@@ -1570,11 +1778,13 @@ var AgilityApiClient = class _AgilityApiClient {
   guard,
   isAssetNumber,
   isOidToken,
+  kindOf,
   loc2,
   meta,
   momentless,
   namesOf,
   parseOid,
+  parseViolation,
   queryV1,
   resolveNumbers,
   resolveRef,