M1.1: Rust guest SDK core

[lann]

The minimum SDK the webcrypto guest migration needs (macro sugar can lag):

• suite scaffolding for the suite world: case registration, name normalization to the grammar (+ post-mangling duplicate check, hard error), lazy case materialization
• verdict ergonomics: Result<(), Outcome>-native assertions, diagnostics via context
• feature-mark declaration (single declaration → static metadata emission (M1.2) + paired decline-case generation)
• sync-vs-async binding choice per suite

Driven by the webcrypto guest's actual needs (suites! tables, probes, decline assertions); the differential harness (M1.4) is the acceptance test.

[lann]

Macro-sugar target shape, validated by webcrypto's 6da53b3/1ffeed0: a single-table suites! registry where one row generates materialization (table order = census order), dispatch, and decline/skip posture — category errors unrepresentable. Their refinements: trait-with-default-method beats macro row-options for per-case metadata (features() -> &'static [&str] defaulting empty); probes-only suites via a dedicated export macro that fails loudly when a feature-tagged probe lacks decline glue; layered stream/verdict helpers (split outcomes at base for contract probes, _op/_ok folds for the common ritual). Note our census-order divergence: link_section record order is linker-determined, so our lockfile canonicalizes to sorted order rather than source order — set-equality semantics, slightly worse diff locality, acceptable.

[lann]

Scope addition, replacing the consumer WIT-vendoring plan: the SDK's macro sugar should be a proc macro that embeds the contract WIT (include_str! at proc-macro build time → generate!({ inline: ... }) + glue). Consumers then never vendor tests.wit — the contract version is locked to the SDK crate by construction, eliminating the drift-check ceremony entirely.

Domain imports (e.g. webcrypto's SUT interfaces) come from a separate, plain user-side generate! over the consumer's own WIT: the packages are disjoint, each emits its own component-type:* section, and wasm-component-ld merges them into the union world.

Verification spike (do first): confirm the multi-generate! section merge produces a linking, running component — e.g. split the sample suite's bindings in two. Fallback if merge misbehaves: the proc macro accepts the user's wit dir and injects the contract package into the Resolve programmatically (wit-parser API) — more work, same zero-vendoring outcome.

[lann]

Working DX proposal (supersedes the table sketch)

Module-attribute shape:

#[component_test_sdk::suite]          // embeds the contract WIT; census = source order
mod sample {
    mod math {
        #[case]
        async fn add(ctx: &Context) -> Verdict {          // "sample/math/add"
            ctx.diagnostic("computing 2 + 2".into()).await;
            check_eq!(2 + 2, 4, "2 + 2");
            Ok(())
        }

        #[case]
        fn mul() -> Verdict {                             // sync + no ctx: both optional
            let got = parse_answer("42")?;                // `?` -> failed via From<E: Error>
            check_eq!(got, 42, "6 * 9");
            Ok(())
        }
    }

    #[cases(marks("hsm"))]                                // inherited by the subtree
    mod hsm {
        #[case]
        async fn attest(ctx: &Context) -> Verdict { ... } // ["hsm"]

        #[case(marks("!hsm"))]                            // polarity flip overrides inherited "hsm"
        async fn declined(ctx: &Context) -> Verdict { ... } // ["!hsm"]
    }

    #[case_generator(prefix = "aes-gcm/wycheproof", marks("aes-gcm"))]
    fn gcm_vectors() -> impl Iterator<Item = Case> {
        vectors::AES_GCM.iter().map(|v| {
            Case::new(format!("tc{}", v.tc_id), move |ctx| run_gcm_vector(ctx, v))
        })
    }
}

Why module-attribute (vs the earlier single-table macro)

An outer #[suite] on a mod receives the whole subtree as tokens: collection is syntactic, census order = source order (no link-order nondeterminism — the objection that motivated the table). Names derive from module path + fn name, so hierarchy stops being stringly and the name-typo class disappears; non-leaf grammar ("segments are WIT labels") maps onto module idents nearly for free.

Resolved semantics

1. Names: ident→segment maps _→- uniformly (injective; idents can't contain -). Fn-derived leaves can't express _/./digit-first — covered by #[case(name = "0x1a2b")] override and by generators (string leaves). Root segment from the mod name; #[suite(name = "...")] renames without renaming the mod.
2. Mark inheritance: marks accumulate along the module path; for a given feature name, the nearest declaration wins whole (polarity flip is the useful special case — the decline case lives inside its family's mod). Same-level contradiction (marks("hsm", "!hsm")) is an error. The contradiction/duplicate invariant is enforced in the data model (Marks::new, commit 9e9a7c5) at every producer — the macro adds source-span diagnostics, it does not own the rule. The lockfile records resolved marks only; inheritance is authoring sugar invisible downstream.
3. Verdicts: Verdict = Result<(), Failure> with blanket impl<E: std::error::Error> From<E> for Failure (one-line failed; blanket over Error not Display — Failure: Display would collide with the reflexive impl). anyhow::Error (not Error) gets its own impl behind an anyhow feature. Skips are always explicit, never via ?. The From target is SDK-owned Failure, not the bindings' Outcome (generated in the consumer crate; glue maps).
4. Case shape: run: Box<dyn for<'a> Fn(&'a Context) -> BoxFuture<'a, Verdict>> — the future borrows the context (which is also what prevents stashing it). async and the ctx parameter are both optional on #[case] fns; the expansion normalizes.
5. Generators: #[case_generator(prefix = ..., marks(...))], prefix path-composed under the mod path like everything else; returns impl Iterator<Item = Case>. Static inventory gets a row-level prefix record (prefix/* + marks) and the runtime all()-vs-section cross-check relaxes to prefix-matching for generated rows. Literal cases keep exact records.
6. WIT embedding: the proc macro embeds the contract WIT (include_str! at macro build time → generate!({ inline })); consumers never vendor tests.wit. Domain/SUT imports are a separate plain user-side generate! (disjoint packages; component-type:* sections merged by wasm-component-ld). Spike first: confirm the multi-generate! merge links and runs; fallback is Resolve-injection via wit-parser.
7. Decline-pair lint at expansion over the collected tree (marked feature without a !feature row = compile error naming the missing pair), with the waiver-with-rationale escape (L4 canonical results: data model, WIT event types, JSON edge encoding #26 observability lesson) surfaced into the lockfile.
8. Sync/async bindings: SDK cargo feature (default async), not per-suite syntax — a toolchain property, not a suite property.

Open (cosmetic)

• Case::new closure plumbing for &'static vector data (move |ctx| f(ctx, v)) — acceptable for the generator-author minority; sugar can come later.
• Whether #[cases(...)] on a mod vs #![cases(...)] inner-attribute spelling; whichever proves friendlier to proc-macro parsing.

Order of work

(1) multi-generate! merge spike → (2) proc-macro skeleton (module walk, name derivation, glue emission, marks section) → (3) inheritance + lints + diagnostics → (4) generators/prefix records + cross-check relaxation (coordinate with the runner) → (5) port sample+fixture suites to the attribute DX as acceptance.

[lann]

Implemented (commit e205495). Everything from the working proposal landed:

• #[suite] module attribute: names from module path + fn idents (_→-, name= override), tag inheritance with nearest-per-feature-wins (polarity flip verified: the fixture's decline case lives inside its tagged family mod), expansion-time grammar validation + decline-pair lint (data-model invariants surfaced with macro spans), sync/no-ctx fn normalization, full glue emission (bindings/registry/impls/export!/tags-section records).
• Contract WIT embedded in the macro — suite crates carry no wit dir at all; both suites' symlinks deleted. The multi-generate! merge spike passed (disjoint packages union at wasm-component-ld: import spike:domain/facts + export spike:contract/greet from two inline generate!s), so consumer SUT imports remain a plain user-side generate! per the plan.
• #[case_generator(prefix = ...)]: runtime leaves under a static prefix; inventory carries prefix/* records (label-only segments enforced); lockfiles grew [[generated]] entries; runner cross-check and tag scheduling are prefix-aware; coverage accepts leaves under prefixes exactly once.
• Acceptance: sample suite byte-identical on ct-runner + composed + jco-node; fixture exercises trap/inheritance/flip/generator (5 pass / 1 trap-fail / 1 N/A / 7 total under --missing hsm); just all green.

Deviations from the proposal, all minor:

• Suite-mod root needs an explicit use component_test_sdk::prelude::*; inside the mod (file-level imports don't reach module bodies); submodules get use super::Context injected but bring their own prelude. Documented pattern; revisit if it grates.
• Case fns are made pub by the macro (registry lives at suite root; child-mod privacy).
• Generator item type is GeneratedCase (prelude-aliased to Case); closures still Box::pin by hand — the known cosmetic open.
• Waivers for the decline-pair lint remain unimplemented (tracked via L4 canonical results: data model, WIT event types, JSON edge encoding #26).

[lann]

Closing as shipped: the SDK core landed (e205495 and successors) and is in production in both consumers — polymorph-webcrypto's guest-ct/signing-guest-ct (~19k + ~770 cases through #[suite]/#[case_row]/#[case_generator], tags with decline pairs, census-pinned) and polymorph-websocket's guest-ct (55 cases). Remaining SDK ergonomics are tracked separately in #40.