@warmhub/sdk-ts 0.83.0 → 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.
      *
@@ -2998,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';

package/dist/index.js

@@ -1,3 +1,3 @@
-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_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall } from './chunk-6AHGGJL6.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_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall } from './chunk-CLDVXOJD.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react.js

@@ -1,5 +1,5 @@
-import { WarmHubClient } from './chunk-6AHGGJL6.js';
-export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-6AHGGJL6.js';
+import { WarmHubClient } from './chunk-CLDVXOJD.js';
+export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-CLDVXOJD.js';
 import { createContext, useMemo, useState, useEffect, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "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.",