@warmhub/sdk-ts 0.82.3 → 0.84.0

package/dist/index.d.ts

@@ -644,6 +644,7 @@ type StreamAppendInput$1 = {
         name: string;
         kind?: 'shape' | 'thing' | 'assertion' | 'collection';
         reason?: string;
+        expectedVersion?: number;
         leaseId?: string;
     } | {
         operation: 'rename';
@@ -1250,6 +1251,11 @@ interface RetractOperation {
      * Optional human-readable retraction reason.
      */
     reason?: string;
+    /**
+     * Optional optimistic-concurrency precondition. When supplied, the retract
+     * is applied only if the target is still at this version number.
+     */
+    expectedVersion?: number;
     /**
      * Optional read-lease token (#3625) returned by `thing.getWithLease`. A
      * matching token auto-releases the lease on commit; a mismatch (or absence
@@ -1408,9 +1414,11 @@ type StreamFailureCause = {
  *
  * The `completedOperations` field contains returned rows the SDK knows
  * completed. `acknowledgedOperationCount` also records progress when an append
- * response contains sparse or empty result rows. Before retrying manually,
- * inspect repository state because the failed append may have committed
- * additional operations that were not reflected locally.
+ * response contains sparse or empty result rows. If the attempted append is
+ * outcome-unknown, stop writes until it can no longer apply, then obtain a
+ * later verified checkpoint and reconcile it with the acknowledged receipt.
+ * Branch on `attemptedAppendOutcome`; the underlying `cause` is diagnostic and
+ * may describe a later rejection that followed an earlier ambiguous attempt.
  *
  * @see https://docs.warmhub.ai/sdk/transient-retry/#partial-submissions
  */
@@ -1421,8 +1429,8 @@ declare class PartialStreamSubmissionError extends Error {
     readonly 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.
      * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#completedoperations
      */
     readonly completedOperations: SubmittedStreamResult['operations'];
@@ -1433,9 +1441,23 @@ declare class PartialStreamSubmissionError extends Error {
      * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#acknowledgedoperationcount
      */
     readonly acknowledgedOperationCount: number;
+    /**
+     * 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.
+     */
+    readonly lastAcknowledgedRepoSeq?: number;
+    /**
+     * 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.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#attemptedappendoutcome
+     */
+    readonly attemptedAppendOutcome: 'not_applied' | 'unknown';
     /**
      * 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.
      * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#cause
      */
     readonly cause: unknown;
@@ -1443,6 +1465,8 @@ declare class PartialStreamSubmissionError extends Error {
         cause: unknown;
         completedOperations: SubmittedStreamResult['operations'];
         acknowledgedOperationCount?: number;
+        lastAcknowledgedRepoSeq?: number;
+        attemptedAppendOutcome: 'not_applied' | 'unknown';
     });
 }
 /**
@@ -1463,41 +1487,50 @@ declare class AllStreamOperationsFailedError extends Error {
  * Submit `operations` to the WarmHub stream-append surface, chunked to
  * stay under MAX_STREAM_APPEND_OPERATION_COUNT.
  *
- * **Retry policy (default-on, first-chunk + single-op only).** A
- * transport-ambiguous failure (timeout / 5xx / network reset / no-code
- * error) on the first chunk triggers a bounded retry — but only when
- * the first chunk contains exactly one operation. The SDK mints a
- * fresh `streamId`, sleeps with jittered
+ * **Retry policy (default-on, first-chunk + single-op + replay-safe
+ * only).** A transport-ambiguous failure (timeout / 5xx / network reset
+ * / no-code error) on the first chunk triggers a bounded retry — but
+ * only when the first chunk contains exactly one operation and that
+ * operation carries a server-enforceable replay fence (see below). The
+ * SDK mints a fresh `streamId`, sleeps with jittered
  * exponential backoff, and re-issues the same operation. The retried
  * call is observationally indistinguishable from a single clean
  * apply — the SDK does not rewrite the request or the response.
  *
- * Multi-op chunks bypass retry entirely because the backend applies
- * operations one-at-a-time in their own transactions, so a mid-chunk
- * transport failure on attempt 1 may have committed an arbitrary
- * prefix. Multi-chunk mid-flight failures (`acknowledgedOperationCount > 0`)
- * also bypass retry. Both surface `PartialStreamSubmissionError`; callers must
- * inspect repository state and resume only operations known not to have landed.
+ * Multi-op chunks bypass retry entirely. One `stream.append` executes in one
+ * database transaction, but a lost response still leaves its per-operation
+ * result vector and repository sequence unknown. Replaying it could produce
+ * different noops, conflicts, or dependency outcomes. Multi-chunk mid-flight
+ * failures (`acknowledgedOperationCount > 0`) also bypass retry. Both surface
+ * `PartialStreamSubmissionError`; callers must stop writes and reconcile the
+ * attempted append from a later verified checkpoint.
+ *
+ * **Unfenced `revise` never auto-retries.** A `revise` without
+ * `expectedVersion` has no server-side precondition, so a replay could
+ * silently overwrite a concurrent revision (lost update). Its ambiguous
+ * failure surfaces as `PartialStreamSubmissionError` instead, preserving
+ * the stop-and-reconcile guidance. Canonical rationale:
+ * `isReplaySafeOperation` in stream-submit-utils.ts.
  *
  * Definite client rejections (`UNAUTHENTICATED`, `VALIDATION_ERROR`,
  * `CONFLICT`, `RATE_LIMITED`, `ALREADY_RETRACTED`, …) on the first chunk
  * still rethrow the raw cause unchanged — they
  * are not transient, and structured detail (e.g. `retryAfter` on
  * `RATE_LIMITED`) survives. If the caller's original attempt landed but
- * the response was lost, the retry surfaces the resulting `CONFLICT`
- * (for `add`) or `ALREADY_RETRACTED` (for `retract`) directly so the
- * caller sees the truth.
+ * the response was lost, a resulting `CONFLICT` (for `add`) or
+ * `ALREADY_RETRACTED` (for `retract`) on the retry does not disprove that the
+ * first attempt landed, so the SDK preserves the ambiguous partial error.
  *
  * `COMMIT_OUTCOME_UNKNOWN` is terminal but ambiguous: the SDK never
  * replays it and surfaces `PartialStreamSubmissionError` with the original
- * cause so callers must inspect repository state before continuing.
+ * cause so callers must stop writes and reconcile from a later checkpoint.
  *
  * **Ambiguity preservation across attempts.** Once any attempt has
  * been transport-ambiguous (timeout / 5xx / reset), a subsequent
  * definite-reject (e.g. `RATE_LIMITED` on a quota check) does *not*
  * prove the prior attempt didn't land. In that case the SDK wraps the
  * cause as `PartialStreamSubmissionError` instead of rethrowing raw,
- * so the "inspect repo state before continuing" warning survives.
+ * so the stop-and-reconcile warning survives.
  *
  * **Operation normalization.** `args.operations` accepts the public
  * `Operation[]` write contract. The SDK normalizes operations to the
@@ -1515,8 +1548,9 @@ declare class AllStreamOperationsFailedError extends Error {
  * `args.skipExisting: true` applies `skipExisting: true` to every
  * normalized `add` op. The server then returns `noop` for `add` ops
  * whose target already exists. `revise` is naturally idempotent on
- * equal `dataHash` + `aboutThingId`; built-in collection adds dedupe
- * on `dataHash`.
+ * equal `dataHash` + `aboutThingId`, but only against an exact replay —
+ * that no-op gate does not make an unfenced `revise` retry-safe (see
+ * above); built-in collection adds dedupe on `dataHash`.
  *
  * Pass `args.retry: false` to disable retry entirely; pass
  * `args.retry: { maxAttempts, baseDelayMs, maxDelayMs }` to override
@@ -1821,6 +1855,11 @@ interface RetractOp {
      * Optional human-readable retraction reason.
      */
     readonly reason?: string;
+    /**
+     * Optional optimistic-concurrency precondition. When supplied, the retract
+     * is applied only if the target is still at this version number.
+     */
+    readonly expectedVersion?: number;
     /**
      * Optional read-lease token (#3625) returned by `thing.getWithLease`. When
      * it matches the target's active lease the lease auto-releases on commit;
@@ -1943,15 +1982,11 @@ declare class OperationBuilder {
     /**
      * 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.
      * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#retract
      */
-    retract(target: string | {
-        name: string;
-        kind?: CommitOperationKind;
-        reason?: string;
-        leaseId?: string;
-    }): this;
+    retract(target: string | Omit<RetractOp, 'operation'>): this;
     /**
      * Return the queued operations.
      *
@@ -2337,6 +2372,8 @@ type ActionNotificationInfo = ActionNotification;
 /** @internal */
 type ActionLiveFeed = ActionLiveFeedResult;
 /** @internal */
+type ActionLiveFeedItem = ActionLiveFeed['items'][number];
+/** @internal */
 type ActionLeaseAcquire = {
     ok: true;
     reused: boolean;
@@ -2662,6 +2699,10 @@ type RepoListForCallerOptions = {
  * @internal
  */
 type RepoExploreOptions = RepoExploreInput;
+/** @internal */
+type RepoExploreBrowseOptions = Omit<RepoExploreOptions, 'slugs'> & {
+    slugs?: never;
+};
 /**
  * A repository row in the public "Explore" directory
  * (`client.repo.explore`).
@@ -2819,6 +2860,17 @@ type ThingHeadOptions = Omit<ThingHeadRequest, 'orgName' | 'repoName'>;
 type HeadResult = {
     items: ThingItem[];
     nextCursor?: string;
+    /** Completed incremental scan checkpoint; omitted on ordinary and nonterminal pages. */
+    repoSeq?: number;
+};
+/** @internal */
+type ThingHeadChangesOptions = Omit<ThingHeadOptions, 'cursor' | 'includeRetracted' | 'sinceRepoSeq'> & {
+    sinceRepoSeq: number;
+};
+/** @internal */
+type ThingChanges = {
+    items: ThingItem[];
+    repoSeq: number;
 };
 /** @internal */
 type ThingGet = ThingDetail;
@@ -2911,32 +2963,17 @@ type ThingGraphResult = ThingDetail & {
 /** @internal */
 type ThingHistory = HistoryResult;
 /** @internal */
-type HistoryResult = ThingHistoryResult & {
+type HistoryVersion = ThingHistoryResult['versions'][number] & Record<string, unknown>;
+/** @internal */
+type HistoryResult = Omit<ThingHistoryResult, 'versions'> & {
     thing?: {
         wref: string;
         name?: string;
         kind: string;
         shapeName?: string;
     };
-    versions: Array<{
-        version: number;
-        wref: string;
-        operation: CommitOperation;
-        retractReason?: string;
-        active: boolean;
-        createdAt: number;
-        thingName?: string;
-        thingKind?: string;
-        shapeName?: string;
-        data?: unknown;
-        aboutWref?: string;
-        committerWref?: string;
-        /** #4848 Phase C: per-version author (renamed from createdByWref). */
-        revisedBy?: string;
-        metadata?: Pick<ThingMetadata, 'durableId' | 'createdOn'>;
-        [key: string]: unknown;
-    }>;
-    nextCursor?: string;
+    /** History rows retain forward-compatible backend fields. */
+    versions: HistoryVersion[];
 };
 /** @internal */
 type ThingHeadRequest = {
@@ -2953,6 +2990,8 @@ type ThingHeadRequest = {
     excludeComponents?: boolean;
     excludeInfraShapes?: boolean;
     where?: WherePredicate[];
+    /** Strict lower repository sequence for an incremental scan; `-1` seeds a complete snapshot. */
+    sinceRepoSeq?: number;
 };
 /** @internal */
 type ThingHead = HeadResult;
@@ -2994,6 +3033,7 @@ type LiveRepoEvent = {
 };
 /** @internal */
 type ActionListRunsOptions = {
+    runId?: string;
     subscriptionName?: string;
     status?: 'pending' | 'running' | 'processing' | 'retry_wait' | 'succeeded' | 'suppressed' | 'failed_terminal' | 'dead_letter';
     outcome?: 'succeeded' | 'failed';
@@ -3127,7 +3167,7 @@ type AboutResult = {
 /** @internal */
 type FilterResult = HeadResult;
 /** @internal */
-type SearchResult = HeadResult;
+type SearchResult = Omit<HeadResult, 'repoSeq'>;
 /** @internal */
 type RefsResult = RefsResult$1;
 /** @internal */
@@ -3153,6 +3193,8 @@ type ThingHeadVersionsResult = ThingHeadVersionsResult$1;
 /** @internal */
 type CountResult = {
     count: number;
+    /** Completed incremental scan checkpoint; omitted from ordinary counts. */
+    repoSeq?: number;
 };
 /** @internal */
 type AboutOptions = {
@@ -3242,6 +3284,12 @@ type FilterOptions = {
      * Up to 8 predicates per call.
      */
     where?: WherePredicate[];
+    /** Strict lower repository sequence for an incremental scan; `-1` seeds a complete snapshot. */
+    sinceRepoSeq?: number;
+};
+/** @internal */
+type ThingQueryChangesOptions = Omit<FilterOptions, 'cursor' | 'includeRetracted' | 'sinceRepoSeq'> & {
+    sinceRepoSeq: number;
 };
 /**
  * Options for `client.thing.search`. Search does not support field-value
@@ -3252,7 +3300,7 @@ type FilterOptions = {
  *
  * @see https://docs.warmhub.ai/sdk/read-semantics/#search-modes
  */
-type SearchOptions = Omit<FilterOptions, 'where' | 'role'> & {
+type SearchOptions = Omit<FilterOptions, 'where' | 'role' | 'sinceRepoSeq'> & {
     /** Restrict the search to assertions about this wref target. */
     about?: string;
     /** Search mode: `text` (BM25), `vector` (semantic), or `hybrid` (combined). Defaults to `text`. */
@@ -3649,13 +3697,44 @@ declare class WarmHubClient {
          * token.
          */
         list: (orgName: string, repoName: string, opts?: ComponentListOptions) => Promise<ComponentList>;
+        /**
+         * Iterate installed components. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        listIter: (orgName: string, repoName: string, opts?: ComponentListOptions) => AsyncIterableIterator<ComponentInfo>;
+        /**
+         * Materialize installed components. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        listAll: (orgName: string, repoName: string, opts?: ComponentListOptions & {
+            max?: number;
+        }) => Promise<ComponentInfo[]>;
         /**
          * 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: (query: string, opts?: GlobalSearchOptions) => Promise<GlobalSearchResult>;
+        /**
+         * 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: string, opts?: GlobalSearchOptions) => AsyncIterableIterator<GlobalSearchResultItem>;
+        /**
+         * Materialize global component search hits. Cursors resume the same query
+         * and result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the
+         * query without `cursor`.
+         */
+        searchAll: (query: string, opts?: GlobalSearchOptions & {
+            max?: number;
+        }) => Promise<GlobalSearchResultItem[]>;
         /**
          * Fetch one installed component by its `Org/Name` ref.
          */
@@ -3937,12 +4016,43 @@ declare class WarmHubClient {
          * token.
          */
         list: (orgName: string, opts?: RepoListOptions) => Promise<RepoList>;
+        /**
+         * Iterate organization repositories. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        listIter: (orgName: string, opts?: RepoListOptions) => AsyncIterableIterator<RepoInfo>;
+        /**
+         * Materialize organization repositories. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        listAll: (orgName: string, opts?: RepoListOptions & {
+            max?: number;
+        }) => Promise<RepoInfo[]>;
         /**
          * 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: (query: string, opts?: GlobalSearchOptions) => Promise<GlobalSearchResult>;
+        /**
+         * 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: string, opts?: GlobalSearchOptions) => AsyncIterableIterator<GlobalSearchResultItem>;
+        /**
+         * Materialize global repository search hits. Cursors resume the same query
+         * and result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the
+         * query without `cursor`.
+         */
+        searchAll: (query: string, opts?: GlobalSearchOptions & {
+            max?: number;
+        }) => Promise<GlobalSearchResultItem[]>;
         /**
          * Create a repository inside an organization.
          *
@@ -4015,6 +4125,20 @@ declare class WarmHubClient {
          * token.
          */
         listPage: (orgName: string, opts?: RepoListPageOptions) => Promise<RepoListPageResult>;
+        /**
+         * 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: string, opts?: RepoListPageOptions) => AsyncIterableIterator<RepoWithStatsInfo>;
+        /**
+         * Materialize repository rows with stats. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        listPageAll: (orgName: string, opts?: RepoListPageOptions & {
+            max?: number;
+        }) => Promise<RepoWithStatsInfo[]>;
         /**
          * List the caller's repositories across every org they belong to, ordered
          * for recency by default (most recently written first), capped at `limit`.
@@ -4051,6 +4175,22 @@ declare class WarmHubClient {
          * token.
          */
         explore: (opts?: RepoExploreOptions) => Promise<RepoExploreResult>;
+        /**
+         * 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?: RepoExploreBrowseOptions) => AsyncIterableIterator<RepoExploreItem>;
+        /**
+         * 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: (opts?: RepoExploreBrowseOptions & {
+            max?: number;
+        }) => Promise<RepoExploreItem[]>;
         /**
          * Fetch a repository's `Content/Readme` markdown record.
          *
@@ -4174,6 +4314,20 @@ declare class WarmHubClient {
          * token.
          */
         history: (orgName: string, repoName: string, name: string, opts?: ShapeHistoryOptions) => Promise<ShapeHistory>;
+        /**
+         * Iterate shape versions. Cursors resume the same query and result scope;
+         * on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        historyIter: (orgName: string, repoName: string, name: string, opts?: ShapeHistoryOptions) => AsyncIterableIterator<HistoryVersion>;
+        /**
+         * Materialize shape versions. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        historyAll: (orgName: string, repoName: string, name: string, opts?: ShapeHistoryOptions & {
+            max?: number;
+        }) => Promise<HistoryVersion[]>;
     };
     /**
      * Webhook subscription management surface scoped to a repository.
@@ -4309,6 +4463,20 @@ declare class WarmHubClient {
          * token.
          */
         liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
+        /**
+         * Iterate delivery-feed entries. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        liveFeedIter: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => AsyncIterableIterator<ActionLiveFeedItem>;
+        /**
+         * Materialize delivery-feed entries. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        liveFeedAll: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions & {
+            max?: number;
+        }) => Promise<ActionLiveFeedItem[]>;
         /**
          * List subscription action runs as a `Page<ActionRunInfo>` (`items` +
          * optional `nextCursor`), newest-first, capped at 200 runs per page.
@@ -4316,11 +4484,26 @@ declare 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: (orgName: string, repoName: string, opts?: ActionListRunsOptions) => Promise<Page<ActionRunInfo>>;
+        /**
+         * 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: string, repoName: string, opts?: ActionListRunsOptions) => AsyncIterableIterator<ActionRunInfo>;
+        /**
+         * 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: (orgName: string, repoName: string, opts?: ActionListRunsOptions & {
+            max?: number;
+        }) => Promise<ActionRunInfo[]>;
         /**
          * Return the newest visible action run for each subscription in a repo.
          *
@@ -4351,8 +4534,23 @@ declare class WarmHubClient {
     };
     readonly collection: {
         create: (orgName: string, repoName: string, opts: CollectionCreateOptions) => Promise<CollectionMutationResult>;
+        /**
+         * Read one collection-membership page. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
         members: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: CollectionMembersOptions) => Promise<CollectionMembersPage>;
+        /**
+         * Iterate collection members. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
         membersIter: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: CollectionMembersOptions) => AsyncIterableIterator<CollectionMember>;
+        /**
+         * Materialize collection members. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
         membersAll: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: CollectionMembersOptions & {
             max?: number;
         }) => Promise<CollectionMember[]>;
@@ -4391,7 +4589,7 @@ declare class WarmHubClient {
          * cursor`; restart the query without `cursor` instead of retrying the stale
          * token.
          */
-        headIter: (orgName: string, repoName: string, opts?: ThingHeadOptions) => AsyncIterableIterator<ThingItem>;
+        headIter: (orgName: string, repoName: string, opts?: Omit<ThingHeadOptions, "sinceRepoSeq">) => AsyncIterableIterator<ThingItem>;
         /**
          * Materialize every current HEAD row matching the supplied filters.
          *
@@ -4403,9 +4601,20 @@ declare class WarmHubClient {
          * cursor`; restart the query without `cursor` instead of retrying the stale
          * token.
          */
-        headAll: (orgName: string, repoName: string, opts?: ThingHeadOptions & {
+        headAll: (orgName: string, repoName: string, opts?: Omit<ThingHeadOptions, "sinceRepoSeq"> & {
             max?: number;
         }) => Promise<ThingItem[]>;
+        /**
+         * 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: (orgName: string, repoName: string, opts: ThingHeadChangesOptions) => Promise<ThingChanges>;
         /**
          * Get one thing, assertion, shape, or collection by wref.
          *
@@ -4497,6 +4706,20 @@ declare class WarmHubClient {
          * token.
          */
         history: (orgName: string | undefined, repoName: string | undefined, opts: ThingHistoryOptions) => Promise<ThingHistory>;
+        /**
+         * Iterate thing history versions. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        historyIter: (orgName: string | undefined, repoName: string | undefined, opts: ThingHistoryOptions) => AsyncIterableIterator<HistoryVersion>;
+        /**
+         * Materialize thing history versions. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        historyAll: (orgName: string | undefined, repoName: string | undefined, opts: ThingHistoryOptions & {
+            max?: number;
+        }) => Promise<HistoryVersion[]>;
         /**
          * Rename a thing within its shape namespace.
          *
@@ -4580,7 +4803,7 @@ declare class WarmHubClient {
          * cursor`; restart the query without `cursor` instead of retrying the stale
          * token.
          */
-        queryIter: (orgName: string, repoName: string, opts?: FilterOptions) => AsyncIterableIterator<ThingItem>;
+        queryIter: (orgName: string, repoName: string, opts?: Omit<FilterOptions, "sinceRepoSeq">) => AsyncIterableIterator<ThingItem>;
         /**
          * Materialize every repository record matching the supplied filters.
          *
@@ -4592,9 +4815,20 @@ declare class WarmHubClient {
          * cursor`; restart the query without `cursor` instead of retrying the stale
          * token.
          */
-        queryAll: (orgName: string, repoName: string, opts?: FilterOptions & {
+        queryAll: (orgName: string, repoName: string, opts?: Omit<FilterOptions, "sinceRepoSeq"> & {
             max?: number;
         }) => Promise<ThingItem[]>;
+        /**
+         * 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: (orgName: string, repoName: string, opts: ThingQueryChangesOptions) => Promise<ThingChanges>;
         /**
          * Search repository records with text, vector, or hybrid mode.
          *
@@ -4607,6 +4841,20 @@ declare class WarmHubClient {
          * token.
          */
         search: (orgName: string, repoName: string, query: string, opts?: SearchOptions) => Promise<SearchResult>;
+        /**
+         * Iterate ranked search hits. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        searchIter: (orgName: string, repoName: string, query: string, opts?: SearchOptions) => AsyncIterableIterator<ThingItem>;
+        /**
+         * Materialize ranked search hits. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        searchAll: (orgName: string, repoName: string, query: string, opts?: SearchOptions & {
+            max?: number;
+        }) => Promise<ThingItem[]>;
         /**
          * Count matching repository records without returning record data.
          */
@@ -4912,6 +5160,20 @@ declare class WarmHubClient {
          * token.
          */
         liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
+        /**
+         * Iterate delivery-feed entries. Cursors resume the same query and result
+         * scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query without
+         * `cursor`.
+         */
+        liveFeedIter: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => AsyncIterableIterator<ActionLiveFeedItem>;
+        /**
+         * Materialize delivery-feed entries. Cursors resume the same query and
+         * result scope; on `VALIDATION_ERROR` / `Invalid cursor`, restart the query
+         * without `cursor`.
+         */
+        liveFeedAll: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions & {
+            max?: number;
+        }) => Promise<ActionLiveFeedItem[]>;
         /**
          * List subscription action runs as a `Page<ActionRunInfo>` (`items` +
          * optional `nextCursor`), newest-first, capped at 200 runs per page.
@@ -4919,11 +5181,26 @@ declare 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: (orgName: string, repoName: string, opts?: ActionListRunsOptions) => Promise<Page<ActionRunInfo>>;
+        /**
+         * 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: string, repoName: string, opts?: ActionListRunsOptions) => AsyncIterableIterator<ActionRunInfo>;
+        /**
+         * 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: (orgName: string, repoName: string, opts?: ActionListRunsOptions & {
+            max?: number;
+        }) => Promise<ActionRunInfo[]>;
         /**
          * Return the newest visible action run for each subscription in a repo.
          *
@@ -4964,4 +5241,4 @@ declare class WarmHubClient {
     private watchRepoQuery;
 }
 
-export { type AboutOptions, type AboutResult, type AccessResolveInput, type AccessResolveResult, type AccessTokenProvider, type ActionAttemptInfo, type ActionDeliveryTarget, type ActionLeaseAcquire, type ActionLeaseOp, type ActionListNotificationsOptions, type ActionListRunsOptions, type ActionLiveFeed, type ActionLiveFeedOptions, type ActionNotificationInfo, type ActionRunInfo, type ActionRunStatsInfo, type ActionRunStatsOptions, type AddOp, type AddOperation, AllStreamOperationsFailedError, type Assertion, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, type CliCallSecrets, CliCallVerificationError, type CliCallVerificationFailureReason, type CollectionAddOp, type CollectionAddType, type CollectionContainsOptions, type CollectionContainsResult, type CollectionCreateOptions, type CollectionDiffOptions, type CollectionDiffResult, type CollectionMember, type CollectionMembersOptions, type CollectionMembersPage, type CollectionMembershipRole, type CollectionMutationResult, type CollectionQuerySourceOptions, type CollectionReadDataMode, type CollectionReadSummary, type CollectionReviseOptions, type CollectionStatsOptions, type CollectionStatsResult, type CollectionTag, type CollectionType, type ComponentHistory, type ComponentHistoryOptions, type ComponentInfo, type ComponentInstallResult, type ComponentList, type ComponentListOptions, type ComponentUninstallResult, type ComponentView, type CoreErrorKind, type CountOptions, type CountResult, type CredentialAuditEntry, type CredentialDeleteResult, type CredentialGrantResult, type CredentialInfo, type CredentialKeyMutationResult, type CredentialRevokeResult, type CredentialUngrantResult, type CurrentUserInfo, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, type ErrorKind, type FilterOptions, type FilterResult, type FunctionLogMode, type GlobalSearchOptions, type GlobalSearchResult, type GlobalSearchResultItem, type HeadResult, type HistoryResult, type HomepageFeaturedListsResult, type IndexedFieldEntry, type IndexedFieldsReport, type LiveHandle, type LiveRepoEvent, type LiveSubscriptionLogOptions, type LiveThingHeadOptions, type LiveThingHistoryOptions, type LiveWatchResult, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, type Operation, OperationBuilder, type OperationBuilderAddInput, type OperationBuilderClient, type OperationBuilderOp, type OperationBuilderOptions, type OperationSubmitResult, type OrgAccessResult, type OrgInfo, type OrgList, type OrgListMembersOptions, type OrgListOptions, type OrgMemberInfo, type OrgMemberList, type OrgRef, type OrgRole, type Page, type PageRequest, PartialStreamSubmissionError, type PingResult, type RefLink, type RefsOptions, type RefsResult, type RenameOperation, type RenameResult, type RepoAccessResult, type RepoConfigureStatsView, type RepoDescribeResult, type RepoExploreItem, type RepoExploreOptions, type RepoExploreResult, type RepoInfo, type RepoLicense, type RepoList, type RepoListForCallerOptions, type RepoListOptions, type RepoListPageOptions, type RepoListPageResult, type RepoLocator, type RepoRecentInfo, type RepoRef, type RepoShapeInstanceCountsView, type RepoSort, type RepoStatsBatchResult, type RepoStatsView, type RepoWithStatsInfo, type RequestEvent, type ResolveWrefResult, type RetractOp, type RetractOperation, type RetryPolicyOptions, type ReviseOp, type ReviseOperation, SDK_VERSION, type SearchOptions, type SearchResult, type Shape, type ShapeChange, type ShapeCreateOptions, type ShapeFields, type ShapeGetOptions, type ShapeHistory, type ShapeHistoryOptions, type ShapeList, type ShapeListOptions, type ShapeRef, type ShapeRemove, type ShapeReviseOptions, type ShapeValidatorResult, type StreamAppendInput, type StreamAppendResult, type StreamContinuationState, type SubscriptionBindCredentialsResult, type SubscriptionCompatCreateInput, type SubscriptionCompatUpdateInput, type SubscriptionInfo, type SubscriptionList, type SubscriptionUnbindCredentialsResult, type SynthesizedRepoContent, type ThingDetail, type ThingGet, type ThingGetManyResult, type ThingGetOptions, type ThingGetWithLease, type ThingGraphOptions, type ThingGraphResult, type ThingGraphValue, type ThingHead, type ThingHeadOptions, type ThingHeadRequest, type ThingHeadVersionsResult, type ThingHistory, type ThingHistoryOptions, type ThingItem, type ThingMetadata, type TokenInfo, type TokenResult, type UndeclaredFieldsWarning, type ValidationDiagnostic, type ValidationResult, type VerifiedCliCall, WarmHubClient, type WarmHubClientOptions, WarmHubError, type WarmHubErrorDetails, type WherePredicate, type WhoamiInfo, type WhoamiScopeEntry, type WireScopeEntry, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };
+export { type AboutOptions, type AboutResult, type AccessResolveInput, type AccessResolveResult, type AccessTokenProvider, type ActionAttemptInfo, type ActionDeliveryTarget, type ActionLeaseAcquire, type ActionLeaseOp, type ActionListNotificationsOptions, type ActionListRunsOptions, type ActionLiveFeed, type ActionLiveFeedItem, type ActionLiveFeedOptions, type ActionNotificationInfo, type ActionRunInfo, type ActionRunStatsInfo, type ActionRunStatsOptions, type AddOp, type AddOperation, AllStreamOperationsFailedError, type Assertion, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, type CliCallSecrets, CliCallVerificationError, type CliCallVerificationFailureReason, type CollectionAddOp, type CollectionAddType, type CollectionContainsOptions, type CollectionContainsResult, type CollectionCreateOptions, type CollectionDiffOptions, type CollectionDiffResult, type CollectionMember, type CollectionMembersOptions, type CollectionMembersPage, type CollectionMembershipRole, type CollectionMutationResult, type CollectionQuerySourceOptions, type CollectionReadDataMode, type CollectionReadSummary, type CollectionReviseOptions, type CollectionStatsOptions, type CollectionStatsResult, type CollectionTag, type CollectionType, type ComponentHistory, type ComponentHistoryOptions, type ComponentInfo, type ComponentInstallResult, type ComponentList, type ComponentListOptions, type ComponentUninstallResult, type ComponentView, type CoreErrorKind, type CountOptions, type CountResult, type CredentialAuditEntry, type CredentialDeleteResult, type CredentialGrantResult, type CredentialInfo, type CredentialKeyMutationResult, type CredentialRevokeResult, type CredentialUngrantResult, type CurrentUserInfo, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, type ErrorKind, type FilterOptions, type FilterResult, type FunctionLogMode, type GlobalSearchOptions, type GlobalSearchResult, type GlobalSearchResultItem, type HeadResult, type HistoryResult, type HistoryVersion, type HomepageFeaturedListsResult, type IndexedFieldEntry, type IndexedFieldsReport, type LiveHandle, type LiveRepoEvent, type LiveSubscriptionLogOptions, type LiveThingHeadOptions, type LiveThingHistoryOptions, type LiveWatchResult, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, type Operation, OperationBuilder, type OperationBuilderAddInput, type OperationBuilderClient, type OperationBuilderOp, type OperationBuilderOptions, type OperationSubmitResult, type OrgAccessResult, type OrgInfo, type OrgList, type OrgListMembersOptions, type OrgListOptions, type OrgMemberInfo, type OrgMemberList, type OrgRef, type OrgRole, type Page, type PageRequest, PartialStreamSubmissionError, type PingResult, type RefLink, type RefsOptions, type RefsResult, type RenameOperation, type RenameResult, type RepoAccessResult, type RepoConfigureStatsView, type RepoDescribeResult, type RepoExploreBrowseOptions, type RepoExploreItem, type RepoExploreOptions, type RepoExploreResult, type RepoInfo, type RepoLicense, type RepoList, type RepoListForCallerOptions, type RepoListOptions, type RepoListPageOptions, type RepoListPageResult, type RepoLocator, type RepoRecentInfo, type RepoRef, type RepoShapeInstanceCountsView, type RepoSort, type RepoStatsBatchResult, type RepoStatsView, type RepoWithStatsInfo, type RequestEvent, type ResolveWrefResult, type RetractOp, type RetractOperation, type RetryPolicyOptions, type ReviseOp, type ReviseOperation, SDK_VERSION, type SearchOptions, type SearchResult, type Shape, type ShapeChange, type ShapeCreateOptions, type ShapeFields, type ShapeGetOptions, type ShapeHistory, type ShapeHistoryOptions, type ShapeList, type ShapeListOptions, type ShapeRef, type ShapeRemove, type ShapeReviseOptions, type ShapeValidatorResult, type StreamAppendInput, type StreamAppendResult, type StreamContinuationState, type SubscriptionBindCredentialsResult, type SubscriptionCompatCreateInput, type SubscriptionCompatUpdateInput, type SubscriptionInfo, type SubscriptionList, type SubscriptionUnbindCredentialsResult, type SynthesizedRepoContent, type ThingChanges, type ThingDetail, type ThingGet, type ThingGetManyResult, type ThingGetOptions, type ThingGetWithLease, type ThingGraphOptions, type ThingGraphResult, type ThingGraphValue, type ThingHead, type ThingHeadChangesOptions, type ThingHeadOptions, type ThingHeadRequest, type ThingHeadVersionsResult, type ThingHistory, type ThingHistoryOptions, type ThingItem, type ThingMetadata, type ThingQueryChangesOptions, type TokenInfo, type TokenResult, type UndeclaredFieldsWarning, type ValidationDiagnostic, type ValidationResult, type VerifiedCliCall, WarmHubClient, type WarmHubClientOptions, WarmHubError, type WarmHubErrorDetails, type WherePredicate, type WhoamiInfo, type WhoamiScopeEntry, type WireScopeEntry, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };