@insiderfinance/totalfinance 0.1.0

package/modules/workflows/dist/operations-journey.js

@@ -0,0 +1,2445 @@
+/**
+ * The journey operations (Stage 7A Decision 4): thin compositions of GREEN compute — a portfolio
+ * valued from its ledger, a P&L explained between two marks, a scenario set run against targets, a
+ * universe screened / ranked / scored, an event study, an options backtest, and the artifact read
+ * and compare doors. Every schema is authored over the direct function's own input shape (same
+ * field names, same defaults, same nulls — law C16); a wire-only restriction (no callbacks, no class
+ * instances, no iterables) is a NARROWER schema, never a different meaning. Nothing is aggregated
+ * here: each `structured` output is the direct result verbatim, and a report of several results
+ * keeps them side by side under one `assumptions`.
+ */
+import { compareAnalysisArtifacts, readAnalysisArtifact, readMarketSnapshot, readScenarioSet, } from '../../core/dist/artifacts/index.js';
+import { OptionQuoteSchema, schema } from '../../core/dist/schema/index.js';
+import { crossSectionalBacktest, fees, slippage } from '../../backtest/dist/index.js';
+import { execution, impactModels, latencyModels, spreadModels, } from '../../backtest/dist/execution/index.js';
+import { optionsBacktest } from '../../backtest/dist/options/index.js';
+import { portfolioBacktest } from '../../backtest/dist/portfolio/index.js';
+import { backtestRunArtifact } from '../../backtest/dist/artifacts.js';
+import { ENVIRONMENT_EPISODE_IDS, agentBaselines, runAgentBench, } from '../../backtest/dist/environment/index.js';
+import { monitorPortfolio, portfolioPnl, portfolioSnapshot, portfolioTimeline, proposePortfolioRebalance, readPortfolioLedgerSnapshot, } from '../../portfolio/dist/index.js';
+import { discountedCashFlowFromStatements, discountedCashFlowSensitivityTable, } from '../../valuation/dist/index.js';
+import { eventStudy, rankUniverse, scoreUniverse, screenUniverse } from '../../research/dist/index.js';
+import { runScenarios, scenarioPortfolioBinding, scenarioTarget, scenarioTargetsFromPortfolio, } from '../../scenarios/dist/index.js';
+import { defineOperation } from './operation.js';
+import { capRows } from './operation-kit.js';
+import { boundedPreview } from './preview.js';
+// ── shared envelope schemas (closed at the level the direct read door re-validates) ───────────
+const ASSUMPTIONS_SCHEMA = { type: 'object', description: 'Applied conventions' };
+const DIAGNOSTICS_SCHEMA = { type: 'object', description: 'Engine, method, warnings' };
+const epochMsOrDate = schema
+    .union([schema.number(), schema.string()])
+    .describe('Epoch ms, YYYY-MM-DD, or a zoned ISO datetime');
+import { CurrencyPairQuoteSchema, MarketSnapshotSchema, PortfolioLedgerEnvelopeSchema, PortfolioStateSchema, ProvenanceSchema, } from './wire-schemas.js';
+const ValuationMarkSchema = schema.object({
+    valuationDate: schema
+        .string()
+        .date()
+        .describe('Strict YYYY-MM-DD; the mark instant is 00:00 UTC'),
+    market: MarketSnapshotSchema,
+    currencyConversions: schema.array(CurrencyPairQuoteSchema).optional(),
+});
+const InstrumentClassificationSchema = schema
+    .record(schema.object({
+    underlying: schema.string().optional(),
+    assetClass: schema.string().optional(),
+    strategy: schema.string().optional(),
+    tags: schema.array(schema.string()).optional(),
+}))
+    .describe('Identity metadata per instrument for grouping; unknown instruments group as unclassified');
+const AnalysisArtifactSchema = schema
+    .object({
+    kind: schema.literal('totalfinance.analysis-artifact'),
+    schemaVersion: schema.number().integer(),
+    id: schema.string(),
+    artifactType: schema.string(),
+    producedBy: schema.object({
+        operation: schema.string(),
+        libraryVersion: schema.string().optional(),
+    }),
+    conventionsVersion: schema.string(),
+    inputs: schema.object({
+        inputsHash: schema.string(),
+        snapshotHash: schema.string().optional(),
+        parameters: schema.unknown().optional(),
+    }),
+    createdFrom: schema.array(schema.string()).optional(),
+    result: schema.record(schema.unknown()),
+    tables: schema.record(schema.record(schema.unknown())).optional(),
+    provenance: ProvenanceSchema.optional(),
+})
+    .describe('A Gate B analysis artifact (totalfinance.analysis-artifact); hashes are re-verified by the read door');
+const ScenarioSetSchema = schema
+    .object({
+    kind: schema.literal('totalfinance.scenario-set'),
+    schemaVersion: schema.number().integer(),
+    name: schema.string().nonempty(),
+    scenarios: schema
+        .array(schema.object({
+        name: schema.string().nonempty(),
+        shocks: schema.array(schema.object({
+            factor: schema.string(),
+            kind: schema.enum(['percent', 'absolute']),
+            value: schema.number(),
+            target: schema.string().optional(),
+        })),
+        overrides: schema
+            .array(schema.object({
+            factor: schema.string(),
+            value: schema.number(),
+            target: schema.string().optional(),
+        }))
+            .optional(),
+    }))
+        .min(1),
+    provenance: ProvenanceSchema.optional(),
+})
+    .describe('A Gate B scenario set (totalfinance.scenario-set)');
+/** A ledger envelope re-hydrates through the read door; a state is handed through as it is. */
+function portfolioStateOf(portfolio) {
+    if (portfolio.kind === 'totalfinance.portfolio-ledger') {
+        return readPortfolioLedgerSnapshot({ snapshot: portfolio }).ledger.state;
+    }
+    return portfolio;
+}
+// ── portfolio ─────────────────────────────────────────────────────────────────────────────────
+const PortfolioSnapshotInputSchema = schema.object({
+    portfolio: schema
+        .union([PortfolioLedgerEnvelopeSchema, PortfolioStateSchema])
+        .describe('A serialized ledger envelope (re-hydrated through readPortfolioLedgerSnapshot) or a PortfolioState'),
+    asOf: epochMsOrDate.describe('The valuation instant'),
+    market: MarketSnapshotSchema,
+    currencyConversions: schema
+        .array(CurrencyPairQuoteSchema)
+        .optional()
+        .describe('Quotes to the base currency — required exactly when the portfolio holds non-base currency'),
+});
+const PORTFOLIO_SNAPSHOT_OUTPUT = {
+    type: 'object',
+    properties: {
+        asOf: { type: 'number' },
+        baseCurrency: { type: 'string' },
+        netAssetValue: { type: 'number' },
+        cash: { type: 'array', items: { type: 'object' } },
+        totalCashBaseCurrencyValue: { type: 'number' },
+        positions: { type: 'array', items: { type: 'object' } },
+        totalPositionsBaseCurrencyValue: { type: 'number' },
+        assumptions: ASSUMPTIONS_SCHEMA,
+        diagnostics: DIAGNOSTICS_SCHEMA,
+    },
+    required: [
+        'asOf',
+        'baseCurrency',
+        'netAssetValue',
+        'cash',
+        'totalCashBaseCurrencyValue',
+        'positions',
+        'totalPositionsBaseCurrencyValue',
+        'assumptions',
+        'diagnostics',
+    ],
+};
+const portfolioSnapshotOperation = defineOperation({
+    id: 'totalfinance.portfolio.snapshot',
+    handleFields: ['portfolio', 'market'],
+    title: 'Value a portfolio at an instant',
+    description: 'Value every cash balance and position of a portfolio at one instant from a Gate B market snapshot: ' +
+        'net asset value in the base currency, per-account cash rows (settled and unsettled), per-position marks, ' +
+        'cost basis and unrealized P&L. Supply the portfolio as its serialized ledger envelope (re-hydrated ' +
+        'through readPortfolioLedgerSnapshot) or as a derived PortfolioState. The result is portfolioSnapshot(...) verbatim.',
+    inputSchema: PortfolioSnapshotInputSchema,
+    outputSchema: PORTFOLIO_SNAPSHOT_OUTPUT,
+    costClass: 'small',
+    run: (input) => {
+        const result = portfolioSnapshot({
+            portfolio: portfolioStateOf(input.portfolio),
+            asOf: input.asOf,
+            market: input.market,
+            ...(input.currencyConversions !== undefined
+                ? { currencyConversions: input.currencyConversions }
+                : {}),
+        });
+        return {
+            summary: `NAV ${result.netAssetValue.toFixed(2)} ${result.baseCurrency} at ${new Date(result.asOf).toISOString()} (${result.positions.length} positions, ${result.cash.length} cash rows)`,
+            structured: result,
+        };
+    },
+});
+const PortfolioPnlInputSchema = schema.object({
+    ledger: PortfolioLedgerEnvelopeSchema,
+    from: ValuationMarkSchema.describe('The opening valuation mark'),
+    to: ValuationMarkSchema.describe('The closing valuation mark (strictly after `from`)'),
+    instrumentClassification: InstrumentClassificationSchema.optional(),
+});
+const PORTFOLIO_PNL_OUTPUT = {
+    type: 'object',
+    properties: {
+        baseCurrency: { type: 'string' },
+        from: { type: 'object' },
+        to: { type: 'object' },
+        netAssetValueChange: { type: 'number' },
+        externalFlows: { type: 'number' },
+        investmentReturn: { type: 'number' },
+        components: {
+            type: 'object',
+            description: 'realized, unrealized, income, costs, financing, FX, total',
+        },
+        residual: { type: 'number' },
+        byCurrency: { type: 'array', items: { type: 'object' } },
+        groupings: { type: 'array', items: { type: 'object' } },
+        assumptions: ASSUMPTIONS_SCHEMA,
+        diagnostics: DIAGNOSTICS_SCHEMA,
+    },
+    required: [
+        'baseCurrency',
+        'from',
+        'to',
+        'netAssetValueChange',
+        'externalFlows',
+        'investmentReturn',
+        'components',
+        'residual',
+        'byCurrency',
+        'groupings',
+        'assumptions',
+        'diagnostics',
+    ],
+};
+const portfolioExplainPnl = defineOperation({
+    id: 'totalfinance.portfolio.explain_pnl',
+    handleFields: ['ledger', 'from.market', 'to.market'],
+    title: 'Explain portfolio P&L between two marks',
+    description: 'Explain the change in net asset value between two dated valuation marks: external flows, investment return, ' +
+        'and the identity components (realized, unrealized, income, transaction costs, financing, foreign exchange) that ' +
+        'reconcile to it with a published residual, by currency and by grouping. The result is portfolioPnl(...) verbatim.',
+    inputSchema: PortfolioPnlInputSchema,
+    outputSchema: PORTFOLIO_PNL_OUTPUT,
+    costClass: 'small',
+    run: (input) => {
+        const { ledger } = readPortfolioLedgerSnapshot({ snapshot: input.ledger });
+        const result = portfolioPnl({
+            ledger,
+            from: input.from,
+            to: input.to,
+            ...(input.instrumentClassification !== undefined
+                ? { instrumentClassification: input.instrumentClassification }
+                : {}),
+        });
+        return {
+            summary: `NAV ${result.from.netAssetValue.toFixed(2)} → ${result.to.netAssetValue.toFixed(2)} ${result.baseCurrency} (${input.from.valuationDate} → ${input.to.valuationDate}): total P&L ${result.components.totalPnl.toFixed(2)}, external flows ${result.externalFlows.toFixed(2)}`,
+            structured: result,
+        };
+    },
+});
+// ── artifacts ─────────────────────────────────────────────────────────────────────────────────
+const artifactRead = defineOperation({
+    id: 'totalfinance.artifact.read',
+    handleFields: ['artifact'],
+    title: 'Read an analysis artifact',
+    description: 'Validate a Gate B analysis artifact (its envelope, its recomputed inputs hash, and its content-hash identity) and ' +
+        'return its identity, type, producer, provenance warnings, table names, and a bounded preview of the stored result ' +
+        '— the one read door for any artifact over the wire. Migrations are not registered over the wire; a stored ' +
+        'older version is refused with the versions named.',
+    inputSchema: schema.object({ artifact: AnalysisArtifactSchema }),
+    outputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            artifactType: { type: 'string' },
+            schemaVersion: { type: 'integer' },
+            producedBy: { type: 'object' },
+            conventionsVersion: { type: 'string' },
+            inputs: { type: 'object' },
+            createdFrom: { type: 'array', items: { type: 'string' } },
+            tables: { type: 'array', items: { type: 'string' } },
+            warnings: { type: 'array', items: { type: 'object' } },
+            preview: {
+                type: 'object',
+                description: 'Top-level keys; scalars inline, containers by size',
+            },
+            migrationsApplied: { type: 'array', items: { type: 'object' } },
+        },
+        required: [
+            'id',
+            'artifactType',
+            'schemaVersion',
+            'producedBy',
+            'conventionsVersion',
+            'inputs',
+            'createdFrom',
+            'tables',
+            'warnings',
+            'preview',
+            'migrationsApplied',
+        ],
+    },
+    costClass: 'small',
+    run: (input) => {
+        const { artifact, migrationsApplied } = readAnalysisArtifact({ artifact: input.artifact });
+        return {
+            summary: `${artifact.artifactType} ${artifact.id} by ${artifact.producedBy.operation} (${Object.keys(artifact.result).length} result fields)`,
+            structured: {
+                id: artifact.id,
+                artifactType: artifact.artifactType,
+                schemaVersion: artifact.schemaVersion,
+                producedBy: artifact.producedBy,
+                conventionsVersion: artifact.conventionsVersion,
+                inputs: artifact.inputs,
+                createdFrom: artifact.createdFrom ?? [],
+                tables: Object.keys(artifact.tables ?? {}),
+                warnings: artifact.provenance?.warnings ?? [],
+                preview: boundedPreview(artifact.result),
+                migrationsApplied,
+            },
+        };
+    },
+});
+const artifactCompare = defineOperation({
+    id: 'totalfinance.artifact.compare',
+    handleFields: ['baseline', 'candidate'],
+    title: 'Compare two analysis artifacts',
+    description: 'Compare a baseline and a candidate artifact of the same type leaf by leaf: value differences with absolute and ' +
+        'relative deltas, added and removed paths, whether inputs and producers match, and — when a tolerance is supplied — ' +
+        'whether every numeric leaf is within it. The result is compareAnalysisArtifacts(...) verbatim.',
+    inputSchema: schema.object({
+        baseline: AnalysisArtifactSchema,
+        candidate: AnalysisArtifactSchema,
+        tolerance: schema
+            .object({
+            absolute: schema.number().nonnegative(),
+            relative: schema.number().nonnegative(),
+        })
+            .optional()
+            .describe('Two-sided: a leaf is within it when |Δ| ≤ absolute + relative·|baseline|'),
+        limits: schema
+            .object({
+            maximumDifferences: schema.number().integer().positive().optional(),
+            maximumLeaves: schema.number().integer().positive().optional(),
+        })
+            .optional(),
+    }),
+    outputSchema: {
+        type: 'object',
+        properties: {
+            artifactType: { type: 'string' },
+            identical: { type: 'boolean' },
+            artifactIds: { type: 'object' },
+            inputs: { type: 'object' },
+            producedBy: { type: 'object' },
+            result: { type: 'object' },
+            warningCounts: { type: 'object' },
+            withinTolerance: { type: ['boolean', 'null'] },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'artifactType',
+            'identical',
+            'artifactIds',
+            'inputs',
+            'producedBy',
+            'result',
+            'warningCounts',
+            'withinTolerance',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'medium',
+    run: (input) => {
+        const result = compareAnalysisArtifacts({
+            baseline: readAnalysisArtifact({ artifact: input.baseline }).artifact,
+            candidate: readAnalysisArtifact({ artifact: input.candidate }).artifact,
+            ...(input.tolerance !== undefined ? { tolerance: input.tolerance } : {}),
+            ...(input.limits !== undefined ? { limits: input.limits } : {}),
+        });
+        return {
+            summary: result.identical
+                ? `${result.artifactType}: identical`
+                : `${result.artifactType}: ${result.result.differenceCount} differences over ${result.result.comparedLeafCount} leaves${result.withinTolerance === null ? '' : result.withinTolerance ? ' (within tolerance)' : ' (outside tolerance)'}`,
+            structured: result,
+        };
+    },
+});
+// ── portfolio.analyze (snapshot + timeline + monitor under one assumptions) ──────────────────
+const TargetGroupSchema = schema
+    .object({
+    instrumentId: schema.string().optional(),
+    sleeveId: schema.string().optional(),
+    assetClass: schema.string().optional(),
+    currency: schema.string().optional(),
+    tag: schema.string().optional(),
+    underlying: schema.string().optional(),
+    strategy: schema.string().optional(),
+})
+    .describe('Exactly one group key');
+const AllocationTargetSchema = schema.object({
+    group: TargetGroupSchema,
+    weight: schema.number().optional(),
+    riskBudget: schema.number().optional(),
+    driftBand: schema.number().optional(),
+});
+const BenchmarkIdentitySchema = schema.object({
+    benchmarkId: schema.string().nonempty(),
+    asOf: epochMsOrDate.optional(),
+    constituents: schema
+        .array(schema.object({ instrumentId: schema.string(), weight: schema.number() }))
+        .optional(),
+});
+const InvestmentPolicySchema = schema.object({
+    targets: schema.array(AllocationTargetSchema).optional(),
+    model: schema
+        .record(schema.unknown())
+        .optional()
+        .describe('A model portfolio envelope (totalfinance.model-portfolio), validated by the policy grammar'),
+    withinGroupAllocation: schema.enum(['proportional-to-current', 'equal']).optional(),
+    driftBand: schema.number().optional(),
+    reviewCadenceDays: schema.number().optional(),
+    maximumTurnover: schema.number().optional(),
+    maximumEstimatedTransactionCost: schema.number().optional(),
+    minimumCash: schema.number().optional(),
+    minimumCashWeight: schema.number().optional(),
+    limits: schema
+        .object({
+        maximumPositionWeight: schema.number().optional(),
+        maximumGroupWeights: schema
+            .array(schema.object({ group: TargetGroupSchema, maximumWeight: schema.number() }))
+            .optional(),
+        maximumGrossLeverage: schema.number().optional(),
+        maximumDrawdown: schema.number().optional(),
+        maximumDailyLoss: schema.number().optional(),
+        maximumDaysToLiquidate: schema.number().optional(),
+        minimumSettledCash: schema.number().optional(),
+    })
+        .optional(),
+    allowedInstruments: schema.array(schema.string()).optional(),
+    restrictedInstruments: schema.array(schema.string()).optional(),
+    allowedAccounts: schema.array(schema.string()).optional(),
+    benchmark: BenchmarkIdentitySchema.optional(),
+    performanceObjective: schema.string().optional(),
+    contributionHandling: schema.enum(['invest-to-targets', 'hold-as-cash']).optional(),
+    withdrawalHandling: schema.enum(['raise-from-overweights', 'pro-rata']).optional(),
+    incomeReinvestment: schema.enum(['reinvest', 'hold-as-cash']).optional(),
+    lotSelectionObjective: schema.string().optional(),
+});
+const nullableNumber = schema.union([schema.number(), schema.null()]);
+const MonitorStateSchema = schema.object({
+    schemaVersion: schema.number().integer(),
+    asOf: schema.number(),
+    netAssetValue: nullableNumber,
+    peakNetAssetValue: nullableNumber,
+    evaluationCount: schema.number().integer().nonnegative(),
+    rules: schema.record(schema.object({
+        active: schema.boolean(),
+        consecutiveBreaches: schema.number().integer().nonnegative(),
+        lastRaisedAtMs: nullableNumber,
+        acknowledged: schema.boolean(),
+        lastValue: nullableNumber,
+    })),
+});
+const MonitorRuleSchema = schema.object({
+    enabled: schema.boolean().optional(),
+    threshold: schema.number().optional(),
+    direction: schema.enum(['above', 'below']).optional(),
+    hysteresis: schema.object({ enter: schema.number(), exit: schema.number() }).optional(),
+    debounceEvaluations: schema.number().integer().positive().optional().describe('Default 1'),
+    cooldownMs: schema.number().nonnegative().optional().describe('Default 0'),
+    severity: schema.enum(['informational', 'warning', 'critical']).optional(),
+});
+const MonitorRequestSchema = schema
+    .object({
+    policy: InvestmentPolicySchema,
+    previousState: schema
+        .union([MonitorStateSchema, schema.null()])
+        .describe("The prior evaluation's state, or null for the first evaluation — required, exactly as monitorPortfolio requires it"),
+    rules: schema.record(MonitorRuleSchema).optional().describe('Per alert family'),
+    acknowledgments: schema.array(schema.string()).optional(),
+    averageDailyVolumes: schema.record(schema.number()).optional(),
+    marketStalenessLimitMs: schema.number().optional(),
+    unusualPnlThreshold: schema.number().optional(),
+    residualTolerance: schema.number().optional(),
+    optionExpirationWarningDays: schema.number().optional(),
+    assignmentRiskMoneyness: schema.number().optional(),
+})
+    .describe('monitorPortfolio inputs beyond the shared portfolio / market / asOf / currencyConversions');
+const PortfolioAnalyzeInputSchema = schema.object({
+    ledger: PortfolioLedgerEnvelopeSchema,
+    asOf: epochMsOrDate.describe('The valuation and monitoring instant'),
+    market: MarketSnapshotSchema,
+    currencyConversions: schema.array(CurrencyPairQuoteSchema).optional(),
+    instrumentClassification: InstrumentClassificationSchema.optional(),
+    marks: schema
+        .array(ValuationMarkSchema)
+        .min(2)
+        .optional()
+        .describe('At least two dated marks, strictly ascending — adds portfolioTimeline when supplied'),
+    monitor: MonitorRequestSchema.optional().describe('Adds monitorPortfolio when supplied'),
+});
+const portfolioAnalyze = defineOperation({
+    id: 'totalfinance.portfolio.analyze',
+    handleFields: ['ledger', 'market'],
+    title: 'Analyze a portfolio (snapshot, timeline, monitor)',
+    description: 'One report of up to three direct results: the valuation snapshot at `asOf` (always), the dated timeline with ' +
+        'P&L since each prior mark and drawdown (when `marks` are supplied), and the policy monitor with its alerts and ' +
+        'carried state (when `monitor` is supplied). Each result is the direct function verbatim; nothing is aggregated ' +
+        'across them, and one `assumptions` says which parts ran and why the others did not.',
+    inputSchema: PortfolioAnalyzeInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            snapshot: { type: 'object', description: 'portfolioSnapshot(...) verbatim' },
+            timeline: {
+                type: ['object', 'null'],
+                description: 'portfolioTimeline(...) verbatim, or null when no marks were supplied',
+            },
+            monitor: {
+                type: ['object', 'null'],
+                description: 'monitorPortfolio(...) verbatim, or null when no monitor request was supplied',
+            },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: ['snapshot', 'timeline', 'monitor', 'assumptions', 'diagnostics'],
+    },
+    costClass: 'medium',
+    run: (input) => {
+        const { ledger } = readPortfolioLedgerSnapshot({ snapshot: input.ledger });
+        const shared = {
+            market: input.market,
+            asOf: input.asOf,
+            ...(input.currencyConversions !== undefined
+                ? { currencyConversions: input.currencyConversions }
+                : {}),
+        };
+        const classification = input.instrumentClassification !== undefined
+            ? { instrumentClassification: input.instrumentClassification }
+            : {};
+        const snapshot = portfolioSnapshot({ portfolio: ledger.state, ...shared });
+        const timeline = input.marks !== undefined
+            ? portfolioTimeline({ ledger, valuationMarks: input.marks, ...classification })
+            : null;
+        const monitor = input.monitor !== undefined
+            ? monitorPortfolio({
+                portfolio: ledger.state,
+                ...shared,
+                ...classification,
+                ...input.monitor,
+            })
+            : null;
+        const warnings = [
+            ...snapshot.diagnostics.warnings,
+            ...(timeline?.diagnostics.warnings ?? []),
+            ...(monitor?.diagnostics.warnings ?? []),
+        ];
+        return {
+            summary: `NAV ${snapshot.netAssetValue.toFixed(2)} ${snapshot.baseCurrency}${timeline ? `; ${timeline.rows.length} marks` : ''}${monitor ? `; ${monitor.alerts.length} alerts` : ''}`,
+            structured: {
+                snapshot,
+                timeline,
+                monitor,
+                assumptions: {
+                    ledger: {
+                        portfolioId: ledger.portfolioId ?? null,
+                        baseCurrency: ledger.baseCurrency,
+                        lotRelief: ledger.lotRelief,
+                        eventCount: ledger.state.eventCount,
+                    },
+                    asOf: snapshot.asOf,
+                    timeline: timeline
+                        ? `portfolioTimeline over ${input.marks.length} marks`
+                        : 'omitted: no marks supplied',
+                    monitor: monitor
+                        ? 'monitorPortfolio under the supplied policy'
+                        : 'omitted: no monitor request supplied',
+                },
+                diagnostics: { warnings },
+            },
+        };
+    },
+});
+// ── Stage 4.7 slice 2 (FC9 Decision 5): the rebalance proposal over the wire ──────────────────
+const RebalanceProposalInputSchema = schema.object({
+    ledger: PortfolioLedgerEnvelopeSchema,
+    asOf: epochMsOrDate.describe('The valuation instant the proposal is sized at'),
+    market: MarketSnapshotSchema,
+    currencyConversions: schema.array(CurrencyPairQuoteSchema).optional(),
+    policy: InvestmentPolicySchema.describe('Targets come from the policy (inline targets or a model)'),
+    instrumentClassification: InstrumentClassificationSchema.optional(),
+    scope: schema
+        .enum(['to-target', 'drift-only'])
+        .describe("'to-target' trades every target to weight; 'drift-only' trades only targets outside their band"),
+    externalFlow: schema
+        .object({ amount: schema.number(), currency: schema.string().nonempty() })
+        .optional()
+        .describe('A contribution (positive) or withdrawal (negative) the proposal sizes around'),
+    tradingAccountId: schema.string().optional(),
+    averageDailyVolumes: schema.record(schema.number()).optional(),
+    lotSizes: schema.record(schema.number()).optional(),
+    defaultLotSize: schema.number().positive().optional(),
+    minimumNotional: schema.number().nonnegative().optional(),
+    transactionCosts: schema
+        .object({
+        commissionPerTrade: schema.number().nonnegative().optional(),
+        commissionPerUnit: schema.number().nonnegative().optional(),
+        spreadBasisPoints: schema.number().nonnegative().optional(),
+        slippageBasisPoints: schema.number().nonnegative().optional(),
+    })
+        .optional(),
+});
+const portfolioRebalanceProposal = defineOperation({
+    id: 'totalfinance.portfolio.rebalance_proposal',
+    title: 'Propose a rebalance (a proposal, never an order)',
+    description: 'Fold the ledger snapshot to its state, mark it from the market snapshot, and propose the trades that take the ' +
+        'portfolio to the policy targets (or only the drifted ones) under the policy limits, lot sizes, minimum notional, ' +
+        'transaction-cost estimates, and an optional external flow. The result is proposePortfolioRebalance(...) verbatim: ' +
+        'weights before and after, the cash summary, the trades with their estimates, the objective, and every target it ' +
+        'could not resolve. Read-only by construction — it returns a proposal and places nothing. Opt-in (portfolioPack).',
+    inputSchema: RebalanceProposalInputSchema,
+    // B6: a proposal is the first step of a trade; proposing is a capability (held by default).
+    requiredCapabilities: ['trade:propose'],
+    outputSchema: {
+        type: 'object',
+        properties: {
+            asOf: { type: 'number' },
+            baseCurrency: { type: 'string' },
+            netAssetValue: { type: 'number' },
+            netAssetValueAfterFlow: { type: 'number' },
+            weights: { type: 'object' },
+            cash: { type: 'object' },
+            trades: { type: 'array', items: { type: 'object' } },
+            estimates: { type: 'object' },
+            objective: { type: 'object' },
+            unresolvedTargets: { type: 'array', items: { type: 'object' } },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'asOf',
+            'baseCurrency',
+            'netAssetValue',
+            'netAssetValueAfterFlow',
+            'weights',
+            'cash',
+            'trades',
+            'estimates',
+            'objective',
+            'unresolvedTargets',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'medium',
+    handleFields: ['ledger', 'market'],
+    run: (input) => {
+        const { ledger: envelope, ...rest } = input;
+        const { ledger } = readPortfolioLedgerSnapshot({ snapshot: envelope });
+        const result = proposePortfolioRebalance({
+            portfolio: ledger.state,
+            ...rest,
+        });
+        return {
+            summary: `${result.trades.length} trade${result.trades.length === 1 ? '' : 's'} proposed on NAV ${result.netAssetValue.toFixed(2)} ${result.baseCurrency} (${input.scope})${result.unresolvedTargets.length > 0 ? `; ${result.unresolvedTargets.length} unresolved target${result.unresolvedTargets.length === 1 ? '' : 's'}` : ''}`,
+            structured: result,
+        };
+    },
+});
+// ── scenarios ─────────────────────────────────────────────────────────────────────────────────
+const TargetTagsSchema = schema.array(schema.string()).optional();
+const SpotTargetSchema = schema.object({
+    kind: schema.literal('spot'),
+    id: schema.string().nonempty(),
+    symbol: schema.string().nonempty(),
+    quantity: schema.number(),
+    currency: schema.string(),
+    strategy: schema.string().optional(),
+    account: schema.string().optional(),
+    book: schema.string().optional(),
+    tags: TargetTagsSchema,
+});
+/** Greeks in the one unit system (the options package's): per unit of the target. */
+const TaylorSensitivitiesSchema = schema.object({
+    delta: schema.number().optional().describe('∂V/∂S per $1 of spot'),
+    gamma: schema.number().optional().describe('∂²V/∂S² per $1²'),
+    vega: schema
+        .number()
+        .optional()
+        .describe('∂V/∂σ per 1 volatility POINT (0.01), as option.greeks reports it'),
+    theta: schema.number().optional().describe('∂V/∂t per CALENDAR DAY, as option.greeks reports it'),
+    rho: schema.number().optional().describe('∂V/∂r per 1% rate (0.01), as option.greeks reports it'),
+    vanna: schema.number().optional().describe('∂Δ/∂σ per 1.00 σ per $'),
+    vomma: schema.number().optional().describe('∂²V/∂σ² per 1.00 σ²'),
+    charm: schema
+        .number()
+        .optional()
+        .describe('∂Δ/∂T per year of time-to-expiry (options-package sign)'),
+    veta: schema.number().optional().describe('∂vega/∂T per year, vega per 1.00 σ'),
+    vera: schema.number().optional().describe('∂²V/∂σ∂r per 1.00 σ per 1.00 rate'),
+    deltaRate: schema.number().optional().describe('∂Δ/∂r per $ per 1% rate'),
+    thetaRate: schema.number().optional().describe('∂Θ/∂r per calendar day per 1% rate'),
+    rhoConvexity: schema.number().optional().describe('∂²V/∂r² per (1%)²'),
+    thetaConvexity: schema.number().optional().describe('∂²V/∂t² per calendar day²'),
+    phi: schema.number().optional().describe('∂V/∂q per 1% dividend yield (dividend rho)'),
+});
+const TaylorFactorLevelSchema = schema.object({ subject: schema.string(), level: schema.number() });
+const TaylorFactorsSchema = schema.object({
+    spot: TaylorFactorLevelSchema.optional(),
+    volatility: TaylorFactorLevelSchema.optional(),
+    riskFreeRate: TaylorFactorLevelSchema.optional(),
+    dividend: TaylorFactorLevelSchema.optional(),
+    valuationInstant: schema.object({ level: schema.number() }).optional(),
+});
+const TaylorTargetSchema = schema.object({
+    kind: schema.literal('taylor'),
+    id: schema.string().nonempty(),
+    quantity: schema.number(),
+    contractMultiplier: schema.number(),
+    currency: schema.string(),
+    underlying: schema.string().optional(),
+    strategy: schema.string().optional(),
+    account: schema.string().optional(),
+    book: schema.string().optional(),
+    tags: TargetTagsSchema,
+    baseValuePerUnit: schema.number(),
+    greeks: TaylorSensitivitiesSchema,
+    factors: TaylorFactorsSchema,
+});
+const TaylorBindingSchema = schema.object({
+    id: schema.string().nonempty(),
+    accountId: schema.string().nonempty(),
+    instrumentId: schema.string().nonempty(),
+    strategy: schema.string().optional(),
+    book: schema.string().optional(),
+    tags: TargetTagsSchema,
+    baseValuePerUnit: schema.number(),
+    greeks: TaylorSensitivitiesSchema,
+    factors: TaylorFactorsSchema,
+});
+const PortfolioTargetSchema = schema.object({
+    kind: schema.literal('portfolio'),
+    portfolio: schema
+        .union([PortfolioLedgerEnvelopeSchema, PortfolioStateSchema])
+        .describe('The ledger envelope or PortfolioState whose open positions become targets'),
+    bindings: schema
+        .array(TaylorBindingSchema)
+        .min(1)
+        .describe('Exactly one Taylor binding per open (accountId, instrumentId) position — the serializable binding kind'),
+});
+const ScenarioRunInputSchema = schema.object({
+    scenarioSet: ScenarioSetSchema,
+    market: MarketSnapshotSchema,
+    targets: schema
+        .array(schema.union([SpotTargetSchema, TaylorTargetSchema, PortfolioTargetSchema]))
+        .min(1)
+        .describe("Wire targets: kind 'spot' (scenarioTarget.spot), 'taylor' (scenarioTarget.taylor), or 'portfolio' (scenarioTargetsFromPortfolio with Taylor bindings). A custom pricer target is SDK-only."),
+    reportingCurrency: schema.string().optional(),
+    currencyConversions: schema.array(CurrencyPairQuoteSchema).optional(),
+    options: schema
+        .object({
+        failureMode: schema.enum(['fail-fast', 'collect']).optional(),
+        seed: schema.number().integer().nonnegative().optional(),
+        maximumValuationCells: schema.number().integer().positive().optional(),
+        maximumWorkUnits: schema.number().integer().positive().optional(),
+    })
+        .optional()
+        .describe('Execution options; market resolvers and factor handlers are SDK-only callbacks'),
+});
+const SCENARIO_RUN_OUTPUT = {
+    type: 'object',
+    properties: {
+        layout: { type: 'object', description: 'scenario-major cell layout and the index formula' },
+        scenarioAxis: { type: 'array', items: { type: 'object' } },
+        targetAxis: { type: 'array', items: { type: 'object' } },
+        base: { type: 'array', items: { type: 'object' } },
+        cells: { type: 'array', items: { type: 'object' } },
+        aggregates: { type: 'object' },
+        assumptions: ASSUMPTIONS_SCHEMA,
+        diagnostics: DIAGNOSTICS_SCHEMA,
+    },
+    required: [
+        'layout',
+        'scenarioAxis',
+        'targetAxis',
+        'base',
+        'cells',
+        'aggregates',
+        'assumptions',
+        'diagnostics',
+    ],
+};
+const scenarioRun = defineOperation({
+    id: 'totalfinance.scenario.run',
+    handleFields: ['scenarioSet', 'market'],
+    title: 'Run a scenario set against targets',
+    description: 'Revalue every target under every scenario of a Gate B scenario set against a Gate B market snapshot: a ' +
+        'scenario-major cell grid with base values, per-cell P&L in local and reporting currency, and per-scenario ' +
+        'aggregates. Targets are the serializable kinds — spot assets, Taylor (greeks) positions, and a portfolio bound ' +
+        'through Taylor bindings. The result is runScenarios(...) verbatim.',
+    inputSchema: ScenarioRunInputSchema,
+    outputSchema: SCENARIO_RUN_OUTPUT,
+    costClass: 'large',
+    run: (input) => {
+        const { scenarioSet } = readScenarioSet({ scenarioSet: input.scenarioSet });
+        const { snapshot } = readMarketSnapshot({ snapshot: input.market });
+        const targets = input.targets.flatMap((target) => {
+            if (target.kind === 'spot') {
+                const { kind: _kind, ...rest } = target;
+                return [scenarioTarget.spot(rest)];
+            }
+            if (target.kind === 'taylor') {
+                const { kind: _kind, ...rest } = target;
+                return [scenarioTarget.taylor(rest)];
+            }
+            const { kind: _kind, portfolio, bindings } = target;
+            return [
+                ...scenarioTargetsFromPortfolio({
+                    state: portfolioStateOf(portfolio),
+                    bindings: bindings.map((binding) => scenarioPortfolioBinding.taylor(binding)),
+                }),
+            ];
+        });
+        const result = runScenarios({
+            scenarioSet,
+            market: snapshot,
+            targets,
+            ...(input.reportingCurrency !== undefined
+                ? { reportingCurrency: input.reportingCurrency }
+                : {}),
+            ...(input.currencyConversions !== undefined
+                ? { currencyConversions: input.currencyConversions }
+                : {}),
+            ...(input.options !== undefined ? { options: input.options } : {}),
+        });
+        return {
+            summary: `${result.layout.scenarioCount} scenarios × ${result.layout.targetCount} targets = ${result.layout.cellCount} cells`,
+            structured: result,
+        };
+    },
+});
+// ── research ──────────────────────────────────────────────────────────────────────────────────
+const FieldDefinitionSchema = schema.object({
+    fieldName: schema.string().nonempty(),
+    kind: schema.enum(['numeric', 'category', 'text', 'boolean']),
+    unit: schema.string().optional(),
+    description: schema.string().optional(),
+});
+const ObservedValueSchema = schema.union([
+    schema.number(),
+    schema.string(),
+    schema.boolean(),
+    schema.null(),
+]);
+const UniverseObservationSchema = schema.object({
+    instrumentId: schema.string().nonempty(),
+    availableTimestampMs: schema.number(),
+    fields: schema
+        .record(ObservedValueSchema)
+        .describe('Declared fields only; null is a stated missing value'),
+});
+const UniverseSchema = {
+    universeId: schema.string().nonempty(),
+    asOf: schema
+        .number()
+        .describe('Epoch ms; the latest observation at or before it is used per instrument'),
+    observations: schema.array(UniverseObservationSchema),
+    fieldDefinitions: schema.array(FieldDefinitionSchema).min(1),
+};
+const MissingValuePolicySchema = schema.enum(['exclude', 'evaluate-as-false']);
+const ScreenInputSchema = schema.object({
+    ...UniverseSchema,
+    filter: schema
+        .record(schema.unknown())
+        .optional()
+        .describe('A ScreenFilter tree — { all: [...] } | { any: [...] } | { not: ... } | { field, operator, value } | ' +
+        "{ field, operator: 'between', from, to } | { field, operator: 'in' | 'notIn', values } | " +
+        "{ field, operator: 'isPresent' | 'isMissing' } — validated node by node by screenUniverse; omitted = every eligible row passes"),
+    missingValuePolicy: MissingValuePolicySchema,
+    orderBy: schema.array(schema.object({
+        field: schema.string(),
+        direction: schema.enum(['ascending', 'descending']),
+    })),
+    limit: schema.number().integer().nonnegative().optional(),
+});
+const RESEARCH_ROWS_OUTPUT = (rowDescription) => ({
+    type: 'object',
+    properties: {
+        assumptions: ASSUMPTIONS_SCHEMA,
+        diagnostics: DIAGNOSTICS_SCHEMA,
+        rows: { type: 'array', items: { type: 'object' }, description: rowDescription },
+    },
+    required: ['assumptions', 'diagnostics', 'rows'],
+});
+const researchScreen = defineOperation({
+    id: 'totalfinance.research.screen',
+    title: 'Screen a universe',
+    description: 'Filter a point-in-time universe of instrument observations with a declarative filter tree, order the survivors, ' +
+        'and optionally limit them — a replayable screen by construction (no caller predicate crosses the wire). ' +
+        'The result is screenUniverse(...) verbatim.',
+    inputSchema: ScreenInputSchema,
+    outputSchema: RESEARCH_ROWS_OUTPUT('{ instrumentId, availableTimestampMs, fields }'),
+    costClass: 'medium',
+    run: (input) => {
+        const observations = capRows(input.observations, 'observations', 'totalfinance.research.screen');
+        const result = screenUniverse({ ...input, observations, filter: input.filter });
+        return {
+            summary: `${result.rows.length} of ${result.diagnostics.suppliedCount} instruments pass (${result.diagnostics.excludedCount} excluded)`,
+            structured: result,
+        };
+    },
+});
+const researchRank = defineOperation({
+    id: 'totalfinance.research.rank',
+    title: 'Rank a universe',
+    description: 'Rank a point-in-time universe by one declared numeric field with an explicit tie policy (competition, dense, ' +
+        'ordinal) and missing-value policy. The result is rankUniverse(...) verbatim.',
+    inputSchema: schema.object({
+        ...UniverseSchema,
+        rankBy: schema.object({
+            field: schema.string(),
+            direction: schema.enum(['ascending', 'descending']),
+        }),
+        tiePolicy: schema.enum(['competition', 'dense', 'ordinal']),
+        missingValuePolicy: MissingValuePolicySchema,
+    }),
+    outputSchema: RESEARCH_ROWS_OUTPUT('{ instrumentId, value, rank }'),
+    costClass: 'medium',
+    run: (input) => {
+        const observations = capRows(input.observations, 'observations', 'totalfinance.research.rank');
+        const result = rankUniverse({ ...input, observations });
+        return {
+            summary: `${result.rows.length} instruments ranked by ${input.rankBy.field} ${input.rankBy.direction}`,
+            structured: result,
+        };
+    },
+});
+const researchScore = defineOperation({
+    id: 'totalfinance.research.score',
+    title: 'Score a universe',
+    description: 'Score a point-in-time universe as a weighted composite of standardized components (z-score or percentile rank, ' +
+        'higher- or lower-is-better) with an explicit missing-value policy. The result is scoreUniverse(...) verbatim.',
+    inputSchema: schema.object({
+        ...UniverseSchema,
+        components: schema
+            .array(schema.object({
+            field: schema.string(),
+            weight: schema.number().positive(),
+            direction: schema.enum(['higher-is-better', 'lower-is-better']),
+            standardization: schema.enum(['z-score', 'percentile-rank']),
+        }))
+            .min(1),
+        missingValuePolicy: schema.enum(['exclude', 'renormalize-weights']),
+    }),
+    outputSchema: RESEARCH_ROWS_OUTPUT('{ instrumentId, score, componentsUsed }'),
+    costClass: 'medium',
+    run: (input) => {
+        const observations = capRows(input.observations, 'observations', 'totalfinance.research.score');
+        const result = scoreUniverse({ ...input, observations });
+        return {
+            summary: `${result.rows.length} instruments scored over ${input.components.length} components`,
+            structured: result,
+        };
+    },
+});
+const TradingSessionWindowSchema = schema.object({
+    startTradingSessionOffset: schema.number().integer(),
+    endTradingSessionOffset: schema.number().integer(),
+});
+const EventStudyInputSchema = schema.object({
+    events: schema.array(schema.object({
+        eventId: schema.string().nonempty(),
+        instrumentId: schema.string().nonempty(),
+        eventType: schema.string(),
+        announcedTimestampMs: schema.number(),
+        effectiveTimestampMs: schema.number().optional(),
+        metadata: schema.record(schema.unknown()).optional(),
+    })),
+    returnObservations: schema.array(schema.object({
+        instrumentId: schema.string().nonempty(),
+        tradingSessionDate: schema.string().date(),
+        simpleReturn: schema.number(),
+    })),
+    marketReturns: schema
+        .array(schema.object({ tradingSessionDate: schema.string().date(), simpleReturn: schema.number() }))
+        .optional()
+        .describe("Required by the 'market-adjusted' and 'market' models"),
+    eventWindow: TradingSessionWindowSchema,
+    estimationWindow: TradingSessionWindowSchema.optional().describe("Required by 'mean-adjusted' and 'market'; must end strictly before the event window starts"),
+    expectedReturnModel: schema
+        .union([
+        schema.object({ model: schema.literal('mean-adjusted') }),
+        schema.object({ model: schema.literal('market-adjusted') }),
+        schema.object({ model: schema.literal('market') }),
+    ])
+        .describe("The serializable models; a 'custom' expected-return function is SDK-only"),
+    sessionPolicy: schema.enum(['announcement-session', 'next-session']).optional(),
+    overlappingEventPolicy: schema.enum(['reject', 'allow-contaminated']),
+    cumulativeConvention: schema.enum(['sum', 'compound']).optional(),
+});
+const researchEventStudy = defineOperation({
+    id: 'totalfinance.research.event_study',
+    title: 'Run an event study',
+    description: 'Measure abnormal returns around dated events under a declared expected-return model (mean-adjusted, ' +
+        'market-adjusted, or market model), with explicit session, overlap, and cumulation policies; per-event rows and ' +
+        'cumulative abnormal returns, and the average abnormal return by offset with t-statistics. ' +
+        'The result is eventStudy(...) verbatim.',
+    inputSchema: EventStudyInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+            events: { type: 'array', items: { type: 'object' } },
+            averageAbnormalReturns: { type: 'array', items: { type: 'object' } },
+        },
+        required: ['assumptions', 'diagnostics', 'events', 'averageAbnormalReturns'],
+    },
+    costClass: 'medium',
+    run: (input) => {
+        const id = 'totalfinance.research.event_study';
+        const result = eventStudy({
+            ...input,
+            events: capRows(input.events, 'events', id),
+            returnObservations: capRows(input.returnObservations, 'returnObservations', id),
+            ...(input.marketReturns !== undefined
+                ? { marketReturns: capRows(input.marketReturns, 'marketReturns', id) }
+                : {}),
+        });
+        return {
+            summary: `${result.diagnostics.eventsIncluded} of ${result.diagnostics.eventsSupplied} events studied under ${result.assumptions.expectedReturnModel}`,
+            structured: result,
+        };
+    },
+});
+// ── options backtest (opt-in backtest pack) ───────────────────────────────────────────────────
+// B7: a chain row is the core `OptionQuote`; its Greeks ride `greeks` (vendor-supplied or from
+// `options.chainGreeks`), never a bare `delta` beside the row.
+const ChainQuoteSchema = OptionQuoteSchema;
+const ChainSnapshotSchema = schema.object({
+    asOf: epochMsOrDate,
+    underlyingPrice: schema.number().positive(),
+    quotes: schema.array(ChainQuoteSchema),
+});
+const CostModelSchema = schema
+    .union([
+    schema.object({ model: schema.literal('none') }),
+    schema.object({ model: schema.literal('bps'), bps: schema.number().nonnegative() }),
+    schema.object({
+        model: schema.literal('perShare'),
+        amountPerShare: schema.number().nonnegative(),
+    }),
+    schema.object({ model: schema.literal('fixed'), amount: schema.number().nonnegative() }),
+])
+    .describe('A declarative commission model (fees.none / bps / perShare / fixed)');
+const SlippageModelSchema = schema
+    .union([
+    schema.object({ model: schema.literal('none') }),
+    schema.object({ model: schema.literal('bps'), bps: schema.number().nonnegative() }),
+    schema.object({ model: schema.literal('fixed'), perShare: schema.number().nonnegative() }),
+    schema.object({ model: schema.literal('spread'), spread: schema.number().nonnegative() }),
+])
+    .describe('A declarative slippage model (slippage.none / bps / fixed / spread)');
+function costModelOf(wire) {
+    switch (wire.model) {
+        case 'none':
+            return fees.none();
+        case 'bps':
+            return fees.bps(wire.bps);
+        case 'perShare':
+            return fees.perShare(wire.amountPerShare);
+        case 'fixed':
+            return fees.fixed(wire.amount);
+    }
+}
+function slippageModelOf(wire) {
+    switch (wire.model) {
+        case 'none':
+            return slippage.none();
+        case 'bps':
+            return slippage.bps(wire.bps);
+        case 'fixed':
+            return slippage.fixed(wire.perShare);
+        case 'spread':
+            return slippage.spread(wire.spread);
+    }
+}
+const EntryCommon = {
+    id: schema.string().nonempty().optional().describe('Names the rule in trades and rows'),
+    when: schema
+        .enum(['flat', 'always'])
+        .optional()
+        .describe("'flat' (default) enters only when no position is open; a caller predicate is SDK-only"),
+    daysToExpiry: schema.object({
+        target: schema.number(),
+        min: schema.number().optional(),
+        max: schema.number().optional(),
+    }),
+    sizing: schema
+        .union([
+        schema.object({ quantity: schema.number().positive() }),
+        schema.object({ maxMarginFraction: schema.number().positive() }),
+    ])
+        .optional()
+        .describe('Default { quantity: 1 }'),
+    price: schema.enum(['bid', 'ask', 'mid', 'last', 'mark']).optional(),
+};
+const EntryRuleSchema = schema
+    .union([
+    schema.object({
+        ...EntryCommon,
+        structure: schema.literal('ironCondor'),
+        select: schema.object({ shortDelta: schema.number(), wingWidth: schema.number() }),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.enum([
+            'bullCallSpread',
+            'bearCallSpread',
+            'bullPutSpread',
+            'bearPutSpread',
+        ]),
+        select: schema.object({ shortDelta: schema.number(), width: schema.number() }),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.literal('strangle'),
+        select: schema.object({ shortDelta: schema.number() }),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.literal('straddle'),
+        select: schema.object({ strike: schema.number().optional() }).optional(),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.literal('coveredCall'),
+        select: schema.object({
+            shortDelta: schema.number(),
+            stockPrice: schema.number().optional(),
+        }),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.literal('protectivePut'),
+        select: schema.object({
+            shortDelta: schema.number(),
+            stockPrice: schema.number().optional(),
+        }),
+    }),
+    schema.object({
+        ...EntryCommon,
+        structure: schema.enum([
+            'calendarCallSpread',
+            'calendarPutSpread',
+            'diagonalCallSpread',
+            'diagonalPutSpread',
+            'doubleDiagonal',
+        ]),
+        select: schema.object({
+            shortDelta: schema.number(),
+            nearDaysToExpiry: schema.object({
+                target: schema.number(),
+                min: schema.number().optional(),
+                max: schema.number().optional(),
+            }),
+            farDaysToExpiry: schema.object({
+                target: schema.number(),
+                min: schema.number().optional(),
+                max: schema.number().optional(),
+            }),
+            width: schema.number().positive().optional(),
+        }),
+    }),
+])
+    .describe('The declarative entry structures; a `build` callback is SDK-only');
+const ExitTriggersSchema = schema.object({
+    profitTarget: schema.number().optional().describe('Fraction of entry premium, e.g. 0.5'),
+    stopLoss: schema.number().optional().describe('Multiple of entry premium, e.g. 2'),
+    daysToExpiry: schema.number().optional().describe('Close at or below this DTE'),
+});
+const OptionsBacktestInputSchema = schema.object({
+    chains: schema
+        .array(ChainSnapshotSchema)
+        .describe('Chain snapshots (any order; the engine sorts)'),
+    marking: schema
+        .object({
+        volatility: schema.enum(['current-quote', 'entry']).optional(),
+        missingMark: schema
+            .enum(['refuse', 'entry-volatility', 'carry-last-volatility'])
+            .optional(),
+        maximumQuoteAgeMs: schema.number().nonnegative().optional(),
+    })
+        .optional()
+        .describe('Default: re-mark from the current quote; refuse a missing mark'),
+    initialCapital: schema.number().positive().optional().describe('Default 100,000'),
+    riskFreeRate: schema
+        .number()
+        .describe('Continuously-compounded risk-free rate (decimal, e.g. 0.045) pricing every mark — REQUIRED; the engine never assumes a rate'),
+    dividendYield: schema.number().optional().describe('Default 0'),
+    entry: EntryRuleSchema.optional().describe('One rule; exactly one of entry and rules'),
+    rules: schema
+        .array(EntryRuleSchema)
+        .min(1)
+        .optional()
+        .describe('Several rules, each a member of the book; exactly one of entry and rules'),
+    exit: ExitTriggersSchema.describe('A `when` predicate is SDK-only'),
+    roll: schema.object({ when: ExitTriggersSchema.optional() }).optional(),
+    hedge: schema
+        .object({
+        deltaBand: schema.number().positive(),
+        commission: CostModelSchema.optional(),
+        slippage: SlippageModelSchema.optional(),
+    })
+        .optional(),
+    commission: CostModelSchema.optional(),
+    slippage: SlippageModelSchema.optional(),
+    assignment: schema.enum(['model', 'none']).optional(),
+    periodsPerYear: schema.number().positive().optional().describe('Default 252'),
+    book: schema
+        .object({
+        maximumOpenPositions: schema.number().integer().positive().optional(),
+        maximumPerUnderlying: schema.number().integer().positive().optional(),
+    })
+        .optional()
+        .describe('Default: one open trade'),
+    limits: schema
+        .object({
+        maximumMarginFraction: schema.number().positive().optional(),
+        maximumNetDelta: schema.number().nonnegative().optional(),
+        maximumNetVega: schema.number().nonnegative().optional(),
+        maximumConcentration: schema.number().positive().optional(),
+        scenarioLoss: schema
+            .object({
+            spotShocks: schema.array(schema.number()).min(1),
+            volatilityShocks: schema.array(schema.number()).min(1),
+            maximumLossFraction: schema.number().positive(),
+        })
+            .optional(),
+    })
+        .optional()
+        .describe('Pre-trade limits on the post-trade book; a breach is a limitRejections row'),
+    fillPolicy: schema
+        .object({
+        mode: schema.enum(['combo', 'legged']).optional(),
+        partialFill: schema.enum(['reject', 'allow']).optional(),
+        price: schema.enum(['bid', 'ask', 'mid', 'last', 'mark']).optional(),
+    })
+        .optional(),
+    quoteFreshness: schema.object({ maximumQuoteAgeMs: schema.number().nonnegative() }).optional(),
+    corporateActions: schema
+        .array(schema.object({
+        symbol: schema.string().nonempty(),
+        effectiveDate: schema.string().date(),
+        type: schema.enum([
+            'split',
+            'reverseSplit',
+            'dividend',
+            'symbolChange',
+            'merger',
+            'spinoff',
+            'other',
+        ]),
+        ratio: schema.number().positive().optional(),
+        cash: schema.number().optional(),
+        newSymbol: schema.string().optional(),
+        details: schema.record(schema.unknown()).optional(),
+    }))
+        .optional(),
+    dividends: schema
+        .array(schema.object({
+        underlying: schema.string().nonempty(),
+        exDate: schema.string().date(),
+        amount: schema.number().positive(),
+    }))
+        .optional(),
+    baseCurrency: schema.string().nonempty().optional().describe("Default 'USD'"),
+});
+const backtestOptionsRun = defineOperation({
+    id: 'totalfinance.backtest.options_run',
+    title: 'Run an options backtest',
+    description: 'Backtest a declarative options strategy over chain snapshots: structure selection by delta and DTE, exit and roll ' +
+        'triggers, optional delta hedging, declarative commission and slippage, American assignment modelling, and the ' +
+        'marking policy (current-quote or entry volatility; what a missing mark does). Several rules may hold several trades ' +
+        'at once (book), pre-trade limits reject entries with rows, combo or legged fills, quote freshness, split lineage, ' +
+        'dividend evidence, the surface summary, and the portfolio ledger the equity reconciles to. Equity points, trades ' +
+        'with per-leg attribution and mark counts, settlements, and the standard performance summary. The result is ' +
+        'optionsBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set.',
+    inputSchema: OptionsBacktestInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            points: { type: 'array', items: { type: 'object' } },
+            returns: { type: 'array', items: { type: 'number' } },
+            trades: { type: 'array', items: { type: 'object' } },
+            settlements: { type: 'array', items: { type: 'object' } },
+            finalValue: { type: 'number' },
+            performance: { type: 'object', description: 'The standard performance summary' },
+            limitRejections: { type: 'array', items: { type: 'object' } },
+            fillRejections: { type: 'array', items: { type: 'object' } },
+            surface: { type: 'array', items: { type: 'object' } },
+            ledger: { type: 'object', description: 'The portfolio ledger snapshot (events)' },
+            timeline: {
+                type: ['object', 'null'],
+                description: 'The ledger timeline (null under two marks)',
+            },
+            runId: { type: 'string' },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'points',
+            'returns',
+            'trades',
+            'settlements',
+            'finalValue',
+            'performance',
+            'limitRejections',
+            'fillRejections',
+            'surface',
+            'ledger',
+            'timeline',
+            'runId',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'job',
+    run: (input) => {
+        const id = 'totalfinance.backtest.options_run';
+        const { chains, commission, slippage: slip, hedge, ...rest } = input;
+        const result = optionsBacktest({
+            ...rest,
+            chains: capRows(chains, 'chains', id),
+            ...(commission !== undefined ? { commission: costModelOf(commission) } : {}),
+            ...(slip !== undefined ? { slippage: slippageModelOf(slip) } : {}),
+            ...(hedge !== undefined
+                ? {
+                    hedge: {
+                        deltaBand: hedge.deltaBand,
+                        ...(hedge.commission !== undefined
+                            ? { commission: costModelOf(hedge.commission) }
+                            : {}),
+                        ...(hedge.slippage !== undefined
+                            ? { slippage: slippageModelOf(hedge.slippage) }
+                            : {}),
+                    },
+                }
+                : {}),
+        });
+        return {
+            summary: `${result.trades.length} trades, final value ${result.finalValue.toFixed(2)} (${result.assumptions.marking.volatility} marking)`,
+            structured: result,
+        };
+    },
+});
+// ── packs ─────────────────────────────────────────────────────────────────────────────────────
+export function portfolioPack() {
+    return {
+        name: 'portfolio',
+        operations: [
+            portfolioSnapshotOperation,
+            portfolioExplainPnl,
+            portfolioAnalyze,
+            portfolioRebalanceProposal,
+        ],
+    };
+}
+export function scenarioPack() {
+    return { name: 'scenario', operations: [scenarioRun] };
+}
+export function researchPack() {
+    return {
+        name: 'research',
+        operations: [researchScreen, researchRank, researchScore, researchEventStudy],
+    };
+}
+export function artifactPack() {
+    return { name: 'artifact', operations: [artifactRead, artifactCompare] };
+}
+// ── Stage 4.6 slice 3 (FC8 Decision 11): the cross-sectional backtest over the wire ─────────────
+const ReturnObservationSchema = schema.object({
+    instrumentId: schema.string().nonempty(),
+    tradingSessionDate: schema.string().date(),
+    simpleReturn: schema.number(),
+});
+const UniverseMemberSchema = schema.object({
+    instrumentId: schema.string().nonempty(),
+    fromTimestampMs: schema.number(),
+    toTimestampMs: schema.number().optional(),
+    exitReason: schema.enum(['removed', 'delisted', 'merged', 'other']).optional(),
+    delistingReturn: schema.number().optional(),
+});
+const ScoreComponentSchema = schema.object({
+    field: schema.string(),
+    weight: schema.number().positive(),
+    direction: schema.enum(['higher-is-better', 'lower-is-better']),
+    standardization: schema.enum(['z-score', 'percentile-rank']),
+});
+const FactorRecipeSchema = schema
+    .object({
+    recipeName: schema.string().nonempty(),
+    recipeVersion: schema.number().integer().positive(),
+    disclosure: schema.string(),
+    direction: schema.enum(['higher-is-better', 'lower-is-better']),
+    features: schema
+        .array(schema.object({
+        field: schema.string().nonempty(),
+        transform: schema.enum(['raw', 'winsorize-then-z-score', 'percentile-rank']),
+        weight: schema.number(),
+    }))
+        .min(1),
+    lagTradingSessions: schema.number().integer().nonnegative(),
+    neutralization: schema.enum(['none', 'sector', 'sector-and-size']),
+    missingValuePolicy: schema.enum(['exclude', 'renormalize-weights']),
+})
+    .describe('A versioned research FactorRecipe (canonical or caller-authored), validated by the engine');
+const CrossSectionalSignalSchema = schema
+    .union([
+    schema.object({ factorRecipe: FactorRecipeSchema }),
+    schema.object({
+        score: schema.object({
+            components: schema.array(ScoreComponentSchema).min(1),
+            missingValuePolicy: schema.enum(['exclude', 'renormalize-weights']),
+        }),
+    }),
+    schema.object({
+        screen: schema.object({
+            filter: schema.record(schema.unknown()).optional(),
+            orderBy: schema
+                .array(schema.object({
+                field: schema.string(),
+                direction: schema.enum(['ascending', 'descending']),
+            }))
+                .min(1),
+            missingValuePolicy: MissingValuePolicySchema,
+        }),
+    }),
+])
+    .describe('The three declarative signal forms; a signal callback is SDK-only');
+const SideSelectionSchema = schema.union([
+    schema.object({ topQuantile: schema.number().positive() }),
+    schema.object({ count: schema.number().integer().positive() }),
+    schema.object({ fraction: schema.number().positive() }),
+]);
+const ShortSideSelectionSchema = schema.union([
+    schema.object({ bottomQuantile: schema.number().positive() }),
+    schema.object({ count: schema.number().integer().positive() }),
+    schema.object({ fraction: schema.number().positive() }),
+]);
+const PortfolioConstructionSchema = schema.object({
+    method: schema
+        .enum(['equal-weight', 'score-weight', 'inverse-volatility', 'risk-budget'])
+        .describe("'supplied-weights' takes a caller function and is SDK-only"),
+    long: SideSelectionSchema,
+    short: ShortSideSelectionSchema.optional(),
+    neutrality: schema.enum(['none', 'dollar', 'sector', 'beta', 'factor']).optional(),
+    neutralizeAgainst: schema.object({ field: schema.string().nonempty() }).optional(),
+    maximumPositions: schema.number().integer().positive().optional(),
+    maximumPositionWeight: schema.number().positive().optional(),
+    minimumPositionWeight: schema.number().nonnegative().optional(),
+    maximumTurnover: schema.number().nonnegative().optional(),
+    maximumParticipation: schema.number().positive().optional(),
+    volatilityLookbackSessions: schema.number().integer().positive().optional(),
+});
+const DeclaredExecutionSchema = schema
+    .object({
+    label: schema.string().nonempty(),
+    ambiguity: schema
+        .enum(['optimistic', 'pessimistic', 'deterministic-path', 'reject'])
+        .optional(),
+    costs: schema
+        .object({
+        commission: CostModelSchema.optional(),
+        slippage: SlippageModelSchema.optional(),
+        spread: schema
+            .union([
+            schema.object({ model: schema.literal('none') }),
+            schema.object({
+                model: schema.literal('halfSpreadBps'),
+                bps: schema.number().nonnegative(),
+            }),
+        ])
+            .optional(),
+        marketImpact: schema
+            .union([
+            schema.object({ model: schema.literal('none') }),
+            schema.object({
+                model: schema.literal('squareRoot'),
+                coefficient: schema.number().nonnegative(),
+            }),
+        ])
+            .optional(),
+        latencySessions: schema.number().integer().nonnegative().optional(),
+        participation: schema.number().positive().optional(),
+    })
+        .optional(),
+    partialFills: schema.enum(['allow', 'reject']).optional(),
+    timeInForce: schema
+        .object({
+        default: schema.enum(['day', 'gtc']),
+        expireAtSessionClose: schema.boolean(),
+    })
+        .optional(),
+    margin: schema
+        .object({
+        buyingPowerMultiplier: schema.number().positive(),
+        initialMarginRate: schema.number().nonnegative(),
+        maintenanceMarginRate: schema.number().nonnegative(),
+        forcedLiquidation: schema.enum(['none', 'close-largest-loss', 'pro-rata']),
+    })
+        .optional(),
+})
+    .describe("A declared execution policy over session bars (execution.declared): the label is the caller's claim; " +
+    'a caller fill model, session rules, and quote/order-book observations are SDK-only');
+function executionPolicyOf(wire) {
+    const costs = wire.costs;
+    return execution.declared({
+        label: wire.label,
+        ...(wire.ambiguity !== undefined ? { ambiguity: wire.ambiguity } : {}),
+        ...(costs !== undefined
+            ? {
+                costs: {
+                    ...(costs.commission !== undefined
+                        ? { commission: costModelOf(costs.commission) }
+                        : {}),
+                    ...(costs.slippage !== undefined ? { slippage: slippageModelOf(costs.slippage) } : {}),
+                    ...(costs.spread !== undefined
+                        ? {
+                            spread: costs.spread.model === 'none'
+                                ? spreadModels.none()
+                                : spreadModels.halfSpreadBps(costs.spread.bps),
+                        }
+                        : {}),
+                    ...(costs.marketImpact !== undefined
+                        ? {
+                            marketImpact: costs.marketImpact.model === 'none'
+                                ? impactModels.none()
+                                : impactModels.squareRoot({ coefficient: costs.marketImpact.coefficient }),
+                        }
+                        : {}),
+                    ...(costs.latencySessions !== undefined
+                        ? { latency: latencyModels.sessions(costs.latencySessions) }
+                        : {}),
+                    ...(costs.participation !== undefined ? { participation: costs.participation } : {}),
+                },
+            }
+            : {}),
+        ...(wire.partialFills !== undefined ? { partialFills: wire.partialFills } : {}),
+        ...(wire.timeInForce !== undefined ? { timeInForce: wire.timeInForce } : {}),
+        ...(wire.margin !== undefined ? { margin: wire.margin } : {}),
+    });
+}
+const CrossSectionalRunInputSchema = schema.object({
+    dataset: schema.object({
+        observations: schema.array(UniverseObservationSchema),
+        fieldDefinitions: schema.array(FieldDefinitionSchema).min(1),
+        returns: schema
+            .array(ReturnObservationSchema)
+            .describe('Per instrument per session; prices are return-index levels (base 100)'),
+        benchmarkReturns: schema.array(ReturnObservationSchema).optional(),
+        groups: schema.record(schema.string()).optional(),
+        sizeField: schema.string().optional(),
+        classification: schema.record(schema.record(schema.unknown())).optional(),
+        averageDailyVolumes: schema.record(schema.number()).optional(),
+        betas: schema.record(schema.number()).optional(),
+    }),
+    universeHistory: schema.object({
+        universeId: schema.string().nonempty(),
+        members: schema.array(UniverseMemberSchema).min(1),
+    }),
+    signal: CrossSectionalSignalSchema,
+    rebalanceSchedule: schema.object({
+        frequency: schema.enum(['daily', 'weekly', 'monthly', 'quarterly']),
+        session: schema.enum(['open', 'close']),
+        bufferBand: schema.number().nonnegative().optional(),
+    }),
+    portfolioConstruction: PortfolioConstructionSchema,
+    execution: DeclaredExecutionSchema.optional().describe('Default: execution.simplified()'),
+    transactionCostModel: schema
+        .object({ commission: CostModelSchema.optional(), slippage: SlippageModelSchema.optional() })
+        .optional(),
+    initialCapital: schema.number().positive().optional().describe('Default 1,000,000'),
+    baseCurrency: schema.string().nonempty().optional().describe("Default 'USD'"),
+    window: schema
+        .object({
+        fromTimestampMs: schema.number().optional(),
+        toTimestampMs: schema.number().optional(),
+    })
+        .optional(),
+    periodsPerYear: schema.number().positive().optional().describe('Default 252'),
+    riskFreeRate: schema.number().optional().describe('Per-period; default 0'),
+    seed: schema
+        .number()
+        .integer()
+        .nonnegative()
+        .optional()
+        .describe('Seeds only the bootstrap confidence intervals; absent = none'),
+});
+const backtestCrossSectionalRun = defineOperation({
+    id: 'totalfinance.backtest.cross_sectional_run',
+    title: 'Run a cross-sectional backtest',
+    description: 'Backtest a point-in-time cross-sectional strategy: a returns dataset with declared features, a universe history ' +
+        'with entries and exits, one declarative signal (a versioned factor recipe, a composite score, or a screen), a ' +
+        'rebalance schedule, and a portfolio construction (quantile/count/fraction selection on each side; equal, score, ' +
+        'inverse-volatility, or risk-budget weights; dollar/sector/beta/factor neutrality; position, weight, turnover, and ' +
+        'participation caps — every trim a reported goal). Fills go through the execution policy into the portfolio ' +
+        'ledger; the final value reconciles to the ledger NAV. Rebalances, holdings, fills, the ledger, the timeline, ' +
+        'attribution, the benchmark block, and the performance summary — crossSectionalBacktest(...) verbatim. Opt-in ' +
+        '(backtestPack): payloads and runtime are heavier than the default set; bulk row sets above the row cap travel by handle.',
+    inputSchema: CrossSectionalRunInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            rebalances: { type: 'array', items: { type: 'object' } },
+            holdings: { type: 'array', items: { type: 'object' } },
+            points: { type: 'array', items: { type: 'object' } },
+            returns: { type: 'array', items: { type: 'number' } },
+            trades: { type: 'array', items: { type: 'object' } },
+            fills: { type: 'array', items: { type: 'object' } },
+            ledger: { type: 'object', description: 'The portfolio ledger snapshot (events)' },
+            timeline: { type: 'object', description: 'The ledger timeline' },
+            attribution: { type: 'object' },
+            benchmark: { type: ['object', 'null'] },
+            performance: { type: 'object', description: 'The standard performance summary' },
+            performanceConfidence: { type: ['object', 'null'] },
+            finalValue: { type: 'number' },
+            runId: { type: 'string' },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'rebalances',
+            'holdings',
+            'points',
+            'returns',
+            'trades',
+            'fills',
+            'ledger',
+            'timeline',
+            'attribution',
+            'benchmark',
+            'performance',
+            'performanceConfidence',
+            'finalValue',
+            'runId',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'job',
+    handleFields: ['dataset'],
+    run: (input) => {
+        const id = 'totalfinance.backtest.cross_sectional_run';
+        const { dataset, universeHistory, execution: executionWire, transactionCostModel, ...rest } = input;
+        const result = crossSectionalBacktest({
+            ...rest,
+            dataset: {
+                ...dataset,
+                observations: capRows(dataset.observations, 'dataset.observations', id),
+                returns: capRows(dataset.returns, 'dataset.returns', id),
+                ...(dataset.benchmarkReturns !== undefined
+                    ? {
+                        benchmarkReturns: capRows(dataset.benchmarkReturns, 'dataset.benchmarkReturns', id),
+                    }
+                    : {}),
+            },
+            universeHistory: {
+                ...universeHistory,
+                members: capRows(universeHistory.members, 'universeHistory.members', id),
+            },
+            ...(executionWire !== undefined ? { execution: executionPolicyOf(executionWire) } : {}),
+            ...(transactionCostModel !== undefined
+                ? {
+                    transactionCostModel: {
+                        ...(transactionCostModel.commission !== undefined
+                            ? { commission: costModelOf(transactionCostModel.commission) }
+                            : {}),
+                        ...(transactionCostModel.slippage !== undefined
+                            ? { slippage: slippageModelOf(transactionCostModel.slippage) }
+                            : {}),
+                    },
+                }
+                : {}),
+        });
+        return {
+            summary: `${result.diagnostics.rebalanceCount} rebalances over ${result.diagnostics.sessionCount} sessions, final value ${result.finalValue.toFixed(2)} (${result.assumptions.execution.realism} execution)`,
+            structured: result,
+        };
+    },
+});
+// ── Stage 4.6 slice 6 (FC8 Decision 11): the portfolio backtest over the wire ──────────────────
+const BarSchema = schema.object({
+    symbol: schema.string().nonempty(),
+    timestampMs: schema.number(),
+    open: schema.number(),
+    high: schema.number(),
+    low: schema.number(),
+    close: schema.number(),
+    volume: schema.number().optional(),
+    vwap: schema.number().optional(),
+    adjusted: schema.boolean().optional(),
+});
+const QuoteSchema = schema.object({
+    symbol: schema.string().nonempty(),
+    timestampMs: schema.number(),
+    bid: schema.number(),
+    ask: schema.number(),
+    bidSize: schema.number().optional(),
+    askSize: schema.number().optional(),
+    exchange: schema.string().optional(),
+    conditions: schema.array(schema.string()).optional(),
+});
+const TradeRowSchema = schema.object({
+    symbol: schema.string().nonempty(),
+    timestampMs: schema.number(),
+    price: schema.number(),
+    size: schema.number(),
+    exchange: schema.string().optional(),
+    conditions: schema.array(schema.string()).optional(),
+    sequence: schema.number().optional(),
+});
+const OrderBookSchema = schema.object({
+    symbol: schema.string().nonempty(),
+    timestampMs: schema.number(),
+    bids: schema.array(schema.object({
+        price: schema.number(),
+        size: schema.number(),
+        exchange: schema.string().optional(),
+    })),
+    asks: schema.array(schema.object({
+        price: schema.number(),
+        size: schema.number(),
+        exchange: schema.string().optional(),
+    })),
+});
+const ContractTermsSchema = schema.union([
+    schema.object({
+        kind: schema.literal('option'),
+        underlyingInstrumentId: schema.string().nonempty(),
+        right: schema.enum(['call', 'put']),
+        strikePricePerUnit: schema.number().positive(),
+        expiryTimestampMs: schema.number(),
+    }),
+    schema.object({
+        kind: schema.literal('future'),
+        underlyingInstrumentId: schema.string().nonempty(),
+        expiryTimestampMs: schema.number(),
+    }),
+    schema.object({
+        kind: schema.literal('perpetual'),
+        underlyingInstrumentId: schema.string().nonempty(),
+    }),
+]);
+const InstrumentSpecificationSchema = schema
+    .object({
+    kind: schema
+        .enum([
+        'equity',
+        'etf',
+        'option',
+        'future',
+        'fx-forward',
+        'crypto-spot',
+        'crypto-perpetual',
+        'bond',
+    ])
+        .describe("A built-in kind; 'custom' brings its own adapter and is SDK-only"),
+    currency: schema.string().nonempty(),
+    contractMultiplier: schema.number().positive().optional(),
+    contract: ContractTermsSchema.optional(),
+    assetClass: schema
+        .enum([
+        'equity',
+        'etf',
+        'option',
+        'future',
+        'fx-forward',
+        'crypto-spot',
+        'crypto-perpetual',
+        'bond',
+        'cash',
+    ])
+        .optional(),
+    classification: schema
+        .object({
+        underlying: schema.string().optional(),
+        assetClass: schema.string().optional(),
+        strategy: schema.string().optional(),
+        tags: schema.array(schema.string()).optional(),
+    })
+        .optional(),
+    roll: schema
+        .object({
+        toInstrumentId: schema.string().nonempty(),
+        sessionsBeforeExpiry: schema.number().integer().nonnegative(),
+    })
+        .optional(),
+    coupon: schema
+        .object({
+        annualRate: schema.number(),
+        paymentsPerYear: schema.number().integer().positive(),
+        faceValuePerUnit: schema.number().positive().optional(),
+        dayCount: schema.enum(['ACT/365F', '30/360']).optional(),
+        issueDate: schema.string().date(),
+        maturityDate: schema.string().date(),
+    })
+        .optional(),
+    forward: schema
+        .object({
+        maturityTimestampMs: schema.number(),
+        baseCurrency: schema.string().nonempty(),
+        quoteCurrency: schema.string().nonempty(),
+        contractRate: schema.number().positive(),
+    })
+        .optional(),
+})
+    .describe('An instrument specification; the terms each kind needs are validated by the engine');
+const PortfolioAccountingSchema = schema.object({
+    baseCurrency: schema.string().nonempty(),
+    initialCash: schema
+        .array(schema.object({ currency: schema.string().nonempty(), amount: schema.number().positive() }))
+        .min(1),
+    lotRelief: schema.enum(['fifo', 'lifo', 'highest-cost', 'specific-lot']).optional(),
+    settlement: schema.record(schema.enum(['T+0', 'T+1', 'T+2'])).optional(),
+});
+const PortfolioMarketDataSchema = schema.object({
+    bars: schema.array(BarSchema).optional(),
+    quotes: schema.array(QuoteSchema).optional(),
+    trades: schema.array(TradeRowSchema).optional(),
+    orderBooks: schema.array(OrderBookSchema).optional(),
+    optionChains: schema.array(ChainSnapshotSchema).optional(),
+    fxRates: schema
+        .array(schema.object({
+        timestampMs: schema.number(),
+        baseCurrency: schema.string().nonempty(),
+        quoteCurrency: schema.string().nonempty(),
+        quotePerBase: schema.number().positive(),
+    }))
+        .optional(),
+    forwardRates: schema
+        .array(schema.object({
+        instrumentId: schema.string().nonempty(),
+        timestampMs: schema.number(),
+        forwardRate: schema.number().positive(),
+    }))
+        .optional(),
+    fundingRates: schema
+        .array(schema.object({
+        instrumentId: schema.string().nonempty(),
+        timestampMs: schema.number(),
+        fundingRate: schema.number(),
+    }))
+        .optional(),
+    corporateActions: schema
+        .array(schema.object({
+        symbol: schema.string().nonempty(),
+        effectiveDate: schema.string().date(),
+        type: schema.enum([
+            'split',
+            'reverseSplit',
+            'dividend',
+            'symbolChange',
+            'merger',
+            'spinoff',
+            'other',
+        ]),
+        ratio: schema.number().positive().optional(),
+        cash: schema.number().optional(),
+        newSymbol: schema.string().optional(),
+        details: schema.record(schema.unknown()).optional(),
+    }))
+        .optional(),
+    dividends: schema
+        .array(schema.object({
+        instrumentId: schema.string().nonempty(),
+        exDate: schema.string().date(),
+        amount: schema.number().positive(),
+        payDate: schema.string().date().optional(),
+    }))
+        .optional(),
+    coupons: schema
+        .array(schema.object({
+        instrumentId: schema.string().nonempty(),
+        paymentDate: schema.string().date(),
+        amountPerUnit: schema.number().positive(),
+    }))
+        .optional(),
+});
+const ExternalFlowsSchema = schema
+    .array(schema.object({
+    timestampMs: schema.number(),
+    amount: schema.number(),
+    currency: schema.string().nonempty(),
+}))
+    .optional();
+const PortfolioCalendarSchema = schema.enum(['NYSE', 'CBOE', 'ALWAYS_OPEN']).optional();
+const BacktestWindowSchema = schema
+    .object({
+    fromTimestampMs: schema.number().optional(),
+    toTimestampMs: schema.number().optional(),
+})
+    .optional();
+const PortfolioRunInputSchema = schema.object({
+    accounting: PortfolioAccountingSchema,
+    instruments: schema.record(InstrumentSpecificationSchema),
+    marketData: PortfolioMarketDataSchema,
+    strategy: schema
+        .object({
+        model: schema.union([
+            schema.record(schema.unknown()).describe('A ModelPortfolio artifact'),
+            schema.array(AllocationTargetSchema).min(1),
+        ]),
+        schedule: schema.object({
+            frequency: schema.enum(['daily', 'weekly', 'monthly', 'quarterly']),
+        }),
+        policy: schema
+            .record(schema.unknown())
+            .optional()
+            .describe('An InvestmentPolicy (limits, handling); targets come from the model'),
+        scope: schema.enum(['to-target', 'drift-only']).optional(),
+    })
+        .describe('The declarative strategy; an onSession callback is SDK-only'),
+    execution: DeclaredExecutionSchema.optional().describe('Default: execution.simplified()'),
+    externalFlows: ExternalFlowsSchema,
+    calendar: PortfolioCalendarSchema,
+    window: BacktestWindowSchema,
+    periodsPerYear: schema.number().positive().optional().describe('Default 252'),
+    seed: schema.number().integer().nonnegative().optional(),
+});
+const backtestPortfolioRun = defineOperation({
+    id: 'totalfinance.backtest.portfolio_run',
+    title: 'Run a portfolio backtest',
+    description: 'Backtest a multi-asset portfolio through the ledger: instruments with built-in adapters (equity, etf, option, ' +
+        'future, fx-forward, crypto-spot, crypto-perpetual, bond), market data by row set, a model or inline targets on a ' +
+        'rebalance schedule, an execution policy with settlement lags, external flows, a calendar, and the margin check with ' +
+        'forced liquidation. Every fill, flow, lifecycle fact, and liquidation is a portfolio event; the equity is the ' +
+        "ledger's net asset value. The result is portfolioBacktest(...) verbatim. Opt-in (backtestPack): payloads and " +
+        'runtime are heavier than the default set; bulk row sets above the row cap travel by handle.',
+    inputSchema: PortfolioRunInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            ledger: { type: 'object' },
+            timeline: { type: ['object', 'null'] },
+            pnl: { type: ['object', 'null'] },
+            orders: { type: 'array', items: { type: 'object' } },
+            fills: { type: 'array', items: { type: 'object' } },
+            rejections: { type: 'array', items: { type: 'object' } },
+            liquidations: { type: 'array', items: { type: 'object' } },
+            events: { type: 'array', items: { type: 'object' } },
+            valuationMarks: { type: 'array', items: { type: 'object' } },
+            points: { type: 'array', items: { type: 'object' } },
+            returns: { type: 'array', items: { type: 'number' } },
+            performance: { type: 'object', description: 'The standard performance summary' },
+            finalValue: { type: 'number' },
+            runId: { type: 'string' },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'ledger',
+            'timeline',
+            'pnl',
+            'orders',
+            'fills',
+            'rejections',
+            'liquidations',
+            'events',
+            'valuationMarks',
+            'points',
+            'returns',
+            'performance',
+            'finalValue',
+            'runId',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'job',
+    handleFields: ['marketData'],
+    run: (input) => {
+        const id = 'totalfinance.backtest.portfolio_run';
+        const { marketData, execution: executionWire, ...rest } = input;
+        const capped = Object.fromEntries(Object.entries(marketData)
+            .filter(([, rows]) => rows !== undefined)
+            .map(([key, rows]) => [key, capRows(rows, `marketData.${key}`, id)]));
+        const result = portfolioBacktest({
+            ...rest,
+            marketData: capped,
+            ...(executionWire !== undefined ? { execution: executionPolicyOf(executionWire) } : {}),
+        });
+        return {
+            summary: `${result.diagnostics.sessionCount} sessions, ${result.fills.length} fills, final value ${result.finalValue.toFixed(2)} (${result.assumptions.execution.realism} execution)`,
+            structured: result,
+        };
+    },
+});
+// ── Stage 7B.1 slice 5 (AT4 Decision 10): the trading-agent environment over the wire ────────────
+const EnvironmentLimitsSchema = schema.object({
+    maximumPositionWeight: schema.number().positive().max(1).optional(),
+    maximumGrossLeverage: schema.number().positive().optional(),
+    maximumDrawdown: schema.number().positive().max(1).optional(),
+    maximumDailyLoss: schema.number().positive().max(1).optional(),
+    maximumDaysToLiquidate: schema.number().positive().optional(),
+    minimumSettledCash: schema.number().optional(),
+    allowUndefinedRiskOptions: schema.boolean().optional(),
+    maximumPositionNotional: schema.number().positive().optional(),
+    onBreach: schema.enum(['terminate', 'reject-and-continue']).optional(),
+});
+const RewardCompositionSchema = schema
+    .object({
+    pnl: schema.number().optional(),
+    drawdown: schema.number().optional(),
+    turnover: schema.number().optional(),
+    cost: schema.number().optional(),
+    concentration: schema.number().optional(),
+    leverage: schema.number().optional(),
+    riskViolation: schema.number().optional(),
+    benchmark: schema
+        .object({ weight: schema.number(), instrumentId: schema.string().nonempty() })
+        .optional(),
+})
+    .describe('The declared reward composition; a goal callback is SDK-only');
+const FeatureRecipesSchema = schema.object({
+    lookbackReturns: schema.array(schema.number().integer().positive()).min(1).optional(),
+    realizedVolatility: schema
+        .object({
+        lookbacks: schema.array(schema.number().integer().positive()).min(1),
+        annualization: schema
+            .number()
+            .positive()
+            .describe('Bars per year scaling the per-bar σ (252 daily, 52 weekly, 12 monthly; 1 = per-bar). Required: the environment never assumes the bar frequency.'),
+    })
+        .optional(),
+    drawdown: schema.boolean().optional(),
+});
+/** The environment definition over the wire: the portfolio request without a strategy, plus the episode blocks. */
+const EnvironmentDefinitionSchema = schema.object({
+    accounting: PortfolioAccountingSchema,
+    instruments: schema.record(InstrumentSpecificationSchema),
+    marketData: PortfolioMarketDataSchema,
+    execution: DeclaredExecutionSchema.optional().describe('Default: execution.simplified()'),
+    externalFlows: ExternalFlowsSchema,
+    calendar: PortfolioCalendarSchema,
+    window: BacktestWindowSchema,
+    periodsPerYear: schema.number().positive().optional().describe('Default 252'),
+    seed: schema.number().integer().nonnegative().optional(),
+    maximumSteps: schema.number().integer().positive().optional(),
+    limits: EnvironmentLimitsSchema.optional(),
+    reward: RewardCompositionSchema.optional(),
+    features: FeatureRecipesSchema.optional(),
+});
+const BaselineSchema = schema.union([
+    schema.object({ baseline: schema.literal('holdCash') }),
+    schema.object({
+        baseline: schema.literal('buyAndHold'),
+        weights: schema.record(schema.number().nonnegative()).optional(),
+    }),
+    schema.object({
+        baseline: schema.literal('periodicRebalance'),
+        everySessions: schema.number().integer().positive(),
+        weights: schema.record(schema.number().nonnegative()).optional(),
+    }),
+    schema.object({
+        baseline: schema.literal('randomValidAction'),
+        seed: schema.number().integer().nonnegative(),
+    }),
+    schema.object({
+        baseline: schema.literal('riskParity'),
+        lookback: schema.number().integer().positive(),
+        everySessions: schema.number().integer().positive().optional(),
+    }),
+    schema.object({
+        baseline: schema.literal('momentumCrossover'),
+        fast: schema.number().integer().positive(),
+        slow: schema.number().integer().positive(),
+    }),
+]);
+const EnvironmentEpisodeInputSchema = schema.object({
+    episode: schema
+        .union([
+        schema.enum(ENVIRONMENT_EPISODE_IDS),
+        schema.object({ id: schema.string().nonempty(), definition: EnvironmentDefinitionSchema }),
+    ])
+        .describe('A catalogue id, or a named declarative definition'),
+    policy: BaselineSchema.describe('A maintained baseline; a TypeScript policy is SDK-only'),
+    seed: schema.number().integer().nonnegative().optional().describe('Default 42'),
+    artifact: schema
+        .enum(['none', 'embed'])
+        .optional()
+        .describe("Default 'none'; 'embed' returns the recorded episode as an `environment` run artifact"),
+});
+function baselineOf(wire) {
+    switch (wire.baseline) {
+        case 'holdCash':
+            return agentBaselines.holdCash();
+        case 'buyAndHold':
+            return agentBaselines.buyAndHold(wire.weights !== undefined ? { weights: wire.weights } : undefined);
+        case 'periodicRebalance':
+            return agentBaselines.periodicRebalance({
+                everySessions: wire.everySessions,
+                ...(wire.weights !== undefined ? { weights: wire.weights } : {}),
+            });
+        case 'randomValidAction':
+            return agentBaselines.randomValidAction(wire.seed);
+        case 'riskParity':
+            return agentBaselines.riskParity({
+                lookback: wire.lookback,
+                ...(wire.everySessions !== undefined ? { everySessions: wire.everySessions } : {}),
+            });
+        case 'momentumCrossover':
+            return agentBaselines.momentumCrossover({ fast: wire.fast, slow: wire.slow });
+    }
+}
+const backtestEnvironmentEpisode = defineOperation({
+    id: 'totalfinance.backtest.environment_episode',
+    title: 'Bench a baseline policy over one trading-environment episode',
+    description: 'Run one of the six maintained baseline policies through the deterministic trading environment over a ' +
+        "catalogue episode (or a named declarative definition) at a seed, and return Agent Bench's report for that " +
+        'episode: operational conformance (look-ahead, replay equality, duplicate orders under the retry drive, ' +
+        'external-order attempts, reconciliation; the mask and limit counts) apart from strategy quality (return, ' +
+        'volatility, Sharpe, Sortino, drawdown, turnover, cost, exposure, violations) — no single score by design. ' +
+        "With artifact: 'embed', the recorded episode travels as an `environment` run artifact that replays to its run " +
+        'hash. Declarative inputs only: a TypeScript policy or a reward goal callback is SDK-only. Opt-in (backtestPack).',
+    inputSchema: EnvironmentEpisodeInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            policy: { type: 'string' },
+            episode: {
+                type: 'object',
+                description: 'The bench report for the one episode: operational and strategy blocks',
+            },
+            trace: {
+                type: 'object',
+                description: 'The recorded episode: runId, engineRunId, traceHash, steps, rewardTotal, terminated, truncated, reason',
+            },
+            artifact: {
+                type: ['object', 'null'],
+                description: "The `environment` run artifact when artifact is 'embed'",
+            },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: ['policy', 'episode', 'trace', 'artifact', 'assumptions', 'diagnostics'],
+    },
+    costClass: 'job',
+    handleFields: ['episode.definition.marketData'],
+    run: (input) => {
+        const id = 'totalfinance.backtest.environment_episode';
+        const policy = baselineOf(input.policy);
+        const seed = input.seed ?? 42;
+        const episode = typeof input.episode === 'string'
+            ? input.episode
+            : (() => {
+                const { execution: executionWire, marketData, ...rest } = input.episode.definition;
+                const capped = Object.fromEntries(Object.entries(marketData)
+                    .filter(([, rows]) => rows !== undefined)
+                    .map(([key, rows]) => [
+                    key,
+                    capRows(rows, `episode.definition.marketData.${key}`, id),
+                ]));
+                return {
+                    id: input.episode.id,
+                    definition: {
+                        ...rest,
+                        marketData: capped,
+                        ...(executionWire !== undefined
+                            ? { execution: executionPolicyOf(executionWire) }
+                            : {}),
+                    },
+                };
+            })();
+        const report = runAgentBench({ policy, episodes: [episode], seeds: [seed] });
+        const row = report.episodes[0];
+        const trace = report.traces[0];
+        const artifact = input.artifact === 'embed'
+            ? backtestRunArtifact({ kind: 'environment', run: trace.episode, input: trace.input })
+            : null;
+        return {
+            summary: `${row.id}@${seed} under ${report.policy}: operational ${row.operational.passes ? 'passes' : 'FAILS'} (look-ahead ${row.operational.lookAhead}, duplicates ${row.operational.duplicateOrders}), final value ${row.strategy.finalValue.toFixed(2)} over ${row.strategy.steps} steps`,
+            structured: {
+                policy: report.policy,
+                episode: row,
+                trace: {
+                    runId: trace.episode.runId,
+                    engineRunId: trace.episode.engineRunId,
+                    traceHash: trace.episode.traceHash,
+                    steps: trace.episode.steps,
+                    rewardTotal: trace.episode.rewardTotal,
+                    terminated: trace.episode.terminated,
+                    truncated: trace.episode.truncated,
+                    reason: trace.episode.reason,
+                },
+                artifact,
+                assumptions: report.assumptions,
+                diagnostics: report.diagnostics,
+            },
+        };
+    },
+});
+/** The journey operations that join the opt-in backtest pack (`backtestPack()`). */
+export function backtestJourneyOperations() {
+    return [
+        backtestOptionsRun,
+        backtestCrossSectionalRun,
+        backtestPortfolioRun,
+        backtestEnvironmentEpisode,
+    ];
+}
+// ── Stage 4.7 slice 2 (FC9 Decision 5): company valuation over the wire ───────────────────────
+const FundamentalPeriodSchema = schema.object({
+    periodStartDate: schema.string().date().optional(),
+    periodEndDate: schema.string().date(),
+    fiscalYear: schema.number().integer(),
+    fiscalQuarter: schema
+        .union([schema.literal(1), schema.literal(2), schema.literal(3), schema.literal(4)])
+        .optional(),
+    periodType: schema.enum(['quarter', 'year', 'trailing-twelve-months']),
+    filedTimestampMs: schema.number().optional(),
+    availableTimestampMs: schema.number(),
+    currency: schema.string().nonempty(),
+    monetaryScale: schema.union([
+        schema.literal(1),
+        schema.literal(1_000),
+        schema.literal(1_000_000),
+    ]),
+    form: schema.string().optional(),
+});
+const IncomeStatementSchema = schema.object({
+    period: FundamentalPeriodSchema,
+    revenue: schema.number(),
+    costOfRevenue: schema.number().optional(),
+    grossProfit: schema.number().optional(),
+    operatingExpenses: schema.number().optional(),
+    operatingIncome: schema.number(),
+    interestExpense: schema.number().optional(),
+    incomeTaxExpense: schema.number().optional(),
+    netIncome: schema.number(),
+    incomeFromContinuingOperations: schema.number().optional(),
+    sellingGeneralAdministrativeExpense: schema.number().optional(),
+    dilutedSharesOutstanding: schema.number().optional(),
+    metadata: schema.record(schema.unknown()).optional(),
+});
+const BalanceSheetSchema = schema.object({
+    period: FundamentalPeriodSchema,
+    cashAndCashEquivalents: schema.number(),
+    shortTermInvestments: schema.number().optional(),
+    accountsReceivable: schema.number().optional(),
+    inventory: schema.number().optional(),
+    currentAssets: schema.number().optional(),
+    propertyPlantEquipmentNet: schema.number().optional(),
+    otherAssets: schema.number().optional(),
+    totalAssets: schema.number(),
+    currentLiabilities: schema.number().optional(),
+    accountsPayable: schema.number().optional(),
+    shortTermDebt: schema.number().optional(),
+    longTermDebt: schema.number().optional(),
+    otherLiabilities: schema.number().optional(),
+    totalDebt: schema.number().optional(),
+    totalLiabilities: schema.number(),
+    preferredEquity: schema.number().optional(),
+    minorityInterest: schema.number().optional(),
+    totalEquity: schema.number(),
+    metadata: schema.record(schema.unknown()).optional(),
+});
+const CashFlowStatementSchema = schema.object({
+    period: FundamentalPeriodSchema,
+    operatingCashFlow: schema.number(),
+    investingCashFlow: schema.number(),
+    financingCashFlow: schema.number(),
+    capitalExpenditure: schema.number().optional(),
+    depreciationAndAmortization: schema.number().optional(),
+    stockBasedCompensation: schema.number().optional(),
+    acquisitions: schema.number().optional(),
+    dividendsPaid: schema.number().optional(),
+    shareRepurchases: schema.number().optional(),
+    increaseInNetWorkingCapital: schema.number().optional(),
+    netChangeInCash: schema.number().optional(),
+    metadata: schema.record(schema.unknown()).optional(),
+});
+const FinancialStatementsSchema = schema
+    .object({
+    income: IncomeStatementSchema,
+    balance: BalanceSheetSchema,
+    cashFlow: CashFlowStatementSchema,
+})
+    .describe('The typed historical base (one period of the three statements) the projection rolls forward');
+const AmountDriverSchema = schema.union([
+    schema.object({ amount: schema.number() }),
+    schema.object({ fractionOfRevenue: schema.number() }),
+]);
+const StatementProjectionPeriodSchema = schema.object({
+    periodLabel: schema.string().nonempty(),
+    revenue: schema.union([
+        schema.object({ amount: schema.number() }),
+        schema.object({ growthRate: schema.number() }),
+    ]),
+    operatingMargin: schema.number(),
+    taxRate: schema.number(),
+    interestExpense: schema.number(),
+    depreciationAndAmortization: AmountDriverSchema,
+    capitalExpenditure: AmountDriverSchema,
+    accountsReceivable: AmountDriverSchema,
+    inventory: AmountDriverSchema,
+    accountsPayable: AmountDriverSchema,
+    netBorrowing: schema.number(),
+    dividendsPaid: schema.number(),
+});
+const InterestCompoundingSchema = schema.union([
+    schema.enum(['simple', 'continuous', 'annual', 'semiannual', 'quarterly', 'monthly']),
+    schema.object({
+        type: schema.literal('periodic'),
+        periodsPerYear: schema.number().integer().positive(),
+    }),
+]);
+const TerminalValueMethodSchema = schema.union([
+    schema.object({
+        method: schema.literal('perpetual-growth'),
+        terminalCashFlow: schema.number(),
+        perpetualGrowthRate: schema.number(),
+    }),
+    schema.object({
+        method: schema.literal('exit-multiple'),
+        terminalMetricAmount: schema.number(),
+        exitMultiple: schema.number(),
+    }),
+]);
+const ValuationConventionsSchema = schema
+    .object({
+    valuationBasis: schema.enum(['firm', 'equity']),
+    valuationDate: schema.string().date(),
+    currency: schema.string().nonempty(),
+    annualDiscountRate: schema
+        .number()
+        .describe('REQUIRED and explicit — a discount rate is a goal, never a default (FC0)'),
+    compounding: InterestCompoundingSchema,
+    dayCount: schema.enum(['ACT/365F', 'ACT/360', '30/360']).optional(),
+    terminalValueMethod: TerminalValueMethodSchema,
+    enterpriseToEquityBridge: schema
+        .object({
+        cashAndCashEquivalents: schema.number(),
+        totalDebt: schema.number(),
+        preferredEquity: schema.number(),
+        minorityInterest: schema.number(),
+        nonOperatingAssets: schema.number(),
+    })
+        .optional(),
+    dilutedSharesOutstanding: schema.number().positive().optional(),
+    provenance: schema
+        .object({
+        forecastIdentity: schema.string().optional(),
+        statementIdentity: schema.string().optional(),
+        restatementIdentity: schema.string().optional(),
+        source: schema.string().optional(),
+    })
+        .optional(),
+})
+    .describe("discountedCashFlow's conventions, minus the projected flows the projection supplies");
+const SensitivityAxisSchema = schema.object({
+    variable: schema.enum([
+        'annual-discount-rate',
+        'perpetual-growth-rate',
+        'exit-multiple',
+    ]),
+    values: schema.array(schema.number()).min(1),
+});
+const ValuationCompanyInputSchema = schema.object({
+    projection: schema.object({
+        baseStatements: FinancialStatementsSchema,
+        periods: schema.array(StatementProjectionPeriodSchema).min(1),
+    }),
+    valuation: ValuationConventionsSchema,
+    sensitivity: schema
+        .object({ rowAxis: SensitivityAxisSchema, columnAxis: SensitivityAxisSchema })
+        .optional()
+        .describe('Adds discountedCashFlowSensitivityTable over the same flows when supplied'),
+});
+const valuationCompany = defineOperation({
+    id: 'totalfinance.valuation.company',
+    title: 'Value a company from its statements',
+    description: 'Project the three statements from explicit drivers, take the free cash flows the valuation basis ' +
+        'needs, and discount them under the stated conventions (basis, date, currency, the REQUIRED discount rate, ' +
+        'compounding, day count, the terminal value method, the enterprise-to-equity bridge). The result is ' +
+        'discountedCashFlowFromStatements(...) verbatim — the projection with its balance-sheet reconciliation, the ' +
+        'cash flows used, and the valuation — plus discountedCashFlowSensitivityTable(...) over the same flows when a ' +
+        'sensitivity request is supplied. Opt-in (valuationPack).',
+    inputSchema: ValuationCompanyInputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            projection: { type: 'object', description: 'projectFinancialStatements(...) verbatim' },
+            cashFlowsUsed: { type: 'string', enum: ['freeCashFlowToFirm', 'freeCashFlowToEquity'] },
+            valuation: { type: 'object', description: 'discountedCashFlow(...) verbatim' },
+            sensitivity: {
+                type: ['object', 'null'],
+                description: 'discountedCashFlowSensitivityTable(...) verbatim, or null when not requested',
+            },
+            assumptions: ASSUMPTIONS_SCHEMA,
+            diagnostics: DIAGNOSTICS_SCHEMA,
+        },
+        required: [
+            'projection',
+            'cashFlowsUsed',
+            'valuation',
+            'sensitivity',
+            'assumptions',
+            'diagnostics',
+        ],
+    },
+    costClass: 'medium',
+    run: (input) => {
+        const { sensitivity, ...request } = input;
+        const result = discountedCashFlowFromStatements(request);
+        // The sensitivity table discounts the SAME flows the composition used — rebuilt exactly as the
+        // acceptance law rebuilds them (period index + 1 years, the basis's free cash flow).
+        const table = sensitivity !== undefined
+            ? discountedCashFlowSensitivityTable({
+                discountedCashFlowInput: {
+                    ...request.valuation,
+                    projectedCashFlows: result.projection.statements.map((period, index) => ({
+                        timeYears: index + 1,
+                        amount: result.cashFlowsUsed === 'freeCashFlowToFirm'
+                            ? period.freeCashFlowToFirm
+                            : period.freeCashFlowToEquity,
+                    })),
+                },
+                rowAxis: sensitivity.rowAxis,
+                columnAxis: sensitivity.columnAxis,
+            })
+            : null;
+        const value = result.valuation;
+        const headline = 'enterpriseValue' in value
+            ? `enterprise value ${value.enterpriseValue.toFixed(2)}`
+            : `equity value ${value.equityValue.toFixed(2)}`;
+        return {
+            summary: `${result.cashFlowsUsed} over ${result.assumptions.projectedPeriodCount} periods: ${headline} ${request.valuation.currency}${table ? `; ${table.rowValues.length}×${table.columnValues.length} sensitivity table` : ''}`,
+            structured: {
+                projection: result.projection,
+                cashFlowsUsed: result.cashFlowsUsed,
+                valuation: result.valuation,
+                sensitivity: table,
+                assumptions: {
+                    ...result.assumptions,
+                    sensitivity: table ? table.assumptions : 'omitted: no sensitivity request supplied',
+                },
+                diagnostics: {
+                    warnings: [...result.diagnostics.warnings, ...(table?.diagnostics.warnings ?? [])],
+                },
+            },
+        };
+    },
+});
+/** The company-valuation journey pack — opt-in beside the ten domain packs and the other journey packs. */
+export function valuationPack() {
+    return { name: 'valuation', operations: [valuationCompany] };
+}
+/**
+ * The five journey packs — opt-in beside the ten domain packs (Decision 9 counts them apart from
+ * the twenty-three defaults; Stage 4.7 slice 2 added the valuation pack): `createOperationRegistry({ packs: [...defaultPacks(), ...journeyPacks()] })`.
+ */
+export function journeyPacks() {
+    return [portfolioPack(), scenarioPack(), researchPack(), artifactPack(), valuationPack()];
+}
+/** Every journey operation across the four journey packs, flattened. */
+export function journeyOperations() {
+    return journeyPacks().flatMap((pack) => pack.operations);
+}
+//# sourceMappingURL=operations-journey.js.map