Workspace — Isolated Data Context Design
Self-contained, layered data workspaces within OreStudio; prerequisite for ORE sample import and multi-track data import

The Data Import Session design identified two fundamentally different import use cases:

Track 1 — Educational / ORE sample import: A complete ORE example is imported so that a user can explore what it does — run it, see the results, understand the trade types and market configuration. Each ORE sample is a self-contained universe: its own market data, conventions, curve configs, pricing engine, and trades. Importing multiple samples into the same data space causes them to collide: curve names clash, trade IDs overlap, market data overwrites, and results become meaningless.

Track 2 — Production trade import: Trades from an external system (FpML, CSV, another TMS) are imported into the live book for review and eventual booking. Market data comes from live curated sources. This track does not need isolation — it targets the shared live data space.

The is_live flag and Pending Book design handles Track 2. Track 1 has no solution without workspace isolation.

Traders routinely want to ask "what happens to my book's NPV if I shock EUR rates by 50bps?" Without an isolation mechanism, any change to market data instantly affects all users and all compute runs. Workspaces give the trader an isolated copy of live data in which to apply the shock, run the report, and compare results side-by-side against the unshocked live view.

Without isolation, importing 30 ORE samples creates hundreds of synthetic trades, thousands of curve config rows, and dozens of conventions in the live books — all mixed with real production data. Users cannot distinguish sample artefacts from curated data.

The Live workspace uses the well-known sentinel UUID aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa (returned by ores_utility_live_workspace_id_fn()) as its stable identifier. It always exists, is the root of all inheritance chains, and is protected against archival by a dedicated elevated permission (see §Permissions below).

The nil UUID (00000000-0000-0000-0000-000000000000) is deliberately not used: it is the default C++ value for an uninitialised boost::uuids::uuid, so using it for Live would cause an unset workspace_id to silently resolve to the Live data space. The max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff) is already reserved for the system tenant (ores_utility_system_tenant_id_fn()).

The sentinel value aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa has version nibble a (decimal 10), which falls outside the valid UUID version range 1–8; no UUID generator will ever emit it. It is defined in utility_system_tenant_create.sql alongside the nil and max functions so it is available at DDL time across all schemas.

All tables that previously defaulted workspace_id to integer 0 default instead to ores_utility_live_workspace_id_fn().

Single-parent inheritance and portfolio scope live directly on the workspace row. No separate parents or scope tables are needed at the workspace level.

The workspace table is bitemporal: every mutation creates a new version row, and the full history of all changes is retained. This is the same pattern used by all first-class domain entities (service definitions, report definitions, etc.).

create table ores_workspaces_tbl (
    id                  uuid         not null,
    version             integer      not null,
    name                text         not null,
    description         text         not null default '',
    source_path         text         not null default '',
    parent_workspace_id uuid         null references ores_workspaces_tbl(id),
    scope_portfolio_id  uuid         null,
    owner_id            uuid         not null,  -- FK to ores_iam_accounts_tbl
    status_code         text         not null default 'active',
    modified_by         text         not null,
    performed_by        text         not null,
    change_reason_code  text         not null,
    change_commentary   text         not null,
    valid_from          timestamptz  not null,
    valid_to            timestamptz  not null,
    primary key (id, valid_from, valid_to),
    exclude using gist (id with =, tstzrange(valid_from, valid_to) with &&),
    check (valid_from < valid_to),
    check (id <> ores_utility_nil_uuid_fn()),
    check (status_code in ('active', 'archived')),
    check (parent_workspace_id is distinct from id)
);

-- Indexes for common access patterns.
create unique index workspaces_name_uniq_idx
    on ores_workspaces_tbl(name)
    where valid_to = ores_utility_infinity_timestamp_fn();

create index workspaces_status_idx
    on ores_workspaces_tbl(status_code)
    where valid_to = ores_utility_infinity_timestamp_fn();

-- Insert trigger: version management, valid_from/valid_to, audit fields.
-- Delete rule: set valid_to = now() (soft close).
-- Both generated by the standard bitemporal codegen template.

-- Seed the Live workspace using the live-workspace sentinel UUID.
-- Owner is the system account (nil UUID); no parent; no portfolio scope.
insert into ores_workspaces_tbl
    (id, version, name, description, owner_id, status_code,
     modified_by, performed_by, change_reason_code, change_commentary,
     valid_from, valid_to)
values (
    ores_utility_live_workspace_id_fn(), 1, 'Live', 'Live production data space',
    ores_utility_nil_uuid_fn(), 'active',
    'system', 'system', 'initial_data', 'Seed Live workspace',
    now(), ores_utility_infinity_timestamp_fn()
);

Workspace status is backed by the badge system rather than a raw text column. A new code domain workspace_status maps each status code to a visual badge:

The active badge already exists in ores_dq_badge_definitions_tbl. A new archived badge (danger/red) is added to dq_badge_system_populate.sql alongside the workspace_status mapping rows. The Qt workspace list renders each row's status column via the badge-lookup infrastructure, consistent with party, book, portfolio, and report FSM status rendering.

Three tiers of workspace permission are enforced in the NATS handler. The handler holds a reference to the IAM authorisation service and validates the caller's permissions against their JWT claims before any service operation.

When a workspace's portfolio scope still includes more trades than the user wants (e.g. they need just three specific trades from a large book), a trade whitelist provides exact selection.

create table ores_workspace_trade_scope_tbl (
    workspace_id  uuid  not null,  -- references current version of ores_workspaces_tbl
    trade_id      uuid  not null,  -- references ores_trading_trades_tbl(id)
    primary key (workspace_id, trade_id)
);

Semantics:

• No rows for a workspace → all trades reachable via the portfolio scope are visible.
• Rows present → only listed trades are visible (must also be within the portfolio scope; rows referencing out-of-scope trades are ignored).

This is a positive selection (include list), not an exclusion list. The common case of "one book" or "one desk" is handled entirely by scope_portfolio_id and needs no whitelist rows at all.

Example inheritance chains:

workspace 0 (Live)
  └─ workspace 5 (EUR shock +50bps)     parent = 0
       └─ workspace 8 (EUR+credit shock) parent = 5

Resolution order for workspace 8: [8, 5, 0]
- Data in workspace 8 wins.
- Data absent from 8 falls through to workspace 5.
- Data absent from 5 falls through to workspace 0 (Live).

Cycle prevention is enforced by a trigger that walks the parent chain before any insert or update of parent_workspace_id.

When a workspace is opened, its full ancestor chain is computed once via a recursive CTE and cached in the application session as an ordered integer array:

with recursive chain(id, depth) as (
    select id, 0
    from ores_workspaces_tbl
    where id = :target_workspace_id
      and valid_to = ores_utility_infinity_timestamp_fn()
    union all
    select w.parent_workspace_id, c.depth + 1
    from ores_workspaces_tbl w
    join chain c on c.id = w.id
    where w.parent_workspace_id is not null
      and w.valid_to = ores_utility_infinity_timestamp_fn()
)
select id from chain order by depth;
-- Returns e.g. [<uuid-8>, <uuid-5>, <nil-uuid>] for a workspace two levels deep

This array is passed as :resolution_order to all workspace-aware queries.

Every table that holds user or import data gains a workspace_id column:

alter table <table_name>
    add column workspace_id uuid not null default ores_utility_live_workspace_id_fn();

create index on <table_name> (workspace_id);

Affected tables (non-exhaustive):

Tables that are genuinely global (users, IAM, parties, DQ FSM definitions, workflow definitions, workspace table itself) do not get workspace_id.

Two query patterns cover all cases.

Trade queries additionally filter by portfolio scope and (if present) the trade whitelist:

-- All trades visible in workspace :ws_id with resolution order :res_order
select distinct on (t.id) t.*
from ores_trading_trades_tbl t
join ores_trading_books_tbl b on b.id = t.book_id
-- Portfolio scope: if scope_portfolio_id is set, restrict to books in that portfolio
left join ores_trading_portfolio_books_tbl pb
    on pb.book_id = b.id
    and pb.portfolio_id = (
        select scope_portfolio_id from ores_workspaces_tbl where id = :ws_id)
where t.workspace_id = any(:res_order)
  and (
      -- No portfolio scope set: include all books
      (select scope_portfolio_id from ores_workspaces_tbl where id = :ws_id) is null
      or pb.book_id is not null
  )
  and (
      -- No trade whitelist: include all scoped trades
      not exists (select 1 from ores_workspace_trade_scope_tbl
                  where workspace_id = :ws_id)
      -- Trade whitelist active: only listed trades
      or t.id in (select trade_id from ores_workspace_trade_scope_tbl
                  where workspace_id = :ws_id)
  )
order by t.id, array_position(:res_order, t.workspace_id);

Non-trade data queries (conventions, curves, market data, etc.) use only the resolution order — no portfolio or trade filtering:

-- Point lookup by natural key
select * from ores_curveconfig_yieldcurve_tbl
where name = 'EUR-EONIA'
  and workspace_id = any(:res_order)
order by array_position(:res_order, workspace_id)
limit 1;

-- List query with deduplication on natural key
select distinct on (name) *
from ores_curveconfig_yieldcurve_tbl
where workspace_id = any(:res_order)
order by name, array_position(:res_order, workspace_id);

report_definition gains workspace_id (default 0 = Live/global). The same resolution chain that applies to trade and reference data applies to report definitions: when listing report definitions available in workspace W, the query returns all report definitions whose workspace_id is in the resolution order [W, parent, ..., 0], deduplicated on name with the closest workspace winning.

Unlike Eclipse (one workspace = one session restart), OreStudio allows multiple workspaces to be active simultaneously. Each MDI subwindow carries its own workspace context. The primary use case is side-by-side comparison:

+-----------------------------+  +-----------------------------+
|  TRADES  [Live ▼]           |  |  TRADES  [EUR shock ▼]       |
|-----------------------------|  |-----------------------------|
|  IRS_001  NPV:  1,234,500   |  |  IRS_001  NPV:  1,189,200   |
|  FXF_002  NPV:    456,100   |  |  FXF_002  NPV:    455,900   |
+-----------------------------+  +-----------------------------+

The trader opens the Trades window twice, sets one to Live and one to the shocked workspace, and sees the NPV impact immediately. The same applies to Market Data, Conventions, and any other view.

Each MDI window carries a workspace context:

• Shown as a chip/badge in the window header: [Live], [MarketRisk], [EUR shock +50bps]. Live workspace shows no badge (it is the default and adding a badge to every window would be noisy).
• Selectable via a compact combo box in the window toolbar. Changing the workspace re-queries all data for that window without closing or reopening it.
• Windows default to workspace 0 (live) on first open.

+-------------------------------------------------------+
|  TRADES  [EUR shock ▼]               [Filter] [Cols]  |
+-------------------------------------------------------+
|  ...trade grid scoped to EUR shock workspace...        |
+-------------------------------------------------------+

A dedicated window in the Data Transfer menu. Shows all workspaces in a tree, grouped by parent/child relationships:

+-----------------------------------------------------------+
|  DATA WORKSHOP                          [New] [Import ORE] |
+-----------------------------------------------------------+
| ▶ Live                          0 local trades  · live    |
| ▼ MarketRisk                   27 reports · 312 trades    |
|     ore_sensi                   12 trades  last run 10:15 |
|     ore_hist                    12 trades  last run 10:17 |
|     ore_correlation             12 trades  not yet run    |
|     ...                                                   |
| ▼ EUR shock +50bps              inherits: Live             |
|     [no local data — all inherited]                       |
|     NPV Report                  last run 11:02            |
| ▶ Legacy · Example_1            1 report · 12 trades      |
| ▶ Legacy · Example_2            1 report  · 3 trades      |
| ...                                                       |
+-----------------------------------------------------------+
| [ Open ] [ Run Report ] [ Copy to... ] [ Archive ]        |
+-----------------------------------------------------------+

Actions:

• Open: opens the selected workspace in the Data Import Session window (or any other window), scoped to that workspace.
• Run Report: submits the selected report definition to the compute grid.
• Copy to…: copies selected workspace or selection within it to another workspace or to Live (live copy triggers pending/approval workflow).
• Archive: marks workspace archived; data retained but hidden from selectors.

All windows that display workspace-scoped data show the workspace chip. Windows with a non-live workspace display it prominently so users always know which data context they are viewing.

Track 2 of that plan (Pending Book, is_live flags) is unchanged and independent of workspaces. Track 1 (ORE sample import) creates workspaces rather than plain import sessions. The Data Import Session window is reused to browse workspace data since it is already workspace-scoped.

These are Track 2 concerns only. Within a workspace, all data is the workspace's data — no is_live distinction is needed because the workspace boundary provides the isolation. The is_live flag only matters when copying workspace data into the live workspace (0).

The report_definition table gains workspace_id (default 0). risk_report_config is extended incrementally with structured fields for ORE orchestration settings (starting with NPV analytics; simulation/sensitivity settings added as needed). No raw XML is stored; no new analyses table is introduced. The existing scheduling, lifecycle FSM, and execution pipeline are reused. Scheduling remains Live-only; non-live workspace report definitions run on-demand only.

1. Rewrite projects/ores.codegen/models/workspace/workspace_domain_entity.json:
   • Change primary key from integer to uuid.
   • Add owner_id (uuid, not null).
   • Rename status → status_code; update check constraint values.
   • Remove created_by / created_at (absorbed by bitemporal audit columns).
   • The temporal template auto-generates version, modified_by, performed_by, change_reason_code, change_commentary, valid_from, valid_to and the insert trigger / delete rule.
2. Run codegen; verify generated workspace_create.sql and workspace.hpp. Delete the hand-written workspace_create.sql.
3. Add archived badge to dq_badge_system_populate.sql.
4. Add workspace_status badge mapping rows (active → active, archived → archived).
5. Add workspace::workspaces:archive, workspace::workspaces:archive_any, and workspace::live_workspace:archive to iam_permissions_populate.sql. Grant read/write/archive to Trading; read to Viewer. archive_any and live_workspace:archive are covered by existing * wildcards on TenantAdmin and SuperAdmin respectively. ✓
6. Enforce permissions in workspace_handler.hpp: list→read, create/trade-scope→write, archive→ownership-aware three-tier check. ✓
7. Create ores_workspaces_tbl (bitemporal, UUID PK); seed Live workspace with nil UUID.
8. Create ores_workspace_trade_scope_tbl.
9. Add workspace_id uuid not null default ores_utility_nil_uuid_fn() to all affected tables.
10. Add indexes on workspace_id; enforce cycle-prevention trigger on parent_workspace_id inserts/updates (updated for UUID FK).
11. Extend ores_reporting_report_definitions_tbl with workspace_id.
12. FK validation inventory and trigger wiring: a. Create ores_workspace_validate_fn(p_workspace_id uuid) returns uuid as SECURITY DEFINER (service users hold no SELECT on ores_workspaces_tbl; this mirrors the pattern of ores_iam_validate_tenant_fn). Function must accept the Live sentinel UUID unconditionally (it has no row in ores_workspaces_tbl that can be checked via the normal active-row predicate). b. Inventory every insert trigger on workspace-aware tables (the 28+ entities from the codegen model list in ~2026-05-19-workspace-id-codegen-propagation.org) and add a ores_workspace_validate_fn(NEW.workspace_id) call alongside the existing ores_iam_validate_tenant_fn call. c. Because most of these triggers are codegen-generated, add has_workspace_id support to the trigger template (cpp_domain_type_create.sql.mustache or equivalent) so the call is regenerated automatically rather than hand-wired per entity.
13. Run recreate_database.sh -k -y; validate schemas.

Note on workspace visibility: workspaces are private to the party that owns them — a user in party A cannot see workspaces belonging to party B, even within the same tenant. Within a party, all authenticated users hold workspace::workspaces:read by default, so workspaces are not restricted by per-user ACLs. Data restriction is handled by the scope_portfolio_id on the workspace itself (portfolio tree scoping), not by per-workspace read grants. This keeps the permission model simple and avoids over-engineering.

1. All service queries gain a workspace_id (or resolution-order array) parameter; default to [0] (live only).
2. Resolution order computation: recursive CTE exposed as a helper function.
3. New NATS endpoints: workspace.v1.list, workspace.v1.create, workspace.v1.archive, workspace.v1.copy, workspace.v1.trade-scope.set, workspace.v1.trade-scope.clear.
4. Extend report definition endpoints to accept and return workspace_id; add report-definition.v1.clone endpoint (creates workspace-local copy).

1. ✓ Add workspace resolution order to application session state.
2. ✓ Propagate workspace context to all MDI windows via a WorkspaceContext object; EntityController event filter forwards changes to ClientManager.
3. ✓ Add workspace chip/badge to window headers (non-live windows only).
4. ✓ Add per-window workspace selector (searchable combo in window toolbar). Each MDI subwindow independently selects its workspace, enabling side-by-side comparison. Requires per-window scoped request context rather than shared ClientManager workspace state.

1. ✓ Workspace tree view (parent/child grouped) in WorkspaceMdiWindow.
2. Report definition list within workspace — shows local + inherited (with visual distinction: local rows bold, inherited rows dimmed with source workspace labelled).
3. ✓ Open / Archive / New workspace actions. Copy to / Run Report deferred.
4. ✓ Inheritance summary ("Inherits from" field in WorkspaceDetailDialog).
5. "Clone to workspace" action on any report definition — creates a workspace-local editable copy pre-populated from the source.

The ORE sample importer (Track 1 of the data import strategy) has been moved to Provisional Blotter Design, where it sits alongside Track 2 (production trade import). The workspace infrastructure built in Phases 1–4 is the prerequisite; no further workspace-plan steps are needed before the blotter plan's Track 1 work begins.