@buildaureon/sdk 0.1.2 → 0.1.7

package/dist/index.d.ts

@@ -1,61 +1,17 @@
-interface AureonLogger {
-    debug(message: string, context?: Record<string, unknown>): void;
-    info(message: string, context?: Record<string, unknown>): void;
-    warn(message: string, context?: Record<string, unknown>): void;
-    error(message: string, context?: Record<string, unknown>): void;
-}
-declare const silentLogger: AureonLogger;
-declare function createConsoleLogger(prefix?: string): AureonLogger;
-
 /**
- * @fileoverview Client configuration types for AureonClient.
+ * @fileoverview Timeline event contracts for append-only operator narratives.
  */
-
-interface AureonClientOptions {
-    /**
-     * Base URL of the AUREON API.
-     * Defaults to `https://api.aureonlabs.network`.
-     */
-    baseUrl?: string;
-    /**
-     * Product API key sent as `X-Aureon-Api-Key` on every request.
-     * Operator-issued keys (from the Developers console) also identify the
-     * bound wallet for control-plane calls — no Bearer required.
-     * Env bootstrap keys unlock product access only; they do not set identity.
-     * The operator utility uses wallet Bearer only.
-     */
-    apiKey?: string | null;
-    /**
-     * Called before each request to resolve the product API key.
-     * Prefer this for automations that load keys from env or a secret store.
-     */
-    getApiKey?: () => string | null | undefined | Promise<string | null | undefined>;
-    /** Optional fetch implementation for non-browser runtimes. */
-    fetch?: typeof fetch;
-    /** Optional default headers merged into every request. */
-    headers?: Record<string, string>;
-    /** Request timeout in milliseconds. Defaults to 30000. */
-    timeoutMs?: number;
-    /**
-     * Static Bearer session token. Prefer `getAccessToken` for apps that refresh
-     * or clear sessions at runtime.
-     */
-    authToken?: string | null;
-    /**
-     * Called before each request to resolve the current Bearer token.
-     * Return null/undefined to send the request without Authorization.
-     */
-    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
-    /** Optional structured logger for request lifecycle diagnostics. */
-    logger?: AureonLogger;
-    /**
-     * Extra attempts after the first failure for retryable errors
-     * (network, timeout, 429, 5xx). Defaults to 0.
-     */
-    maxRetries?: number;
-    /** Delay in ms between retries. Defaults to 250. */
-    retryDelayMs?: number;
+type TimelineEventType = "objective_created" | "objective_updated" | "objective_paused" | "objective_resumed" | "health_changed" | "violation_detected" | "evaluation_started" | "execution_started" | "execution_completed" | "market_event_applied" | "objective_restored" | "capital_provisioned" | "capital_cleared" | "capital_synced" | "registry_registered" | "settlement_recorded";
+interface TimelineEvent {
+    id: string;
+    objectiveId: string | null;
+    type: TimelineEventType;
+    message: string;
+    payload: Record<string, unknown>;
+    createdAt: string;
 }
+declare const TIMELINE_EVENT_TYPES: readonly TimelineEventType[];
+declare function isTimelineEventType(value: string): value is TimelineEventType;
 
 /**
  * @fileoverview Phase 2 ObjectiveRegistry types.
@@ -106,6 +62,39 @@ type ObjectiveRegistryLookup = {
     record: ObjectiveRegistryRecord;
 };
 
+/**
+ * @fileoverview On-chain settlement record for vault rebalances (Day 8).
+ */
+
+type SettlementStatus = "confirmed" | "orphan";
+interface SettlementRecord {
+    id: string;
+    executionId: string | null;
+    objectiveId: string | null;
+    walletAddress: string;
+    /** Chain-verified vault settlements are always `"vault"`. */
+    settlement: "vault";
+    transactionHash: string;
+    blockNumber: number;
+    logIndex: number;
+    vaultAddress: string;
+    tokenSell: string;
+    tokenBuy: string;
+    amountIn: string;
+    amountOut: string;
+    explorerUrl: string;
+    verifiedAt: string;
+    status: SettlementStatus;
+    registryRef?: RegistryRef;
+}
+interface ExecutionSettlementLookup {
+    executionId: string;
+    verifiedOnChain: boolean;
+    settlement: SettlementRecord | null;
+}
+/** Human-readable settlement summary for agents and logs. */
+declare function formatSettlementSummary(record: SettlementRecord): string;
+
 /**
  * @fileoverview Execution receipt + restore-plan types.
  *
@@ -128,8 +117,14 @@ interface ExecutionReceipt {
      * `"vault"`: keeper rebalance confirmed (or pending_vault_* then confirmed).
      * `"staged"`: capital-book restore only (honest non-finality label).
      */
-    settlement?: "staged" | "vault";
+    settlement: "staged" | "vault";
+    /** Block explorer link when vault tx is a real `0x…` hash; null for staged. */
+    explorerUrl?: string | null;
     registryRef?: RegistryRef;
+    /** True when a settlement record exists for this execution (vault only). */
+    verifiedOnChain?: boolean;
+    /** Populated when verifiedOnChain is true. */
+    settlementRecord?: SettlementRecord;
 }
 /** Client-side restore action: wrap/unwrap ETH↔WETH or keeper vault swap. */
 type RestorePlanKind = "wrap_eth" | "unwrap_weth" | "vault_swap";
@@ -143,38 +138,12 @@ interface RestorePlan {
 }
 /** True when the receipt claims vault (on-chain) settlement. */
 declare function isVaultSettlement(receipt: ExecutionReceipt): boolean;
-
-/**
- * @fileoverview Health Engine result types.
- */
-type HealthState = "healthy" | "warning" | "violation" | "paused";
-interface ObjectiveHealth {
-    objectiveId: string;
-    state: HealthState;
-    score: number;
-    currentMetric: number;
-    targetMetric: number;
-    deviation: number;
-    message: string;
-    evaluatedAt: string;
-}
-declare function isHealthState(value: string): value is HealthState;
-declare function pickWorstHealth(records: ObjectiveHealth[]): ObjectiveHealth | null;
-
-/**
- * @fileoverview Timeline event contracts for append-only operator narratives.
- */
-type TimelineEventType = "objective_created" | "objective_updated" | "objective_paused" | "objective_resumed" | "health_changed" | "violation_detected" | "evaluation_started" | "execution_started" | "execution_completed" | "market_event_applied" | "objective_restored" | "capital_provisioned" | "capital_cleared" | "capital_synced" | "registry_anchored";
-interface TimelineEvent {
-    id: string;
-    objectiveId: string | null;
-    type: TimelineEventType;
-    message: string;
-    payload: Record<string, unknown>;
-    createdAt: string;
-}
-declare const TIMELINE_EVENT_TYPES: readonly TimelineEventType[];
-declare function isTimelineEventType(value: string): value is TimelineEventType;
+/** True when the receipt has independent on-chain settlement proof. */
+declare function isChainVerifiedReceipt(receipt: ExecutionReceipt): boolean;
+/** Human-readable one-line receipt summary for agents and logs. */
+declare function formatReceiptSummary(receipt: ExecutionReceipt): string;
+/** Timeline events linked to a receipt via payload.executionId. */
+declare function findTimelineEventsForReceipt(events: TimelineEvent[], receipt: ExecutionReceipt): TimelineEvent[];
 
 /**
  * @fileoverview Controlled market event types for operator demos and rehearsals.
@@ -239,6 +208,23 @@ interface DashboardOverview {
     recentEvents: TimelineEvent[];
 }
 
+/**
+ * @fileoverview Health Engine result types.
+ */
+type HealthState = "healthy" | "warning" | "violation" | "paused";
+interface ObjectiveHealth {
+    objectiveId: string;
+    state: HealthState;
+    score: number;
+    currentMetric: number;
+    targetMetric: number;
+    deviation: number;
+    message: string;
+    evaluatedAt: string;
+}
+declare function isHealthState(value: string): value is HealthState;
+declare function pickWorstHealth(records: ObjectiveHealth[]): ObjectiveHealth | null;
+
 /**
  * @fileoverview Objective domain types for Financial Compass Objectives.
  */
@@ -333,6 +319,377 @@ declare const OBJECTIVE_PRIORITIES: readonly ObjectivePriority[];
 declare function isObjectiveKind(value: string): value is ObjectiveKind;
 declare function isObjectivePriority(value: string): value is ObjectivePriority;
 
+/**
+ * @fileoverview Objective vs actual allocation comparison and plan paradox detection.
+ */
+
+interface AllocationComparisonRow {
+    objectiveId: string;
+    name: string;
+    kind: ObjectiveKind;
+    targetSymbol?: string;
+    targetWeight: number;
+    currentMetric: number;
+    deviation: number;
+    state: HealthState;
+}
+interface PlanParadoxResult {
+    detected: boolean;
+    bookUp: boolean;
+    offPlanCount: number;
+    message: string;
+}
+/**
+ * Joins active objectives with health records into target vs current rows.
+ */
+declare function buildAllocationComparison(objectives: Objective[], health: ObjectiveHealth[]): AllocationComparisonRow[];
+/**
+ * Detects when book performance looks fine but objectives are off-plan.
+ */
+declare function detectPlanParadox(overview: DashboardOverview, health: ObjectiveHealth[]): PlanParadoxResult;
+
+/**
+ * @fileoverview Drift → detection → restore teaching flow helpers.
+ */
+
+type DriftRestorePhase = "aligned" | "drift_detected" | "restored";
+interface DriftRestoreFlow {
+    objectiveId: string;
+    rule: {
+        summary: string;
+        targetWeight: number;
+        tolerance: number;
+    };
+    phases: {
+        aligned: {
+            health: ObjectiveHealth;
+            allocationRow?: AllocationComparisonRow;
+        };
+        drift: {
+            health: ObjectiveHealth;
+            allocationRow?: AllocationComparisonRow;
+            restorePlan?: RestorePlan;
+        };
+        restored?: {
+            health: ObjectiveHealth;
+            receipt?: ExecutionReceipt;
+            settlement?: string;
+        };
+    };
+    currentPhase: DriftRestorePhase;
+    message: string;
+}
+/**
+ * Infers drift-restore phase from a single health snapshot.
+ */
+declare function inferDriftPhase(health: ObjectiveHealth): DriftRestorePhase;
+/**
+ * Builds the drift → detection → restore teaching shape.
+ */
+declare function buildDriftRestoreFlow(input: {
+    objective: Objective;
+    alignedHealth: ObjectiveHealth;
+    driftHealth: ObjectiveHealth;
+    driftPlan?: RestorePlan;
+    restoredHealth?: ObjectiveHealth;
+    receipt?: ExecutionReceipt;
+    alignedRow?: AllocationComparisonRow;
+    driftRow?: AllocationComparisonRow;
+}): DriftRestoreFlow;
+/**
+ * Read-only flow from current objective state + optional latest receipt.
+ */
+declare function buildDriftRestoreFlowFromSnapshot(input: {
+    objective: Objective;
+    health: ObjectiveHealth;
+    allocationRow?: AllocationComparisonRow;
+    restorePlan?: RestorePlan;
+    latestReceipt?: ExecutionReceipt;
+}): DriftRestoreFlow;
+
+/**
+ * @fileoverview Phase 2 execution receipt validator — schema + honesty rules.
+ */
+
+type ReceiptValidationCode = "INVALID_INPUT" | "MISSING_FIELD" | "INVALID_SETTLEMENT" | "INVALID_STATUS" | "MISSING_CONFIRMED_AT" | "STAGED_WITH_EXPLORER" | "STAGED_VERIFIED_ON_CHAIN" | "STAGED_WITH_SETTLEMENT_RECORD" | "INVALID_VAULT_HASH" | "VAULT_MISSING_EXPLORER" | "VERIFIED_WITHOUT_RECORD" | "VERIFIED_RECORD_MISMATCH" | "INVALID_REGISTRY_REF" | "INVALID_SETTLEMENT_RECORD";
+type ReceiptValidationIssue = {
+    code: ReceiptValidationCode;
+    message: string;
+    path?: string;
+};
+type ReceiptValidationResult = {
+    valid: boolean;
+    issues: ReceiptValidationIssue[];
+};
+/** Validates a settlement record nested on a receipt. */
+declare function validateSettlementRecord(input: unknown, options?: {
+    executionId?: string;
+}): ReceiptValidationResult;
+/**
+ * Validates an execution receipt against the Phase 2 contract + honesty rules.
+ * Never throws — inspect `valid` and `issues`.
+ */
+declare function validateExecutionReceipt(input: unknown): ReceiptValidationResult;
+/** Type guard: true when input passes validateExecutionReceipt. */
+declare function isValidExecutionReceipt(input: unknown): input is ExecutionReceipt;
+/** Throws AureonValidationError when the receipt fails validation. */
+declare function assertValidExecutionReceipt(receipt: unknown): asserts receipt is ExecutionReceipt;
+
+/**
+ * @fileoverview Receipt → verification teaching flow helpers.
+ */
+
+type ReceiptVerificationPhase = "claimed" | "validated" | "validation_failed" | "chain_verified";
+type ReceiptProofTier = "claim_only" | "schema_valid" | "chain_verified";
+interface ReceiptVerificationFlow {
+    executionId: string;
+    receipt: ExecutionReceipt;
+    phases: {
+        claimed: {
+            summary: string;
+            status: string;
+            settlement: string;
+            result: string;
+        };
+        validation: ReceiptValidationResult;
+        settlement?: ExecutionSettlementLookup;
+        timelineEvents?: TimelineEvent[];
+    };
+    proofTier: ReceiptProofTier;
+    currentPhase: ReceiptVerificationPhase;
+    message: string;
+}
+/**
+ * Infers proof tier from receipt, validation, and optional settlement lookup.
+ */
+declare function inferProofTier(receipt: ExecutionReceipt, validation: ReceiptValidationResult, settlement?: ExecutionSettlementLookup): ReceiptProofTier;
+/**
+ * Builds the receipt → verification teaching shape.
+ */
+declare function buildReceiptVerificationFlow(input: {
+    receipt: ExecutionReceipt;
+    validation?: ReceiptValidationResult;
+    settlement?: ExecutionSettlementLookup;
+    timelineEvents?: TimelineEvent[];
+}): ReceiptVerificationFlow;
+
+/**
+ * @fileoverview Portfolio watch while away — agent-in-host teaching flow (Update 6).
+ */
+
+type AgentHost = "cursor" | "claude" | "mcp";
+type PortfolioWatchPhase = "watch_registered" | "while_away" | "return_briefing";
+/** Default consumer brief for Update 6 demos. */
+declare const DEFAULT_PORTFOLIO_WATCH_BRIEF = "Watch my portfolio while I'm away \u2014 keep about 20% in stable assets.";
+interface PortfolioWatchFlow {
+    objectiveId: string;
+    userBrief: string;
+    host: AgentHost;
+    phases: {
+        register: {
+            objectiveName: string;
+            automationMode: string;
+            policySummary: string;
+            health: ObjectiveHealth;
+            allocationRow?: AllocationComparisonRow;
+        };
+        whileAway?: {
+            marketEventName: string;
+            symbol: string;
+            priceChangeRatio: number;
+            healthBefore: ObjectiveHealth;
+            healthAfter: ObjectiveHealth;
+            autoRestored: boolean;
+            receipt?: ExecutionReceipt;
+        };
+        briefing: {
+            health: ObjectiveHealth;
+            timelineEventCount: number;
+            timelineEvents: TimelineEvent[];
+            summaryLines: string[];
+        };
+    };
+    currentPhase: PortfolioWatchPhase;
+    message: string;
+}
+/**
+ * Infers portfolio-watch phase from register + optional while-away data.
+ */
+declare function inferPortfolioWatchPhase(input: {
+    registerHealth: ObjectiveHealth;
+    whileAway?: PortfolioWatchFlow["phases"]["whileAway"];
+}): PortfolioWatchPhase;
+/**
+ * Builds human-readable briefing lines for agent hosts (Cursor / Claude).
+ */
+declare function buildPortfolioWatchBriefingLines(input: {
+    userBrief: string;
+    host: AgentHost;
+    objective: Objective;
+    registerHealth: ObjectiveHealth;
+    briefingHealth: ObjectiveHealth;
+    whileAway?: PortfolioWatchFlow["phases"]["whileAway"];
+    timelineEvents: TimelineEvent[];
+}): string[];
+/**
+ * Builds the portfolio watch teaching shape for agent-in-host demos.
+ */
+declare function buildPortfolioWatchFlow(input: {
+    userBrief: string;
+    host: AgentHost;
+    objective: Objective;
+    registerHealth: ObjectiveHealth;
+    registerRow?: AllocationComparisonRow;
+    whileAway?: {
+        marketEvent: MarketEvent;
+        healthBefore: ObjectiveHealth;
+        healthAfter: ObjectiveHealth;
+        autoRestored: boolean;
+        receipt?: ExecutionReceipt;
+    };
+    briefingHealth: ObjectiveHealth;
+    timelineEvents: TimelineEvent[];
+}): PortfolioWatchFlow;
+/**
+ * Read-only portfolio watch snapshot from current objective state.
+ */
+declare function buildPortfolioWatchFlowFromSnapshot(input: {
+    userBrief: string;
+    host: AgentHost;
+    objective: Objective;
+    health: ObjectiveHealth;
+    allocationRow?: AllocationComparisonRow;
+    latestReceipt?: ExecutionReceipt;
+    timelineEvents: TimelineEvent[];
+}): PortfolioWatchFlow;
+
+/**
+ * @fileoverview Full AUREON loop teaching flow helpers.
+ */
+
+type FullAureonLoopPhase = "intent" | "plan_check" | "restored" | "verified";
+/** Default brief for full-loop demos. */
+declare const DEFAULT_FULL_LOOP_BRIEF = "Keep about 20% in stable assets \u2014 grow the book without abandoning the plan.";
+interface FullAureonLoopFlow {
+    objectiveId: string;
+    userBrief: string;
+    phases: {
+        intent: {
+            objectiveName: string;
+            policySummary: string;
+            automationMode: string;
+            health: ObjectiveHealth;
+        };
+        planCheck: {
+            baselineAligned: boolean;
+            afterShock: {
+                health: ObjectiveHealth;
+                allocationRow?: AllocationComparisonRow;
+                paradox: PlanParadoxResult;
+            };
+        };
+        driftRestore: {
+            healthBefore: ObjectiveHealth;
+            healthAfter: ObjectiveHealth;
+            receipt: ExecutionReceipt;
+            settlement: string;
+        };
+        verification: ReceiptVerificationFlow;
+    };
+    currentPhase: FullAureonLoopPhase;
+    message: string;
+}
+/**
+ * Infers loop phase from which stages are present.
+ */
+declare function inferFullAureonLoopPhase(input: {
+    hasRestore: boolean;
+    verificationValid: boolean;
+}): FullAureonLoopPhase;
+/**
+ * Builds the full AUREON loop teaching shape.
+ */
+declare function buildFullAureonLoopFlow(input: {
+    userBrief: string;
+    objective: Objective;
+    baselineHealth: ObjectiveHealth;
+    afterShockHealth: ObjectiveHealth;
+    afterShockRow?: AllocationComparisonRow;
+    paradox: PlanParadoxResult;
+    restoredHealth: ObjectiveHealth;
+    receipt: ExecutionReceipt;
+    verification?: ReceiptVerificationFlow;
+}): FullAureonLoopFlow;
+/**
+ * Read-only full-loop snapshot from current objective state + latest receipt.
+ */
+declare function buildFullAureonLoopFlowFromSnapshot(input: {
+    userBrief: string;
+    objective: Objective;
+    health: ObjectiveHealth;
+    allocationRow?: AllocationComparisonRow;
+    paradox: PlanParadoxResult;
+    latestReceipt?: ExecutionReceipt;
+    verification?: ReceiptVerificationFlow;
+}): FullAureonLoopFlow | null;
+
+/**
+ * @fileoverview Financial audit trail — objective → registry → receipt → settlement.
+ *
+ * Joins what already exists. Never invents missing proof. Gaps stay labeled.
+ */
+
+type AuditTrailGapCode = "not_registered" | "no_executions" | "no_settlements" | "staged_only" | "vault_unverified" | "invalid_receipt" | "no_timeline" | "lookup_failed";
+interface AuditTrailGap {
+    code: AuditTrailGapCode;
+    message: string;
+}
+interface AuditTrailReceiptRow {
+    id: string;
+    action: string;
+    settlement: "vault" | "staged";
+    status: string;
+    valid: boolean;
+    verifiedOnChain: boolean;
+    explorerUrl: string | null;
+    summary: string;
+    validation: ReceiptValidationResult;
+}
+interface FinancialAuditTrail {
+    objectiveId: string;
+    objectiveName: string;
+    policySummary: string;
+    healthState: string | null;
+    generatedAt: string;
+    registry: {
+        present: boolean;
+        record?: ObjectiveRegistryRecord;
+    };
+    receipts: AuditTrailReceiptRow[];
+    settlements: SettlementRecord[];
+    timeline: Array<{
+        id: string;
+        type: string;
+        message: string;
+        createdAt: string;
+        executionId: string | null;
+    }>;
+    gaps: AuditTrailGap[];
+    message: string;
+}
+declare function buildFinancialAuditTrail(input: {
+    objective: Objective;
+    health?: ObjectiveHealth;
+    registry?: ObjectiveRegistryLookup;
+    receipts: ExecutionReceipt[];
+    settlements: SettlementRecord[];
+    timeline: TimelineEvent[];
+    generatedAt?: string;
+    registryLookupFailed?: boolean;
+    settlementsLookupFailed?: boolean;
+}): FinancialAuditTrail;
+declare function formatAuditTrailLines(trail: FinancialAuditTrail): string[];
+
 /**
  * @fileoverview Portfolio snapshot types used by health evaluation and utility screens.
  */
@@ -365,6 +722,106 @@ interface PortfolioPositionInput {
     markPriceUsd: number;
 }
 
+/**
+ * @fileoverview Financial intent → objective → portfolio flow helpers.
+ */
+
+interface FinancialIntent {
+    /** User or agent wording — what they want money to do. */
+    brief: string;
+    kind: ObjectiveKind;
+    targetWeight: number;
+    tolerance: number;
+    targetSymbol?: string;
+    name?: string;
+    priority?: ObjectivePriority;
+}
+interface ObjectivePortfolioFlow {
+    intent: {
+        brief: string;
+        policySummary: string;
+    };
+    objective: Objective;
+    health: ObjectiveHealth | null;
+    portfolio: {
+        totalNotionalUsd: number;
+        stableWeight: number;
+        positions: PortfolioPosition[];
+    };
+    message: string;
+}
+/**
+ * Maps agent-extracted intent into a create-objective payload.
+ */
+declare function resolveObjectiveFromIntent(intent: FinancialIntent): CreateObjectiveInput;
+/**
+ * Builds the AI → objective → portfolio teaching shape after create + read.
+ */
+declare function buildObjectivePortfolioFlow(intent: FinancialIntent, objective: Objective, health: ObjectiveHealth | null, portfolio: PortfolioSnapshot): ObjectivePortfolioFlow;
+/**
+ * Lightweight rule-based parser for demo scripts.
+ */
+declare function parseFinancialIntent(brief: string): FinancialIntent;
+
+interface AureonLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+declare const silentLogger: AureonLogger;
+declare function createConsoleLogger(prefix?: string): AureonLogger;
+
+/**
+ * @fileoverview Client configuration types for AureonClient.
+ */
+
+interface AureonClientOptions {
+    /**
+     * Base URL of the AUREON API.
+     * Defaults to `https://api.aureonlabs.network`.
+     */
+    baseUrl?: string;
+    /**
+     * Product API key sent as `X-Aureon-Api-Key` on every request.
+     * Operator-issued keys (from the Developers console) also identify the
+     * bound wallet for control-plane calls — no Bearer required.
+     * Env bootstrap keys unlock product access only; they do not set identity.
+     * The operator utility uses wallet Bearer only.
+     */
+    apiKey?: string | null;
+    /**
+     * Called before each request to resolve the product API key.
+     * Prefer this for automations that load keys from env or a secret store.
+     */
+    getApiKey?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Optional fetch implementation for non-browser runtimes. */
+    fetch?: typeof fetch;
+    /** Optional default headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /**
+     * Static Bearer session token. Prefer `getAccessToken` for apps that refresh
+     * or clear sessions at runtime.
+     */
+    authToken?: string | null;
+    /**
+     * Called before each request to resolve the current Bearer token.
+     * Return null/undefined to send the request without Authorization.
+     */
+    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Optional structured logger for request lifecycle diagnostics. */
+    logger?: AureonLogger;
+    /**
+     * Extra attempts after the first failure for retryable errors
+     * (network, timeout, 429, 5xx). Defaults to 0.
+     */
+    maxRetries?: number;
+    /** Delay in ms between retries. Defaults to 250. */
+    retryDelayMs?: number;
+}
+
 /**
  * @fileoverview Vault overview + prepare-tx contracts for AureonVault.
  *
@@ -620,9 +1077,88 @@ declare class AureonClient {
     refreshWatchdog(): Promise<WatchdogRefreshResult>;
     /** Returns dashboard overview aggregates. Auth required. */
     getOverview(): Promise<DashboardOverview>;
+    /**
+     * Objective vs actual portfolio — joins objectives, health, and overview
+     * into comparison rows plus a green-book/off-plan paradox flag.
+     * Auth required.
+     */
+    getAllocationVsTarget(): Promise<{
+        rows: AllocationComparisonRow[];
+        paradox: PlanParadoxResult;
+        overview: DashboardOverview;
+    }>;
+    /**
+     * Registers agent/user intent as an Automatic objective and returns the
+     * AI → objective → portfolio flow snapshot.
+     * Auth required.
+     */
+    applyFinancialIntent(intent: FinancialIntent): Promise<ObjectivePortfolioFlow>;
+    /**
+     * Read-only AI → objective → portfolio flow for existing objectives.
+     * Auth required.
+     */
+    getObjectivePortfolioFlow(objectiveId?: string): Promise<ObjectivePortfolioFlow[]>;
+    /**
+     * Controlled drift → detection → restore demo
+     * Seeds book, creates stable objective, applies NVDA rally with auto-restore
+     * disabled, then runs manual restore and returns the three-beat flow.
+     * Auth required.
+     */
+    runDriftRestoreDemo(): Promise<DriftRestoreFlow>;
+    /**
+     * Read-only drift → detection → restore flow for active objectives.
+     * Auth required.
+     */
+    getDriftRestoreFlow(objectiveId?: string): Promise<DriftRestoreFlow[]>;
+    private buildReceiptVerificationFlowForReceipt;
+    /**
+     * Controlled receipt → verification demo.
+     * Runs drift-restore, then validates receipt and looks up settlement.
+     * Auth required.
+     */
+    runReceiptVerificationDemo(): Promise<ReceiptVerificationFlow>;
+    /**
+     * Read-only receipt → verification flow for execution receipts.
+     * Auth required.
+     */
+    getReceiptVerificationFlow(executionId?: string): Promise<ReceiptVerificationFlow[]>;
+    /**
+     * Controlled portfolio watch demo.
+     * User brief → Automatic objective → market move while away → auto restore → return briefing.
+     * Auth required.
+     */
+    runPortfolioWatchDemo(input?: {
+        brief?: string;
+        host?: AgentHost;
+    }): Promise<PortfolioWatchFlow>;
+    /**
+     * Read-only portfolio watch briefing for Automatic objectives.
+     * Auth required.
+     */
+    getPortfolioWatchFlow(input?: {
+        objectiveId?: string;
+        brief?: string;
+        host?: AgentHost;
+    }): Promise<PortfolioWatchFlow[]>;
+    /**
+     * Controlled full AUREON loop demo (Content Arc).
+     * Intent → plan check (green vs plan with autoRestore false) → restore → receipt verification.
+     * Auth required.
+     */
+    runFullAureonLoopDemo(input?: {
+        brief?: string;
+    }): Promise<FullAureonLoopFlow>;
+    /**
+     * Read-only full AUREON loop for active objectives with a latest receipt.
+     * Auth required.
+     */
+    getFullAureonLoopFlow(input?: {
+        objectiveId?: string;
+        brief?: string;
+    }): Promise<FullAureonLoopFlow[]>;
     /**
      * Applies a controlled market event to portfolio marks.
-     * When autoRestore is true, the API evaluates health and may run staged restorative execution.
+     * When autoRestore is true, the API may run restore. Omit or false = drift only, no restore. Automatic still 409s if the vault cannot execute.
      * Auth required.
      */
     applyMarketEvent(input: ApplyMarketEventInput): Promise<{
@@ -646,12 +1182,24 @@ declare class AureonClient {
      */
     runExecution(objectiveId: string): Promise<ExecutionReceipt>;
     /**
-     * Runs vault-backed restorative execution for an objective outside policy.
+     * Runs restorative execution for an objective outside policy.
+     * Receipt.settlement may be vault or staged. Only verifiedOnChain is proof.
      * Auth required.
      */
     restoreObjective(objectiveId: string): Promise<ExecutionReceipt>;
     /** Lists recent execution receipts. Auth required. */
     listExecutions(objectiveId?: string): Promise<ExecutionReceipt[]>;
+    /** Returns chain-verified settlement record for an execution when present. Auth required. */
+    getExecutionSettlement(executionId: string): Promise<ExecutionSettlementLookup>;
+    /** Lists chain-verified settlement records for the authenticated wallet. Auth required. */
+    listSettlements(objectiveId?: string): Promise<SettlementRecord[]>;
+    /**
+     * Manual backfill: verify a vault tx on-chain and attach settlement proof.
+     * Auth required.
+     */
+    confirmExecutionSettlement(executionId: string, transactionHash: string): Promise<{
+        settlement: SettlementRecord;
+    }>;
     /** Returns Phase 2 ObjectiveRegistry deployment status. Auth required. */
     getRegistryStatus(): Promise<RegistryStatus>;
     /** Returns on-chain registry record for an objective when registered. Auth required. */
@@ -701,6 +1249,11 @@ declare class AureonClient {
     revokeApiKey(keyId: string): Promise<DeveloperApiKey>;
     /** Toggles the status (active/paused) of an SDK API key owned by this wallet. */
     toggleApiKey(keyId: string): Promise<DeveloperApiKey>;
+    /**
+     * Joins objective → registry → receipts → settlements → timeline.
+     * Missing proof is labeled as a gap. Nothing is invented. Auth required.
+     */
+    getAuditTrail(objectiveId: string): Promise<FinancialAuditTrail>;
 }
 
 /**
@@ -825,7 +1378,7 @@ declare const DEFAULT_API_BASE_URL = "https://api.aureonlabs.network";
 /** Local monorepo preview only; not for public docs. */
 declare const LOCAL_API_BASE_URL = "http://127.0.0.1:8787";
 declare const DEFAULT_TIMEOUT_MS = 30000;
-declare const SDK_VERSION = "0.1.2";
+declare const SDK_VERSION = "0.1.7";
 declare const SDK_NAME = "@buildaureon/sdk";
 declare const PRODUCT_NAME = "AUREON";
 declare const PRODUCT_TAGLINE = "Financial Compass for Robinhood Chain";
@@ -860,6 +1413,7 @@ declare const ENDPOINTS: {
     readonly authMe: "/auth/me";
     readonly developerApiKeys: "/developer/api-keys";
     readonly registryStatus: "/registry/status";
+    readonly settlements: "/settlements";
 };
 
 /**
@@ -868,4 +1422,4 @@ declare const ENDPOINTS: {
 type FetchLike = typeof fetch;
 declare function resolveFetch(custom?: FetchLike): FetchLike;
 
-export { API_KEY_HEADER, type ApplyMarketEventInput, AureonClient, type AureonClientOptions, AureonConflictError, AureonError, type AureonErrorCode, AureonNetworkError, AureonNotFoundError, AureonTimeoutError, AureonValidationError, type AuthMeResponse, type AuthNonceResponse, type AuthSessionResponse, type CreateObjectiveInput, type CreatedDeveloperApiKey, DEFAULT_API_BASE_URL, DEFAULT_TIMEOUT_MS, type DashboardOverview, type DeveloperApiKey, ENDPOINTS, type ExecutionReceipt, type HealthState, LOCAL_API_BASE_URL, type MarkQuote, type MarkQuoteSource, type MarketEvent, type MarketPreset, OBJECTIVE_KINDS, OBJECTIVE_PRIORITIES, type Objective, type ObjectiveAutomationMode, type ObjectiveHealth, type ObjectiveKind, type ObjectivePolicy, type ObjectivePriority, type ObjectiveRegistryLookup, type ObjectiveRegistryRecord, type ObjectiveStatus, PRODUCT_NAME, PRODUCT_TAGLINE, type PortfolioPosition, type PortfolioPositionInput, type PortfolioSnapshot, type PrepareRegistryResult, type RegistryRef, type RegistryStatus, type RestorePlan, type RestorePlanKind, type RestoreSuggestion, type RestoreSuggestionAction, SDK_NAME, SDK_VERSION, type SessionTokenProvider, type SyncPortfolioResult, TIMELINE_EVENT_TYPES, type TimelineEvent, type TimelineEventType, type UpdateObjectiveInput, type VaultBalance, type VaultDepositSymbol, type VaultOverview, type VaultPrepareResult, type VaultPreparedStep, type VaultStatus, type VaultToken, type VaultWithdrawSymbol, type WatchdogAlertResult, type WatchdogRefreshResult, assertBaseUrl, buildPolicySummary, createAureonClient, createConsoleLogger, createLocalAureonClient, createSessionTokenProvider, errorFromHttpStatus, formatIsoTime, formatSignedPercent, formatUsd, formatWeight, healthTone, isAureonError, isHealthState, isObjectiveKind, isObjectivePriority, isTimelineEventType, isVaultSettlement, joinUrl, normalizeCreateObjectiveInput, normalizeUpdateObjectiveInput, pickWorstHealth, requestJson, resolveFetch, silentLogger, withQuery };
+export { API_KEY_HEADER, type AgentHost, type AllocationComparisonRow, type ApplyMarketEventInput, type AuditTrailGap, type AuditTrailGapCode, type AuditTrailReceiptRow, AureonClient, type AureonClientOptions, AureonConflictError, AureonError, type AureonErrorCode, AureonNetworkError, AureonNotFoundError, AureonTimeoutError, AureonValidationError, type AuthMeResponse, type AuthNonceResponse, type AuthSessionResponse, type CreateObjectiveInput, type CreatedDeveloperApiKey, DEFAULT_API_BASE_URL, DEFAULT_FULL_LOOP_BRIEF, DEFAULT_PORTFOLIO_WATCH_BRIEF, DEFAULT_TIMEOUT_MS, type DashboardOverview, type DeveloperApiKey, type DriftRestoreFlow, type DriftRestorePhase, ENDPOINTS, type ExecutionReceipt, type ExecutionSettlementLookup, type FinancialAuditTrail, type FinancialIntent, type FullAureonLoopFlow, type FullAureonLoopPhase, type HealthState, LOCAL_API_BASE_URL, type MarkQuote, type MarkQuoteSource, type MarketEvent, type MarketPreset, OBJECTIVE_KINDS, OBJECTIVE_PRIORITIES, type Objective, type ObjectiveAutomationMode, type ObjectiveHealth, type ObjectiveKind, type ObjectivePolicy, type ObjectivePortfolioFlow, type ObjectivePriority, type ObjectiveRegistryLookup, type ObjectiveRegistryRecord, type ObjectiveStatus, PRODUCT_NAME, PRODUCT_TAGLINE, type PlanParadoxResult, type PortfolioPosition, type PortfolioPositionInput, type PortfolioSnapshot, type PortfolioWatchFlow, type PortfolioWatchPhase, type PrepareRegistryResult, type ReceiptProofTier, type ReceiptValidationCode, type ReceiptValidationIssue, type ReceiptValidationResult, type ReceiptVerificationFlow, type ReceiptVerificationPhase, type RegistryRef, type RegistryStatus, type RestorePlan, type RestorePlanKind, type RestoreSuggestion, type RestoreSuggestionAction, SDK_NAME, SDK_VERSION, type SessionTokenProvider, type SettlementRecord, type SettlementStatus, type SyncPortfolioResult, TIMELINE_EVENT_TYPES, type TimelineEvent, type TimelineEventType, type UpdateObjectiveInput, type VaultBalance, type VaultDepositSymbol, type VaultOverview, type VaultPrepareResult, type VaultPreparedStep, type VaultStatus, type VaultToken, type VaultWithdrawSymbol, type WatchdogAlertResult, type WatchdogRefreshResult, assertBaseUrl, assertValidExecutionReceipt, buildAllocationComparison, buildDriftRestoreFlow, buildDriftRestoreFlowFromSnapshot, buildFinancialAuditTrail, buildFullAureonLoopFlow, buildFullAureonLoopFlowFromSnapshot, buildObjectivePortfolioFlow, buildPolicySummary, buildPortfolioWatchBriefingLines, buildPortfolioWatchFlow, buildPortfolioWatchFlowFromSnapshot, buildReceiptVerificationFlow, createAureonClient, createConsoleLogger, createLocalAureonClient, createSessionTokenProvider, detectPlanParadox, errorFromHttpStatus, findTimelineEventsForReceipt, formatAuditTrailLines, formatIsoTime, formatReceiptSummary, formatSettlementSummary, formatSignedPercent, formatUsd, formatWeight, healthTone, inferDriftPhase, inferFullAureonLoopPhase, inferPortfolioWatchPhase, inferProofTier, isAureonError, isChainVerifiedReceipt, isHealthState, isObjectiveKind, isObjectivePriority, isTimelineEventType, isValidExecutionReceipt, isVaultSettlement, joinUrl, normalizeCreateObjectiveInput, normalizeUpdateObjectiveInput, parseFinancialIntent, pickWorstHealth, requestJson, resolveFetch, resolveObjectiveFromIntent, silentLogger, validateExecutionReceipt, validateSettlementRecord, withQuery };