feat(fp): WP-05 — parse-don't-validate closure + MDX

Close the three remaining unvalidated `as <DomainType>` casts at the wire
boundary (intake-policy, big-register aantekening type, brief passage scope),
each replaced by a Result-returning parser with a rejection-case spec, plus
the Foundations/Parse, don't validate curriculum page.

src/app/brief/infrastructure/brief.adapter.spec.ts

@@ -141,6 +141,14 @@ describe('brief.adapter parse boundary', () => {
     ]);
   });
 
+  it('rejects a library passage with an unknown scope', () => {
+    const r = parseBriefView({
+      ...view,
+      availablePassages: [{ ...view.availablePassages![0], scope: 'bogus' as never }],
+    });
+    expect(r.ok).toBe(false);
+  });
+
   it('rejects a passage block missing provenance', () => {
     const r = parseBrief({
       ...view.brief,

src/app/brief/infrastructure/brief.adapter.ts

@@ -21,7 +21,6 @@ import {
   LetterBlock,
   LetterSection,
   LibraryPassage,
-  PassageScope,
 } from '@brief/domain/brief';
 import { PlaceholderDef } from '@brief/domain/placeholders';
 import { Mark, Paragraph, RichTextBlock, RichTextNode } from '@shared/kernel/rich-text';
@@ -228,8 +227,9 @@ export function parseStatus(dto: BriefStatusDto | undefined): Result<string, Bri
 }
 
 function parsePassage(dto: LibraryPassageDto): Result<string, LibraryPassage> {
-  if (typeof dto.passageId !== 'string' || (dto.scope !== 'global' && dto.scope !== 'beroep'))
-    return err('passage: bad shape');
+  if (typeof dto.passageId !== 'string') return err('passage: bad shape');
+  if (dto.scope !== 'global' && dto.scope !== 'beroep')
+    return err(`passage: unknown scope ${dto.scope}`);
   if (
     typeof dto.sectionKey !== 'string' ||
     typeof dto.label !== 'string' ||
@@ -240,7 +240,7 @@ function parsePassage(dto: LibraryPassageDto): Result<string, LibraryPassage> {
   if (!content.ok) return content;
   return ok({
     passageId: dto.passageId,
-    scope: dto.scope as PassageScope,
+    scope: dto.scope,
     sectionKey: dto.sectionKey,
     label: dto.label,
     content: content.value,

src/app/herregistratie/domain/intake.machine.ts

@@ -42,6 +42,11 @@ export interface ValidIntake {
     fallback; the server value wins. */
 export const SCHOLING_THRESHOLD_DEFAULT = 1000;
 
+/** The server-owned intake policy (domain-side, parsed from the wire at the boundary). */
+export interface IntakePolicy {
+  readonly scholingThreshold: number;
+}
+
 /** True when NL-hours are low enough that the scholing question must be answered.
     The threshold is passed in (server-owned), not hardcoded. */
 export function lageUren(a: Answers, scholingThreshold = SCHOLING_THRESHOLD_DEFAULT): boolean {

src/app/herregistratie/infrastructure/intake-policy.adapter.spec.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { parseIntakePolicy } from './intake-policy.adapter';
+
+describe('intake-policy.adapter parse boundary', () => {
+  it('parses a well-formed policy', () => {
+    const r = parseIntakePolicy({ scholingThreshold: 800 });
+    expect(r).toEqual({ ok: true, value: { scholingThreshold: 800 } });
+  });
+
+  it('rejects a missing or non-numeric threshold', () => {
+    expect(parseIntakePolicy({}).ok).toBe(false);
+    expect(parseIntakePolicy({ scholingThreshold: '800' }).ok).toBe(false);
+    expect(parseIntakePolicy(null).ok).toBe(false);
+  });
+});

src/app/herregistratie/infrastructure/intake-policy.adapter.ts

@@ -1,4 +1,6 @@
 import { Injectable, inject, resource } from '@angular/core';
+import { Result, ok, err } from '@shared/kernel/fp';
+import { IntakePolicy } from '@herregistratie/domain/intake.machine';
 import { ApiClient } from '@shared/infrastructure/api-client';
 
 /**
@@ -11,6 +13,21 @@ export class IntakePolicyAdapter {
   private client = inject(ApiClient);
 
   policyResource() {
-    return resource({ loader: () => this.client.policy() });
+    return resource({
+      loader: async () => {
+        const parsed = parseIntakePolicy(await this.client.policy());
+        if (!parsed.ok) throw new Error(parsed.error);
+        return parsed.value;
+      },
+    });
   }
 }
+
+/** Trust-boundary parse: an unrecognized/missing threshold is an explicit Failure. */
+export function parseIntakePolicy(json: unknown): Result<string, IntakePolicy> {
+  if (typeof json !== 'object' || json === null) return err('intake-policy: not an object');
+  const dto = json as { scholingThreshold?: unknown };
+  if (typeof dto.scholingThreshold !== 'number')
+    return err('intake-policy: missing scholingThreshold');
+  return ok({ scholingThreshold: dto.scholingThreshold });
+}

src/app/registratie/infrastructure/big-register.adapter.spec.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { parseAantekening } from './big-register.adapter';
+
+describe('big-register.adapter parse boundary', () => {
+  it('parses known aantekening types', () => {
+    expect(parseAantekening({ type: 'Specialisme', omschrijving: 'x', datum: '2026-01-01' })).toEqual({
+      ok: true,
+      value: { type: 'Specialisme', omschrijving: 'x', datum: '2026-01-01' },
+    });
+    expect(parseAantekening({ type: 'Aantekening' })).toEqual({
+      ok: true,
+      value: { type: 'Aantekening', omschrijving: '', datum: '' },
+    });
+  });
+
+  it('rejects an unknown type', () => {
+    expect(parseAantekening({ type: 'Bogus' }).ok).toBe(false);
+    expect(parseAantekening({}).ok).toBe(false);
+  });
+});

src/app/registratie/infrastructure/big-register.adapter.ts

@@ -1,4 +1,5 @@
 import { Injectable, inject, resource } from '@angular/core';
+import { Result, ok, err } from '@shared/kernel/fp';
 import { Aantekening, AantekeningType } from '../domain/registration';
 import { ApiClient, AantekeningDto } from '@shared/infrastructure/api-client';
 
@@ -16,15 +17,30 @@ export class BigRegisterAdapter {
   private client = inject(ApiClient);
 
   aantekeningenResource() {
-    return resource({ loader: () => this.client.notes().then((ns) => ns.map(toAantekening)) });
+    return resource({
+      loader: () =>
+        this.client.notes().then((ns) => {
+          const out: Aantekening[] = [];
+          for (const n of ns) {
+            const parsed = parseAantekening(n);
+            if (!parsed.ok) throw new Error(parsed.error);
+            out.push(parsed.value);
+          }
+          return out;
+        }),
+    });
   }
 }
 
-/** Map the wire DTO (all fields optional) onto our domain type. */
-function toAantekening(n: AantekeningDto): Aantekening {
-  return {
+const AANTEKENING_TYPES: readonly AantekeningType[] = ['Specialisme', 'Aantekening'];
+
+/** Trust-boundary parse: an unrecognized type is an explicit Failure, never a silent cast. */
+export function parseAantekening(n: AantekeningDto): Result<string, Aantekening> {
+  if (!n.type || !AANTEKENING_TYPES.includes(n.type as AantekeningType))
+    return err(`aantekening: unknown type ${n.type}`);
+  return ok({
     type: n.type as AantekeningType,
     omschrijving: n.omschrijving ?? '',
     datum: n.datum ?? '',
-  };
+  });
 }

src/docs/parse-dont-validate.mdx

@@ -0,0 +1,111 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Foundations/Parse, don't validate" />
+
+# Parse, don't validate
+
+The wire is untrusted. A `boolean`/`string` field coming back from `fetch` is typed `unknown`
+until something checks it — casting it away with `as` doesn't check anything, it just tells the
+compiler to stop complaining. This repo's rule: every response crosses the FE⇄BE seam through a
+hand-written `parse*` function that returns a `Result<string, T>` (`src/app/shared/kernel/fp.ts`).
+Once you hold the parsed value, you never re-check it — the type _is_ the proof.
+
+## Two places this shows up
+
+**Value objects** (`src/app/registratie/domain/value-objects/`) parse a single user-entered
+field — `Postcode`, `Uren`, `BigNummer` — from a raw string into a branded type.
+
+**Boundary parsers** (`*.adapter.ts` in every `infrastructure/`) parse a whole DTO — or one
+enum-ish field inside it — from the generated `ApiClient`'s response into the domain shape the
+rest of the app trusts.
+
+```ts
+parsePostcode(raw)               // Result<string, Postcode>
+  |> mapErr(toLocalizedMessage)  // swap raw msg → UI copy
+  |> map(toDomain)               // only runs on success
+```
+
+## The failure mode this closes: the silent `as` cast
+
+An `as SomeUnion` cast on a wire value compiles even when the value doesn't match — the tag
+just gets forwarded as-is, and something far away breaks on an "impossible" case. A validated
+parse turns that into an explicit `Failure` at the boundary, right where the untrusted data
+enters.
+
+### Before/after: `big-register.adapter.ts`
+
+```ts
+// before — the wire's `type` string is trusted outright
+function toAantekening(n: AantekeningDto): Aantekening {
+  return { type: n.type as AantekeningType, omschrijving: n.omschrijving ?? '', datum: n.datum ?? '' };
+}
+```
+
+```ts
+// after — an unrecognized type is a Result you can spec, not a silently-wrong tag
+const AANTEKENING_TYPES: readonly AantekeningType[] = ['Specialisme', 'Aantekening'];
+
+export function parseAantekening(n: AantekeningDto): Result<string, Aantekening> {
+  if (!n.type || !AANTEKENING_TYPES.includes(n.type as AantekeningType))
+    return err(`aantekening: unknown type ${n.type}`);
+  return ok({ type: n.type as AantekeningType, omschrijving: n.omschrijving ?? '', datum: n.datum ?? '' });
+}
+```
+
+The resource loader throws on `Failure`, which Angular's `resource()` turns into its error
+state — the same `Failure` a `RemoteData` consumer already renders, no new plumbing.
+
+### Before/after: `brief.adapter.ts`
+
+```ts
+// before — `dto.scope` is checked, then re-cast anyway
+if (typeof dto.passageId !== 'string' || (dto.scope !== 'global' && dto.scope !== 'beroep'))
+  return err('passage: bad shape');
+// … scope: dto.scope as PassageScope
+```
+
+```ts
+// after — split the guard so TS narrows `scope` on its own; no cast needed
+if (dto.scope !== 'global' && dto.scope !== 'beroep')
+  return err(`passage: unknown scope ${dto.scope}`);
+// … scope: dto.scope   // already narrowed to PassageScope
+```
+
+Splitting a compound `if` into two single-condition guards is often enough to make the cast
+disappear entirely — the compiler was already able to prove the narrowing, the `||` was just
+hiding it.
+
+### Before/after: `intake-policy.adapter.ts`
+
+```ts
+// before — the resource exposes the raw DTO; consumers reach into it with `?.`
+policyResource() {
+  return resource({ loader: () => this.client.policy() });
+}
+```
+
+```ts
+// after — a domain-side type + a validated parse; the resource never surfaces raw wire shape
+export interface IntakePolicy { readonly scholingThreshold: number }
+
+export function parseIntakePolicy(json: unknown): Result<string, IntakePolicy> {
+  if (typeof json !== 'object' || json === null) return err('intake-policy: not an object');
+  const dto = json as { scholingThreshold?: unknown };
+  if (typeof dto.scholingThreshold !== 'number')
+    return err('intake-policy: missing scholingThreshold');
+  return ok({ scholingThreshold: dto.scholingThreshold });
+}
+```
+
+## The sanctioned exception
+
+Narrowing `unknown` to `Partial<Dto>` so you can *start* checking fields is fine — that's not a
+trust decision, it's just giving the compiler a shape to probe (`const dto = json as
+Partial<DashboardViewDto>`, see `dashboard-view.adapter.ts`). What's never fine is casting a
+field to its final domain type without having checked it first.
+
+## Spec every parser like a decision table
+
+Each parser gets a spec covering: a valid shape, a missing required field, and — for
+tagged/enum-ish values — an unknown tag. See `big-register.adapter.spec.ts`,
+`intake-policy.adapter.spec.ts`, and the scope-rejection case in `brief.adapter.spec.ts`.