Frozen snapshot model: make loaded documents immutable (Frontmatter / YamlMapping)

Open
#181 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp, markdown, yaml
Domain
backend

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

.NET enhancement

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, YamlValue collections), 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.sln and dotnet test producers/OkfProducer.sln green.

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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from jchable/okf4net

All issues in jchable/okf4net

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.