fix(ci): preserve crate docs and declare artifact dependencies

.github/workflows/ci.yml

@@ -1188,20 +1188,23 @@ jobs:
           if-no-files-found: error
 
       - name: Upload shared Rust query package
+        if: ${{ contains(join(fromJson(needs.affected.outputs.job_targets)['rust-sdk-package'], ','), 'oliphaunt-query:') }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: oliphaunt-query-sdk-package-artifacts
           path: target/sdk-artifacts/oliphaunt-query
           if-no-files-found: error
 
       - name: Upload native Rust bindings package
+        if: ${{ contains(join(fromJson(needs.affected.outputs.job_targets)['rust-sdk-package'], ','), 'liboliphaunt-native-bindings:') }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: liboliphaunt-native-bindings-sdk-package-artifacts
           path: target/sdk-artifacts/liboliphaunt-native-bindings
           if-no-files-found: error
 
       - name: Upload broker source package
+        if: ${{ contains(join(fromJson(needs.affected.outputs.job_targets)['rust-sdk-package'], ','), 'oliphaunt-broker:') }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: oliphaunt-broker-sdk-package-artifacts

src/database-resources/icu/cargo/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_icu.rs"));

src/database-resources/seeds/package-carriers.mts

@@ -182,7 +182,7 @@ export function packageSeedCarriers(argv = [], { assetDir, outputDir, sourceDir
     mkdirSync(path.join(stage, 'src'));
     writeFileSync(
       path.join(stage, 'src/lib.rs'),
-      `#![deny(unsafe_code)]\npub fn seed_archive() -> &'static [u8] { include_bytes!("../seed.tar.zst") }\npub fn seed_manifest() -> &'static str { include_str!("../manifest.json") }\n${identity.profile === 'icu' ? 'pub use oliphaunt_icu as icu;\n' : ''}`,
+      `#![doc = include_str!("../README.md")]\n#![deny(unsafe_code)]\npub fn seed_archive() -> &'static [u8] { include_bytes!("../seed.tar.zst") }\npub fn seed_manifest() -> &'static str { include_str!("../manifest.json") }\n${identity.profile === 'icu' ? 'pub use oliphaunt_icu as icu;\n' : ''}`,
     );
     writeFileSync(
       path.join(stage, 'Cargo.toml'),

src/extensions/artifacts/packages/tools/package-extension-cargo-facades.mts

@@ -231,7 +231,8 @@ The default \`native\` feature selects the matching native artifact leaf.${
   );
   writeFileSync(
     path.join(sourceDir, 'src/lib.rs'),
-    `#![deny(unsafe_op_in_unsafe_fn)]
+    `#![doc = include_str!("../README.md")]
+#![deny(unsafe_op_in_unsafe_fn)]
 
 ${unsupportedNativeGuard}
 

src/extensions/artifacts/packages/tools/package-extension-release-carriers.mts

@@ -2193,7 +2193,8 @@ Applications do not depend on this crate directly.
   );
   writeFileSync(
     path.join(crateDir, 'src/lib.rs'),
-    `pub const PRODUCT: &str = "${product}";
+    `#![doc = include_str!("../README.md")]
+pub const PRODUCT: &str = "${product}";
 pub const KIND: &str = "extension-part";
 pub const MEMBERS: &[&str] = &[${members.map((member) => JSON.stringify(member)).join(', ')}];
 pub const RELEASE_TARGET: &str = "${target}";
@@ -2784,7 +2785,8 @@ sha2 = "0.10"
   );
   writeFileSync(
     path.join(crateDir, 'src/lib.rs'),
-    `pub const PRODUCT: &str = "${product}";
+    `#![doc = include_str!("../README.md")]
+pub const PRODUCT: &str = "${product}";
 pub const KIND: &str = "extension";
 pub const MEMBERS: &[&str] = &[${members.map((member) => JSON.stringify(member)).join(', ')}];
 pub const RELEASE_TARGET: &str = "${target}";

src/native/broker/crates/linux-arm64-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub const PRODUCT: &str = "oliphaunt-broker";
 pub const KIND: &str = "broker-helper";
 pub const RELEASE_TARGET: &str = "linux-arm64-gnu";

src/native/broker/crates/linux-x64-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub const PRODUCT: &str = "oliphaunt-broker";
 pub const KIND: &str = "broker-helper";
 pub const RELEASE_TARGET: &str = "linux-x64-gnu";

src/native/broker/crates/macos-arm64/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub const PRODUCT: &str = "oliphaunt-broker";
 pub const KIND: &str = "broker-helper";
 pub const RELEASE_TARGET: &str = "macos-arm64";

src/native/broker/crates/windows-x64-msvc/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub const PRODUCT: &str = "oliphaunt-broker";
 pub const KIND: &str = "broker-helper";
 pub const RELEASE_TARGET: &str = "windows-x64-msvc";

src/native/broker/moon.yml

@@ -122,7 +122,8 @@ tasks:
       CARGO_TARGET_DIR: "target"
     inputs:
       - "@group(cargo-workspace)"
-      - "@group(code)"
+      - "{src,tests}/**/*"
+      - "{Cargo.toml,README.md}"
     options:
       cache: true
       runFromWorkspaceRoot: true

src/native/broker/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 //! Broker transport shared by the broker executable and native SDK client.
 pub mod ipc;
 pub mod mobile;

src/native/postgres-tools/crates/tools/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 mod arguments;

src/native/runtime/moon.yml

@@ -630,6 +630,8 @@ tasks:
       - requires-rust
     command: "bash src/native/runtime/tools/test-packaging.sh"
     inputs:
+      - /src/native/postgres-tools/crates/tools/**/*
+      - /src/native/postgres-tools/tools/package-cargo-artifacts.mts
       - /tools/packaging/windows-vc-runtime-policy.json
       - /src/extensions/tools/extension-upstream-licenses.mts
       - /src/extensions/contracts/*.mts

src/native/runtime/tools/package-liboliphaunt-cargo-artifacts.test.sh

@@ -17,6 +17,12 @@ bash tools/dev/bun.sh test ./src/native/runtime/tools/package-liboliphaunt-cargo
 CARGO_HOME="$root/installed-consumer/cargo-home" \
   CARGO_TARGET_DIR="$root/installed-consumer/target" \
   cargo check --offline --manifest-path "$root/installed-consumer/Cargo.toml"
+CARGO_HOME="$root/installed-consumer/cargo-home" \
+  CARGO_TARGET_DIR="$root/installed-consumer/target" \
+  cargo doc --offline --no-deps --manifest-path "$root/installed-consumer/Cargo.toml" \
+    -p liboliphaunt-native-linux-x64-gnu -p oliphaunt-tools
+grep -q 'Cargo artifact crate for' "$root/installed-consumer/target/doc/liboliphaunt_native_linux_x64_gnu/index.html"
+grep -q 'Optional endpoint-oriented runner' "$root/installed-consumer/target/doc/oliphaunt_tools/index.html"
 if rustc --crate-name oliphaunt_tools --crate-type lib --edition 2024 \
   --emit metadata -o "$root/unsupported.rmeta" "$root/forced-unsupported-tools.rs" \
   > "$root/unsupported.log" 2>&1; then

src/native/rust-bindings/moon.yml

@@ -51,7 +51,7 @@ tasks:
         cacheStrategy: hash
     tags: ["quality", "unit", "requires-rust"]
     command: "cargo test --locked"
-    inputs: ["@group(code)", "testdata/**/*", "/Cargo.lock", "/Cargo.toml"]
+    inputs: ["@group(code)", "README.md", "testdata/**/*", "/Cargo.lock", "/Cargo.toml"]
   package:
     tags: ["release", "artifact-package", "ci-rust-sdk-package"]
     script: |

src/native/rust-bindings/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_op_in_unsafe_fn)]
 //! Shared native liboliphaunt execution and resource ownership.
 mod build_resources;

src/native/sdks/rust/README.md

@@ -14,7 +14,7 @@ The [quickstart](https://oliphaunt.dev/docs/sdk/rust) covers prerequisites and t
 
 The crate includes its matching desktop runtime resources.
 
-```rust
+```rust,no_run
 use oliphaunt::Oliphaunt;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {

src/native/sdks/rust/crates/oliphaunt-build/README.md

@@ -5,7 +5,8 @@ bundle Oliphaunt runtime artifacts.
 
 Applications add it as a build dependency and call it from `build.rs`:
 
-```rust
+```rust,no_run
+# #[allow(clippy::needless_doctest_main)] // build.rs requires a main function.
 fn main() {
     oliphaunt_build::configure();
 }

src/native/sdks/rust/crates/oliphaunt-build/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 //! Cargo artifact integration for SDKs and custom deployments.
 //!
 //! The SDK uses `embed_resolved_artifacts()` internally. Ordinary applications

src/native/sdks/rust/moon.yml

@@ -89,7 +89,9 @@ tasks:
       - "@group(rust-test-config)"
       - project: "shared-test-fixtures"
         group: "fixtures"
-      - "@group(code)"
+      - "{src,tests,tools}/**/*"
+      - "{Cargo.toml,build.rs,README.md}"
+      - "crates/oliphaunt-build/**/*"
     options:
       cache: true
       runFromWorkspaceRoot: true

src/native/sdks/rust/src/lib.rs

@@ -1,9 +1,6 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_op_in_unsafe_fn)]
 #![forbid(missing_docs)]
-//! Native-first Rust SDK surface for embedded Oliphaunt.
-//!
-//! This crate is deliberately native-only. It does not expose a WASIX engine
-//! and it does not depend on the current `oliphaunt-wasix` runtime layout.
 
 #[cfg(feature = "desktop")]
 mod broker;

src/query/rust/moon.yml

@@ -45,7 +45,7 @@ tasks:
         cacheStrategy: hash
     tags: ["quality", "unit", "requires-rust"]
     command: "cargo test --locked"
-    inputs: ["@group(sources)", "/Cargo.lock", "/Cargo.toml"]
+    inputs: ["@group(sources)", "README.md", "/Cargo.lock", "/Cargo.toml"]
 
   package:
     tags: ["release", "artifact-package", "ci-rust-sdk-package"]

src/query/rust/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 // Runtime-neutral PostgreSQL query protocol core shared by the Rust SDKs.
 //
 // This module deliberately has no dependencies outside `std`. It owns the

src/wasix/pgwire-server/moon.yml

@@ -45,7 +45,7 @@ tasks:
         cacheStrategy: hash
     command: "cargo test --locked"
     tags: ["quality", "unit", "requires-rust"]
-    inputs: ["@group(sources)", "/Cargo.toml", "/Cargo.lock"]
+    inputs: ["@group(sources)", "README.md", "/Cargo.toml", "/Cargo.lock"]
   test-integration:
     command: "cargo test --locked -- --ignored --test-threads=1"
     tags: ["runtime", "integration", "requires-rust", "ci-liboliphaunt-wasix-aot"]

src/wasix/pgwire-server/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 //! PostgreSQL wire server with a separately selectable WASIX backend.
 
 /// Runtime-independent PostgreSQL connection framing.

src/wasix/postgres-tools/crates/aot/aarch64-apple-darwin/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/postgres-tools/crates/aot/aarch64-unknown-linux-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/postgres-tools/crates/aot/x86_64-pc-windows-msvc/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/postgres-tools/crates/aot/x86_64-unknown-linux-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/postgres-tools/crates/tools/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_tools.rs"));

src/wasix/postgres-tools/moon.yml

@@ -66,13 +66,13 @@ tasks:
   test-consumer:
     tags: ["integration", "consumer", "ci-wasix-ts-sdk-package"]
     command: "bash tools/ci/with-projects.sh --exec bash src/wasix/postgres-tools/ts/tests/consumer.sh"
-    deps: ["oliphaunt-query-ts:build", "oliphaunt-wasix-tools-ts:package", {target: "oliphaunt-wasix-ts:package", cacheStrategy: ignored}, "oliphaunt-wasix-ts:build", "wasix-browser-host:build", "oliphaunt-wasix-napi:build-release-assets", "postgres-tools-wasix:package-portable", "postgres-tools-wasix:package-aot"]
+    deps: ["oliphaunt-query-ts:build", "extension-artifacts-wasix:compiler-output", "oliphaunt-wasix-tools-ts:package", {target: "oliphaunt-wasix-ts:package", cacheStrategy: ignored}, "oliphaunt-wasix-ts:build", "wasix-browser-host:build", "oliphaunt-wasix-napi:build-release-assets", "postgres-tools-wasix:package-portable", "postgres-tools-wasix:package-aot"]
     inputs: ["ts/tests/**/*", "/src/wasix/sdks/ts/tools/integration/packed-node-fixture.mts", "/src/wasix/sdks/ts/tools/pgwire-client.mts", "/src/test-fixtures/postgres/**/*", "tools/*.mts"]
     options: {cache: false, runFromWorkspaceRoot: true}
   test-browser:
     tags: ["integration", "browser", "ci-wasix-ts-sdk-package"]
     command: "bash tools/ci/with-projects.sh --exec bash src/wasix/sdks/ts/tools/integration/smoke-browser.sh --package-only --tools"
-    deps: ["oliphaunt-query-ts:build", "oliphaunt-wasix-tools-ts:package", {target: "oliphaunt-wasix-ts:package", cacheStrategy: ignored}, "oliphaunt-wasix-ts:build", "wasix-browser-host:build", "postgres-tools-wasix:package-portable"]
+    deps: ["oliphaunt-query-ts:build", "extension-artifacts-wasix:compiler-output", "database-resources:package-wasix", "database-resources:package-icu", "oliphaunt-wasix-tools-ts:package", {target: "oliphaunt-wasix-ts:package", cacheStrategy: ignored}, "oliphaunt-wasix-ts:build", "wasix-browser-host:build", "postgres-tools-wasix:package-portable"]
     inputs: ["ts/tests/**/*", "/src/wasix/sdks/ts/tools/integration/{packed-node-fixture.mts,smoke-browser.*}", "/src/test-fixtures/postgres/**/*", "tools/*.mts"]
     options: {cache: false, runFromWorkspaceRoot: true}
   format-check:

src/wasix/runtime/crates/aot/aarch64-apple-darwin/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/runtime/crates/aot/aarch64-unknown-linux-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/runtime/crates/aot/x86_64-pc-windows-msvc/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/runtime/crates/aot/x86_64-unknown-linux-gnu/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 include!(concat!(env!("OUT_DIR"), "/generated_aot.rs"));

src/wasix/runtime/crates/assets/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(unsafe_code)]
 
 use serde::{Deserialize, Serialize};

src/wasix/runtime/tools/package_liboliphaunt_wasix_cargo_artifacts.mts

@@ -732,6 +732,7 @@ function writeExtensionPayloadPartSources({
     writeFileSync(
       path.join(part.sourceDir, 'src/lib.rs'),
       [
+        '#![doc = include_str!("../README.md")]',
         '#![deny(unsafe_code)]',
         `pub const PRODUCT: &str = ${JSON.stringify(product)};`,
         `pub const TARGET: &str = ${JSON.stringify(target)};`,
@@ -1279,6 +1280,7 @@ function writeExtensionCargoSource(spec, sourceRoot, partBytes) {
   writeFileSync(
     path.join(crateDir, 'src/lib.rs'),
     [
+      '#![doc = include_str!("../README.md")]',
       '#![deny(unsafe_code)]',
       '',
       `pub const SQL_NAMES: &[&str] = &[${spec.members.map((member) => JSON.stringify(member.sqlName)).join(', ')}];`,
@@ -1437,6 +1439,7 @@ function writeExtensionAotCargoSource(spec, sourceRoot, partBytes) {
   writeFileSync(
     path.join(crateDir, 'src/lib.rs'),
     [
+      '#![doc = include_str!("../README.md")]',
       '#![deny(unsafe_code)]',
       '',
       `pub const SQL_NAMES: &[&str] = &[${spec.members.map((member) => JSON.stringify(member.sqlName)).join(', ')}];`,

src/wasix/sdks/rust/README.md

@@ -12,7 +12,7 @@ The [quickstart](https://oliphaunt.dev/docs/sdk/wasix-rust) covers prerequisites
 
 ## First query
 
-```rust
+```rust,no_run
 use oliphaunt_wasix::Oliphaunt;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {

src/wasix/sdks/rust/moon.yml

@@ -137,7 +137,8 @@ tasks:
       - "@group(rust-test-config)"
       - project: "shared-test-fixtures"
         group: "fixtures"
-      - "@group(code)"
+      - "{src,tests,tools}/**/*"
+      - "{Cargo.toml,build.rs,README.md}"
       - project: "liboliphaunt-wasix"
         group: "crates"
     options:

tools/ci/ci-plan-node-products.test.mts

@@ -983,7 +983,12 @@ test('Android extension packaging selects matching dependency-complete Linux sup
 });
 
 test('WASIX package README and compiler unit fixtures do not select runtime compilers', () => {
-  for (const file of [paths.wasixSdkReadme, paths.wasixDockerTest, paths.nativeExtensionFixture]) {
+  for (const file of [
+    paths.wasixSdkReadme,
+    paths.wasixRustReadme,
+    paths.wasixDockerTest,
+    paths.nativeExtensionFixture,
+  ]) {
     const observation = affectedObservation([file]);
     const roots = new Set(triggeringTaskNames(observation.tasks));
     const required = requiredTasksForAffected(roots);
@@ -996,6 +1001,21 @@ test('WASIX package README and compiler unit fixtures do not select runtime comp
   );
   assert(jobs.has('wasix-ts-package'));
   assert(!jobs.has('wasix-ts-sdk-package'));
+  const rust = effects(paths.wasixRustReadme);
+  assert(rust.directTasks.includes('oliphaunt-wasix-rust:test'));
+  assert.deepEqual(rust.releaseProducts, []);
+});
+
+test('native Rust README selects its source tests without compiling runtime artifacts', () => {
+  const result = effects(paths.nativeRustReadme);
+  assert(result.directTasks.includes('oliphaunt-rust:test'));
+  assert.deepEqual(result.releaseProducts, []);
+  for (const target of [
+    'liboliphaunt-native:build-runtime-desktop-target',
+    'extension-artifacts-native:build-target',
+    'liboliphaunt-wasix:compiler-output',
+  ])
+    assert(!result.tasks.includes(target), target);
 });
 
 test('SDK runtime test edits select their final hosted execution roots', () => {

tools/ci/ci-plan-test-inputs.mts

@@ -8,6 +8,8 @@ export const paths = {
   mobileBrokerRuntimeTests: 'src/native/sdks/rust/tests/mobile_broker.rs',
   wasixResourceRuntimeTests: 'src/wasix/sdks/rust/tests/resources.rs',
   wasixSdkReadme: 'src/wasix/sdks/ts/README.md',
+  wasixRustReadme: 'src/wasix/sdks/rust/README.md',
+  nativeRustReadme: 'src/native/sdks/rust/README.md',
   wasixDockerTest: 'src/wasix/runtime/assets/build/docker/install-pinned-wasixcc.test.sh',
   nativeExtensionFixture: 'src/extensions/artifacts/native/tools/create-artifact.test.mts',
   windowsVcRuntimePolicy: 'tools/packaging/windows-vc-runtime-policy.json',

tools/ci/ci-plan-wasix-postmaster-release.test.mts

@@ -244,12 +244,12 @@ test('native lifecycle supervisor changes select its exact hosted proof', () =>
   );
 });
 
-test('shipped Postmaster documentation has a cheap producer without losing release ownership', () => {
+test('shipped Postmaster documentation has a cheap producer without requesting a release', () => {
   const effects = directEffects(paths.postmasterReadme);
   assert(effects.directTasks.includes('liboliphaunt-wasix-postmaster:package-docs'));
   assert(!effects.jobs.includes('wasix-postmaster'));
   const release = buildPlan(loadGraph(), normalizeFiles([paths.postmasterReadme]));
-  assert(release.releaseProducts.includes('liboliphaunt-wasix-postmaster'));
+  assert.deepEqual(release.releaseProducts, []);
   const closure = taskGraph(taskRoots.liboliphauntWasixPostmasterReleaseAssets);
   assert(closure.some(({ target }) => target === 'liboliphaunt-wasix-postmaster:package-docs'));
 });