Task: Resolve market simulator folders by derived slug identifier
Table of Contents
This page documents a task in the Synthetic data scope and binding: system/tenant/party levels, bound vs sandboxed story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Market simulator folders currently have only a human-readable name (multi-word, spaces allowed), so shell commands must address them by exact full name (quoted) or UUID. Rather than a stored code column, derive a machine-readable identifier from the name at resolve time: each folder gets a codename – its source_name-style slug (lower(replace(name, ' ', ''))) – and folders address by a standard, filesystem-style path of codenames. Folders resolve as uuid, then exact name, then codename path. No schema change.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Synthetic data scope and binding: system/tenant/party levels, bound vs sandboxed |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-08-08 |
Acceptance
- no schema change: folders gain no
codecolumn; each folder's codename is derived by a pure function mirroring thesource_nameslug convention (lower(replace(name, ' ', ''))) - ores.shell synthetic commands resolve folder tokens as uuid, then exact name, then codename path
- codename paths are standard, filesystem-style paths walked component-by-component from the tree root (
2026realistic/fx,synthetic/2026realistic/fx,/synthetic/2026realistic/fx); components tolerate case and spaces ("2026 Realistic/FX"works) - a bare codename matching folders in more than one collection (e.g.
fxunder two collections) reports ambiguous, listing each candidate's codename path; ambiguity and no-match messages show codename paths, copy-pasteable as tokens
Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
Notes
A stored code column was considered and rejected. Rationale: the
codebase already derives machine tokens from display names
(source_name is 'synthetic.' || lower(replace(config, ' ', '')) ||
lower(pair) in publish_from_dq), and folder names are themselves
derived from DQ dataset names at publish – not user-renamed – so a
stored code would have no rename-stability consumer, would drift from
the name, and would force schema regeneration across every layer
(domain, table I/O, generator, repository, Qt).
Mid-implementation, the original path-token idea – display paths
joined by ' > ' ("2026 Realistic > FX") – was rejected by review
as messy and untypable. The final addressing scheme is codenames plus
standard folder paths: each folder's codename is its slug, and paths
are walked component-by-component from the tree root, so
2026realistic/fx, synthetic/2026realistic/fx and
"2026 Realistic/FX" all resolve to the same folder; a bare codename
(fx) matches at any depth.
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
PRs
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
Result
Market simulator folders now resolve by a derived slug identifier — no schema change. ores.shell synthetic command folder tokens resolve as uuid, then exact name, then codename path:
- Each folder's codename is its
source_name-style slug (lower(replace(name, ' ', ''))): "2026 Realistic" ->2026realistic, a pure function applied at resolve time. - Codename paths are standard, filesystem-style paths walked
component-by-component from the tree root:
2026realistic/fx,synthetic/2026realistic/fxand/synthetic/2026realistic/fxall resolve to the same folder. Components tolerate case and spaces ("2026 Realistic/FX"works); at each step the component matches the folder itself or a child, so the root may be part of the path. - A bare codename (
fx) matches at any depth; when it matches folders in more than one collection the token reports ambiguous and lists each candidate's codename path, copy-pasteable as a token (Ambiguous folder token 'fx' matches 2 entries: synthetic/2016oresamples/fx synthetic/2026realistic/fx). - Ambiguity and no-match messages show codename paths.
Implemented in synthetic_commands.cpp (slugify, match_codename,
match_folder_path, match_folders, folder_slug_path, resolve_folder_id;
–name subtree selection uses the same resolver). The ' > '-joined
display-path token form ("2026 Realistic > FX") was rejected by
review as messy and untypable and is not supported.
Verified end-to-end against prime_origin (tenant_admin): bare codename, case-tolerant tokens, exact names, relative/absolute/human-component paths and collection paths all resolve; start/stop folder show A/B symmetry (slug 13/13, exact name 13/13, codename path 13/13, uuid 13/13); ambiguity reports both candidate paths; negatives rejected (substring, partial codename, underscore, unknown token, the old ' > ' form, overlong path). All 8 CI checks pass on PR #1923.