Skip to content

Return Studio

Configuration engine

Tier: Configure · Requirement module: Return Template Builder · Status: 🟨 In progress (line-item spine)

Purpose

The supervisor defines what it collects. Return Studio holds every return template — sections, line items, formulas, repeating schedules, validation rules, attachment requirements, checklists, and due-date policy — as versioned configuration with effective dates.

This is the engine that makes the first law true. Regulatory returns are structured financial reports, not surveys.

Critical juncture (AMC Excel reality)

Real returns (e.g. sec_latest_template.xlsx — AMC quarterly) have:

  • Hierarchical statements with formulas (Income Statement, Balance Sheet)
  • Period columns (YTD, Current Quarter, Previous Quarter)
  • Many repeating schedules (funds, assets, top-N clients, investments)
  • Cross-sheet references
  • Header metadata and a declaration

Pure questionnaire builders fail here. Full in-browser spreadsheet engines are overkill for v1. Hybrid model — KD-015.

Scope

Capability Status Notes
Template identity + versions ✅ Stub catalogue; Cadence pins version on materialise
Section types (HEADER · STATEMENT · REPEATING · DECLARATION) ✅ Spine Schema + AMC sample seed
Statement line-item tree + period columns ✅ Spine Codes, hierarchy, formula text
Constrained formula language 🟨 Stored now; Assay evaluates later (SUM_CHILDREN, SUM(…), REF(…))
Repeating schedule field defs ✅ Spine Excel upload / grid mapping later
Semi-automatic Excel → template import ⬜ Assistive importer + human review — not magic
Field library (cross-template reuse) ⬜
Validation rules with citations 🟡 Designed
Reviewer checklist ✅ Config shape
Version immutability (draft → publish) 🟡 Partial
In-browser spreadsheet engine ❌ Rejected for v1

Hybrid anatomy

return_template
  └── return_template_version
        └── return_section[]          HEADER | STATEMENT | REPEATING | DECLARATION
              ├── return_section_column[]     YTD, CURRENT, PREVIOUS, …
              ├── return_line_item[]          tree (parent_id), formula, is_calculated
              └── return_repeating_field[]    columns of a repeating grid
Section type Example (AMC file) Firm UX (target)
HEADER Institution, period, FX rate Simple fields (some from Registry)
STATEMENT Income Statement, Balance Sheet Line-item grid; calculated cells read-only
REPEATING Mgmt fees by fund, fixed assets, top-N Grid and/or Excel upload
DECLARATION Yes/No + figures Simple form

Licence binding: focused templates per return type, linked via obligation rules → licence category — not one mega-template with conditional sections for v1.

Submission storage (later, Strata): keep analytics-friendly values keyed by line_item_id / repeating_field_id + column + row_index — prefer jsonb per KD-002, not three typed value columns.

Formula language (v1 contract)

Platform-owned calculations. Firms enter leaf cells only.

Form Meaning
SUM_CHILDREN Sum immediate children for the same column
SUM(1.4.1, 1.4.2, 1.4.3) Sum named sibling codes (same section)
REF(SCHEDULE_2.TOTAL, CURRENT) Cross-section reference
PREVIOUS(1.1) Prior accepted period (Assay/Strata later)

Not supported in v1: pasting raw Excel formulas with cell addresses. Importer may suggest normalised formulas; humans confirm.

Owns

  • Template definitions and versions
  • Section / line-item / repeating-field structure
  • Formula definitions (execution → Assay)
  • Validation rule definitions with citations
  • Due-date policy and checklists
  • Risk model weights (when wired)

Does not own

Sample

Flyway seeds ZW_AMC_Q from the AMC Excel shape: header, income statement (partial tree), balance sheet (partial), one repeating schedule (management fees), declaration — enough to browse and debate in Studio.