Skip to content

Changelog

Single project changelog. All entries live here (rendered on site under Development).

[Unreleased]

[2026-03-21]

Changed

  • Decision-perch subscript: \(\circ\) → \(\sim\) (repo-wide): Adopted \sim as the canonical math subscript for the decision perch, replacing \circ. This aligns bellman-ddsl with SolvingMicroDSOPs notation and frees \circ for its standard use as function composition. Updated across all spec pages, theory docs, examples, formal MDPs, dev-specs, working notes, and the Matsya system prompt.
  • symbols-conventions.md: perch index table, filtration definition, Rosetta Stone, all transition subscripts (\(\mathrm{g}_{\prec\sim}\), \(\mathrm{g}_{\sim\succ}\))
  • Syntax-semantic-rules: 01, 06, 07, 08
  • Theory: 03-symbol-system, 05-bellman-theory, 06-representation-maps, 07-execution-pipeline, MDP-foundations/index, dolo-sym-to-ddsl-core-mapping
  • Examples: solving-conjugates, unemployment/index, formal MDPs (noport_stage_mdp, unemployment_branching_mdp)
  • Dev-specs: spec_0.1l-branching-theory, spec_0.1eA-stage-operators-to-dolo
  • References: ddsl_schema, dolo-to-doloplus-syntax-changes
  • AI/working: dolo-plus.md, T-calc-core.md, session notes, perch-index exploration
  • Matsya prompt (Bellman-DDSL.md): transition notation, branching notation
  • Matsya system prompt fixes (HIGH + MEDIUM severity):
  • max_{c}() vs max_{c}{}: now accepts both; braces are canonical for operator bodies, parentheses accepted for named-operator arguments
  • ShadowBellman: removed false "DEPRECATED" claim — ShadowBellman is valid in dcsn_to_arvl_mover; MarginalBellman is valid in cntn_to_dcsn_mover
  • [~] decision tag: softened prohibition — unmarked is preferred, [~] accepted as explicit marker
  • Unicode parameters: softened mandate — both β/ρ and beta/rho are valid
  • _opr alias: noted as valid synonym for _mover (used by canonical consumption_savings_iid example)
  • V_cntn branching notation: replaced with spec 0.1l canonical V[>][label] sugar (looked up via values.V[>] map)

Key Insights

  • \(\sim\) over \(\circ\) for decision perch: Using \sim eliminates ambiguity with function composition (\mathbb{I} \circ \mathbb{B}). The tilde visually suggests "approximately here" or "the reference point" — the decision perch is the unmarked default from which \prec and \succ are defined. SolvingMicroDSOPs already uses \sim; adopting it in bellman-ddsl unifies the notation across the two repositories.

[2026-02-12]

Added

  • spec 0.2a (compiler pipeline architecture): Lean 4-inspired architectural spec for the full dolo-plus compiler pipeline.
  • docs/development/dolo-plus-impl/spec_0.2a-compiler-pipeline-architecture.md
  • 8-stage pipeline (Parse → Validate → Υ → Methodize → Calibrate → Ρ → Solve → Analyze) with typed intermediate representations at each stage.
  • Operator registry with attribute-based registration (pluggable methods as Lean-style tactics).
  • Immutable environment threading (scoped extensions pattern).
  • Template-driven Ρ-map code generation.
  • Multi-error validation following Lean's collect-all-errors approach.
  • Composition pipeline design for periods and nests.
  • Lean 4 ≈ CORE elaboration note: added analogy connecting Lean 4's elaboration pipeline to the φ (SYM → CORE) translation in 08-sym-core-architecture.md, for-engineers.md, and homepage.
  • AI/matsya.md: added Matsya RAG configuration file to repo.

Changed

  • Perch tag propagation (repo-wide):
  • Parser (packages/dolang/dolang/grammar.py): added normalize_perch_glyphs() pre-parse step — [<]/[>] glyph tags normalize to canonical [_arvl]/[_cntn] before Lark parsing.
  • Parser (packages/dolo/dolo/compiler/doloplus_translator/transforms.py): defensive normalization in perch_to_time() and shift_perch_tags().
  • MDP foundations (docs/theory/MDP-foundations/index.md): full notation rewrite — subscript → superscript perch indices (\(x_{\prec}\) → \(x^{\prec}\)), transition functions (\(\mathrm{g}_{\prec}/\mathrm{g}_{\succ}\) → \(\mathrm{f}/\mathrm{g}\)), preferred SYM tags ([<]/unmarked/[>]).
  • Homepage, for-engineers, language guide, dolo-dynare-relationship, stage-structure-and-timing: updated to preferred perch tags and superscript notation.
  • Canonical naming: "Dolo+" → "dolo-plus": global rename across 51 files (387 occurrences). Updated CLAUDE.md canonical terminology table accordingly.
  • Value object perch tags: V → V[-] and dV → dV[-] in all YAML snippets where decision-perch value objects appeared bare. Value objects that exist at all three perches require explicit [-] tag at the decision perch (unlike controls/states where unmarked = decision by convention). Updated in homepage, symbols-conventions, for-engineers, consumption_savings_iid example doc, ddsl_foundations proposal.

Key Insights

  • Elaboration ≈ φ (SYM → CORE): Lean 4's elaboration (surface Syntax → kernel Expr) is the precise analogue of the Bellman-calculus φ map (dolo-plus YAML → normalized typed stage IR). The kernel/elaboration separation principle means CORE should be small and trusted; all complexity lives in the SYM-to-CORE desugaring.
  • Unmarked ≠ bare for value objects: The "unmarked = decision" convention works for controls and states (which live at exactly one perch), but value objects (V, dV) that span multiple perches must always carry an explicit perch tag. This is a measurability distinction: V[-] asserts "V evaluated at the decision σ-algebra", which differs from V[<] and V[>].
  • Pluggable methods as tactics: Lean's tactic framework (registered proof strategies dispatched by name) maps directly to the DDSL operator registry (registered solver methods dispatched by method tag). The @register_method decorator pattern enables extensibility without modifying core pipeline code.
  • Persistent IRs prevent black-box pipelines: Every pipeline stage should produce a serializable, inspectable intermediate representation. This makes debugging, diffing, and testing tractable — you can inspect a methodized stage without running calibration.
  • Immutable environment threading: Following Lean's scoped extensions, each pipeline stage should extend (never mutate) the symbol/method environment. This is especially important for composition, where each stage in a period has its own scope joined by connector renames.

Added (prior)

  • Semiconjugate solve (spec 0.1eA implementation): full pipeline from dolo-plus split-file stages through accretive nest build to EGM solve with Stachurski's semiconjugate transform.
  • explore/semiconjugate_solve.py — three solve methods (egm black-box, egm per-period, manual loop), all verified to exact match.
  • explore/semiconjugate_solve.ipynb — hand-holdy notebook with Stachurski references, iterates lemma, per-cell math explanations.
  • return_internals for egm() (dolo): returns raw sa0/xa0/z arrays alongside EGMResult, enabling per-period EGM calls without cubic-resampling error accumulation.
  • make_egm_dr0_from_internals() (dolo): builds a linear-interpolation dr0 callable from raw EGM internals — matches what egm() uses between its own internal iterations.
  • mapping_set() (dolang): yaml_nodes.mapping_set(m, key, value_node) for setting/updating keys in YAML MappingNode data.
  • spec_0.1p (intermediate-variable indexing): placeholder spec for c[_a], m_d[_a] bracket syntax — intermediate variables as local perch indices within mover sub-equations.
  • docs/development/dolo-plus-impl/spec_0.1p-intermediate-variable-indexing.md
  • Deliverables addendum: docs/deliverables-AAS-Feb2026.md — polished Feb–Apr 2026 SOW addendum with tags and repo links.

Fixed

  • Model.set_calibration() (dolo): now works with MappingNode data from yaml.compose(). Previously crashed with TypeError: 'MappingNode' object is not subscriptable.

Changed

  • solving-conjugates.md: front-to-back review — fixed Ŝ vs S operator labelling, rewrote pseudocode to use real repo APIs (doloplus_to_dolo, egm()), added "level values vs EGM objects" conceptual seam, removed nonexistent helpers.
  • spec_0.1eA: fixed β-placement convention (β in direct_response_egm, not expectation), added import numpy, renamed Step 4 to reflect mr(a) output.
  • noport_stage_mdp.md: \mathrm{T} → \mathbf{T}, E → \mathbf{E}.
  • CLAUDE.md: added single-changelog rule (no root CHANGELOG.md).

[2026-02-11]

Docs

  • MDP foundations rewrite: rewrote theory/MDP-foundations/index.md with ≺/·/≻ perch notation, B/I backward movers, intra-stage branching diagrams, and clean forward/backward separation.
  • Nav restructure: restructured mkdocs nav to match folder layout; added network scroll animation.
  • Homepage: updated homepage algebra section with Bellman calculus identity.

[2026-02-09]

Docs

  • Condensed MDP foundations, reordered Theory nav, toned down nav CSS.
  • Added branding assets; removed legacy operator YAMLs.
  • Embedded Matsya (MatsΥa) chatbot on homepage (MatsΥa (AI) button).
  • Refreshed site landing page, nav, and RAG demo.

[2026-02-07]

Added

  • DDSL YAML schema: docs/dolo-plus-spec/reference/ddsl_schema.md with v0.1 stage/period/nest field definitions.
  • Discrete housing grid: XH: "@def linspace(H_min, H_max, n_H)" in housing_owner space declaration (design principle: grid defines the mathematical space → parameters, not settings).

Docs

  • Comprehensive example documentation for all models (consumption_savings_iid, housing_owner, port_with_shocks, formal MDPs).
  • Combined port_with_shocks and period-nests into single page.
  • Updated period-nests doc to use actual period YAML files.
  • Fleshed out core ideas on index page; restructured documentation sections.
  • Dark teal Material theme with custom CSS overrides.

Fixed

  • Broken anchor link in port_stage.md.
  • Missing link to port-with-shocks in examples index.
  • .gitkeep for overrides dir so CI can find custom_dir.
  • Normalised notebook format via nbconvert.

[2026-02-06]

Added

  • spec 0.1eA (stage-to-operator translation): implemented generic translator + backward step orchestrator.
  • explore/transformations/egm-stage-operators-to-dolo/translate_stage_to_operator.py
  • explore/transformations/egm-stage-operators-to-dolo/backward_step_noport_cons.py
  • Mapping tables for cons and noport operators.
  • test_stage_operators.py — regression test against vanilla Dolo.
  • DDSL overview presentation: docs aimed at DSAI audience.
  • Compiled stage operators as vanilla Dolo models.
  • mkdocs-callouts plugin in CI workflow.

Docs

  • Comprehensive review of spec 0.1eA (stage operators).
  • Added intelligent perch offset handling to translator note.
  • Added overview section with new docs to index.
  • Quick Summary link in Overview section.

[2026-02-05]

Docs

  • Obsidian/MkDocs dual rendering: Added mkdocs-callouts plugin to automatically convert Obsidian-style callouts (> [!type]) to MkDocs admonitions during build.
  • spec_0.1h restructured: Converted nested callouts to collapsible ??? type details sections for proper HTML rendering while preserving Obsidian compatibility.
  • Warning block with open questions now uses expandable sections for each decision point
  • Separated nested [!note] from [!important] callout

[2026-01-29]

Added

  • spec_0.1g (bare symbol resolution): Allow bare symbols in adc-stage equations without explicit perch indices.
  • packages/dolang/dolang/perch_resolver.py — AST walker for native perch inference
  • packages/dolang/dolang/grammar.lark — bare symbol support in assignment LHS
  • packages/dolo/dolo/compiler/model.py — integration for adc-stage dialect
  • argmax grammar support: Added argmax_{} syntax mirroring existing max_{} structure.
  • packages/dolang/dolang/grammar.lark — argmaximization rule
  • packages/dolang/dolang/grammar.py — argmaximization printer method
  • port-with-shocks library bindings:
  • calibration.yaml — parameter values (β, ρ, R, shock parameters)
  • settings.yaml — numerical settings (grid sizes, quadrature nodes, simulation)
  • methodization.yml — scheme/method pairings for all three stages
  • Explore scripts:
  • explore/stage_explorer.py — inspect stage files (symbols, equations, metadata)
  • explore/stage_pipeline.py — run methodize/calibrate/configure pipeline
  • explore/stage_pipeline.ipynb — notebook demonstrating accretion approach

Docs

  • Updated spec_0.1-overview.md with implementation status table for all milestones (0.1a–0.1h).
  • Documented implementation locations and example files for each completed spec.

[2026-01-25]

Added

  • Repository-level CHANGELOG.md plus rendered docs/changelog.md page and MkDocs nav entry.
  • AI/working/AAS/25012026/session.md (today’s working log).

Docs

  • Refined docs/specs/dolo-plus-v0.1/syntax-semantic-rules/periods-and-models.md:
  • Made twisters explicitly core model-level DDSL syntax (inter-period wiring), including an indexed/template form (t, t+1).
  • Clarified the DDSL/orchestration boundary: DDSL specifies artifact interfaces, not construction procedures.
  • Clarified “bindings are immutable once instantiated” (no hidden state / referential transparency stance).

Changed

  • Added/updated internal process guidance:
  • AI/claude.md now points to AI/road-map-todo.md (roadmap/decision tracker) and records the proposed periods/models instantiation boundary as pending team review.
  • AI/road-map-todo.md includes a rename note (replacing older AI/todo.md).

[2026-01-24]

Docs

  • Introduced/expanded “0.4 Periods and models (assembly)” to formalize:
  • Syntax collections (template libraries) vs instantiated model instances (time-expanded constructions).
  • Orchestration-layer responsibility for time-indexing, per-period calibration binding, and inter-period wiring.
  • The twisters.yaml concept for inter-period variable and value-function wiring, including a loop-generated connections: pattern.
  • Polished internal consistency across Dolang+ syntax/semantics docs (terminology: period template vs period instance; connectors vs twisters; what lives in SYM vs orchestration).
  • Updated 05-methodization.md framing to align with the “syntax collection / orchestration” separation.

Added

  • Working-note digest: Pflug & Pichler (2014) multistage stochastic optimization concepts relevant to scenario trees, information structure, and nonanticipativity.

[2026-01-23]

Added

  • New Dolang+ example syntax collection: packages/dolo/examples/models/doloplus/port-with-shocks/
  • Stage templates: noport_stage.yaml, port_stage.yaml, cons_stage.yaml
  • Period templates: cons_period.yaml, port_cons_period.yaml, cons_port_period.yaml
  • README documenting “optimal” period YAML direction and identity/rename connector conventions.

Docs

  • Restructured Dolang+ syntax/semantics documentation into a flat, numbered set of pages under:
  • docs/specs/dolo-plus-v0.1/syntax-semantic-rules/
  • Added “From syntax to formal problem definition” and “Methodization” as numbered overview pages.
  • Updated MkDocs navigation to make:
  • dolo-plus a top-level section with separate implementation and Dolang+ syntax and semantics groupings.
  • Unified-framework sections render as separate pages under a “Unified Framework” group.
  • “Example: Portfolio Choice with Correlated Shocks” grouped under a single navigation subsection.
  • Added custom sidebar styling via docs/stylesheets/extra.css to visually distinguish major nav section headers.