hebbrix 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.4.0 — 2026-09-07
+
+- Add typed Evidence Loop methods for owner-managed verifiers, durable episodes, actual-execution claims, protected outcome delivery and evidence assessments.
+- Preserve incomplete outcomes, scope, replay and permission receipts. Verifier errors never fall back to caller-reported outcomes.
+- Reject malformed, ambiguous or unknown evidence contracts before exposing unsupported synthesis; retain valid degraded evidence with its abstention signal.
+- Protected ledger methods require the connected Evidence Loop backend, separately scoped verifier credentials and external execution/outcome checks. They do not grant permission or execute actions.
+
+## 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.4.0
 ```
 
 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;
 }
@@ -95,12 +101,48 @@ interface ProofLoopCandidate {
 }
 interface ProofLoopDecisionParams {
     policy_key: string;
+    episode_id?: string;
     candidates: ProofLoopCandidate[];
     proof_context?: ProofContext | string;
     collection_id?: string;
     user_id?: string;
     [key: string]: any;
 }
+interface EvidenceScope {
+    policy_key: string;
+    collection_id?: string;
+    user_id?: string;
+}
+interface VerifierRegistration extends EvidenceScope {
+    api_key_id: string;
+    source_system: string;
+    metric_keys: string[];
+}
+interface EpisodeCreateParams extends EvidenceScope {
+    verifier_id: string;
+    idempotency_key: string;
+}
+interface ExecutionClaim {
+    attempt_id: string;
+    status: "started" | "completed" | "failed" | "interrupted" | "blocked";
+    actual_action_key: string;
+    arguments_digest: string;
+    evidence_digest?: string;
+    occurred_at?: string;
+}
+interface VerifiedOutcomeDelivery {
+    decision_id: string;
+    source_event_id: string;
+    evidence_digest: string;
+    execution_digest: string;
+    observations: Array<{
+        metric_key: string;
+        value: number;
+        confidence?: number;
+        is_final?: boolean;
+        observed_at: string;
+    }>;
+}
 interface ReasoningSource {
     memory_id: string;
     content: string;
@@ -155,6 +197,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 +210,7 @@ interface MemoryAddResult {
     event: "ADD" | "UPDATE" | "NOOP" | string;
     memory?: string;
     reason?: string;
+    processing_status?: string;
 }
 interface MemoryAddResponse {
     results: MemoryAddResult[];
@@ -170,6 +219,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 +422,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
@@ -435,7 +501,7 @@ declare class SearchResource extends BaseResource {
     reason(params: ReasonParams): Promise<ReasoningResponse>;
 }
 declare class ProofLoopResource extends BaseResource {
-    /** Create a causal decision bound to search/chat evidence automatically. */
+    /** Record a recommendation; this never authorizes execution or proves causality. */
     decide(params: ProofLoopDecisionParams): Promise<Record<string, any>>;
     recordOutcome(decisionId: string, body: {
         observations?: Record<string, any>[];
@@ -444,6 +510,18 @@ declare class ProofLoopResource extends BaseResource {
         idempotency_key?: string;
     }): Promise<Record<string, any>>;
     getDecision(decisionId: string): Promise<Record<string, any>>;
+    /** Owner-session administration. Use a separate client for the verifier key. */
+    registerVerifier(params: VerifierRegistration): Promise<Record<string, any>>;
+    revokeVerifier(verifierId: string): Promise<Record<string, any>>;
+    createEpisode(params: EpisodeCreateParams): Promise<Record<string, any>>;
+    getEpisode(episodeId: string, offset?: number): Promise<Record<string, any>>;
+    closeEpisode(episodeId: string, status: "completed" | "interrupted"): Promise<Record<string, any>>;
+    /** Append an execution claim. This method does not execute a tool. */
+    recordExecution(decisionId: string, claim: ExecutionClaim): Promise<Record<string, any>>;
+    assessment(decisionId: string, evidenceOffset?: number): Promise<Record<string, any>>;
+    verifierEvidence(verifierId: string, decisionId: string): Promise<Record<string, any>>;
+    /** Deliver using the dedicated source credential, after checking execution independently. */
+    deliverVerifiedOutcomes(verifierId: string, delivery: VerifiedOutcomeDelivery): Promise<Record<string, any>>;
     defineMetric(params: ProofLoopMetricParams): Promise<Record<string, any>>;
     listMetrics(params?: {
         policy_key?: string;
@@ -689,11 +767,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 +855,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 EpisodeCreateParams, type EvidenceClaim, type EvidenceScope, type ExecutionClaim, 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, type VerifiedOutcomeDelivery, type VerifierRegistration, 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;
 }
@@ -95,12 +101,48 @@ interface ProofLoopCandidate {
 }
 interface ProofLoopDecisionParams {
     policy_key: string;
+    episode_id?: string;
     candidates: ProofLoopCandidate[];
     proof_context?: ProofContext | string;
     collection_id?: string;
     user_id?: string;
     [key: string]: any;
 }
+interface EvidenceScope {
+    policy_key: string;
+    collection_id?: string;
+    user_id?: string;
+}
+interface VerifierRegistration extends EvidenceScope {
+    api_key_id: string;
+    source_system: string;
+    metric_keys: string[];
+}
+interface EpisodeCreateParams extends EvidenceScope {
+    verifier_id: string;
+    idempotency_key: string;
+}
+interface ExecutionClaim {
+    attempt_id: string;
+    status: "started" | "completed" | "failed" | "interrupted" | "blocked";
+    actual_action_key: string;
+    arguments_digest: string;
+    evidence_digest?: string;
+    occurred_at?: string;
+}
+interface VerifiedOutcomeDelivery {
+    decision_id: string;
+    source_event_id: string;
+    evidence_digest: string;
+    execution_digest: string;
+    observations: Array<{
+        metric_key: string;
+        value: number;
+        confidence?: number;
+        is_final?: boolean;
+        observed_at: string;
+    }>;
+}
 interface ReasoningSource {
     memory_id: string;
     content: string;
@@ -155,6 +197,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 +210,7 @@ interface MemoryAddResult {
     event: "ADD" | "UPDATE" | "NOOP" | string;
     memory?: string;
     reason?: string;
+    processing_status?: string;
 }
 interface MemoryAddResponse {
     results: MemoryAddResult[];
@@ -170,6 +219,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 +422,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
@@ -435,7 +501,7 @@ declare class SearchResource extends BaseResource {
     reason(params: ReasonParams): Promise<ReasoningResponse>;
 }
 declare class ProofLoopResource extends BaseResource {
-    /** Create a causal decision bound to search/chat evidence automatically. */
+    /** Record a recommendation; this never authorizes execution or proves causality. */
     decide(params: ProofLoopDecisionParams): Promise<Record<string, any>>;
     recordOutcome(decisionId: string, body: {
         observations?: Record<string, any>[];
@@ -444,6 +510,18 @@ declare class ProofLoopResource extends BaseResource {
         idempotency_key?: string;
     }): Promise<Record<string, any>>;
     getDecision(decisionId: string): Promise<Record<string, any>>;
+    /** Owner-session administration. Use a separate client for the verifier key. */
+    registerVerifier(params: VerifierRegistration): Promise<Record<string, any>>;
+    revokeVerifier(verifierId: string): Promise<Record<string, any>>;
+    createEpisode(params: EpisodeCreateParams): Promise<Record<string, any>>;
+    getEpisode(episodeId: string, offset?: number): Promise<Record<string, any>>;
+    closeEpisode(episodeId: string, status: "completed" | "interrupted"): Promise<Record<string, any>>;
+    /** Append an execution claim. This method does not execute a tool. */
+    recordExecution(decisionId: string, claim: ExecutionClaim): Promise<Record<string, any>>;
+    assessment(decisionId: string, evidenceOffset?: number): Promise<Record<string, any>>;
+    verifierEvidence(verifierId: string, decisionId: string): Promise<Record<string, any>>;
+    /** Deliver using the dedicated source credential, after checking execution independently. */
+    deliverVerifiedOutcomes(verifierId: string, delivery: VerifiedOutcomeDelivery): Promise<Record<string, any>>;
     defineMetric(params: ProofLoopMetricParams): Promise<Record<string, any>>;
     listMetrics(params?: {
         policy_key?: string;
@@ -689,11 +767,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 +855,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 EpisodeCreateParams, type EvidenceClaim, type EvidenceScope, type ExecutionClaim, 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, type VerifiedOutcomeDelivery, type VerifierRegistration, WorkingMemoryResource, enforceSearchSafety };