@warmhub/cli 0.85.0 → 0.86.0

package/dist/wh.js

@@ -27993,8 +27993,8 @@ function normalizeOptionalName(value) {
 
 // ../../packages/sdk-ts/src/operation-normalize.ts
 function toBackendStreamOperation(operation) {
-  if (operation.expectedVersion !== undefined && operation.operation !== "revise") {
-    throw new Error("expectedVersion is only valid on revise operations — set operation: 'revise'");
+  if (operation.expectedVersion !== undefined && operation.operation !== "revise" && operation.operation !== "retract") {
+    throw new Error("expectedVersion is only valid on revise or retract operations — set an explicit operation discriminator");
   }
   if (operation.operation === "retract") {
     return {
@@ -28002,6 +28002,7 @@ function toBackendStreamOperation(operation) {
       name: operation.name,
       ...operation.kind ? { kind: operation.kind } : {},
       ...operation.reason ? { reason: operation.reason } : {},
+      ...operation.expectedVersion !== undefined ? { expectedVersion: operation.expectedVersion } : {},
       ...operation.leaseId ? { leaseId: operation.leaseId } : {}
     };
   }
@@ -28097,13 +28098,19 @@ class PartialStreamSubmissionError extends Error {
   code = "PARTIAL_STREAM_SUBMISSION";
   completedOperations;
   acknowledgedOperationCount;
+  lastAcknowledgedRepoSeq;
+  attemptedAppendOutcome;
   cause;
   constructor(input) {
-    super("Stream submission failed. A timed-out append may already have landed, so inspect repository state before sending any further operations.");
+    super("Stream submission outcome is incomplete or unknown. Stop sending writes; once any outstanding append can no longer apply, obtain a later verified checkpoint and reconcile before replanning.");
     this.name = "WarmHubError";
     this.cause = input.cause;
     this.completedOperations = input.completedOperations;
     this.acknowledgedOperationCount = input.acknowledgedOperationCount ?? input.completedOperations.length;
+    this.attemptedAppendOutcome = input.attemptedAppendOutcome;
+    if (input.lastAcknowledgedRepoSeq !== undefined) {
+      this.lastAcknowledgedRepoSeq = input.lastAcknowledgedRepoSeq;
+    }
   }
 }
 
@@ -28260,6 +28267,9 @@ function isTransientStreamFailure(cause) {
 function isFetchNetworkTypeError(cause) {
   return cause instanceof TypeError && /fetch/i.test(cause.message);
 }
+function isReplaySafeOperation(operation) {
+  return operation.operation !== "revise" || operation.expectedVersion !== undefined;
+}
 function computeBackoffDelayMs(attempt, policy) {
   const exponential = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
   const jitter = Math.random() * policy.baseDelayMs;
@@ -28309,7 +28319,8 @@ async function submitOperationsViaStream(client, args) {
   for (const { operations: chunk, start: chunkStart } of chunkOperations(operations, chunkSize)) {
     let attempt = 1;
     let priorAttemptAmbiguous = false;
-    const chunkIsAtomic = chunk.length === 1;
+    const chunkIsSingleOperation = chunk.length === 1;
+    const chunkIsReplaySafe = chunk.every(isReplaySafeOperation);
     while (true) {
       try {
         const appendResult = await client.stream.append({
@@ -28337,7 +28348,7 @@ async function submitOperationsViaStream(client, args) {
         if (acknowledgedOperationCount === 0 && !priorAttemptAmbiguous && isDefiniteClientError(cause)) {
           throw cause;
         }
-        if (acknowledgedOperationCount === 0 && chunkIsAtomic && policy !== false && attempt < policy.maxAttempts && isTransientStreamFailure(cause)) {
+        if (acknowledgedOperationCount === 0 && chunkIsSingleOperation && chunkIsReplaySafe && policy !== false && attempt < policy.maxAttempts && isTransientStreamFailure(cause)) {
           await sleep2(computeBackoffDelayMs(attempt, policy));
           attempt += 1;
           priorAttemptAmbiguous = true;
@@ -28352,7 +28363,9 @@ async function submitOperationsViaStream(client, args) {
         throw new PartialStreamSubmissionError({
           cause,
           completedOperations,
-          acknowledgedOperationCount
+          acknowledgedOperationCount,
+          lastAcknowledgedRepoSeq: repoSeq,
+          attemptedAppendOutcome: !priorAttemptAmbiguous && isDefiniteClientError(cause) ? "not_applied" : "unknown"
         });
       }
     }
@@ -28366,7 +28379,9 @@ async function submitOperationsViaStream(client, args) {
       throw new PartialStreamSubmissionError({
         cause: failure,
         completedOperations: completedOperationsFrom(result),
-        acknowledgedOperationCount
+        acknowledgedOperationCount,
+        lastAcknowledgedRepoSeq: repoSeq,
+        attemptedAppendOutcome: "unknown"
       });
     }
     throw failure;
@@ -28480,7 +28495,7 @@ function dedupeDeprecationsByShape(results) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.83.0",
+  version: "0.84.0",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -28709,6 +28724,9 @@ function chunkArray(items, chunkSize) {
   }
   return chunks;
 }
+function narrowKind(kind) {
+  return kind !== undefined && COMMIT_OPERATION_KINDS.includes(kind) ? kind : undefined;
+}
 function toSubscriptionRef(args) {
   const [first, repoName, name] = args;
   return typeof first === "string" ? { orgName: first, repoName, name } : first;
@@ -30047,6 +30065,7 @@ class WarmHubClient {
         return await this.trpc.action.listRuns.query({
           orgName,
           repoName,
+          runId: opts?.runId,
           subscriptionName: opts?.subscriptionName,
           status: opts?.status,
           outcome: opts?.outcome,
@@ -30257,12 +30276,11 @@ class WarmHubClient {
   thing = {
     head: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : undefined;
         return await this.trpc.thing.head.query({
           orgName,
           repoName,
           shape: opts?.shape,
-          kind,
+          kind: narrowKind(opts?.kind),
           match: opts?.match,
           dataMode: opts?.dataMode,
           includeRetracted: opts?.includeRetracted,
@@ -30496,13 +30514,12 @@ class WarmHubClient {
     },
     query: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : undefined;
         return await this.trpc.thing.query.query({
           orgName,
           repoName,
           shape: opts?.shape,
           about: opts?.about,
-          kind,
+          kind: narrowKind(opts?.kind),
           match: opts?.match,
           includeRetracted: opts?.includeRetracted,
           resolveCollections: opts?.resolveCollections,
@@ -30536,14 +30553,13 @@ class WarmHubClient {
     },
     search: async (orgName, repoName, query, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : undefined;
         return await this.trpc.thing.search.query({
           orgName,
           repoName,
           query,
           shape: opts?.shape,
           about: opts?.about,
-          kind,
+          kind: narrowKind(opts?.kind),
           match: opts?.match,
           includeRetracted: opts?.includeRetracted,
           resolveCollections: opts?.resolveCollections,
@@ -30571,13 +30587,12 @@ class WarmHubClient {
     },
     count: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : undefined;
         return await this.trpc.thing.count.query({
           orgName,
           repoName,
           shape: opts?.shape,
           about: opts?.about,
-          kind,
+          kind: narrowKind(opts?.kind),
           match: opts?.match,
           includeRetracted: opts?.includeRetracted,
           resolveCollections: opts?.resolveCollections,
@@ -31215,20 +31230,101 @@ class CliError extends Error {
   cause;
   hint;
   backendCode;
+  recovery;
   context;
-  constructor(code, kind, message, cause, hint, context, backendCode) {
+  constructor(code, kind, message, cause, hint, context, backendCode, recovery) {
     super(message);
     this.code = code;
     this.kind = kind;
     this.cause = cause;
     this.hint = hint;
     this.backendCode = backendCode;
+    this.recovery = recovery;
     this.context = context;
   }
   get errorCode() {
     return this.backendCode;
   }
 }
+
+// ../../packages/warmhub-cli/src/stream-recovery.ts
+function failureCode(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const typed = error;
+  if (typeof typed.errorCode === "string")
+    return typed.errorCode;
+  if (typeof typed.backendCode === "string")
+    return typed.backendCode;
+  if (typeof typed.data?.warmhub?.code === "string") {
+    return typed.data.warmhub.code;
+  }
+  if (typeof typed.data?.code === "string")
+    return typed.data.code;
+  return failureCode(typed.cause);
+}
+function failureStatus(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const typed = error;
+  if (typeof typed.status === "number")
+    return typed.status;
+  if (typeof typed.data?.warmhub?.status === "number") {
+    return typed.data.warmhub.status;
+  }
+  if (typeof typed.data?.status === "number")
+    return typed.data.status;
+  if (typeof typed.data?.httpStatus === "number") {
+    return typed.data.httpStatus;
+  }
+  return failureStatus(typed.cause);
+}
+function streamAppendWasExplicitlyRejected(cause) {
+  const normalized = toWarmHubError(cause);
+  const code = failureCode(cause) ?? normalized.errorCode ?? normalized.code;
+  if (code === "COMMIT_OUTCOME_UNKNOWN")
+    return false;
+  const status = failureStatus(cause) ?? normalized.status;
+  return status !== undefined && status >= 400 && status < 500 && status !== 408;
+}
+function streamFailureCode(cause) {
+  const normalized = toWarmHubError(cause);
+  const wireCode = failureCode(cause) ?? normalized.errorCode;
+  if (wireCode !== undefined)
+    return wireCode;
+  return normalized.status !== undefined && normalized.code !== "BACKEND" ? normalized.code : undefined;
+}
+function buildStreamRecoveryReceipt(args) {
+  const {
+    acknowledgedOperationCount,
+    lastAcknowledgedRepoSeq,
+    cause,
+    attemptedAppendOutcome
+  } = args;
+  const sequenceReceipt = lastAcknowledgedRepoSeq === undefined ? "" : ` Last acknowledged repo sequence: ${lastAcknowledgedRepoSeq}.`;
+  const errorCode = streamFailureCode(cause);
+  const backendSuffix = errorCode ? ` (backend: ${errorCode})` : "";
+  const recovery = {
+    acknowledgedOperationCount,
+    ...lastAcknowledgedRepoSeq === undefined ? {} : { lastAcknowledgedRepoSeq },
+    attemptedAppendOutcome
+  };
+  if (attemptedAppendOutcome === "unknown") {
+    return {
+      message: `Stream append outcome is unknown after ${acknowledgedOperationCount} acknowledged operation(s).${sequenceReceipt}${backendSuffix}`,
+      hint: "Stop submitting writes. The attempted append may have landed after the last acknowledgement; once it can no longer apply, obtain and verify a later checkpoint, then reconcile the attempted append and unsent work.",
+      errorCode,
+      recovery
+    };
+  }
+  const causeMessage = cause instanceof Error ? cause.message : String(cause);
+  return {
+    message: `${causeMessage} (${acknowledgedOperationCount} earlier operation(s) already acknowledged before this failure).${sequenceReceipt}${backendSuffix}`,
+    hint: "The failed input or rejected append was not applied. Keep the acknowledged prefix receipt, then correct or replan the rejected and unsent operations.",
+    errorCode,
+    recovery
+  };
+}
 // ../../packages/warmhub-cli/src/errors-logging.ts
 function shouldLogToErrorTier(err) {
   switch (err.kind) {
@@ -31453,7 +31549,8 @@ function printCliError(err, errWriter, opts = {}) {
         message: err.message,
         ...err.hint ? { hint: err.hint } : {},
         ...suggestions.length > 0 ? { suggestions } : {},
-        ...err.context ? { context: err.context } : {}
+        ...err.context ? { context: err.context } : {},
+        ...err.recovery ? { recovery: err.recovery } : {}
       }
     };
     errWriter(JSON.stringify(envelope));
@@ -31493,8 +31590,13 @@ function toCliError(err) {
     return cliErrorFromAllFailed(err.operations);
   }
   if (err instanceof PartialStreamSubmissionError) {
-    const hint = err.cause instanceof Error ? err.cause.message : err.cause === undefined ? undefined : String(err.cause);
-    return new CliError(4 /* Backend */, "BACKEND", err.message, err, hint);
+    const receipt = buildStreamRecoveryReceipt({
+      acknowledgedOperationCount: err.acknowledgedOperationCount,
+      lastAcknowledgedRepoSeq: err.lastAcknowledgedRepoSeq,
+      cause: err.cause,
+      attemptedAppendOutcome: err.attemptedAppendOutcome
+    });
+    return new CliError(4 /* Backend */, "BACKEND", receipt.message, err, receipt.hint, undefined, receipt.errorCode, receipt.recovery);
   }
   if (err instanceof WarmHubError) {
     if (err.code === "CURSOR_EPOCH_INVALID" || err.errorCode === "CURSOR_EPOCH_INVALID") {
@@ -34966,6 +35068,7 @@ function pageEnvelope(items, opts) {
   const nextCursor = opts.nextCursor ?? null;
   return {
     items,
+    ...opts.repoSeq === undefined ? {} : { repoSeq: opts.repoSeq },
     page: {
       limit: opts.limit,
       count: items.length,
@@ -35118,6 +35221,9 @@ var reviseFlags = {
 };
 var retractFlags = {
   reason: flag.string({ description: "Reason for retraction (<=500 chars)" }),
+  "expected-version": flag.number({
+    description: "only retract if the target is still at this version (optimistic concurrency)"
+  }),
   message: flag.string({ short: "m", description: "Commit message" }),
   committer: flag.string({
     description: "Committer wref (shape or shaped thing; e.g. Agent/bot-1)"
@@ -35152,15 +35258,17 @@ var handleRevise = async (ctx, { flags, args }) => {
 var handleRetract = async (ctx, { flags, args }) => {
   const name = args[0];
   if (!name) {
-    usageError("Usage: wh assertion retract <wref> -m <message>", 'wh assertion retract Belief/cave-safe -m "withdraw claim"');
+    usageError("Usage: wh assertion retract <wref> -m <message> [--expected-version <n>]", 'wh assertion retract Belief/cave-safe -m "withdraw claim"');
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh assertion retract Belief/cave-safe --expected-version 3");
   const result = await ctx.client.commit.apply(org, repo, flags.message ?? `retract ${name}`, [
     {
       operation: "retract",
       kind: "assertion",
       name,
-      ...flags.reason ? { reason: flags.reason } : {}
+      ...flags.reason ? { reason: flags.reason } : {},
+      ...expectedVersion !== undefined ? { expectedVersion } : {}
     }
   ], {
     committer: flags.committer
@@ -35235,6 +35343,47 @@ function parseCollectionRoleFlag(value, example) {
     return value;
   usageError("Invalid --role. Expected from, to, or ends.", example);
 }
+function parseSinceRepoSeqFlag(value) {
+  if (value === undefined)
+    return;
+  if (Number.isSafeInteger(value) && value >= -1)
+    return value;
+  usageError("--since-repo-seq must be -1 or a nonnegative safe integer.", "wh thing list --since-repo-seq -1 --all --format json");
+}
+function requireIncrementalCheckpoint(repoSeq, required) {
+  if (required && repoSeq === undefined) {
+    throw new CliError(4 /* Backend */, "BACKEND", "Incremental read completed without repoSeq", undefined, "Retry the read. If the checkpoint remains absent, report a backend incremental-read contract violation.");
+  }
+}
+async function collectThingPages(args) {
+  const items = [];
+  let cursor = args.initialCursor;
+  const seenCursors = new Set(cursor ? [cursor] : []);
+  while (true) {
+    const page = await args.fetchPage(cursor);
+    const pageItems = page.items ?? [];
+    if (args.onPage) {
+      if (!await args.onPage(pageItems)) {
+        return { items, nextCursor: undefined };
+      }
+    } else {
+      items.push(...pageItems);
+    }
+    if (!page.nextCursor) {
+      requireIncrementalCheckpoint(page.repoSeq, args.requireRepoSeq);
+      return {
+        items,
+        nextCursor: undefined,
+        ...page.repoSeq === undefined ? {} : { repoSeq: page.repoSeq }
+      };
+    }
+    if (seenCursors.has(page.nextCursor)) {
+      throw new CliError(4 /* Backend */, "BACKEND", `${args.title} pagination cursor repeated; aborting --all to avoid an infinite loop.`, undefined, "Retry without --all to fetch one page and inspect page.nextCursor. If cursors repeat, report this as a backend pagination issue.");
+    }
+    seenCursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+}
 async function handleCount(ctx, org, repo, opts) {
   const result = await ctx.client.thing.count(org, repo, opts);
   writeOutput(ctx, result, () => ctx.out(`${result.count}`));
@@ -36190,6 +36339,9 @@ var headFlags = {
     description: "Max items per page (default: 50, max: 500)"
   }),
   cursor: flag.string({ description: "Opaque pagination cursor" }),
+  "since-repo-seq": flag.number({
+    description: "Return identities changed after this repository sequence"
+  }),
   all: flag.boolean({ description: "Fetch all pages" }),
   match: flag.string({ description: "Filter by wref glob pattern" }),
   count: flag.boolean({ description: "Return count of matching items" }),
@@ -36213,15 +36365,19 @@ var handleHead = async (ctx, { flags, args }) => {
   const kind = validateKind(flags.kind);
   const limit = flags.limit;
   const cursor = flags.cursor;
+  const sinceRepoSeq = parseSinceRepoSeqFlag(flags["since-repo-seq"]);
   const all = flags.all;
   const match = flags.match;
   const count = flags.count;
   const includeRetracted = flags["include-retracted"];
   const whereRaw = flags.where ?? [];
   const where = whereRaw.map(parseWhereFlag);
+  if (ctx.liveMode && sinceRepoSeq !== undefined) {
+    usageError("--since-repo-seq cannot be used with --live.", "wh thing list --since-repo-seq 42 --all --format json");
+  }
   if (count) {
     if (cursor || all || limit || ctx.liveMode) {
-      usageError("Usage: wh thing list --count [--shape SHAPE] [--kind KIND] [--match PATTERN]", "wh thing list --shape Player --count");
+      usageError("Usage: wh thing list --count [--shape SHAPE] [--kind KIND] [--match PATTERN] [--since-repo-seq N]", "wh thing list --shape Player --count --since-repo-seq 42");
     }
     const componentRef2 = flags.component;
     const strictExclude2 = !!flags["exclude-components"];
@@ -36234,7 +36390,8 @@ var handleHead = async (ctx, { flags, args }) => {
       componentRef: componentRef2,
       excludeComponents: strictExclude2,
       excludeInfraShapes: !strictExclude2 && !shape,
-      where: where.length > 0 ? where : undefined
+      where: where.length > 0 ? where : undefined,
+      ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
     });
   }
   if (cursor && !limit) {
@@ -36261,7 +36418,8 @@ var handleHead = async (ctx, { flags, args }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   };
   if (ctx.liveMode) {
     await runLive({
@@ -36294,7 +36452,8 @@ var handleHead = async (ctx, { flags, args }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   }, streamJsonl ? async (items) => {
     writePageOutput(ctx, items, { limit: pageLimit }, () => {});
     return await ctx.flushOut?.() ?? true;
@@ -36308,23 +36467,25 @@ var handleHead = async (ctx, { flags, args }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   });
   if (streamJsonl)
     return;
+  requireIncrementalCheckpoint(result.repoSeq, sinceRepoSeq !== undefined && !result.nextCursor);
   if (!all && result.nextCursor) {
     emitPartialPageHint(ctx, (result.items ?? []).length, result.nextCursor, boundedLimit);
   }
   writePageOutput(ctx, result.items ?? [], {
     limit: all ? pageLimit : boundedLimit,
-    nextCursor: result.nextCursor ?? null
+    nextCursor: result.nextCursor ?? null,
+    ...result.repoSeq === undefined ? {} : { repoSeq: result.repoSeq }
   }, () => renderHead(ctx.out, ctx.colors, ctx.chars, result, org, repo, shape, kind));
 };
 async function fetchAllHeadPages(ctx, org, repo, opts, onPage) {
-  const items = [];
-  let cursor = opts.cursor;
-  while (true) {
-    const page = await ctx.client.thing.head(org, repo, {
+  return collectThingPages({
+    initialCursor: opts.cursor,
+    fetchPage: (cursor) => ctx.client.thing.head(org, repo, {
       shape: opts.shape,
       kind: opts.kind,
       match: opts.match,
@@ -36334,20 +36495,13 @@ async function fetchAllHeadPages(ctx, org, repo, opts, onPage) {
       componentRef: opts.componentRef,
       excludeComponents: opts.excludeComponents,
       excludeInfraShapes: opts.excludeInfraShapes,
-      where: opts.where
-    });
-    const pageItems = page.items ?? [];
-    if (onPage) {
-      if (!await onPage(pageItems))
-        break;
-    } else {
-      items.push(...pageItems);
-    }
-    if (!page.nextCursor)
-      break;
-    cursor = page.nextCursor;
-  }
-  return { items, nextCursor: undefined };
+      where: opts.where,
+      ...opts.sinceRepoSeq === undefined ? {} : { sinceRepoSeq: opts.sinceRepoSeq }
+    }),
+    onPage,
+    requireRepoSeq: opts.sinceRepoSeq !== undefined,
+    title: "Thing list"
+  });
 }
 
 // ../../packages/warmhub-cli/src/domains/thing/query.ts
@@ -36359,6 +36513,9 @@ var queryFlags = {
     description: "Max results per page (default: 50, max: 500)"
   }),
   cursor: flag.string({ description: "Opaque pagination cursor" }),
+  "since-repo-seq": flag.number({
+    description: "Return identities changed after this repository sequence"
+  }),
   all: flag.boolean({ description: "Fetch all pages" }),
   match: flag.string({ description: "Filter by wref glob pattern" }),
   count: flag.boolean({ description: "Return count of matching items" }),
@@ -36389,6 +36546,7 @@ var handleQuery = async (ctx, { flags }) => {
   const kind = validateKind(flags.kind);
   const limit = flags.limit;
   const cursor = flags.cursor;
+  const sinceRepoSeq = parseSinceRepoSeqFlag(flags["since-repo-seq"]);
   const all = flags.all;
   const match = flags.match;
   const count = flags.count;
@@ -36404,9 +36562,12 @@ var handleQuery = async (ctx, { flags }) => {
   const c = ctx.colors;
   const whereRaw = flags.where ?? [];
   const where = whereRaw.map(parseWhereFlag);
+  if (ctx.liveMode && sinceRepoSeq !== undefined) {
+    usageError("--since-repo-seq cannot be used with --live.", "wh thing query --since-repo-seq 42 --all --format json");
+  }
   if (count) {
     if (cursor || all || limit || ctx.liveMode || role) {
-      usageError("Usage: wh thing query --count [--shape SHAPE] [--about WREF] [--kind KIND] [--match PATTERN]", "wh thing query --kind assertion --about Player/alice --count");
+      usageError("Usage: wh thing query --count [--shape SHAPE] [--about WREF] [--kind KIND] [--match PATTERN] [--since-repo-seq N]", "wh thing query --kind assertion --about Player/alice --count --since-repo-seq 42");
     }
     return handleCount(ctx, org, repo, {
       shape,
@@ -36418,7 +36579,8 @@ var handleQuery = async (ctx, { flags }) => {
       componentRef,
       excludeComponents,
       excludeInfraShapes,
-      where: where.length > 0 ? where : undefined
+      where: where.length > 0 ? where : undefined,
+      ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
     });
   }
   if (role && (!about || !resolveCollections)) {
@@ -36445,7 +36607,8 @@ var handleQuery = async (ctx, { flags }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   };
   if (ctx.liveMode) {
     await runLive({
@@ -36481,7 +36644,8 @@ var handleQuery = async (ctx, { flags }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   }, streamJsonl ? async (items) => {
     writePageOutput(ctx, items, { limit: pageLimit }, () => {});
     return await ctx.flushOut?.() ?? true;
@@ -36498,23 +36662,25 @@ var handleQuery = async (ctx, { flags }) => {
     componentRef,
     excludeComponents,
     excludeInfraShapes,
-    where: where.length > 0 ? where : undefined
+    where: where.length > 0 ? where : undefined,
+    ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
   });
   if (streamJsonl)
     return;
+  requireIncrementalCheckpoint(result.repoSeq, sinceRepoSeq !== undefined && !result.nextCursor);
   if (!all && result.nextCursor) {
     emitPartialPageHint(ctx, (result.items ?? []).length, result.nextCursor, boundedLimit);
   }
   writePageOutput(ctx, result.items ?? [], {
     limit: all ? pageLimit : boundedLimit,
-    nextCursor: result.nextCursor ?? null
+    nextCursor: result.nextCursor ?? null,
+    ...result.repoSeq === undefined ? {} : { repoSeq: result.repoSeq }
   }, () => renderQueryResults(ctx.out, c, result));
 };
 async function fetchAllQueryPages(ctx, org, repo, opts, onPage) {
-  const items = [];
-  let cursor = opts.cursor;
-  while (true) {
-    const page = await ctx.client.thing.query(org, repo, {
+  return collectThingPages({
+    initialCursor: opts.cursor,
+    fetchPage: (cursor) => ctx.client.thing.query(org, repo, {
       shape: opts.shape,
       about: opts.about,
       kind: opts.kind,
@@ -36527,20 +36693,13 @@ async function fetchAllQueryPages(ctx, org, repo, opts, onPage) {
       componentRef: opts.componentRef,
       excludeComponents: opts.excludeComponents,
       excludeInfraShapes: opts.excludeInfraShapes,
-      where: opts.where
-    });
-    const pageItems = page.items ?? [];
-    if (onPage) {
-      if (!await onPage(pageItems))
-        break;
-    } else {
-      items.push(...pageItems);
-    }
-    if (!page.nextCursor)
-      break;
-    cursor = page.nextCursor;
-  }
-  return { items, nextCursor: undefined };
+      where: opts.where,
+      ...opts.sinceRepoSeq === undefined ? {} : { sinceRepoSeq: opts.sinceRepoSeq }
+    }),
+    onPage,
+    requireRepoSeq: opts.sinceRepoSeq !== undefined,
+    title: "Thing query"
+  });
 }
 function renderQueryResults(out, c, result) {
   const items = result.items ?? [];
@@ -36709,6 +36868,9 @@ var retractFlags2 = {
     description: "Optional safety check: thing|assertion|shape|collection (errors on mismatch)"
   }),
   reason: flag.string({ description: "Reason for retraction (<=500 chars)" }),
+  "expected-version": flag.number({
+    description: "only retract if the target is still at this version (optimistic concurrency)"
+  }),
   message: flag.string({ short: "m", description: "Commit message" }),
   committer: flag.string({
     description: "Committer wref (shape or shaped thing; e.g. Agent/bot-1)"
@@ -36720,13 +36882,14 @@ var retractFlags2 = {
 var handleThingRetract = async (ctx, { flags, args }) => {
   const name = args[0];
   if (!name) {
-    usageError("Usage: wh thing retract <wref> -m <message> [--reason <text>] [--kind thing|assertion|shape|collection]", 'wh thing retract Measurement/m1 -m "cleanup" --reason "bad source"');
+    usageError("Usage: wh thing retract <wref> -m <message> [--reason <text>] [--kind thing|assertion|shape|collection] [--expected-version <n>]", 'wh thing retract Measurement/m1 -m "cleanup" --reason "bad source"');
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const committer = flags.committer;
   const message = flags.message;
   const kind = flags.kind;
   const reason = flags.reason;
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh thing retract Player/alice --expected-version 3");
   const leaseId = requireLeaseIdFlag(flags["lease-id"], "wh thing retract Player/alice --lease-id <id>");
   const c = ctx.colors;
   const result = await ctx.client.commit.apply(org, repo, message ?? `retract ${name}`, [
@@ -36735,6 +36898,7 @@ var handleThingRetract = async (ctx, { flags, args }) => {
       name,
       ...kind ? { kind } : {},
       ...reason ? { reason } : {},
+      ...expectedVersion !== undefined ? { expectedVersion } : {},
       ...leaseId ? { leaseId } : {}
     }
   ], { committer });
@@ -39319,7 +39483,7 @@ var createFlags3 = {
     description: "collection members (comma-separated wrefs)"
   }),
   "expected-version": flag.number({
-    description: "Only apply if the --revise target is still at this version (optimistic concurrency). Requires --revise."
+    description: "only apply if the --revise or single --retract target is still at this version (optimistic concurrency)."
   }),
   "lease-id": flag.string({
     description: "read-lease token from `wh thing lease`, bound to --revise or one --retract target (auto-released on success)"
@@ -39582,7 +39746,7 @@ function buildAddOperations(input) {
   });
 }
 function buildRetractOperations(input) {
-  const { retractNames, kinds, reasons, leaseId } = input;
+  const { retractNames, kinds, reasons, expectedVersion, leaseId } = input;
   if (leaseId !== undefined && retractNames.length !== 1) {
     throw new CliError(2 /* UserInput */, "USER_INPUT", `--lease-id requires exactly one --retract target; received ${retractNames.length}.`, undefined, "wh commit submit --retract Player/alice --lease-id lease-xyz --repo acme/world");
   }
@@ -39612,6 +39776,7 @@ function buildRetractOperations(input) {
       name,
       ...kind ? { kind } : {},
       ...reason ? { reason } : {},
+      ...expectedVersion !== undefined ? { expectedVersion } : {},
       ...leaseId ? { leaseId } : {}
     };
   });
@@ -39711,15 +39876,14 @@ import { createInterface as createInterface2 } from "node:readline";
 class JsonlPartialSubmissionError extends CliError {
 }
 function jsonlPartialSubmissionError(args) {
-  const { acknowledgedOperationCount, cause } = args;
-  if (args.failedAppendMayHaveLanded === true) {
-    const backendCode = toWarmHubError(cause).backendCode;
-    const suffix = backendCode ? ` (backend: ${backendCode})` : "";
-    return new JsonlPartialSubmissionError(4 /* Backend */, "BACKEND", `Stream append failed after ${acknowledgedOperationCount} acknowledged operation(s).${suffix}`, cause, "The failed append may also have landed; inspect repository state before submitting any remaining JSONL operations.", undefined, backendCode);
-  }
-  const message = cause instanceof Error ? cause.message : String(cause);
-  const causeHint = cause instanceof CliError && cause.hint ? `${cause.hint} ` : "";
-  return new JsonlPartialSubmissionError(4 /* Backend */, "BACKEND", `${message} (${acknowledgedOperationCount} earlier operation(s) already acknowledged by the server before this input failure).`, cause, `${causeHint}Earlier chunks have landed; inspect repository state before submitting any remaining JSONL operations.`);
+  const receipt = buildStreamRecoveryReceipt({
+    acknowledgedOperationCount: args.acknowledgedOperationCount,
+    lastAcknowledgedRepoSeq: args.lastAcknowledgedRepoSeq,
+    cause: args.cause,
+    attemptedAppendOutcome: args.failedAppendMayHaveLanded === true ? "unknown" : "not_applied"
+  });
+  const causeHint = args.cause instanceof CliError && args.cause.hint ? `${args.cause.hint} ` : "";
+  return new JsonlPartialSubmissionError(4 /* Backend */, "BACKEND", receipt.message, args.cause, `${causeHint}${receipt.hint}`, undefined, receipt.errorCode, receipt.recovery);
 }
 
 // ../../packages/warmhub-cli/src/domains/commit-submit-utils.ts
@@ -39804,50 +39968,6 @@ function toCommitSubmitResult(args) {
     operations
   };
 }
-function backendErrorCode(error) {
-  if (typeof error !== "object" || error === null) {
-    return;
-  }
-  const typed = error;
-  if (typeof typed.data === "object" && typed.data !== null) {
-    const data = typed.data;
-    if (typeof data.code === "string") {
-      return data.code;
-    }
-  }
-  const causeCode = backendErrorCode(typed.cause);
-  if (causeCode !== undefined) {
-    return causeCode;
-  }
-  return typeof typed.code === "string" ? typed.code : undefined;
-}
-function backendErrorStatus(error) {
-  if (typeof error !== "object" || error === null) {
-    return;
-  }
-  const typed = error;
-  if (typeof typed.status === "number") {
-    return typed.status;
-  }
-  if (typeof typed.data === "object" && typed.data !== null) {
-    const data = typed.data;
-    if (typeof data.status === "number") {
-      return data.status;
-    }
-    if (typeof data.httpStatus === "number") {
-      return data.httpStatus;
-    }
-    if (typeof data.warmhub?.status === "number") {
-      return data.warmhub.status;
-    }
-  }
-  return backendErrorStatus(typed.cause);
-}
-function firstJsonlAppendErrorMayHaveCommitted(error) {
-  const errorCode = backendErrorCode(error);
-  const errorStatus = backendErrorStatus(error);
-  return errorCode === undefined || errorCode === "COMMIT_OUTCOME_UNKNOWN" || errorCode === "INTERNAL_ERROR" || errorCode === "NETWORK" || errorCode === "SERVICE_UNAVAILABLE" || errorCode === "BACKEND" && errorStatus !== undefined && errorStatus >= 500;
-}
 
 // ../../packages/warmhub-cli/src/domains/stream-progress.ts
 import { createReadStream } from "node:fs";
@@ -40032,12 +40152,12 @@ async function applyJsonlCommit(ctx, args) {
   const tAppendStart = performance.now();
   progress.start(t0);
   let opCount = 0;
+  let repoSeq;
   try {
     const operations = [];
     const submittedOperations = [];
     let allocatedTokenRanges = [];
     let createdByEmail;
-    let repoSeq;
     let parsedOpCount = 0;
     let chunk = [];
     let lineNumber = 0;
@@ -40060,11 +40180,13 @@ async function applyJsonlCommit(ctx, args) {
         });
       } catch (cause) {
         const completed = opCount;
-        if (opCount > 0 || firstJsonlAppendErrorMayHaveCommitted(cause)) {
+        const failedAppendMayHaveLanded = !streamAppendWasExplicitlyRejected(cause);
+        if (opCount > 0 || failedAppendMayHaveLanded) {
           throw jsonlPartialSubmissionError({
             acknowledgedOperationCount: completed,
             cause,
-            failedAppendMayHaveLanded: true
+            failedAppendMayHaveLanded,
+            lastAcknowledgedRepoSeq: repoSeq
           });
         }
         throw cause;
@@ -40259,7 +40381,8 @@ async function applyJsonlCommit(ctx, args) {
     }
     throw jsonlPartialSubmissionError({
       acknowledgedOperationCount: opCount,
-      cause: error
+      cause: error,
+      lastAcknowledgedRepoSeq: repoSeq
     });
   }
 }
@@ -40329,9 +40452,10 @@ var handleSubmit = async (ctx, { flags, args }) => {
   const abouts = flags.about ?? [];
   const reasons = flags.reason ?? [];
   const kinds = flags.kind ?? [];
-  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh commit submit --revise Player/alice --data '{...}' --expected-version 3");
-  if (expectedVersion !== undefined && !reviseName) {
-    usageError("--expected-version requires --revise", "wh commit submit --revise Player/alice --data '{...}' --expected-version 3");
+  const expectedVersionExample = retractNames.length > 0 ? "wh commit submit --retract Player/alice --expected-version 3" : "wh commit submit --revise Player/alice --data '{...}' --expected-version 3";
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", expectedVersionExample);
+  if (expectedVersion !== undefined && reviseName === undefined && retractNames.length !== 1) {
+    usageError("--expected-version requires --revise or exactly one --retract", "wh commit submit --retract Player/alice --expected-version 3");
   }
   const leaseIdFlag = requireLeaseIdFlag(flags["lease-id"], `wh commit submit --revise Player/alice --data '{"score":2}' --lease-id <id>`);
   if (leaseIdFlag !== undefined && reviseName === undefined && retractNames.length === 0) {
@@ -40455,6 +40579,7 @@ var handleSubmit = async (ctx, { flags, args }) => {
       retractNames,
       kinds,
       reasons,
+      expectedVersion,
       leaseId: leaseIdFlag
     });
   } else if (operationSource === "--revise") {
@@ -44376,7 +44501,7 @@ var ORG_DOMAIN = defineDomain({
 });
 
 // ../../packages/warmhub-cli/src/domains/prime-content.md
-var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json -m \"msg\" --repo org/repo  # submit operations (bare `wh commit` also works)\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Thing operations\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--kind] [--data] [--reason] [--expected-version] [--chunk-size] [--skip-existing] [--progress] [--stream-id]` — Submit operations (bare `wh commit` is equivalent). Use `--file ops.jsonl --stream-id <id> --chunk-size 5000 --skip-existing` for bulk ingest.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Delete a subscription\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# --about takes an untyped target wref: Shape or Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures when present.\n```\n\n**Create via write entrypoint** (alternative, supports batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # add --kind assertion --about TargetShape/name for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all operations (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# Add-only restart: rerun the WHOLE file. --skip-existing makes fixed-name adds\n# idempotent; --stream-id only identifies the submission. Mid-stream resume is\n# not a CLI mode. Revise/retract JSONL is not full-rerun safe after an ambiguous\n# append; inspect repo state and reconcile.\n```\n\n**Create collections:**\n```bash\nwh commit submit --type arc --name route --members Location/a,Location/b --repo org/repo\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
+var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json -m \"msg\" --repo org/repo  # submit operations (bare `wh commit` also works)\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Thing operations\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind] [--expected-version]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--kind] [--data] [--reason] [--expected-version] [--chunk-size] [--skip-existing] [--progress] [--stream-id]` — Submit operations (bare `wh commit` is equivalent). Use `--file ops.jsonl --stream-id <id> --chunk-size 5000 --skip-existing` for bulk ingest.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer] [--expected-version]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason] [--expected-version]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Delete a subscription\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# --about takes an untyped target wref: Shape or Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures when present.\n```\n\n**Create via write entrypoint** (alternative, supports batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # add --kind assertion --about TargetShape/name for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all operations (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# --stream-id identifies the submission but provides no receipt or resume.\n# After an outcome-unknown append, stop writes and reconcile attempted + unsent\n# work from a later verified checkpoint; never blindly replay revise/retract.\n```\n\n**Create collections:**\n```bash\nwh commit submit --type arc --name route --members Location/a,Location/b --repo org/repo\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
 
 // ../../packages/warmhub-cli/src/domains/prime.ts
 function buildMarkdown(config) {
@@ -45605,6 +45730,9 @@ function renderShapeFieldDiff(out, diff) {
 }
 var retractFlags3 = {
   reason: flag.string({ description: "Reason for retraction (<=500 chars)" }),
+  "expected-version": flag.number({
+    description: "only retract if the target is still at this version (optimistic concurrency)"
+  }),
   message: flag.string({ short: "m", description: "Commit message" }),
   committer: flag.string({
     description: "Committer wref (shape or shaped thing; e.g. Agent/bot-1)"
@@ -45681,16 +45809,18 @@ var handleRevise3 = async (ctx, { flags, args }) => {
 var handleRetract2 = async (ctx, { flags, args }) => {
   const shapeName = args[0];
   if (!shapeName) {
-    usageError("Usage: wh shape retract <name>", "wh shape retract Location");
+    usageError("Usage: wh shape retract <name> [--expected-version <n>]", "wh shape retract Location");
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh shape retract Location --expected-version 3");
   const c = ctx.colors;
   const result = await ctx.client.commit.apply(org, repo, flags.message ?? `retract shape ${shapeName}`, [
     {
       operation: "retract",
       kind: "shape",
       name: shapeName,
-      ...flags.reason ? { reason: flags.reason } : {}
+      ...flags.reason ? { reason: flags.reason } : {},
+      ...expectedVersion !== undefined ? { expectedVersion } : {}
     }
   ], { committer: flags.committer });
   assertSingleOpSuccess(result);
@@ -49203,7 +49333,7 @@ function resolveLogLevel(flagLevel, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.85.0",
+  version: "0.86.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -49820,5 +49950,5 @@ process.exitCode = interceptedExitCode === undefined ? await runPreparedCli(laun
   version: package_default3.version
 }) : interceptedExitCode;
 
-//# debugId=F50B28EECDCA074C64756E2164756E21
-//# warmhub-cli-build-info {"cliVersion":"0.85.0","sdkVersion":"0.83.0"}
+//# debugId=864ACFE03DA5766664756E2164756E21
+//# warmhub-cli-build-info {"cliVersion":"0.86.0","sdkVersion":"0.84.0"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",