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

package/dist/index.d.cts

@@ -301,6 +301,8 @@ interface AssetType {
     /** The attribute that carries the short name (Number on workitems). */
     ShortName?: AttributeTokenRef;
     Attributes: Record<AttributeToken, AttributeDefinition>;
+    /** The operations the type supports, by bare name (Delete, Inactivate, …); delivered keyed by token (Story.Delete). */
+    Operations?: string[];
 }
 type AssetTypeMap$1 = Record<AssetTypeToken, AssetType>;
 interface Metamodel {
@@ -772,6 +774,12 @@ declare class Schema implements AttributeLookup {
     assetType(token: AssetTypeToken): AssetType | null | undefined;
     /** An attribute by bare name; undefined when the type is not loaded, null when it has no such attribute. */
     attribute(type: AssetTypeToken, name: string): AttributeDefinition | null | undefined;
+    /**
+     * 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: AssetTypeToken, op: string): boolean | undefined;
     /** The tokens loaded so far. */
     get loaded(): AssetTypeToken[];
     /**
@@ -803,6 +811,12 @@ declare class Schema implements AttributeLookup {
  * which were skipped by the guard; and a reverse batch that undoes what
  * succeeded, best effort, with a note for anything it cannot.
  *
+ * Closing a workitem cascades: Core's Inactivate and QuickClose also close
+ * its open descendants, and Reactivate reopens only the asset it names. So
+ * before a batch that closes, the receipt records each closing target's
+ * open descendants; after it, the ones the close actually closed; and the
+ * reverse reopens the parent, then those, top down.
+ *
  * The snapshot keeps the endpoint's spelling (strings, relations as OID
  * tokens) on purpose: it is what a reverse batch writes back.
  */
@@ -867,18 +881,29 @@ interface Reverse {
     commands: Command[];
     notes: string[];
 }
+/** What reverseOf can know beyond the response, each optional. */
+interface ReverseContext {
+    /** Per closing target, its open descendants before the batch (Receipt.openDescendants). */
+    openDescendants?: Record<Oid, Oid[]>;
+    /** Per closing target, the descendants the close closed (Receipt.cascaded); undefined when they could not be read back. */
+    cascaded?: Record<Oid, Oid[]>;
+    /** Can this type do this operation? Undefined is "don't know", and the command is kept. */
+    canOperate?: (type: AssetTypeToken, op: string) => boolean | undefined;
+}
 /**
  * A batch that undoes what the response says succeeded — best effort. Only
  * what the response confirms is reversed (membership in it, not command
  * index, decides): updated attributes put back from the snapshot, the
- * inverse operation where one is known, created assets deleted (newest
- * first).
+ * inverse operation where one is known (and, for a close, the descendants
+ * it closed reopened after it, top down), created assets deleted (newest
+ * first). An operation a type does not have, by `context.canOperate`, is
+ * a note rather than a command the server would refuse.
  */
 declare function reverseOf(described: Described, before: Record<Oid, Record<string, unknown>>, done: {
     created: Oid[];
     modified: Oid[];
     operated: Oid[];
-}): Reverse;
+}, context?: ReverseContext): Reverse;
 interface Receipt {
     receipt: 1;
     request: Command[];
@@ -908,8 +933,14 @@ interface Receipt {
     } & Named)[];
     /** ChangeDate of everything the batch touched, just after it: the stamp a later reverse checks for drift. */
     after: Record<Oid, string>;
-    /** Touched assets the guard left alone: changed or gone since the snapshot. */
+    /** Touched assets the guard left alone: changed or gone since the snapshot. Not the ones whose command failed: those are in `failed`. */
     skipped: Oid[];
+    /** Touched assets whose command the server reports as failed (outcome.failures says why). */
+    failed: Oid[];
+    /** Per asset the batch closes (Inactivate, QuickClose): its open descendants at the snapshot, top down. */
+    openDescendants: Record<Oid, Oid[]>;
+    /** Per asset the batch closed: the descendants the close closed with it, read back after the send. */
+    cascaded: Record<Oid, Oid[]>;
     reverse: Reverse;
     /** What the record could not do and why: a name lookup that failed, deferred commands sent unsnapshotted. */
     notes: string[];
@@ -985,7 +1016,10 @@ declare function reversible(transport: Transport, receipt: Pick<Receipt, "revers
  *     pattern first, so it cannot carry grammar. The ID stays a variable.
  *   - Moment is NOT a stamp: `Moment=<an earlier moment of this asset>`
  *     selects the asset as it was then (as-of), and an update scoped by it
- *     lands on the current asset. A Moment guard guards nothing.
+ *     lands on the current asset. A Moment guard guards nothing. Proven for
+ *     writes on 2026-11-11: an update filtered on a stale Moment previews as
+ *     one command and applies, overwriting the change made in between
+ *     ("why not Moment, on a write"; versionone/VersionOne.SDK.JavaScript#51).
  * Every type has ChangeDate except the Ideas product's (Idea*), which keeps
  * no history and cannot be guarded.
  *

package/dist/index.d.ts

@@ -301,6 +301,8 @@ interface AssetType {
     /** The attribute that carries the short name (Number on workitems). */
     ShortName?: AttributeTokenRef;
     Attributes: Record<AttributeToken, AttributeDefinition>;
+    /** The operations the type supports, by bare name (Delete, Inactivate, …); delivered keyed by token (Story.Delete). */
+    Operations?: string[];
 }
 type AssetTypeMap$1 = Record<AssetTypeToken, AssetType>;
 interface Metamodel {
@@ -772,6 +774,12 @@ declare class Schema implements AttributeLookup {
     assetType(token: AssetTypeToken): AssetType | null | undefined;
     /** An attribute by bare name; undefined when the type is not loaded, null when it has no such attribute. */
     attribute(type: AssetTypeToken, name: string): AttributeDefinition | null | undefined;
+    /**
+     * 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: AssetTypeToken, op: string): boolean | undefined;
     /** The tokens loaded so far. */
     get loaded(): AssetTypeToken[];
     /**
@@ -803,6 +811,12 @@ declare class Schema implements AttributeLookup {
  * which were skipped by the guard; and a reverse batch that undoes what
  * succeeded, best effort, with a note for anything it cannot.
  *
+ * Closing a workitem cascades: Core's Inactivate and QuickClose also close
+ * its open descendants, and Reactivate reopens only the asset it names. So
+ * before a batch that closes, the receipt records each closing target's
+ * open descendants; after it, the ones the close actually closed; and the
+ * reverse reopens the parent, then those, top down.
+ *
  * The snapshot keeps the endpoint's spelling (strings, relations as OID
  * tokens) on purpose: it is what a reverse batch writes back.
  */
@@ -867,18 +881,29 @@ interface Reverse {
     commands: Command[];
     notes: string[];
 }
+/** What reverseOf can know beyond the response, each optional. */
+interface ReverseContext {
+    /** Per closing target, its open descendants before the batch (Receipt.openDescendants). */
+    openDescendants?: Record<Oid, Oid[]>;
+    /** Per closing target, the descendants the close closed (Receipt.cascaded); undefined when they could not be read back. */
+    cascaded?: Record<Oid, Oid[]>;
+    /** Can this type do this operation? Undefined is "don't know", and the command is kept. */
+    canOperate?: (type: AssetTypeToken, op: string) => boolean | undefined;
+}
 /**
  * A batch that undoes what the response says succeeded — best effort. Only
  * what the response confirms is reversed (membership in it, not command
  * index, decides): updated attributes put back from the snapshot, the
- * inverse operation where one is known, created assets deleted (newest
- * first).
+ * inverse operation where one is known (and, for a close, the descendants
+ * it closed reopened after it, top down), created assets deleted (newest
+ * first). An operation a type does not have, by `context.canOperate`, is
+ * a note rather than a command the server would refuse.
  */
 declare function reverseOf(described: Described, before: Record<Oid, Record<string, unknown>>, done: {
     created: Oid[];
     modified: Oid[];
     operated: Oid[];
-}): Reverse;
+}, context?: ReverseContext): Reverse;
 interface Receipt {
     receipt: 1;
     request: Command[];
@@ -908,8 +933,14 @@ interface Receipt {
     } & Named)[];
     /** ChangeDate of everything the batch touched, just after it: the stamp a later reverse checks for drift. */
     after: Record<Oid, string>;
-    /** Touched assets the guard left alone: changed or gone since the snapshot. */
+    /** Touched assets the guard left alone: changed or gone since the snapshot. Not the ones whose command failed: those are in `failed`. */
     skipped: Oid[];
+    /** Touched assets whose command the server reports as failed (outcome.failures says why). */
+    failed: Oid[];
+    /** Per asset the batch closes (Inactivate, QuickClose): its open descendants at the snapshot, top down. */
+    openDescendants: Record<Oid, Oid[]>;
+    /** Per asset the batch closed: the descendants the close closed with it, read back after the send. */
+    cascaded: Record<Oid, Oid[]>;
     reverse: Reverse;
     /** What the record could not do and why: a name lookup that failed, deferred commands sent unsnapshotted. */
     notes: string[];
@@ -985,7 +1016,10 @@ declare function reversible(transport: Transport, receipt: Pick<Receipt, "revers
  *     pattern first, so it cannot carry grammar. The ID stays a variable.
  *   - Moment is NOT a stamp: `Moment=<an earlier moment of this asset>`
  *     selects the asset as it was then (as-of), and an update scoped by it
- *     lands on the current asset. A Moment guard guards nothing.
+ *     lands on the current asset. A Moment guard guards nothing. Proven for
+ *     writes on 2026-11-11: an update filtered on a stale Moment previews as
+ *     one command and applies, overwriting the change made in between
+ *     ("why not Moment, on a write"; versionone/VersionOne.SDK.JavaScript#51).
  * Every type has ChangeDate except the Ideas product's (Idea*), which keeps
  * no history and cannot be guarded.
  *

package/dist/index.js

@@ -827,9 +827,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;
@@ -854,10 +891,32 @@ 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 };
@@ -892,12 +951,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 = [];
@@ -929,13 +990,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);
@@ -1099,7 +1176,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) {
@@ -1163,6 +1241,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);