@warmhub/sdk-ts 0.82.3 → 0.84.0

package/dist/{chunk-PMLASUR6.js → chunk-CLDVXOJD.js}

@@ -56,6 +56,12 @@ var DEFAULT_STREAM_APPEND_CHUNK_SIZE = 1e3;
 var MAX_STREAM_APPEND_OPERATION_COUNT = 1e4;
 
 // ../rules/src/commit-types.ts
+var COMMIT_OPERATION_KINDS = [
+  "shape",
+  "thing",
+  "assertion",
+  "collection"
+];
 function splitLocalPath(name) {
   const idx = name.indexOf("/");
   if (idx === -1) return null;
@@ -184,26 +190,6 @@ function constantTimeEqualHex(a, b) {
   return diff === 0;
 }
 
-// ../rules/src/repo-auth-scopes.ts
-var REPO_AUTH_SCOPES = [
-  "repo:read",
-  "repo:write",
-  "repo:configure",
-  "repo:admin",
-  // GH-4679: the repo-scoped twin of `org:action-callback`. A narrow capability
-  // for acknowledging a repo-scoped action run's delivery (the async webhook
-  // callback). Deliberately NOT implied by `repo:write` — a webhook handler
-  // (e.g. a component) can be granted exactly this without standing authority to
-  // write things/shapes. The callback gate currently ALSO accepts `repo:write`
-  // so existing consumers (the Veritas worker) keep acking; that broad
-  // acceptance is dropped once consumers move to this scope. Held by
-  // owner/admin roles; grantable to a token (or component manifest) on its own.
-  "repo:action-callback"
-];
-
-// ../rules/src/component-manifest-contract-internals.ts
-new Set(REPO_AUTH_SCOPES);
-
 // ../rules/src/field-name-safety.ts
 var ESCAPE_DISPLAY_MAX_CHARS = 120;
 var DANGEROUS_FORMAT_CODEPOINTS = /* @__PURE__ */ new Set([
@@ -6755,13 +6741,6 @@ function isFieldOptional(fieldKey, typeSpec) {
   return optionalByKey || normalizeOptionalTypeSpec(typeSpec).optionalByType;
 }
 
-// ../rules/src/name-charset.ts
-var RESERVED_NAME_SEGMENT_CHARS = ["?", "#", "@", ":", "$"];
-function escapeForCharClass(char) {
-  return char.replace(/[\\\]^-]/g, "\\$&");
-}
-RESERVED_NAME_SEGMENT_CHARS.map(escapeForCharClass).join("");
-
 // ../rules/src/tokens.ts
 var COMMIT_TOKEN_SYNTAX_REMOVED_MESSAGE = "$N/#N commit-token syntax is no longer supported. Use explicit names and explicit wrefs. For assertions about newly created things, create the thing with a deterministic name and set about to that wref in the same commit.";
 var ANY_TOKEN_RE = /[$#]\d+/;
@@ -7053,39 +7032,6 @@ function preflightCommitDiagnostics2(operations, options) {
   return preflightCommitDiagnostics(operations, options);
 }
 
-// ../rules/src/reserved-orgs.ts
-var RESERVED_RAW_CONTENT_TOP_LEVEL_NAMES = [
-  "_app",
-  "_static",
-  "api",
-  "health",
-  "healthz",
-  "mcp",
-  "readyz",
-  "robots.txt",
-  "sse",
-  "trpc",
-  "version"
-];
-var RESERVED_ORG_NAMES = [
-  ...RESERVED_RAW_CONTENT_TOP_LEVEL_NAMES,
-  "admin",
-  "billing",
-  "blog",
-  "docs",
-  "help",
-  "login",
-  "public",
-  "settings",
-  "signup",
-  "status",
-  "support",
-  "system",
-  "warmhub",
-  "www"
-];
-new Set(RESERVED_ORG_NAMES);
-
 // ../rules/src/shape-field-key.ts
 function foldFieldName(name) {
   const stripped = name.endsWith("?") ? name.slice(0, -1) : name;
@@ -7843,67 +7789,6 @@ function validateShapeDefinition(data, options = {}) {
   return { valid: true };
 }
 
-// ../rules/src/system-components/system.ts
-var SYSTEM_COMPONENT_ID = "com.warmhub.system";
-var COMPONENT_INSTALL_FIELDS = {
-  componentId: "string",
-  name: "string",
-  version: "string",
-  source: "string",
-  "sourceKind?": "string",
-  "sourceRef?": "string",
-  "resolvedSha?": "string",
-  "registeredComponentRef?": "string",
-  manifestHash: "string",
-  state: "string",
-  manifest: "string",
-  installedAt: "string",
-  installedByUserId: "string?",
-  "installId?": "string",
-  "updatedAt?": "string"
-};
-var COMPONENT_CONFIG_FIELDS = {};
-var SYSTEM_MANIFEST = {
-  component: {
-    id: SYSTEM_COMPONENT_ID,
-    name: "system",
-    version: "1.0.0"
-  },
-  shapes: [
-    { name: "ComponentInstall", fields: COMPONENT_INSTALL_FIELDS },
-    { name: "ComponentConfig", fields: COMPONENT_CONFIG_FIELDS }
-  ],
-  credentials: [],
-  subscriptions: [],
-  seeds: [],
-  health: {
-    requires: { shapes: ["ComponentInstall", "ComponentConfig"] }
-  },
-  teardown: {},
-  runtimeAccess: { reads: [], writes: [] }
-};
-var SYSTEM_COMPONENT = {
-  componentId: SYSTEM_COMPONENT_ID,
-  name: SYSTEM_MANIFEST.component.name,
-  version: SYSTEM_MANIFEST.component.version,
-  manifest: SYSTEM_MANIFEST,
-  installInfra: true,
-  shapes: [
-    { name: "ComponentInstall", fields: COMPONENT_INSTALL_FIELDS },
-    { name: "ComponentConfig", fields: COMPONENT_CONFIG_FIELDS }
-  ]
-};
-
-// ../rules/src/system-components/index.ts
-var SYSTEM_COMPONENTS = [
-  SYSTEM_COMPONENT
-];
-new Set(
-  SYSTEM_COMPONENTS.filter((entry) => entry.installInfra === true).flatMap(
-    (entry) => entry.shapes.map((s) => s.name)
-  )
-);
-
 // src/shape-preflight.ts
 function shapeDefinitionPreflightError(name, data, verb) {
   const result = validateShapeDefinition(
@@ -8018,9 +7903,9 @@ function normalizeOptionalName(value) {
 
 // src/operation-normalize.ts
 function toBackendStreamOperation(operation) {
-  if (operation.expectedVersion !== void 0 && operation.operation !== "revise") {
+  if (operation.expectedVersion !== void 0 && operation.operation !== "revise" && operation.operation !== "retract") {
     throw new Error(
-      "expectedVersion is only valid on revise operations \u2014 set operation: 'revise'"
+      "expectedVersion is only valid on revise or retract operations \u2014 set an explicit operation discriminator"
     );
   }
   if (operation.operation === "retract") {
@@ -8029,6 +7914,7 @@ function toBackendStreamOperation(operation) {
       name: operation.name,
       ...operation.kind ? { kind: operation.kind } : {},
       ...operation.reason ? { reason: operation.reason } : {},
+      ...operation.expectedVersion !== void 0 ? { expectedVersion: operation.expectedVersion } : {},
       ...operation.leaseId ? { leaseId: operation.leaseId } : {}
     };
   }
@@ -8133,8 +8019,8 @@ var PartialStreamSubmissionError = class extends Error {
   code = "PARTIAL_STREAM_SUBMISSION";
   /**
    * Operations the SDK confirmed completed before the ambiguous or failing
-   * append. The remaining operations may or may not have landed; inspect
-   * repository state before retrying manually.
+   * append. The attempted append may or may not have landed; do not blindly
+   * replay it.
    */
   completedOperations;
   /**
@@ -8143,19 +8029,36 @@ var PartialStreamSubmissionError = class extends Error {
    * returns sparse or empty result rows.
    */
   acknowledgedOperationCount;
+  /**
+   * Last repository sequence returned by an acknowledged chunk that persisted
+   * an event. This is a lower bound for known completed work, never evidence
+   * that the attempted append did not land.
+   */
+  lastAcknowledgedRepoSeq;
+  /**
+   * Authoritative outcome of the attempted append. `not_applied` is used only
+   * when the SDK received explicit server rejection evidence; `unknown` means
+   * callers must stop writes and reconcile from a later verified checkpoint.
+   */
+  attemptedAppendOutcome;
   /**
    * Underlying error that triggered the partial submission, preserved for
-   * diagnostics. Inspect via `isWarmHubError(err.cause)` / `err.cause.kind`.
+   * diagnostics. Do not infer append outcome from this field; branch on
+   * `attemptedAppendOutcome` instead.
    */
   cause;
   constructor(input) {
     super(
-      "Stream submission failed. A timed-out append may already have landed, so inspect repository state before sending any further operations."
+      "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 !== void 0) {
+      this.lastAcknowledgedRepoSeq = input.lastAcknowledgedRepoSeq;
+    }
   }
 };
 var AllStreamOperationsFailedError = class extends Error {
@@ -8310,6 +8213,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 !== void 0;
+}
 function computeBackoffDelayMs(attempt, policy) {
   const exponential = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
   const jitter = Math.random() * policy.baseDelayMs;
@@ -8366,7 +8272,8 @@ async function submitOperationsViaStream(client, args) {
   )) {
     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({
@@ -8396,7 +8303,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 sleep(computeBackoffDelayMs(attempt, policy));
           attempt += 1;
           priorAttemptAmbiguous = true;
@@ -8421,7 +8328,9 @@ async function submitOperationsViaStream(client, args) {
         throw new PartialStreamSubmissionError({
           cause,
           completedOperations,
-          acknowledgedOperationCount
+          acknowledgedOperationCount,
+          lastAcknowledgedRepoSeq: repoSeq,
+          attemptedAppendOutcome: !priorAttemptAmbiguous && isDefiniteClientError(cause) ? "not_applied" : "unknown"
         });
       }
     }
@@ -8443,7 +8352,9 @@ async function submitOperationsViaStream(client, args) {
       throw new PartialStreamSubmissionError({
         cause: failure,
         completedOperations: completedOperationsFrom(result),
-        acknowledgedOperationCount
+        acknowledgedOperationCount,
+        lastAcknowledgedRepoSeq: repoSeq,
+        attemptedAppendOutcome: "unknown"
       });
     }
     throw failure;
@@ -8570,7 +8481,7 @@ var SDK_DEVELOPMENT_VERSION = "0.0.0-development";
 function sdkVersionIsDevelopment(version) {
   return version === SDK_DEVELOPMENT_VERSION;
 }
-var SDK_VERSION = "0.82.3" ;
+var SDK_VERSION = "0.84.0" ;
 
 // src/component-cli.ts
 var SUPPORTED_METHODS = /* @__PURE__ */ new Set([
@@ -8810,13 +8721,7 @@ function normalizeReviseKind(op, name) {
 }
 function toBackendOp(op) {
   if (op.operation === "retract") {
-    return {
-      operation: "retract",
-      name: op.name,
-      ...op.kind ? { kind: op.kind } : {},
-      ...op.reason ? { reason: op.reason } : {},
-      ...op.leaseId ? { leaseId: op.leaseId } : {}
-    };
+    return toBackendStreamOperation(op);
   }
   if (op.operation === "add") {
     const kind2 = normalizeAddKind(op);
@@ -9069,7 +8974,8 @@ var OperationBuilder = class {
   /**
    * Add a retract operation.
    *
-   * Pass a wref string shorthand or an object with a target name, optional kind safety hint, and optional reason.
+   * Pass a wref string shorthand or an object with retract options such as a
+   * kind safety hint, reason, expected version, or lease ID.
    */
   retract(target) {
     this.assertCanModify();
@@ -9078,6 +8984,7 @@ var OperationBuilder = class {
       name: target.name,
       ...target.kind ? { kind: target.kind } : {},
       ...target.reason ? { reason: target.reason } : {},
+      ...target.expectedVersion !== void 0 ? { expectedVersion: target.expectedVersion } : {},
       ...target.leaseId ? { leaseId: target.leaseId } : {}
     });
     this.ops.push(op);
@@ -9400,20 +9307,31 @@ function assertPaginatedCursorAdvanced(cursor, nextCursor, seenCursors) {
     );
   }
 }
-async function* paginate(fetchPage, extractItems, initialCursor) {
+function assertIncrementalLowerBound(sinceRepoSeq) {
+  if (sinceRepoSeq === void 0) {
+    throw new WarmHubError(
+      "VALIDATION_ERROR",
+      "sinceRepoSeq is required for an incremental read"
+    );
+  }
+}
+async function* paginatePages(fetchPage, initialCursor) {
   let cursor = initialCursor;
   const seenCursors = /* @__PURE__ */ new Set();
   for (; ; ) {
     if (cursor) seenCursors.add(cursor);
     const page = await fetchPage(cursor);
-    for (const item of extractItems(page)) {
-      yield item;
-    }
+    yield page;
     if (!page.nextCursor) return;
     assertPaginatedCursorAdvanced(cursor, page.nextCursor, seenCursors);
     cursor = page.nextCursor;
   }
 }
+async function* paginate(fetchPage, extractItems, initialCursor) {
+  for await (const page of paginatePages(fetchPage, initialCursor)) {
+    yield* extractItems(page);
+  }
+}
 async function collectPaginatedPages(fetchPage, extractItems, max, initialCursor) {
   if (max !== void 0 && (!Number.isFinite(max) || Math.trunc(max) !== max || max < 0)) {
     throw new WarmHubError(
@@ -9422,11 +9340,7 @@ async function collectPaginatedPages(fetchPage, extractItems, max, initialCursor
     );
   }
   const items = [];
-  let cursor = initialCursor;
-  const seenCursors = /* @__PURE__ */ new Set();
-  for (; ; ) {
-    if (cursor) seenCursors.add(cursor);
-    const page = await fetchPage(cursor);
+  for await (const page of paginatePages(fetchPage, initialCursor)) {
     const pageItems = extractItems(page);
     if (max !== void 0 && items.length + pageItems.length > max) {
       throw new WarmHubError(
@@ -9435,7 +9349,34 @@ async function collectPaginatedPages(fetchPage, extractItems, max, initialCursor
       );
     }
     items.push(...pageItems);
-    if (!page.nextCursor) return items;
+  }
+  return items;
+}
+function assertRepoExploreBrowseMode(opts) {
+  if (opts?.slugs !== void 0) {
+    throw new WarmHubError(
+      "VALIDATION_ERROR",
+      "repo.explore pagination helpers do not support slugs mode"
+    );
+  }
+}
+async function collectIncrementalPages(fetchPage) {
+  const items = [];
+  let cursor;
+  const seenCursors = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    if (cursor) seenCursors.add(cursor);
+    const page = await fetchPage(cursor);
+    items.push(...page.items);
+    if (!page.nextCursor) {
+      if (page.repoSeq === void 0) {
+        throw new WarmHubError(
+          "VALIDATION_ERROR",
+          "Incremental read completed without repoSeq"
+        );
+      }
+      return { items, repoSeq: page.repoSeq };
+    }
     assertPaginatedCursorAdvanced(cursor, page.nextCursor, seenCursors);
     cursor = page.nextCursor;
   }
@@ -9451,6 +9392,9 @@ function chunkArray(items, chunkSize) {
   }
   return chunks;
 }
+function narrowKind(kind) {
+  return kind !== void 0 && COMMIT_OPERATION_KINDS.includes(kind) ? kind : void 0;
+}
 function toSubscriptionRef(args) {
   const [first, repoName, name] = args;
   return typeof first === "string" ? { orgName: first, repoName, name } : first;
@@ -9979,11 +9923,40 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate installed components. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    listIter: (orgName, repoName, opts) => {
+      return paginate(
+        (cursor) => this.component.list(orgName, repoName, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize installed components. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    listAll: async (orgName, repoName, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.component.list(orgName, repoName, { ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Search registered components visible to the caller across all orgs
      * (GH-4383): public components plus private components the caller can
      * read. Distinct from listing components installed in a repo
      * (`component.list`).
+     *
+     * Cursor contract: cursors resume the same query and result scope; on
+     * `VALIDATION_ERROR` / `Invalid cursor`, restart the query without `cursor`.
      */
     search: async (query, opts) => {
       try {
@@ -9996,6 +9969,32 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate global component search hits. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    searchIter: (query, opts) => {
+      return paginate(
+        (cursor) => this.component.search(query, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize global component search hits. Cursors resume the same query
+     * and result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the
+     * query without `cursor`.
+     */
+    searchAll: async (query, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.component.search(query, { ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Fetch one installed component by its `Org/Name` ref.
      */
@@ -10604,10 +10603,39 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate organization repositories. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    listIter: (orgName, opts) => {
+      return paginate(
+        (cursor) => this.repo.list(orgName, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize organization repositories. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    listAll: async (orgName, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.repo.list(orgName, { ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Search repos visible to the caller across all orgs (GH-4383): public
      * repos plus private repos the caller can read. BM25 over
      * name/description/shape vocabulary/README.
+     *
+     * Cursor contract: cursors resume the same query and result scope; on
+     * `VALIDATION_ERROR` / `Invalid cursor`, restart the query without `cursor`.
      */
     search: async (query, opts) => {
       try {
@@ -10620,6 +10648,32 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate global repository search hits. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    searchIter: (query, opts) => {
+      return paginate(
+        (cursor) => this.repo.search(query, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize global repository search hits. Cursors resume the same query
+     * and result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the
+     * query without `cursor`.
+     */
+    searchAll: async (query, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.repo.search(query, { ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Create a repository inside an organization.
      *
@@ -10784,6 +10838,32 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate repository rows with stats. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    listPageIter: (orgName, opts) => {
+      return paginate(
+        (cursor) => this.repo.listPage(orgName, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize repository rows with stats. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    listPageAll: async (orgName, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.repo.listPage(orgName, { ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * List the caller's repositories across every org they belong to, ordered
      * for recency by default (most recently written first), capped at `limit`.
@@ -10845,6 +10925,36 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate public Explore browse results. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`. Exact `slugs` lookup is not pageable.
+     */
+    exploreIter: (opts) => {
+      assertRepoExploreBrowseMode(opts);
+      return paginate(
+        (cursor) => this.repo.explore({ ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize public Explore browse results. Cursors resume the same query
+     * and result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the
+     * query without `cursor`. Exact `slugs` lookup is not pageable. `max`
+     * remains optional as part of the uniform `*All` contract; callers should
+     * provide a finite cap for this offset-paginated endpoint.
+     */
+    exploreAll: async (opts) => {
+      assertRepoExploreBrowseMode(opts);
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.repo.explore({ ...pageOpts, cursor }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Fetch a repository's `Content/Readme` markdown record.
      *
@@ -11142,6 +11252,32 @@ var WarmHubClient = class _WarmHubClient {
       } catch (error) {
         throw toWarmHubError(error);
       }
+    },
+    /**
+     * Iterate shape versions. Cursors resume the same query and result scope;
+     * on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    historyIter: (orgName, repoName, name, opts = {}) => {
+      return paginate(
+        (cursor) => this.shape.history(orgName, repoName, name, { ...opts, cursor }),
+        (page) => page.versions,
+        opts.cursor
+      );
+    },
+    /**
+     * Materialize shape versions. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    historyAll: async (orgName, repoName, name, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.shape.history(orgName, repoName, name, { ...pageOpts, cursor }),
+        (page) => page.versions,
+        max,
+        pageOpts.cursor
+      );
     }
   };
   /**
@@ -11423,6 +11559,38 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate delivery-feed entries. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    liveFeedIter: (orgName, repoName, subscriptionName, opts) => {
+      return paginate(
+        (cursor) => this.action.liveFeed(orgName, repoName, subscriptionName, {
+          ...opts,
+          cursor
+        }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize delivery-feed entries. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    liveFeedAll: async (orgName, repoName, subscriptionName, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.action.liveFeed(orgName, repoName, subscriptionName, {
+          ...pageOpts,
+          cursor
+        }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * List subscription action runs as a `Page<ActionRunInfo>` (`items` +
      * optional `nextCursor`), newest-first, capped at 200 runs per page.
@@ -11430,8 +11598,9 @@ var WarmHubClient = class _WarmHubClient {
      * `status` and `outcome` are mutually exclusive.
      * `since` and `cursor` are mutually exclusive; pass `cursor` alone on later
      * pages — the `since` window rides in the cursor.
-     * Cursors are opaque, short-lived resume tokens; on `VALIDATION_ERROR`
-     * restart the query without `cursor`.
+     * Cursors are opaque, short-lived resume tokens for the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
      * See docs/dev/warmhub-actions-api.md for the full contract.
      */
     listRuns: async (orgName, repoName, opts) => {
@@ -11439,6 +11608,7 @@ var WarmHubClient = class _WarmHubClient {
         return await this.trpc.action.listRuns.query({
           orgName,
           repoName,
+          runId: opts?.runId,
           subscriptionName: opts?.subscriptionName,
           status: opts?.status,
           outcome: opts?.outcome,
@@ -11450,6 +11620,40 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate action runs. Cursors resume the same query and result scope; on
+     * `VALIDATION_ERROR` / `Invalid cursor`, restart the query without `cursor`.
+     * `since` is sent only on the initial request.
+     */
+    listRunsIter: (orgName, repoName, opts) => {
+      return paginate(
+        (cursor) => this.action.listRuns(orgName, repoName, {
+          ...opts,
+          since: cursor === void 0 ? opts?.since : void 0,
+          cursor
+        }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize action runs. Cursors resume the same query and result scope;
+     * on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`. `since` is sent only on the initial request.
+     */
+    listRunsAll: async (orgName, repoName, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.action.listRuns(orgName, repoName, {
+          ...pageOpts,
+          since: cursor === void 0 ? pageOpts.since : void 0,
+          cursor
+        }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Return the newest visible action run for each subscription in a repo.
      *
@@ -11541,6 +11745,11 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Read one collection-membership page. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
     members: async (orgName, repoName, wref, opts) => {
       try {
         return await this.trpc.collection.members.query({
@@ -11555,6 +11764,11 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate collection members. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
     membersIter: (orgName, repoName, wref, opts) => {
       let snapshotVersion = opts?.version;
       return paginate(
@@ -11571,6 +11785,11 @@ var WarmHubClient = class _WarmHubClient {
         opts?.cursor
       );
     },
+    /**
+     * Materialize collection members. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
     membersAll: async (orgName, repoName, wref, opts) => {
       const { max, ...pageOpts } = opts ?? {};
       let snapshotVersion = pageOpts.version;
@@ -11694,12 +11913,11 @@ var WarmHubClient = class _WarmHubClient {
      */
     head: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : void 0;
         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,
@@ -11708,7 +11926,8 @@ var WarmHubClient = class _WarmHubClient {
           componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
-          where: opts?.where
+          where: opts?.where,
+          sinceRepoSeq: opts?.sinceRepoSeq
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -11752,6 +11971,26 @@ var WarmHubClient = class _WarmHubClient {
         pageOpts.cursor
       );
     },
+    /**
+     * Materialize identity-owned changes after a repository sequence and return
+     * the exact checkpoint reached by the completed scan.
+     *
+     * Key a local cache by `item.metadata.durableId`: an identity rename
+     * carries its checkpoint wref, and a retraction carries `active: false`.
+     * This helper forces retracted rows on and returns only after draining the
+     * terminal page. It does not fan out changes caused by another identity
+     * and therefore is not, by itself, a complete local-result-mirror protocol.
+     */
+    headChanges: async (orgName, repoName, opts) => {
+      assertIncrementalLowerBound(opts?.sinceRepoSeq);
+      return await collectIncrementalPages(
+        (cursor) => this.thing.head(orgName, repoName, {
+          ...opts,
+          includeRetracted: true,
+          cursor
+        })
+      );
+    },
     /**
      * Get one thing, assertion, shape, or collection by wref.
      *
@@ -11985,6 +12224,32 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate thing history versions. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    historyIter: (orgName, repoName, opts) => {
+      return paginate(
+        (cursor) => this.thing.history(orgName, repoName, { ...opts, cursor }),
+        (page) => page.versions,
+        opts.cursor
+      );
+    },
+    /**
+     * Materialize thing history versions. Cursors resume the same query and
+     * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+     * without `cursor`.
+     */
+    historyAll: async (orgName, repoName, opts) => {
+      const { max, ...pageOpts } = opts;
+      return await collectPaginatedPages(
+        (cursor) => this.thing.history(orgName, repoName, { ...pageOpts, cursor }),
+        (page) => page.versions,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Rename a thing within its shape namespace.
      *
@@ -12111,13 +12376,12 @@ var WarmHubClient = class _WarmHubClient {
      */
     query: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : void 0;
         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,
@@ -12127,7 +12391,8 @@ var WarmHubClient = class _WarmHubClient {
           componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
-          where: opts?.where
+          where: opts?.where,
+          sinceRepoSeq: opts?.sinceRepoSeq
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -12171,6 +12436,26 @@ var WarmHubClient = class _WarmHubClient {
         pageOpts.cursor
       );
     },
+    /**
+     * Materialize filtered identity-owned changes after a repository sequence
+     * and return the exact checkpoint reached by the completed scan.
+     *
+     * Key a local cache by `item.metadata.durableId`: an identity rename
+     * carries its checkpoint wref, and a retraction carries `active: false`.
+     * This helper forces retracted rows on and returns only after draining the
+     * terminal page. It does not fan out changes caused by another identity
+     * and therefore is not, by itself, a complete local-result-mirror protocol.
+     */
+    queryChanges: async (orgName, repoName, opts) => {
+      assertIncrementalLowerBound(opts?.sinceRepoSeq);
+      return await collectIncrementalPages(
+        (cursor) => this.thing.query(orgName, repoName, {
+          ...opts,
+          includeRetracted: true,
+          cursor
+        })
+      );
+    },
     /**
      * Search repository records with text, vector, or hybrid mode.
      *
@@ -12184,14 +12469,13 @@ var WarmHubClient = 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 : void 0;
         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,
@@ -12207,25 +12491,54 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Iterate ranked search hits. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    searchIter: (orgName, repoName, query, opts) => {
+      return paginate(
+        (cursor) => this.thing.search(orgName, repoName, query, { ...opts, cursor }),
+        (page) => page.items,
+        opts?.cursor
+      );
+    },
+    /**
+     * Materialize ranked search hits. Cursors resume the same query and result
+     * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+     * `cursor`.
+     */
+    searchAll: async (orgName, repoName, query, opts) => {
+      const { max, ...pageOpts } = opts ?? {};
+      return await collectPaginatedPages(
+        (cursor) => this.thing.search(orgName, repoName, query, {
+          ...pageOpts,
+          cursor
+        }),
+        (page) => page.items,
+        max,
+        pageOpts.cursor
+      );
+    },
     /**
      * Count matching repository records without returning record data.
      */
     count: async (orgName, repoName, opts) => {
       try {
-        const kind = opts?.kind === "shape" || opts?.kind === "thing" || opts?.kind === "assertion" || opts?.kind === "collection" ? opts.kind : void 0;
         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,
           componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
-          where: opts?.where
+          where: opts?.where,
+          sinceRepoSeq: opts?.sinceRepoSeq
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -12987,5 +13300,5 @@ re2js/build/index.js:
 */
 
 export { AllStreamOperationsFailedError, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, CliCallVerificationError, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT2 as MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };
-//# sourceMappingURL=chunk-PMLASUR6.js.map
-//# sourceMappingURL=chunk-PMLASUR6.js.map
+//# sourceMappingURL=chunk-CLDVXOJD.js.map
+//# sourceMappingURL=chunk-CLDVXOJD.js.map