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 code column; each folder's codename is derived by a pure function mirroring the source_name slug 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. fx under 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

PR Title
#1924 [agile] Close folder-code-identifier task and synthetic story
#1923 [ores.shell] Resolve market simulator folders by codename path

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/fx and /synthetic/2026realistic/fx all 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.

Emacs 29.3 (Org mode 9.6.15)