Frozen snapshot model: make loaded documents immutable (Frontmatter / YamlMapping)
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 12/100
Research direction
The mutation points are Frontmatter.Set in src/OKF4net/Frontmatter.cs (around line 96) and Frontmatter.AsMapping() (around line 87), which exposes the internal YamlMapping. The first deliverable is an inventory of every mutating member and caller across src/ and producers/, starting with BundleConceptWriter.WriteConcept. Done means that inventory with a cost estimate for the read-only-view and defensive-copy options, agreed with the maintainer before any code changes.
Written by the indexing model from the issue text.
Description
Area
src/OKF4net (OkfDocument, Frontmatter, Yaml/YamlMapping and friends), and every in-repo site that mutates a loaded document.
Why it matters
The bundle provider design (#139) shares one loaded snapshot (Bundle) between several consumers through a BundleHandle (OkfBundleTools, OkfContextProvider, the catalog sources). The snapshot is swapped atomically on refresh, but its contents are not immutable: Frontmatter.Set mutates in place (src/OKF4net/Frontmatter.cs:96) and Frontmatter.AsMapping() returns the internal YamlMapping itself (:87). Any caller can therefore change a concept inside the shared snapshot, with no change of BundleVersion and no refresh — every other consumer then sees content that is in no storage. An external review of the #139 spec reproduced it (snapshot frontmatter mutable: changed).
Decision (2026-10-09): #139 ships with a weaker, documented guarantee — the snapshot is shared, mutating it is unsupported, and in-repo mutation sites are audited (the writer already works on a shallow copy, see BundleConceptWriter.WriteConcept(string, Frontmatter, string)). This issue tracks the real fix.
Proposal (to cost)
A genuinely frozen published model:
- read-only views for documents held by a snapshot (
Frontmatter,YamlMapping,YamlValuecollections), with explicit copy-to-mutable (ToBuilder()-style) for callers that edit; - or defensive copies at the snapshot boundary (cheaper to introduce, more allocation per read).
Either is a breaking change to Frontmatter / YamlMapping, whose mutability is used by producers (OkfDocumentBuilder, producers/) and by the writer. The first deliverable is an inventory of every mutating member and every caller, in src/ and producers/, with the cost of each option.
Acceptance (when picked up)
- A test that mutates a document obtained from a shared snapshot fails to compile, or throws, or leaves the snapshot unchanged — per the chosen option.
dotnet test OKF4net.slnanddotnet test producers/OkfProducer.slngreen.
Depends on
#139
Effort
M/L
🤖 Generated with Claude Code
- Dominant language
- C#
- Stars
- 4
- Forks
- 1
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 32
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from jchable/okf4net
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
.NET bug
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
test
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 1-3 hours Newbie friendliness 90/100
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 Under an hour Newbie friendliness 82/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
area/backend type/bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
umbraco/Umbraco-CMS#24668 · 1 comment ·
Maintainers usually reply within 1 day
-
Pri3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
MicrosoftDocs/windows-dev-docs#6205 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
area-ai untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
dotnet/extensions#7956 ·
Maintainers usually reply within 1 day