@blockrun/franklin 3.18.0 → 3.20.0

package/dist/trading/trade-log.d.ts

@@ -16,6 +16,37 @@
  * prior crash never bricks the log.
  */
 import type { Side } from './portfolio.js';
+/**
+ * Trade rationale — the "why" behind a fill, captured at trade time so
+ * the journal can score for discipline (not P&L). Inspired by the AI-Trader
+ * signal-quality model: verifiability + evidence + specificity drive better
+ * decisions than rewarding outcomes (which incentivizes curve-fitting).
+ *
+ * All fields are optional; the scorer rewards completeness without forcing it.
+ */
+export interface TradeRationale {
+    direction?: 'long' | 'short' | 'neutral';
+    priceTarget?: number;
+    stopLoss?: number;
+    timeHorizon?: string;
+    conviction?: 1 | 2 | 3 | 4 | 5;
+    evidence?: string[];
+    tags?: string[];
+    thesis?: string;
+}
+/**
+ * Persisted quality breakdown — five components on 0–1 scales plus a 0–5
+ * total. Written next to each entry at append time so portfolio reads
+ * never need to re-score.
+ */
+export interface QualityScore {
+    total: number;
+    verifiability: number;
+    evidence: number;
+    specificity: number;
+    novelty: number;
+    review: number;
+}
 export interface TradeLogEntry {
     timestamp: number;
     symbol: string;
@@ -25,6 +56,12 @@ export interface TradeLogEntry {
     feeUsd: number;
     /** Realized P&L from this specific fill — 0 for opens, ± for closes. */
     realizedPnlUsd: number;
+    /** Journal-v2 fields (optional, back-compat: older entries lack these). */
+    rationale?: TradeRationale;
+    /** User's post-trade note. Boosts the `review` component of the score. */
+    review?: string;
+    /** Computed at append time so portfolio reads don't re-score on every render. */
+    qualityScore?: QualityScore;
 }
 export declare class TradeLog {
     private filePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {