@flashyos/holding

holding/1 — a log of what happened to the positions an office holds.

Transitions rather than states. The current state of a position is derived from its log and never asserted, which is the whole design: a table of states can be edited, and a log can only be appended to.

npm i @flashyos/holding

Or take the vendored emitter and run it with nothing installed at all:

curl -O https://unpkg.com/@flashyos/holding/vendor-holding.mjs
node vendor-holding.mjs board

What it is for

An office that publishes only its wins has published a track record, and every reader knows it. This format exists so that "we do not abandon a position when it goes wrong" can be a column somebody counts rather than a sentence somebody writes.

Three rules carry that, and none of them can be relaxed by a caller:

recorded may not precede at. The gap between when a thing happened and when it was written down is published, per entry and as a median. A register that records good news the same week and bad news eighteen months later says so in a number, and no amount of copy improves it.

A cross-entity transition is invalid without consent. Moving a position between entities under common control requires a consent block naming every affected party, a basis each of them also holds, and a date that does not follow the event — consent afterwards is ratification, and the format will not let the two be written as the same thing. "Restructured with full consent and alignment" stops being a sentence anybody can write and becomes a document somebody must hold.

No currency figures in version 1. Publishing marks is a regulated communication in most jurisdictions an office of this kind operates in; a distribution is harder to flatter than a multiple; and a money column would be the only column anybody read. Fifteen field names are refused by name. See SPEC.md §6.

The seven states

committed · funded · held · impaired · restructured · realised · written-off

impaired and written-off are the two a track record leaves out, and a log with no path to either will be read as selective rather than as fortunate.

The metrics, and the one rule about them

import { metrics } from '@flashyos/holding';

metrics(fragment).recovery;
// { everImpaired: 12, recovered: 7, ratio: 0.583, writtenOff: 5, medianLagDays: 4 }

recovery is one object rather than five fields on purpose. It may not be published without its denominator, the write-off count and the recording lag, because it is a number the publisher can move — unlike a countersignature ratio, which only somebody else can move — and a number you can move is worth publishing only beside the numbers that would expose you moving it.

API

| | | |---|---| | checkFragment(doc) | Every problem, not the first. Returns [code, subject, message][]. | | derive(fragment) | Current state per position, plus whether it was ever impaired. | | metrics(fragment) | The counts, the recovery object, and the median hold. | | project(fragment) | The public projection. Positions with at least one public transition, and only their public transitions. | | STATES TERMINAL TIERS FORBIDDEN | The vocabulary. |

Discovery

| Path | Read by | |---|---| | /.well-known/holding.json | Anyone fetching from a domain. | | holding.fragment.json | A merge that reads checkouts. |

A consumer must fetch over https, apply a timeout and a size cap, follow redirects only within the same registrable domain, and must not treat an unreachable publisher as one that published nothing.

The vendored copy

vendor-holding.mjs imports nothing but node: builtins and is copied whole into whichever repository adopts the format. src/vendor.test.ts runs it and the TypeScript checker over the same corpus and fails on any disagreement about a verdict — never by comparing constants, because two lists of one rule is how a checker ends up disagreeing with its own specification.

Apache-2.0.