Curriculum · What happened to a position (holding/1)

Holding a Position: Transitions, Not States

5 lessons · For: Anyone recording what an office owns and what became of it — where a mutable current value would be a lie waiting to happen

The tempting way to record what you own is a table with a "current value" column you update. It is also the way a record starts lying: the moment you overwrite the old value, the history of how you got here is gone, and a reader cannot tell a careful mark-down from a quiet cover-up.

holding/1 refuses that. It records positions as transitions — what happened and when — and derives the present from the history rather than storing it. A change is a new entry that supersedes the old one, which stays in place. It is the ledger idiom (entries, never a mutable balance) pointed at ownership.

Five lessons. You will finish able to record a position honestly, including the parts nobody enjoys recording.

Lessons

Why a position is a history, not a current value

You should be able to: Explain what is lost when a position is stored as a mutable current value.

A position has a past, and the past is often the interesting part: what was acquired, at what terms, what happened to it since. A single "current value" throws all of that away and keeps only the answer — which is exactly the information a reader needs to trust the answer.

Worse, a mutable value is unfalsifiable. If the number can be overwritten, a correction and a concealment look identical from the outside, and a reader who finds one glossed re-reads everything else looking for more. The record loses the one thing it was for.

So holding/1 keeps the history and derives the present, the same way a ledger keeps entries and derives a balance. The current state is a function of the transitions, never a field somebody set.

Source: FlashyOS — @flashyos/holding (holding/1)

Transitions, not states — supersede, never edit

You should be able to: Describe how a position is revised without destroying its history.

A holding is a sequence of transitions: acquisition, revaluation, partial realisation, write-off. Each is an entry that says what changed and when. Revising a position means publishing a new entry that supersedes an earlier one — the earlier entry is not edited or deleted, it is marked as superseded and left in place.

This is the same correction discipline the estate keeps in every format: a backlog item is revised, a pulse retracted, a shipped classification appended to — never edited in place. A superseding entry carries a reason, so the record shows not just that something changed but why.

The result is a position whose entire history is legible. A reader can replay the transitions and arrive at the present, or stop at any point and see what was true then. Nothing about the past has to be taken on trust, because nothing about the past was overwritten.

Source: FlashyOS — holding/1, transitions not states

What an entry must carry, or not exist

You should be able to: State the fields an ownership transition requires and why a partial one is not emitted.

An ownership edge carries a real instrument, a percentage, and a date, or it is not emitted at all. A half-specified holding — "we own some of that, roughly, at some point" — is worse than silence, because it reads as a fact while being one nobody can check.

This is the estate's "an empty register is honest; an invented one is not recoverable" rule at its sharpest. A cap table is a record before it is a spreadsheet, and on a record whose whole value is that it can be trusted about exactly this, a fabricated or vague entry is not a small error — it is the one that makes every other entry suspect.

So the discipline is binary: if you cannot state the instrument, the size and the date, you do not have a holding entry yet — you have a note to yourself, which does not belong in the published record.

Source: gord.holdings — the cap table as a record

Realisations, write-offs, and unresolved positions

You should be able to: Record the outcomes nobody enjoys recording, plainly.

The test of an ownership record is not how it states a gain — anyone states those — but how it states a loss. A realisation, a write-off, and a position that is simply unresolved are each recorded plainly, as their own transitions, in the same log as the acquisitions.

A record that quietly omits the write-offs is not a smaller true record; it is a false one, because it implies a track record that did not happen. The estate's rule is that a reader who finds one loss glossed will trust none of the wins — so the honest move is also the only credible one.

An unresolved position is stated as unresolved, not rounded to a guess or left off. "We do not yet know what became of this" is a fact, and recording it is what lets the eventual resolution be a transition rather than a surprise.

Source: gord.holdings — positions revised by a new statement

What the projection refuses

You should be able to: Explain why the published projection refuses currency fields by name, at any depth.

A holding/1 record carries the facts of a position; it does not carry a computed money value, and the projection refuses currency fields by name — many of them, checked at any depth — so a caller cannot slip a valuation into a record that is supposed to state transitions and let a reader derive worth.

This is the same rule the estate keeps for every derived figure: a value that could be asserted is a value a caller could fake, so it is computed at read from a rate or price the record does not hold, never stored. A projection refuses rather than trims — it names the forbidden fields, so a field added later cannot leak in through a spread.

The effect is a record that says what happened and refuses to say what it is worth, leaving the second to whoever holds the prices. That separation is what keeps the ownership log a record of facts rather than a marketing document about their value.

Source: FlashyOS — a projection refuses rather than trims

Frequently asked

Why not just keep a current value for each position?

Because overwriting it destroys the history a reader needs to trust it, and makes a correction indistinguishable from a concealment. holding/1 records transitions and derives the present, the ledger idiom applied to ownership — entries, never a mutable balance.

How is a position corrected?

By publishing a new entry that supersedes the earlier one, with a reason. The earlier entry stays in place, marked superseded — never edited or deleted. It is the same append-a-correction discipline the estate keeps in backlog, pulse and the shiplog.

Why does the record refuse to carry a money value?

Because a stored value is one a caller could fabricate. A holding/1 record states the facts — instrument, percentage, date, and what happened — and the projection refuses currency fields by name at any depth. Worth is derived at read from prices the record does not hold, so the log stays a record of facts, not a valuation anyone set.