hebbrix 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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:

package/README.md

@@ -6,7 +6,7 @@ outcome-learning APIs.
 ## Install
 
 ```bash
-npm install hebbrix@2.3.1
+npm install hebbrix@2.4.0
 ```
 
 Node.js 16+ and modern browsers are supported.

package/dist/index.d.mts

@@ -101,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;
@@ -465,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>[];
@@ -474,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;
@@ -807,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, 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 };
+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

@@ -101,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;
@@ -465,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>[];
@@ -474,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;
@@ -807,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, 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 };
+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.js

@@ -61,7 +61,7 @@ var REQUIRED_FIELDS = [
 function enforceSearchSafety(response, rowsKey = "results") {
   const data = { ...response };
   const rawRows = data[rowsKey];
-  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const rows = Array.isArray(rawRows) ? rawRows : [];
   const missing = REQUIRED_FIELDS.filter(
     (field) => !Object.prototype.hasOwnProperty.call(data, field)
   );
@@ -76,6 +76,22 @@ function enforceSearchSafety(response, rowsKey = "results") {
     reason = "invalid_grounding_receipt";
   } else if (!Array.isArray(data.evidence_ids)) {
     reason = "invalid_evidence_ids";
+  } else if (data.safety_contract_version !== "search-safety-v1") {
+    reason = "unsupported_safety_contract_version";
+  } else if (!Array.isArray(rawRows)) {
+    reason = "invalid_evidence_rows";
+  } else if (data.evidence_ids.some((id) => typeof id !== "string" || !id.trim())) {
+    reason = "invalid_evidence_ids";
+  } else if (new Set(data.evidence_ids).size !== data.evidence_ids.length) {
+    reason = "duplicate_evidence_ids";
+  } else if (rows.some((row) => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return true;
+    const id = "memory_id" in row ? row.memory_id : row.id;
+    return typeof id !== "string" || !id.trim() || "memory_id" in row && "id" in row && row.memory_id !== row.id;
+  })) {
+    reason = "invalid_evidence_row_identity";
+  } else if (rows.length === 0 && data.no_match === false) {
+    reason = "no_evidence_rows";
   } else {
     const evidenceIds = new Set(data.evidence_ids.map(String));
     const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
@@ -93,6 +109,10 @@ function enforceSearchSafety(response, rowsKey = "results") {
     data.query_confidence = 0;
     data.evidence_ids = [];
     data.evidence_claims = [];
+    if (rowsKey === "sources") {
+      data.answer = null;
+      data.citations = [];
+    }
     if (reason) {
       data.sdk_safety_reason = reason;
       data.grounding = { status: "no_grounded_match", reason };
@@ -710,7 +730,7 @@ var SearchResource = class extends BaseResource {
   }
 };
 var ProofLoopResource = class extends BaseResource {
-  /** Create a causal decision bound to search/chat evidence automatically. */
+  /** Record a recommendation; this never authorizes execution or proves causality. */
   async decide(params) {
     const context = params.proof_context;
     const token = typeof context === "string" ? context : context?.token;
@@ -729,6 +749,56 @@ var ProofLoopResource = class extends BaseResource {
   async getDecision(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}`);
   }
+  /** Owner-session administration. Use a separate client for the verifier key. */
+  async registerVerifier(params) {
+    return this.client.post("/v1/learning/verifiers", params);
+  }
+  async revokeVerifier(verifierId) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/revoke`,
+      {}
+    );
+  }
+  async createEpisode(params) {
+    return this.client.post("/v1/learning/episodes", params);
+  }
+  async getEpisode(episodeId, offset = 0) {
+    return this.client.get(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}`,
+      { offset }
+    );
+  }
+  async closeEpisode(episodeId, status) {
+    return this.client.post(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}/close`,
+      { status }
+    );
+  }
+  /** Append an execution claim. This method does not execute a tool. */
+  async recordExecution(decisionId, claim) {
+    return this.client.post(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/executions`,
+      claim
+    );
+  }
+  async assessment(decisionId, evidenceOffset = 0) {
+    return this.client.get(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/assessment`,
+      { evidence_offset: evidenceOffset }
+    );
+  }
+  async verifierEvidence(verifierId, decisionId) {
+    return this.client.get(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/decisions/${encodeURIComponent(decisionId)}`
+    );
+  }
+  /** Deliver using the dedicated source credential, after checking execution independently. */
+  async deliverVerifiedOutcomes(verifierId, delivery) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/events`,
+      delivery
+    );
+  }
   async defineMetric(params) {
     return this.client.post("/v1/learning/metrics", params);
   }
@@ -1079,7 +1149,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.1"
+      "User-Agent": "hebbrix-typescript/2.4.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;

package/dist/index.mjs

@@ -10,7 +10,7 @@ var REQUIRED_FIELDS = [
 function enforceSearchSafety(response, rowsKey = "results") {
   const data = { ...response };
   const rawRows = data[rowsKey];
-  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const rows = Array.isArray(rawRows) ? rawRows : [];
   const missing = REQUIRED_FIELDS.filter(
     (field) => !Object.prototype.hasOwnProperty.call(data, field)
   );
@@ -25,6 +25,22 @@ function enforceSearchSafety(response, rowsKey = "results") {
     reason = "invalid_grounding_receipt";
   } else if (!Array.isArray(data.evidence_ids)) {
     reason = "invalid_evidence_ids";
+  } else if (data.safety_contract_version !== "search-safety-v1") {
+    reason = "unsupported_safety_contract_version";
+  } else if (!Array.isArray(rawRows)) {
+    reason = "invalid_evidence_rows";
+  } else if (data.evidence_ids.some((id) => typeof id !== "string" || !id.trim())) {
+    reason = "invalid_evidence_ids";
+  } else if (new Set(data.evidence_ids).size !== data.evidence_ids.length) {
+    reason = "duplicate_evidence_ids";
+  } else if (rows.some((row) => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return true;
+    const id = "memory_id" in row ? row.memory_id : row.id;
+    return typeof id !== "string" || !id.trim() || "memory_id" in row && "id" in row && row.memory_id !== row.id;
+  })) {
+    reason = "invalid_evidence_row_identity";
+  } else if (rows.length === 0 && data.no_match === false) {
+    reason = "no_evidence_rows";
   } else {
     const evidenceIds = new Set(data.evidence_ids.map(String));
     const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
@@ -42,6 +58,10 @@ function enforceSearchSafety(response, rowsKey = "results") {
     data.query_confidence = 0;
     data.evidence_ids = [];
     data.evidence_claims = [];
+    if (rowsKey === "sources") {
+      data.answer = null;
+      data.citations = [];
+    }
     if (reason) {
       data.sdk_safety_reason = reason;
       data.grounding = { status: "no_grounded_match", reason };
@@ -659,7 +679,7 @@ var SearchResource = class extends BaseResource {
   }
 };
 var ProofLoopResource = class extends BaseResource {
-  /** Create a causal decision bound to search/chat evidence automatically. */
+  /** Record a recommendation; this never authorizes execution or proves causality. */
   async decide(params) {
     const context = params.proof_context;
     const token = typeof context === "string" ? context : context?.token;
@@ -678,6 +698,56 @@ var ProofLoopResource = class extends BaseResource {
   async getDecision(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}`);
   }
+  /** Owner-session administration. Use a separate client for the verifier key. */
+  async registerVerifier(params) {
+    return this.client.post("/v1/learning/verifiers", params);
+  }
+  async revokeVerifier(verifierId) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/revoke`,
+      {}
+    );
+  }
+  async createEpisode(params) {
+    return this.client.post("/v1/learning/episodes", params);
+  }
+  async getEpisode(episodeId, offset = 0) {
+    return this.client.get(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}`,
+      { offset }
+    );
+  }
+  async closeEpisode(episodeId, status) {
+    return this.client.post(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}/close`,
+      { status }
+    );
+  }
+  /** Append an execution claim. This method does not execute a tool. */
+  async recordExecution(decisionId, claim) {
+    return this.client.post(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/executions`,
+      claim
+    );
+  }
+  async assessment(decisionId, evidenceOffset = 0) {
+    return this.client.get(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/assessment`,
+      { evidence_offset: evidenceOffset }
+    );
+  }
+  async verifierEvidence(verifierId, decisionId) {
+    return this.client.get(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/decisions/${encodeURIComponent(decisionId)}`
+    );
+  }
+  /** Deliver using the dedicated source credential, after checking execution independently. */
+  async deliverVerifiedOutcomes(verifierId, delivery) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/events`,
+      delivery
+    );
+  }
   async defineMetric(params) {
     return this.client.post("/v1/learning/metrics", params);
   }
@@ -1028,7 +1098,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.1"
+      "User-Agent": "hebbrix-typescript/2.4.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hebbrix",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Typed TypeScript client for Hebbrix memory, retrieval, and outcome-learning APIs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",