hebbrix 2.3.0 → 2.3.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.3.1 — 2026-08-27
+
+- Make single-memory `wait_for_index` a client-enforced readiness contract:
+  submit exactly one write, poll the durable receipt to searchable completion,
+  preserve receipt and idempotency context on timeout or cancellation, and
+  reject terminal indexing states.
+
 ## 2.3.0 — 2026-08-27
 
 - Reconcile every exported advanced method with the canonical public OpenAPI,

package/README.md

@@ -6,7 +6,7 @@ outcome-learning APIs.
 ## Install
 
 ```bash
-npm install hebbrix@2.3.0
+npm install hebbrix@2.3.1
 ```
 
 Node.js 16+ and modern browsers are supported.
@@ -43,6 +43,28 @@ it throws `IndexingTimeoutError`; the error retains the receipt, durable memory
 IDs, and status URL. Reuse the same idempotency key with the same body to recover
 the same logical resources.
 
+Single writes and batch writes use the same one-write readiness rule. The
+client sends exactly one mutation, then uses read-only status requests. Set
+`index_timeout_ms` and `index_poll_interval_ms` on `memories.create()` to tune
+that client-side wait. A signal can cancel the initial request; once a receipt
+is available, cancellation stops only the read-only polling.
+`IndexingAbortedError` then preserves the durable receipt and IDs so
+cancellation cannot be mistaken for a failed write. Terminal `failed`,
+`cancelled`, or `canceled` states raise `IndexingTerminalError` with the same
+receipt context.
+
+```typescript
+const controller = new AbortController();
+const ready = await client.memories.create({
+  content: "Customer prefers concise replies",
+  wait_for_index: true,
+  index_timeout_ms: 30_000,
+  index_poll_interval_ms: 250,
+  signal: controller.signal,
+  idempotency_key: "customer-42-preference-v1",
+});
+```
+
 ```typescript
 const receipt = await client.memories.createBatch({
   memories: [{ content: "First fact" }, { content: "Second fact" }],

package/dist/index.d.mts

@@ -38,6 +38,12 @@ interface Memory {
     source_reference?: string;
     access_count: number;
     last_accessed_at?: string;
+    /** Authoritative indexing state returned by GET /v1/memories/{id}. */
+    processing_status?: string;
+    /** True only when the memory is available to search. */
+    searchable?: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
     created_at: string;
     updated_at: string;
 }
@@ -155,6 +161,12 @@ interface CreateMemoryParams {
     source?: string;
     /** Stable retry key sent as the Idempotency-Key transport header. */
     idempotency_key?: string;
+    /** Optional caller cancellation signal; it is never serialized. */
+    signal?: AbortSignal;
+    /** Client-side readiness deadline used only when wait_for_index=true. */
+    index_timeout_ms?: number;
+    /** Poll interval for a durable pending receipt. */
+    index_poll_interval_ms?: number;
 }
 interface MemoryAddResult {
     id: string;
@@ -162,6 +174,7 @@ interface MemoryAddResult {
     event: "ADD" | "UPDATE" | "NOOP" | string;
     memory?: string;
     reason?: string;
+    processing_status?: string;
 }
 interface MemoryAddResponse {
     results: MemoryAddResult[];
@@ -170,6 +183,9 @@ interface MemoryAddResponse {
     searchable: boolean;
     outbox_event_id?: string;
     status_url?: string;
+    idempotency_replay?: boolean;
+    request_id?: string;
+    retry_after?: string;
     job_id?: string;
     created_count: number;
     updated_count: number;
@@ -370,9 +386,23 @@ declare class CollectionsResource extends BaseResource {
 }
 declare class MemoriesResource extends BaseResource {
     /**
-     * Create a new memory
+     * Create one logical memory write. When `wait_for_index=true`, a durable
+     * pending receipt is polled without issuing a second create request.
      */
     create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
+    /** Poll a single-write durable receipt until every accepted memory is searchable. */
+    waitForSearchable(receipt: MemoryAddResponse, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+        idempotencyKey?: string;
+    }): Promise<MemoryAddResponse>;
+    private memoryIds;
+    private isSearchableCompletion;
+    private isTerminalStatus;
+    private readinessPath;
+    private throwIfPollingAborted;
+    private pollingDelay;
     /**
      * Create up to 100 memories with one unambiguous readiness contract.
      * `wait_for_index=true` resolves only for a fully searchable batch. A durable
@@ -689,11 +719,36 @@ declare class EntitlementError extends HebbrixError {
         details?: Record<string, any>;
     });
 }
-declare class IndexingTimeoutError extends Error {
+interface IndexingWaitErrorOptions {
+    idempotencyKey?: string;
+    cause?: unknown;
+}
+/** Base class for readiness failures after the API has accepted a durable write. */
+declare class IndexingWaitError extends Error {
     receipt: Record<string, any>;
     memoryIds: string[];
+    jobId?: string;
     statusUrl?: string;
-    constructor(message: string, receipt: Record<string, any>);
+    requestId?: string;
+    outboxEventId?: string;
+    indexingEventId?: string;
+    eventId?: string;
+    idempotencyReplay?: boolean;
+    idempotencyKey?: string;
+    retryAfter?: string;
+    recovery: Record<string, unknown>;
+    cause?: unknown;
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTimeoutError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingAbortedError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTerminalError extends IndexingWaitError {
+    processingStatus: string;
+    constructor(message: string, receipt: Record<string, any>, processingStatus: string, options?: IndexingWaitErrorOptions);
 }
 declare class AuthenticationError extends HebbrixError {
     constructor(message?: string, options?: {
@@ -752,4 +807,4 @@ interface SafetyEnvelope {
  */
 declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, EntitlementError, type EvidenceClaim, type GroundingReceipt, HebbrixError, IndexingTimeoutError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, enforceSearchSafety };
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, EntitlementError, type EvidenceClaim, type GroundingReceipt, HebbrixError, IndexingAbortedError, IndexingTerminalError, IndexingTimeoutError, IndexingWaitError, type IndexingWaitErrorOptions, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, enforceSearchSafety };

package/dist/index.d.ts

@@ -38,6 +38,12 @@ interface Memory {
     source_reference?: string;
     access_count: number;
     last_accessed_at?: string;
+    /** Authoritative indexing state returned by GET /v1/memories/{id}. */
+    processing_status?: string;
+    /** True only when the memory is available to search. */
+    searchable?: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
     created_at: string;
     updated_at: string;
 }
@@ -155,6 +161,12 @@ interface CreateMemoryParams {
     source?: string;
     /** Stable retry key sent as the Idempotency-Key transport header. */
     idempotency_key?: string;
+    /** Optional caller cancellation signal; it is never serialized. */
+    signal?: AbortSignal;
+    /** Client-side readiness deadline used only when wait_for_index=true. */
+    index_timeout_ms?: number;
+    /** Poll interval for a durable pending receipt. */
+    index_poll_interval_ms?: number;
 }
 interface MemoryAddResult {
     id: string;
@@ -162,6 +174,7 @@ interface MemoryAddResult {
     event: "ADD" | "UPDATE" | "NOOP" | string;
     memory?: string;
     reason?: string;
+    processing_status?: string;
 }
 interface MemoryAddResponse {
     results: MemoryAddResult[];
@@ -170,6 +183,9 @@ interface MemoryAddResponse {
     searchable: boolean;
     outbox_event_id?: string;
     status_url?: string;
+    idempotency_replay?: boolean;
+    request_id?: string;
+    retry_after?: string;
     job_id?: string;
     created_count: number;
     updated_count: number;
@@ -370,9 +386,23 @@ declare class CollectionsResource extends BaseResource {
 }
 declare class MemoriesResource extends BaseResource {
     /**
-     * Create a new memory
+     * Create one logical memory write. When `wait_for_index=true`, a durable
+     * pending receipt is polled without issuing a second create request.
      */
     create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
+    /** Poll a single-write durable receipt until every accepted memory is searchable. */
+    waitForSearchable(receipt: MemoryAddResponse, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+        idempotencyKey?: string;
+    }): Promise<MemoryAddResponse>;
+    private memoryIds;
+    private isSearchableCompletion;
+    private isTerminalStatus;
+    private readinessPath;
+    private throwIfPollingAborted;
+    private pollingDelay;
     /**
      * Create up to 100 memories with one unambiguous readiness contract.
      * `wait_for_index=true` resolves only for a fully searchable batch. A durable
@@ -689,11 +719,36 @@ declare class EntitlementError extends HebbrixError {
         details?: Record<string, any>;
     });
 }
-declare class IndexingTimeoutError extends Error {
+interface IndexingWaitErrorOptions {
+    idempotencyKey?: string;
+    cause?: unknown;
+}
+/** Base class for readiness failures after the API has accepted a durable write. */
+declare class IndexingWaitError extends Error {
     receipt: Record<string, any>;
     memoryIds: string[];
+    jobId?: string;
     statusUrl?: string;
-    constructor(message: string, receipt: Record<string, any>);
+    requestId?: string;
+    outboxEventId?: string;
+    indexingEventId?: string;
+    eventId?: string;
+    idempotencyReplay?: boolean;
+    idempotencyKey?: string;
+    retryAfter?: string;
+    recovery: Record<string, unknown>;
+    cause?: unknown;
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTimeoutError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingAbortedError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTerminalError extends IndexingWaitError {
+    processingStatus: string;
+    constructor(message: string, receipt: Record<string, any>, processingStatus: string, options?: IndexingWaitErrorOptions);
 }
 declare class AuthenticationError extends HebbrixError {
     constructor(message?: string, options?: {
@@ -752,4 +807,4 @@ interface SafetyEnvelope {
  */
 declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, EntitlementError, type EvidenceClaim, type GroundingReceipt, HebbrixError, IndexingTimeoutError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, enforceSearchSafety };
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, EntitlementError, type EvidenceClaim, type GroundingReceipt, HebbrixError, IndexingAbortedError, IndexingTerminalError, IndexingTimeoutError, IndexingWaitError, type IndexingWaitErrorOptions, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, enforceSearchSafety };

package/dist/index.js

@@ -27,7 +27,10 @@ __export(index_exports, {
   CorrectionsResource: () => CorrectionsResource,
   EntitlementError: () => EntitlementError,
   HebbrixError: () => HebbrixError,
+  IndexingAbortedError: () => IndexingAbortedError,
+  IndexingTerminalError: () => IndexingTerminalError,
   IndexingTimeoutError: () => IndexingTimeoutError,
+  IndexingWaitError: () => IndexingWaitError,
   MemoriesResource: () => MemoriesResource,
   MemoryClient: () => MemoryClient,
   MemoryJobsResource: () => MemoryJobsResource,
@@ -119,16 +122,72 @@ var EntitlementError = class _EntitlementError extends HebbrixError {
     Object.setPrototypeOf(this, _EntitlementError.prototype);
   }
 };
-var IndexingTimeoutError = class _IndexingTimeoutError extends Error {
-  constructor(message, receipt) {
+var IndexingWaitError = class _IndexingWaitError extends Error {
+  constructor(message, receipt, options = {}) {
     super(message);
-    this.name = "IndexingTimeoutError";
+    this.name = "IndexingWaitError";
     this.receipt = { ...receipt };
-    this.memoryIds = [...receipt.memory_ids || []];
-    this.statusUrl = receipt.status_url;
+    this.memoryIds = [
+      ...new Set(
+        [
+          ...receipt.memory_ids || [],
+          receipt.memory_id,
+          receipt.id,
+          ...(receipt.results || []).map(
+            (row) => row.memory_id || row.id
+          )
+        ].filter(Boolean)
+      )
+    ];
+    this.jobId = receipt.job_id;
+    this.statusUrl = receipt.status_url || (this.memoryIds.length === 1 ? `/v1/memories/${encodeURIComponent(this.memoryIds[0])}` : this.jobId ? `/v1/memory-jobs/${encodeURIComponent(this.jobId)}` : void 0);
+    this.requestId = receipt.request_id;
+    this.outboxEventId = receipt.outbox_event_id;
+    this.indexingEventId = receipt.indexing_event_id || this.outboxEventId;
+    this.eventId = receipt.event_id || this.indexingEventId;
+    this.idempotencyReplay = receipt.idempotency_replay;
+    this.idempotencyKey = options.idempotencyKey || receipt.idempotency_key;
+    this.retryAfter = receipt.retry_after;
+    this.recovery = Object.fromEntries(
+      Object.entries({
+        memory_ids: this.memoryIds,
+        job_id: this.jobId,
+        status_url: this.statusUrl,
+        request_id: this.requestId,
+        outbox_event_id: this.outboxEventId,
+        indexing_event_id: this.indexingEventId,
+        event_id: this.eventId,
+        idempotency_key: this.idempotencyKey,
+        idempotency_replay: this.idempotencyReplay,
+        retry_after: this.retryAfter
+      }).filter(([, value]) => value !== void 0 && value !== null)
+    );
+    this.cause = options.cause;
+    Object.setPrototypeOf(this, _IndexingWaitError.prototype);
+  }
+};
+var IndexingTimeoutError = class _IndexingTimeoutError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTimeoutError";
     Object.setPrototypeOf(this, _IndexingTimeoutError.prototype);
   }
 };
+var IndexingAbortedError = class _IndexingAbortedError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingAbortedError";
+    Object.setPrototypeOf(this, _IndexingAbortedError.prototype);
+  }
+};
+var IndexingTerminalError = class _IndexingTerminalError extends IndexingWaitError {
+  constructor(message, receipt, processingStatus, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTerminalError";
+    this.processingStatus = processingStatus;
+    Object.setPrototypeOf(this, _IndexingTerminalError.prototype);
+  }
+};
 var AuthenticationError = class _AuthenticationError extends HebbrixError {
   constructor(message = "Authentication failed", options = {}) {
     super(message, 401, options);
@@ -242,22 +301,195 @@ var CollectionsResource = class extends BaseResource {
 };
 var MemoriesResource = class extends BaseResource {
   /**
-   * Create a new memory
+   * Create one logical memory write. When `wait_for_index=true`, a durable
+   * pending receipt is polled without issuing a second create request.
    */
   async create(params) {
     if (!params.content?.trim() && !params.messages?.length) {
       throw new TypeError("content or messages must be provided");
     }
-    const { idempotency_key, ...input } = params;
-    return this.client.request("POST", "/v1/memories", {
-      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
-      body: JSON.stringify({
-        source_type: "text",
-        metadata: {},
-        infer: false,
-        wait_for_index: false,
-        ...input
-      })
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...input
+    } = params;
+    const receipt = await this.client.request(
+      "POST",
+      "/v1/memories",
+      {
+        headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+        body: JSON.stringify({
+          source_type: "text",
+          metadata: {},
+          infer: false,
+          wait_for_index: false,
+          ...input
+        }),
+        signal
+      }
+    );
+    if (params.wait_for_index && !this.isSearchableCompletion(receipt)) {
+      return this.waitForSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal,
+        idempotencyKey: idempotency_key
+      });
+    }
+    return receipt;
+  }
+  /** Poll a single-write durable receipt until every accepted memory is searchable. */
+  async waitForSearchable(receipt, options = {}) {
+    if (this.isSearchableCompletion(receipt)) {
+      return receipt;
+    }
+    if (this.isTerminalStatus(receipt.processing_status)) {
+      const status = String(receipt.processing_status).toLowerCase();
+      throw new IndexingTerminalError(
+        `memory indexing reached terminal state ${status}`,
+        receipt,
+        status,
+        { idempotencyKey: options.idempotencyKey }
+      );
+    }
+    const ids = this.memoryIds(receipt);
+    if (!ids.length) {
+      throw new Error("memory receipt does not contain a durable memory id");
+    }
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    const paths = ids.map(
+      (id, index) => index === 0 && receipt.status_url ? this.readinessPath(receipt.status_url, id) : `/v1/memories/${encodeURIComponent(id)}`
+    );
+    while (true) {
+      this.throwIfPollingAborted(receipt, options);
+      if (Date.now() >= deadline) {
+        throw new IndexingTimeoutError(
+          `memory was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      let rows;
+      try {
+        rows = await Promise.all(
+          paths.map(
+            (path) => this.client.request("GET", path, {
+              signal: options.signal
+            })
+          )
+        );
+      } catch (error) {
+        if (options.signal?.aborted) {
+          throw new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            { idempotencyKey: options.idempotencyKey, cause: error }
+          );
+        }
+        throw error;
+      }
+      const terminal = rows.find(
+        (row) => this.isTerminalStatus(row.processing_status)
+      );
+      if (terminal) {
+        const status = String(terminal.processing_status).toLowerCase();
+        throw new IndexingTerminalError(
+          `memory ${terminal.id} indexing reached terminal state ${status}`,
+          receipt,
+          status,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      if (rows.every(
+        (row) => row.searchable === true && String(row.processing_status || "").toLowerCase() === "completed"
+      )) {
+        return {
+          ...receipt,
+          processing_status: "completed",
+          searchable: true,
+          results: receipt.results.map((result) => ({
+            ...result,
+            processing_status: "completed"
+          }))
+        };
+      }
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        continue;
+      }
+      await this.pollingDelay(
+        Math.min(pollIntervalMs, remainingMs),
+        receipt,
+        options
+      );
+    }
+  }
+  memoryIds(receipt) {
+    return [
+      ...new Set(
+        (receipt.results || []).map((row) => row.memory_id || row.id).filter((id) => Boolean(id))
+      )
+    ];
+  }
+  isSearchableCompletion(receipt) {
+    return receipt.searchable === true && String(receipt.processing_status || "").toLowerCase() === "completed";
+  }
+  isTerminalStatus(status) {
+    return ["failed", "cancelled", "canceled"].includes(
+      String(status || "").toLowerCase()
+    );
+  }
+  readinessPath(statusUrl, memoryId) {
+    try {
+      const parsed = new URL(statusUrl, "https://status.hebbrix.invalid");
+      if (!["http:", "https:"].includes(parsed.protocol)) {
+        return `/v1/memories/${encodeURIComponent(memoryId)}`;
+      }
+      return `${parsed.pathname}${parsed.search}`;
+    } catch {
+      return `/v1/memories/${encodeURIComponent(memoryId)}`;
+    }
+  }
+  throwIfPollingAborted(receipt, options) {
+    if (options.signal?.aborted) {
+      throw new IndexingAbortedError(
+        "memory readiness polling was aborted after the write became durable",
+        receipt,
+        {
+          idempotencyKey: options.idempotencyKey,
+          cause: options.signal.reason
+        }
+      );
+    }
+  }
+  async pollingDelay(delayMs, receipt, options) {
+    await new Promise((resolve, reject) => {
+      const onAbort = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        reject(
+          new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            {
+              idempotencyKey: options.idempotencyKey,
+              cause: options.signal?.reason
+            }
+          )
+        );
+      };
+      const timer = setTimeout(() => {
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, delayMs);
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) {
+        onAbort();
+      }
     });
   }
   /**
@@ -608,9 +840,12 @@ var ProceduralResource = class extends BaseResource {
    * Execute a procedure
    */
   async execute(procedureId, context) {
-    const response = await this.client.post(`/v1/procedures/${procedureId}/execute`, {
-      input_state: context || {}
-    });
+    const response = await this.client.post(
+      `/v1/procedures/${procedureId}/execute`,
+      {
+        input_state: context || {}
+      }
+    );
     return response?.execution_result || response;
   }
   /**
@@ -627,7 +862,10 @@ var ProceduralResource = class extends BaseResource {
       body.action = { steps: params.action_sequence };
     }
     if (params.metadata !== void 0) body.parameters = params.metadata;
-    const response = await this.client.patch(`/v1/procedures/${procedureId}`, body);
+    const response = await this.client.patch(
+      `/v1/procedures/${procedureId}`,
+      body
+    );
     return this.unwrapProcedure(response);
   }
   /**
@@ -710,7 +948,9 @@ var TemporalResource = class extends BaseResource {
    */
   async pointInTime(timestamp, entity) {
     if (!entity) {
-      throw new TypeError("entity is required and maps to the canonical subject");
+      throw new TypeError(
+        "entity is required and maps to the canonical subject"
+      );
     }
     return this.queryAtTime({
       timestamp,
@@ -794,7 +1034,8 @@ var MemoryToolsResource = class extends BaseResource {
    */
   async insert(params) {
     const metadata = { ...params.metadata || {} };
-    if (params.position !== void 0) metadata.requested_position = params.position;
+    if (params.position !== void 0)
+      metadata.requested_position = params.position;
     if (params.reason !== void 0) metadata.reason = params.reason;
     return this.client.post("/v1/memory-tools/insert", {
       collection_id: params.collection_id,
@@ -838,7 +1079,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.0"
+      "User-Agent": "hebbrix-typescript/2.3.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -864,7 +1105,9 @@ var MemoryClient = class {
       throw new RateLimitError(message, { code, requestId, details });
     } else if (statusCode >= 500) {
       throw new ServerError(message, { code, requestId, details });
-    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(details?.error))) {
+    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(
+      details?.error
+    ))) {
       throw new EntitlementError(message, statusCode, {
         code,
         requestId,
@@ -876,7 +1119,11 @@ var MemoryClient = class {
   }
   async request(method, path, options = {}) {
     const url = `${this.baseUrl}${path}`;
-    const { headers: requestHeaders, signal: requestSignal, ...requestOptions } = options;
+    const {
+      headers: requestHeaders,
+      signal: requestSignal,
+      ...requestOptions
+    } = options;
     const response = await fetch(url, {
       ...requestOptions,
       method,
@@ -903,6 +1150,21 @@ var MemoryClient = class {
     if (!response.ok) {
       this.handleError(response, data);
     }
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const requestId = response.headers.get("X-Request-ID");
+      const statusUrl = response.headers.get("Location");
+      const outboxEventId = response.headers.get("X-Hebbrix-Index-Event");
+      const retryAfter = response.headers.get("Retry-After");
+      const idempotencyReplay = response.headers.get("X-Idempotent-Replay");
+      data = {
+        ...data,
+        ...data.request_id === void 0 && requestId ? { request_id: requestId } : {},
+        ...data.status_url === void 0 && statusUrl ? { status_url: statusUrl } : {},
+        ...data.outbox_event_id === void 0 && outboxEventId ? { outbox_event_id: outboxEventId } : {},
+        ...data.retry_after === void 0 && retryAfter ? { retry_after: retryAfter } : {},
+        ...data.idempotency_replay === void 0 && idempotencyReplay ? { idempotency_replay: idempotencyReplay.toLowerCase() === "true" } : {}
+      };
+    }
     return data;
   }
   async get(path, params) {
@@ -955,7 +1217,10 @@ var MemoryClient = class {
   CorrectionsResource,
   EntitlementError,
   HebbrixError,
+  IndexingAbortedError,
+  IndexingTerminalError,
   IndexingTimeoutError,
+  IndexingWaitError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,

package/dist/index.mjs

@@ -71,16 +71,72 @@ var EntitlementError = class _EntitlementError extends HebbrixError {
     Object.setPrototypeOf(this, _EntitlementError.prototype);
   }
 };
-var IndexingTimeoutError = class _IndexingTimeoutError extends Error {
-  constructor(message, receipt) {
+var IndexingWaitError = class _IndexingWaitError extends Error {
+  constructor(message, receipt, options = {}) {
     super(message);
-    this.name = "IndexingTimeoutError";
+    this.name = "IndexingWaitError";
     this.receipt = { ...receipt };
-    this.memoryIds = [...receipt.memory_ids || []];
-    this.statusUrl = receipt.status_url;
+    this.memoryIds = [
+      ...new Set(
+        [
+          ...receipt.memory_ids || [],
+          receipt.memory_id,
+          receipt.id,
+          ...(receipt.results || []).map(
+            (row) => row.memory_id || row.id
+          )
+        ].filter(Boolean)
+      )
+    ];
+    this.jobId = receipt.job_id;
+    this.statusUrl = receipt.status_url || (this.memoryIds.length === 1 ? `/v1/memories/${encodeURIComponent(this.memoryIds[0])}` : this.jobId ? `/v1/memory-jobs/${encodeURIComponent(this.jobId)}` : void 0);
+    this.requestId = receipt.request_id;
+    this.outboxEventId = receipt.outbox_event_id;
+    this.indexingEventId = receipt.indexing_event_id || this.outboxEventId;
+    this.eventId = receipt.event_id || this.indexingEventId;
+    this.idempotencyReplay = receipt.idempotency_replay;
+    this.idempotencyKey = options.idempotencyKey || receipt.idempotency_key;
+    this.retryAfter = receipt.retry_after;
+    this.recovery = Object.fromEntries(
+      Object.entries({
+        memory_ids: this.memoryIds,
+        job_id: this.jobId,
+        status_url: this.statusUrl,
+        request_id: this.requestId,
+        outbox_event_id: this.outboxEventId,
+        indexing_event_id: this.indexingEventId,
+        event_id: this.eventId,
+        idempotency_key: this.idempotencyKey,
+        idempotency_replay: this.idempotencyReplay,
+        retry_after: this.retryAfter
+      }).filter(([, value]) => value !== void 0 && value !== null)
+    );
+    this.cause = options.cause;
+    Object.setPrototypeOf(this, _IndexingWaitError.prototype);
+  }
+};
+var IndexingTimeoutError = class _IndexingTimeoutError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTimeoutError";
     Object.setPrototypeOf(this, _IndexingTimeoutError.prototype);
   }
 };
+var IndexingAbortedError = class _IndexingAbortedError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingAbortedError";
+    Object.setPrototypeOf(this, _IndexingAbortedError.prototype);
+  }
+};
+var IndexingTerminalError = class _IndexingTerminalError extends IndexingWaitError {
+  constructor(message, receipt, processingStatus, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTerminalError";
+    this.processingStatus = processingStatus;
+    Object.setPrototypeOf(this, _IndexingTerminalError.prototype);
+  }
+};
 var AuthenticationError = class _AuthenticationError extends HebbrixError {
   constructor(message = "Authentication failed", options = {}) {
     super(message, 401, options);
@@ -194,22 +250,195 @@ var CollectionsResource = class extends BaseResource {
 };
 var MemoriesResource = class extends BaseResource {
   /**
-   * Create a new memory
+   * Create one logical memory write. When `wait_for_index=true`, a durable
+   * pending receipt is polled without issuing a second create request.
    */
   async create(params) {
     if (!params.content?.trim() && !params.messages?.length) {
       throw new TypeError("content or messages must be provided");
     }
-    const { idempotency_key, ...input } = params;
-    return this.client.request("POST", "/v1/memories", {
-      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
-      body: JSON.stringify({
-        source_type: "text",
-        metadata: {},
-        infer: false,
-        wait_for_index: false,
-        ...input
-      })
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...input
+    } = params;
+    const receipt = await this.client.request(
+      "POST",
+      "/v1/memories",
+      {
+        headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+        body: JSON.stringify({
+          source_type: "text",
+          metadata: {},
+          infer: false,
+          wait_for_index: false,
+          ...input
+        }),
+        signal
+      }
+    );
+    if (params.wait_for_index && !this.isSearchableCompletion(receipt)) {
+      return this.waitForSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal,
+        idempotencyKey: idempotency_key
+      });
+    }
+    return receipt;
+  }
+  /** Poll a single-write durable receipt until every accepted memory is searchable. */
+  async waitForSearchable(receipt, options = {}) {
+    if (this.isSearchableCompletion(receipt)) {
+      return receipt;
+    }
+    if (this.isTerminalStatus(receipt.processing_status)) {
+      const status = String(receipt.processing_status).toLowerCase();
+      throw new IndexingTerminalError(
+        `memory indexing reached terminal state ${status}`,
+        receipt,
+        status,
+        { idempotencyKey: options.idempotencyKey }
+      );
+    }
+    const ids = this.memoryIds(receipt);
+    if (!ids.length) {
+      throw new Error("memory receipt does not contain a durable memory id");
+    }
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    const paths = ids.map(
+      (id, index) => index === 0 && receipt.status_url ? this.readinessPath(receipt.status_url, id) : `/v1/memories/${encodeURIComponent(id)}`
+    );
+    while (true) {
+      this.throwIfPollingAborted(receipt, options);
+      if (Date.now() >= deadline) {
+        throw new IndexingTimeoutError(
+          `memory was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      let rows;
+      try {
+        rows = await Promise.all(
+          paths.map(
+            (path) => this.client.request("GET", path, {
+              signal: options.signal
+            })
+          )
+        );
+      } catch (error) {
+        if (options.signal?.aborted) {
+          throw new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            { idempotencyKey: options.idempotencyKey, cause: error }
+          );
+        }
+        throw error;
+      }
+      const terminal = rows.find(
+        (row) => this.isTerminalStatus(row.processing_status)
+      );
+      if (terminal) {
+        const status = String(terminal.processing_status).toLowerCase();
+        throw new IndexingTerminalError(
+          `memory ${terminal.id} indexing reached terminal state ${status}`,
+          receipt,
+          status,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      if (rows.every(
+        (row) => row.searchable === true && String(row.processing_status || "").toLowerCase() === "completed"
+      )) {
+        return {
+          ...receipt,
+          processing_status: "completed",
+          searchable: true,
+          results: receipt.results.map((result) => ({
+            ...result,
+            processing_status: "completed"
+          }))
+        };
+      }
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        continue;
+      }
+      await this.pollingDelay(
+        Math.min(pollIntervalMs, remainingMs),
+        receipt,
+        options
+      );
+    }
+  }
+  memoryIds(receipt) {
+    return [
+      ...new Set(
+        (receipt.results || []).map((row) => row.memory_id || row.id).filter((id) => Boolean(id))
+      )
+    ];
+  }
+  isSearchableCompletion(receipt) {
+    return receipt.searchable === true && String(receipt.processing_status || "").toLowerCase() === "completed";
+  }
+  isTerminalStatus(status) {
+    return ["failed", "cancelled", "canceled"].includes(
+      String(status || "").toLowerCase()
+    );
+  }
+  readinessPath(statusUrl, memoryId) {
+    try {
+      const parsed = new URL(statusUrl, "https://status.hebbrix.invalid");
+      if (!["http:", "https:"].includes(parsed.protocol)) {
+        return `/v1/memories/${encodeURIComponent(memoryId)}`;
+      }
+      return `${parsed.pathname}${parsed.search}`;
+    } catch {
+      return `/v1/memories/${encodeURIComponent(memoryId)}`;
+    }
+  }
+  throwIfPollingAborted(receipt, options) {
+    if (options.signal?.aborted) {
+      throw new IndexingAbortedError(
+        "memory readiness polling was aborted after the write became durable",
+        receipt,
+        {
+          idempotencyKey: options.idempotencyKey,
+          cause: options.signal.reason
+        }
+      );
+    }
+  }
+  async pollingDelay(delayMs, receipt, options) {
+    await new Promise((resolve, reject) => {
+      const onAbort = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        reject(
+          new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            {
+              idempotencyKey: options.idempotencyKey,
+              cause: options.signal?.reason
+            }
+          )
+        );
+      };
+      const timer = setTimeout(() => {
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, delayMs);
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) {
+        onAbort();
+      }
     });
   }
   /**
@@ -560,9 +789,12 @@ var ProceduralResource = class extends BaseResource {
    * Execute a procedure
    */
   async execute(procedureId, context) {
-    const response = await this.client.post(`/v1/procedures/${procedureId}/execute`, {
-      input_state: context || {}
-    });
+    const response = await this.client.post(
+      `/v1/procedures/${procedureId}/execute`,
+      {
+        input_state: context || {}
+      }
+    );
     return response?.execution_result || response;
   }
   /**
@@ -579,7 +811,10 @@ var ProceduralResource = class extends BaseResource {
       body.action = { steps: params.action_sequence };
     }
     if (params.metadata !== void 0) body.parameters = params.metadata;
-    const response = await this.client.patch(`/v1/procedures/${procedureId}`, body);
+    const response = await this.client.patch(
+      `/v1/procedures/${procedureId}`,
+      body
+    );
     return this.unwrapProcedure(response);
   }
   /**
@@ -662,7 +897,9 @@ var TemporalResource = class extends BaseResource {
    */
   async pointInTime(timestamp, entity) {
     if (!entity) {
-      throw new TypeError("entity is required and maps to the canonical subject");
+      throw new TypeError(
+        "entity is required and maps to the canonical subject"
+      );
     }
     return this.queryAtTime({
       timestamp,
@@ -746,7 +983,8 @@ var MemoryToolsResource = class extends BaseResource {
    */
   async insert(params) {
     const metadata = { ...params.metadata || {} };
-    if (params.position !== void 0) metadata.requested_position = params.position;
+    if (params.position !== void 0)
+      metadata.requested_position = params.position;
     if (params.reason !== void 0) metadata.reason = params.reason;
     return this.client.post("/v1/memory-tools/insert", {
       collection_id: params.collection_id,
@@ -790,7 +1028,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.0"
+      "User-Agent": "hebbrix-typescript/2.3.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -816,7 +1054,9 @@ var MemoryClient = class {
       throw new RateLimitError(message, { code, requestId, details });
     } else if (statusCode >= 500) {
       throw new ServerError(message, { code, requestId, details });
-    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(details?.error))) {
+    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(
+      details?.error
+    ))) {
       throw new EntitlementError(message, statusCode, {
         code,
         requestId,
@@ -828,7 +1068,11 @@ var MemoryClient = class {
   }
   async request(method, path, options = {}) {
     const url = `${this.baseUrl}${path}`;
-    const { headers: requestHeaders, signal: requestSignal, ...requestOptions } = options;
+    const {
+      headers: requestHeaders,
+      signal: requestSignal,
+      ...requestOptions
+    } = options;
     const response = await fetch(url, {
       ...requestOptions,
       method,
@@ -855,6 +1099,21 @@ var MemoryClient = class {
     if (!response.ok) {
       this.handleError(response, data);
     }
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const requestId = response.headers.get("X-Request-ID");
+      const statusUrl = response.headers.get("Location");
+      const outboxEventId = response.headers.get("X-Hebbrix-Index-Event");
+      const retryAfter = response.headers.get("Retry-After");
+      const idempotencyReplay = response.headers.get("X-Idempotent-Replay");
+      data = {
+        ...data,
+        ...data.request_id === void 0 && requestId ? { request_id: requestId } : {},
+        ...data.status_url === void 0 && statusUrl ? { status_url: statusUrl } : {},
+        ...data.outbox_event_id === void 0 && outboxEventId ? { outbox_event_id: outboxEventId } : {},
+        ...data.retry_after === void 0 && retryAfter ? { retry_after: retryAfter } : {},
+        ...data.idempotency_replay === void 0 && idempotencyReplay ? { idempotency_replay: idempotencyReplay.toLowerCase() === "true" } : {}
+      };
+    }
     return data;
   }
   async get(path, params) {
@@ -906,7 +1165,10 @@ export {
   CorrectionsResource,
   EntitlementError,
   HebbrixError,
+  IndexingAbortedError,
+  IndexingTerminalError,
   IndexingTimeoutError,
+  IndexingWaitError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hebbrix",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Typed TypeScript client for Hebbrix memory, retrieval, and outcome-learning APIs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -46,10 +46,14 @@
   ],
   "author": "Hebbrix Team <support@hebbrix.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebbrix/hebbrix-typescript.git"
+  },
   "bugs": {
-    "url": "https://www.hebbrix.com/contact"
+    "url": "https://github.com/Hebbrix/hebbrix-typescript/issues"
   },
-  "homepage": "https://hebbrix.com",
+  "homepage": "https://docs.hebbrix.com",
   "publishConfig": {
     "access": "public"
   },