hebbrix 2.3.1 → 2.5.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.5.0-rc.1 — 2026-09-09 (prerelease, npm `next`)
+
+- Add typed native experience program, job, review, revision, policy activation
+  and one-use execution-permission transports.
+- Preserve separate credentials, opaque evidence, uncertainty and authorization
+  receipts; never convert recommendations into execution permission.
+- Require the matching `b5c6d7e8f959` backend, not yet deployed to public
+  production. Stable 2.4.0 remains the production recommendation.
+
+## 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

@@ -5,8 +5,14 @@ outcome-learning APIs.
 
 ## Install
 
+This branch is the **2.5.0-rc.1 prerelease**, published under npm `next`.
+Native experience operations require backend schema `b5c6d7e8f959`, which is not
+yet deployed to the public production API. Keep `2.4.0` for the current stable
+deployment. Installing this SDK does not grant execution permission or establish
+that an agent learns better outcomes.
+
 ```bash
-npm install hebbrix@2.3.1
+npm install hebbrix@2.5.0-rc.1
 ```
 
 Node.js 16+ and modern browsers are supported.

package/dist/index.d.mts

@@ -101,12 +101,84 @@ 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 ExperienceAssessmentParams {
+    collection_id?: string | null;
+    user_id?: string | null;
+    context: Record<string, unknown>;
+    candidate: {
+        schema_version?: "experience-candidate-v1";
+        policy_key: string;
+        action_key: string;
+        lesson: string;
+        applicability: {
+            schema_version?: "experience-applicability-v1";
+            required: Record<string, string | number | boolean>;
+        };
+        sources: Array<{
+            decision_id: string;
+            evidence_revision: number;
+            bundle_digest: string;
+        }>;
+    };
+}
+interface ExperienceContextParams {
+    memory_collection_id: string;
+    evidence_collection_id?: string | null;
+    user_id?: string | null;
+    agent_id?: string | null;
+    run_id?: string | null;
+    policy_key: string;
+    references: Array<{
+        memory_id: string;
+        record_digest: string;
+    }>;
+    context: Record<string, unknown>;
+    max_context_bytes?: number;
+}
+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 {
+    /** Optional source claims; their canonical digest must match evidence_digest. */
+    evidence_document?: Record<string, unknown>;
+    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 +537,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 +546,22 @@ 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>>;
+    /** Revalidate a hypothesis against current source evidence; never permission to act. */
+    assessExperience(params: ExperienceAssessmentParams): Promise<Record<string, any>>;
+    /** Revalidate selected stored hypotheses; never grants execution permission. */
+    experienceContext(params: ExperienceContextParams): 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;
@@ -668,6 +756,118 @@ declare class MemoryToolsResource extends BaseResource {
     rethink(memoryId: string, collectionId: string): Promise<any>;
 }
 
+/** Native workflow transport. Separate owner, worker and reviewer credentials.
+ * No provider call or autonomous tool execution is started by this resource.
+ */
+
+interface ReflectionConfig {
+    model: string;
+    applicability_keys: string[];
+    maximum_attempts: number;
+    budget_microusd: number;
+    per_attempt_microusd: number;
+    lease_seconds?: number;
+}
+interface ExperienceProgramInput {
+    collection_id?: string;
+    memory_collection_id: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    policy_key: string;
+    worker_key_id: string;
+    reviewer_key_id?: string;
+    source_since?: string;
+    config: ReflectionConfig;
+}
+interface ReflectionOutput {
+    schema_version?: "experience-reflection-output-v1";
+    hypotheses: Array<{
+        advice: string;
+        rationale: string;
+        limitations: string;
+        future_verification: string;
+    }>;
+    insufficient_evidence_reason?: string | null;
+}
+interface LessonReviewInput {
+    expected_sequence: number;
+    expected_digest: string | null;
+    candidate_digest: string;
+    verdict: "eligible" | "blocked" | "retracted";
+    rationale: string;
+}
+interface LessonRevisionInput extends Omit<LessonReviewInput, "verdict"> {
+    request_key: string;
+    hypothesis: ReflectionOutput["hypotheses"][number];
+}
+type ReflectionUncertainty = "provider_failure" | "invalid_provider_output" | "completion_delivery_uncertain";
+declare class ExperienceWorkflowResource {
+    private client;
+    constructor(client: MemoryClient);
+    definePermission(id: string, policy: {
+        actor_key_id: string;
+        tool_key: string;
+        target_digest: string;
+        action_keys: string[];
+        maximum_argument_bytes: number;
+        maximum_dispatches: number;
+        permit_seconds: number;
+        capability_contract: string;
+    }): Promise<any>;
+    activatePermission(id: string, activation: {
+        policy_id: string | null;
+        expected_sequence: number;
+        expected_digest: string | null;
+        rationale: string;
+    }): Promise<any>;
+    permissionState(id: string): Promise<any>;
+    issuePermit(id: string, input: {
+        lesson_id: string;
+        decision_id: string;
+        request_key: string;
+        invocation: {
+            tool_key: string;
+            target: Record<string, unknown>;
+            arguments: Record<string, unknown>;
+        };
+    }): Promise<any>;
+    dispatchPermit(id: string, invocationDigest: string): Promise<any>;
+    permit(id: string): Promise<any>;
+    register(input: ExperienceProgramInput): Promise<any>;
+    program(id: string): Promise<any>;
+    stop(id: string): Promise<any>;
+    claim(id: string, requestKey: string): Promise<any>;
+    job(id: string): Promise<any>;
+    /** A dispatch grant is single-use. Never retry a provider call after uncertainty. */
+    dispatch(id: string, input: {
+        input_digest: string;
+        request_digest: string;
+    }): Promise<any>;
+    complete(id: string, input: {
+        output: ReflectionOutput;
+        request_digest: string;
+        provider_response_digest: string;
+        reported_microusd: number;
+    }): Promise<any>;
+    uncertain(id: string, requestDigest: string, reason: ReflectionUncertainty): Promise<any>;
+    lessons(id: string, params?: {
+        after_id?: string;
+        limit?: number;
+    }): Promise<any>;
+    reviewQueue(id: string, params?: {
+        after_id?: string;
+        limit?: number;
+    }): Promise<any>;
+    lesson(id: string): Promise<any>;
+    review(id: string, input: LessonReviewInput): Promise<any>;
+    revise(id: string, input: LessonRevisionInput): Promise<any>;
+    reviews(id: string, params?: {
+        after_sequence?: number;
+        limit?: number;
+    }): Promise<any>;
+}
+
 declare class MemoryClient {
     private apiKey?;
     private baseUrl;
@@ -685,6 +885,7 @@ declare class MemoryClient {
     consolidation: ConsolidationResource;
     memoryTools: MemoryToolsResource;
     proofloop: ProofLoopResource;
+    experiences: ExperienceWorkflowResource;
     constructor(config?: ClientConfig);
     private getHeaders;
     private handleError;
@@ -807,4 +1008,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 ExperienceAssessmentParams, type ExperienceContextParams, type ExperienceProgramInput, ExperienceWorkflowResource, type GroundingReceipt, HebbrixError, IndexingAbortedError, IndexingTerminalError, IndexingTimeoutError, IndexingWaitError, type IndexingWaitErrorOptions, type LessonReviewInput, type LessonRevisionInput, 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 ReflectionConfig, type ReflectionOutput, type ReflectionUncertainty, 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,84 @@ 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 ExperienceAssessmentParams {
+    collection_id?: string | null;
+    user_id?: string | null;
+    context: Record<string, unknown>;
+    candidate: {
+        schema_version?: "experience-candidate-v1";
+        policy_key: string;
+        action_key: string;
+        lesson: string;
+        applicability: {
+            schema_version?: "experience-applicability-v1";
+            required: Record<string, string | number | boolean>;
+        };
+        sources: Array<{
+            decision_id: string;
+            evidence_revision: number;
+            bundle_digest: string;
+        }>;
+    };
+}
+interface ExperienceContextParams {
+    memory_collection_id: string;
+    evidence_collection_id?: string | null;
+    user_id?: string | null;
+    agent_id?: string | null;
+    run_id?: string | null;
+    policy_key: string;
+    references: Array<{
+        memory_id: string;
+        record_digest: string;
+    }>;
+    context: Record<string, unknown>;
+    max_context_bytes?: number;
+}
+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 {
+    /** Optional source claims; their canonical digest must match evidence_digest. */
+    evidence_document?: Record<string, unknown>;
+    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 +537,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 +546,22 @@ 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>>;
+    /** Revalidate a hypothesis against current source evidence; never permission to act. */
+    assessExperience(params: ExperienceAssessmentParams): Promise<Record<string, any>>;
+    /** Revalidate selected stored hypotheses; never grants execution permission. */
+    experienceContext(params: ExperienceContextParams): 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;
@@ -668,6 +756,118 @@ declare class MemoryToolsResource extends BaseResource {
     rethink(memoryId: string, collectionId: string): Promise<any>;
 }
 
+/** Native workflow transport. Separate owner, worker and reviewer credentials.
+ * No provider call or autonomous tool execution is started by this resource.
+ */
+
+interface ReflectionConfig {
+    model: string;
+    applicability_keys: string[];
+    maximum_attempts: number;
+    budget_microusd: number;
+    per_attempt_microusd: number;
+    lease_seconds?: number;
+}
+interface ExperienceProgramInput {
+    collection_id?: string;
+    memory_collection_id: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    policy_key: string;
+    worker_key_id: string;
+    reviewer_key_id?: string;
+    source_since?: string;
+    config: ReflectionConfig;
+}
+interface ReflectionOutput {
+    schema_version?: "experience-reflection-output-v1";
+    hypotheses: Array<{
+        advice: string;
+        rationale: string;
+        limitations: string;
+        future_verification: string;
+    }>;
+    insufficient_evidence_reason?: string | null;
+}
+interface LessonReviewInput {
+    expected_sequence: number;
+    expected_digest: string | null;
+    candidate_digest: string;
+    verdict: "eligible" | "blocked" | "retracted";
+    rationale: string;
+}
+interface LessonRevisionInput extends Omit<LessonReviewInput, "verdict"> {
+    request_key: string;
+    hypothesis: ReflectionOutput["hypotheses"][number];
+}
+type ReflectionUncertainty = "provider_failure" | "invalid_provider_output" | "completion_delivery_uncertain";
+declare class ExperienceWorkflowResource {
+    private client;
+    constructor(client: MemoryClient);
+    definePermission(id: string, policy: {
+        actor_key_id: string;
+        tool_key: string;
+        target_digest: string;
+        action_keys: string[];
+        maximum_argument_bytes: number;
+        maximum_dispatches: number;
+        permit_seconds: number;
+        capability_contract: string;
+    }): Promise<any>;
+    activatePermission(id: string, activation: {
+        policy_id: string | null;
+        expected_sequence: number;
+        expected_digest: string | null;
+        rationale: string;
+    }): Promise<any>;
+    permissionState(id: string): Promise<any>;
+    issuePermit(id: string, input: {
+        lesson_id: string;
+        decision_id: string;
+        request_key: string;
+        invocation: {
+            tool_key: string;
+            target: Record<string, unknown>;
+            arguments: Record<string, unknown>;
+        };
+    }): Promise<any>;
+    dispatchPermit(id: string, invocationDigest: string): Promise<any>;
+    permit(id: string): Promise<any>;
+    register(input: ExperienceProgramInput): Promise<any>;
+    program(id: string): Promise<any>;
+    stop(id: string): Promise<any>;
+    claim(id: string, requestKey: string): Promise<any>;
+    job(id: string): Promise<any>;
+    /** A dispatch grant is single-use. Never retry a provider call after uncertainty. */
+    dispatch(id: string, input: {
+        input_digest: string;
+        request_digest: string;
+    }): Promise<any>;
+    complete(id: string, input: {
+        output: ReflectionOutput;
+        request_digest: string;
+        provider_response_digest: string;
+        reported_microusd: number;
+    }): Promise<any>;
+    uncertain(id: string, requestDigest: string, reason: ReflectionUncertainty): Promise<any>;
+    lessons(id: string, params?: {
+        after_id?: string;
+        limit?: number;
+    }): Promise<any>;
+    reviewQueue(id: string, params?: {
+        after_id?: string;
+        limit?: number;
+    }): Promise<any>;
+    lesson(id: string): Promise<any>;
+    review(id: string, input: LessonReviewInput): Promise<any>;
+    revise(id: string, input: LessonRevisionInput): Promise<any>;
+    reviews(id: string, params?: {
+        after_sequence?: number;
+        limit?: number;
+    }): Promise<any>;
+}
+
 declare class MemoryClient {
     private apiKey?;
     private baseUrl;
@@ -685,6 +885,7 @@ declare class MemoryClient {
     consolidation: ConsolidationResource;
     memoryTools: MemoryToolsResource;
     proofloop: ProofLoopResource;
+    experiences: ExperienceWorkflowResource;
     constructor(config?: ClientConfig);
     private getHeaders;
     private handleError;
@@ -807,4 +1008,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 ExperienceAssessmentParams, type ExperienceContextParams, type ExperienceProgramInput, ExperienceWorkflowResource, type GroundingReceipt, HebbrixError, IndexingAbortedError, IndexingTerminalError, IndexingTimeoutError, IndexingWaitError, type IndexingWaitErrorOptions, type LessonReviewInput, type LessonRevisionInput, 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 ReflectionConfig, type ReflectionOutput, type ReflectionUncertainty, 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

@@ -26,6 +26,7 @@ __export(index_exports, {
   ConsolidationResource: () => ConsolidationResource,
   CorrectionsResource: () => CorrectionsResource,
   EntitlementError: () => EntitlementError,
+  ExperienceWorkflowResource: () => ExperienceWorkflowResource,
   HebbrixError: () => HebbrixError,
   IndexingAbortedError: () => IndexingAbortedError,
   IndexingTerminalError: () => IndexingTerminalError,
@@ -61,7 +62,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 +77,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 +110,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 +731,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 +750,64 @@ 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 }
+    );
+  }
+  /** Revalidate a hypothesis against current source evidence; never permission to act. */
+  async assessExperience(params) {
+    return this.client.post("/v1/learning/experiences/assess", params);
+  }
+  /** Revalidate selected stored hypotheses; never grants execution permission. */
+  async experienceContext(params) {
+    return this.client.post("/v1/learning/experiences/context", params);
+  }
+  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);
   }
@@ -1055,6 +1134,79 @@ var MemoryToolsResource = class extends BaseResource {
   }
 };
 
+// src/experience-workflow.ts
+var root = "/v1/learning/experiences";
+var resource = (kind, id) => `${root}/${kind}/${encodeURIComponent(id)}`;
+var ExperienceWorkflowResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  definePermission(id, policy) {
+    return this.client.post(`${resource("programs", id)}/permission-policies`, policy);
+  }
+  activatePermission(id, activation) {
+    return this.client.post(`${resource("programs", id)}/permission-activation`, activation);
+  }
+  permissionState(id) {
+    return this.client.get(`${resource("programs", id)}/permission-state`);
+  }
+  issuePermit(id, input) {
+    return this.client.post(`${resource("programs", id)}/permits`, input);
+  }
+  dispatchPermit(id, invocationDigest) {
+    return this.client.post(`${resource("permits", id)}/dispatch`, { invocation_digest: invocationDigest });
+  }
+  permit(id) {
+    return this.client.get(resource("permits", id));
+  }
+  register(input) {
+    return this.client.post(`${root}/programs`, input);
+  }
+  program(id) {
+    return this.client.get(resource("programs", id));
+  }
+  stop(id) {
+    return this.client.post(`${resource("programs", id)}/stop`);
+  }
+  claim(id, requestKey) {
+    return this.client.post(`${resource("programs", id)}/claim`, { request_key: requestKey });
+  }
+  job(id) {
+    return this.client.get(resource("jobs", id));
+  }
+  /** A dispatch grant is single-use. Never retry a provider call after uncertainty. */
+  dispatch(id, input) {
+    return this.client.post(`${resource("jobs", id)}/dispatch`, input);
+  }
+  complete(id, input) {
+    return this.client.post(`${resource("jobs", id)}/complete`, input);
+  }
+  uncertain(id, requestDigest, reason) {
+    return this.client.post(`${resource("jobs", id)}/uncertain`, {
+      request_digest: requestDigest,
+      reason
+    });
+  }
+  lessons(id, params = {}) {
+    return this.client.get(`${resource("programs", id)}/lessons`, params);
+  }
+  reviewQueue(id, params = {}) {
+    return this.client.get(`${resource("programs", id)}/review-queue`, params);
+  }
+  lesson(id) {
+    return this.client.get(resource("lessons", id));
+  }
+  review(id, input) {
+    return this.client.post(`${resource("lessons", id)}/reviews`, input);
+  }
+  revise(id, input) {
+    return this.client.post(`${resource("lessons", id)}/revisions`, input);
+  }
+  reviews(id, params = {}) {
+    return this.client.get(`${resource("lessons", id)}/reviews`, params);
+  }
+};
+
 // src/client.ts
 var MemoryClient = class {
   constructor(config = {}) {
@@ -1075,11 +1227,12 @@ var MemoryClient = class {
     this.consolidation = new ConsolidationResource(this);
     this.memoryTools = new MemoryToolsResource(this);
     this.proofloop = new ProofLoopResource(this);
+    this.experiences = new ExperienceWorkflowResource(this);
   }
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.1"
+      "User-Agent": "hebbrix-typescript/2.5.0-rc.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -1216,6 +1369,7 @@ var MemoryClient = class {
   ConsolidationResource,
   CorrectionsResource,
   EntitlementError,
+  ExperienceWorkflowResource,
   HebbrixError,
   IndexingAbortedError,
   IndexingTerminalError,

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,64 @@ 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 }
+    );
+  }
+  /** Revalidate a hypothesis against current source evidence; never permission to act. */
+  async assessExperience(params) {
+    return this.client.post("/v1/learning/experiences/assess", params);
+  }
+  /** Revalidate selected stored hypotheses; never grants execution permission. */
+  async experienceContext(params) {
+    return this.client.post("/v1/learning/experiences/context", params);
+  }
+  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);
   }
@@ -1004,6 +1082,79 @@ var MemoryToolsResource = class extends BaseResource {
   }
 };
 
+// src/experience-workflow.ts
+var root = "/v1/learning/experiences";
+var resource = (kind, id) => `${root}/${kind}/${encodeURIComponent(id)}`;
+var ExperienceWorkflowResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  definePermission(id, policy) {
+    return this.client.post(`${resource("programs", id)}/permission-policies`, policy);
+  }
+  activatePermission(id, activation) {
+    return this.client.post(`${resource("programs", id)}/permission-activation`, activation);
+  }
+  permissionState(id) {
+    return this.client.get(`${resource("programs", id)}/permission-state`);
+  }
+  issuePermit(id, input) {
+    return this.client.post(`${resource("programs", id)}/permits`, input);
+  }
+  dispatchPermit(id, invocationDigest) {
+    return this.client.post(`${resource("permits", id)}/dispatch`, { invocation_digest: invocationDigest });
+  }
+  permit(id) {
+    return this.client.get(resource("permits", id));
+  }
+  register(input) {
+    return this.client.post(`${root}/programs`, input);
+  }
+  program(id) {
+    return this.client.get(resource("programs", id));
+  }
+  stop(id) {
+    return this.client.post(`${resource("programs", id)}/stop`);
+  }
+  claim(id, requestKey) {
+    return this.client.post(`${resource("programs", id)}/claim`, { request_key: requestKey });
+  }
+  job(id) {
+    return this.client.get(resource("jobs", id));
+  }
+  /** A dispatch grant is single-use. Never retry a provider call after uncertainty. */
+  dispatch(id, input) {
+    return this.client.post(`${resource("jobs", id)}/dispatch`, input);
+  }
+  complete(id, input) {
+    return this.client.post(`${resource("jobs", id)}/complete`, input);
+  }
+  uncertain(id, requestDigest, reason) {
+    return this.client.post(`${resource("jobs", id)}/uncertain`, {
+      request_digest: requestDigest,
+      reason
+    });
+  }
+  lessons(id, params = {}) {
+    return this.client.get(`${resource("programs", id)}/lessons`, params);
+  }
+  reviewQueue(id, params = {}) {
+    return this.client.get(`${resource("programs", id)}/review-queue`, params);
+  }
+  lesson(id) {
+    return this.client.get(resource("lessons", id));
+  }
+  review(id, input) {
+    return this.client.post(`${resource("lessons", id)}/reviews`, input);
+  }
+  revise(id, input) {
+    return this.client.post(`${resource("lessons", id)}/revisions`, input);
+  }
+  reviews(id, params = {}) {
+    return this.client.get(`${resource("lessons", id)}/reviews`, params);
+  }
+};
+
 // src/client.ts
 var MemoryClient = class {
   constructor(config = {}) {
@@ -1024,11 +1175,12 @@ var MemoryClient = class {
     this.consolidation = new ConsolidationResource(this);
     this.memoryTools = new MemoryToolsResource(this);
     this.proofloop = new ProofLoopResource(this);
+    this.experiences = new ExperienceWorkflowResource(this);
   }
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.1"
+      "User-Agent": "hebbrix-typescript/2.5.0-rc.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -1164,6 +1316,7 @@ export {
   ConsolidationResource,
   CorrectionsResource,
   EntitlementError,
+  ExperienceWorkflowResource,
   HebbrixError,
   IndexingAbortedError,
   IndexingTerminalError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hebbrix",
-  "version": "2.3.1",
+  "version": "2.5.0-rc.1",
   "description": "Typed TypeScript client for Hebbrix memory, retrieval, and outcome-learning APIs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -55,7 +55,8 @@
   },
   "homepage": "https://docs.hebbrix.com",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "next"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",