feat: meta marker for stoml

[yuvrajjsingh0]

Problem

Meta marker support for stoml to effectively ship new versions and helps validating a file is stoml even if the extension is .toml

Solution

Add a meta marker to toml where the default is pinned to version 1, with a warning asking people to pin their version in the toml file itself if meta marker is not present in toml

Environment variable changes

What ENVs need to be added or changed

Pre-deployment activity

N/A

Post-deployment activity

N/A

API changes

N/A

Possible Issues in the future

Describe any possible issues that could occur because of this change

Summary by CodeRabbit

• New Features
  • TOML configuration files now include format metadata identifying the file type and version when saved.
  • TOML files can specify a format version; unsupported file types and versions are rejected.
• Documentation
  • The configuration format guide now describes TOML metadata, version validation, and includes an updated example.
• Compatibility
  • TOML files without metadata continue to be read as version 1 and produce a warning.

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/superposition_core/src/format/tests/toml.rs	0% smaller
crates/superposition_core/src/format/toml.rs	0% smaller
docs/docs/superposition-config-file/format-specification.md	Unsupported file format

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: de98509b-c5ba-4113-aa7d-eadb1f47d82a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 4bee51da-b559-4eb2-94a9-b918fbeaa9ef

📥 Commits

Reviewing files that changed from the base of the PR and between 0437831 and a581e3b.

📒 Files selected for processing (3)

• crates/superposition_core/src/format/tests/toml.rs
• crates/superposition_core/src/format/toml.rs
• docs/docs/superposition-config-file/format-specification.md

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

Walkthrough

TOML configuration files now support optional SuperTOML type and version metadata. Parsing validates provided metadata and warns when it assumes version 1. Serialization emits metadata, and tests and documentation cover the format.

Changes

TOML metadata

Layer / File(s)	Summary
Metadata contract and parsing crates/superposition_core/src/format/toml.rs, crates/superposition_core/src/format/tests/toml.rs, docs/docs/superposition-config-file/format-specification.md	The parser accepts only the supertoml type and supported versions. When metadata is absent, it assumes version 1 and logs a warning. Tests and documentation cover validation and missing-metadata behavior.
Metadata serialization crates/superposition_core/src/format/toml.rs, crates/superposition_core/src/format/tests/toml.rs, docs/docs/superposition-config-file/format-specification.md	Serialization emits the current type and version in [meta]. A test checks the output and reparsing. The documentation examples include the metadata table.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Suggested reviewers: knutties, ayushjain17

Merge Risk: ⚪ Minimal · up to a581e

The metadata example is valid, and no actionable merge-blocking issue remains after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to a581e

No introduced security issue was identified. Existing files without metadata remain readable, but exports have a new shape whose compatibility with every downstream reader is not established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The identified change affects TOML input validation and exported file contents; the available caller evidence does not establish a broader tenant, service, or privilege exposure.

Trust Boundaries and Controls

• observed — Attacker-supplied metadata is checked during TOML deserialization; unsupported values fail before conversion into DetailedConfig.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.91% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding a metadata marker for STOML/TOML files. It is concise and relevant to the pull request.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.91% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the TOML page,
The type and version mark each stage.
A missing tag brings one clear note,
While fresh exports wear metadata’s coat.
The tests hop through each parsing case,
And document the format in place.}

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🟡 Changes recommended

Address repeated/unobservable legacy-file warnings and correct the documented metadata example.

Review effort: Lite
Findings: 1

Open (1)

• Add required fields to the [meta] table example · New

What changed in this PR

Adds versioned [meta] marker support for SuperTOML files with validation, serialization, backward compatibility, documentation, and tests.

Changes:

• Validates metadata type and version.
• Emits metadata during serialization.
• Warns for unmarked files.
• Adds documentation and test coverage.

File	Description
docs/​docs/​superposition-config-file/​format-specification.md	Documents metadata syntax and validation.
crates/​superposition_core/​src/​format/​toml.rs	Implements metadata parsing, validation, warnings, and serialization.
crates/​superposition_core/​src/​format/​tests/​toml.rs	Tests metadata behavior and warnings.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.