feat: add checked enum narrowing, and close an inert guarantee in ParseResult

[ernysans]

Follow-up to #10. Two commits, deliberately separable — the first is a narrowing, the second is purely additive. Drop either independently.

---

Commit 2 (additive): matchMember / requireMember

The requested affordance. Ledger.service is a validated string because the vocabulary is owned by the metering service, which is the right layering — but on its own it only moves the cast: a caller still writes parsed.service as Service, which checks nothing. Telling every call site to narrow instead is a rule, not a mechanism, and relying on discipline at every call site is what failed the first time.

const result = matchMember(Service, record.service);
if (!result.matched) return refuse(result.value);
doWork(result.member);            // Service, checked

requireMember(members, value, label) is the throwing counterpart, mirroring parseOrThrow / parseResult.

Membership policy, stated explicitly

A miss is anything that is not exactly one of the declared values: a non-string, null, undefined, the empty string, and any difference in casing or surrounding whitespace. Nothing is normalised, because normalising means guessing which near-miss the writer intended.

Absence and invalidity are both misses but stay distinguishable via MemberMiss.value — undefined for an absent field, null for an explicit null, the offending string otherwise. Which of those warrants an error is the caller's policy, so this function does not decide it for them.

---

Commit 1 (narrowing): an inert guarantee in #10

While measuring the return shape for memberOf I found that a guarantee I documented in #10 does not fire. ParseFailure declared data?: undefined and its docs claimed a caller "cannot reach a typed document without first narrowing on success". Measured on merged main:

const result = Ledger.safeParse({service: 's', scope: 'sc', amount: 'abc'});
const amount: number = result.data.amount;   // compiles clean; TypeError at runtime

Under strictNullChecks: false undefined is assignable to everything, so the sibling marker collapses. I checked the consumer: it is also strictNullChecks: false, so this was inert exactly where it was documented to hold — false confidence in a control that never fires, which is worse than a documented gap.

Omitting the property from the failure branch entirely gives Property 'data' does not exist on type 'ParseFailure' regardless of the flag.

Kept asymmetric on purpose. Reading .issues off a success yields undefined where none exist — wrong but benign, and convenient when logging an un-narrowed result. Reading .data off a failure yields an absent value typed as a valid document. Only the dangerous direction is closed; the 40 benign call sites are untouched, and only 7 needed narrowing.

This narrows a published type, so it is not additive and I have kept it separate. The window is now: #10 landed minutes ago and the functions pin is still on df3559a5…, so nothing compiles against it yet.

---

⚠️ I deviated from the requested API — flagging it, per the lesson from #10

You asked for memberOf(...): Service | undefined. That form does not satisfy your own requirement 2 in this repo. Measured, all three forms, same file, both configurations:

return shape	this repo (strictNullChecks: false)	a strict consumer
T | undefined	compiles ❌	compile error ✓
discriminated, member?: undefined	compiles ❌	compile error ✓
discriminated, property omitted	compile error ✓	compile error ✓

Since the consumer is also non-strict, only the third form makes the mistake unrepresentable today rather than after a flag flip. That is why this is MemberResult<T> rather than T | undefined. Row 2 is the trap — it looks discriminated but isn't, and it is precisely the mistake commit 1 fixes.

---

Evidence — 7/7 detected, across both gates

mutation	npm test	npm run typecheck
matchMember accept anything	RED (8)	RED
matchMember normalise casing	RED (1)	green
matchMember accept non-strings	RED (3)	green
requireMember return instead of throw	RED (16)	RED
MemberMiss drop the carried value	RED (1)	green
ParseFailure reintroduce the collapsing marker	green	RED
MemberMiss reintroduce the collapsing marker	green	RED

The last two rows are the compile-time half you asked for. Reintroducing either marker leaves the suite fully green and turns typecheck red — so the guarantee has a real regression guard, and npm test provably cannot see it.

That guard is a committed @ts-expect-error with a description, not a comment: it asserts the line under it is an error, so if the error stops occurring the directive becomes unused and typecheck fails. It runs under the existing npm run typecheck gate, which already includes test/ — no new tooling and no CI change.

Gates

Gate	Result
npm run build	exit 0
npm test	919 passed, 18 files (was 903)
npm run typecheck	exit 0
npm run lint	exit 0
git status --porcelain -uall -- lib/	empty after rebuild
private-marker guard	exit 0
trailers / authorship in range	0 / Erny Sans only

lib/ regenerated and committed in each commit, so either can be reverted without leaving stale output.

The barrel inventory test from #10 caught the two new exports and had to be updated — that control working as intended.