From ad722885e3b6924bedf0c3cc5d728dfb8c8a75cf Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Thu, 23 Jul 2026 22:09:35 +0200 Subject: [PATCH] feat(oci): embed full component metadata so wasm.directory renders a real page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit wasm.directory shows a component's WIT (with doc comments) + its EMBEDDED package metadata (description/licenses/source/authors/version), which cargo-component bakes into the wasm `package-metadata` section from Cargo.toml. The flight crate carried only name/description/version, and — being a standalone crate — inherits nothing from the workspace root, so the listing had no license or source link. Add license/repository/homepage/documentation/authors/keywords/categories, and rewrite the description for a stranger (drop the internal meld→loom→synth→gale jargon and the confusing "(v1.26.0)"; lead with "formally-verified" + the actual verification tools). Document this as the metadata contract EVERY published relay component must carry (docs/OCI-DISTRIBUTION.md) — the per-component publishing for falcon-rate/estimator/mixer (jess#167) inherits it. Also mark the wasm.directory listing LIVE (namespace accepted, #467 merged). Takes effect on the next release's ghcr push; no code/interface change. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HvusAXYbHLyv3uTzfBcMbG --- docs/OCI-DISTRIBUTION.md | 32 ++++++++++++++++++++++++++++---- wasm/cm/flight/Cargo.toml | 15 ++++++++++++++- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/OCI-DISTRIBUTION.md b/docs/OCI-DISTRIBUTION.md index d941de8..1ff989b 100644 --- a/docs/OCI-DISTRIBUTION.md +++ b/docs/OCI-DISTRIBUTION.md @@ -74,16 +74,40 @@ cosign verify ghcr.io/pulseengine/falcon-flight:1.127.0 \ already exist and be **public** (step 1) before submitting — an unpullable entry is rejected. Do this only after a real release has populated the package. - > Status: filed for `pulseengine` off falcon-v1.127.0 — - > [wasm.directory#466](https://github.com/yoshuawuyts/wasm.directory/issues/466) - > → auto-opened [PR #467](https://github.com/yoshuawuyts/wasm.directory/pull/467) - > (`registry/pulseengine.toml`), awaiting new-namespace maintainer review. + > Status: **LIVE** — the `pulseengine` namespace was accepted + > ([wasm.directory#466](https://github.com/yoshuawuyts/wasm.directory/issues/466) + > → [PR #467](https://github.com/yoshuawuyts/wasm.directory/pull/467) merged); + > indexed at . wasm.directory is **alpha** ("indexed data may be incomplete or reset without notice; don't depend on it in production") — treat the listing as a visibility channel, not a dependency. The durable, signed artifacts remain the GitHub Release and the ghcr OCI ref. +## Component metadata contract (what wasm.directory renders) + +wasm.directory shows a component's **WIT interface** (with its `///` doc comments) +plus the **embedded package metadata** — `description`, `licenses`, `source`, +`authors`, `version` — which `cargo-component` bakes into the wasm +`package-metadata` section from the crate's `Cargo.toml`. Empty metadata → a bare +listing. So **every published relay component MUST carry**, in its (standalone) +`Cargo.toml` — it can't inherit the workspace root: + +```toml +description = "" +license = "Apache-2.0" +repository = "https://github.com/pulseengine/relay" +documentation = "" +authors = ["PulseEngine"] +keywords = ["flight-control", "verified", "drone", "embedded", "wasm"] +categories = ["aerospace", "science::robotics"] +``` + +…and a WIT world/interface with real `///` doc comments (the interface docs come +straight from the WIT). This is the metadata pattern the per-component publishing +(the `falcon-rate`/estimator/mixer components, jess#167) inherits — a listing is +only as informative as the metadata the component carries. + ## Scope note `falcon:flight`'s current world (`flight-demo`) exports two runnable smoke-test diff --git a/wasm/cm/flight/Cargo.toml b/wasm/cm/flight/Cargo.toml index 7329fad..034f8c8 100644 --- a/wasm/cm/flight/Cargo.toml +++ b/wasm/cm/flight/Cargo.toml @@ -1,9 +1,22 @@ [package] name = "falcon-flight-component" -description = "The verified falcon flight core (IEKF → geometric SE(3) → ADRC → mixer) as a WebAssembly Component Model component — the portable, wasmtime-runnable artifact the toolchain-to-hardware integration (meld → loom → synth → gale) consumes. (v1.26.0)" +description = "Formally-verified drone flight core (invariant-EKF estimator → geometric SE(3) attitude control → ADRC → mixer) as a portable WebAssembly Component. Runs the same cascade that is Kani/Verus/Rocq/Lean-verified natively and bare-metal on Cortex-M." version = "0.1.0" edition = "2021" publish = false +# Embedded component metadata — cargo-component bakes these into the wasm +# `package-metadata` section, and wasm.directory renders them (description, +# licenses, source) alongside the WIT. Standalone crate (own [workspace]), +# so it can't inherit the repo root's fields — set them explicitly. This is +# the metadata contract for EVERY published relay component (see +# docs/OCI-DISTRIBUTION.md). +license = "Apache-2.0" +repository = "https://github.com/pulseengine/relay" +homepage = "https://pulseengine.eu" +documentation = "https://github.com/pulseengine/relay/blob/main/docs/OCI-DISTRIBUTION.md" +authors = ["PulseEngine"] +keywords = ["flight-control", "verified", "drone", "embedded", "wasm"] +categories = ["aerospace", "science::robotics"] [dependencies] falcon-core = { path = "../../../crates/falcon-core" }