ruact 0.0.4 → 0.0.6

data/docs/internal/decisions/server-functions-api.md

@@ -1777,3 +1777,405 @@ kwargs contract is enforced server-side. Append-only addendum to the
    `server-functions.ts` is 9.8). Request de-duplication for `useQuery` is 9.6
    (the hook fetches once per mount; a `useSyncExternalStore` refactor can layer
    dedup later). The v1 substrate is untouched (demolition is 9.9).
+
+### 2026-06-25 — Story 13.1 — Serialize-only invariant (FR97)
+
+Epic 13 ("Server-Function Contract & Safety") opens by turning a *happy accident
+of architecture* into a **defended invariant**. The 2026-06-15 technical research
+report established that ruact is **serialize-only**: its Ruby side *emits* React
+Flight (`text/x-component`) but has **no inbound Flight deserializer**, so it sits
+structurally **outside** the React2Shell / **CVE-2025-55182** class — a Flight-
+deserialization RCE (CVSS 10, Dec 2025) in which an attacker-supplied Flight
+payload is deserialized into live server objects. Append-only addendum; supersedes
+nothing.
+
+1. **The invariant (the rule).** ruact **may emit** Flight (`text/x-component`)
+   from the Ruby server, but must **never deserialize externally-supplied Flight
+   into live Ruby objects.** No inbound `*Deserializer`, no `parse_flight` /
+   `from_flight` / `deserialize_flight` / `decode_flight` reading a request body,
+   no Ruby call to a React Flight reader (`createFromNodeStream` /
+   `createFromReadableStream` / `createFromFetch`). Reads stay GET-with-primitives (FR88); writes stay
+   form/JSON over the host's own CSRF — neither path parses Flight inbound.
+
+2. **Out of scope — the client `createFromFlightPayload`.** The generated
+   client entry (`lib/generators/ruact/install/templates/application.jsx.tt`)
+   calls `createFromFlightPayload` to deserialize the server's **own trusted**
+   payload in the **browser**. That is normal RSC on the client — not the Ruby
+   server, not attacker-controlled inbound Flight — and is explicitly **outside**
+   this invariant. The tripwire scans Ruby source only and excludes the
+   generators' client-side templates.
+
+3. **Enforcement — a `Ruact::Doctor` tripwire, not a parser.** `check_serialize_only`
+   greps ruact's own `lib/**/*.rb` (default root `Ruact.gem_path/lib`, injectable
+   for specs) for a curated list of structural inbound-deserialization signals and
+   **fails** on any unannotated hit, naming `file:line` + this invariant. The raw
+   `text/x-component` token is deliberately **not** a signal — the gem legitimately
+   *emits* that media type (`controller.rb` / `server.rb`), so matching it would
+   false-fail the (invariant-holding) current tree. Today the check **passes
+   silently**. AST parsing was rejected as over-engineering for a tripwire whose
+   job is to *stay at zero* (consistent with the single-dependency / "make invalid
+   states unconstructible, simply" discipline). The signal literals are assembled
+   from fragments via `Array#join` and `doctor.rb` is excluded from its own scan
+   by exact file path — not basename, so a differently-located future namesake is
+   still scanned (mirrors the Story 5.1 F4 self-reference lesson).
+
+4. **Escape hatch — `# ruact:allow-flight-deserialization <reason>`.** A line
+   carrying that annotation is treated as guarded, so a deliberate, reviewed
+   deserializer is allowed without failing. This is what makes the check a
+   **guard** rather than a blanket ban.
+
+5. **Middleware warn (non-failing).** `check_flight_middleware` introduces a new
+   `:warn` doctor status (rendered `⚠`; a `:warn` does **not** flip the run to
+   failure — the pass computation moved from `status == :pass` to an allowlist,
+   `SUCCESS_STATUSES = %i[pass warn]`, so a `:warn` passes while any unexpected
+   status fails loudly rather than being silently treated as a pass).
+   It warns when a response-transforming middleware (`Rack::Deflater` + a small
+   curated list) is mounted, since recompressing/mutating a streamed
+   `text/x-component` body breaks the Flight wire contract / streaming
+   (React-on-Rails ops lesson). Rack middleware is app-global, not per-route, so
+   the warn cannot be scoped precisely to Flight routes — it points the operator
+   at the remedy (exclude `text/x-component` from compression).
+
+6. **Where it earns its keep.** The primary venue is the gem's own CI (the
+   `:story_13_1` spec runs the tripwire against a fixture tree). In a host app,
+   `rails ruact:doctor` scanning `Ruact.gem_path/lib` is defense-in-depth — a
+   released gem won't contain a deserializer, so it passes; its value there is
+   catching a hand-patched/vendored gem.
+
+7. **Scope guards.** This story ships ONLY the ADR addendum + the two doctor
+   checks + specs. No SignedGlobalID (13.2 / FR96), no error round-trip (13.3 /
+   FR98), no TS emission (13.4 / FR99), no component contract (13.5 / FR100), no
+   playground (13.6). The client-side React deserialization path is untouched.
+
+### 2026-06-26 — Story 13.2 — SignedGlobalID record references (FR96)
+
+The inbound-safety counterpart to the serialize-only invariant (13.1). The
+serialize-only guard keeps ruact from *deserializing* hostile Flight; this story
+keeps a controller from handing the client a *forgeable* record reference in the
+first place. Decisions:
+
+1. **The canonical record-reference primitive is a SignedGlobalID, opt-in via an
+   explicit helper.** `Ruact.signed_global_id(record, for:, expires_in:)` returns
+   `record.to_sgid(for:, expires_in:).to_s` (a plain `String` → the Flight
+   serializer carries it unchanged, no serializer branch). `Ruact.locate_signed(
+   token, for:)` wraps `GlobalID::Locator.locate_signed`. Chosen over (a)
+   hand-rolled `to_sgid` (no loud-omission guard, no symmetry) and (c)
+   auto-serializing every `ActiveRecord::Base` (magic; conflicts with the
+   `ruact_props` explicit-allowlist grain; can't carry a per-site `for:`). The
+   opt-in is "the developer reaches for the helper," surfaced in docs as the
+   canonical pattern.
+
+2. **Inbound resolution is explicit, never automatic.** The action/query calls
+   `Ruact.locate_signed` itself; the strict param allowlist (`query_dispatch.rb`)
+   is untouched — no auto-detect-and-resolve of token-shaped strings (a param may
+   legitimately be a string that merely looks like a token; auto-resolution would
+   couple the param layer to ActiveRecord and surprise developers).
+
+3. **Loud-omission invariant — never a silent insecure default.** Purpose and
+   expiry resolve call-arg → config default → **raise** `Ruact::Error`. Purpose
+   is always required (an unscoped token is never acceptable, so even an explicit
+   `for: nil` raises). Expiry distinguishes *omission* from a deliberate choice
+   via a private `UNSET` sentinel: pure omission with no configured default
+   raises; an explicit `expires_in: nil` is honored as a reviewed non-expiring
+   token. `expires_in:` must be an `ActiveSupport::Duration` (globalid calls
+   `#from_now`).
+
+4. **Tampered/expired/wrong-purpose → clean 400.** `locate_signed` returns `nil`
+   on any verification failure; the helper raises `Ruact::InvalidSignedGlobalIDError`,
+   mapped to **400** in `__ruact_status_for` (alongside `BadRequestError`). 400
+   over 404 because the token is an invalid client *credential*, not a missing
+   record — and verification fails before any DB lookup, so record existence is
+   never revealed either way. No `ActiveRecord::RecordNotFound` leak; the
+   rejection message never echoes the raw token.
+
+5. **Single-dependency discipline preserved.** `globalid` ships with every Rails
+   app but is not a gemspec dependency (only `nokogiri` is). It is **lazily
+   required** inside the helpers on first call (mirroring the class-name-string
+   matching in `ErrorRendering` that avoids requiring ActiveRecord at load), so
+   the gem stays loadable in pure-Ruby contexts and the gemspec is unchanged.
+
+6. **Scope guards.** This story ships ONLY the two helpers + the error class +
+   400 mapping + two config keys + security docs + specs. No error round-trip
+   (13.3 / FR98), no TS emission (13.4 / FR99), no component contract (13.5 /
+   FR100), no playground (13.6). The Epic 10 scaffold generator does not exist
+   yet — the docs worked-example is the canonical pattern it will later emit.
+
+#### 2026-06-26 — Story 13.2 review patch (dev⇄Codex)
+
+Three findings, all resolved before merge:
+- **(Patch)** `InvalidSignedGlobalIDError`'s YARD comment was inserted between
+  `UploadTooLargeError`'s doc block and its class, detaching the upload docs →
+  moved the new error + comment to sit right after `BadRequestError`.
+- **(Patch)** the production-mode no-leak spec asserted `not_to have_key("backtrace")`,
+  but the dev-only payload keys are `app_frames` / `gem_frames` / `suggestion` →
+  the spec now asserts the response is exactly the four baseline keys.
+- **(Decision, Luiz)** a **valid** token whose record was since **deleted** is
+  out of AC2's three rejection cases (tampered/expired/wrong-purpose, which never
+  reach the finder). **Resolved: do NOT normalize.** The finder's
+  `ActiveRecord::RecordNotFound` propagates as the host's ordinary not-found
+  concern (identical to a raw `Model.find`); the primitive owns only signature/
+  expiry/purpose verification. Documented on `InvalidSignedGlobalIDError` and
+  pinned by a spec.
+- YARD `{Ruact.signed_global_id}` / `{Ruact.locate_signed}` cross-references are
+  unresolvable (the methods are mixed onto `Ruact`'s singleton via `extend`), so
+  they are written as plain code spans, not doc links.
+
+#### 2026-06-26 — Story 13.2 review patch R2 (dev⇄Codex)
+
+One new finding (all three layers, same root): `expires_in: false` — and a
+configured default of `false` — silently minted a **non-expiring** token, because
+globalid treats a falsy `expires_in` as "no expiry". That was a second silent
+path around the "only an explicit `nil` is the reviewed non-expiring choice"
+contract. **Fixed:** `__ruact_resolve_expiry` now type-checks the resolved value
+— only `nil` or an `ActiveSupport::Duration` (anything responding to `#from_now`,
+what globalid actually calls) is allowed; `false`, a bare Integer, or any other
+type raises `Ruact::Error` loudly (closing both the call-arg and the configured-
+default path). Bonus: a bare Integer now gets a clear message instead of
+globalid's cryptic `NoMethodError: from_now`.
+
+### 2026-06-26 — Story 13.3 — Inertia-style validation `errors` round-trip (FR98)
+
+**Context.** Stories 8.4 / 9.1 handle the **exception** path: a `save!` /
+`create!` that raises `ActiveRecord::RecordInvalid` bubbles past the host's
+`rescue_from` into the structured **error payload** (`_ruact_server_action_error:
+true`, mapped to **422**, with a dev-only flat `full_messages` **array** under
+`validation_errors`) — for the dev overlay. FR98 is the complementary
+**non-exception happy-failure** path: the idiomatic `if record.save … else …`
+where `save` returns `false` and the action does NOT raise. That path needs a
+field-level `errors` **prop** (not an error payload) so a form re-renders with
+messages and a normal 200 / redirect — exactly how a Rails dev expects
+`record.invalid?` to behave. **13.3 EXTENDS, does not replace, the 8.4/9.1
+chain**; `error_payload.rb`'s dev-only `validation_errors` array is left
+untouched (different shape, different purpose).
+
+**Decision — design (B), explicit opt-in helper.** The contract escalation in
+the story (auto-inject a reserved `errors` prop into EVERY response — variant
+(A) — vs. an explicit opt-in helper — variant (B)) was resolved by Luiz in
+favour of **(B)**. Rationale: (A) would reserve the prop name `errors` globally
+AND change Story 9.2's Bucket-2 `204 No Content` empty contract (a genuinely
+empty response would become `{"errors": {}}`); that is magic, in tension with
+the explicit-allowlist grain that 13.1/13.2 just hardened. (B) preserves the
+grain and the 9.2 contract.
+
+**(a) Canonical shape — a pure normalizer.**
+`Ruact::ServerFunctions::ValidationErrors.normalize(source)` is a pure function
+(no Rails / `Ruact.config` / request reads — same caller/builder split as
+`ErrorPayload` / `BucketTwoPayload`) producing `Hash{String=>Array<String>}`:
+attribute names as strings (a `base`-level error keys under `"base"`), values
+arrays of human-readable **full messages** (`ActiveModel::Error#full_message`,
+e.g. `"Title can't be blank"`). It accepts an ActiveModel-ish record (responds
+to `#errors`), a raw `ActiveModel::Errors`, or a pre-shaped Hash, and is
+idempotent on already-canonical input; `nil` / a valid record → `{}`. Full
+messages (not partial `errors.messages`) are the default — self-describing, and
+faithful to the AC. Note this diverges from inertia-rails' single-string-per-
+attribute: FR98 mandates `string[]` because one attribute can carry multiple
+errors.
+
+**(b) Opt-in collector helper.** `ruact_errors` is a single dual-purpose
+controller helper on the shared `Ruact::ValidationErrorsCollector` concern
+(included by both `Ruact::Server` and `Ruact::Controller`). `ruact_errors(@post)`
+normalizes + merges into a per-request collector (the private ivar
+`@__ruact_errors`, NOT a `view_assigns` ivar) and returns the normalized hash;
+the no-arg `ruact_errors` reads the always-present collector (`{}` default), for
+binding to a form component (`<PostForm errors={ruact_errors} />`, exposed to
+the view via `helper_method`). Because the shape derives from `record.errors`
+(empty on a valid record), one `ruact_errors(@post)` call after the save yields
+`{}` on success and the populated map on failure — the "always present, same
+code path" invariant, **per-action and explicit**, with no global prop.
+
+**(c) Bucket-2 (imperative `await`).** When `__ruact_function_call?` and the
+collector was **touched** this request, `Ruact::Server#default_render` injects
+the collector under the reserved JSON key `"errors"` alongside the serialized
+ivars (even on an otherwise-empty assigns set, so an opted-in success surfaces
+`{"errors": {}}` and the client reads `result.errors` uniformly). The two
+collector internals and a stray dev ivar literally named `@errors` are dropped
+from the serialized assigns (`RESERVED_ASSIGN_KEYS` — Rails' `view_assigns` only
+filters a fixed set of `@_` ivars, not every `@__` one); the collector is the
+source of truth for the key. An **untouched** collector changes nothing — the
+9.2 `204 No Content` empty-Bucket-2 contract is preserved. No client-runtime
+change: the `errors` key rides `parseResponse` verbatim.
+
+**(d) Bucket-1 redirect-back (native form / navigation).** The Inertia "redirect
+back with errors" pattern: on a Flight `redirect_to`
+(`Ruact::Controller#redirect_to`) where the collector was touched, the canonical
+errors are stashed in `flash[:ruact_errors]` (single-use, session-backed — the
+exact Inertia semantics). The re-rendered page (`ruact_render`) reads the flash
+back into the collector before the view evaluates, so `ruact_errors` returns the
+surviving errors as a prop on the re-render. Guarded on `respond_to?(:flash)`:
+a session-less API-only host degrades to the Bucket-2 body path rather than
+crashing. Bucket-2 does NOT redirect-to-convey-failure — errors ride the body.
+
+**Append-only invariant preserved.** The Story 8.0 accessor lock is untouched
+(`import { createPost } from "@/.ruact/server-functions"` unchanged); FR98 adds
+a Ruby-side collector + a reserved response key, no codegen / runtime change.
+The raised-`RecordInvalid` → 422 path (8.4) is unchanged and still covered by
+`server_rescue_request_spec.rb`.
+
+### 2026-06-26 — Story 13.4 — TS type emission for query `params` (FR99)
+
+FR99 closes the **parameter/accessor `any` gap**: before this story a query that
+declares keyword arguments emitted `(params: Record<string, unknown>) =>
+Promise<unknown>` — the client got no named keys, no autocomplete, no
+missing-required error, no unknown-key error. The codegen now narrows that
+`params` object to the query method's **actual declared keyword arguments**.
+Append-only addendum; no locked accessor shape changes (the import surface —
+`import { searchUsers, useQuery } from "@/.ruact/server-functions"` — is
+untouched; only the inline TS type annotation on the emitted `export const`
+gets narrower).
+
+**The reflection-honesty decision (the one real contract call) — RESOLVED (A).**
+Ruby is dynamically typed; `Method#parameters` returns **names + required/optional
+only** (`[[:keyreq, :term], [:key, :limit]]`) — never types, never default
+values. So the epic's illustrative `{ q: string; limit?: number }` (where
+`number` would come from `limit: 10`) is **not honestly reachable by pure
+reflection**. Decision (locked by Luiz): each param's **value type is the FR88
+wire-serializable union `string | number | boolean | null`** — the exact
+query-string contract the kwargs sanitizer (`query_dispatch.rb`) already enforces
+— while **keys and optionality are EXACT** (`:keyreq` → required prop, `:key` →
+optional prop). This kills the `Record<string, unknown>`/`any` gap truthfully:
+named keys (autocomplete), exact required-ness (**missing-required is a compile
+error**), and excess-property checking (**unknown-key is a compile error**).
+Rejected alternatives: (B) parsing default-value literals to infer scalar types —
+fragile, Ruby-version-dependent, a byte-stability hazard, and gives `term:` (no
+default) no type anyway; (C) an explicit param-type DSL (`param :limit, :integer`)
+for true scalar precision — a new feature surface, deferred to a future story.
+Per-param scalar narrowing is therefore explicitly **out of scope** here.
+
+**Action scope boundary — actions stay byte-identical.** Actions are Rails
+controller methods that read `params` dynamically; there is **no reflectable
+declared-input source** (the action entry hash carries no kwargs), and the action
+signature is already a sensible `FormData | Record<string, unknown>` intersection
+(not bare `any`). Inventing an action-input declaration DSL is a new feature
+surface, out of scope. Action accessors — and therefore every action-only and
+empty `server-functions.ts` module — are emitted **byte-for-byte unchanged**
+(regression-pinned in the parity suite). Return types stay `Promise<unknown>`
+(per-function return precision is Phase 3; `useQuery<T>` remains the return-typing
+lever).
+
+**`**keyrest` fails open.** A query declaring `**opts` keeps an open
+`Record<string, unknown>` (intersected with any named keys:
+`{ scope: <union> } & Record<string, unknown>`) so a legitimate dynamic key is
+never narrowed away. A `**keyrest`-only query is just `Record<string, unknown>` —
+byte-identical to its pre-13.4 `accepts_params: true` output.
+
+**Pipeline + dual-codegen byte parity reaffirmed.** Per-kwarg metadata is derived
+in `QuerySource.build_entry` (`params`: an ordered `[{ "name", "required" }]`
+array + a `params_rest` Boolean, alongside the retained `accepts_params` Boolean,
+now derived as "named keys present OR keyrest"), carried verbatim through the
+`Snapshot` JSON (string keys, declaration order → byte-stable), and consumed
+**byte-identically** by BOTH the Ruby `Codegen::V2.render_query_export` and the JS
+`renderQueryExportV2`. The cross-implementation parity test
+(`server-functions-codegen.test.mjs`) is extended with a typed-query fixture
+(required + optional + keyrest + keyrest-only) asserting `jsOutput ===
+rubyOutput`. The new `params` metadata is a **trust boundary** (it becomes TS
+object keys): both renderers reject a malformed/corrupted snapshot (non-Array
+`params`, a non-object element, an empty/multi-line param name, a non-Boolean
+`required`) rather than emit broken — or injected — TS, and any param name that
+is not a valid bare JS identifier is JSON-quoted. The AC6 proof is a `tsc
+--noEmit` type-level test fixture in `vendor/javascript/vite-plugin-ruact/`
+(`type-tests/`, `typescript` added as a build-only devDependency) asserting that
+missing-required / unknown-key / wrong-typed / wrong-arity all fail to compile and
+a clean call type-checks — wired into a new `js` CI job. The runtime `_makeQuery`
+declaration needed **no change**: the emitted typed-`params` `export const`
+assigns to `_makeQuery`'s declared return without a cast (proven by a second
+type-test fixture).
+
+### 2026-06-26 — Story 13.5 — Compile-time component contract, HEEx-style `attr`/`slot` (FR100)
+
+FR100 closes the **component-boundary contract gap** — the consumer-side mirror
+of `ruact_props`. `ruact_props` validates the **producer** at class-load (a
+serializable model only exposes real methods, `serializable.rb`); until now the
+**consumer** — a `<Component prop={...} />` call site in an ERB view — was
+unchecked, so a missing required prop, a typo'd prop name (`postID` vs `postId`),
+or a slot misuse produced a **silent `undefined` in the browser** (the worst
+failure: discovered at runtime in production). 13.5 makes the call site a checked
+contract that fails **at preprocess time**, naming the component, file:line, the
+offending prop, and a "did you mean?" suggestion — before the page renders.
+
+**Contract source = opt-in `.tsx` export → manifest `contract` field (design A,
+locked by Luiz).** A component opts in by exporting `__ruactContract` from its own
+module (HEEx spirit — the declaration lives next to the component, in the
+component's own language):
+
+```ts
+export const __ruactContract = {
+  props: { title: "required", subtitle: "optional" },
+  slots: { header: "optional" },   // optional; { name: "required"|"optional" } or ["name", ...]
+  passthrough: false,              // optional; true allows undeclared props
+};
+```
+
+The Vite plugin's existing component scanner (`buildManifest`) — which already
+opens every component file for `"use client"` + export names — extracts this
+**names-only** (a brace-balanced object scan + targeted regexes; **NOT** a TS-AST
+pass, **NOT** `eval`) into an optional `contract` field on the manifest entry.
+A component without the export emits **no** `contract` field (byte-additive;
+every existing manifest + reader is unaffected). A malformed/partial declaration
+is **warned + skipped** in the plugin, so the Ruby side sees "no contract" and
+fails open. The brace-balancer that bounds the object literal is string- and
+comment-aware (a `{` inside a comment or string never throws off the balance).
+A single `__ruactContract` describes the file's **one** component — a file that
+exports more than one PascalCase component has the contract **warned + skipped**
+(it cannot be attributed), reaffirming the one-component-per-file convention;
+per-export contract syntax is deferred. Rejected alternatives: **(B)** a Ruby-side DSL and **(C)** a JSON
+sidecar both invent a parallel registry that drifts from the `.tsx` (the source
+of truth); **(D)** a full TS-AST `Props` parse is heavy, version-fragile, and
+over-delivers (preprocess-time validation needs names + required + slots, not
+value types — and component prop value typing is a separate, later concern; the
+server-boundary value-typing win already landed in 13.4 / FR99).
+
+**Check location = Ruby preprocess-time (forced, not a choice).** ERB
+`<Component .../>` tags are transformed by the **Ruby** ERB preprocessor
+(`erb_preprocessor.rb`), which already detects PascalCase tags, parses prop
+**names**, and computes each call site's line. A TypeScript/codegen-time check
+**cannot see ERB call sites at all** — they live in `.html.erb`, not `.tsx`. So
+the validator (`Ruact::ComponentContract`) is necessarily Ruby-side, hooked into
+the existing `COMPONENT_TAG_RE` transform loop. The only missing input was the
+template **file path**, now threaded through `ErbPreprocessorHook#call` as
+`template.identifier` (and `ErbPreprocessor.transform(source, identifier:,
+registry:)` — the contract registry is an **injectable seam** defaulting to the
+process-loaded, frozen `Ruact.manifest`, stubbable in specs per the Story 7.1
+explicit-context grain; no `Thread.current`, no per-call disk read).
+
+**Granularity = NAME-level only (required / unknown / slot).** Prop **values** are
+arbitrary render-time Ruby expressions the preprocessor never evaluates
+(`postId={@post.id}` → it emits `"postId" => @post.id`), so a preprocess-time
+check can validate **names + presence + slots** — *not* value types. This is the
+same reflection-honesty discipline 13.4 used: deliver exactly what the static
+phase can truthfully see. The three checks map precisely to the epic's three
+failure cases: **missing required** prop/slot, **unknown** prop name (closed by
+default; `passthrough: true` reopens it), and **slot misuse**.
+
+**Slots = minimal / name-level, deeper semantics deferred.** Children/slot passing
+is thin today (only `<Suspense>` is paired in the preprocessor; generic
+`<Component>…</Component>` children are not yet first-class). A slot is therefore
+expressed at the ERB call site as a **named prop attribute** (render-prop style:
+`<Card header={...} />`); the validator treats declared slot names as valid
+attributes and enforces **required** slots by attribute presence. A contract that
+declares no slots makes slot checking a **no-op**. A typed slot runtime / slot
+rendering / children-based slot capture is explicitly **deferred**.
+
+**Opt-in / fail-open / byte-identical (the load-bearing regression).** A
+contract-less component gets **zero** validation and **byte-identical** emitted
+output (`<%= __ruact_component__("Name", { … }) %>`), and the no-component-tag
+fast path reads no registry — both regression-pinned. Validation runs **only**
+inside the `COMPONENT_TAG_RE` block, never on the fast path. When the manifest is
+absent (fresh app, pre-build) or has no contract for a component, validation is
+skipped. This follows the gem's whole grain — explicit allowlisting, never magic
+(`ruact_props`, the SGID helper, the strict query allowlist are all opt-in).
+
+**Error surface.** The validator raises `Ruact::ComponentContractError`, a
+**subclass of `Ruact::PreprocessorError`** (so it flows through the same dev error
+overlay, NFR30 lineage) — the distinct subclass lets the preprocessor re-raise it
+**as-is** (its message already carries component + file:line + offending prop +
+suggestion) instead of re-wrapping it with the generic "at line N: snippet" tail
+the preprocessor appends to malformed-tag errors. The "did you mean?" suggestion
+reuses the **Damerau-Levenshtein** closest-match (Story 7.4), factored out of
+`ClientManifest` into a shared `Ruact::StringDistance` module so the prop-typo
+hint and the unknown-component hint share one algorithm.
+
+**Scope boundary (this story does NOT do).** Prop value-type checking; a full
+TS-AST `Props` parse; a Ruby DSL / JSON sidecar; a new slot runtime; moving
+validation to render time. The **Epic 10 scaffold** consuming contracts and the
+**playground build-fails CI proof** are **Story 13.6** (`epics-phase-2.md`).
+ADR addendum (2026-06-26).