Viska IBKR Flex Feature — Engineering Map

§1Overview & Client User-Journey

The IBKR Flex ingest feature is the data pipeline that turns Viska's live Interactive Brokers account into the fund state the viska.gg dashboard renders. An n8n workflow on Hostinger pulls daily Flex statements from IBKR, normalizes them to metadata, hands the raw XML to a standalone apply-svc on Railway that re-parses it and is the sole writer of the trading.* schema, which projects up into the public.* views the frontend reads.

This is a thin-transport / authoritative-writer split: n8n moves bytes and holds zero database or storage credentials, while apply-svc owns every write to trading.* behind a single bearer gate. apply_service.py:35-44 The pipeline fires nightly via a 22:30 cron on the live n8n workflow; an on-demand viska.gg pull is DESIGN-APPROVED, NOT BUILT. on-demand-webhook-design.md:6,109-117

End-to-End Client User Journey

Current State — KPI Strip

Components at a Glance

§2Hosting Topology & Dependencies

The IBKR Flex feature is a two-host pipeline: an n8n orchestrator on Hostinger (thin transport, zero DB/storage credential) and an apply-svc on Railway that re-parses the raw XML and is the sole SSOT writer of trading.*. Three external/managed services back them: IBKR Flex Web Service (source), Supabase Postgres + Storage (sink), and Cloudflare Access (dashboard auth only — not in the ingest path). The two Railway services — apply-svc and the Mastra/Mímir agent — are distinct and must never be conflated.

The chain (end to end)

Schedule (22:30 Mon-Fri) ─┐
                          ├→ Init → Flex SendRequest (httpQueryAuth, ndcdyn) → poll loop ($runIndex < 6)
Webhook (POST, headerAuth)┘   → Flex GetStatement (dynamic {{ FlexStatementResponse.Url }}, observed gdcdyn)
                              → Parse XML → Normalize (multi-day) → "Statement Usable?" guard
                                  (position_count > 0 AND report_date notEmpty)
                              → Sign Upload (POST /sign-upload, bearer) → PUT raw XML (signed URL, auth:none)
                                  → flex-inbox bucket  (flex/<report_date>/<execId>.xml)
                              → Apply POST (POST /apply, bearer) → apply-svc RE-PARSES XML → writes trading.*
                                  → object moved to processed/ on success

n8n holds zero trading writes and zero storage credential; apply-svc is the SSOT parser of the raw XML and the only writer to trading.*. The Upsert Positions node (f694c363…) was removed — replaced by Sign Upload → Upload → Apply POST. flex-multiday-normalize-apply-contract.md:54-56 flex-pull-rescope-ops.md:23-24,31,83-89

Dependency table

flex-pull-rescope-ops.md:14,23-24,62 flex-multiday-normalize-apply-contract.md:54-56,63-68 apply_service.py:35-44 cio-ratification-ibkr-feed-gaps-A-H.md:63 on-demand-webhook-design.md:136-137

IBKR host nuance — ndcdyn vs gdcdyn

Credential inventory (bindings only — no values)

flex-pull-rescope-ops.md:8-13,16,24,54,62-65,76 apply_service.py:6-9,35-44,46,66-70,182-186,326-340 on-demand-webhook-design.md:111-113 chronicle-2026-06-22:389

Deploy-state & open caveats

• Apply POST body key — handler truth = object_path (apply_service.py:146, 400s on missing); n8n node spec sends path (rescope-ops:78). This mismatch is an unreconciled OPEN — reconciliation state UNKNOWN. Contract = {bucket, object_path}; never assert path works end-to-end. rescope-ops:78,80
• PUT-leg auth shape — whether the signed-upload PUT needs the returned token as a header vs query-string self-auth is OPEN UNKNOWN. rescope-ops:67-70
• On-demand webhook — 2nd Webhook trigger, onReceived 202-async, native Header Auth, n8n 5-min static-data cooldown — DESIGN-APPROVED, NOT BUILT (blocked on N8N_API_URL/N8N_API_KEY + secret mint). Exact webhook path string UNKNOWN. on-demand-webhook-design.md:6,109-117
• Live node ids for Sign Upload / Upload / Apply POST UNKNOWN (raw JSON gated). rescope-ops
• Supabase project ref behind VISKA_SUPABASE_URL — binding-only by policy, not read. Whether Cloudflare also serves Pages/DNS for viska.gg surfaces is UNKNOWN; only its CF Access (dashboard auth) role is confirmed.

§3Source Data & the IBKR Flex Handshake

The trading-intelligence pipeline draws one source: the IBKR Flex Web Service. A single Activity Flex query returns the full daily series (~22 <FlexStatement> in one FlexQueryResponse) via a 2-call async handshake on Hostinger n8n. n8n is thin transport holding zero DB/storage credential; the Railway apply-svc re-parses the raw XML and is the sole SSOT writer of trading.*.

3.1 — The Flex query

A single pull returns the full daily series in one FlexQueryResponse. The earlier "one pull = one report_date" framing was explicitly retracted. multiday-contract:23-24

3.2 — The two-call async handshake

IBKR Flex is a request → poll pattern (no push). Live-proven end-to-end through Normalize by operator test (exec 35607). SendRequest is pinned to ndcdyn in the live node; the <Url> IBKR returns came back on gdcdyn, so both GetStatement URLs follow {{ FlexStatementResponse.Url }} dynamically. flex-pull-...json:85; chronicle:389(3)

Call 1 — SendRequest (request XML)

GET https://ndcdyn.interactivebrokers.com/Universal/servlet/
      FlexStatementService.SendRequest?t=<FLEX_TOKEN>&q=1384817&v=3

→ FlexStatementResponse:

<FlexStatementResponse timestamp="...">
  <Status>Success</Status>                  <!-- Success | Warn | Fail -->
  <ReferenceCode>NNNNNNNNNN</ReferenceCode>
  <Url>https://gdcdyn.interactivebrokers.com/Universal/servlet/
       FlexStatementService.GetStatement</Url>
</FlexStatementResponse>

• n8n node Flex SendRequest, auth = httpQueryAuth cred IBKR flex — token bound as query param t, never in body. build:24,38; chronicle:389(1)
• Parsed by Parse SendRequest XML → gate SendRequest OK?; on Fail → Slack Flex Generation Failed. build:24-29; chronicle:389(5)
• <ReferenceCode> + <Url> confirmed returned live. chronicle:389(3)

Call 2 — GetStatement (poll loop)

GET {{ FlexStatementResponse.Url }}?t=<FLEX_TOKEN>&q=<ReferenceCode>&v=3
    (node Flex GetStatement, responseFormat:text → raw XML at $json.data)

Poll loop (bounded, NOT fixed 2-shot):
   Statement Ready?  ──false──▶  Max Tries? {{$runIndex}} < 6
        │true                         │true            │false
        ▼                             ▼                ▼
   FlexQueryResponse            Wait Retry ↺      Flex Timeout Alert
   (data document)             Flex GetStatement      → Respond

• Bounded poll loop $runIndex < 6 — refactored live from a 2-shot scaffold after a Status=Warn not-ready race. chronicle:389(4); build:36
• Not-ready signal: GetStatement returns the same FlexStatementResponse envelope with <Status>Warn</Status> (still generating) instead of the FlexQueryResponse data document — the gate distinguishes these. domain finding §2

Live write-path node ids

3.3 — The FlexQueryResponse data document

Reconstructed verbatim from the parser's .get(...) targets (flex_to_sections.py) and the canonical test fixture (test_flex.py:20-48,123-137). Attribute names are the actual strings the parser reads.

<FlexQueryResponse queryName="t" type="AF">                       <!-- test_flex.py:20,127 -->
  <FlexStatements count="22">                                    <!-- multiday-contract:17 -->
    <FlexStatement accountId="U22131377"                        <!-- :51-53 _account_id -->
                   fromDate="20260514" toDate="20260514"        <!-- :134-137 period bounds -->
                   period="Last30CalendarDays"
                   whenGenerated="20260615;..." >               <!-- re-stamped every pull -->

      <AccountInformation accountId="U22131377" currency="USD" />   <!-- :54 fallback acct -->

      <!-- ===== OpenPositions → instruments + positions_snapshots ===== -->
      <OpenPosition reportDate="20260514"                       <!-- :38,72 latest-rd selector -->
                    levelOfDetail="SUMMARY"                       <!-- :74 SUMMARY-only filter -->
                    symbol="AA" conid="100" description="Alcoa"   <!-- :80-81 -->
                    isin="US0138721065" listingExchange="NYSE"    <!-- :81 isin→Security ID -->
                    multiplier="1" assetCategory="STK"            <!-- :82 -->
                    currency="USD" position="200"                 <!-- :83 position→Quantity -->
                    costBasisPrice="30" costBasisMoney="6000"     <!-- :84-85 -->
                    markPrice="35" positionValue="7000"           <!-- :85 markPrice→Close -->
                    fifoPnlUnrealized="1000"                      <!-- :86 →Unrealized P/L -->
                    percentOfNAV="..." fxRateToBase="..." />      <!-- Normalize-only; NOT flex_to_sections -->
      <!-- ... one OpenPosition per holding, 25–31 per day ... -->

      <!-- ===== EquitySummaryInBase → nav_snapshots ===== -->
      <EquitySummaryByReportDateInBase reportDate="20260514"     <!-- :93-94 -->
                    currency="USD" cash="500" stock="1000"        <!-- :96-97 -->
                    total="1500" />                               <!-- :98 total→NAV total -->

      <!-- ===== FxPositions → fx_balances ===== -->
      <FxPosition reportDate="20260514" levelOfDetail="SUMMARY"  <!-- :105-108 -->
                  functionalCurrency="USD" fxCurrency="EUR"       <!-- :110 fxCurrency→Description -->
                  quantity="1000" costBasis="-1100"               <!-- :113 -->
                  value="1100" unrealizedPL="5" />                <!-- :113-114 -->

      <!-- ===== Activity-Flex extras: parsed by n8n Normalize only ===== -->
      <CashReport>                                               <!-- multiday-contract:106-108 -->
        <CashReportCurrency currency="USD"
                            endingCash="..." endingSettledCash="..." />
      </CashReport>
      <!-- Trades / Dividends / CashTransaction: CSV path, NOT Flex Phase-1 -->

    </FlexStatement>
    <!-- ... 21 more FlexStatement, one per trading day ... -->
  </FlexStatements>
</FlexQueryResponse>

Parse guards (flex_to_sections.py): _safe_parse (:25-33) rejects any <!DOCTYPE>/<!ENTITY> (XXE / billion-laughs guard, stdlib-only) — a genuine FlexQueryResponse carries neither. levelOfDetail filter (:74, :108): only SUMMARY (or empty) rows pass; LOT-level rows dropped. flex_to_sections.py:25-33,74,108

3.4 — Source stream → trading.* coverage matrix

Two parsers consume the document with different coverage: flex_to_sections.py (the live apply-svc path) lands the Phase-1 snapshot only; ibkr_import.emit() has the full machinery but the trade/dividend/cash/interest sections populate only on the CSV path.

3.5 — From XML to trading.*: the write path

The raw FlexQueryResponse reaches trading.* via the Railway apply-svc, not n8n. n8n Normalize output is metadata/guard/filename only — it never drives the DB write.

n8n (thin transport):
  Sign Upload  ──POST /sign-upload (bearer)──▶ apply-svc mints signed URL
  Upload Flex XML ──PUT raw FlexQueryResponse to signed URL (auth: none)──▶ flex-inbox bucket
  Apply POST   ──POST /apply (bearer, body {bucket, object_path})──▶ apply-svc

apply-svc (SSOT writer):
  fetch object (service_role) → flex_to_sections.build_sections_by_day
    → ibkr_import.emit_days → ONE idempotent BEGIN…COMMIT → trading.*

Apply POST body — the key contract

POST /apply
Authorization: Bearer <FLEX_APPLY_WEBHOOK_SECRET>   (constant-time compare, 401-before-I/O)
Content-Type: application/json

{
  "bucket": "flex-inbox",
  "object_path": "flex/U22131377/20260619/FlexQueryResponse.xml"
}

Multiday landing & idempotency

The empty-statement guard

IF "Statement Usable?" (position_count > 0 AND report_date notEmpty) sits between Normalize and Sign Upload (commit f8a0304, activeVersionId 6aa4c859). False branch → Flag Unmapped Conids → Respond, skipping Sign/Upload/Apply (no empty overwrite). Reason: IBKR toDate floats → empty next-day snapshot (exec 35606, reportDate 2026-06-20, 0 positions). git show f8a0304; chronicle.md:17-32

3.6 — Credential bindings (names only)

3.7 — UNKNOWN / unconfirmed (this domain)

• CashTransaction — named in the prompt but in no importer file or spec; no section key, no table. Cannot confirm it is consumed. (CashReport/CashReportCurrency is read by n8n Normalize but lands nowhere.) UNKNOWN
• SendRequest/GetStatement not-ready XML attributes beyond <Status>/<ReferenceCode>/<Url> — raw envelope not committed (gated). UNKNOWN
• SendRequest / GetStatement / Wait / Init node ids — fetched node table lists only the 5 write-path nodes. UNKNOWN
• Apply PUT-leg auth shape + the path-vs-object_path live reconciliation — both OPEN. UNKNOWN
• Sign Upload / Upload / Apply POST live node ids — raw JSON gated. UNKNOWN
• Live image SHA running Fix A on Railway — unfingerprinted (RAILWAY_TOKEN unset). Fix A is code-confirmed (f810998, 75 tests) but live-deploy-unconfirmed; do not claim "22/22 lands in prod." UNKNOWN

§4The n8n Workflow — Node by Node

Workflow ADeTjBZiHOMIXzvr — "Viska Macro Daily — IBKR Flex Pull" — runs on Hostinger n8n and is the thin transport of the IBKR ingest path. It pulls a multi-day Flex statement from IBKR, guards it, and drops the raw XML to the Railway apply-svc via a signed URL. It holds zero DB/storage credential and does zero trading writes — the apply-svc re-parses the raw XML and is the sole SSOT writer of trading.*. flex-pull-...json:85; multiday-contract:50-52

Live state & evolution

Live node graph (17-node design → current wiring)

┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TRIGGERS (two entry points, converge on Init Params)                                  │
└─────────────────────────────────────────────────────────────────────────────────────┘

  [Daily Schedule (EOD)]            scheduleTrigger   cron 0 30 22 * * 1-5  (22:30 Mon–Fri)
        │
        ├──────────────────────────────────────┐
  [On-Demand Pull]                              │   webhook, authentication: headerAuth
        │  (2nd entry; 202 onReceived async)    │   DESIGN-APPROVED, cooldown NOT BUILT
        └──────────────────────────────────────┤
                                                ▼
                                        [Init Params]   Set/Code — seeds run params
                                                │
                                                ▼
                        [Flex SendRequest]   httpRequest, auth=httpQueryAuth
                        q={query 1384817}, v=3, t=text   ── cred "IBKR flex"
                        host PINNED ndcdyn   → returns FlexStatementResponse XML
                                                │
                                                ▼
                        [Parse SendRequest XML]   xml node
                                                │
                                                ▼
                      ┌──── [SendRequest OK?]  IF (Status == Success?) ────┐
                      │ true                                          false │
                      ▼                                                     ▼
              [Wait For Report]   wait                       [Flex Generation Failed]  Slack
                      │                                                     │
                      ▼                                                     ▼
    ┌────────►[Flex GetStatement]  httpRequest                         [Respond]
    │  id 4531f9c5-bbdc-4f40-9639-680ab3f5aa2d
    │  url = {{ FlexStatementResponse.Url }}  (DYNAMIC — observed gdcdyn host)
    │  responseFormat: text → $json.data = raw FlexQueryResponse XML
    │                 │
    │                 ▼
    │        [Parse Statement XML]   xml node
    │                 │
    │                 ▼
    │     ┌─── [Statement Ready?]  IF (statement generated?) ───┐
    │     │ false                                          true │
    │     ▼                                                     ▼
    │  [Max Tries?]  IF ({{$runIndex}} < 6)         [Normalize Flex Dataset]
    │     │ true                  │ false              id 28992ad5-b0e7-491f-8f5f-7b001802fe6e
    │     ▼                       ▼                             │ Code (flex-normalize.js body)
    │  [Wait Retry]   [Flex Timeout Alert]  Slack              │ multi-day: Σ positions,
    │     │                       │                            │ latest report_date, days[]
    └─────┘                       ▼                            ▼
     (loop GetStatement)      [Respond]         ┌── [Statement Usable?]  IF ──┐
                                                │ true                  false │
                                                │ (pos_count>0 AND          │ (empty/next-day
                                                │  report_date notEmpty)      │  snapshot — skip)
                                                ▼                             │
                                       [Sign Upload]  httpRequest POST        │
                                       {apply-svc}/sign-upload  (headerAuth)  │
                                       cred "Viska: Flex Webhook Auth"        │
                                       body {bucket:flex-inbox, object_path}  │
                                       → {ok,bucket,path,signedUrl,token}     │
                                                │                             │
                                                ▼                             │
                                       [Upload Flex XML]  httpRequest PUT      │
                                       url = {{ Sign Upload.signedUrl }}      │
                                       auth: none (signed URL self-auth)      │
                                       body = {{ Flex GetStatement.data }}    │
                                       (raw 22-statement XML, application/xml) │
                                                │                             │
                                                ▼                             │
                                       [Apply POST]  httpRequest POST          │
                                       {apply-svc}/apply  (headerAuth)        │
                                       body {bucket, object_path: ...path}    │
                                       → {ok,reportDate,positions,fx,nav_rows}│
                                                │                             │
                                                ▼                             ▼
                                       [Flag Unmapped Conids] ◄───────────────┘
                                       id 902d95a5-17b8-4380-b33c-5c5f74db6ce7
                                                │
                                                ▼
                                       [Respond]
                                       id e6daefe1-b458-43aa-aae0-bb45d95b7cf4

  REMOVED: [Upsert Positions]  id f694c363-607a-4c18-8a84-57b5a5d8e444  (postgres)
           disabled → REMOVED; replaced by Sign Upload → Upload → Apply POST.
           n8n now holds ZERO trading-write credential.

Triggers

Pull & parse

Poll / retry loop

Normalize & empty-statement guard

Output shape (Fix B logic, scripts/lib/flex-normalize.js:46-53, 7/7 tests green; iterates all statements, keys positions on conid, preserves NULLs via toN/toS never 0):

{ report_date: <latest day>,           // → Sign Upload filename + Respond
  position_count: <Σ across all days>,  // → guard (passes if ANY day has data)
  statement_count, report_dates[],
  date_from, date_to,
  days[] }   // each: {report_date, positions[], nav, cash, fx, position_count}

Statement Usable? — IF (inserted 2026-06-22)

Empty-statement guard between Normalize and Sign Upload. Condition: position_count > 0 AND report_date notEmpty. true → Sign Upload (apply path). false → Flag Unmapped Conids → Respond, skipping Sign/Upload/Apply (no empty overwrite). Reason: IBKR Flex's floating toDate returns an empty next-day/weekend snapshot that would otherwise PUT empty XML and overwrite good trading.* data (live incident: exec 35606, reportDate 2026-06-20, 0 positions). Commit f8a0304, activeVersionId 6aa4c859. A dedicated Slack "no-data" alert on the false branch was left off to dodge the Slack resource-discriminator quirk. git show f8a0304; chronicle.md:17-32

Write path — signed-URL drop (replaces removed Upsert Positions)

Live execution evidence & the two distinct gaps

Single-day Apply POST (live, exec 35607) returned { ok:true, reportDate:20260619, positions:21, fx:5, nav_rows:3 }. chronicle-2026-06-22:502-503 Normalize had parsed 30 positions for that same day. These are two separate phenomena — never conflate:

Terminal & alert nodes

Credentials & node-id discipline

Open items

• On-demand webhook build (cooldown gate + 202 async) — design-approved, blocked on N8N_API_URL/N8N_API_KEY REST creds + auth-secret mint. webhook-design:109-117
• Normalize multi-day live node body — committed in lib, live update deferred to A+B-green deploy (Class C, viska-pm-routed PR). chronicle.md:54-62
• Apply body key — path (n8n) vs object_path (handler) reconciliation state UNKNOWN; PUT-token shape UNKNOWN. rescope-ops:67-70,80
• Not in sourced docs UNKNOWN: exact webhook path string; Wait/Wait-Retry durations; live Slack channel id; Init Params field contents; live Sign Upload / Upload / Apply POST node ids (raw JSON gated). raw JSON gated

§5Normalize & the Guards

The n8n side of the Flex pull is thin transport. Its "Normalize Flex Dataset" Code node and the two guards around it never write the database — they shape metadata, gate empty statements, and surface unmapped instruments. apply-svc on Railway re-parses the raw XML and is the sole SSOT writer of trading.*. flex-normalize.js:6-11; multiday-contract:50-52

Node map & identity

Statement Ready?[true]
  → Normalize Flex Dataset   (node id 28992ad5-b0e7-491f-8f5f-7b001802fe6e)
      → Statement Usable?     (IF guard — true/false branch)
  true → Sign Upload → Upload Flex XML → Apply POST → Flag Unmapped Conids → Respond
  false→ Flag Unmapped Conids → Respond            (skips Sign/Upload/Apply)

rescope-ops:30,32,37; chronicle.md:22-24

1. Normalize Flex Dataset

The Code node embeds a copy of normalizeFlexDataset because n8n Code nodes cannot import repo files; the tested SSOT for that body is scripts/lib/flex-normalize.js. Raw workflow JSON was not read (gated), so the lib is asserted-equal to the live node body, not independently diffed. flex-normalize.js:1-5 LIB=SSOT, LIVE NOT DIFFED

What it reads — four Activity-Flex blocks per <FlexStatement>

build-spec:33; flex-normalize.js:23-38

Every block is wrapped [].concat(… || []) so the single-statement-as-object case (n8n's XML parser collapses 1-element arrays to objects) and an empty/absent block both normalize to an array. flex-normalize.js:24,33,36; multiday-contract:80

Fix B — multi-day awareness (commit 2f12e5c)

Fix B iterates all statements ([].concat(...) then stmts.map) and adds the multi-day contract to the returned object: flex-normalize.js:19-21,42-54

• report_dates[] — every day's ISO date, sorted ascending flex-normalize.js:42-43
• position_count — sum across all days (days.reduce((s,d)=>s+d.position_count,0)), NOT day-0's count flex-normalize.js:48
• statement_count — days.length flex-normalize.js:49
• date_from / date_to — first/last of sorted report_dates flex-normalize.js:51-52
• report_date (top-level) — the latest day, so the Sign Upload filename flex-<latest>-<execId>.xml stays sensible while the uploaded file still holds all days flex-normalize.js:44,47; multiday-contract:10,135

Per-day object: { report_date, positions, nav, cash, fx, position_count: positions.length }; a .filter((d)=>d.report_date) drops statements with no resolvable date before they reach the guard. flex-normalize.js:39-40

Top-level emitted shape: { report_date, position_count, statement_count, report_dates, date_from, date_to, days }. report_date + position_count are the keys downstream nodes already read; the rest are additive — no downstream node breaks. Tests: 7/7 green in tests/ingestion/flex-normalize.test.js. flex-normalize.js:46-54; multiday-contract:79-80,137

conid-keying & NULL discipline

Each position keys on conid: toN(p.conid) — the join key is conid/isin, never ticker; unmapped (conid=null) positions are flagged back, not dropped. Carried per-position: symbol, isin, quantity, mark_price, position_value, cost_basis_price, cost_basis_money, fifo_pnl_unrealized, percent_of_nav, currency, asset_category, fx_rate_to_base. flex-normalize.js:25-29; build-spec:40-41

Two coercers ensure empty/undefined/null map to null, never 0:

toN = (v) => (v===undefined || v===null || v==='') ? null : Number(v)
toS = (v) => (v===undefined || v===null || v==='') ? null : String(v)
isoDate: YYYYMMDD => YYYY-MM-DD, or null if falsy

flex-normalize.js:13-15; build-spec:42

2. Guard — "Statement Usable?" (commit f8a0304)

f8a030499160ec3fc78b6fe506f21ac7982e0531 — "feat(flex): empty-statement guard on IBKR Flex pull (ADeTjBZiHOMIXzvr)", 2026-06-22 10:58:22 +0200. Landed in DRAFT then published — activeVersionId 6aa4c859. PUBLISHED git show f8a0304; chronicle.md:25-28

Condition: an IF node between Normalize and Sign Upload — position_count > 0 AND report_date notEmpty.

• True → Sign Upload → Upload → Apply POST (the apply path).
• False → Flag Unmapped Conids → Respond, skipping Sign/Upload/Apply; returns position_count:0, no empty write.

chronicle.md:22-24

With Fix B's summed position_count, the guard blocks only a wholly-empty file (every day empty); any one day with data passes. "Wrong-date" detection (report_date == last trading day) is explicitly out of scope. Applied via MCP update_workflow (5 atomic ops); not test-exec'd because mutating (fires IBKR + apply + DB) → Class C trading-writer critical-path, viska-pm-routed PR. multiday-contract:159; chronicle.md:25-32

3. Guard — "Flag Unmapped Conids" (node id 902d95a5-…)

Reads Normalize's output and reports back positions where conid resolved to null — the conid-mapping feedback path. The workflow writes raw IBKR fields only; the theme/sub_group overlay (trading.instrument_themes) is a downstream DB concern, untouched here. Unmapped positions are surfaced rather than silently dropped. build-spec:41,43-44

It is the penultimate node before Respond on both paths. Across the rescope its inbound connection moved from the removed Upsert Positions → Flag Unmapped Conids to Apply POST → Flag Unmapped Conids; on the guard's false branch it is reached via Normalize → Flag Unmapped Conids → Respond. Marked "keep" through the Upsert Positions removal — Normalize is kept precisely because it drives object_path + Flag Unmapped. rescope-ops:83-89,93; chronicle.md:23-24

Open / unknown in this domain

• Live n8n node body vs flex-normalize.js — not diffed (raw JSON gated; live update deferred). Lib is the tested SSOT, asserted-equal not verified-equal. multiday-contract:81-82
• The downstream 30→21 single-day count gap lives inside apply-svc parse/persist, not in Normalize — Normalize parsed 30 for that day; the loss is on the persist side. Cause INFERRED, not root-caused. Distinct from the multi-day 1-of-22 landing. ViskaN8N chronicle.md:7-14
• Sign Upload / Upload / Apply POST live node ids — UNKNOWN (raw JSON gated). —

§6Write Path — Sign-Upload, Apply, Real Payloads

The IBKR Flex mutating write path that lands raw FlexQueryResponse XML into Supabase trading.*. Three n8n nodes drive two Railway apply-svc endpoints plus one direct Supabase Storage PUT. n8n is thin transport holding zero DB/storage credential; apply-svc re-parses the raw XML and is the sole SSOT writer of trading.*.

6.0 Topology

Flex GetStatement (raw 22-stmt FlexQueryResponse XML, Hostinger n8n)
  → Parse Statement XML → Normalize Flex Dataset   (emits report_date + object_path; metadata/guard/filename ONLY, never the DB write)
  → Statement Usable? guard   (position_count > 0 AND report_date notEmpty)
  → [1] Sign Upload   POST {apply-svc}/sign-upload   bearer       → {ok, bucket, path, signedUrl, token}
  → [2] Upload Flex XML   PUT signedUrl   auth=none   raw XML     → object in flex-inbox bucket
  → [3] Apply POST   POST {apply-svc}/apply   bearer             → {ok, account, reportDate, report_dates, statements, positions, fx, nav_rows}
  → Flag Unmapped Conids → Respond

The raw 22-statement XML reaches apply-svc on the wire; apply-svc re-parses it as SSOT for report_date + positions — the n8n Normalize date only names the storage object. on-demand-webhook-design.md:70-76; flex-multiday-normalize-apply-contract.md:50-52

6.1 Node [1] — Sign Upload

n8n-nodes-base.httpRequest, POST {apply-svc}/sign-upload. Auth = httpHeaderAuth credential Viska: Flex Webhook Auth (6zo7MIzIBcUrjswl) binding env var FLEX_APPLY_WEBHOOK_SECRET — the single shared bearer for BOTH endpoints, constant-time compared. flex-pull-rescope-ops.md:50-58; apply_service.py:36-37,66-70,326 Handler handle_sign_upload apply_service.py:177-219

Request body (object_path from the Normalize node):

POST /sign-upload
Authorization: Bearer <FLEX_APPLY_WEBHOOK_SECRET>
Content-Type: application/json

{
  "bucket": "flex-inbox",
  "object_path": "flex/2026-06-12/01HXXXXEXECID.xml"
}

Server-side input hardening:

• bucket is never caller-controlled — a present non-default bucket is refused 400 "bucket override not allowed" apply_service.py:85-91,206-208
• Body is OPTIONAL; a missing object_path ⇒ generated incoming/<uuid>.xml apply_service.py:171-174,209
• object_path must match _OBJECT_PATH_RE = [A-Za-z0-9_\-/]{1,200}\.xml, no .., not absolute; else 400 "object_path must be a safe .xml object" apply_service.py:75-82,210-211
• Mint is server-side: POST {VISKA_SUPABASE_URL}/storage/v1/object/upload/sign/<bucket>/<path> with the service-role key, which stays on the server (injected closure; pure core never receives it; test-asserted) apply_service.py:182-186,250-271,340

Response 200 apply_service.py:218-219,265-270:

{
  "ok": true,
  "bucket": "flex-inbox",
  "path": "flex/2026-06-12/01HXXXXEXECID.xml",
  "signedUrl": "https://<viska-supabase-host>/storage/v1/object/upload/sign/flex-inbox/flex/2026-06-12/01HXXXXEXECID.xml?token=<jwt>",
  "token": "<jwt>"
}

Error codes: 401 bad/missing bearer · 400 malformed body / non-xml object_path / bucket override · 502 storage mint failure. apply_service.py:191-192,215-216

6.2 Node [2] — Upload Flex XML

n8n-nodes-base.httpRequest, PUT. flex-pull-rescope-ops.md:60-70

This PUTs the bytes straight to Supabase Storage flex-inbox — a private bucket. No apply-svc round-trip on this leg. 20260621-01-flex-inbox-bucket.sql:21-24

6.3 Node [3] — Apply POST

n8n-nodes-base.httpRequest, POST {apply-svc}/apply (same Railway host). Same httpHeaderAuth credential = FLEX_APPLY_WEBHOOK_SECRET. retryOnFail + onError continue — apply is idempotent so retry is safe. flex-pull-rescope-ops.md:72-80 Handler handle_apply apply_service.py:125-168

Request body (handler-truth contract):

POST /apply
Authorization: Bearer <FLEX_APPLY_WEBHOOK_SECRET>
Content-Type: application/json

{
  "bucket": "flex-inbox",
  "object_path": "flex/2026-06-12/01HXXXXEXECID.xml"
}

Response 200 — spreads the _build_and_emit summary apply_service.py:117-119,168:

{
  "ok": true,
  "account": "U22131377",
  "reportDate": "20260612",
  "report_dates": ["2026-05-14", "2026-05-15", "…", "2026-06-12"],
  "statements": 22,
  "positions": 660,
  "fx": 110,
  "nav_rows": 22
}

Field semantics: reportDate = latest report_date (backward-compat); report_dates = per-day period_end list (ascending); statements = day count; positions/fx/nav_rows = summed across all days. apply_service.py:117-119

Error codes: 401 bad/missing bearer · 400 malformed JSON / missing-or-unsafe object_path / bucket override · 500 fetch/parse/apply failure (no commit + durable alert). apply_service.py:130-159

6.4 The Write Transaction — handle_apply

One pure core with injected I/O (fetch_object / apply_sql / move_object / alert) so it is unit-testable with no flask/psycopg/network. apply_service.py:30-33

• 1. Bearer check → 401 before any I/O apply_service.py:133-134
• 2. Body parse + bucket/path hardening — same guards as sign-upload apply_service.py:136-150
• 3. Fetch XML from flex-inbox with service-role key: GET {VISKA_SUPABASE_URL}/storage/v1/object/<bucket>/<path> apply_service.py:227-235
• 4. _build_and_emit → build_sections_by_day(path) yields one tuple per distinct OpenPosition reportDate (ascending); per day file_hash = flex_file_hash(account, rd); emit_days(days,"flex_api",timezone) → ONE BEGIN…COMMIT transaction apply_service.py:94-122,110; flex_to_sections.py:145-162; ibkr_import.py:359-382
• 5. apply_sql(sql) — one autocommit connection; the emitted BEGIN…COMMIT is the txn apply_service.py:274-281
• 6. On success: move_object(bucket, object_path, "processed/"+object_path) via POST .../storage/v1/object/move — best-effort; a move failure does NOT un-commit apply_service.py:161-166,238-247
• 7. On any exception: alert(...) → insert ops.health_events, return 500 — no commit; object left in inbox for retry apply_service.py:156-159,284-299

SQL shape (emit_days): single BEGIN; → SET LOCAL timezone → per day emit(..., stmt_tmp="_stmt_<i>", wrap=False) → COMMIT;. Per-day CREATE TEMP TABLE _stmt_<i> ON COMMIT DROP captures that day's statement_id via the RETURNING id upsert, avoiding single-statement collapse. ibkr_import.py:190-197,359-382 Every write is ON CONFLICT: instruments ON CONFLICT (conid) DO UPDATE ibkr_import.py:184-187; statements ON CONFLICT (file_hash) DO UPDATE … RETURNING id ibkr_import.py:196; trades/positions/dividends/cash_flows/fees_interest ON CONFLICT DO NOTHING ibkr_import.py:199-206; nav_snapshots ON CONFLICT (statement_id) DO NOTHING ibkr_import.py:281; fx_balances ON CONFLICT (statement_id, currency) DO NOTHING ibkr_import.py:352. Re-apply = no-op.

6.5 Idempotency Grain — Semantic file_hash

# flex_import.py:20-31
def flex_file_hash(account, rd):
    return hashlib.sha256(("flex:%s:%s" % (account, rd)).encode()).hexdigest()

• Dedup key = sha256("flex:{account}:{report_date}") — semantic, NOT raw XML bytes. IBKR stamps whenGenerated fresh every pull, so two pulls of the same reportDate are byte-different yet the same snapshot; a bytes-hash would mint a duplicate every re-pull (the shipped bug, fixed b1664ff). flex_import.py:23-29
• This hash lands in trading.statements.file_hash carrying CONSTRAINT statements_file_hash_key UNIQUE (file_hash) ⇒ exactly one statement row per (account, reportDate); statement_id is the per-day key for all child rows. 20260610-01-trading_schema_core.sql:23,29
• source='flex_api' admitted by statements_source_check CHECK (source = ANY (ARRAY['csv','flex_api'])). 20260610-01-trading_schema_core.sql:30-31
• CSV path divergence: ibkr_import.main() keeps a file-bytes sha256 — there a re-import IS the identical file, so bytes are correct identity. ibkr_import.py:403-404; flex_import.py:28-29

6.6 Error / Alert Path → ops.health_events

On 500, _real_alert writes stderr + inserts; meta carries {"bucket":…, "object_path":…}; alerting is best-effort (wrapped to never raise). apply_service.py:157-158,284-299

INSERT INTO ops.health_events (source,severity,error_class,message,meta)
VALUES ('flex_apply', %s, %s, %s, %s)

source='flex_apply' is admitted by health_events_source_check CHECK (source IN ('layer1','watchdog','flex_apply')) — the base CHECK in 20260611-01 allowed only ('layer1','watchdog'); the flex-inbox migration extends it. 20260621-01-flex-inbox-bucket.sql:48-50; 20260611-01-ops_schema_core.sql:14 The table is retry-safe: the object stays in flex-inbox (not moved to processed/) on failure, so a re-fire re-attempts cleanly.

6.7 The Two Distinct Gaps — Never Conflate

6.8 Empty-Statement Guard — "Statement Usable?"

An IF node between Normalize and Sign Upload: position_count > 0 AND report_date notEmpty (commit f8a0304, activeVersionId 6aa4c859). False branch → Flag Unmapped Conids → Respond, skipping Sign/Upload/Apply (no empty overwrite). git show f8a0304; ViskaN8N chronicle.md:17-32 Reason: IBKR toDate floats → empty next-day snapshot (exec 35606, reportDate 2026-06-20, 0 positions). The Upsert Positions node (f694c363…) was removed — replaced by this Sign Upload → Upload → Apply path; n8n holds zero trading-write credential. flex-pull-rescope-ops.md:31,83-89

6.9 Credential Bindings (env var NAMES only — values via Hades, never read)

apply_service.py:35-44,62,326-330 n8n side: ONE standing credential Viska: Flex Webhook Auth (6zo7MIzIBcUrjswl, httpHeaderAuth) binding FLEX_APPLY_WEBHOOK_SECRET. n8n carries exactly 2 feature creds (IBKR Flex token + this webhook secret) and zero standing upload token. flex-pull-rescope-ops.md:24,54,76,97

6.10 Security Posture (rule #19 — mutating + network-reachable ⇒ authenticate)

• Both endpoints require Authorization: Bearer <secret>, constant-time compared, 401 before any I/O (live-confirmed). Bearer (not body-HMAC) because this n8n blocks $env in nodes and Code nodes can't read credentials, making HMAC-over-body unwireable. apply_service.py:18-23,66-70,133,194
• bucket never caller-controlled; object_path anchored to a traversal-free .xml charset, url-quoted before forming any Storage URL. apply_service.py:25-28,73-82,230,259
• Upload PUT auth = none — the server-minted signed URL self-authenticates; service-role key never leaves apply-svc. flex-pull-rescope-ops.md:63; apply_service.py:182-186
• flex-inbox is a private bucket; only the apply-svc service-role key reads it (service_role bypasses RLS); no anon/authenticated SELECT policy. 20260621-01-flex-inbox-bucket.sql:21-24
• XML parse refuses any DOCTYPE/ENTITY before parsing (XXE + billion-laughs guard, stdlib-only, no defusedxml). flex_to_sections.py:16-33
• CF Access fronts the dashboard / artifacts Pages portal only — it is NOT in the IBKR ingest path; apply-svc's static bearer is the sole caller-auth. grep null; on-demand-webhook-design.md:136-137

6.11 Confirmed-State & Open Items (honest)

§7Supabase Landing — the trading.* Schema

apply-svc re-parses the raw Flex XML and is the sole SSOT writer of trading.*; n8n holds zero DB/storage credential and does zero trading writes (the Upsert Positions node was removed). apply_service.py:182-186; rescope-ops:31,83-89 The schema is created CREATE SCHEMA IF NOT EXISTS trading at 20260610-01-trading_schema_core.sql:9, commented "Viska macro slhf. book of record (IBKR). Append-only import; statement_id lineage on every event row. Bot/API reads go through trading.v_* views." 20260610-01:11-12

Migration provenance

• 20260610-01-trading_schema_core.sql — statements, instruments, instrument_themes 20260610-01
• 20260610-02-trading_book.sql — trades, positions_snapshots, nav_snapshots, cash_flows, dividends, fees_interest, fx_balances, candles 20260610-02
• 20260610-06-trades-nullconid-dedup.sql — trades NULL-conid partial dedup index 20260610-06:14-16
• 20260610-07-fees-interest-dedup.sql — fees_interest business-key dedup + positions_snapshots NULL-conid partial dedup 20260610-07:18-25
• 20260619-01-flex-symbol-theme-close.sql — DATA backfill into instrument_themes (RIOl/AMRC), no DDL 20260619-01
• 20260621-01-flex-inbox-bucket.sql — storage.buckets/storage.objects (flex-inbox), NOT a trading.* table 20260621-01

Table matrix

Importer write-set

The IBKR/Flex importer (importer/ibkr_import.py) writes 9 tables directly: statements (lineage anchor, written first), instruments ibkr_import.py:181, nav_snapshots :273, and via the insert_rows(table,...) helper (all ON CONFLICT DO NOTHING) :199: trades :229, positions_snapshots :251, cash_flows :295, dividends :321, fees_interest :337, fx_balances :350.

• instrument_themes — NOT importer-written; operator-seeded (20260610-05 seed + 20260619-01 backfill); importer backfills conid only. 20260610-01:54-57
• candles — NOT importer-written; n8n nightly EOD job. 20260610-02:172

flex-inbox Storage bucket (the raw-XML drop)

Not a trading.* table — the durable raw-XML drop apply-svc reads. Source: migrations/20260621-01-flex-inbox-bucket.sql (Task 057a).

Side effect (same migration, not a trading.* table): the ops.health_events source CHECK is extended to admit 'flex_apply' so a failed import lands a durable status-page-visible event — CHECK (source IN ('layer1','watchdog','flex_apply')). 20260621-01:48-50

RLS / read posture

All trading.* tables are anon-REVOKED (20260610-04-trading_rls.sql); the trading schema carries no anon surface. 20260619-01:17-20 Bot/API reads route through trading.v_* views (20260610-03-trading_views.sql) under the trading_bot_ro role — consumed by the Mímir bot. 20260610-08:42-47 The frontend (viska.gg / ViskaFront) reads public.* projections (positions_current, nav_latest, cash_current, holdings_profiles, allocation_history, market_quotes, fx_rates), never trading.v_* directly — the data-streams bible is STALE on this point. useDashboardData.ts:76,108,152; 05-data-streams.md:9-13 All public.* are currently authenticated-only (anon revoked 06-19). 20260619-03/04/06

§8Consumption — Views & Read Contract

The read surface is two tiers with a deliberate trust boundary: the internal book-of-record layer trading.v_* (consumed by the Mímir Slack bot via a dedicated trading_bot_ro role) and the portal-projection layer public.* (consumed by the viska.gg dashboard). The frontend never reads trading.v_* directly — it reads public.* projections, and the data-streams bible that still names trading.v_* as FE targets is stale.

The two consumers

Read-contract — every view, exposure, consumer, posture

Consumer contracts — who and how

Data-quality flags carried in the views

• public.positions_current.march_mtd = NULL — MTD P&L not in flex snapshot, needs period calc 20260617-01:37
• public.nav_latest.nav_total == nav_ibkr until off-IBKR ISK bankabók cash source exists; march_mtd NULL 20260617-01:51,53
• public.cash_current omits the off-IBKR ISK bankabók row — no source table yet 20260617-01:64,80
• trading.v_nav_latest.twr_pct may be NULL → FE shows "n/a" 05-data-streams.md:9
• public.holdings_profiles.description/moat EMPTY until operator/research authors — flag, not fabricated 20260617-03:25

§9Security & Privacy

How the IBKR/Flex trading pipeline is kept safe — no unauthenticated mutation (rule #19), least-privilege roles, credential isolation — and private — RLS lockdown, the anon-revoke arc, a private storage bucket. All DDL below is the authored intended posture: every migration header except 20260619-03 (PR #20, Hades-applied rc=0) self-labels FORWARD — not applied to prod. See the apply-state caveat at the end.

9.1 Write-path authentication (rule #19)

The rule-#19 predicate UNSAFE = MUTATING ∧ PUBLIC ∧ UNAUTHENTICATED is not satisfied: the endpoints are mutating and public, but the bearer removes the unauthenticated leg. apply_service.py:66-70

• Constant-time compare, both endpoints: _valid_bearer returns hmac.compare_digest("Bearer " + secret, auth_header) — rejects an empty header and a bare token without the Bearer  prefix. apply_service.py:66-70
• Bearer, not body-HMAC (commit 7466abf): this n8n instance blocks $env in nodes and Code nodes can't read credentials, so HMAC-over-body is unwireable. X-Viska-Signature → Authorization: Bearer; n8n binds it as an httpHeaderAuth credential so the value never enters node/LLM context. Native header-auth from vault — not path obscurity. apply_service.py:17-23
• Single shared bearer for both /sign-upload and /apply. apply_service.py:4,36,326
• Upload PUT auth = authentication: none — the server-minted signed upload URL self-authenticates; n8n carries no upload token. The HS256 FLEX_UPLOADER_JWT leg is dead/dropped (see 9.3). apply_service.py:6-9,46
• Replay = no-op given (account, reportDate) semantic idempotency (see 9.6). apply_service.py:23

9.2 Task-060 hardening — bucket scope-lock & path-traversal

Folded into commit d182bcb (2 MEDIUM security-review findings); hardens both /apply and /sign-upload since they share the file and bearer. apply_service.py:75-91

Tested: test_bucket_override_rejected_400 (asserts applied_sql is None — foreign bucket never fetched) test_apply_service.py:192-196, test_path_traversal_rejected_400 test_apply_service.py:199-205, test_unsafe_paths_rejected over ("../x.xml","/x.xml","x.txt","a..b/x.xml","x.xml?q=1","a b.xml","x.xml#f","",None,123) test_apply_service.py:215-217; auth: test_missing_bearer_401 / test_bad_bearer_401 / test_raw_token_without_bearer_prefix_401 test_apply_service.py:71-87. 75 importer tests green after the multiday fix f810998.

9.3 Private storage — flex-inbox bucket

The raw-XML drop is a private Supabase Storage bucket. 20260621-01:24-26

• Private by construction: INSERT INTO storage.buckets … ('flex-inbox','flex-inbox', false) ON CONFLICT DO UPDATE SET public = false — forces private even if it pre-existed; storage.objects RLS asserted. 20260621-01:24-29
• No SELECT/UPDATE/DELETE policy for anon or authenticated → apply-svc reads/moves with service_role, which BYPASSES RLS; reads happen server-side only. 20260621-01:18-19,40-42

9.4 Credential isolation — who holds what

Bindings only (env-var names; values Hades-provisioned). Consistent with rule #04 — credential VALUES are the one thing Viska escalates out, to Hades. apply_service.py:35-46

service-role key never leaves apply-svc: the injected sign_upload closure closes over the key; the pure handle_sign_upload core never receives it, so it cannot appear in any response (test-asserted). apply_service.py:182-186,340

9.5 RLS posture — trading.* and mirror schemas

The pattern across all four data schemas: service_role full · authenticated SELECT-only · anon NOTHING. 20260610-04:13-14

9.6 Least-privilege read role — trading_bot_ro (Mímir)

The 4 trading.v_* views are security_invoker = true, so granting the Mímir bot SELECT on views only let it read nothing (invoker semantics evaluate base-table privilege against the calling role). 20260610-08:1-8

• Resolution = OPTION (a): keep the heph-reviewed invoker posture; grant base-table SELECT on exactly the 6 view-touched tables (trades, positions_snapshots, nav_snapshots, statements, instruments, instrument_themes) + round_trips matview + the 4 views, plus a role-targeted RLS read policy trading_bot_ro_read. 20260610-08:8-16,29-47,52-68
• Deliberately NOT granted: candles, cash_flows, dividends, fees_interest, fx_balances — no curated view exposes them, so the bot cannot read them. "Never raw tables" is enforced by convention (the role's contract is the v_* views). 20260610-08:14-16
• Role is Hades-provisioned vault-side, not created in the migration. 20260610-08:18-22,42-47

9.7 Anon-surface posture — the anon-revoke arc

Trigger: Heph directive 2026-06-19 "no anon-readable Viska tables" + a live rule-#04 breach (public.ssot_credentials was anon-readable). Hades enumerated 84 of 131 public.* objects anon=t at the start. 20260619-04-revoke-anon-scoped.AUDIT.md:1-6

Why grant-revoke is sufficient: a GRANT SELECT TO anon is required for anon to read even under a permissive anon RLS policy, so revoking the grant blocks anon in all cases — the GRANT-vs-RLS-effective split is an exposure ledger, not a correctness gate. 20260619-04:8-12 Legacy thread 20260609-04-revoke-legacy-anon-grants revokes leftover full-DML anon/authenticated grants on public.viska_chat_users (defense-in-depth; RLS already denied them). 20260609-04:8-14

9.8 Read contract & auth-domain whitelist

• FE reads public.* projections (positions_current, nav_latest, cash_current, holdings_profiles, allocation_history, market_quotes, fx_rates) — never trading.v_* directly (the data-streams bible is stale). All public.* are currently authenticated-only (anon revoked 06-19). useDashboardData.ts:76,108,152
• Mímir bot reads trading.v_* via trading_bot_ro. 20260610-08:42-47
• Email-domain whitelist gates who can hold an authenticated session — no native GoTrue "allowed domain" knob, so a DB-layer trigger on auth.users: predicate is_viska_allowed_email = @viskasjodir.is OR admin@boas.dev; enforce_viska_email_whitelist BEFORE INSERT AND BEFORE UPDATE OF email (blocks out-of-domain creation AND re-pointing); security definer, search_path=''. All viska.gg auth = Supabase magic-link, NO Cloudflare Access. 20260615-05:5-11,25-36,46-47,61-69

9.9 CF Access — NOT in the ingest path

The planned on-demand webhook (2nd trigger on the same workflow, onReceived 202-async, n8n-native Header Auth chosen over a CF edge shield, 5-min cooldown) is DESIGN-APPROVED, NOT BUILT — blocked on N8N_API_URL/N8N_API_KEY + an auth-secret mint; the headerAuth trigger node exists, the cooldown gate does not. The auth secret lives in the dashboard backend, never in browser JS. on-demand-webhook-design.md:6,47-49,109-117

9.10 Decision 055-A — gated fallback, not primary

9.11 Idempotency — semantic dedup as a safety property

Idempotency is a security control (replay-safe writes), not only a correctness one: file_hash = sha256("flex:"+account+":"+report_date) → trading.statements UNIQUE(file_hash) → one row per (account, reportDate); a re-pull is a no-op. This is a semantic hash, NOT a raw-bytes hash (the raw-bytes form was the shipped bug, fixed b1664ff). apply-svc re-parses the raw XML and is the sole SSOT writer of trading.*; n8n holds zero DB/storage credential and does zero trading writes (the Upsert Positions node was removed). flex_import.py:20-31; 20260610-01:23,29

§10The Real Decision Arcs (not blind)

Eight load-bearing decisions in the IBKR-Flex → trading.* pipeline, each with what was chosen, what was rejected, the driving incident, and a file/SHA citation. The first one — 055-A — carries the named trap: writers who skim it report the Railway HTTP apply-svc as the design. It is not. It is the rule-#19 FALLBACK; the default was a host-internal file-drop + Hades-owned cron.

Per-decision detail

§11Source & Confidence Ledger

This report is a reconciliation + QA pass over nine independently-cited domain findings, not fresh code research. The ledger below is the audit-grade output of that pass: every load-bearing fact carries a status badge and its source. Ten cross-domain contradictions were resolved into the canonical fact sheet; the residual UNKNOWN rows are the honest edge of what the repo can prove.

Confirmed / Inferred / Unknown ledger

Contradictions resolved (10)

The reconciliation found ten cross-domain conflicts. Each was resolved to the handler/code/commit truth and folded into the canonical fact sheet; section writers follow the resolution, not the raw domain finding.

Residual unknowns — the honest edge