@adaptic/backend-legacy 0.0.83 → 0.0.84

package/helpers/deep-merge.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMerge = void 0;
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Pure, non-mutating deep merge.
+ * - Plain objects merge recursively.
+ * - Arrays and scalars: right side replaces.
+ * - `undefined` on the right is treated as absent (left value retained).
+ * - `null` on the right overrides to null.
+ *
+ * Used by effectivePolicy() and effectiveLlmConfig() to deep-merge
+ * Organization → Fund → BrokerageAccount policy layers per charter §2.2.
+ * Consumers must use this helper; do not re-implement merge semantics.
+ */
+const deepMerge = (left, right) => {
+    const out = { ...left };
+    for (const key of Object.keys(right)) {
+        const rv = right[key];
+        if (rv === undefined)
+            continue;
+        const lv = out[key];
+        if (isPlainObject(lv) && isPlainObject(rv)) {
+            out[key] = (0, exports.deepMerge)(lv, rv);
+        }
+        else {
+            out[key] = rv;
+        }
+    }
+    return out;
+};
+exports.deepMerge = deepMerge;
+//# sourceMappingURL=deep-merge.js.map

package/helpers/deep-merge.d.ts

@@ -0,0 +1,15 @@
+type Plain = Record<string, unknown>;
+/**
+ * Pure, non-mutating deep merge.
+ * - Plain objects merge recursively.
+ * - Arrays and scalars: right side replaces.
+ * - `undefined` on the right is treated as absent (left value retained).
+ * - `null` on the right overrides to null.
+ *
+ * Used by effectivePolicy() and effectiveLlmConfig() to deep-merge
+ * Organization → Fund → BrokerageAccount policy layers per charter §2.2.
+ * Consumers must use this helper; do not re-implement merge semantics.
+ */
+export declare const deepMerge: <T extends Plain, U extends Plain>(left: T, right: U) => T & U;
+export {};
+//# sourceMappingURL=deep-merge.d.ts.map

package/helpers/deep-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.d.ts","sourceRoot":"","sources":["../../src/helpers/deep-merge.ts"],"names":[],"mappings":"AAAA,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKrC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,KAAK,EAAE,CAAC,SAAS,KAAK,EACxD,MAAM,CAAC,EACP,OAAO,CAAC,KACP,CAAC,GAAG,CAaN,CAAC"}

package/helpers/deep-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.js","sourceRoot":"","sources":["../../src/helpers/deep-merge.ts"],"names":[],"mappings":";;;AAEA,MAAM,aAAa,GAAG,CAAC,CAAU,EAAc,EAAE,CAC/C,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE3D;;;;;;;;;;GAUG;AACI,MAAM,SAAS,GAAG,CACvB,IAAO,EACP,KAAQ,EACD,EAAE;IACT,MAAM,GAAG,GAAU,EAAE,GAAG,IAAI,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAC/B,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,IAAI,aAAa,CAAC,EAAE,CAAC,IAAI,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,GAAG,CAAC,GAAG,IAAA,iBAAS,EAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,GAAY,CAAC;AACtB,CAAC,CAAC;AAhBW,QAAA,SAAS,aAgBpB"}

package/helpers/effective-llm-config.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveLlmConfig = effectiveLlmConfig;
+const deep_merge_1 = require("./deep-merge.cjs");
+const llm_configuration_1 = require("../types/llm-configuration.cjs");
+/**
+ * Deep-merges DEFAULT_LLM_CONFIGURATION → Org.llmDefaults →
+ * Fund.llmOverrides into a single frozen `LlmConfigurationJson`.
+ *
+ * `apiKeys.<provider>` values are EncryptedApiKey envelopes; this
+ * helper does NOT decrypt. Use `decryptApiKey()` from
+ * `helpers/kms-envelope` with appropriate role gating per spec §4.3.
+ */
+function effectiveLlmConfig(fund) {
+    let cfg = { ...llm_configuration_1.DEFAULT_LLM_CONFIGURATION };
+    if (fund.organization.llmDefaults) {
+        cfg = (0, deep_merge_1.deepMerge)(cfg, fund.organization.llmDefaults);
+    }
+    if (fund.llmOverrides) {
+        cfg = (0, deep_merge_1.deepMerge)(cfg, fund.llmOverrides);
+    }
+    return Object.freeze(cfg);
+}
+//# sourceMappingURL=effective-llm-config.js.map

package/helpers/effective-llm-config.d.ts

@@ -0,0 +1,28 @@
+import { type LlmConfigurationJson } from '../types/llm-configuration';
+/**
+ * The relation shape `effectiveLlmConfig()` requires.
+ *
+ * Note: there is no overlay tier (LLM config is not event-driven).
+ * Precedence is a two-level chain.
+ */
+interface FundWithLlmContext {
+    id: string;
+    llmOverrides: LlmConfigurationJson | null;
+    organization: {
+        id: string;
+        llmDefaults: LlmConfigurationJson | null;
+    };
+}
+/**
+ * Deep-merges DEFAULT_LLM_CONFIGURATION → Org.llmDefaults →
+ * Fund.llmOverrides into a single frozen `LlmConfigurationJson`.
+ *
+ * `apiKeys.<provider>` values are EncryptedApiKey envelopes; this
+ * helper does NOT decrypt. Use `decryptApiKey()` from
+ * `helpers/kms-envelope` with appropriate role gating per spec §4.3.
+ */
+export declare function effectiveLlmConfig(fund: FundWithLlmContext): Required<Omit<LlmConfigurationJson, 'apiKeys'>> & {
+    apiKeys: NonNullable<LlmConfigurationJson['apiKeys']>;
+};
+export {};
+//# sourceMappingURL=effective-llm-config.d.ts.map

package/helpers/effective-llm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-llm-config.d.ts","sourceRoot":"","sources":["../../src/helpers/effective-llm-config.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AAEpC;;;;;GAKG;AACH,UAAU,kBAAkB;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1C,YAAY,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,oBAAoB,GAAG,IAAI,CAAA;KAAE,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,QAAQ,CACpE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,CACtC,GAAG;IACF,OAAO,EAAE,WAAW,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC;CACvD,CAeA"}

package/helpers/effective-llm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-llm-config.js","sourceRoot":"","sources":["../../src/helpers/effective-llm-config.ts"],"names":[],"mappings":";;AA0BA,gDAmBC;AA7CD,6CAAyC;AACzC,kEAGoC;AAcpC;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,IAAwB;IAKzD,IAAI,GAAG,GAAyB,EAAE,GAAG,6CAAyB,EAAE,CAAC;IACjE,IAAI,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;QAClC,GAAG,GAAG,IAAA,sBAAS,EACb,GAA8B,EAC9B,IAAI,CAAC,YAAY,CAAC,WAAsC,CACjC,CAAC;IAC5B,CAAC;IACD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,GAAG,GAAG,IAAA,sBAAS,EACb,GAA8B,EAC9B,IAAI,CAAC,YAAuC,CACrB,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAA0C,CAAC;AACrE,CAAC"}

package/helpers/effective-policy.cjs

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brokerageAccountWithPolicyContextSelectionSet = exports.EffectivePolicyContextError = void 0;
+exports.effectivePolicy = effectivePolicy;
+const deep_merge_1 = require("./deep-merge.cjs");
+const trading_policy_1 = require("../types/trading-policy.cjs");
+/**
+ * Thrown when a caller invokes effectivePolicy() with a
+ * BrokerageAccount whose required relations (`fund.organization`,
+ * `fund.policyOverlays`) were not loaded by the selection set. We do
+ * not silently fall back to defaults — silent fall-back hides bugs.
+ */
+class EffectivePolicyContextError extends Error {
+    constructor(field) {
+        super(`effectivePolicy(): missing relation \`${field}\`. ` +
+            `Fetch with brokerageAccountWithPolicyContextSelectionSet ` +
+            `(see @adaptic/backend-legacy docs).`);
+        this.name = 'EffectivePolicyContextError';
+    }
+}
+exports.EffectivePolicyContextError = EffectivePolicyContextError;
+/**
+ * The 14 BrokerageAccount column fields preserved per charter §2.2.
+ * Read directly from the entity, not from the JSON merge.
+ */
+const BA_COLUMN_FIELDS = [
+    'enablePortfolioTrailingStop',
+    'portfolioTrailPercent',
+    'portfolioProfitThresholdPercent',
+    'reducedPortfolioTrailPercent',
+    'defaultTrailingStopPercentage100',
+    'firstTrailReductionThreshold100',
+    'secondTrailReductionThreshold100',
+    'firstReducedTrailPercentage100',
+    'secondReducedTrailPercentage100',
+    'minimumPriceChangePercent100',
+    'cryptoTradingEnabled',
+    'cryptoTradingPairs',
+    'tradeAllocationPct',
+    'cryptoTradeAllocationPct',
+];
+const severityRank = {
+    LOW: 0,
+    MEDIUM: 1,
+    HIGH: 2,
+    CRITICAL: 3,
+};
+/**
+ * Canonical selection-set string for `adaptic.brokerageAccount.get(id, …)`.
+ * Loads fund + fund.organization + fund.policyOverlays in one query.
+ *
+ * Consumers should pass this verbatim to fetch a BrokerageAccount
+ * suitable for effectivePolicy().
+ */
+exports.brokerageAccountWithPolicyContextSelectionSet = `
+  id
+  enablePortfolioTrailingStop
+  portfolioTrailPercent
+  portfolioProfitThresholdPercent
+  reducedPortfolioTrailPercent
+  defaultTrailingStopPercentage100
+  firstTrailReductionThreshold100
+  secondTrailReductionThreshold100
+  firstReducedTrailPercentage100
+  secondReducedTrailPercentage100
+  minimumPriceChangePercent100
+  cryptoTradingEnabled
+  cryptoTradingPairs
+  tradeAllocationPct
+  cryptoTradeAllocationPct
+  fund {
+    id
+    tradingOverrides
+    policyOverlays
+    organization { id tradingDefaults }
+  }
+`;
+/**
+ * Deep-merges DEFAULT_TRADING_POLICY → Org.tradingDefaults →
+ * Fund.tradingOverrides → active Fund.policyOverlays (severity-sorted)
+ * → 14 BrokerageAccount column fields into a single canonical
+ * `Required<TradingPolicyJson>` plus the 14 column overrides.
+ *
+ * Consumers MUST use this helper — do not re-implement the precedence
+ * chain. The result is frozen.
+ *
+ * @throws EffectivePolicyContextError if `fund.organization` or
+ *   `fund.policyOverlays` is missing (selection-set bug).
+ */
+function effectivePolicy(ba) {
+    var _a;
+    if (!ba.fund)
+        throw new EffectivePolicyContextError('fund');
+    if (!ba.fund.organization) {
+        throw new EffectivePolicyContextError('fund.organization');
+    }
+    if (ba.fund.policyOverlays === undefined) {
+        throw new EffectivePolicyContextError('fund.policyOverlays');
+    }
+    // 1) defaults
+    let policy = { ...trading_policy_1.DEFAULT_TRADING_POLICY };
+    // 2) Org defaults
+    if (ba.fund.organization.tradingDefaults) {
+        policy = (0, deep_merge_1.deepMerge)(policy, ba.fund.organization.tradingDefaults);
+    }
+    // 3) Fund overrides
+    if (ba.fund.tradingOverrides) {
+        policy = (0, deep_merge_1.deepMerge)(policy, ba.fund.tradingOverrides);
+    }
+    // 4) Active overlays (severity-sorted; CRITICAL last → highest precedence)
+    const now = new Date();
+    const active = ((_a = ba.fund.policyOverlays) !== null && _a !== void 0 ? _a : [])
+        .filter((o) => o.status === 'ACTIVE' &&
+        (o.expiresAt == null || new Date(o.expiresAt) > now))
+        .sort((a, b) => severityRank[a.severity] - severityRank[b.severity]);
+    for (const overlay of active) {
+        policy = (0, deep_merge_1.deepMerge)(policy, overlay.mutations);
+    }
+    // 5) BA column overrides (the 14 fields stay alongside the JSON)
+    const baCols = {};
+    for (const f of BA_COLUMN_FIELDS) {
+        baCols[f] = ba[f];
+    }
+    // 6) freeze and return
+    return Object.freeze({
+        ...policy,
+        ...baCols,
+    });
+}
+//# sourceMappingURL=effective-policy.js.map

package/helpers/effective-policy.d.ts

@@ -0,0 +1,70 @@
+import { type TradingPolicyJson } from '../types/trading-policy';
+import type { PolicyOverlayEntry } from '../types/policy-overlay';
+/**
+ * Thrown when a caller invokes effectivePolicy() with a
+ * BrokerageAccount whose required relations (`fund.organization`,
+ * `fund.policyOverlays`) were not loaded by the selection set. We do
+ * not silently fall back to defaults — silent fall-back hides bugs.
+ */
+export declare class EffectivePolicyContextError extends Error {
+    constructor(field: string);
+}
+/**
+ * The 14 BrokerageAccount column fields preserved per charter §2.2.
+ * Read directly from the entity, not from the JSON merge.
+ */
+declare const BA_COLUMN_FIELDS: readonly ["enablePortfolioTrailingStop", "portfolioTrailPercent", "portfolioProfitThresholdPercent", "reducedPortfolioTrailPercent", "defaultTrailingStopPercentage100", "firstTrailReductionThreshold100", "secondTrailReductionThreshold100", "firstReducedTrailPercentage100", "secondReducedTrailPercentage100", "minimumPriceChangePercent100", "cryptoTradingEnabled", "cryptoTradingPairs", "tradeAllocationPct", "cryptoTradeAllocationPct"];
+type BACol = (typeof BA_COLUMN_FIELDS)[number];
+/**
+ * The relation shape effectivePolicy() requires. Consumers must fetch
+ * with the selection set below to populate these correctly.
+ */
+export interface BrokerageAccountWithPolicyContext {
+    id: string;
+    enablePortfolioTrailingStop: boolean;
+    portfolioTrailPercent: number;
+    portfolioProfitThresholdPercent: number;
+    reducedPortfolioTrailPercent: number;
+    defaultTrailingStopPercentage100: number;
+    firstTrailReductionThreshold100: number;
+    secondTrailReductionThreshold100: number;
+    firstReducedTrailPercentage100: number;
+    secondReducedTrailPercentage100: number;
+    minimumPriceChangePercent100: number;
+    cryptoTradingEnabled: boolean;
+    cryptoTradingPairs: string[];
+    tradeAllocationPct: number;
+    cryptoTradeAllocationPct: number;
+    fund: {
+        id: string;
+        tradingOverrides: TradingPolicyJson | null;
+        policyOverlays: PolicyOverlayEntry[] | null;
+        organization: {
+            id: string;
+            tradingDefaults: TradingPolicyJson | null;
+        };
+    };
+}
+/**
+ * Canonical selection-set string for `adaptic.brokerageAccount.get(id, …)`.
+ * Loads fund + fund.organization + fund.policyOverlays in one query.
+ *
+ * Consumers should pass this verbatim to fetch a BrokerageAccount
+ * suitable for effectivePolicy().
+ */
+export declare const brokerageAccountWithPolicyContextSelectionSet = "\n  id\n  enablePortfolioTrailingStop\n  portfolioTrailPercent\n  portfolioProfitThresholdPercent\n  reducedPortfolioTrailPercent\n  defaultTrailingStopPercentage100\n  firstTrailReductionThreshold100\n  secondTrailReductionThreshold100\n  firstReducedTrailPercentage100\n  secondReducedTrailPercentage100\n  minimumPriceChangePercent100\n  cryptoTradingEnabled\n  cryptoTradingPairs\n  tradeAllocationPct\n  cryptoTradeAllocationPct\n  fund {\n    id\n    tradingOverrides\n    policyOverlays\n    organization { id tradingDefaults }\n  }\n";
+/**
+ * Deep-merges DEFAULT_TRADING_POLICY → Org.tradingDefaults →
+ * Fund.tradingOverrides → active Fund.policyOverlays (severity-sorted)
+ * → 14 BrokerageAccount column fields into a single canonical
+ * `Required<TradingPolicyJson>` plus the 14 column overrides.
+ *
+ * Consumers MUST use this helper — do not re-implement the precedence
+ * chain. The result is frozen.
+ *
+ * @throws EffectivePolicyContextError if `fund.organization` or
+ *   `fund.policyOverlays` is missing (selection-set bug).
+ */
+export declare function effectivePolicy(ba: BrokerageAccountWithPolicyContext): Required<TradingPolicyJson> & Record<BACol, unknown>;
+export {};
+//# sourceMappingURL=effective-policy.d.ts.map

package/helpers/effective-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-policy.d.ts","sourceRoot":"","sources":["../../src/helpers/effective-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,KAAK,EAAE,MAAM;CAQ1B;AAED;;;GAGG;AACH,QAAA,MAAM,gBAAgB,sbAeZ,CAAC;AAEX,KAAK,KAAK,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B,EAAE,OAAO,CAAC;IACrC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+BAA+B,EAAE,MAAM,CAAC;IACxC,4BAA4B,EAAE,MAAM,CAAC;IACrC,gCAAgC,EAAE,MAAM,CAAC;IACzC,+BAA+B,EAAE,MAAM,CAAC;IACxC,gCAAgC,EAAE,MAAM,CAAC;IACzC,8BAA8B,EAAE,MAAM,CAAC;IACvC,+BAA+B,EAAE,MAAM,CAAC;IACxC,4BAA4B,EAAE,MAAM,CAAC;IACrC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wBAAwB,EAAE,MAAM,CAAC;IACjC,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,CAAC;QAC3C,cAAc,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC;QAC5C,YAAY,EAAE;YACZ,EAAE,EAAE,MAAM,CAAC;YACX,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;SAC3C,CAAC;KACH,CAAC;CACH;AASD;;;;;;GAMG;AACH,eAAO,MAAM,6CAA6C,kiBAsBzD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,iCAAiC,GACpC,QAAQ,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAuDtD"}

package/helpers/effective-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-policy.js","sourceRoot":"","sources":["../../src/helpers/effective-policy.ts"],"names":[],"mappings":"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"}

package/helpers/kms-envelope.cjs

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decryptApiKey = exports.encryptApiKey = void 0;
+const node_crypto_1 = require("node:crypto");
+const kms_envelope_kms_adapter_1 = require("./kms-envelope.kms-adapter.cjs");
+const requireKeyId = () => {
+    const k = process.env.KMS_KEY_ID;
+    if (!k) {
+        throw new Error('KMS_KEY_ID env var is required for kms-envelope');
+    }
+    return k;
+};
+/**
+ * Encrypts plaintext under a fresh per-record DEK wrapped by the
+ * configured KMS CMK. Returns the on-disk envelope shape.
+ */
+const encryptApiKey = async (plaintext) => {
+    const keyId = requireKeyId();
+    const dek = (0, node_crypto_1.randomBytes)(32); // 256-bit DEK
+    const iv = (0, node_crypto_1.randomBytes)(12); // 96-bit IV for GCM
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', dek, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const wrapped = await (0, kms_envelope_kms_adapter_1.kmsWrap)(dek, keyId);
+    return {
+        ciphertext: ct.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: authTag.toString('base64'),
+        keyId,
+        wrappedDek: wrapped.toString('base64'),
+        algorithm: 'AES-256-GCM',
+        createdAt: new Date().toISOString(),
+    };
+};
+exports.encryptApiKey = encryptApiKey;
+/**
+ * Decrypts an EncryptedApiKey envelope. Throws on tampering,
+ * unsupported algorithm, or KMS unwrap failure.
+ */
+const decryptApiKey = async (env) => {
+    if (env.algorithm !== 'AES-256-GCM') {
+        throw new Error(`Unsupported algorithm: ${env.algorithm}`);
+    }
+    const dek = await (0, kms_envelope_kms_adapter_1.kmsUnwrap)(Buffer.from(env.wrappedDek, 'base64'), env.keyId);
+    const iv = Buffer.from(env.iv, 'base64');
+    const authTag = Buffer.from(env.authTag, 'base64');
+    const ct = Buffer.from(env.ciphertext, 'base64');
+    const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', dek, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+};
+exports.decryptApiKey = decryptApiKey;
+//# sourceMappingURL=kms-envelope.js.map

package/helpers/kms-envelope.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Envelope-encrypted secret at rest. Stored as a JSON value inside
+ * `Organization.llmDefaults.apiKeys.<provider>` and
+ * `Fund.llmOverrides.apiKeys.<provider>` per charter §2.4 F6 and
+ * spec §4.3.
+ *
+ * Algorithm: AES-256-GCM with per-record IV. The DEK is generated
+ * per-record and wrapped by a KMS-managed CMK identified by `keyId`.
+ */
+export interface EncryptedApiKey {
+    /** base64-encoded AES-GCM ciphertext */
+    ciphertext: string;
+    /** base64-encoded 12-byte IV */
+    iv: string;
+    /** base64-encoded 16-byte GCM auth tag */
+    authTag: string;
+    /** KMS key id used to wrap the DEK */
+    keyId: string;
+    /** base64-encoded KMS-wrapped DEK */
+    wrappedDek: string;
+    /** Locked to AES-256-GCM for now; future schemas extend this union. */
+    algorithm: 'AES-256-GCM';
+    /** ISO-8601 timestamp of when this envelope was created. */
+    createdAt: string;
+}
+/**
+ * Encrypts plaintext under a fresh per-record DEK wrapped by the
+ * configured KMS CMK. Returns the on-disk envelope shape.
+ */
+export declare const encryptApiKey: (plaintext: string) => Promise<EncryptedApiKey>;
+/**
+ * Decrypts an EncryptedApiKey envelope. Throws on tampering,
+ * unsupported algorithm, or KMS unwrap failure.
+ */
+export declare const decryptApiKey: (env: EncryptedApiKey) => Promise<string>;
+//# sourceMappingURL=kms-envelope.d.ts.map

package/helpers/kms-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-envelope.d.ts","sourceRoot":"","sources":["../../src/helpers/kms-envelope.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,SAAS,EAAE,aAAa,CAAC;IACzB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,MAAM,KAChB,OAAO,CAAC,eAAe,CAiBzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAU,KAAK,eAAe,KAAG,OAAO,CAAC,MAAM,CAaxE,CAAC"}

package/helpers/kms-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-envelope.js","sourceRoot":"","sources":["../../src/helpers/kms-envelope.ts"],"names":[],"mappings":";;;AAAA,6CAA4E;AAC5E,yEAAgE;AA4BhE,MAAM,YAAY,GAAG,GAAW,EAAE;IAChC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACjC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAEF;;;GAGG;AACI,MAAM,aAAa,GAAG,KAAK,EAChC,SAAiB,EACS,EAAE;IAC5B,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,CAAC,cAAc;IAC3C,MAAM,EAAE,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB;IAChD,MAAM,MAAM,GAAG,IAAA,4BAAc,EAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,IAAA,kCAAO,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO;QACL,UAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACjC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzB,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACnC,KAAK;QACL,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACtC,SAAS,EAAE,aAAa;QACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC,CAAC;AAnBW,QAAA,aAAa,iBAmBxB;AAEF;;;GAGG;AACI,MAAM,aAAa,GAAG,KAAK,EAAE,GAAoB,EAAmB,EAAE;IAC3E,IAAI,GAAG,CAAC,SAAS,KAAK,aAAa,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,IAAA,oCAAS,EAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9E,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,IAAA,8BAAgB,EAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CACpE,MAAM,CACP,CAAC;AACJ,CAAC,CAAC;AAbW,QAAA,aAAa,iBAaxB"}

package/helpers/kms-envelope.kms-adapter.cjs

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * KMS adapter — wraps/unwraps the per-record Data Encryption Key (DEK).
+ *
+ * Unit tests mock this module to provide deterministic wrap/unwrap.
+ * The runtime implementation should wire to AWS KMS via
+ * `@aws-sdk/client-kms` (or GCP KMS via `@google-cloud/kms`) and
+ * be replaced via a build-time alias or runtime injection.
+ *
+ * The default exports throw so unintended use in production surfaces
+ * an obvious error rather than silently returning plaintext-as-wrapped.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kmsUnwrap = exports.kmsWrap = void 0;
+const kmsWrap = async (_dek, _keyId) => {
+    throw new Error('kmsWrap not wired to a real KMS provider. Mock this module in tests, ' +
+        'or wire to AWS KMS via @aws-sdk/client-kms (or GCP KMS via @google-cloud/kms).');
+};
+exports.kmsWrap = kmsWrap;
+const kmsUnwrap = async (_wrapped, _keyId) => {
+    throw new Error('kmsUnwrap not wired to a real KMS provider. Mock this module in tests, ' +
+        'or wire to AWS KMS via @aws-sdk/client-kms (or GCP KMS via @google-cloud/kms).');
+};
+exports.kmsUnwrap = kmsUnwrap;
+//# sourceMappingURL=kms-envelope.kms-adapter.js.map

package/helpers/kms-envelope.kms-adapter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * KMS adapter — wraps/unwraps the per-record Data Encryption Key (DEK).
+ *
+ * Unit tests mock this module to provide deterministic wrap/unwrap.
+ * The runtime implementation should wire to AWS KMS via
+ * `@aws-sdk/client-kms` (or GCP KMS via `@google-cloud/kms`) and
+ * be replaced via a build-time alias or runtime injection.
+ *
+ * The default exports throw so unintended use in production surfaces
+ * an obvious error rather than silently returning plaintext-as-wrapped.
+ */
+export declare const kmsWrap: (_dek: Buffer, _keyId: string) => Promise<Buffer>;
+export declare const kmsUnwrap: (_wrapped: Buffer, _keyId: string) => Promise<Buffer>;
+//# sourceMappingURL=kms-envelope.kms-adapter.d.ts.map

package/helpers/kms-envelope.kms-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-envelope.kms-adapter.d.ts","sourceRoot":"","sources":["../../src/helpers/kms-envelope.kms-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,OAAO,GAClB,MAAM,MAAM,EACZ,QAAQ,MAAM,KACb,OAAO,CAAC,MAAM,CAKhB,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,QAAQ,MAAM,KACb,OAAO,CAAC,MAAM,CAKhB,CAAC"}

package/helpers/kms-envelope.kms-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-envelope.kms-adapter.js","sourceRoot":"","sources":["../../src/helpers/kms-envelope.kms-adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEI,MAAM,OAAO,GAAG,KAAK,EAC1B,IAAY,EACZ,MAAc,EACG,EAAE;IACnB,MAAM,IAAI,KAAK,CACb,uEAAuE;QACrE,gFAAgF,CACnF,CAAC;AACJ,CAAC,CAAC;AARW,QAAA,OAAO,WAQlB;AAEK,MAAM,SAAS,GAAG,KAAK,EAC5B,QAAgB,EAChB,MAAc,EACG,EAAE;IACnB,MAAM,IAAI,KAAK,CACb,yEAAyE;QACvE,gFAAgF,CACnF,CAAC;AACJ,CAAC,CAAC;AARW,QAAA,SAAS,aAQpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/backend-legacy",
-  "version": "0.0.83",
+  "version": "0.0.84",
   "description": "Backend executable CRUD functions with dynamic variables construction, and type definitions for the Adaptic AI platform.",
   "type": "module",
   "types": "index.d.ts",
@@ -24,6 +24,8 @@
     "validators/",
     "config/",
     "middleware/",
+    "types/",
+    "helpers/",
     "*.d.ts",
     "*.js",
     "*.cjs",

package/types/llm-configuration.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LLM_CONFIGURATION = void 0;
+/**
+ * Built-in safe defaults consumed by effectiveLlmConfig() as the
+ * lowest-precedence layer.
+ */
+exports.DEFAULT_LLM_CONFIGURATION = {
+    defaultProvider: 'OPENAI',
+    miniProvider: 'OPENAI',
+    normalProvider: 'OPENAI',
+    advancedProvider: 'ANTHROPIC',
+    miniModel: 'gpt-5.5',
+    normalModel: 'gpt-5',
+    advancedModel: 'claude-opus-4-7',
+    apiKeys: {},
+};
+//# sourceMappingURL=llm-configuration.js.map

package/types/llm-configuration.d.ts

@@ -0,0 +1,42 @@
+import type { EncryptedApiKey } from '../helpers/kms-envelope';
+export type LlmProvider = 'OPENAI' | 'ANTHROPIC' | 'DEEPSEEK' | 'KIMI' | 'QWEN' | 'XAI' | 'GEMINI';
+/**
+ * Canonical LlmConfigurationJson shape stored at:
+ *   Organization.llmDefaults  (org-wide defaults)
+ *   Fund.llmOverrides         (fund-level overrides)
+ *
+ * Read-time merging is precedence-ordered (charter §2.4 F6, spec §4.3):
+ *   built-in DEFAULT_LLM_CONFIGURATION → Org.llmDefaults → Fund.llmOverrides
+ *
+ * Consumers MUST use `effectiveLlmConfig()` from
+ * `@adaptic/backend-legacy/helpers/effective-llm-config`.
+ *
+ * API keys (`apiKeys.<provider>`) are stored as EncryptedApiKey
+ * envelopes; encrypt/decrypt is gated by org-membership role per
+ * spec §4.3.
+ */
+export interface LlmConfigurationJson {
+    /** Provider used when a tier-specific provider is unset. */
+    defaultProvider?: LlmProvider;
+    /** Per-tier provider overrides (null = inherit from defaultProvider). */
+    miniProvider?: LlmProvider;
+    normalProvider?: LlmProvider;
+    advancedProvider?: LlmProvider;
+    /** Per-tier model id strings (e.g. "gpt-5.5", "claude-opus-4-7"). */
+    miniModel?: string;
+    normalModel?: string;
+    advancedModel?: string;
+    /**
+     * Per-provider API keys, stored at rest as EncryptedApiKey envelopes.
+     * Plaintext only ever crosses the GraphQL mutation boundary.
+     */
+    apiKeys?: Partial<Record<Lowercase<LlmProvider>, EncryptedApiKey>>;
+}
+/**
+ * Built-in safe defaults consumed by effectiveLlmConfig() as the
+ * lowest-precedence layer.
+ */
+export declare const DEFAULT_LLM_CONFIGURATION: Required<Omit<LlmConfigurationJson, 'apiKeys'>> & {
+    apiKeys: NonNullable<LlmConfigurationJson['apiKeys']>;
+};
+//# sourceMappingURL=llm-configuration.d.ts.map

package/types/llm-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-configuration.d.ts","sourceRoot":"","sources":["../../src/types/llm-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,GACN,KAAK,GACL,QAAQ,CAAC;AAEb;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,WAAW,CAAC;IAC9B,yEAAyE;IACzE,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,cAAc,CAAC,EAAE,WAAW,CAAC;IAC7B,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;CACpE;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAC9C,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,CACtC,GAAG;IACF,OAAO,EAAE,WAAW,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC;CAUvD,CAAC"}

package/types/llm-configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-configuration.js","sourceRoot":"","sources":["../../src/types/llm-configuration.ts"],"names":[],"mappings":";;;AA4CA;;;GAGG;AACU,QAAA,yBAAyB,GAIlC;IACF,eAAe,EAAE,QAAQ;IACzB,YAAY,EAAE,QAAQ;IACtB,cAAc,EAAE,QAAQ;IACxB,gBAAgB,EAAE,WAAW;IAC7B,SAAS,EAAE,SAAS;IACpB,WAAW,EAAE,OAAO;IACpB,aAAa,EAAE,iBAAiB;IAChC,OAAO,EAAE,EAAE;CACZ,CAAC"}

package/types/policy-overlay.cjs

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=policy-overlay.js.map

package/types/policy-overlay.d.ts

@@ -0,0 +1,40 @@
+import type { TradingPolicyJson } from './trading-policy';
+export type OverlayType = 'RISK_GATE' | 'NEWS_GATE' | 'COMPLIANCE_GATE' | 'MANUAL_HALT' | 'CIRCUIT_BREAKER';
+export type OverlaySeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export type OverlayStatus = 'ACTIVE' | 'EXPIRED' | 'DEACTIVATED';
+/**
+ * Active and recent policy overlays stored on `Fund.policyOverlays`
+ * (Json[] column) per charter §2.4 F4 and spec §4.4.
+ *
+ * `effectivePolicy()` filters this list to entries where
+ * `status === 'ACTIVE' && (expiresAt == null || expiresAt > now)`,
+ * sorts by severity ascending (CRITICAL last → highest precedence),
+ * and deep-merges each overlay's `mutations` over the policy chain.
+ *
+ * On every status flip away from ACTIVE the engine archiver moves
+ * the entry to Tier-A `PolicyOverlayHistory` and removes it from this
+ * array atomically (one DB transaction). Steady-state size ≤ 20.
+ */
+export interface PolicyOverlayEntry {
+    /** UUID for cross-referencing with Tier-A PolicyOverlayHistory. */
+    id: string;
+    overlayType: OverlayType;
+    /** Source service that activated this overlay (e.g. "engine.risk.var-breach"). */
+    source: string;
+    /** Human-readable reason; surfaced in alerts. */
+    reason: string;
+    severity: OverlaySeverity;
+    /** Policy paths to override while ACTIVE. */
+    mutations: Partial<TradingPolicyJson>;
+    status: OverlayStatus;
+    /** ISO-8601 activation timestamp. */
+    activatedAt: string;
+    /** ISO-8601 expiry timestamp; absence means "until manually deactivated". */
+    expiresAt?: string;
+    deactivatedAt?: string;
+    deactivatedBy?: string;
+    /** Correlation id linking this overlay to the event that triggered it. */
+    correlationId?: string;
+    triggerEventId?: string;
+}
+//# sourceMappingURL=policy-overlay.d.ts.map

package/types/policy-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-overlay.d.ts","sourceRoot":"","sources":["../../src/types/policy-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,iBAAiB,CAAC;AAEtB,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAErE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,WAAW,CAAC;IACzB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,CAAC;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/types/policy-overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-overlay.js","sourceRoot":"","sources":["../../src/types/policy-overlay.ts"],"names":[],"mappings":""}

package/types/trading-policy.cjs

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TRADING_POLICY = void 0;
+/**
+ * Built-in safe defaults consumed by effectivePolicy() as the
+ * lowest-precedence layer. Tunings here are conservative and broadly
+ * safe; `@adaptic/utils` re-exports a more tuned variant for short-horizon
+ * day trading (see utils U1 plan).
+ */
+exports.DEFAULT_TRADING_POLICY = {
+    autonomy: {
+        enableAutoEntry: false,
+        enableAutoExit: true,
+        enableAutoRebalance: false,
+        requireHumanApprovalAboveNotional: 100000,
+    },
+    risk: {
+        maxPortfolioVarPct: 0.05,
+        maxSinglePositionPct: 0.1,
+        maxSectorExposurePct: 0.3,
+        maxAssetClassPct: { equity: 1.0, crypto: 0.2, options: 0.2 },
+        minBuyingPowerReservePct: 0.05,
+    },
+    allocation: {
+        perTradeEquityPct: 0.05,
+        perTradeCryptoPct: 0.05,
+        perTradeOptionsPct: 0.02,
+        autoAllocation: true,
+    },
+    scalping: {
+        enableScalping: false,
+        maxConcurrentScalps: 0,
+        minHoldSeconds: 0,
+        maxHoldSeconds: 0,
+        profitTargetBps: 0,
+        stopLossBps: 0,
+        requireRSIConfirm: false,
+        requireMACDConfirm: false,
+        requireVolumeSurge: false,
+        cooldownAfterLossMs: 0,
+        cooldownAfterWinMs: 0,
+        maxScalpsPerSession: 0,
+    },
+    compliance: {
+        equityWashTradeCooldownMs: 0,
+        restrictedTickerOverrides: [],
+        requireAuditLogForAll: true,
+    },
+    assetClasses: { equity: true, crypto: false, options: false },
+    sentiment: {
+        minSentimentScoreToEnter: 0,
+        maxNegativeSentimentToHold: -0.5,
+        requireRecentNews: false,
+        newsLookbackMinutes: 1440,
+    },
+    backtest: {
+        defaultUniverse: [],
+        defaultPeriodDays: 30,
+        defaultStrategyId: '',
+    },
+    runtime: {
+        enginePersonalityProfile: 'balanced',
+        signalRoutingRules: null,
+        manualOverrideAllowlist: [],
+        riskOverrideJustifications: [],
+        enableShadowMode: false,
+        experimentBucket: null,
+    },
+};
+//# sourceMappingURL=trading-policy.js.map

package/types/trading-policy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Canonical TradingPolicyJson shape stored at:
+ *   Organization.tradingDefaults  (org-wide defaults)
+ *   Fund.tradingOverrides         (fund-level overrides)
+ *
+ * Read-time merging is precedence-ordered (charter §2.2, spec §4.2.2):
+ *   built-in DEFAULT_TRADING_POLICY → Org.tradingDefaults
+ *     → Fund.tradingOverrides → active Fund.policyOverlays
+ *     → 14 per-BrokerageAccount column overrides
+ *
+ * Consumers MUST use `effectivePolicy()` from
+ * `@adaptic/backend-legacy/helpers/effective-policy` — do NOT
+ * re-implement the precedence chain.
+ */
+export interface TradingPolicyJson {
+    /** Autonomy — when the engine is allowed to act without human approval. */
+    autonomy?: {
+        enableAutoEntry?: boolean;
+        enableAutoExit?: boolean;
+        enableAutoRebalance?: boolean;
+        requireHumanApprovalAboveNotional?: number;
+    };
+    /** Risk caps applied per-strategy and per-portfolio. */
+    risk?: {
+        /** Maximum portfolio Value-at-Risk as a fraction (0..1). */
+        maxPortfolioVarPct?: number;
+        /** Maximum single-position weight as a fraction (0..1). */
+        maxSinglePositionPct?: number;
+        /** Maximum sector exposure as a fraction (0..1). */
+        maxSectorExposurePct?: number;
+        /** Per-asset-class caps as fractions of NAV. */
+        maxAssetClassPct?: {
+            equity?: number;
+            crypto?: number;
+            options?: number;
+        };
+        /** Minimum buying-power reserve as a fraction (0..1). */
+        minBuyingPowerReservePct?: number;
+    };
+    /** Per-trade allocation defaults (SR's tradeAllocationPct collapsed here). */
+    allocation?: {
+        perTradeEquityPct?: number;
+        perTradeCryptoPct?: number;
+        perTradeOptionsPct?: number;
+        autoAllocation?: boolean;
+    };
+    /** Scalping / intraday-specific policy (12 W3-3 fields from SR commit 10b63819d). */
+    scalping?: {
+        enableScalping?: boolean;
+        maxConcurrentScalps?: number;
+        minHoldSeconds?: number;
+        maxHoldSeconds?: number;
+        profitTargetBps?: number;
+        stopLossBps?: number;
+        requireRSIConfirm?: boolean;
+        requireMACDConfirm?: boolean;
+        requireVolumeSurge?: boolean;
+        cooldownAfterLossMs?: number;
+        cooldownAfterWinMs?: number;
+        maxScalpsPerSession?: number;
+    };
+    /** Compliance — FINRA / SEC operational rules. */
+    compliance?: {
+        /** FINRA 5210 wash-trade cooldown in milliseconds. */
+        equityWashTradeCooldownMs?: number;
+        /** Tickers explicitly excluded from autonomous trading. */
+        restrictedTickerOverrides?: string[];
+        /** Force AuditLog row creation on every order. */
+        requireAuditLogForAll?: boolean;
+    };
+    /** Asset-class enablement (defaults set in DEFAULT_TRADING_POLICY). */
+    assetClasses?: {
+        equity?: boolean;
+        crypto?: boolean;
+        options?: boolean;
+    };
+    /** Sentiment / news subscription policy (fund-scope per charter §2.4 F5). */
+    sentiment?: {
+        minSentimentScoreToEnter?: number;
+        maxNegativeSentimentToHold?: number;
+        requireRecentNews?: boolean;
+        newsLookbackMinutes?: number;
+    };
+    /** Backtest scope (fund-scope per charter §2.4 F7). */
+    backtest?: {
+        defaultUniverse?: string[];
+        defaultPeriodDays?: number;
+        defaultStrategyId?: string;
+    };
+    /**
+     * Engine runtime config (charter §2.4 F1/F8/F9 catch-all).
+     *
+     * Populated when sub-project 6 (engine port) has not yet committed
+     * to owning `EngineFundConfig` in Tier-A. Carries the 6 SR
+     * `TradingPolicy` policy-shape fields that have no canonical JSON
+     * home: enginePersonalityProfile, signalRoutingRules,
+     * manualOverrideAllowlist, riskOverrideJustifications,
+     * enableShadowMode, experimentBucket.
+     *
+     * If/when sub-project 6 promotes these to Tier-A, this group can be
+     * migrated out and removed.
+     */
+    runtime?: {
+        enginePersonalityProfile?: string;
+        signalRoutingRules?: unknown;
+        manualOverrideAllowlist?: string[];
+        riskOverrideJustifications?: unknown[];
+        enableShadowMode?: boolean;
+        experimentBucket?: string | null;
+    };
+}
+/**
+ * Built-in safe defaults consumed by effectivePolicy() as the
+ * lowest-precedence layer. Tunings here are conservative and broadly
+ * safe; `@adaptic/utils` re-exports a more tuned variant for short-horizon
+ * day trading (see utils U1 plan).
+ */
+export declare const DEFAULT_TRADING_POLICY: Required<TradingPolicyJson>;
+//# sourceMappingURL=trading-policy.d.ts.map

package/types/trading-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trading-policy.d.ts","sourceRoot":"","sources":["../../src/types/trading-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE;QACT,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,iCAAiC,CAAC,EAAE,MAAM,CAAC;KAC5C,CAAC;IAEF,wDAAwD;IACxD,IAAI,CAAC,EAAE;QACL,4DAA4D;QAC5D,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,2DAA2D;QAC3D,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,oDAAoD;QACpD,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,gDAAgD;QAChD,gBAAgB,CAAC,EAAE;YACjB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC;QACF,yDAAyD;QACzD,wBAAwB,CAAC,EAAE,MAAM,CAAC;KACnC,CAAC;IAEF,8EAA8E;IAC9E,UAAU,CAAC,EAAE;QACX,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IAEF,qFAAqF;IACrF,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF,kDAAkD;IAClD,UAAU,CAAC,EAAE;QACX,sDAAsD;QACtD,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,2DAA2D;QAC3D,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;QACrC,kDAAkD;QAClD,qBAAqB,CAAC,EAAE,OAAO,CAAC;KACjC,CAAC;IAEF,uEAAuE;IACvE,YAAY,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF,6EAA6E;IAC7E,SAAS,CAAC,EAAE;QACV,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,0BAA0B,CAAC,EAAE,MAAM,CAAC;QACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF,uDAAuD;IACvD,QAAQ,CAAC,EAAE;QACT,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IAEF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE;QACR,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;QACnC,0BAA0B,CAAC,EAAE,OAAO,EAAE,CAAC;QACvC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;CACH;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,iBAAiB,CA2D9D,CAAC"}

package/types/trading-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trading-policy.js","sourceRoot":"","sources":["../../src/types/trading-policy.ts"],"names":[],"mappings":";;;AAwHA;;;;;GAKG;AACU,QAAA,sBAAsB,GAAgC;IACjE,QAAQ,EAAE;QACR,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,mBAAmB,EAAE,KAAK;QAC1B,iCAAiC,EAAE,MAAO;KAC3C;IACD,IAAI,EAAE;QACJ,kBAAkB,EAAE,IAAI;QACxB,oBAAoB,EAAE,GAAG;QACzB,oBAAoB,EAAE,GAAG;QACzB,gBAAgB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE;QAC5D,wBAAwB,EAAE,IAAI;KAC/B;IACD,UAAU,EAAE;QACV,iBAAiB,EAAE,IAAI;QACvB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,IAAI;QACxB,cAAc,EAAE,IAAI;KACrB;IACD,QAAQ,EAAE;QACR,cAAc,EAAE,KAAK;QACrB,mBAAmB,EAAE,CAAC;QACtB,cAAc,EAAE,CAAC;QACjB,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,CAAC;QAClB,WAAW,EAAE,CAAC;QACd,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,KAAK;QACzB,kBAAkB,EAAE,KAAK;QACzB,mBAAmB,EAAE,CAAC;QACtB,kBAAkB,EAAE,CAAC;QACrB,mBAAmB,EAAE,CAAC;KACvB;IACD,UAAU,EAAE;QACV,yBAAyB,EAAE,CAAC;QAC5B,yBAAyB,EAAE,EAAE;QAC7B,qBAAqB,EAAE,IAAI;KAC5B;IACD,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;IAC7D,SAAS,EAAE;QACT,wBAAwB,EAAE,CAAC;QAC3B,0BAA0B,EAAE,CAAC,GAAG;QAChC,iBAAiB,EAAE,KAAK;QACxB,mBAAmB,EAAE,IAAI;KAC1B;IACD,QAAQ,EAAE;QACR,eAAe,EAAE,EAAE;QACnB,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;KACtB;IACD,OAAO,EAAE;QACP,wBAAwB,EAAE,UAAU;QACpC,kBAAkB,EAAE,IAAI;QACxB,uBAAuB,EAAE,EAAE;QAC3B,0BAA0B,EAAE,EAAE;QAC9B,gBAAgB,EAAE,KAAK;QACvB,gBAAgB,EAAE,IAAI;KACvB;CACF,CAAC"}