blog · · engineering

Eight copies of a decision nobody had made

outl doctor printed 908 warnings on a 2,865-page workspace and 840 of them were the same sentence with a different path: a stale .md projection, 85% differing in nothing but the order of their key:: value lines. Pulling on that turned up a policy with no owner. outl renders properties alphabetically, that was documented nowhere, and the rule lived in eight copy-pasted sort_by calls across two crates whose comments gave three different reasons for it. Alphabetical is not a style preference: Op::SetProp carries no position slot, so declaration order is not in the log at all, and the nearest substitute is each op's HLC, the order the properties were last edited. The fix is one function, a lexical ratchet against a ninth copy, and a paragraph in docs/markdown-format.md. The second half aims the same lesson at the diagnostic, where the fix is an asymmetry rather than a threshold.

A
11 min read

outl doctor printed 908 warnings on my workspace. 840 of them were the same sentence with a different path.

The sentence said a page’s .md was a stale projection and the op log rendered different content. It was true all 840 times. What made it true, on 85% of them, was that the key:: value lines in the file sat in a different order from the one outl writes. Two findings in that run actually needed a decision from me, and they were somewhere in the middle of the scroll.

So I went to look at which order outl writes, and who had decided it.

Nobody had. Eight files decided it, separately, and they all agreed.

the order is alphabetical, and that was written down in no document

Type this into a page:

- objective
  owner:: [[avelino]]
  due:: 2026-11-30
  priority:: high

and the next time outl writes that file you get this:

- objective
  due:: 2026-11-30
  owner:: [[avelino]]
  priority:: high

That has been the behaviour for as long as key:: lines have rendered. The parser accepts any order and loses nothing; only the sequence moves, and only when outl rewrites the file. docs/markdown-format.md did not mention it. Neither did the CLI reference, nor any RFC. The closest thing to a specification was this line, written out eight times across two crates:

properties.sort_by(|a, b| a.0.cmp(&b.0));

Seven in outl-actions and one in outl-cli. Between them they cover every surface that shows a user a property: the .md renderer in crates/outl-actions/src/journal/render.rs, the outline DTO both GUI clients read and the outline parsed back from disk (crates/outl-actions/src/outline.rs), a backlink row’s leaf, the tree-derived workspace index in crates/outl-actions/src/index.rs, the clipboard, outl page prop list in crates/outl-cli/src/cmd/prop.rs and outl block prop list in crates/outl-cli/src/cmd/block_prop.rs.

the log has no slot to put a position in

Why alphabetical rather than the order someone typed? Because the order someone typed is not in the op log. Here is the whole variant, from crates/outl-core/src/op.rs:

    /// Set or clear a property on a node.
    ///
    /// `old_value` is populated by `do_op` for undo.
    SetProp {
        /// The node owning the property.
        node: NodeId,
        /// Property key.
        key: String,
        /// `None` removes the property.
        value: Option<PropValue>,
        /// Filled by `do_op` for `undo_op`. Same rule as
        /// [`Op::Move::old_parent`]: local derivation, undo-only, never
        /// authoritative to a reader of the log as data.
        old_value: Option<PropValue>,
    },

Three fields that describe the operation, and a fourth that is scratch. old_value carries the same warning as Move.old_parent, the field that looked like it recorded where a deleted block came from and did not; on my reference workspace all 14,191 stored SetProp ops carry a null old_value, so it is not a record of anything even if you wanted one. But the position is a harder case than a lying field. There is no field. A reader that folded the entire log, carefully, in order, would still come up with nothing, because the information was never serialised.

The nearest thing available is the HLC on each op’s envelope. That gives you an order, and it is the order the properties were last edited. Under that rule a peer fixing one typo in owner:: moves owner:: to the bottom of the block, on every device, in a file that is probably in git. The reorder would arrive as a sync event rather than an edit.

The other option is a real position field on SetProp. outl-core’s invariant 6 says undo_op must be the exact inverse of do_op for every op, so that field needs its own old_* twin recording the previous order, and the previous order is not in the op. It is a permanent widening of the sync surface, paid on every property write forever, for the sequence of three formatting lines.

So alphabetical is a decision, and it is the only order outl can still name: it is a function of the keys and of nothing else, so every device derives it identically with no coordination. docs/markdown-format.md now says that, including the two rejected alternatives, which is the part a user can argue with.

a HashMap is why an order has to be imposed at all

Properties live in one flat map on the tree, in crates/outl-core/src/tree/mod.rs:

    pub(super) properties: HashMap<(NodeId, String), PropValue>,

std’s default hasher seeds itself from the operating system, and the standard library documents the iteration order as arbitrary. Two runs of the same binary over the same op log walk that map in different orders. A projection that imposes no order of its own therefore renders different bytes from the same log on every boot, and the .md is the artifact outl exists to produce: the thing you read, diff and commit. “Same content, different bytes” on a 2,865-page workspace is a whole-workspace diff, for free, every time you open the app.

The unit test for it does not mock anything. It builds the pairs, reverses them, rotates one copy by a prime, and asserts both come out identical:

        let mut once = properties.clone();
        sort_in_presentation_order(&mut once);
        let mut again = properties;
        again.rotate_left(17);
        sort_in_presentation_order(&mut again);

        assert_eq!(once, again);

And none of that ever happened, which is the whole trap. All eight copies sorted. Not one surface was shipping seeded bytes, so the map’s order never reached a rendered file, and no test could have failed. The 840 stale pages came from the other direction entirely: a bulk edit made outside outl left those files in an order outl does not write, and the next projection would correct them. The hash map is the reason a policy has to exist. The eight copies are the reason nobody had noticed there was one.

The test that now holds the line states it plainly in its own module doc:

They agreed on the answer, which is what made the split invisible: nothing a user or a test could see was wrong, so “what order do properties render in” had eight homes and no address.

three reasons, each of them true, none of them the whole thing

The comments that survive the consolidation are the sharpest evidence of what eight copies cost. The renderer’s reason is the hash map’s per-process seed. The reason given by the reader that builds an outline from a parsed .md, in crates/outl-actions/src/outline.rs, is a different one:

    // The one place an authoring order exists — the parsed `.md` keeps
    // the sequence the user typed — and it is dropped on purpose, so a
    // block renders the same inside its own page (this path) and as a
    // backlink elsewhere (the workspace path, which has no order to
    // keep). `crate::tree::sort_in_presentation_order` owns the rule.

And the owner’s reason is the one above: declaration order is not in the log.

Every one of those is true. Not one of them is sufficient. The backlink argument is satisfied by any deterministic order. The hash map argument is satisfied by any imposed order at all. Only the third explains why alphabetical rather than, say, insertion order recorded in a side table. Three correct partial answers to one question is what a fact with no owner looks like from the inside, and you cannot tell it apart from a settled design by reading any single file.

The owner is five lines in crates/outl-actions/src/tree/props.rs, and the rest of it is documentation:

pub fn sort_in_presentation_order(properties: &mut [(String, String)]) {
    properties.sort_by(|a, b| a.0.cmp(&b.0));
}

a lexical ratchet, which only catches the way the eight got here

crates/outl-actions/tests/property_order_owner.rs walks the src/ tree of five crates and fails if any file other than the owner contains the statement the eight spelled out. The constant it searches for is deliberately not the comparator:

const PROPERTY_SORT: &str = "sort_by(|a, b| a.0.cmp(&b.0));";

The semicolon is load-bearing. a.0.cmp(&b.0) on its own is a perfectly good first key in a composite sort, and two of them exist in this codebase for unrelated things, so matching the expression would turn the test into an allowlist of exceptions, which is a second copy of the fact wearing a different hat.

It also refuses to scan a crate as zero files. The directory walk returns quietly on a path it cannot read, so a renamed crate would silently contribute nothing and a total large enough to look healthy is reached by outl-actions alone:

        assert!(
            sources.len() > before,
            "no `.rs` file found under {} — this surface does not resolve, \
             so it is being scanned as nothing at all",
            dir.display()
        );

outl-cli held the eighth copy, which is exactly the crate a sloppier version of this test would have skipped.

What it does not catch is written in its own header: a ninth caller that writes sort_by_key(|p| p.0.clone()) passes this test and is still the defect. The ratchet catches copy-paste, because copy-paste is how the eight actually arrived. That limit is stated rather than papered over, and the behavioural half lives in the owner’s unit tests instead.

the user who hand-sorts a file is the one who pays

Nothing a user sees changed in this release. That is worth being blunt about, because it is also the cost.

If you keep .md files that outl reads and you have arranged a block’s properties in an order that means something to you, outl will reorder them the next time it writes that page, and there is no setting. The write is not always something you did: a peer’s ops arriving, outl serve’s projection sweep, or outl doctor --repair will all do it. The documentation now says so, and the best advice it can give is scheduling rather than avoidance: if your files are in git, run outl doctor --repair once after a bulk external edit so the reordering lands in one commit instead of leaking into the next hundred.

That is a real limitation with a documented workaround, which is strictly better than a real limitation nobody wrote down, and strictly worse than not having it. What changed is that the behaviour can now be changed, or argued with, in one place.

840 copies of one sentence is a report with no reader

The other half of this change is the tool that found the problem, because it had the same shape of defect pointed at the user instead of at the code.

A stale page whose re-projection removes no content is a page with nothing to decide. Usually a property reordered, sometimes whitespace normalised. There were 840 of them, each printing its own warning, and outl doctor is the command you run when something is wrong. A report where 840 of 908 lines are one sentence reads as a broken workspace even when it is describing a cosmetic rewrite.

They arrive as one counted line now, in crates/outl-cli/src/cmd/doctor/tree.rs, with a tail that sample_suffix builds. Its doc comment writes the tail out as it reads on exactly this workspace:

/// `, e.g. a.md, b.md (and 835 more; \`--json\` lists every one)` — the
/// tail a grouped finding carries so it points somewhere instead of only
/// counting.

Both halves of that tail are load-bearing. Five paths is enough to recognise a pattern, as in “oh, those are all journals”, and a bare count is a dead end: you cannot tell a systemic rewrite from one odd page, and you have nowhere to look next. The pointer at --json matters more than it looks, because the human listing of repairable items is itself capped at 20 while --json carries every path, so from the 21st page onward that single grouped line is the entire human-readable account of it.

an asymmetry, because a threshold would have been easier

The obvious design is a threshold: print each finding individually until the list passes some N, then collapse. That is wrong in the direction that matters, and the code says why in a comment rather than in a constant:

                if lines_removed > 0 {
                    // Named individually, always, however many there are.
                    // This is the page where the user has something to
                    // decide, and a count cannot carry that. The pages
                    // that remove nothing are counted instead, and the
                    // asymmetry is the design: a count is enough when
                    // there is nothing to decide, and never enough when
                    // there is.

A page whose re-projection would delete lines from disk is named, with its own line count, however many such pages there are. Five hundred pages that each lose a line is precisely the situation where you need all five hundred names, and it is also precisely where a threshold would have collapsed them. a_page_that_loses_content_is_named_even_while_the_harmless_ones_are_counted in crates/outl-cli/src/cmd/doctor/tests/tree.rs pins both arms at once: one page named with removes 2 content line(s), one page counted, and an assertion that the grouped count says 1 page(s) and not 2.

That lines_removed number has its own history. It is measured by asking whether each line on disk survives the new render, which is a different question from whether the log knows the line, and getting the two confused is how a page with nothing to lose looked identical to a page nothing could vouch for.

The mirror of the rule lives in crates/outl-cli/src/cmd/doctor/print.rs, where --repair lists what it did: cap the successes, never the refusals.

        for action in rep
            .actions
            .iter()
            .filter(|a| !a.ok)
            .chain(rep.actions.iter().filter(|a| a.ok).take(LIST_CAP))

Refusals first, uncapped, however long the list is. A repair outl declined to perform is the one thing in that output you cannot reconstruct from the counts underneath it, and a refusal nobody hears about is the silence the refusal exists to prevent.

one log, described three ways

The same change carries a third instance, small enough to state in a paragraph. outl workspace info printed ops: 332 on a workspace whose ops/ directory holds 228,943. Not a rounding error: three orders of magnitude, on the one command you run to ask how big your graph is, and it reads as data loss.

The count was never wrong, it was answering a different question. A workspace that booted from a snapshot replays only the delta above the cutoff, so the resident log holds that delta and nothing below it. outl_actions::activity had already written the rule this broke, that a partial count is never presented as a total, and the fix carries one boolean from Workspace::booted_from_snapshot into the payload so the human line, the JSON and the desktop status bar in crates/outl-desktop/src/components/StatusBar.tsx cannot describe one log three ways. It stays a resident count on purpose: the true total needs a full parse of every .jsonl, which outl doctor pays because integrity is its job and a summary command has no reason to.

agreement is not ownership

The thing I keep taking from this one is that eight call sites which agree look exactly like one decision, from every angle except the one that matters. Nothing is wrong. No test fails. There is nothing to grep for, because each copy is individually correct, and each comment next to it is individually true. The absence only becomes visible when somebody asks why the behaviour is what it is, and the honest answer is that no one chose it, the first implementation did, and seven more agreed with it by reading over its shoulder.

So the question to ask of a behaviour is not whether it is consistent. It is whether a user who asks why can be sent to one place, and whether the person who wants to change it can find everyone who would be affected. If the answer to either is “grep and hope”, the consistency you have is a coincidence that has not been tested yet.

The owner is sort_in_presentation_order in crates/outl-actions/src/tree/props.rs, the ratchet is crates/outl-actions/tests/property_order_owner.rs, the user-facing half is docs/markdown-format.md under Property order, and the issues are #285 and #286 in the outl repository.