From 7923a85c01590adb8218c21aebc2ffc6ab1c5a32 Mon Sep 17 00:00:00 2001 From: Chris <16280532+chrisl10@users.noreply.github.com> Date: Mon, 17 Aug 2026 11:27:33 -0700 Subject: [PATCH] Add rust-worker-bee and rust-stinger Port the rust-worker-bee agent and its paired rust-stinger from a prior fork. - Add .claude/agents/rust-worker-bee.md - Add .claude/skills/rust-stinger/ (guides, examples, templates, research, reports) - Add beekeeper-suit routing guide for rust-worker-bee - Register rust-worker-bee in the beekeeper-suit roster and pairing audit - Regenerate harnesses (.agents, .codex, .cursor) rust-worker-bee owns bounded Rust implementation and code review for Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, tests, and local packaging evidence. --- .../skills/beekeeper-suit/PAIRING-AUDIT.md | 14 +- .agents/skills/beekeeper-suit/SKILL.md | 5 +- .../beekeeper-suit/guides/rust-worker-bee.md | 52 +++++ .agents/skills/rust-stinger/README.md | 16 ++ .agents/skills/rust-stinger/SKILL.md | 83 ++++++++ .../01-happy-path-bounded-service-slice.md | 66 +++++++ .../02-edge-visible-output-cancellation.md | 62 ++++++ .../03-edge-concurrent-budget-reservation.md | 49 +++++ .../04-release-evidence-with-closed-gates.md | 45 +++++ .../guides/00-authority-and-principles.md | 41 ++++ .../guides/01-inspect-workspace.md | 38 ++++ .../guides/02-design-workspace-and-types.md | 52 +++++ .../guides/03-implement-bounded-slices.md | 34 ++++ .../guides/04-prove-async-streams.md | 36 ++++ .../guides/05-prove-persistence-and-state.md | 39 ++++ .../guides/06-implement-adapters.md | 37 ++++ .../guides/07-build-cli-and-tui.md | 30 +++ .../guides/08-verify-and-package-evidence.md | 54 ++++++ .../rust-stinger/guides/09-close-the-loop.md | 42 +++++ .agents/skills/rust-stinger/reports/README.md | 3 + .../implementation-handoff-report-template.md | 15 ++ .../2026-07-24-axum-graceful-shutdown.md | 26 +++ .../async/2026-07-24-axum-service-testing.md | 26 +++ .../async/2026-07-24-axum-streaming-body.md | 26 +++ .../2026-07-24-tokio-graceful-shutdown.md | 26 +++ .../research/async/2026-07-24-tokio-mpsc.md | 26 +++ .../async/2026-07-24-tokio-release-policy.md | 26 +++ .../2026-07-24-tokio-select-cancellation.md | 26 +++ .../async/2026-07-24-tokio-send-reserve.md | 26 +++ .../async/2026-07-24-tower-service-builder.md | 26 +++ .../2026-07-24-tower-service-readiness.md | 26 +++ .../2026-07-24-serde-container-attributes.md | 26 +++ .../2026-07-24-serde-enum-representations.md | 26 +++ .../boundaries/2026-07-24-thiserror.md | 26 +++ .../cli-tui/2026-07-24-clap-errors.md | 26 +++ .../cli-tui/2026-07-24-clap-parser.md | 26 +++ .../2026-07-24-ratatui-architecture.md | 26 +++ .../cli-tui/2026-07-24-ratatui-lifecycle.md | 26 +++ .../2026-07-24-ratatui-test-backend.md | 26 +++ .../research/evidence-synthesis.md | 178 ++++++++++++++++++ .agents/skills/rust-stinger/research/index.md | 64 +++++++ .../2026-07-24-tracing-instrument.md | 26 +++ .../2026-07-24-tracing-subscriber.md | 26 +++ .../2026-07-24-sqlite-atomic-commit.md | 26 +++ .../2026-07-24-sqlite-pragma-durability.md | 26 +++ .../2026-07-24-sqlite-transactions.md | 26 +++ .../persistence/2026-07-24-sqlite-wal.md | 26 +++ .../2026-07-24-sqlx-connect-options.md | 26 +++ .../2026-07-24-sqlx-custom-transactions.md | 26 +++ .../2026-07-24-sqlx-migrations-queries.md | 26 +++ .../rust-stinger/research/research-plan.md | 91 +++++++++ .../rust-stinger/research/research-summary.md | 68 +++++++ .../rust-cargo/2026-07-24-cargo-ci-msrv.md | 26 +++ .../rust-cargo/2026-07-24-cargo-features.md | 26 +++ .../2026-07-24-cargo-resolver-v3.md | 26 +++ .../2026-07-24-cargo-rust-version.md | 26 +++ .../rust-cargo/2026-07-24-clippy-ci.md | 26 +++ .../rust-cargo/2026-07-24-platform-support.md | 26 +++ .../2026-07-24-rust-release-1-97.md | 26 +++ .../rust-cargo/2026-07-24-unsafe-rust.md | 26 +++ .../2026-07-24-rustls-config-builder.md | 26 +++ .../2026-07-24-rustls-verification-markers.md | 26 +++ .../research/security/2026-07-24-secrecy.md | 26 +++ .../supply-chain/2026-07-24-cargo-audit.md | 26 +++ .../2026-07-24-cargo-auditable.md | 26 +++ .../2026-07-24-cargo-cyclonedx.md | 26 +++ .../2026-07-24-cargo-deny-checks.md | 26 +++ ...26-07-24-cargo-deny-license-limitations.md | 26 +++ .../2026-07-24-cargo-dist-attestations.md | 26 +++ .../2026-07-24-cargo-dist-config.md | 26 +++ .../2026-07-24-cargo-package-verification.md | 26 +++ .../2026-07-24-cargo-sbom-unstable.md | 26 +++ .../supply-chain/2026-07-24-rustsec.md | 26 +++ .../2026-07-24-sigstore-cosign-blob.md | 26 +++ .../testing/2026-07-24-criterion-analysis.md | 26 +++ .../research/testing/2026-07-24-loom.md | 26 +++ .../testing/2026-07-24-nextest-retries.md | 26 +++ .../research/testing/2026-07-24-nextest.md | 26 +++ .../testing/2026-07-24-proptest-index.md | 26 +++ .../2026-07-24-proptest-state-machines.md | 26 +++ .../testing/2026-07-24-tokio-time-testing.md | 26 +++ .../templates/acceptance-slice-checklist.md | 16 ++ .../templates/implementation-handoff.md | 53 ++++++ .../templates/release-evidence-manifest.yaml | 63 +++++++ .../templates/rust-decision-log.md | 25 +++ .claude/agents/rust-worker-bee.md | 111 +++++++++++ .../skills/beekeeper-suit/PAIRING-AUDIT.md | 14 +- .claude/skills/beekeeper-suit/SKILL.md | 5 +- .../beekeeper-suit/guides/rust-worker-bee.md | 52 +++++ .claude/skills/rust-stinger/README.md | 16 ++ .claude/skills/rust-stinger/SKILL.md | 83 ++++++++ .../01-happy-path-bounded-service-slice.md | 66 +++++++ .../02-edge-visible-output-cancellation.md | 62 ++++++ .../03-edge-concurrent-budget-reservation.md | 49 +++++ .../04-release-evidence-with-closed-gates.md | 45 +++++ .../guides/00-authority-and-principles.md | 41 ++++ .../guides/01-inspect-workspace.md | 38 ++++ .../guides/02-design-workspace-and-types.md | 52 +++++ .../guides/03-implement-bounded-slices.md | 34 ++++ .../guides/04-prove-async-streams.md | 36 ++++ .../guides/05-prove-persistence-and-state.md | 39 ++++ .../guides/06-implement-adapters.md | 37 ++++ .../guides/07-build-cli-and-tui.md | 30 +++ .../guides/08-verify-and-package-evidence.md | 54 ++++++ .../rust-stinger/guides/09-close-the-loop.md | 42 +++++ .claude/skills/rust-stinger/reports/README.md | 3 + .../implementation-handoff-report-template.md | 15 ++ .../2026-07-24-axum-graceful-shutdown.md | 26 +++ .../async/2026-07-24-axum-service-testing.md | 26 +++ .../async/2026-07-24-axum-streaming-body.md | 26 +++ .../2026-07-24-tokio-graceful-shutdown.md | 26 +++ .../research/async/2026-07-24-tokio-mpsc.md | 26 +++ .../async/2026-07-24-tokio-release-policy.md | 26 +++ .../2026-07-24-tokio-select-cancellation.md | 26 +++ .../async/2026-07-24-tokio-send-reserve.md | 26 +++ .../async/2026-07-24-tower-service-builder.md | 26 +++ .../2026-07-24-tower-service-readiness.md | 26 +++ .../2026-07-24-serde-container-attributes.md | 26 +++ .../2026-07-24-serde-enum-representations.md | 26 +++ .../boundaries/2026-07-24-thiserror.md | 26 +++ .../cli-tui/2026-07-24-clap-errors.md | 26 +++ .../cli-tui/2026-07-24-clap-parser.md | 26 +++ .../2026-07-24-ratatui-architecture.md | 26 +++ .../cli-tui/2026-07-24-ratatui-lifecycle.md | 26 +++ .../2026-07-24-ratatui-test-backend.md | 26 +++ .../research/evidence-synthesis.md | 178 ++++++++++++++++++ .claude/skills/rust-stinger/research/index.md | 64 +++++++ .../2026-07-24-tracing-instrument.md | 26 +++ .../2026-07-24-tracing-subscriber.md | 26 +++ .../2026-07-24-sqlite-atomic-commit.md | 26 +++ .../2026-07-24-sqlite-pragma-durability.md | 26 +++ .../2026-07-24-sqlite-transactions.md | 26 +++ .../persistence/2026-07-24-sqlite-wal.md | 26 +++ .../2026-07-24-sqlx-connect-options.md | 26 +++ .../2026-07-24-sqlx-custom-transactions.md | 26 +++ .../2026-07-24-sqlx-migrations-queries.md | 26 +++ .../rust-stinger/research/research-plan.md | 91 +++++++++ .../rust-stinger/research/research-summary.md | 68 +++++++ .../rust-cargo/2026-07-24-cargo-ci-msrv.md | 26 +++ .../rust-cargo/2026-07-24-cargo-features.md | 26 +++ .../2026-07-24-cargo-resolver-v3.md | 26 +++ .../2026-07-24-cargo-rust-version.md | 26 +++ .../rust-cargo/2026-07-24-clippy-ci.md | 26 +++ .../rust-cargo/2026-07-24-platform-support.md | 26 +++ .../2026-07-24-rust-release-1-97.md | 26 +++ .../rust-cargo/2026-07-24-unsafe-rust.md | 26 +++ .../2026-07-24-rustls-config-builder.md | 26 +++ .../2026-07-24-rustls-verification-markers.md | 26 +++ .../research/security/2026-07-24-secrecy.md | 26 +++ .../supply-chain/2026-07-24-cargo-audit.md | 26 +++ .../2026-07-24-cargo-auditable.md | 26 +++ .../2026-07-24-cargo-cyclonedx.md | 26 +++ .../2026-07-24-cargo-deny-checks.md | 26 +++ ...26-07-24-cargo-deny-license-limitations.md | 26 +++ .../2026-07-24-cargo-dist-attestations.md | 26 +++ .../2026-07-24-cargo-dist-config.md | 26 +++ .../2026-07-24-cargo-package-verification.md | 26 +++ .../2026-07-24-cargo-sbom-unstable.md | 26 +++ .../supply-chain/2026-07-24-rustsec.md | 26 +++ .../2026-07-24-sigstore-cosign-blob.md | 26 +++ .../testing/2026-07-24-criterion-analysis.md | 26 +++ .../research/testing/2026-07-24-loom.md | 26 +++ .../testing/2026-07-24-nextest-retries.md | 26 +++ .../research/testing/2026-07-24-nextest.md | 26 +++ .../testing/2026-07-24-proptest-index.md | 26 +++ .../2026-07-24-proptest-state-machines.md | 26 +++ .../testing/2026-07-24-tokio-time-testing.md | 26 +++ .../templates/acceptance-slice-checklist.md | 16 ++ .../templates/implementation-handoff.md | 53 ++++++ .../templates/release-evidence-manifest.yaml | 63 +++++++ .../templates/rust-decision-log.md | 25 +++ .codex/agents/rust-worker-bee.toml | 3 + .../skills/beekeeper-suit/PAIRING-AUDIT.md | 14 +- .../skills/beekeeper-suit/SKILL.md | 5 +- .../beekeeper-suit/guides/rust-worker-bee.md | 52 +++++ .../skills/rust-stinger/README.md | 16 ++ .../skills/rust-stinger/SKILL.md | 83 ++++++++ .../01-happy-path-bounded-service-slice.md | 66 +++++++ .../02-edge-visible-output-cancellation.md | 62 ++++++ .../03-edge-concurrent-budget-reservation.md | 49 +++++ .../04-release-evidence-with-closed-gates.md | 45 +++++ .../guides/00-authority-and-principles.md | 41 ++++ .../guides/01-inspect-workspace.md | 38 ++++ .../guides/02-design-workspace-and-types.md | 52 +++++ .../guides/03-implement-bounded-slices.md | 34 ++++ .../guides/04-prove-async-streams.md | 36 ++++ .../guides/05-prove-persistence-and-state.md | 39 ++++ .../guides/06-implement-adapters.md | 37 ++++ .../guides/07-build-cli-and-tui.md | 30 +++ .../guides/08-verify-and-package-evidence.md | 54 ++++++ .../rust-stinger/guides/09-close-the-loop.md | 42 +++++ .../skills/rust-stinger/reports/README.md | 3 + .../implementation-handoff-report-template.md | 15 ++ .../2026-07-24-axum-graceful-shutdown.md | 26 +++ .../async/2026-07-24-axum-service-testing.md | 26 +++ .../async/2026-07-24-axum-streaming-body.md | 26 +++ .../2026-07-24-tokio-graceful-shutdown.md | 26 +++ .../research/async/2026-07-24-tokio-mpsc.md | 26 +++ .../async/2026-07-24-tokio-release-policy.md | 26 +++ .../2026-07-24-tokio-select-cancellation.md | 26 +++ .../async/2026-07-24-tokio-send-reserve.md | 26 +++ .../async/2026-07-24-tower-service-builder.md | 26 +++ .../2026-07-24-tower-service-readiness.md | 26 +++ .../2026-07-24-serde-container-attributes.md | 26 +++ .../2026-07-24-serde-enum-representations.md | 26 +++ .../boundaries/2026-07-24-thiserror.md | 26 +++ .../cli-tui/2026-07-24-clap-errors.md | 26 +++ .../cli-tui/2026-07-24-clap-parser.md | 26 +++ .../2026-07-24-ratatui-architecture.md | 26 +++ .../cli-tui/2026-07-24-ratatui-lifecycle.md | 26 +++ .../2026-07-24-ratatui-test-backend.md | 26 +++ .../research/evidence-synthesis.md | 178 ++++++++++++++++++ .../skills/rust-stinger/research/index.md | 64 +++++++ .../2026-07-24-tracing-instrument.md | 26 +++ .../2026-07-24-tracing-subscriber.md | 26 +++ .../2026-07-24-sqlite-atomic-commit.md | 26 +++ .../2026-07-24-sqlite-pragma-durability.md | 26 +++ .../2026-07-24-sqlite-transactions.md | 26 +++ .../persistence/2026-07-24-sqlite-wal.md | 26 +++ .../2026-07-24-sqlx-connect-options.md | 26 +++ .../2026-07-24-sqlx-custom-transactions.md | 26 +++ .../2026-07-24-sqlx-migrations-queries.md | 26 +++ .../rust-stinger/research/research-plan.md | 91 +++++++++ .../rust-stinger/research/research-summary.md | 68 +++++++ .../rust-cargo/2026-07-24-cargo-ci-msrv.md | 26 +++ .../rust-cargo/2026-07-24-cargo-features.md | 26 +++ .../2026-07-24-cargo-resolver-v3.md | 26 +++ .../2026-07-24-cargo-rust-version.md | 26 +++ .../rust-cargo/2026-07-24-clippy-ci.md | 26 +++ .../rust-cargo/2026-07-24-platform-support.md | 26 +++ .../2026-07-24-rust-release-1-97.md | 26 +++ .../rust-cargo/2026-07-24-unsafe-rust.md | 26 +++ .../2026-07-24-rustls-config-builder.md | 26 +++ .../2026-07-24-rustls-verification-markers.md | 26 +++ .../research/security/2026-07-24-secrecy.md | 26 +++ .../supply-chain/2026-07-24-cargo-audit.md | 26 +++ .../2026-07-24-cargo-auditable.md | 26 +++ .../2026-07-24-cargo-cyclonedx.md | 26 +++ .../2026-07-24-cargo-deny-checks.md | 26 +++ ...26-07-24-cargo-deny-license-limitations.md | 26 +++ .../2026-07-24-cargo-dist-attestations.md | 26 +++ .../2026-07-24-cargo-dist-config.md | 26 +++ .../2026-07-24-cargo-package-verification.md | 26 +++ .../2026-07-24-cargo-sbom-unstable.md | 26 +++ .../supply-chain/2026-07-24-rustsec.md | 26 +++ .../2026-07-24-sigstore-cosign-blob.md | 26 +++ .../testing/2026-07-24-criterion-analysis.md | 26 +++ .../research/testing/2026-07-24-loom.md | 26 +++ .../testing/2026-07-24-nextest-retries.md | 26 +++ .../research/testing/2026-07-24-nextest.md | 26 +++ .../testing/2026-07-24-proptest-index.md | 26 +++ .../2026-07-24-proptest-state-machines.md | 26 +++ .../testing/2026-07-24-tokio-time-testing.md | 26 +++ .../templates/acceptance-slice-checklist.md | 16 ++ .../templates/implementation-handoff.md | 53 ++++++ .../templates/release-evidence-manifest.yaml | 63 +++++++ .../templates/rust-decision-log.md | 25 +++ .cursor/agents/rust-worker-bee.md | 111 +++++++++++ .../skills/beekeeper-suit/PAIRING-AUDIT.md | 14 +- .cursor/skills/beekeeper-suit/SKILL.md | 5 +- .../beekeeper-suit/guides/rust-worker-bee.md | 52 +++++ .cursor/skills/rust-stinger/README.md | 16 ++ .cursor/skills/rust-stinger/SKILL.md | 83 ++++++++ .../01-happy-path-bounded-service-slice.md | 66 +++++++ .../02-edge-visible-output-cancellation.md | 62 ++++++ .../03-edge-concurrent-budget-reservation.md | 49 +++++ .../04-release-evidence-with-closed-gates.md | 45 +++++ .../guides/00-authority-and-principles.md | 41 ++++ .../guides/01-inspect-workspace.md | 38 ++++ .../guides/02-design-workspace-and-types.md | 52 +++++ .../guides/03-implement-bounded-slices.md | 34 ++++ .../guides/04-prove-async-streams.md | 36 ++++ .../guides/05-prove-persistence-and-state.md | 39 ++++ .../guides/06-implement-adapters.md | 37 ++++ .../guides/07-build-cli-and-tui.md | 30 +++ .../guides/08-verify-and-package-evidence.md | 54 ++++++ .../rust-stinger/guides/09-close-the-loop.md | 42 +++++ .cursor/skills/rust-stinger/reports/README.md | 3 + .../implementation-handoff-report-template.md | 15 ++ .../2026-07-24-axum-graceful-shutdown.md | 26 +++ .../async/2026-07-24-axum-service-testing.md | 26 +++ .../async/2026-07-24-axum-streaming-body.md | 26 +++ .../2026-07-24-tokio-graceful-shutdown.md | 26 +++ .../research/async/2026-07-24-tokio-mpsc.md | 26 +++ .../async/2026-07-24-tokio-release-policy.md | 26 +++ .../2026-07-24-tokio-select-cancellation.md | 26 +++ .../async/2026-07-24-tokio-send-reserve.md | 26 +++ .../async/2026-07-24-tower-service-builder.md | 26 +++ .../2026-07-24-tower-service-readiness.md | 26 +++ .../2026-07-24-serde-container-attributes.md | 26 +++ .../2026-07-24-serde-enum-representations.md | 26 +++ .../boundaries/2026-07-24-thiserror.md | 26 +++ .../cli-tui/2026-07-24-clap-errors.md | 26 +++ .../cli-tui/2026-07-24-clap-parser.md | 26 +++ .../2026-07-24-ratatui-architecture.md | 26 +++ .../cli-tui/2026-07-24-ratatui-lifecycle.md | 26 +++ .../2026-07-24-ratatui-test-backend.md | 26 +++ .../research/evidence-synthesis.md | 178 ++++++++++++++++++ .cursor/skills/rust-stinger/research/index.md | 64 +++++++ .../2026-07-24-tracing-instrument.md | 26 +++ .../2026-07-24-tracing-subscriber.md | 26 +++ .../2026-07-24-sqlite-atomic-commit.md | 26 +++ .../2026-07-24-sqlite-pragma-durability.md | 26 +++ .../2026-07-24-sqlite-transactions.md | 26 +++ .../persistence/2026-07-24-sqlite-wal.md | 26 +++ .../2026-07-24-sqlx-connect-options.md | 26 +++ .../2026-07-24-sqlx-custom-transactions.md | 26 +++ .../2026-07-24-sqlx-migrations-queries.md | 26 +++ .../rust-stinger/research/research-plan.md | 91 +++++++++ .../rust-stinger/research/research-summary.md | 68 +++++++ .../rust-cargo/2026-07-24-cargo-ci-msrv.md | 26 +++ .../rust-cargo/2026-07-24-cargo-features.md | 26 +++ .../2026-07-24-cargo-resolver-v3.md | 26 +++ .../2026-07-24-cargo-rust-version.md | 26 +++ .../rust-cargo/2026-07-24-clippy-ci.md | 26 +++ .../rust-cargo/2026-07-24-platform-support.md | 26 +++ .../2026-07-24-rust-release-1-97.md | 26 +++ .../rust-cargo/2026-07-24-unsafe-rust.md | 26 +++ .../2026-07-24-rustls-config-builder.md | 26 +++ .../2026-07-24-rustls-verification-markers.md | 26 +++ .../research/security/2026-07-24-secrecy.md | 26 +++ .../supply-chain/2026-07-24-cargo-audit.md | 26 +++ .../2026-07-24-cargo-auditable.md | 26 +++ .../2026-07-24-cargo-cyclonedx.md | 26 +++ .../2026-07-24-cargo-deny-checks.md | 26 +++ ...26-07-24-cargo-deny-license-limitations.md | 26 +++ .../2026-07-24-cargo-dist-attestations.md | 26 +++ .../2026-07-24-cargo-dist-config.md | 26 +++ .../2026-07-24-cargo-package-verification.md | 26 +++ .../2026-07-24-cargo-sbom-unstable.md | 26 +++ .../supply-chain/2026-07-24-rustsec.md | 26 +++ .../2026-07-24-sigstore-cosign-blob.md | 26 +++ .../testing/2026-07-24-criterion-analysis.md | 26 +++ .../research/testing/2026-07-24-loom.md | 26 +++ .../testing/2026-07-24-nextest-retries.md | 26 +++ .../research/testing/2026-07-24-nextest.md | 26 +++ .../testing/2026-07-24-proptest-index.md | 26 +++ .../2026-07-24-proptest-state-machines.md | 26 +++ .../testing/2026-07-24-tokio-time-testing.md | 26 +++ .../templates/acceptance-slice-checklist.md | 16 ++ .../templates/implementation-handoff.md | 53 ++++++ .../templates/release-evidence-manifest.yaml | 63 +++++++ .../templates/rust-decision-log.md | 25 +++ 343 files changed, 11505 insertions(+), 28 deletions(-) create mode 100644 .agents/skills/beekeeper-suit/guides/rust-worker-bee.md create mode 100644 .agents/skills/rust-stinger/README.md create mode 100644 .agents/skills/rust-stinger/SKILL.md create mode 100644 .agents/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md create mode 100644 .agents/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md create mode 100644 .agents/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md create mode 100644 .agents/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md create mode 100644 .agents/skills/rust-stinger/guides/00-authority-and-principles.md create mode 100644 .agents/skills/rust-stinger/guides/01-inspect-workspace.md create mode 100644 .agents/skills/rust-stinger/guides/02-design-workspace-and-types.md create mode 100644 .agents/skills/rust-stinger/guides/03-implement-bounded-slices.md create mode 100644 .agents/skills/rust-stinger/guides/04-prove-async-streams.md create mode 100644 .agents/skills/rust-stinger/guides/05-prove-persistence-and-state.md create mode 100644 .agents/skills/rust-stinger/guides/06-implement-adapters.md create mode 100644 .agents/skills/rust-stinger/guides/07-build-cli-and-tui.md create mode 100644 .agents/skills/rust-stinger/guides/08-verify-and-package-evidence.md create mode 100644 .agents/skills/rust-stinger/guides/09-close-the-loop.md create mode 100644 .agents/skills/rust-stinger/reports/README.md create mode 100644 .agents/skills/rust-stinger/reports/implementation-handoff-report-template.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md create mode 100644 .agents/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md create mode 100644 .agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md create mode 100644 .agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md create mode 100644 .agents/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md create mode 100644 .agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md create mode 100644 .agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md create mode 100644 .agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md create mode 100644 .agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md create mode 100644 .agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md create mode 100644 .agents/skills/rust-stinger/research/evidence-synthesis.md create mode 100644 .agents/skills/rust-stinger/research/index.md create mode 100644 .agents/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md create mode 100644 .agents/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md create mode 100644 .agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md create mode 100644 .agents/skills/rust-stinger/research/research-plan.md create mode 100644 .agents/skills/rust-stinger/research/research-summary.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md create mode 100644 .agents/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md create mode 100644 .agents/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md create mode 100644 .agents/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md create mode 100644 .agents/skills/rust-stinger/research/security/2026-07-24-secrecy.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md create mode 100644 .agents/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-loom.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-nextest.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md create mode 100644 .agents/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md create mode 100644 .agents/skills/rust-stinger/templates/acceptance-slice-checklist.md create mode 100644 .agents/skills/rust-stinger/templates/implementation-handoff.md create mode 100644 .agents/skills/rust-stinger/templates/release-evidence-manifest.yaml create mode 100644 .agents/skills/rust-stinger/templates/rust-decision-log.md create mode 100644 .claude/agents/rust-worker-bee.md create mode 100644 .claude/skills/beekeeper-suit/guides/rust-worker-bee.md create mode 100644 .claude/skills/rust-stinger/README.md create mode 100644 .claude/skills/rust-stinger/SKILL.md create mode 100644 .claude/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md create mode 100644 .claude/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md create mode 100644 .claude/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md create mode 100644 .claude/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md create mode 100644 .claude/skills/rust-stinger/guides/00-authority-and-principles.md create mode 100644 .claude/skills/rust-stinger/guides/01-inspect-workspace.md create mode 100644 .claude/skills/rust-stinger/guides/02-design-workspace-and-types.md create mode 100644 .claude/skills/rust-stinger/guides/03-implement-bounded-slices.md create mode 100644 .claude/skills/rust-stinger/guides/04-prove-async-streams.md create mode 100644 .claude/skills/rust-stinger/guides/05-prove-persistence-and-state.md create mode 100644 .claude/skills/rust-stinger/guides/06-implement-adapters.md create mode 100644 .claude/skills/rust-stinger/guides/07-build-cli-and-tui.md create mode 100644 .claude/skills/rust-stinger/guides/08-verify-and-package-evidence.md create mode 100644 .claude/skills/rust-stinger/guides/09-close-the-loop.md create mode 100644 .claude/skills/rust-stinger/reports/README.md create mode 100644 .claude/skills/rust-stinger/reports/implementation-handoff-report-template.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md create mode 100644 .claude/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md create mode 100644 .claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md create mode 100644 .claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md create mode 100644 .claude/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md create mode 100644 .claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md create mode 100644 .claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md create mode 100644 .claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md create mode 100644 .claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md create mode 100644 .claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md create mode 100644 .claude/skills/rust-stinger/research/evidence-synthesis.md create mode 100644 .claude/skills/rust-stinger/research/index.md create mode 100644 .claude/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md create mode 100644 .claude/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md create mode 100644 .claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md create mode 100644 .claude/skills/rust-stinger/research/research-plan.md create mode 100644 .claude/skills/rust-stinger/research/research-summary.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md create mode 100644 .claude/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md create mode 100644 .claude/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md create mode 100644 .claude/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md create mode 100644 .claude/skills/rust-stinger/research/security/2026-07-24-secrecy.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md create mode 100644 .claude/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-loom.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-nextest.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md create mode 100644 .claude/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md create mode 100644 .claude/skills/rust-stinger/templates/acceptance-slice-checklist.md create mode 100644 .claude/skills/rust-stinger/templates/implementation-handoff.md create mode 100644 .claude/skills/rust-stinger/templates/release-evidence-manifest.yaml create mode 100644 .claude/skills/rust-stinger/templates/rust-decision-log.md create mode 100644 .codex/agents/rust-worker-bee.toml create mode 100644 .codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/rust-worker-bee.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/README.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/SKILL.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/00-authority-and-principles.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/01-inspect-workspace.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/02-design-workspace-and-types.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/03-implement-bounded-slices.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/04-prove-async-streams.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/05-prove-persistence-and-state.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/06-implement-adapters.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/07-build-cli-and-tui.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/08-verify-and-package-evidence.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/09-close-the-loop.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/README.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/implementation-handoff-report-template.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/evidence-synthesis.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/index.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-plan.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-summary.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-secrecy.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-loom.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/acceptance-slice-checklist.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/implementation-handoff.md create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/release-evidence-manifest.yaml create mode 100644 .codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/rust-decision-log.md create mode 100644 .cursor/agents/rust-worker-bee.md create mode 100644 .cursor/skills/beekeeper-suit/guides/rust-worker-bee.md create mode 100644 .cursor/skills/rust-stinger/README.md create mode 100644 .cursor/skills/rust-stinger/SKILL.md create mode 100644 .cursor/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md create mode 100644 .cursor/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md create mode 100644 .cursor/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md create mode 100644 .cursor/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md create mode 100644 .cursor/skills/rust-stinger/guides/00-authority-and-principles.md create mode 100644 .cursor/skills/rust-stinger/guides/01-inspect-workspace.md create mode 100644 .cursor/skills/rust-stinger/guides/02-design-workspace-and-types.md create mode 100644 .cursor/skills/rust-stinger/guides/03-implement-bounded-slices.md create mode 100644 .cursor/skills/rust-stinger/guides/04-prove-async-streams.md create mode 100644 .cursor/skills/rust-stinger/guides/05-prove-persistence-and-state.md create mode 100644 .cursor/skills/rust-stinger/guides/06-implement-adapters.md create mode 100644 .cursor/skills/rust-stinger/guides/07-build-cli-and-tui.md create mode 100644 .cursor/skills/rust-stinger/guides/08-verify-and-package-evidence.md create mode 100644 .cursor/skills/rust-stinger/guides/09-close-the-loop.md create mode 100644 .cursor/skills/rust-stinger/reports/README.md create mode 100644 .cursor/skills/rust-stinger/reports/implementation-handoff-report-template.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md create mode 100644 .cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md create mode 100644 .cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md create mode 100644 .cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md create mode 100644 .cursor/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md create mode 100644 .cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md create mode 100644 .cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md create mode 100644 .cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md create mode 100644 .cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md create mode 100644 .cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md create mode 100644 .cursor/skills/rust-stinger/research/evidence-synthesis.md create mode 100644 .cursor/skills/rust-stinger/research/index.md create mode 100644 .cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md create mode 100644 .cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md create mode 100644 .cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md create mode 100644 .cursor/skills/rust-stinger/research/research-plan.md create mode 100644 .cursor/skills/rust-stinger/research/research-summary.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md create mode 100644 .cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md create mode 100644 .cursor/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md create mode 100644 .cursor/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md create mode 100644 .cursor/skills/rust-stinger/research/security/2026-07-24-secrecy.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md create mode 100644 .cursor/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-loom.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-nextest.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md create mode 100644 .cursor/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md create mode 100644 .cursor/skills/rust-stinger/templates/acceptance-slice-checklist.md create mode 100644 .cursor/skills/rust-stinger/templates/implementation-handoff.md create mode 100644 .cursor/skills/rust-stinger/templates/release-evidence-manifest.yaml create mode 100644 .cursor/skills/rust-stinger/templates/rust-decision-log.md diff --git a/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md b/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..bfdae086 100644 --- a/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,20 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`rust-worker-bee` / `rust-stinger` was ported in from a prior fork and registered here: Rust implementation and code review for Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, tests, and local packaging evidence. ## Path integrity @@ -41,7 +45,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.agents/skills/beekeeper-suit/SKILL.md b/.agents/skills/beekeeper-suit/SKILL.md index c4fb309f..bc45542d 100644 --- a/.agents/skills/beekeeper-suit/SKILL.md +++ b/.agents/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,6 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | +| `rust-worker-bee` | Rust implementation and code review for production Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence | "implement this in Rust", "review this Cargo workspace", "fix this Tokio or SQLx service", "audit this SQLx transaction", "build the approved Rust PRD slice" | `rust-stinger` | | `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | @@ -251,7 +252,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.agents/skills/beekeeper-suit/guides/rust-worker-bee.md b/.agents/skills/beekeeper-suit/guides/rust-worker-bee.md new file mode 100644 index 00000000..7c2e21ad --- /dev/null +++ b/.agents/skills/beekeeper-suit/guides/rust-worker-bee.md @@ -0,0 +1,52 @@ +# rust-worker-bee + +## Domain +This Bee owns bounded implementation and code review for production Rust systems. It handles Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, decide dependency or release policy, issue final Quality acceptance, or authorize external effects. + +## Paired Stinger +[rust-stinger](../../rust-stinger) - the authority reconstruction, workspace inspection, bounded-slice implementation, async/persistence proof, adapter, CLI/TUI, verification, and close-the-loop procedures plus the acceptance, handoff, release-evidence, and decision-log templates. + +## Trigger phrases +- "Implement this in Rust." +- "Review this Cargo workspace." +- "Fix this Tokio or SQLx service." +- "Audit this SQLx transaction." +- "Build the approved Rust PRD slice." + +Also route proactively when a requested change or review touches Rust source, Cargo manifests or workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, or local Rust packaging evidence. + +## Do NOT route when +- The ask is HTTP/REST or MCP semantic and compatibility decisions: that is `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`; Rust implements their approved contracts. +- The ask is product, model, and provider policy: that is `ai-tools-platform-worker-bee` or the named product owner. +- The ask is schema architecture: that is `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- The ask is Security acceptance: that is `security-worker-bee`. +- The ask is dependency/license/advisory disposition: that is `dependency-audit-worker-bee`. +- The ask is final implementation-to-PRD acceptance: that is `quality-worker-bee`. +- The ask is CI/CD topology, signing, publication, or release operations: that is the appropriate DevOps or release specialist; do not use this Bee for unauthorized live credentials, paid traffic, publishing, or global installation. + +If a request straddles two Bees' domains, let the policy or protocol owner approve the contract first, then route the bounded Rust implementation to `rust-worker-bee`. + +## Inputs the Bee needs +- The exact repository or worktree, owned paths, branch/change boundary, and concurrent-work constraints. +- The authorizing PRD, ADR, ledger rows, acceptance criteria, gates, and repository instructions. +- The current Cargo graph, Rust source, features and targets, migrations, tests, and release configuration. +- Approved protocol, provider, persistence, security, CLI, platform, and operational contracts, including data-integrity and cancellation requirements. +- The required verification commands and explicit authorization for any external effect. + +If a missing input controls safety, public compatibility, money, credentials, signing, publication, or destructive behavior, invoke only to record the fail-closed blocker and smallest safe checkpoint; do not ask the Bee to guess. + +## Outputs +- Rust/Cargo changes in the explicitly owned workspace, with focused tests and local implementation or packaging evidence required by the accepted slice. +- An acceptance-linked Rust implementation handoff using `templates/implementation-handoff.md`, including changed paths, exact verification commands and results, safety evidence, rollback/recovery notes, and remaining gates. +- When release evidence is explicitly in scope, a populated local `templates/release-evidence-manifest.yaml`; signing and publication remain closed unless separately authorized. +- A precise blocker record instead of a completion claim when an owning decision, tool, gate, or required proof is missing. + +## Commonly sequenced with +- Plan execution loop: `rust-worker-bee` is the implementation Bee for Rust/Cargo work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Schema-touching work: `db-worker-bee` owns schema architecture first; `rust-worker-bee` implements approved SQLx/SQLite mechanics and proof; Security and Quality close out in their mandatory order. +- Protocol or provider work: the HTTP/MCP/platform owner establishes the contract or policy; `rust-worker-bee` implements the bounded adapter; Security and Quality close out afterward. + +## Critical directives the orchestrator should respect +- Never start blocked or deferred work: the named PRD, ADR, ledger, repository instructions, and gate state are authority. +- Keep harness agency and external effects fail-closed while requiring provable bounded concurrency, cancellation/replay behavior, transactions, crash recovery, redaction, and a default of no `unsafe`; no live credentials, paid traffic, global installation, signing, publication, or auto-update execution without explicit authorization. +- Preserve the verification order: implementation checks, Security, affected-check reruns, then Quality; partial or stale evidence is not shipped evidence. diff --git a/.agents/skills/rust-stinger/README.md b/.agents/skills/rust-stinger/README.md new file mode 100644 index 00000000..2498a96f --- /dev/null +++ b/.agents/skills/rust-stinger/README.md @@ -0,0 +1,16 @@ +# Rust Stinger + +Rust Stinger equips `rust-worker-bee` to implement and review production Cargo workspaces, async services, durable local state, operator surfaces, tests, and release evidence. It operationalizes the approved Command Brief while preserving protocol, Security, dependency, release, and Quality peer ownership. Its technical rules are traceable to [`research/research-summary.md`](research/research-summary.md) and the underlying primary-source notes. + +## Layout + +- `SKILL.md` — trigger, procedure, directives, outputs, and decision boundaries. +- `guides/` — numbered procedures matching every Command Brief action. +- `examples/` — worked happy-path and failure-boundary handoffs. +- `templates/` — reusable implementation, decision, and release-evidence stubs. +- `reports/` — report-shape template and future run archive. +- `research/` — immutable scripture-historian evidence packet. + +## Maintenance + +Update the research packet before changing version-sensitive guidance. The current packet marks Rust/Cargo, Tokio, SQLx, rustls, cargo-dist, platform support, and RustSec as explicit revalidation points; current-at-retrieval values are evidence snapshots, not defaults. diff --git a/.agents/skills/rust-stinger/SKILL.md b/.agents/skills/rust-stinger/SKILL.md new file mode 100644 index 00000000..8c2d427b --- /dev/null +++ b/.agents/skills/rust-stinger/SKILL.md @@ -0,0 +1,83 @@ +--- +name: "rust-stinger" +description: "Implements and reviews production Rust systems across Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui operator surfaces, tests, and release evidence. Use when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or invokes rust-worker-bee. Do not use it to invent protocol semantics, approve security or dependency policy, author the final Quality report, or publish a release." +license: MIT +--- + +# Rust Stinger + +Equip `rust-worker-bee` to own bounded Rust implementation while preserving the authority of the exact PRD, ADR, ledger, and peer specialists. Make async ownership, durability, state transitions, redaction, and release evidence mechanically reviewable. Stop at a recorded fail-closed boundary whenever a missing decision affects safety, compatibility, money, credentials, signing, publication, or another external effect. + +## Required inputs + +Before editing, obtain: + +- the exact repository or worktree, owned paths, and concurrent-work boundaries; +- the authorizing PRD/ADR/ledger rows, acceptance criteria, gates, and repository instructions; +- the existing Cargo graph, toolchain files, feature/target matrix, migrations, code, tests, and release configuration; +- approved protocol, provider, persistence, security, CLI, platform, and operational contracts; +- the required verification commands and explicit authorization for any external effect. + +If a missing input determines safety, public compatibility, monetary behavior, credentials, publication, or destructive behavior, return a blocker rather than choosing silently. + +## Procedure + +1. Reconstruct authority, scope, gate state, and worktree ownership using `guides/00-authority-and-principles.md`. +2. Inventory the Rust system and record revalidation points using `guides/01-inspect-workspace.md`. +3. Establish the smallest coherent crate, feature, type, and error design using `guides/02-design-workspace-and-types.md`. +4. Implement a test-first acceptance slice using `guides/03-implement-bounded-slices.md`. +5. Prove task, cancellation, stream, backpressure, timeout, retry, and shutdown behavior using `guides/04-prove-async-streams.md`. +6. Prove SQLite/SQLx transactions, migrations, crash recovery, and typed state transitions using `guides/05-prove-persistence-and-state.md`. +7. Implement provider and harness edges only behind approved contracts using `guides/06-implement-adapters.md`. +8. Build scriptable CLI and optional TUI surfaces using `guides/07-build-cli-and-tui.md`. +9. Run the complete owned verification and generate release evidence without publishing using `guides/08-verify-and-package-evidence.md`. +10. Produce the acceptance-linked handoff, route Security before Quality, and leave unresolved gates explicit using `guides/09-close-the-loop.md`. + +## Critical directives + +- Treat the named PRD, ADR, ledger, gate state, and repository instructions as authority. Never start blocked or deferred work. +- Keep provider code subordinate to the host harness: it may route inference but never acquire tools, approvals, repository access, memory, or user interaction. +- Default to bounded queues, explicit task owners, operation-level cancellation review, and no transparent replay after visible output or a harness-visible tool call. +- Put monetary/quota checks, reservations, reconciliation, idempotency, and aggregate updates in explicit transactions with concurrency and crash evidence. +- Keep credentials in approved secret references and start sensitive instrumentation with `skip_all`; allowlist only non-sensitive correlation and state fields. +- Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Enforce approved egress allowlists and never bypass redirect, DNS, or SSRF checks. +- Default to no `unsafe`. Any exception needs a minimal scope, written invariant, targeted tests, and independent review. +- Use fake providers and fixtures by default. Do not use live credentials, paid traffic, subscriptions, signing identities, publishing, auto-update, Git initialization, or destructive controls without explicit authorization. +- Never promote retrieval-time crate/tool versions, OS targets, durability settings, timeout values, signing systems, or soak thresholds into timeless defaults. Revalidate them at the decision point. +- Preserve peer authority: protocol semantics, product/provider policy, security acceptance, schema review, dependency/license disposition, CI topology, signing/publication, and final PRD Quality remain separate handoffs. +- Preserve verification order: implementation checks, Security, affected-check reruns, then Quality. Partial or stale evidence is not shipped evidence. + +See `guides/00-authority-and-principles.md` for the rationale and fail-closed decision table. + +## Output contract + +Produce a Rust implementation handoff from `templates/implementation-handoff.md`, backed by exact commands and artifacts. When release work is in scope, also populate `templates/release-evidence-manifest.yaml` without signing or publishing unless independently authorized. Past execution reports belong in `reports/`; see `reports/README.md`. + +## Examples + +- `examples/01-happy-path-bounded-service-slice.md` — Cargo/Axum/SQLx acceptance slice with deterministic evidence. +- `examples/02-edge-visible-output-cancellation.md` — cancellation after visible output, where replay must remain disabled. +- `examples/03-edge-concurrent-budget-reservation.md` — concurrent SQLite reservation and crash boundary. +- `examples/04-release-evidence-with-closed-gates.md` — package evidence generation with signing/publication held closed. + +## Research and refresh points + +Read `research/research-summary.md` and `research/evidence-synthesis.md` before making architecture or version-sensitive claims. Use `research/index.md` to locate primary notes. Re-fetch the Rust release/platform matrix, Tokio support policy, the selected SQLx transaction API, stable rustls APIs, cargo-dist behavior, and RustSec data at the point of use; the research packet records a 2026-07-24 snapshot, not permanent defaults. + +## Human decisions that remain open + +Do not resolve these from the Stinger alone: + +- supported OS/architecture/install matrix and minimum OS baselines; +- actual MSRV after the resolved graph and public features exist; +- SQLite power-loss durability and contended-writer behavior; +- durable replay/promotion event schema; +- first-milestone TUI scope; +- signing identity, attestation platform, installer formats, and publication authorization; +- quantitative soak pass/fail thresholds. + +Record the missing owner/decision, affected acceptance criteria, and first authorized next action in the handoff. + +## Paired owner + +This Stinger is paired with `rust-worker-bee`. diff --git a/.agents/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md b/.agents/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md new file mode 100644 index 00000000..e38c5359 --- /dev/null +++ b/.agents/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md @@ -0,0 +1,66 @@ +# Example 01 — Happy path: bounded service slice + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [verification](../guides/08-verify-and-package-evidence.md). + +## Input + +```text +Repo: /work/router +Owned paths: crates/router-daemon/**, crates/provider-fake/**, tests/stream_contract.rs +AC ROUTE-12: At most 16 in-flight requests; provider chunks preserve order; shutdown drains accepted turns in 2 seconds. +Gates: fake provider only; HTTP error schema already approved; no live credentials. +``` + +## Implementation pattern + +```rust +use tokio::sync::{mpsc, Semaphore}; +use tokio_util::sync::CancellationToken; + +struct RuntimeOwner { + cancel: CancellationToken, + capacity: std::sync::Arc, + queue: mpsc::Sender, +} + +impl RuntimeOwner { + async fn submit(&self, turn: Turn) -> Result<(), SubmitError> { + let permit = self.queue.reserve().await.map_err(|_| SubmitError::Stopping)?; + permit.send(turn); + Ok(()) + } +} +``` + +The bounded queue and reservation-before-send pattern follows Tokio's documented backpressure and cancellation behavior ([bounded MPSC](../research/async/2026-07-24-tokio-mpsc.md), [`reserve`](../research/async/2026-07-24-tokio-send-reserve.md)). The implementation also owns listener shutdown separately from joined background work ([Axum shutdown](../research/async/2026-07-24-axum-graceful-shutdown.md), [Tokio shutdown](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Focused proof + +```bash +cargo test -p router-daemon --test stream_contract bounded_admission +cargo test -p router-daemon --test stream_contract preserves_chunk_order +cargo test -p router-daemon --test shutdown drains_accepted_turns +cargo clippy -p router-daemon -p provider-fake --all-targets -- -D warnings +``` + +The contract test calls the Axum Router as a Tower service; a separate loopback test proves bind and shutdown ([research](../research/async/2026-07-24-axum-service-testing.md)). + +## Output + +```markdown +# Rust implementation handoff: ROUTE-12 bounded fake-provider route + +## Outcome +The fake-provider route admits no more than 16 concurrent turns, preserves chunk order, and drains accepted work during bounded shutdown. + +## Acceptance evidence +- ROUTE-12: three focused tests PASS; no live provider or credential path executed. + +## Safety and operations +- External effects used: none +- Shutdown: listener admission stops, root token cancels workers, owner joins tracked tasks. + +## Peer handoffs and remaining gates +- Security: ready for redaction and shutdown review. +- Quality: wait until Security and affected-check reruns complete. +``` diff --git a/.agents/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md b/.agents/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md new file mode 100644 index 00000000..b3454f06 --- /dev/null +++ b/.agents/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md @@ -0,0 +1,62 @@ +# Example 02 — Edge case: cancellation after visible output + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async/replay proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC REPLAY-07: A provider disconnect before output may be retried once. After any visible chunk or harness-visible tool call, the turn must never be replayed automatically. +Fixture: provider emits chunk seq=0, then disconnects. +``` + +## State pattern + +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Visibility { + None, + OutputSeen, + ToolCallSeen, +} + +enum Recovery { + ReplayEligible(NoVisibleEffect), + ResumeRequired { correlation_id: CorrelationId }, +} + +fn classify(trace: &TurnTrace) -> Recovery { + match trace.visibility { + Visibility::None => Recovery::ReplayEligible(NoVisibleEffect::new_private()), + Visibility::OutputSeen | Visibility::ToolCallSeen => Recovery::ResumeRequired { + correlation_id: trace.correlation_id, + }, + } +} +``` + +Keep the proof-token constructor private so callers cannot manufacture replay eligibility; rustls uses private verification markers for the same omitted-check defense ([research](../research/security/2026-07-24-rustls-verification-markers.md)). Use an explicit tagged durable representation rather than an ambiguous untagged enum ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). + +## Failure-focused proof + +```bash +cargo test -p router-core replay_before_output_is_single_use +cargo test -p provider-fake disconnect_after_first_chunk_disables_replay +cargo test -p provider-fake tool_call_visibility_disables_replay +cargo test -p router-daemon dropped_body_cancels_upstream_and_releases_permit +``` + +The last test matters because an Axum body is pull-driven and only preserves the desired backpressure if upstream production stops on disconnect ([research](../research/async/2026-07-24-axum-streaming-body.md)). Each selected future is reviewed individually because Tokio cancellation safety is operation-specific ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). + +## Output + +```markdown +## Outcome +Disconnect before visibility consumes one replay proof; disconnect after seq=0 returns `resume_required` and does not create a second provider request. + +## Acceptance evidence +- REPLAY-07: four focused tests PASS; fake request count remains 1 after visible output. + +## Safety and operations +- External effects used: none +- Recovery: correlation and last visible sequence persist; automatic replay remains disabled. +``` diff --git a/.agents/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md b/.agents/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md new file mode 100644 index 00000000..01e90549 --- /dev/null +++ b/.agents/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md @@ -0,0 +1,49 @@ +# Example 03 — Edge case: concurrent budget reservation + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded slices](../guides/03-implement-bounded-slices.md), [persistence/state proof](../guides/05-prove-persistence-and-state.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC BUDGET-09: Two processes racing for the last $0.10 cannot reserve more than the account balance. Duplicate idempotency keys return the original reservation. Crash before commit leaves no partial reservation. +Approved decision: BEGIN IMMEDIATE; durability PRAGMA remains separately gated. +``` + +## Transaction pattern + +```sql +UPDATE budget +SET reserved_microunits = reserved_microunits + ?1 +WHERE account_id = ?2 + AND limit_microunits - spent_microunits - reserved_microunits >= ?1 +RETURNING reserved_microunits; +``` + +Run the eligibility check, conditional update, reservation row, and idempotency record inside one tracked write transaction. SQLite permits one writer and `BEGIN IMMEDIATE` acquires write intent before the read/modify/write sequence ([research](../research/persistence/2026-07-24-sqlite-transactions.md)); SQLx 0.9 documents `begin_with`, but the selected version must be revalidated before using that API ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). + +## Failure-focused proof + +```bash +cargo test -p router-state concurrent_last_balance_has_one_winner +cargo test -p router-state duplicate_idempotency_key_returns_same_reservation +cargo test -p router-state kill_before_commit_recovers_all_or_none +cargo test -p router-state busy_timeout_returns_structured_contention +``` + +Use two real SQLite connections/processes; a process-local lock is not sufficient. Preserve database and WAL/SHM/journal companions in the crash fixture because recovery semantics depend on them ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). + +## Output + +```markdown +## Outcome +Exactly one racing process reserves the final balance; duplicate requests are idempotent; pre-commit crash recovery is all-or-none. + +## Acceptance evidence +- BUDGET-09: 100 deterministic race iterations PASS with exactly one winner; crash fixture PASS. + +## Peer handoffs and remaining gates +- Database: review schema/index and contention policy. +- Security: review account identifier handling and error redaction. +- Quality: wait until Security and reruns complete. +- Open: product owner must approve power-loss durability and busy UX before support claim. +``` diff --git a/.agents/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md b/.agents/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md new file mode 100644 index 00000000..57ea49d3 --- /dev/null +++ b/.agents/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md @@ -0,0 +1,45 @@ +# Example 04 — Release evidence with signing and publication closed + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [CLI/TUI boundary](../guides/07-build-cli-and-tui.md), [verification/release evidence](../guides/08-verify-and-package-evidence.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC RELEASE-04: Produce local macOS ARM64 package evidence and an uninstall transcript. +Not authorized: signing, attestation, GitHub release, registry publication, installer execution outside a temp prefix. +Open: final multi-platform matrix and signing identity. +``` + +## Local-only evidence commands + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo nextest run --profile release +cargo test --workspace --doc +cargo package --workspace +``` + +Then run the repository's pinned local package generator into a staging directory, calculate hashes, generate the approved SBOM/advisory/license reports, and install/uninstall only inside an isolated temporary prefix. `cargo package` verifies package contents/buildability but not provenance ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)); cargo-dist checksums are integrity evidence but are not signed proof ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). + +Do not invoke Cosign or a public release workflow: blob signing can create OIDC identity and transparency-log records ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). Re-run RustSec immediately at release time because advisory results are time-dependent ([research](../research/supply-chain/2026-07-24-rustsec.md)). + +## Output + +```markdown +## Outcome +Unsigned macOS ARM64 staging artifacts, hashes, SBOM, scans, and isolated install/uninstall transcript were generated locally. + +## Verification +- `cargo nextest run --profile release` — PASS +- `cargo test --workspace --doc` — PASS +- local staging install/uninstall — PASS +- signing — BLOCKED (no identity/authorization) +- publication — BLOCKED (no authorization) + +## Peer handoffs and remaining gates +- Dependency/license: review SBOM and scan dispositions. +- Release/Security: select signing identity and verify provenance policy. +- Quality: after Security and affected reruns. +- Platform: no support claim beyond the locally exercised target. +``` diff --git a/.agents/skills/rust-stinger/guides/00-authority-and-principles.md b/.agents/skills/rust-stinger/guides/00-authority-and-principles.md new file mode 100644 index 00000000..bf7946e2 --- /dev/null +++ b/.agents/skills/rust-stinger/guides/00-authority-and-principles.md @@ -0,0 +1,41 @@ +# 00 — Authority and principles + +## Purpose + +Reconstruct why the change is authorized, which paths are owned, which gates are open, and where Rust implementation authority ends. This guide covers Command Brief action 1 and every critical directive. + +## Procedure + +1. Read the repository instructions, exact PRD/sub-PRD, ADRs, execution ledger, acceptance criteria, and current Security/Quality evidence before source code. +2. Inspect `git status`, active branch/worktree, and owned paths. Treat unrelated or concurrent edits as user work. +3. Build a scope table with columns `AC`, `owned path`, `gate`, `proof`, and `peer handoff`. +4. Mark any blocked or deferred slice `BLOCKED`; do not prepare implementation behind it. +5. Record each decision that cannot be made locally: protocol semantics, provider/product policy, threat acceptance, schema policy, dependency/license exceptions, CI topology, signing, publication, or final Quality. +6. Confirm that all external effects are either `none` or separately authorized. + +## Fail-closed decision table + +| Missing fact | Required response | +|---|---| +| Safety or egress boundary | Stop and hand to Security/platform owner. | +| Public protocol meaning | Stop and hand to protocol owner. | +| Live credentials, paid traffic, or subscription use | Keep fake/fixture route only. | +| Destructive/billable CLI policy | Keep command disabled. | +| Signing, publication, installer execution, or auto-update | Generate local evidence only. | +| Target matrix, MSRV, durability, or soak threshold | Record a revalidation/TODO decision; do not declare support. | + +## Non-negotiable implementation posture + +- Use typed, explicit state at boundaries. Serde ignores unknown fields by default, so strict local control/config inputs need an intentional rejection or validated-conversion policy ([research](../research/boundaries/2026-07-24-serde-container-attributes.md)). +- Treat cancellation safety as a property of each awaited operation, not of async code generally ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +- Default sensitive instrumentation to `skip_all` because `#[instrument]` otherwise records function arguments ([research](../research/observability/2026-07-24-tracing-instrument.md)). +- Default to safe Rust and isolate any `unsafe` proof obligation behind the smallest safe abstraction ([research](../research/rust-cargo/2026-07-24-unsafe-rust.md)). +- Never equate a passing license/advisory tool with final legal or security acceptance; cargo-deny itself documents limits to license discovery ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Gate exit + +Proceed only when the assigned slice has authority, owned paths, acceptance proof, and peer handoffs. Otherwise populate `templates/implementation-handoff.md` as a precise blocker. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.agents/skills/rust-stinger/guides/01-inspect-workspace.md b/.agents/skills/rust-stinger/guides/01-inspect-workspace.md new file mode 100644 index 00000000..c389e466 --- /dev/null +++ b/.agents/skills/rust-stinger/guides/01-inspect-workspace.md @@ -0,0 +1,38 @@ +# 01 — Inspect the Rust workspace + +## Purpose + +Inventory the current workspace before changing it. This guide covers Command Brief action 2. + +## Inventory commands + +Run only commands supported by the repository, and record unavailable tools as blockers rather than installing them implicitly. + +```bash +git status --short --branch +cargo metadata --format-version 1 --no-deps +cargo tree --workspace -e features +cargo tree --workspace -e normal,build,dev +cargo test --workspace --no-run +``` + +Also inspect `Cargo.toml`, `Cargo.lock`, `rust-toolchain*`, `.cargo/config*`, `build.rs`, migrations, release profiles, `deny.toml`, nextest configuration, and CI/release manifests. + +## Inspection checklist + +- Draw the crate dependency direction and identify public type owners. +- Record workspace edition, resolver, toolchain pin, declared `rust-version`, default features, optional providers/TUI, targets, and binary entry points. +- Find all `unsafe`, panic/unwrap/expect paths in daemon/adapter/state/migration boundaries, global mutable state, spawned tasks, channels, `select!`, retries, time access, raw SQL, logging macros, secret exposure, TLS customization, and migrations. +- Locate every task owner and shutdown join path; Axum listener shutdown does not join arbitrary background tasks ([research](../research/async/2026-07-24-axum-graceful-shutdown.md)). +- Locate every bounded and unbounded queue; bounded Tokio MPSC expresses backpressure while unbounded channels do not encode a memory limit ([research](../research/async/2026-07-24-tokio-mpsc.md)). +- Verify effective SQLite journal, synchronous, foreign-key, busy-timeout, and checkpoint policy; SQLx does not select a journal mode by default ([research](../research/persistence/2026-07-24-sqlx-connect-options.md)). +- Separate current stable from declared MSRV. Cargo's `rust-version` participates in resolution but still needs CI proof across advertised features ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- Treat compiler target tiers as compiler guarantees, not product install/runtime proof ([research](../research/rust-cargo/2026-07-24-platform-support.md)). + +## Revalidation record + +Create or update `templates/rust-decision-log.md` for values likely to drift: toolchain, MSRV, target matrix, Tokio line, SQLx API, rustls stable API, package generator, and advisory snapshot. Do not copy current-at-retrieval numbers from research without rechecking. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.agents/skills/rust-stinger/guides/02-design-workspace-and-types.md b/.agents/skills/rust-stinger/guides/02-design-workspace-and-types.md new file mode 100644 index 00000000..140625db --- /dev/null +++ b/.agents/skills/rust-stinger/guides/02-design-workspace-and-types.md @@ -0,0 +1,52 @@ +# 02 — Design workspace and types + +## Purpose + +Establish the smallest coherent design without inventing peer-owned semantics. This guide covers Command Brief action 3. + +## Workspace rules + +1. Keep one owner per invariant; do not create a crate per noun. +2. Keep protocol/domain types inward, policy/state above them, provider adapters at edges, daemon/control as composition, and CLI/TUI as clients. +3. Keep test-support out of production dependency paths. +4. Declare `resolver = "3"` explicitly in a virtual Rust 2024 workspace; resolver choice is global, and version 3 is the Rust 2024 default ([research](../research/rust-cargo/2026-07-24-cargo-resolver-v3.md)). +5. Keep features additive, inspect feature unification, and make optional providers/TUI default-off unless the product contract requires otherwise ([research](../research/rust-cargo/2026-07-24-cargo-features.md)). +6. Centralize shared dependency versions/features only when it reduces drift without making edge features leak inward. + +## Typed boundary rules + +- Convert edge DTOs into validated domain newtypes before use. +- Prefer explicit tagged enums for durable safety state; untagged Serde enums try variants in order and can be ambiguous ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). +- Use private constructors and consumable marker/capability values for completed checks such as `NoVisibleOutput`, `ReservationHeld`, or `SafeTurnReviewed`. rustls uses non-constructible verification markers to prevent omitted-check control flow ([research](../research/security/2026-07-24-rustls-verification-markers.md)). +- Keep provider and harness SDK types in edge crates; normalize into protocol-neutral facts. +- Use structured errors with redacted public display and preserved internal sources; `thiserror` supports opaque public wrappers and causal chains, but redaction still depends on selected fields ([research](../research/boundaries/2026-07-24-thiserror.md)). + +## Minimal typestate pattern + +```rust +pub struct NoVisibleOutput(()); + +impl NoVisibleOutput { + fn after_preflight(trace: &TurnTrace) -> Option { + (!trace.visible_output && !trace.tool_call).then_some(Self(())) + } +} + +pub fn authorize_replay(proof: NoVisibleOutput) -> ReplayAuthorized { + let _consumed = proof; + ReplayAuthorized +} +``` + +Keep constructors private to the state-owning crate. Persist the underlying facts and rebuild proof only through the validated transition path. + +## Architecture test ideas + +- Compile-fail tests for private marker construction. +- Feature-matrix builds proving core crates do not acquire provider/TUI dependencies. +- Public API inspection confirming no harness/provider SDK types cross inward. +- `forbid(unsafe_code)` at crate roots where dependencies allow it; otherwise maintain an explicit inventory. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.agents/skills/rust-stinger/guides/03-implement-bounded-slices.md b/.agents/skills/rust-stinger/guides/03-implement-bounded-slices.md new file mode 100644 index 00000000..f793433b --- /dev/null +++ b/.agents/skills/rust-stinger/guides/03-implement-bounded-slices.md @@ -0,0 +1,34 @@ +# 03 — Implement bounded acceptance slices + +## Purpose + +Implement test-first, acceptance-linked changes while preserving concurrent work. This guide covers Command Brief action 4. + +## Slice loop + +1. Select one acceptance criterion whose dependencies and gates are open. +2. Name the observable outcome, owned files, and fastest focused proof. +3. Add a failing unit, contract, property, migration, concurrency, or failure-injection test. +4. Implement the narrowest code that satisfies the proof. +5. Run format, focused test, affected crate checks, and the repository's relevant gate. +6. Record the exact command/result and map it back to the criterion. +7. Re-read the diff for scope, redaction, panic/unsafe, retries, feature leakage, and external effects. + +## Test selection + +- Use direct Axum/Tower service calls for most request/middleware contracts without binding a port ([research](../research/async/2026-07-24-axum-service-testing.md)). +- Use Tokio paused time for timeout/backoff/breaker/pin behavior; only Tokio-controlled time is paused ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Use proptest for invariant-rich values and transition sequences, and persist failing seeds ([research](../research/testing/2026-07-24-proptest-index.md)). +- Use real temporary SQLite and multiple connections/processes for persistence concurrency; Loom cannot see operations not expressed through Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Use narrow loopback integration tests only for bind, listener shutdown, disconnect, and process behavior. + +## Patch discipline + +- Do not edit paths outside assigned ownership. +- Do not install missing tools, initialize Git, change public policy, run live providers, or publish as a convenience. +- Do not weaken a test to fit the implementation. +- Do not turn retries on to hide a race; nextest can mark retry-only success as flaky, and release profiles should fail it absent an approved quarantine ([research](../research/testing/2026-07-24-nextest-retries.md)). + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.agents/skills/rust-stinger/guides/04-prove-async-streams.md b/.agents/skills/rust-stinger/guides/04-prove-async-streams.md new file mode 100644 index 00000000..3fb29767 --- /dev/null +++ b/.agents/skills/rust-stinger/guides/04-prove-async-streams.md @@ -0,0 +1,36 @@ +# 04 — Prove async and stream correctness + +## Purpose + +Make task ownership, cancellation, timeout, retry, backpressure, ordering, shutdown, and cleanup observable. This guide covers Command Brief action 5. + +## Lifecycle model + +1. Name the root owner of every spawned task. +2. Define admission stop, cooperative cancellation signal, drain policy, join deadline, escalation, and cleanup. +3. Use bounded channels on hot paths and state the capacity rationale. +4. Review every `select!` awaited operation for documented cancellation safety; dropping and recreating a future must not lose observable work ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +5. Reserve channel capacity before expensive/fallible message construction when cancellation could otherwise lose the message; Tokio documents that cancelled `send` loses the message and queue position ([research](../research/async/2026-07-24-tokio-send-reserve.md)). +6. Call Tower readiness before dispatch and prove reserved capacity is released if dispatch/future is dropped ([research](../research/async/2026-07-24-tower-service-readiness.md)). +7. Record Tower layer order and test saturation, timeout, load shedding, and error mapping because layer order changes observable behavior ([research](../research/async/2026-07-24-tower-service-builder.md)). +8. Stop upstream production when an Axum response body is dropped; HTTP pull-based framing only provides backpressure if the producer is bounded and cancellation-aware ([research](../research/async/2026-07-24-axum-streaming-body.md)). +9. Detect shutdown, notify owned work, and wait for completion as separate phases ([research](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Replay boundary + +Track `visible_output`, `tool_call`, sequence/correlation ID, and reservation state as explicit facts. Once output or a harness-visible tool call occurs, consume/withhold the replay proof and return a structured terminal or recoverable state according to the approved contract; never infer safety from a transport error alone. + +## Required tests + +- cancellation before and after channel reservation; +- cancellation between `poll_ready` and `call`; +- client disconnect while producer is blocked; +- chunk ordering and correlation preservation; +- timeout at each side-effect boundary; +- retry only before the approved visibility boundary; +- shutdown under idle, saturated, streaming, and database-flush states; +- task/permit/handle cleanup after every failure path. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.agents/skills/rust-stinger/guides/05-prove-persistence-and-state.md b/.agents/skills/rust-stinger/guides/05-prove-persistence-and-state.md new file mode 100644 index 00000000..9e4f434c --- /dev/null +++ b/.agents/skills/rust-stinger/guides/05-prove-persistence-and-state.md @@ -0,0 +1,39 @@ +# 05 — Prove persistence and state machines + +## Purpose + +Make SQLx/SQLite transactions, locking, migrations, crash recovery, and state transitions atomic and testable. This guide covers Command Brief action 6. + +## Transaction rules + +1. Acquire write intent before reading mutable budget/quota state when the operation must serialize. SQLite allows one writer; deferred transactions can fail on read-to-write upgrade, while `BEGIN IMMEDIATE` attempts write acquisition at the start ([research](../research/persistence/2026-07-24-sqlite-transactions.md)). +2. Keep eligibility, reservation, aggregate update, and idempotency record in one transaction. +3. Use a conditional SQL update/constraint as the final oversubscription guard; an in-process mutex does not coordinate other processes. +4. Treat `SQLITE_BUSY` as a bounded, observable result. A timeout is not authority for invisible unbounded retry. +5. Use the selected SQLx version's tracked transaction API. `Connection::begin_with` is documented for SQLx 0.9; revalidate or design a version-specific alternative for other lines ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). +6. Centralize and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy. WAL improves reader/writer concurrency but still permits one writer and can grow under long readers ([research](../research/persistence/2026-07-24-sqlite-wal.md)). +7. Match product durability language to the chosen PRAGMAs; WAL with `synchronous=NORMAL` does not provide recent-transaction durability across power loss ([research](../research/persistence/2026-07-24-sqlite-pragma-durability.md)). + +## Migration rules + +- Embed migrations only after the database peer approves schema direction. +- Keep migrations forward-only; test old binary/new schema compatibility as required. +- Test interrupted migration, repeated startup, partial files, and crash/restart recovery. +- Preserve database, WAL, SHM, and journal companions together during recovery; SQLite's atomicity evidence relies on journal/WAL recovery and fault testing ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). +- Use compile-checked queries or checked-in offline metadata where practical; `migrate!` embeds migrations but does not replace compatibility/crash policy ([research](../research/persistence/2026-07-24-sqlx-migrations-queries.md)). + +## State-machine proof + +- Persist explicit tagged states/events and schema versions. +- Keep invalid transitions unconstructible through private types and consumed proof tokens. +- Model reservation, reconciliation, breaker, quota, pin, replay, recovery, and promotion in a reference state machine. +- Generate valid transition sequences, assert postconditions/invariants, shrink failures, and save regression seeds; upstream proptest state-machine support is sequential, so add independent concurrency evidence ([research](../research/testing/2026-07-24-proptest-state-machines.md)). +- Inject fake time, stale observations, duplicate commands, process crashes, busy writers, and restart recovery. + +## Open decision checkpoints + +> TODO: human decision before the relevant product slice — power-loss durability, busy timeout/UX, and final durable replay/promotion schema remain product/architecture decisions. + +## Worked examples + +See [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.agents/skills/rust-stinger/guides/06-implement-adapters.md b/.agents/skills/rust-stinger/guides/06-implement-adapters.md new file mode 100644 index 00000000..429b9550 --- /dev/null +++ b/.agents/skills/rust-stinger/guides/06-implement-adapters.md @@ -0,0 +1,37 @@ +# 06 — Implement adapters behind approved contracts + +## Purpose + +Implement provider and harness edges without granting providers agency or inventing protocol policy. This guide covers Command Brief action 7. + +## Boundary design + +1. Import approved protocol/domain types into edge crates; do not leak SDK types inward. +2. Normalize provider chunks, usage, finish reasons, and errors into the approved internal contract. +3. Preserve correlation, ordering, visibility, tool-call, retry, reservation, and cancellation facts explicitly. +4. Inject credentials only through approved secret-reference interfaces. Secret wrappers require explicit exposure and reduce accidental Debug/copying, but do not replace the secret store ([research](../research/security/2026-07-24-secrecy.md)). +5. Start provider/request functions with `#[instrument(skip_all)]` and add only allowlisted fields; function arguments are captured by default otherwise ([research](../research/observability/2026-07-24-tracing-instrument.md)). +6. Let libraries emit structured events while daemon/CLI binaries own subscriber and sink initialization; tracing advises libraries not to set a global subscriber ([research](../research/observability/2026-07-24-tracing-subscriber.md)). +7. Use stable rustls safe builders and approved roots. Custom verifier APIs are deliberately dangerous and require Security review ([research](../research/security/2026-07-24-rustls-config-builder.md)). +8. Keep unsupported, unauthorized, and unconfigured routes disabled. + +## Fake-first contract suite + +Use fake HTTP servers and fixtures for: + +- success and chunk-boundary variation; +- malformed/unknown fields and structured errors; +- disconnect and cancellation at every visible-output boundary; +- throttling, timeout, server error, retry eligibility, and backpressure; +- usage/reservation/reconciliation and duplicate idempotency keys; +- secret/header/prompt redaction in logs, crashes, metrics, diagnostics, and support exports. + +Direct Router/Tower calls cover most HTTP contracts without a live listener ([research](../research/async/2026-07-24-axum-service-testing.md)); keep a narrow loopback test for bind/shutdown/stream disconnect. + +## Prohibited effects + +Do not use live credentials, paid/subscription traffic, public endpoints, signing identity, or provider activation unless the gate explicitly authorizes them. Adapter implementation never gives a provider tools, approvals, filesystem/repository access, memory, or user interaction. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.agents/skills/rust-stinger/guides/07-build-cli-and-tui.md b/.agents/skills/rust-stinger/guides/07-build-cli-and-tui.md new file mode 100644 index 00000000..e1a7730d --- /dev/null +++ b/.agents/skills/rust-stinger/guides/07-build-cli-and-tui.md @@ -0,0 +1,30 @@ +# 07 — Build CLI and TUI surfaces + +## Purpose + +Build operable, scriptable, redacted operator clients without creating a second control authority. This guide covers Command Brief action 8. + +## CLI contract + +- Model commands and constrained arguments with Clap typed parsers and subcommands ([research](../research/cli-tui/2026-07-24-clap-parser.md)). +- Test parsing with non-exiting APIs; decide printing and process exit only at the binary boundary. +- Keep human help/errors separate from stable JSON/stdout schemas. Clap exposes rendering and exit information, but human formatting is not a machine protocol ([research](../research/cli-tui/2026-07-24-clap-errors.md)). +- Define a domain exit-code taxonomy for operational failures. +- Require a reviewed confirmation or explicit noninteractive policy for destructive or billable commands; keep them disabled if absent. +- Make diagnostics/support exports previewable, double-redacted, and free of prompt bodies, code, raw credentials, headers, and unsalted account identifiers. + +## Optional TUI contract + +- Keep the TUI feature-gated and thin over the same authenticated control client as the CLI. +- Prefer the main Ratatui crate unless a lower-level crate is specifically required; upstream recommends this for ordinary applications ([research](../research/cli-tui/2026-07-24-ratatui-architecture.md)). +- Use Ratatui's managed `run` lifecycle or explicitly handle fallible init/restore so success, error, panic, and cancellation restore the terminal ([research](../research/cli-tui/2026-07-24-ratatui-lifecycle.md)). +- Unit-test widgets against buffers and integration-test the whole UI with `TestBackend` ([research](../research/cli-tui/2026-07-24-ratatui-test-backend.md)). +- Add narrow platform/real-terminal smoke tests only where the supported matrix requires them. + +## Open decision checkpoint + +> TODO: human decision before implementation — whether the TUI is in the first executable milestone remains unresolved. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.agents/skills/rust-stinger/guides/08-verify-and-package-evidence.md b/.agents/skills/rust-stinger/guides/08-verify-and-package-evidence.md new file mode 100644 index 00000000..9796ac2c --- /dev/null +++ b/.agents/skills/rust-stinger/guides/08-verify-and-package-evidence.md @@ -0,0 +1,54 @@ +# 08 — Verify and package evidence + +## Purpose + +Run the complete owned Rust gate and generate reviewable package evidence without claiming peer acceptance or performing unauthorized external effects. This guide covers Command Brief action 9. + +## Verification ladder + +Adapt exact commands to the repository and record every result. + +```bash +cargo fmt --all -- --check +cargo check --workspace --all-targets +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo test --workspace --doc +cargo metadata --format-version 1 +cargo tree --workspace -e features +``` + +Add declared minimal/default/all-feature builds, MSRV checks, target builds, migration/concurrency/crash/fake-provider tests, property/model tests, benchmarks, and soak checks. Clippy guidance recommends `-Dwarnings` with the same compiler toolchain as compilation; new lints make the result toolchain-specific ([research](../research/rust-cargo/2026-07-24-clippy-ci.md)). Nextest does not run doctests, so retain a separate doc-test step ([research](../research/testing/2026-07-24-nextest.md)). + +## Evidence layers + +- Unit/contract: pure logic and direct Tower/Axum calls. +- Deterministic time: Tokio paused clock for time-driven behavior ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Property/state: proptest with saved seeds. +- Model concurrency: Loom only for small primitives expressed with Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Persistence/process: real SQLite, multiple writers, fault injection, kill/restart. +- Provider/stream: fake servers and transcript fixtures. +- Benchmark: Criterion on a controlled host; statistics do not remove noisy-host risk ([research](../research/testing/2026-07-24-criterion-analysis.md)). +- Soak: purpose-built fake-provider run with periodic RSS, task, queue, DB/WAL, handle, throughput, and error telemetry. + +> TODO: human decision before release qualification — define quantitative soak thresholds; no universal off-the-shelf eight-hour harness or product threshold exists in the research packet. + +## Release evidence packet + +Populate `templates/release-evidence-manifest.yaml` with target artifacts, hashes, toolchain/lockfile, tests, SBOM, advisory/license/source scans, install/uninstall transcripts, and verification commands. + +- Revalidate cargo-dist before generating archives/installers; it supports target artifacts, checksums, and several installers, while checksums alone are unsigned integrity values ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). +- Generate target/feature-aware SBOM evidence and record tool version; cargo-cyclonedx added reproducible timestamp and target support in its retrieval-time release ([research](../research/supply-chain/2026-07-24-cargo-cyclonedx.md)). +- Record advisory database time and lockfile/artifact hash because RustSec findings are point-in-time ([research](../research/supply-chain/2026-07-24-rustsec.md)). +- Treat cargo-deny output as evidence for the dependency owner, not license/legal clearance ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). +- Treat Cargo's native SBOM precursor as optional/nightly until stabilized ([research](../research/supply-chain/2026-07-24-cargo-sbom-unstable.md)). +- Do not confuse `cargo package` verification with provenance; Cargo states provenance is not verified ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)). +- Do not sign or publish. Cosign signing can create identity/transparency-log effects and needs explicit authorization ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). + +## Open decision checkpoints + +> TODO: human decisions before release — supported targets/baselines, MSRV, installer formats, signing/attestation identity, and publication authorization. + +## Worked examples + +See [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.agents/skills/rust-stinger/guides/09-close-the-loop.md b/.agents/skills/rust-stinger/guides/09-close-the-loop.md new file mode 100644 index 00000000..dd6bedc9 --- /dev/null +++ b/.agents/skills/rust-stinger/guides/09-close-the-loop.md @@ -0,0 +1,42 @@ +# 09 — Close the loop + +## Purpose + +Return acceptance-linked implementation evidence, limitations, recovery notes, and peer handoffs in the required order. This guide covers Command Brief action 10. + +## Completion procedure + +1. Re-read the requested acceptance criteria and current ledger/gates. +2. Run the final relevant Rust commands against the current tree; do not reuse stale results. +3. Populate `templates/implementation-handoff.md` with exact outcomes and changed paths. +4. For each criterion, cite a command, test, artifact, and result. +5. State external effects exactly: `none` or the recorded authorization/effect. +6. Explain migration, rollback, restart, and data recovery, including any irreversible step. +7. Explain prompt/secret/log/diagnostic handling and remaining Security questions. +8. Route the implemented state to Security. If fixes land, rerun affected implementation gates. +9. Route the post-Security state to Quality for final implementation-to-PRD audit. +10. Leave protocol, platform, dependency/license, CI/release, signing, publication, and other gates with their actual owners. + +## Evidence honesty rules + +- A current-stable toolchain is not a proven MSRV; Cargo requires verification of declared `rust-version` across supported functionality ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- A compiler-supported target is not a product-supported install/runtime target ([research](../research/rust-cargo/2026-07-24-platform-support.md)). +- Passing Loom is not general concurrency proof because unmodeled operations are invisible and state spaces are bounded ([research](../research/testing/2026-07-24-loom.md)). +- A retry-only test success is flaky evidence, not a clean pass ([research](../research/testing/2026-07-24-nextest-retries.md)). +- A generated checksum, SBOM, advisory scan, or license scan does not by itself prove signed provenance or peer acceptance ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md), [research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Blocked checkpoint + +When blocked, provide the smallest safe compilable/testable checkpoint if one exists, then name: + +- blocker and owning gate; +- affected acceptance criteria; +- files/tests completed; +- commands that passed, failed, or were unavailable; +- first authorized next action. + +Never call a partial checkpoint shipped or release-ready. + +## Worked examples + +See all four examples, especially [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.agents/skills/rust-stinger/reports/README.md b/.agents/skills/rust-stinger/reports/README.md new file mode 100644 index 00000000..bdb75008 --- /dev/null +++ b/.agents/skills/rust-stinger/reports/README.md @@ -0,0 +1,3 @@ +# Rust Stinger reports + +This folder accumulates dated implementation handoffs produced by `rust-worker-bee`; copy `implementation-handoff-report-template.md`, preserve exact command evidence, and never overwrite an earlier run. diff --git a/.agents/skills/rust-stinger/reports/implementation-handoff-report-template.md b/.agents/skills/rust-stinger/reports/implementation-handoff-report-template.md new file mode 100644 index 00000000..ccb48186 --- /dev/null +++ b/.agents/skills/rust-stinger/reports/implementation-handoff-report-template.md @@ -0,0 +1,15 @@ +# Rust implementation handoff: {{slice_name}} + +Use the complete reusable form in [`../templates/implementation-handoff.md`](../templates/implementation-handoff.md). Store a populated copy here as `YYYY-MM-DD-{{slice_slug}}.md` only when the orchestrator designates this global Stinger as the report archive; product-specific evidence normally remains in the product's authorized artifact path. + +Required sections: + +1. Outcome +2. Authority and scope +3. Acceptance evidence +4. Changed paths +5. Verification +6. Safety and operations +7. Revalidation points +8. Peer handoffs and remaining gates +9. Blocker, if any diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md new file mode 100644 index 00000000..ac6314f7 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/serve/struct.Serve.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: axum +stinger: rust-stinger +--- + +# Axum server graceful shutdown + +## Summary +Axum's `Serve::with_graceful_shutdown` binds server lifetime to a supplied future. It stops accepting new work when the signal resolves and waits for connections according to the server's graceful behavior. Application-owned background tasks still need separate ownership and joining. + +## Key quotations / statistics +- "Prepares a server to handle graceful shutdown" +- The signal is a future "that resolves to `()`" + +## Version/date caveat +Axum latest docs at retrieval; exact connection-drain semantics depend on the matching hyper/axum versions. + +## Annotations for stinger-forge +- Use for the loopback listener shutdown path. +- Pair with Tokio task tracking; server shutdown alone does not prove all background work stopped. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md new file mode 100644 index 00000000..dd8c0e33 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/src/axum/routing/mod.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: testing +stinger: rust-stinger +--- + +# Axum router testing as a Tower service + +## Summary +Axum routers can be converted to borrowed or owned Tower services and invoked directly with requests. This avoids binding a real socket for most contract and middleware tests, making state, status, headers, and body behavior deterministic while reserving live-listener tests for integration boundaries. + +## Key quotations / statistics +- "Use `as_service` to get a borrowed `Service` from a `Router`." +- "Use `into_service` to get an owned `Service`" + +## Version/date caveat +Source docs for Axum latest; test helpers and body collection APIs vary across axum/http-body-util releases. + +## Annotations for stinger-forge +- Supports in-process HTTP contract tests without network flakiness. +- Loopback bind and shutdown still require a smaller dedicated integration test. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md new file mode 100644 index 00000000..2c2c12f0 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/body/struct.Body.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: streaming +stinger: rust-stinger +--- + +# Axum streaming bodies + +## Summary +Axum 0.8.9 wraps `http_body::Body` and can create a response body from a fallible `Stream`. Consumers pull frames asynchronously through `poll_frame`; converting to a data-only stream discards trailers. Backpressure therefore propagates through polling only if the upstream producer is itself bounded and cancellation-aware. + +## Key quotations / statistics +- `from_stream`: "Create a new `Body` from a `Stream`." +- `poll_frame`: "Attempt to pull out the next data buffer of this stream." + +## Version/date caveat +Axum 0.8.9, http-body 1.1.0 at retrieval. Frame/trailer behavior must match the selected HTTP contract. + +## Annotations for stinger-forge +- Core source for streaming body construction and disconnect/cancellation tests. +- Do not collect unbounded streams into memory; test that dropping the body stops producer work and releases permits. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md new file mode 100644 index 00000000..653ee9c7 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/shutdown +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: shutdown +stinger: rust-stinger +--- + +# Tokio graceful shutdown + +## Summary +Tokio presents graceful shutdown as three explicit phases: detect the trigger, notify owned work, and wait for work to finish. It demonstrates cancellation tokens for cooperative notification and task trackers for joining all tracked work, allowing cleanup such as database flushes before termination. + +## Key quotations / statistics +- "Figuring out when to shut down." +- "Waiting for other parts of the program to shut down." + +## Version/date caveat +Conceptual Tokio topic page; exact APIs may live in `tokio-util` and must match the selected versions. + +## Annotations for stinger-forge +- Core source for task ownership and shutdown checklists. +- Supports a root cancellation token plus explicit join/timeout/escalation evidence. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md new file mode 100644 index 00000000..c0c0d4cf --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: backpressure +stinger: rust-stinger +--- + +# Tokio bounded MPSC channels + +## Summary +Tokio's bounded MPSC channel supplies backpressure by suspending senders when capacity is exhausted. Clean shutdown closes the receiver and drains buffered values; dropping the receiver drains and drops unread messages. Unbounded channels have infinite logical capacity and therefore cannot express a memory/backpressure bound. + +## Key quotations / statistics +- "the channel provides backpressure" +- "the receiver first calls `close`, which will prevent any further messages" + +## Version/date caveat +Retrieved against Tokio 1.53.1. Allocation details are explicitly implementation details and may change. + +## Annotations for stinger-forge +- Grounds bounded queue requirements and shutdown draining tests. +- Supports rejecting unbounded queues on stream/provider hot paths without a proven upper bound. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md new file mode 100644 index 00000000..d86db676 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/tokio/latest +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: tokio +stinger: rust-stinger +--- + +# Tokio current release and support policy + +## Summary +Docs.rs records Tokio 1.53.1 released 2026-07-20. Tokio states that 1.51.x is LTS through March 2027 with MSRV 1.71, while current minor releases may move faster. A fixed-minor daemon dependency can choose an LTS line, but the choice must be reconciled with required APIs and security fixes. + +## Key quotations / statistics +- "1.53.1 (2026-07-20)" +- "`1.51.x` - LTS release until March 2027. (MSRV 1.71)" + +## Version/date caveat +Patch versions and LTS designations can change; this is a retrieval-time snapshot. + +## Annotations for stinger-forge +- Use to frame current versus LTS version policy without choosing on the release peer's behalf. +- Record the transitive-dependency MSRV caveat stated by Tokio. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md new file mode 100644 index 00000000..09e162ed --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/macro.select.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: cancellation +stinger: rust-stinger +--- + +# Tokio `select!` cancellation safety + +## Summary +Tokio defines cancellation safety as dropping and recreating an incomplete future without observable loss. The docs enumerate safe and unsafe operations and warn that loops using non-cancellation-safe futures can lose data when another branch wins. This must be checked per awaited operation, not assumed because code is async. + +## Key quotations / statistics +- "it must be a no-op to drop that future and recreate it" +- "The lists in this section are not exhaustive." + +## Version/date caveat +Retrieved against Tokio 1.53.1; method-level cancellation guarantees may change and should be linked directly in code review. + +## Annotations for stinger-forge +- Core source for cancellation audits around streams, writes, queues, and database work. +- Supports focused tests for the exact boundary where visible output makes replay forbidden. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md new file mode 100644 index 00000000..60756cfc --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/src/tokio/sync/mpsc/bounded.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: permits +stinger: rust-stinger +--- + +# Tokio MPSC reserve and cancellation + +## Summary +The bounded-channel source documentation says cancelling `send` loses the message and the sender's queue position. Reserving capacity first returns a permit so message construction can occur only after capacity is secured. Outstanding permits also delay a receiver from observing final closure. + +## Key quotations / statistics +- "the message is dropped and will be lost" +- "To avoid losing messages, use `reserve`" + +## Version/date caveat +Source documentation for Tokio latest (1.53.1 at retrieval); treat internal implementation as unstable while relying on documented public behavior. + +## Annotations for stinger-forge +- Supports reserve-before-expensive-work and cancellation-focused queue tests. +- Shutdown code must account for outstanding permits, not only sender handles. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md new file mode 100644 index 00000000..dcce062a --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: middleware +stinger: rust-stinger +--- + +# Tower concurrency, buffering, and load shedding + +## Summary +`ServiceBuilder` exposes concurrency limits, buffers, timeouts, and load shedding as composable layers. Concurrency limits count in-flight requests through response-future completion. Load shedding converts lack of readiness into an immediate error rather than waiting. Layer order changes which work is bounded and which errors are visible. + +## Key quotations / statistics +- "Limit the max number of in-flight requests." +- "`LoadShed` immediately responds with an error" + +## Version/date caveat +Feature-gated Tower APIs; selected crate features and layer order must be recorded in the workspace. + +## Annotations for stinger-forge +- Supports explicit capacity/timeout/load-shed policy and layer-order tests. +- Protocol error mapping remains a peer decision; this source only establishes middleware behavior. + diff --git a/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md b/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md new file mode 100644 index 00000000..974e3456 --- /dev/null +++ b/.agents/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/trait.Service.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: readiness +stinger: rust-stinger +--- + +# Tower `Service` readiness contract + +## Summary +Tower separates readiness from dispatch. Callers must observe `poll_ready` before `call`; readiness may reserve shared resources, which implementations must release if dispatch never occurs or the response future is dropped. Capacity is therefore an ownership contract, not merely a performance hint. + +## Key quotations / statistics +- "Before dispatching a request, `poll_ready` must be called" +- readiness "may reserve shared resources" + +## Version/date caveat +Tower latest docs at retrieval; middleware can alter readiness semantics by layer order. + +## Annotations for stinger-forge +- Core evidence for backpressure-aware Tower services and adapters. +- Supports tests that cancel between readiness and call and assert permit/resource release. + diff --git a/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md new file mode 100644 index 00000000..fc5a2b46 --- /dev/null +++ b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/container-attrs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: validation +stinger: rust-stinger +--- + +# Serde container boundary attributes + +## Summary +Serde's container attributes allow unknown-field rejection, fallible conversion through `try_from`, transparent newtypes, defaults, and explicit tagging. Unknown fields are ignored by default in self-describing formats, so strict control/config inputs require an intentional choice rather than assuming fail-closed parsing. + +## Key quotations / statistics +- `deny_unknown_fields` will "Always error during deserialization when encountering unknown fields." +- By default, "unknown fields are ignored" + +## Version/date caveat +`deny_unknown_fields` cannot be combined with `flatten`; compatibility policy must account for that limitation. + +## Annotations for stinger-forge +- Grounds strict config/control-plane parsing and validated newtypes. +- Use separate input DTOs when forward-compatible wire payloads must retain unknown fields. + diff --git a/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md new file mode 100644 index 00000000..f2e288b8 --- /dev/null +++ b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/enum-representations.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: serde +stinger: rust-stinger +--- + +# Serde enum representations + +## Summary +Serde supports externally, internally, adjacently, and untagged enum encodings. Tagged enums make the selected variant explicit before or alongside content; untagged enums try variants in order and accept the first successful parse. For safety-state and protocol boundaries, representation choice affects ambiguity, forward compatibility, and error quality. + +## Key quotations / statistics +- Externally tagged data identifies "which variant we are dealing with before beginning to parse" +- Untagged "will try to match the data against each variant in order" + +## Version/date caveat +Serde project documentation; specific derive behavior still depends on the pinned serde version and enabled `alloc` feature. + +## Annotations for stinger-forge +- Supports explicit tagged enums for state/event boundaries where ambiguity is unacceptable. +- Protocol wire encoding remains the protocol peer's contract. + diff --git a/.agents/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md new file mode 100644 index 00000000..692d0b6e --- /dev/null +++ b/.agents/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/thiserror/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: errors +stinger: rust-stinger +--- + +# thiserror structured errors + +## Summary +thiserror 2.0.19 derives standard error implementations without becoming part of the public API contract. `source`, `from`, and `transparent` preserve causal chains, while an opaque public wrapper can hide a private evolving representation. Redaction still depends on the chosen fields and Display text. + +## Key quotations / statistics +- "Errors may use `error(transparent)` to forward the source and Display methods" +- "hiding implementation details ... behind an opaque error type" + +## Version/date caveat +Version 2.0.19 was published six days before retrieval; pin and test formatting if machine parsing depends on it. + +## Annotations for stinger-forge +- Supports domain error enums at crate boundaries and opaque public errors. +- Do not place secrets/prompts in source error values or formatted context. + diff --git a/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md new file mode 100644 index 00000000..e079d17a --- /dev/null +++ b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/type.Error.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: exits +stinger: rust-stinger +--- + +# Clap error and exit behavior + +## Summary +Clap errors expose their kind, rendered form, stderr/stdout routing, printing, and exit code. Library/test paths can use non-exiting parse APIs, while the process boundary decides when to print and exit. Operational failures after parsing need a separate stable exit-code taxonomy. + +## Key quotations / statistics +- The error API includes `exit_code`. +- The error API includes `use_stderr` and `render`. + +## Version/date caveat +Clap 4.6.2 at retrieval; exact human rendering is not a stable machine protocol. + +## Annotations for stinger-forge +- Supports separating parse errors from domain/transport exit codes. +- Require JSON/stdout contracts to avoid scraping colored human help/error output. + diff --git a/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md new file mode 100644 index 00000000..f15fca06 --- /dev/null +++ b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/parser/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: clap +stinger: rust-stinger +--- + +# Clap typed command-line parsing + +## Summary +Clap 4.6.2 provides `Parser`, `Subcommand`, `Args`, `CommandFactory`, and `ValueEnum` traits for typed command structures and introspection. These types support explicit command inventories, constrained values, generated help/completions, and parser tests independent of process execution. + +## Key quotations / statistics +- `ValueEnum`: "Parse arguments into enums." +- `CommandFactory`: "Create a `Command` relevant for a user-defined container." + +## Version/date caveat +Clap 4.6.2 at retrieval; help text and formatting can change across minor releases. + +## Annotations for stinger-forge +- Supports typed subcommands and deterministic parser contract tests. +- Machine-readable command output is an application schema layered above Clap. + diff --git a/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md new file mode 100644 index 00000000..98784587 --- /dev/null +++ b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: medium +topic: tui +stinger: rust-stinger +--- + +# Ratatui crate architecture + +## Summary +Ratatui's primary crate re-exports the application-facing surface, while lower-level workspace crates exist for custom widget libraries and backend-specific integrations. The docs recommend staying in the main crate unless a lower-level dependency is specifically needed, reducing feature and compile-time surface for ordinary applications. + +## Key quotations / statistics +- "Most application authors should stay in this `ratatui` crate." +- "Reach for other crates ... only when you specifically need a lower-level layer" + +## Version/date caveat +Ratatui 0.30.2; workspace decomposition may evolve. + +## Annotations for stinger-forge +- Supports avoiding premature internal TUI crate fragmentation. +- Feature-gate the entire TUI and keep domain/control logic outside it. + diff --git a/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md new file mode 100644 index 00000000..bc52308f --- /dev/null +++ b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/init/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: terminal +stinger: rust-stinger +--- + +# Ratatui terminal initialization and restoration + +## Summary +Ratatui 0.30.2 recommends `run` for ownership of terminal setup/cleanup, or fallible `try_init`/`try_restore` when the application needs explicit handling. Helpers manage raw mode, alternate screen, and a panic hook that restores the terminal. Manual construction transfers teardown responsibility to the application. + +## Key quotations / statistics +- `run` "automatically restores the terminal state" +- "All initialization functions install a panic hook" + +## Version/date caveat +`run` was introduced in 0.30.0; older examples may show manual lifecycle code. + +## Annotations for stinger-forge +- Grounds terminal cleanup on success, error, panic, and cancellation. +- Favor the headless CLI/control client; keep the TUI a thin optional surface. + diff --git a/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md new file mode 100644 index 00000000..afcd9d15 --- /dev/null +++ b/.agents/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/backend/struct.TestBackend.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: rendering +stinger: rust-stinger +--- + +# Ratatui `TestBackend` + +## Summary +Ratatui's `TestBackend` renders an integration-level terminal UI to an in-memory buffer and can assert lines, cursor, resize, and scrollback. The docs prefer direct widget-buffer tests for units and reserve `TestBackend` for whole-TUI integration, giving two appropriately sized evidence layers. + +## Key quotations / statistics +- "renders to an memory buffer" +- "preferable to write unit tests for widgets directly against the buffer" + +## Version/date caveat +Ratatui 0.30.2 at retrieval; snapshot glyph/width behavior can vary with terminal/unicode dependencies. + +## Annotations for stinger-forge +- Supports deterministic TUI rendering tests without a real terminal. +- Add narrow real-terminal smoke tests only where lifecycle/platform integration matters. + diff --git a/.agents/skills/rust-stinger/research/evidence-synthesis.md b/.agents/skills/rust-stinger/research/evidence-synthesis.md new file mode 100644 index 00000000..70a55448 --- /dev/null +++ b/.agents/skills/rust-stinger/research/evidence-synthesis.md @@ -0,0 +1,178 @@ +# Rust Stinger Evidence Synthesis + +This is an evidence map for Stinger Forge, not a replacement for the product ADR, protocol contract, Security review, dependency/license decision, release authorization, or Quality report. The 56 indexed source notes are authoritative inputs; this file connects them to the Command Brief's research questions and records the remaining decisions honestly. +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +## Current anchors at retrieval + +| Surface | Current evidence snapshot | Caveat | +|---|---|---| +| Rust | 1.97.1 released 2026-07-16 | Current stable is not automatically the product MSRV. | +| Cargo | Rust 2024 resolver v3; `rust-version`-aware fallback | Virtual workspaces must declare the resolver; CI must prove MSRV. | +| Tokio | 1.53.1 released 2026-07-20; 1.51.x LTS through March 2027 | Tokio's MSRV does not establish the whole graph's MSRV. | +| Axum | 0.8.9 docs snapshot | Pin compatible hyper/http-body/tower versions together. | +| SQLx | 0.9.0 docs snapshot | `begin_with` is version-specific; verify before applying to SQLx 0.8. | +| Clap / Ratatui | 4.6.2 / 0.30.2 | Human rendering and TUI APIs can change across minor versions. | +| rustls | 0.23.42 stable docs; 0.24 development docs also visible | Avoid accidental dependency on development APIs. | +| Testing | Loom 0.7.2; Criterion 0.8.2 | Model and benchmark results have explicit coverage/environment limits. | +| SBOM | cargo-cyclonedx 0.5.9 (2026-03-19) | Cargo native SBOM precursors remain unstable/nightly. | + +## 1. Tokio, Axum, and Tower ownership, cancellation, streaming, and shutdown + +The sources converge on a verifiable lifecycle made of distinct obligations: + +1. A root owner detects shutdown, signals cooperative cancellation, stops admission, and waits for every owned task. Tokio's shutdown guide explicitly separates trigger, notification, and joining. +2. Bounded MPSC channels express a capacity contract. Clean shutdown closes the receiver and drains it. `send` inside `select!` may lose the message; `reserve` obtains capacity first and makes that boundary testable. +3. Every `select!` branch needs method-level cancellation review. "Async" alone does not imply cancellation safety. +4. Tower readiness is a resource reservation. `poll_ready` must precede `call`, and capacity must be released if dispatch or its future is dropped. Concurrency-limit, buffer, timeout, and load-shed layer order changes observable behavior. +5. Axum can serve a fallible stream as a response body. HTTP consumers pull frames; the upstream producer must still be bounded and cancellation-aware. Dropping/disconnecting the body should stop producer work and release permits in focused tests. +6. `with_graceful_shutdown` owns listener/connection admission, not arbitrary background work. Background task ownership remains in Tokio task tracking. +7. Most router/middleware contracts can be tested by invoking the Router as a Tower service without binding a port. A narrower loopback integration test proves bind address, shutdown, and disconnect behavior. + +Primary notes: [Tokio shutdown](async/2026-07-24-tokio-graceful-shutdown.md), [MPSC](async/2026-07-24-tokio-mpsc.md), [`select!`](async/2026-07-24-tokio-select-cancellation.md), [reserve](async/2026-07-24-tokio-send-reserve.md), [Tower readiness](async/2026-07-24-tower-service-readiness.md), [Tower layers](async/2026-07-24-tower-service-builder.md), [Axum shutdown](async/2026-07-24-axum-graceful-shutdown.md), [Axum streaming](async/2026-07-24-axum-streaming-body.md), and [service testing](async/2026-07-24-axum-service-testing.md). + +## 2. SQLite and SQLx transactions, locking, and durability + +SQLite permits a single writer. `BEGIN DEFERRED` can read a stale budget view and then fail during write upgrade; `BEGIN IMMEDIATE` acquires write intent before the read-modify-write sequence. SQLx 0.9's `Connection::begin_with` provides a tracked custom transaction start, enabling `BEGIN IMMEDIATE` while preserving explicit commit/rollback and rollback-on-drop behavior. + +Evidence-supported invariants for reservations/reconciliations/breakers/migrations: + +- Acquire the write transaction before reading mutable budget/quota state. +- Keep eligibility check, reservation insert/update, aggregate update, and idempotency record in one transaction. +- Use conditional SQL constraints/updates as the final oversubscription guard; application locks are not sufficient across processes. +- Treat `SQLITE_BUSY` as a bounded, observable contention result. A busy timeout is not permission for invisible unbounded retry. +- Configure and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy through one connection-options path. +- WAL improves reader/writer concurrency but does not allow multiple writers. Long readers can starve checkpoints and grow the WAL. +- WAL plus `synchronous=NORMAL` can lose recent committed transactions after power loss. Product durability language must match the chosen PRAGMA contract. +- Crash evidence should kill/restart at transaction and checkpoint boundaries and verify all-or-none invariants. Preserve the database and its WAL/SHM/journal companions during recovery. +- Embedded migrations improve delivery but do not replace forward-only migration, old-binary/new-schema compatibility, and interruption tests. + +Primary notes: [transactions](persistence/2026-07-24-sqlite-transactions.md), [WAL](persistence/2026-07-24-sqlite-wal.md), [atomic commit](persistence/2026-07-24-sqlite-atomic-commit.md), [PRAGMAs](persistence/2026-07-24-sqlite-pragma-durability.md), [SQLx options](persistence/2026-07-24-sqlx-connect-options.md), [custom transactions](persistence/2026-07-24-sqlx-custom-transactions.md), and [queries/migrations](persistence/2026-07-24-sqlx-migrations-queries.md). + +## 3. Typed state machines and replay/promotion proof + +Rust's enums, newtypes, privacy, exhaustive matching, and ownership can make invalid transitions difficult to express. The strongest upstream example in this corpus is rustls: private marker values bind the fact that verification occurred and prevent skipping required checks before entering the traffic state. + +Evidence-supported design constraints for Forge to encode: + +- Persist durable facts as an explicit tagged enum/event schema; avoid ambiguous untagged parsing for safety state. +- Reject unknown fields on strict local control/config inputs unless an explicit compatibility contract requires otherwise. +- Use private constructors and non-forgeable capability/marker types for facts such as `NoVisibleOutput`, `NoToolCall`, `ReservationHeld`, or `SafeTurnReviewed`. +- Consume one-shot proof values on transition so replay/promotion cannot accidentally reuse authorization. +- Keep provider events and harness events in edge crates, normalize them into protocol-neutral domain facts, and let the state machine depend only on those facts. +- Represent terminal/irreversible states explicitly and test every transition plus serialization round trip against a reference model. +- Keep user-visible error codes separate from internal causal chains; neither should contain prompts, raw credentials, or headers. + +Primary notes: [Serde enums](boundaries/2026-07-24-serde-enum-representations.md), [strict attributes](boundaries/2026-07-24-serde-container-attributes.md), [thiserror](boundaries/2026-07-24-thiserror.md), [rustls builder typestate](security/2026-07-24-rustls-config-builder.md), and [verification markers](security/2026-07-24-rustls-verification-markers.md). + +## 4. Cargo workspace and MSRV evidence + +Resolver v3 is global at the top-level workspace. Features remain additive and can unify through dependency paths, so crate boundaries and feature design must prevent provider/TUI/TLS choices from leaking into protocol, policy, and state cores. + +A reviewable dependency direction for the accepted architecture is: + +```text +protocol/types <- policy/state <- provider adapters + ^ ^ ^ + | | | + daemon/control ----+--------------+ + ^ + CLI <- optional TUI + +test-support/evaluation may depend on public seams; +production crates must not depend on test-support. +``` + +This is a research-derived dependency constraint, not approval of exact crate names. Workspace review should look for: + +- one owner per invariant rather than a crate per noun; +- `resolver = "3"` in a virtual workspace; +- shared dependency versions/features declared centrally where that reduces drift; +- provider and TUI features default-off unless the product requires otherwise; +- `cargo tree -e features`, all-target/all-feature checks, and representative minimal-feature checks; +- public types flowing inward only from the approved protocol/domain crate, never harness/provider SDK types; +- a documented unsafe inventory, defaulting to `forbid(unsafe_code)` where possible. + +For a new removable local daemon, the credible starting toolchain is a pinned current stable release (1.97.1 at retrieval), with `package.rust-version` declared only after the full resolved graph and advertised features pass MSRV CI. Tokio 1.51.x is an available 2026 LTS line with MSRV 1.71, but that fact alone is not a reason to choose Rust 1.71 for the product. Re-check stable, platform tiers, and dependency MSRVs immediately before Forge freezes guidance. + +Primary notes: [current Rust](rust-cargo/2026-07-24-rust-release-1-97.md), [`rust-version`](rust-cargo/2026-07-24-cargo-rust-version.md), [resolver v3](rust-cargo/2026-07-24-cargo-resolver-v3.md), [features](rust-cargo/2026-07-24-cargo-features.md), [platform tiers](rust-cargo/2026-07-24-platform-support.md), [Cargo CI](rust-cargo/2026-07-24-cargo-ci-msrv.md), [Clippy](rust-cargo/2026-07-24-clippy-ci.md), and [Tokio release policy](async/2026-07-24-tokio-release-policy.md). + +## 5. Tracing, secrets, and TLS + +- `#[instrument]` captures all arguments by default, including Debug output. Sensitive functions should start from `skip_all` and add allowlisted identifiers/state fields. +- Libraries emit structured spans/events; binaries own subscriber/filter/sink initialization. Libraries should not set the global subscriber. +- Secret wrappers reduce accidental exposure and require explicit access, but do not replace a secret store and cannot prevent every copy during deserialization. +- rustls stable builders encode mandatory verifier/certificate choices and use safe defaults. Custom verifier APIs are deliberately marked dangerous and require Security review. +- TLS/provider selection, certificate roots, egress/redirect/DNS/SSRF controls, redaction acceptance, and crash-dump policy remain Security/platform decisions. + +Primary notes: [instrument capture](observability/2026-07-24-tracing-instrument.md), [subscriber ownership](observability/2026-07-24-tracing-subscriber.md), [secrecy](security/2026-07-24-secrecy.md), and [rustls](security/2026-07-24-rustls-config-builder.md). + +## 6. CLI and TUI evidence + +Clap supports typed subcommands, constrained enums, introspection, and non-exiting parse paths. Human help/error formatting should not become the machine protocol; define stable JSON/stdout schemas and a separate domain exit-code taxonomy. Destructive or billable commands need an explicit confirmation/noninteractive policy above Clap. + +Ratatui 0.30's `run` owns terminal initialization and restoration, including panic cleanup. Fallible init/restore APIs exist for explicit error handling. `TestBackend` provides deterministic integration rendering; direct buffer/widget tests are preferred for units. The TUI should remain feature-gated and depend on the same authenticated control client as the CLI rather than becoming a second authority. + +Primary notes: [Clap parser](cli-tui/2026-07-24-clap-parser.md), [Clap errors](cli-tui/2026-07-24-clap-errors.md), [terminal lifecycle](cli-tui/2026-07-24-ratatui-lifecycle.md), [TestBackend](cli-tui/2026-07-24-ratatui-test-backend.md), and [Ratatui architecture](cli-tui/2026-07-24-ratatui-architecture.md). + +## 7. Verification stack, including eight-hour soak evidence + +| Evidence layer | Primary mechanism | What it proves | Main limitation | +|---|---|---|---| +| Unit/contract | `cargo test`, direct Axum/Tower service calls | Pure logic, types, HTTP/service contracts | Does not prove listener/process behavior. | +| Deterministic time | Tokio `start_paused`, injected clocks | Timeouts, retry schedules, breakers, pins, promotion windows | Only controlled clocks advance. | +| Property/state | proptest + persisted seeds | Invariants across generated values/transition sequences | Current state-machine helper is sequential. | +| Model concurrency | Loom on small primitives | Explored synchronization interleavings | Requires Loom types; state explosion; not DB/process proof. | +| Persistence/concurrency | real temp SQLite, multiple connections/processes, fault injection | Write contention, idempotency, migration and crash recovery | Needs platform/filesystem coverage. | +| Provider/stream | fake HTTP servers and transcript fixtures | chunk ordering, cancellation, replay boundary, error normalization | Fixture drift must be managed; no live credentials. | +| Suite execution | cargo-nextest profiles, timeouts, JUnit | Isolation, classification, evidence export | Doctests remain separate; retries can mask flaws. | +| Microbenchmark | Criterion on controlled hosts | throughput/latency trends with confidence intervals | Noisy shared CI can mislead. | +| Eight-hour soak | purpose-built release harness under nextest/process supervisor | bounded memory/queues, handle/task cleanup, WAL growth/checkpoints, reconnect stability | No single crate proves this; requires explicit invariants and periodic telemetry. | + +An eight-hour soak should use fake providers and local fixtures, emit periodic bounded metrics (RSS, task count, queue depth, DB/WAL size, open handles, request/error counters), assert no monotonic leak or invariant breach, capture start/end versions/config/seeds, and fail on flaky retry. It is separate from Criterion and from Loom. + +Primary notes: [proptest state machines](testing/2026-07-24-proptest-state-machines.md), [Loom](testing/2026-07-24-loom.md), [Tokio time](testing/2026-07-24-tokio-time-testing.md), [nextest](testing/2026-07-24-nextest.md), [flaky retries](testing/2026-07-24-nextest-retries.md), and [Criterion](testing/2026-07-24-criterion-analysis.md). + +## 8. Packaging, SBOM, signing, and advisory evidence + +A credible 2026 release-evidence packet can contain target-specific archives/installers, hashes, install/uninstall transcripts, SBOM, embedded dependency metadata, advisory/license/source scan results, and provenance/signature verification. The tools have complementary roles: + +- cargo-dist builds target archives/installers and hashes; generated output and tool version must be pinned/reviewed. +- cargo-cyclonedx generates standardized SBOMs and supports `SOURCE_DATE_EPOCH`/target-aware output as of 0.5.9. +- cargo-auditable embeds dependency information in binaries for later scanning. +- cargo-deny supplies advisory/license/ban/source policy evidence but does not prove legal clearance. +- RustSec/cargo-audit produces point-in-time lockfile/binary advisory findings; record database time and lockfile/artifact hash. +- Cosign signs blobs and emits verification bundles; signing/publishing is an explicitly authorized external effect. +- Cargo's native SBOM precursor is still unstable/nightly and should remain supplemental for a stable baseline. +- `cargo package` verifies crate contents/buildability but explicitly does not prove provenance. + +Primary notes: [dist config](supply-chain/2026-07-24-cargo-dist-config.md), [dist attestations](supply-chain/2026-07-24-cargo-dist-attestations.md), [cargo-cyclonedx](supply-chain/2026-07-24-cargo-cyclonedx.md), [cargo-auditable](supply-chain/2026-07-24-cargo-auditable.md), [cargo-deny](supply-chain/2026-07-24-cargo-deny-checks.md), [license limits](supply-chain/2026-07-24-cargo-deny-license-limitations.md), [RustSec](supply-chain/2026-07-24-rustsec.md), [cargo-audit](supply-chain/2026-07-24-cargo-audit.md), [Cosign](supply-chain/2026-07-24-sigstore-cosign-blob.md), [Cargo SBOM](supply-chain/2026-07-24-cargo-sbom-unstable.md), and [cargo package](supply-chain/2026-07-24-cargo-package-verification.md). + +## Peer-boundary map + +| Area | Rust Bee may implement/prove | Peer retains final authority | +|---|---|---| +| HTTP/MCP/provider protocol | Approved types, adapters, fixtures, streaming behavior | Protocol semantics and compatibility | +| Security/TLS/secrets/logs | Safe defaults, redaction mechanics, tests | Threat model and acceptance | +| SQLite/SQLx | Transactions, migrations, concurrency/crash tests | Schema/data architecture review | +| Dependencies/SBOM/licenses | Generate exact reports/artifacts | Exceptions, license/advisory disposition | +| Release/CI | Rust build/package configuration and local proof | CI topology, signing identity, publication | +| Quality | Acceptance-linked implementation evidence | Final PRD implementation audit | + +## Open decisions for the user/orchestrator + +1. Exact supported OS/architecture/install matrix and minimum OS/glibc baselines. +2. Whether the initial toolchain pins current stable or a selected older stable after the dependency graph exists; no evidence supports claiming an MSRV before that graph is tested. +3. Required power-loss durability: WAL `FULL`, WAL `NORMAL`, or another documented contract. +4. Maximum writer wait/busy timeout and user-visible contention behavior. +5. Exact state/event schema for visible output, tool calls, reservation, replay prohibition, and safe-turn promotion. +6. Whether the optional TUI is inside the first executable milestone. +7. Release signing identity/attestation platform and which installer formats are authorized. +8. Quantitative pass/fail thresholds for the eight-hour soak (RSS slope, WAL growth, task/handle counts, throughput/error rate). + +## Tool provenance limitation + +The research packet uses the configured Context7 service plus current direct official/upstream documentation retrieval. No raw web-crawl JSON exists; this limitation is explicit so Forge does not mistake the corpus for a web-crawl corpus. + diff --git a/.agents/skills/rust-stinger/research/index.md b/.agents/skills/rust-stinger/research/index.md new file mode 100644 index 00000000..9636d31a --- /dev/null +++ b/.agents/skills/rust-stinger/research/index.md @@ -0,0 +1,64 @@ +# Research Index: rust-stinger + +Generated by scripture-historian. Updated after every source-file write. + +Snapshot: 2026-07-24. Version-sensitive values in this packet are evidence snapshots, not timeless defaults; revalidate at the point of use. + +| File | Source type | Authority | Relevance | Topic | +|---|---|---|---|---| +| `rust-cargo/2026-07-24-rust-release-1-97.md` | changelog | official | critical | toolchain | +| `rust-cargo/2026-07-24-cargo-rust-version.md` | official-docs | official | critical | msrv | +| `rust-cargo/2026-07-24-cargo-resolver-v3.md` | official-docs | official | critical | resolver | +| `rust-cargo/2026-07-24-cargo-features.md` | official-docs | official | high | features | +| `rust-cargo/2026-07-24-platform-support.md` | official-docs | official | critical | targets | +| `rust-cargo/2026-07-24-cargo-ci-msrv.md` | official-docs | official | high | ci | +| `rust-cargo/2026-07-24-clippy-ci.md` | official-docs | official | high | linting | +| `rust-cargo/2026-07-24-unsafe-rust.md` | official-docs | official | high | unsafe | +| `async/2026-07-24-tokio-release-policy.md` | changelog | official | critical | tokio | +| `async/2026-07-24-tokio-graceful-shutdown.md` | official-docs | official | critical | shutdown | +| `async/2026-07-24-tokio-mpsc.md` | official-docs | official | critical | backpressure | +| `async/2026-07-24-tokio-select-cancellation.md` | official-docs | official | critical | cancellation | +| `async/2026-07-24-tokio-send-reserve.md` | official-docs | official | high | permits | +| `async/2026-07-24-tower-service-readiness.md` | official-docs | official | critical | readiness | +| `async/2026-07-24-tower-service-builder.md` | official-docs | official | high | middleware | +| `async/2026-07-24-axum-graceful-shutdown.md` | official-docs | official | critical | axum | +| `async/2026-07-24-axum-service-testing.md` | official-docs | official | high | testing | +| `async/2026-07-24-axum-streaming-body.md` | official-docs | official | critical | streaming | +| `persistence/2026-07-24-sqlite-transactions.md` | official-docs | official | critical | transactions | +| `persistence/2026-07-24-sqlite-wal.md` | official-docs | official | critical | wal | +| `persistence/2026-07-24-sqlite-atomic-commit.md` | official-docs | official | critical | recovery | +| `persistence/2026-07-24-sqlite-pragma-durability.md` | official-docs | official | critical | durability | +| `persistence/2026-07-24-sqlx-connect-options.md` | official-docs | official | critical | sqlx | +| `persistence/2026-07-24-sqlx-migrations-queries.md` | official-docs | official | high | migrations | +| `persistence/2026-07-24-sqlx-custom-transactions.md` | official-docs | official | critical | locking | +| `boundaries/2026-07-24-serde-enum-representations.md` | official-docs | official | critical | serde | +| `boundaries/2026-07-24-serde-container-attributes.md` | official-docs | official | high | validation | +| `boundaries/2026-07-24-thiserror.md` | official-docs | official | high | errors | +| `observability/2026-07-24-tracing-instrument.md` | official-docs | official | critical | tracing | +| `observability/2026-07-24-tracing-subscriber.md` | official-docs | official | high | subscriber | +| `security/2026-07-24-secrecy.md` | official-docs | official | high | secrets | +| `security/2026-07-24-rustls-config-builder.md` | official-docs | official | critical | tls | +| `security/2026-07-24-rustls-verification-markers.md` | official-docs | official | critical | typestate | +| `cli-tui/2026-07-24-clap-parser.md` | official-docs | official | high | clap | +| `cli-tui/2026-07-24-clap-errors.md` | official-docs | official | high | exits | +| `cli-tui/2026-07-24-ratatui-lifecycle.md` | official-docs | official | high | terminal | +| `cli-tui/2026-07-24-ratatui-test-backend.md` | official-docs | official | high | rendering | +| `cli-tui/2026-07-24-ratatui-architecture.md` | official-docs | official | medium | tui | +| `testing/2026-07-24-proptest-state-machines.md` | official-docs | official | critical | proptest | +| `testing/2026-07-24-proptest-index.md` | official-docs | official | high | properties | +| `testing/2026-07-24-loom.md` | official-docs | official | critical | loom | +| `testing/2026-07-24-tokio-time-testing.md` | official-docs | official | critical | faketime | +| `testing/2026-07-24-nextest.md` | official-docs | official | high | nextest | +| `testing/2026-07-24-nextest-retries.md` | official-docs | official | high | flakiness | +| `testing/2026-07-24-criterion-analysis.md` | official-docs | official | high | benchmark | +| `supply-chain/2026-07-24-cargo-dist-config.md` | official-docs | official | critical | packaging | +| `supply-chain/2026-07-24-cargo-dist-attestations.md` | official-docs | official | high | provenance | +| `supply-chain/2026-07-24-cargo-cyclonedx.md` | changelog | official | critical | sbom | +| `supply-chain/2026-07-24-cargo-auditable.md` | github-readme | practitioner | high | auditability | +| `supply-chain/2026-07-24-cargo-deny-checks.md` | official-docs | official | high | policy | +| `supply-chain/2026-07-24-cargo-deny-license-limitations.md` | official-docs | official | high | licenses | +| `supply-chain/2026-07-24-rustsec.md` | official-docs | official | critical | advisories | +| `supply-chain/2026-07-24-cargo-audit.md` | github-readme | official | critical | cargo-audit | +| `supply-chain/2026-07-24-sigstore-cosign-blob.md` | official-docs | official | high | signing | +| `supply-chain/2026-07-24-cargo-sbom-unstable.md` | official-docs | official | high | cargo-sbom | +| `supply-chain/2026-07-24-cargo-package-verification.md` | official-docs | official | high | package | diff --git a/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md b/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md new file mode 100644 index 00000000..95f928d0 --- /dev/null +++ b/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/attr.instrument.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tracing +stinger: rust-stinger +--- + +# `tracing::instrument` field capture + +## Summary +`#[instrument]` records function arguments by default, using `Value` or `Debug`. `skip` and `skip_all` explicitly exclude arguments, and replacement fields can record safe identifiers. This default makes unreviewed instrumentation a direct secret/prompt leakage risk at sensitive boundaries. + +## Key quotations / statistics +- "By default, all arguments to the function are included as fields" +- `skip_all` can "skip all arguments" + +## Version/date caveat +Retrieved against tracing 0.1.44; macro capture policy is current at access time. + +## Annotations for stinger-forge +- Critical source for a `skip_all`-first rule on provider, prompt, credential, and SQL boundaries. +- Add explicit allowlisted correlation/state fields rather than relying on Debug. + diff --git a/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md b/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md new file mode 100644 index 00000000..0cffcd7a --- /dev/null +++ b/.agents/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: subscriber +stinger: rust-stinger +--- + +# tracing library/subscriber ownership + +## Summary +Tracing libraries emit spans/events but executables install subscribers that collect and format them. The docs warn libraries not to set a global default because that conflicts with downstream executables. This creates a clean crate boundary: libraries describe structured events; daemon/CLI binaries own filtering, sinks, and output format. + +## Key quotations / statistics +- "Libraries should link only to the `tracing` crate" +- "libraries should not call `set_global_default()`" + +## Version/date caveat +Tracing 0.1.44 documentation; subscriber features and ecosystem layers vary independently. + +## Annotations for stinger-forge +- Grounds observability dependency direction and binary-owned initialization. +- Security/redaction review remains a peer gate even when field ownership is correct. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md new file mode 100644 index 00000000..1a2dfba4 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/atomiccommit.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: recovery +stinger: rust-stinger +--- + +# SQLite atomic commit and crash recovery + +## Summary +SQLite documents how rollback journals provide atomic commit across process, OS, and power failures, including hot-journal recovery. It also documents assumptions and failure modes around filesystem locking, sync behavior, file renames, and deletion of journals. SQLite's own confidence rests on fault-injecting VFS crash tests, not code inspection alone. + +## Key quotations / statistics +- "either all database changes within a single transaction occur or none" +- "crash tests ... simulate incomplete sector writes" + +## Version/date caveat +This page primarily describes rollback-journal mode; WAL atomicity uses a different mechanism documented separately. + +## Annotations for stinger-forge +- Strong evidence for crash/restart and filesystem-fault tests around local state. +- Preserve database, WAL, SHM, and journal files together during recovery/support operations. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md new file mode 100644 index 00000000..cfe565e1 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md @@ -0,0 +1,26 @@ +--- +source_url: https://sqlite.org/pragma.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: durability +stinger: rust-stinger +--- + +# SQLite PRAGMA durability controls + +## Summary +SQLite's PRAGMA reference defines `journal_mode`, `synchronous`, `busy_timeout`, foreign-key enforcement, and checkpoint controls. The durability contract changes by journal mode and synchronous level; `OFF` does not sync, while WAL plus `NORMAL` trades away recent-transaction durability on power loss. + +## Key quotations / statistics +- "you lose durability across power loss with synchronous NORMAL in WAL mode" +- With `synchronous=OFF`, SQLite proceeds "without syncing" + +## Version/date caveat +Official reference retrieved 2026-07-24; platform VFS behavior can still weaken guarantees. + +## Annotations for stinger-forge +- Use to require explicit, tested connection PRAGMAs rather than driver defaults. +- Final durability policy is an architecture/product decision and should be recorded. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md new file mode 100644 index 00000000..02a13e90 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/lang_transaction.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: transactions +stinger: rust-stinger +--- + +# SQLite transaction semantics + +## Summary +SQLite permits multiple simultaneous readers but only one write transaction. `BEGIN DEFERRED` delays lock acquisition and can fail when upgrading a read to a write; `BEGIN IMMEDIATE` attempts to acquire the write transaction at the start and returns `SQLITE_BUSY` if another writer is active. Nested `BEGIN` transactions are not supported. + +## Key quotations / statistics +- "Transactions created using BEGIN...COMMIT do not nest." +- "BEGIN IMMEDIATE might fail with SQLITE_BUSY" + +## Version/date caveat +SQLite official page published within the six-month research window. Exact busy behavior also depends on connection busy timeout and transaction duration. + +## Annotations for stinger-forge +- Critical for reservation/reconciliation write serialization and busy-retry design. +- Supports acquiring write intent before reading budget state when the operation must be atomic. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md new file mode 100644 index 00000000..b3143ac4 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/wal.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: wal +stinger: rust-stinger +--- + +# SQLite write-ahead logging + +## Summary +WAL mode separates writes from checkpoints, permits readers alongside a writer, and persists as a database property. Automatic checkpoints occur at a default threshold of 1000 pages. Long readers can prevent checkpoint completion and grow the WAL; `synchronous=NORMAL` can lose recent committed transactions after power loss even while preserving database consistency. + +## Key quotations / statistics +- "By default, SQLite does a checkpoint automatically" at 1000 pages. +- With `synchronous=NORMAL`, "transactions are no longer durable" across power failure. + +## Version/date caveat +Official SQLite page updated in the research window; durability claims depend on VFS/filesystem correctness. + +## Annotations for stinger-forge +- Grounds explicit journal, synchronous, checkpoint, and reader-lifetime choices. +- Contradicts any blanket claim that WAL plus NORMAL implies full power-loss durability. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md new file mode 100644 index 00000000..dcc861a0 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/sqlite/struct.SqliteConnectOptions.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: sqlx +stinger: rust-stinger +--- + +# SQLx SQLite connection options + +## Summary +`SqliteConnectOptions` exposes journal, locking, synchronous, busy-timeout, foreign-key, and statement settings. SQLx deliberately does not select a journal mode by default; WAL persists in the database and switching away from it may require an exclusive lock. The default busy timeout is five seconds. + +## Key quotations / statistics +- "SQLx does not set a journal mode by default" +- "The default busy timeout is 5 seconds." + +## Version/date caveat +SQLx latest docs at retrieval (the docs index reported 0.9.0). Verify APIs against the actually pinned SQLx release. + +## Annotations for stinger-forge +- Grounds a single audited connection-options builder and startup verification of effective PRAGMAs. +- Prevent per-connection configuration drift in pools. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md new file mode 100644 index 00000000..b3ef08b7 --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/trait.Connection.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: locking +stinger: rust-stinger +--- + +# SQLx custom transaction start + +## Summary +SQLx 0.9.0 exposes `Connection::begin_with` to begin a tracked transaction using a database-specific statement. This permits SQLite `BEGIN IMMEDIATE` while retaining the `Transaction` commit/rollback API. The function rejects statements that do not actually enter a transaction, which is safer than issuing an unrelated raw statement and assuming tracking. + +## Key quotations / statistics +- "Begin a new transaction with a custom statement." +- It errors if the statement "does not put the connection into a transaction." + +## Version/date caveat +This API appears in SQLx 0.9.0; SQLx 0.8-era projects need a version-specific alternative and should not copy the call blindly. + +## Annotations for stinger-forge +- Resolves the primary SQLx mechanism for write-intent acquisition before budget reads. +- Pair with bounded busy handling, conditional updates, and concurrency/crash tests. + diff --git a/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md new file mode 100644 index 00000000..74a7899d --- /dev/null +++ b/.agents/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: migrations +stinger: rust-stinger +--- + +# SQLx query macros and embedded migrations + +## Summary +SQLx provides compile-time checked query macros and `migrate!`, which embeds migrations into the binary. Query macros require a build-time schema connection or checked-in `.sqlx` offline metadata. Embedded migrations improve deployability but do not replace forward-only migration policy, crash tests, and schema-version compatibility checks. + +## Key quotations / statistics +- "The `migrate!` macro embeds migrations into the binary" +- "The `query!` macro allows for statically checked SQL queries" + +## Version/date caveat +SQLx latest docs at retrieval; offline metadata commands and migration macro rebuild behavior vary by release/build system. + +## Annotations for stinger-forge +- Supports compile-checked repository queries and migration packaging tests. +- Database schema review remains a peer boundary; this source covers Rust integration mechanics. + diff --git a/.agents/skills/rust-stinger/research/research-plan.md b/.agents/skills/rust-stinger/research/research-plan.md new file mode 100644 index 00000000..7c00d1ca --- /dev/null +++ b/.agents/skills/rust-stinger/research/research-plan.md @@ -0,0 +1,91 @@ +# Research Plan: rust-stinger + +- **Depth tier:** deep +- **Time window:** 2026-07-24 back to 2026-01-24 (6 months) +- **Page budget target:** 1,000 page-equivalents across official documentation sets, upstream repositories, release notes, and standards/tooling references +- **Source breadth target:** official language/toolchain documentation, upstream crate documentation, upstream GitHub repositories, SQLite specifications, security advisories, release/changelog material, standards/provenance specifications +- **Discovery caveat:** The initial queries below are reconstructed from the Command Brief's primary research targets and research questions. Research used Context7 documentation retrieval and direct official/upstream pages; this limitation is preserved in the final summary. + +## Initial queries (derived from the Command Brief) + +- "Rust Cargo workspace architecture MSRV feature unification platform support 2026" +- "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" +- "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" +- "Rust typed state machines replay prohibition safe promotion error boundaries 2026" +- "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" +- "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" +- "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" +- "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +## Expansion queries + +### Branch from "Rust Cargo workspace architecture MSRV feature unification platform support 2026" + +- "Cargo resolver version 3 workspace dependency inheritance feature unification official" +- "Rust MSRV policy rust-version Cargo official platform support tier policy" +- "Cargo workspace compile time crate boundaries feature flags official guidance" +- "Rust API Guidelines unsafe code guidelines Clippy rustfmt official" + +### Branch from "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" + +- "Tokio task cancellation safety JoinSet CancellationToken graceful shutdown official" +- "Tokio bounded mpsc backpressure reserve Permit shutdown channel official" +- "Axum with_graceful_shutdown streaming Body cancellation official" +- "Tower Service readiness load shed concurrency limit timeout buffer backpressure official" +- "Tokio time pause advance deterministic tests tracing official" + +### Branch from "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" + +- "SQLite BEGIN IMMEDIATE transaction locking WAL busy timeout synchronous official" +- "SQLite atomic commit crash recovery WAL checkpoint durability official" +- "SQLx SQLite transaction acquire begin immediate migrations official" +- "SQLite concurrent reservation budget oversubscription conditional update RETURNING official" +- "SQLx offline mode compile checked queries migrations locking upstream" + +### Branch from "Rust typed state machines replay prohibition safe promotion error boundaries 2026" + +- "Rust enum typestate state machine exhaustive matching official" +- "Rust ownership newtype sealed traits visibility architecture boundaries official" +- "Serde tagged enums deny unknown fields boundary validation official" +- "thiserror source transparent structured error official" + +### Branch from "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" + +- "tracing instrument skip fields redaction EnvFilter JSON official" +- "secrecy SecretString expose_secret Debug redaction official" +- "rustls dangerous configuration certificate verification official" +- "Rust TLS certificate roots platform verifier rustls official" + +### Branch from "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" + +- "Clap derive value enum exit codes JSON output shell completion official" +- "Clap error handling try_parse_from CommandFactory official" +- "Ratatui terminal init restore panic hook test backend official" +- "Ratatui snapshot testing event loop cancellation official" + +### Branch from "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" + +- "proptest state machine strategy shrinking persistence official" +- "Loom model concurrency atomics Arc Mutex limitations official" +- "cargo-nextest retries slow timeout archive junit official" +- "Criterion benchmark statistical confidence regression official" +- "Tokio test start_paused timeout cancellation fake server soak evidence official" + +### Branch from "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +- "cargo-dist installers checksums GitHub releases provenance official" +- "cargo-cyclonedx SBOM Rust official upstream" +- "cargo-auditable binary dependency metadata official upstream" +- "cargo-deny advisories licenses bans sources official" +- "RustSec advisory database cargo-audit withdrawn unmaintained official" +- "Sigstore cosign sign blob attest SBOM keyless official" + +## Research order and rationale + +1. Establish language, Cargo, MSRV, and platform constraints because every later recommendation depends on the supported compiler and target contract. +2. Resolve runtime/service ownership and failure behavior across Tokio, Axum, and Tower. +3. Resolve SQLite/SQLx transaction, locking, and crash-durability semantics. +4. Collect type-boundary, serialization, error, observability, secret, and TLS sources. +5. Collect operator-surface sources for Clap and Ratatui. +6. Collect deterministic, property, model-concurrency, benchmark, and soak-test evidence. +7. Close with packaging, provenance, SBOM, signature, advisory, and release evidence while preserving dependency/release/security peer ownership. diff --git a/.agents/skills/rust-stinger/research/research-summary.md b/.agents/skills/rust-stinger/research/research-summary.md new file mode 100644 index 00000000..f8caa1bb --- /dev/null +++ b/.agents/skills/rust-stinger/research/research-summary.md @@ -0,0 +1,68 @@ +# Research Summary: rust-stinger + +- **Depth tier consumed:** deep, completed as a concise authoritative packet rather than an open-ended crawl +- **Time window:** 2026-01-24 through 2026-07-24 (6 months), with stable canonical reference pages used where the governing specification predates the window +- **Source notes:** 56 +- **Research/control artifacts:** 4 (`research-plan.md`, `index.md`, `evidence-synthesis.md`, `research-summary.md`) +- **Total Markdown files:** 60 +- **Primary-source posture:** 55 official/upstream sources and 1 upstream practitioner-maintained GitHub project note (`cargo-auditable`); no community forum/Reddit source was needed + +## Files by subfolder + +| Subfolder | Source files | +|---|---:| +| `async/` | 10 | +| `boundaries/` | 3 | +| `cli-tui/` | 5 | +| `observability/` | 2 | +| `persistence/` | 7 | +| `rust-cargo/` | 8 | +| `security/` | 3 | +| `supply-chain/` | 11 | +| `testing/` | 7 | +| **Total** | **56** | + +## Coverage against the Command Brief + +- Rust/Cargo workspace architecture, feature unification, MSRV, toolchain, platform tiers, Clippy, and unsafe policy: covered. +- Tokio/Axum/Tower task ownership, cancellation safety, bounded backpressure, readiness, graceful shutdown, streaming bodies, and service testing: covered. +- SQLite/SQLx transactions, `BEGIN IMMEDIATE`, busy behavior, WAL, checkpointing, durability, atomic commit/crash recovery, connection options, compile-checked queries, and migrations: covered. +- Typed boundaries/state machines, Serde strictness/tagging, structured errors, non-forgeable verification markers: covered. +- tracing/subscriber ownership, secret wrappers, rustls safe/dangerous configuration and typestate: covered. +- Clap CLI parsing/exit behavior and Ratatui lifecycle/test architecture: covered. +- proptest, Loom, deterministic Tokio time, nextest, Criterion, failure/concurrency/migration/fake-provider and eight-hour-soak evidence model: covered. +- cargo-dist, cargo-cyclonedx, cargo-auditable, cargo-deny, RustSec/cargo-audit, Cargo SBOM precursors/package verification, and Sigstore/Cosign: covered with peer-boundary caveats. + +## Five most influential sources + +1. [`async/2026-07-24-tokio-select-cancellation.md`](async/2026-07-24-tokio-select-cancellation.md) — establishes that cancellation safety is an operation-level property and identifies the central replay/data-loss review boundary. +2. [`async/2026-07-24-tower-service-readiness.md`](async/2026-07-24-tower-service-readiness.md) — makes backpressure a resource-reservation contract and exposes the readiness-to-call cancellation edge. +3. [`persistence/2026-07-24-sqlite-transactions.md`](persistence/2026-07-24-sqlite-transactions.md) plus [`persistence/2026-07-24-sqlx-custom-transactions.md`](persistence/2026-07-24-sqlx-custom-transactions.md) — together establish the one-writer rule and the SQLx 0.9 mechanism for tracked `BEGIN IMMEDIATE` transactions. +4. [`security/2026-07-24-rustls-verification-markers.md`](security/2026-07-24-rustls-verification-markers.md) — supplies upstream precedent for private proof tokens preventing skipped safety checks. +5. [`testing/2026-07-24-proptest-state-machines.md`](testing/2026-07-24-proptest-state-machines.md) — supplies the reference-model, invariant, shrinking, and regression-seed pattern for quota/breaker/promotion state. + +## Open questions that survived research + +- Final platform/installer matrix and minimum OS baselines. +- Declared MSRV after the real dependency graph and features exist. +- Required SQLite power-loss durability and busy/contended-write UX. +- Final durable state/event schema for replay prohibition and promotion. +- TUI inclusion in the first milestone. +- Signing/attestation identity and publication authorization. +- Numeric eight-hour-soak thresholds. + +## Sources Forge should re-fetch at build time + +- Rust release index and platform support (toolchain/target drift). +- Tokio current/LTS policy (1.53.1 and 1.51.x were current at retrieval). +- SQLx `Connection::begin_with` and migration/query docs against the selected SQLx version. +- rustls stable docs to avoid using 0.24 development APIs. +- cargo-dist configuration/changelog and GitHub attestation eligibility. +- RustSec advisory database immediately before any release recommendation. + +## Blocked or incomplete research + +- No subject area is blocked. +- Raw web-crawl JSON and ranked discovery records were not produced. Context7 plus direct official/upstream retrieval was used; the limitation is recorded in the plan and synthesis. +- No source establishes a universal off-the-shelf eight-hour Rust soak harness. The synthesis therefore records a composable evidence model and leaves numeric thresholds to the product/release owners. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md new file mode 100644 index 00000000..ae859eb9 --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/guide/continuous-integration.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: ci +stinger: rust-stinger +--- + +# Cargo continuous integration guidance + +## Summary +Cargo's CI guide explicitly recommends verifying `rust-version`, testing dependency freshness, and pinning the compiler when warnings are denied because new toolchains can add warnings. It illustrates `cargo hack check --rust-version --workspace --all-targets` and a full-feature Clippy job. + +## Key quotations / statistics +- "When publishing packages that specify `rust-version`, it is important to verify the correctness of that field." +- "CI can fail due to new toolchain versions because there are limited compatibility guarantees around warnings." + +## Version/date caveat +The guide names third-party tools as examples, not as Rust project guarantees. + +## Annotations for stinger-forge +- Grounds separate pinned-toolchain, MSRV, latest-dependency, and target/feature checks. +- Peer boundary: CI topology remains the release/DevOps specialist's decision. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md new file mode 100644 index 00000000..f521634a --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/features.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: features +stinger: rust-stinger +--- + +# Cargo features and feature unification + +## Summary +Cargo features are additive and can be unified across dependency paths. Resolver v2 and later avoid several unwanted unifications for target-specific, build/proc-macro, and inactive dev dependencies, but feature coupling still requires deliberate crate boundaries and CI combinations. Default features are part of the public dependency contract unless callers disable them consistently. + +## Key quotations / statistics +- "Features should be additive." +- Resolver v2 "avoids unifying features" across several dependency categories. + +## Version/date caveat +Stable Cargo documentation; individual dependency feature sets can change without a workspace architecture change. + +## Annotations for stinger-forge +- Supports feature hygiene, `cargo tree -e features`, and targeted feature-matrix checks. +- Relevant to keeping TUI/provider/TLS capabilities out of core crates by default. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md new file mode 100644 index 00000000..d1fcb298 --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/resolver.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: resolver +stinger: rust-stinger +--- + +# Cargo dependency resolver + +## Summary +Cargo resolver version 3 is the Rust 2024 default and changes incompatible-Rust-version handling from `allow` to `fallback`. Resolver choice is global to the top-level workspace and dependency manifests cannot override it; virtual workspaces must set it explicitly. This is a workspace architecture constraint, not a per-crate preference. + +## Key quotations / statistics +- "`3` (`edition = `2024` default, requires Rust 1.84+)" +- "The resolver is a global option that affects the entire workspace." + +## Version/date caveat +Stable Cargo docs as of retrieval. Resolver v3 sets selection behavior but does not prove every selected dependency actually honors its MSRV. + +## Annotations for stinger-forge +- Inform the workspace manifest checklist and feature/MSRV audit. +- Warn that a virtual workspace must explicitly declare `resolver = "3"`. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md new file mode 100644 index 00000000..a377739d --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/rust-version.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: msrv +stinger: rust-stinger +--- + +# Cargo `rust-version` + +## Summary +Cargo's `rust-version` field declares the minimum supported compiler and participates in diagnostics and dependency resolution. Workspace members can have different policies, but shared dependencies and feature unification mean the lowest supported member can constrain the whole workspace. The declared value needs CI proof rather than being treated as descriptive metadata. + +## Key quotations / statistics +- "The resolver may take Rust version into account when picking dependencies." +- "All functionality, including binaries and API, are available on the supported Rust versions under every feature." + +## Version/date caveat +Stable Cargo documentation retrieved against the Rust 1.97 release line; resolver behavior depends on workspace resolver selection. + +## Annotations for stinger-forge +- Grounds MSRV declaration and verification rules. +- Supports testing all public feature combinations claimed to work at MSRV. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md new file mode 100644 index 00000000..1155d39a --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/clippy/continuous_integration/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: linting +stinger: rust-stinger +--- + +# Clippy in continuous integration + +## Summary +Official Clippy guidance recommends treating Clippy warnings as CI failures and using the same toolchain as compilation for compatibility. Because new lints appear over time, a pinned toolchain or an explicit upgrade process prevents unrelated stable updates from unexpectedly breaking release branches. + +## Key quotations / statistics +- "It is recommended to run Clippy on CI with `-Dwarnings`." +- "use Clippy from the same toolchain, that you use for compiling your crate" + +## Version/date caveat +Lint inventories evolve with the compiler; a clean result is toolchain-specific. + +## Annotations for stinger-forge +- Supports the standard Rust verification gate and toolchain pinning. +- Avoid enabling all `restriction` lints indiscriminately; the Clippy index warns they may conflict. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md new file mode 100644 index 00000000..b1fb7d7a --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/rustc/platform-support.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: targets +stinger: rust-stinger +--- + +# Rust platform support + +## Summary +Rust classifies targets into three tiers with materially different build and test guarantees. Tier 1 targets build and pass tests in Rust CI; Tier 2 targets are guaranteed to build but may not be tested. A product target matrix therefore needs its own runtime/install/uninstall proof even when the compiler labels a target supported. + +## Key quotations / statistics +- "Tier 1 targets can be thought of as `guaranteed to work`." +- Tier 2 targets "can be thought of as `guaranteed to build`." + +## Version/date caveat +Target tiers and OS baselines can change between Rust releases; re-check during release planning. + +## Annotations for stinger-forge +- Use to separate compiler support from product support evidence. +- Supports explicit macOS/Linux/Windows target triples and host-tool requirements. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md new file mode 100644 index 00000000..46def630 --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md @@ -0,0 +1,26 @@ +--- +source_url: https://blog.rust-lang.org/releases/ +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: toolchain +stinger: rust-stinger +--- + +# Rust release announcements + +## Summary +The official release index records Rust 1.97.1 on 2026-07-16 and Rust 1.97.0 on 2026-07-09. It provides the current stable anchor for any 2026 toolchain discussion, but it does not itself establish the product's MSRV; that remains a deliberate compatibility decision verified independently. + +## Key quotations / statistics +- "July 16 | Announcing Rust 1.97.1" +- 2026 releases listed in the six-month window: 1.93.0 through 1.97.1. + +## Version/date caveat +Current stable at retrieval time; Rust releases on a regular cadence, so re-check immediately before freezing a toolchain. + +## Annotations for stinger-forge +- Use as the current-version anchor in toolchain/MSRV guidance. +- Distinguish "current stable" from the separately declared `package.rust-version` and CI-tested MSRV. + diff --git a/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md new file mode 100644 index 00000000..cf491309 --- /dev/null +++ b/.agents/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: unsafe +stinger: rust-stinger +--- + +# Unsafe Rust + +## Summary +The Rust Book defines the five operations requiring `unsafe`, stresses that unsafe code transfers proof obligations to the programmer, and recommends keeping unsafe blocks small behind safe abstractions. This supports a default `forbid(unsafe_code)` posture with narrowly reviewed exceptions. + +## Key quotations / statistics +- "Keep `unsafe` blocks small" +- "wrapping unsafe code in a safe function is a common abstraction" + +## Version/date caveat +The current Book uses the Rust 2024 edition. Low-level memory-model details must be checked against the Reference/Nomicon, not inferred from examples. + +## Annotations for stinger-forge +- Grounds unsafe inventory, documented invariants, and targeted tests. +- Note that the old Unsafe Code Guidelines reference describes itself as largely abandoned. + diff --git a/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md b/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md new file mode 100644 index 00000000..b7df5e59 --- /dev/null +++ b/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tls +stinger: rust-stinger +--- + +# rustls configuration typestate + +## Summary +rustls 0.23.42 uses builder typestates to require protocol/provider, peer verification, and certificate decisions in order. Normal builders select safe default protocol versions; custom verifiers sit behind a deliberately dangerous API. The builder demonstrates compile-time enforcement of required configuration steps. + +## Key quotations / statistics +- "use rustls' default cryptographic provider and safe defaults" +- Builder state "ensure[s] at compile time that each required configuration item is provided exactly once" + +## Version/date caveat +The stable docs reported rustls 0.23.42; rustls.dev also exposed 0.24.0-dev.0, so do not code to development APIs accidentally. + +## Annotations for stinger-forge +- Strong upstream example for typestate and TLS-safe defaults. +- Custom certificate verification requires explicit Security review. + diff --git a/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md b/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md new file mode 100644 index 00000000..b92aa6da --- /dev/null +++ b/.agents/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustls.dev/src/rustls/verify.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: typestate +stinger: rust-stinger +--- + +# rustls verification marker types + +## Summary +rustls uses non-constructible marker values to encode that certificate-chain and handshake-signature verification occurred before traffic state is reached. The source explicitly frames this as protection against omitted-check control flow. This is directly relevant as prior art for non-forgeable replay/promotion authorization tokens. + +## Key quotations / statistics +- "bind the fact some verification ... has taken place into protocol states" +- "compiler check that there are no `goto fail`-style elisions" + +## Version/date caveat +Source view from rustls.dev may track development rather than the pinned 0.23 release; use the pattern, not an internal type dependency. + +## Annotations for stinger-forge +- Key evidence for private constructors and capability tokens representing completed checks. +- Do not couple the router's state machine to rustls internal marker types. + diff --git a/.agents/skills/rust-stinger/research/security/2026-07-24-secrecy.md b/.agents/skills/rust-stinger/research/security/2026-07-24-secrecy.md new file mode 100644 index 00000000..c323990a --- /dev/null +++ b/.agents/skills/rust-stinger/research/security/2026-07-24-secrecy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/secrecy/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: secrets +stinger: rust-stinger +--- + +# secrecy secret wrappers + +## Summary +secrecy 0.10.3 wraps secret values so access requires an explicit exposure trait, reduces accidental Debug/logging/copying, and wipes supported owned values on drop. Optional Serde support permits deserialization but explicitly cannot prevent upstream deserializers from making copies. It is defense-in-depth, not a complete secret store. + +## Key quotations / statistics +- access is "only available through a special `ExposeSecret` trait" +- Serde support "doesn't guarantee ... additional copies" are not made. + +## Version/date caveat +MSRV is Rust 1.60; the project states future MSRV changes are outside SemVer guarantees but accompany a minor bump. + +## Annotations for stinger-forge +- Supports secret newtypes and narrow exposure sites. +- Secret acquisition/storage policy remains Security/platform-owned. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md new file mode 100644 index 00000000..7044e61a --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rustsec/rustsec/blob/main/cargo-audit/README.md +retrieved_on: 2026-07-24 +source_type: github-readme +authority: official +relevance: critical +topic: cargo-audit +stinger: rust-stinger +--- + +# RustSec cargo-audit + +## Summary +cargo-audit checks Cargo.lock against RustSec and can inspect binaries built with cargo-auditable. Its experimental `fix` command modifies manifests, while ignore entries require application-specific justification. The README states binary scanning is incomplete for ordinary optimized binaries but accurate when auditable metadata is embedded. + +## Key quotations / statistics +- "Audit your dependencies for crates with security vulnerabilities" +- Without auditable metadata it may miss "roughly half of the Rust dependencies" + +## Version/date caveat +README currently requires Rust 1.74 or later; pin cargo-audit independently from the product MSRV. + +## Annotations for stinger-forge +- Supports lockfile and shipped-binary audit evidence. +- Never run automatic fix as part of an evidence-only release gate without review. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md new file mode 100644 index 00000000..675c4a35 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rust-secure-code/cargo-auditable +retrieved_on: 2026-07-24 +source_type: github-readme +authority: practitioner +relevance: high +topic: auditability +stinger: rust-stinger +--- + +# cargo-auditable + +## Summary +cargo-auditable embeds Cargo dependency version information in production binaries so deployed artifacts can be scanned later. It integrates with cargo-dist and experimental Cargo SBOM precursor output. The project recommends recording artifact hash, Cargo.lock, compiler/LLVM versions, and build date alongside binaries because embedded dependency metadata alone is not complete provenance. + +## Key quotations / statistics +- "Make production Rust binaries auditable" +- record "the hash of every executable" with build metadata. + +## Version/date caveat +The upstream README mentions nightly `-Z sbom`; nightly Cargo features are not a stable release foundation without explicit approval. + +## Annotations for stinger-forge +- Supports artifact-to-lockfile traceability and post-build `cargo audit bin` checks. +- Treat it as complementary to external SBOMs and attestations. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md new file mode 100644 index 00000000..55fe7b91 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/cargo-cyclonedx/0.5.9/source/CHANGELOG.md +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: sbom +stinger: rust-stinger +--- + +# cargo-cyclonedx 0.5.9 changelog + +## Summary +cargo-cyclonedx 0.5.9, released 2026-03-19, added `SOURCE_DATE_EPOCH` support for reproducible SBOM timestamps and honors `CARGO_BUILD_TARGET` for target identity. It also fixed sparse-registry and package-URL correctness. SBOM generation still requires validation against the shipped artifact and selected features/target. + +## Key quotations / statistics +- "Support for the `SOURCE_DATE_EPOCH` environment variable" +- "`CARGO_BUILD_TARGET` ... determine[s] the target platform" + +## Version/date caveat +Version 0.5.9 is the current release reported at retrieval; coverage/format support should be checked before freezing. + +## Annotations for stinger-forge +- Strong 2026 source for reproducible target-specific CycloneDX generation. +- Final SBOM completeness/policy judgment belongs to dependency/release peers. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md new file mode 100644 index 00000000..fc653b53 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: policy +stinger: rust-stinger +--- + +# cargo-deny checks + +## Summary +cargo-deny evaluates licenses, duplicate/banned crates, advisories/yanks, and dependency sources from the resolved crate graph. Running the umbrella check uses defaults for sections not configured, so a repository needs an explicit reviewed policy rather than assuming tool defaults match its legal/security constraints. + +## Key quotations / statistics +- Checks include "licenses", "bans", "advisories", and "sources". +- Advisories cover vulnerabilities, unmaintained crates, and yanked versions. + +## Version/date caveat +Policy/schema changes across cargo-deny versions; pin both tool and configuration version. + +## Annotations for stinger-forge +- Supports Rust-side evidence generation for dependency peer review. +- The Bee may run/report it but must not own final license/advisory exceptions. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md new file mode 100644 index 00000000..7472fa31 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/licenses/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: licenses +stinger: rust-stinger +--- + +# cargo-deny license check limitations + +## Summary +cargo-deny evaluates SPDX expressions and license files but explicitly cannot exhaustively prove a crate's legal licensing. It trusts manifest/package evidence and documents absence, mismatch, and unconventional-placement gaps. Clarifications are hash-bound evidence, not permanent blanket waivers. + +## Key quotations / statistics +- "does not exhaustively search the entirety of the source code" +- It makes a "good-faith assumption" that crates define licensing correctly. + +## Version/date caveat +License-list versions and cargo-deny detection behavior evolve; legal review cannot be replaced by a passing scan. + +## Annotations for stinger-forge +- Prevent overclaiming `cargo deny` as legal clearance. +- Route exceptions and notices to dependency/legal/release peers with exact evidence. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md new file mode 100644 index 00000000..3ff88414 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/supplychain-security/attestations/github.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: provenance +stinger: rust-stinger +--- + +# cargo-dist GitHub artifact attestations + +## Summary +dist can enable GitHub artifact attestations, creating verifiable provenance linked to GitHub Actions and Sigstore. The feature is disabled by default and has repository/plan limitations. Verification uses `gh attestation verify`, so evidence must include both generation and consumer verification transcripts. + +## Key quotations / statistics +- "Artifact Attestations is disabled by default" +- Verification is supported via "`gh attestation verify`" + +## Version/date caveat +The page labels GitHub Artifact Attestations public beta and records eligibility constraints that may change. + +## Annotations for stinger-forge +- Supports provenance as an explicit opt-in release gate, not an assumed dist feature. +- Signing identity/workflow permissions remain release/security peer concerns. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md new file mode 100644 index 00000000..b239d4fa --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/reference/config.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: packaging +stinger: rust-stinger +--- + +# cargo-dist artifact and installer configuration + +## Summary +cargo-dist configures target builds, archives, checksums, source tarballs, extra artifacts, and shell/PowerShell/npm/Homebrew/MSI installers. It can integrate cargo-auditable and cargo-cyclonedx. Checksums are unsigned integrity values; the docs explicitly describe stronger signed checksums as future work. + +## Key quotations / statistics +- Default checksum is "sha256". +- "Future work is planned to support more robust signed checksums." + +## Version/date caveat +Current docs include settings introduced through dist 0.31-era behavior; pin the generator because generated workflows/installers change. + +## Annotations for stinger-forge +- Grounds release manifest, artifact naming, installer matrix, and checksum evidence. +- Release topology/publication/signing authorization remains with the release peer. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md new file mode 100644 index 00000000..91f1b2d0 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/commands/cargo-package.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: package +stinger: rust-stinger +--- + +# Cargo package verification + +## Summary +`cargo package` builds a distributable crate archive, lists controlled contents, injects best-effort VCS metadata, and rebuilds the extracted package to verify a clean package. The VCS metadata does not prove source provenance, and `--no-verify`/`--allow-dirty` weaken evidence. + +## Key quotations / statistics +- It rebuilds "from scratch" from the package. +- "the provenance of the package is not verified" + +## Version/date caveat +Stable Cargo 1.97-era docs; binary release archives produced by dist have separate contents and verification. + +## Annotations for stinger-forge +- Supports package-content and clean-build checks for publishable crates. +- Do not confuse crate packaging proof with signed binary artifact provenance. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md new file mode 100644 index 00000000..e9bcda24 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/unstable.html#sbom +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: cargo-sbom +stinger: rust-stinger +--- + +# Cargo unstable SBOM precursors + +## Summary +Nightly Cargo's `-Z sbom` emits per-artifact JSON precursor files containing dependencies, target, features, and compiler data. These are inputs for SBOM tools, not complete standardized SBOMs. Because the feature is unstable and requires nightly, a stable release pipeline should treat it as supplemental unless explicitly approved. + +## Key quotations / statistics +- "generate so-called SBOM pre-cursor files" +- Files contain "dependencies, target, features and the used rustc compiler" + +## Version/date caveat +Unstable Cargo feature tracked by issue/RFC; schema and availability may change without stable guarantees. + +## Annotations for stinger-forge +- Record as optional deeper artifact evidence. +- Prefer stable cargo-cyclonedx/cargo-auditable paths for baseline release guidance. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md new file mode 100644 index 00000000..5053b24a --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustsec.org/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: advisories +stinger: rust-stinger +--- + +# RustSec Advisory Database + +## Summary +RustSec is the canonical community-maintained advisory database for crates.io packages and supports Cargo.lock auditing through cargo-audit and automation. Findings are time-dependent because the database changes after a build; release evidence needs a reviewed-on timestamp and repeatable lockfile input. + +## Key quotations / statistics +- "repository of security advisories filed against Rust crates" +- Maintained by the "Rust Secure Code Working Group" + +## Version/date caveat +Advisory results are a point-in-time snapshot; re-run at release and in ongoing maintenance. + +## Annotations for stinger-forge +- Require recorded database/update time and lockfile hash with audit evidence. +- Security/dependency peers own disposition, ignore expiry, and remediation acceptance. + diff --git a/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md new file mode 100644 index 00000000..dc01d8e6 --- /dev/null +++ b/.agents/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.sigstore.dev/cosign/signing/signing_with_blobs/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: signing +stinger: rust-stinger +--- + +# Cosign blob signing + +## Summary +Cosign signs ordinary files with keyless OIDC identities, local/KMS/hardware-backed keys, and emits a recommended bundle containing signature, certificate, and transparency-log proof. Noninteractive signing can create external effects and identity records, so it must remain an explicitly authorized release step. + +## Key quotations / statistics +- "using a bundle is the recommended way of signing a blob" +- The bundle includes "proof of transparency log inclusion" + +## Version/date caveat +Sigstore public infrastructure, identity claims, and command flags can change; capture the CLI version and verification policy. + +## Annotations for stinger-forge +- Supports signing/verification transcript requirements, not automatic invocation. +- Signing identity and publication remain peer/user-authorized boundaries. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md new file mode 100644 index 00000000..da0b82ba --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md @@ -0,0 +1,26 @@ +--- +source_url: https://bheisler.github.io/criterion.rs/book/analysis.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: benchmark +stinger: rust-stinger +--- + +# Criterion analysis process + +## Summary +Criterion performs warmup, measurement, statistical analysis, and comparison to saved baselines. It retains outliers, uses regression and bootstrap confidence intervals, and applies configurable significance/noise thresholds. Results still require a stable environment; statistical sophistication does not eliminate host noise. + +## Key quotations / statistics +- "Each benchmark ... goes through four phases" +- "outlier samples are not dropped" + +## Version/date caveat +Criterion docs reported crate 0.8.2 elsewhere in the corpus. The project warns virtualized CI can be too noisy for reliable wall-time regressions. + +## Annotations for stinger-forge +- Use for controlled local/release-host microbenchmarks and saved evidence. +- Eight-hour soak evidence is a distinct workload with invariants/resource telemetry, not a Criterion benchmark. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-loom.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-loom.md new file mode 100644 index 00000000..2745add5 --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-loom.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/loom/latest/loom/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: loom +stinger: rust-stinger +--- + +# Loom concurrency model checking + +## Summary +Loom 0.7.2 deterministically explores valid thread interleavings under a modeled memory model. Code under test must use Loom replacement synchronization types; unmodeled operations are invisible. State spaces grow exponentially, so Loom is best applied to small concurrency primitives with controlled preemption bounds and separate release-mode jobs. + +## Key quotations / statistics +- "runs tests many times, permuting the possible concurrent executions" +- "All sources of non-determism must be via loom types" + +## Version/date caveat +Loom documents limitations for relaxed ordering, hidden operations, and combinatorial explosion; passing Loom is not universal concurrency proof. + +## Annotations for stinger-forge +- Use selectively for small reservation/permit/task-state primitives. +- Do not wrap ordinary database/business logic in Loom merely to claim model checking. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md new file mode 100644 index 00000000..a5d135bd --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md @@ -0,0 +1,26 @@ +--- +source_url: https://nexte.st/docs/features/retries/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: flakiness +stinger: rust-stinger +--- + +# Nextest retries and flaky results + +## Summary +Nextest labels tests that pass only after retry as flaky and can make flaky outcomes fail the profile. JUnit output distinguishes flaky and rerun failures. This supports visibility while preserving a strict default for correctness/concurrency tests. + +## Key quotations / statistics +- "If a test succeeds during a retry, the test is marked flaky." +- "Flaky test detection is integrated with nextest's JUnit support." + +## Version/date caveat +Behavior described includes versioned JUnit changes; confirm the pinned nextest release's config schema. + +## Annotations for stinger-forge +- Require `flaky-result = "fail"` for release evidence unless a peer-approved quarantine exists. +- Never use retries to mask model, migration, or cancellation races. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest.md new file mode 100644 index 00000000..394ee869 --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-nextest.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.nexte.st/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: nextest +stinger: rust-stinger +--- + +# cargo-nextest capabilities + +## Summary +cargo-nextest supplies parallel test execution, per-test settings, timeouts, retries/flaky classification, archives/partitions, record/replay, and JUnit output across major platforms. It does not run doctests, which remain a separate `cargo test --doc` step. + +## Key quotations / statistics +- "Automatically retry some tests, mark them as heavy, run them serially" +- "Doctests are currently not supported" + +## Version/date caveat +Feature availability can depend on nextest version and execution platform; pin the runner used for release evidence. + +## Annotations for stinger-forge +- Grounds profiles for unit/integration/slow/soak classes and explicit doctest coverage. +- Retries must expose flakiness, not convert a nondeterministic gate into a silent pass. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md new file mode 100644 index 00000000..6f58e586 --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: properties +stinger: rust-stinger +--- + +# Proptest guide + +## Summary +The upstream guide covers strategies, shrinking, failure persistence, configuration, and state-machine testing. Property tests are most useful for invariant-rich inputs and transition sequences; they supplement rather than replace example-based contract tests whose exact output is part of a public API. + +## Key quotations / statistics +- Guide sections include "Shrinking Basics" and "Failure Persistence". +- The guide includes dedicated "State Machine testing" material. + +## Version/date caveat +The guide reflects upstream main documentation; exact APIs must be checked against the pinned crate release. + +## Annotations for stinger-forge +- Supports corpus persistence and reproducible seeds as evidence artifacts. +- Define invariants and input strategies in domain/test-support crates, not production adapters. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md new file mode 100644 index 00000000..31b60956 --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/state-machine.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: proptest +stinger: rust-stinger +--- + +# Proptest state-machine testing + +## Summary +Proptest state-machine testing generates sequences of valid transitions from a reference model, applies them to the system under test, checks postconditions/invariants, and shrinks failures to a minimal reproducer. It persists regression seeds. Current upstream support is sequential; concurrency behavior needs another technique such as Loom or explicit multi-client integration tests. + +## Key quotations / statistics +- "checking properties of a system under test ... against an abstract reference state machine" +- "only sequential strategy is supported" + +## Version/date caveat +State-machine support lives in the separate `proptest-state-machine` crate and may not version-lock with all proptest releases. + +## Annotations for stinger-forge +- Primary evidence for quota, reservation, reconciliation, breaker, pin, and promotion model tests. +- Pair with deterministic persistence fixtures and independent concurrency evidence. + diff --git a/.agents/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md b/.agents/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md new file mode 100644 index 00000000..67495488 --- /dev/null +++ b/.agents/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/testing +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: faketime +stinger: rust-stinger +--- + +# Tokio deterministic time testing + +## Summary +Tokio test utilities pause the runtime clock and advance timer-driven futures when no other work can progress. `#[tokio::test(start_paused = true)]` makes backoff, timeout, breaker, pin, and promotion timing tests fast and deterministic, provided production time access is routed through Tokio time or an injected clock. + +## Key quotations / statistics +- "Pausing time has the effect that any time-related future may become ready early." +- `start_paused` requires the `test-util` feature. + +## Version/date caveat +Only Tokio's clock is paused; `std::time` and external systems do not automatically follow it. + +## Annotations for stinger-forge +- Critical source for fake-clock tests and avoiding wall-clock sleeps. +- Explicitly yield/advance and assert temporal ordering, not elapsed host time. + diff --git a/.agents/skills/rust-stinger/templates/acceptance-slice-checklist.md b/.agents/skills/rust-stinger/templates/acceptance-slice-checklist.md new file mode 100644 index 00000000..456968f0 --- /dev/null +++ b/.agents/skills/rust-stinger/templates/acceptance-slice-checklist.md @@ -0,0 +1,16 @@ +# Rust acceptance slice checklist: {{slice_name}} + +- [ ] Read repository instructions, PRD/ADR/ledger, criteria, gates, and current Security/Quality evidence. +- [ ] Confirm repository/worktree and exact owned paths. +- [ ] Preserve unrelated and concurrent edits. +- [ ] Map each changed path and test to {{AC_IDS}}. +- [ ] Inventory crate/features/targets/tasks/channels/migrations/errors/config/logs/unsafe. +- [ ] Record version-sensitive decisions and revalidation points. +- [ ] Add a focused failing test before implementation. +- [ ] Prove cancellation, backpressure, retry/replay, shutdown, and cleanup where affected. +- [ ] Prove transactions, migrations, idempotency, concurrency, and crash recovery where affected. +- [ ] Use fake providers/fixtures unless a live gate is explicitly authorized. +- [ ] Run format, compile/check, Clippy, tests, docs, and affected specialized gates. +- [ ] Generate release evidence locally without signing/publishing unless authorized. +- [ ] Route Security, rerun affected checks after fixes, then route Quality. +- [ ] Report exact commands, results, external effects, limitations, blockers, and rollback/recovery. diff --git a/.agents/skills/rust-stinger/templates/implementation-handoff.md b/.agents/skills/rust-stinger/templates/implementation-handoff.md new file mode 100644 index 00000000..c4b6b5cc --- /dev/null +++ b/.agents/skills/rust-stinger/templates/implementation-handoff.md @@ -0,0 +1,53 @@ +# Rust implementation handoff: {{slice_name}} + +## Outcome + +{{what_is_now_true}} + +## Authority and scope + +- Repository/worktree: `{{absolute_path}}` +- Source authority: `{{prd_or_adr_path}}` +- Owned paths: {{owned_paths}} +- Gates consumed: {{gate_ids_or_none}} +- Concurrent/user edits preserved: {{evidence}} + +## Acceptance evidence + +- {{AC_ID}}: {{command_test_or_artifact}} — {{PASS_FAIL_BLOCKED}} + +## Changed paths + +- `{{path}}` — {{reason}} + +## Verification + +- `{{exact_command}}` — {{PASS_FAIL_BLOCKED}} + +## Safety and operations + +- External effects used: {{none_or_explicit_authorization_and_effect}} +- Async/shutdown/replay: {{evidence}} +- Migration/rollback/recovery: {{evidence}} +- Secrets/prompts/logging/diagnostics: {{evidence}} +- Unsafe inventory: {{none_or_review_reference}} + +## Revalidation points + +- Toolchain/MSRV/targets: {{current_evidence_or_owner_decision}} +- Dependency/runtime APIs: {{current_evidence_or_owner_decision}} +- Durability/contention: {{current_evidence_or_owner_decision}} +- Release/signing/soak: {{current_evidence_or_owner_decision}} + +## Peer handoffs and remaining gates + +- Security: {{ready_or_blocker}} +- Affected-check rerun after Security: {{commands_or_pending}} +- Quality: {{ready_only_after_security_and_reruns}} +- Protocol/platform/database/dependency/release: {{owner_and_open_item}} + +## Blocker, if any + +- Gate/owner: {{gate_and_owner}} +- Affected criteria: {{AC_IDS}} +- First authorized next action: {{next_action}} diff --git a/.agents/skills/rust-stinger/templates/release-evidence-manifest.yaml b/.agents/skills/rust-stinger/templates/release-evidence-manifest.yaml new file mode 100644 index 00000000..9b030b14 --- /dev/null +++ b/.agents/skills/rust-stinger/templates/release-evidence-manifest.yaml @@ -0,0 +1,63 @@ +schema_version: "{{schema_version}}" +release_candidate: "{{version_or_commit}}" +generated_at: "{{ISO_8601_UTC}}" +external_effects_authorized: {{true_or_false}} +authorization_reference: "{{reference_or_NONE}}" + +source: + repository: "{{repository}}" + commit: "{{commit_sha}}" + dirty: {{true_or_false}} + lockfile_sha256: "{{sha256}}" + toolchain: "{{rustc_and_cargo_versions}}" + msrv_status: "{{PROVEN_UNDECIDED_NOT_CLAIMED}}" + +artifacts: + - target: "{{rust_target_triple}}" + path: "{{artifact_path}}" + sha256: "{{sha256}}" + build_command: "{{exact_command}}" + build_result: "{{PASS_FAIL_BLOCKED}}" + runtime_smoke: "{{evidence}}" + install_transcript: "{{path_or_NOT_RUN}}" + uninstall_transcript: "{{path_or_NOT_RUN}}" + +verification: + formatting: "{{command_and_result}}" + clippy: "{{command_and_result}}" + unit_contract_integration: "{{command_and_result}}" + doctests: "{{command_and_result}}" + property_model_concurrency: "{{command_and_result}}" + migrations_crash_recovery: "{{command_and_result}}" + benchmarks: "{{command_and_result}}" + soak: "{{command_result_thresholds_or_BLOCKED}}" + +supply_chain: + sbom: + path: "{{path_or_NOT_GENERATED}}" + tool_version: "{{version}}" + sha256: "{{sha256}}" + advisories: + database_updated_at: "{{ISO_8601_UTC}}" + command: "{{exact_command}}" + result: "{{PASS_FAIL_REVIEW_REQUIRED}}" + dependency_license_source_scan: "{{path_command_and_result}}" + embedded_audit_metadata: "{{evidence_or_NOT_ENABLED}}" + +provenance: + signing_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + attestation_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + signer_identity: "{{identity_or_NONE}}" + verification_transcript: "{{path_or_NONE}}" + +peer_handoffs: + security: "{{owner_status_report}}" + dependency_license: "{{owner_status_report}}" + release_devops: "{{owner_status_report}}" + quality: "{{owner_status_report_after_security}}" + +open_gates: + - id: "{{gate_id}}" + owner: "{{owner}}" + blocker: "{{missing_decision_or_evidence}}" + next_action: "{{first_authorized_action}}" diff --git a/.agents/skills/rust-stinger/templates/rust-decision-log.md b/.agents/skills/rust-stinger/templates/rust-decision-log.md new file mode 100644 index 00000000..d53a705d --- /dev/null +++ b/.agents/skills/rust-stinger/templates/rust-decision-log.md @@ -0,0 +1,25 @@ +# Rust decision log + +| Decision | Chosen value | Evidence date | Source or test | Revalidate when | Owner | +|---|---|---|---|---|---| +| Toolchain pin | {{value}} | {{YYYY-MM-DD}} | {{source_or_command}} | Before upgrade/release | {{owner}} | +| MSRV | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{feature_matrix_command}} | Dependency/feature change | {{owner}} | +| Product targets/baselines | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{runtime_install_evidence}} | Release matrix change | {{owner}} | +| Tokio line | {{value}} | {{YYYY-MM-DD}} | {{support_policy_and_tests}} | Runtime upgrade | {{owner}} | +| SQLx transaction API | {{value}} | {{YYYY-MM-DD}} | {{selected_version_docs_and_tests}} | SQLx upgrade | {{owner}} | +| SQLite PRAGMAs | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{durability_decision_and_crash_tests}} | Persistence policy change | {{owner}} | +| rustls configuration | {{value}} | {{YYYY-MM-DD}} | {{stable_docs_and_security_review}} | rustls/root-policy change | {{owner}} | +| Package generator | {{value}} | {{YYYY-MM-DD}} | {{version_and_diff_review}} | Generator upgrade | {{owner}} | +| Signing/attestation | {{value_or_UNAUTHORIZED}} | {{YYYY-MM-DD}} | {{approval_and_verification_policy}} | Every release | {{owner}} | +| Soak thresholds | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{performance_SLO_source}} | Workload/platform change | {{owner}} | + +## Rationale and alternatives + +### {{decision_name}} + +- Context: {{context}} +- Decision: {{decision}} +- Evidence: {{evidence}} +- Alternatives: {{alternatives}} +- Consequences: {{consequences}} +- Peer approval/gate: {{approval_or_open_gate}} diff --git a/.claude/agents/rust-worker-bee.md b/.claude/agents/rust-worker-bee.md new file mode 100644 index 00000000..c60d75c5 --- /dev/null +++ b/.claude/agents/rust-worker-bee.md @@ -0,0 +1,111 @@ +--- +name: "rust-worker-bee" +description: "Rust implementation and code-review specialist for production `*.rs`, `Cargo.toml`, Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence. Use proactively when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or a PR touches Rust/Cargo surfaces. Do NOT invoke to invent HTTP/MCP semantics, approve Security or dependency/license policy, design CI topology, author final Quality, or perform unauthorized live/provider/release effects." +--- + +# Rust Worker Bee + +Before doing anything else, read your paired Stinger at `../skills/rust-stinger/SKILL.md` in full and follow it as your operating manual. Stay within the exact scope and file ownership assigned by the parent orchestrator. Preserve unrelated and concurrent edits. Return concise acceptance-linked implementation and verification evidence to the parent thread. + +## Identity & responsibility + +rust-worker-bee is the roster's implementation and code-review owner for production Rust systems. It owns bounded Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against already approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, dispose of dependency/license findings, design CI topology, issue final Quality acceptance, or authorize live credentials, paid traffic, signing, publication, or release effects. + +## Paired Stinger + +[`.claude/skills/rust-stinger/`](../skills/rust-stinger/) + +Read `../skills/rust-stinger/SKILL.md` in full first. It is the master index. Then read the guides and reusable artifacts named by the selected procedure steps. + +## Activation contract + +Activate proactively when the assigned implementation or review touches: + +- Rust source (*.rs), Cargo.toml, Cargo.lock, Cargo workspaces, rust-toolchain*, build.rs, crate migrations, features, targets, or Rust release configuration. +- Tokio task ownership, cancellation, backpressure, streams, timeouts, retries, shutdown, Axum routes/bodies, or Tower services/middleware. +- SQLx/SQLite transactions, migrations, idempotency, concurrency, durability mechanics, crash recovery, or persisted state machines. +- Clap commands, deterministic exit/output contracts, an explicitly scoped Ratatui client, Rust unit/property/contract/integration/concurrency/failure/soak tests, or local Rust packaging evidence. +- Requests such as "implement this in Rust", "review this Cargo workspace", "fix this Tokio service", "audit this SQLx transaction", or a PRD slice whose accepted architecture requires Rust. + +Do not act as final authority for HTTP/MCP/provider semantics, Security acceptance, schema architecture, product/provider policy, dependency/license/advisory disposition, CI/CD topology, release/signing/publication, or implementation-to-PRD Quality. Implement an approved contract, produce evidence, and hand those decisions to their owners. + +## Procedure + +1. Reconstruct authority and ownership. Read repository instructions, the exact PRD/sub-PRD, ADRs, execution ledger rows, acceptance criteria, gates, current Security/Quality evidence, worktree state, and assigned paths. Build an acceptance-to-path-to-proof map with `guides/00-authority-and-principles.md`. Do not start blocked or deferred work. +2. Inspect before editing. Use `guides/01-inspect-workspace.md` to inventory the Cargo graph, toolchain/MSRV claims, features, targets, crate boundaries, unsafe/panic paths, tasks/channels, configuration, migrations, SQL, logs, secrets, tests, benchmarks, and release files. Record missing tools as blockers instead of installing them implicitly. +3. Choose the smallest coherent design with `guides/02-design-workspace-and-types.md`: one owner per invariant, edge types at edges, validated domain types, structured redacted errors, private proof tokens, additive/default-off optional features, and no provider acquisition of harness agency. Escalate an unapproved protocol or architecture decision. +4. Implement a bounded test-first slice with `guides/03-implement-bounded-slices.md` and `templates/acceptance-slice-checklist.md`. Add the focused failing proof, patch only owned paths, run the narrow gate, and map every change/result to an acceptance criterion. +5. Where affected, prove task owners, bounded admission, cancellation safety, channel/Tower reservations, ordering, visibility/replay, timeout, retry, disconnect cleanup, and joined shutdown using `guides/04-prove-async-streams.md`. Never transparently replay after visible output or a harness-visible tool call unless the approved contract explicitly permits it. +6. Where affected, prove SQLx/SQLite transaction intent, conditional guards, idempotency, contention, PRAGMAs, migrations, crash recovery, and state transitions with `guides/05-prove-persistence-and-state.md`. Do not choose durability, busy behavior, schema policy, or monetary semantics while their owning decision is open. +7. Implement adapters behind approved contracts using `guides/06-implement-adapters.md`. Normalize edge types, preserve correlation/visibility/reservation facts, use approved secret references, default sensitive tracing to `skip_all`, keep egress/TLS controls intact, and use fake servers/fixtures unless live use has explicit authorization. +8. Build operator clients with `guides/07-build-cli-and-tui.md`: typed Clap parsing, stable machine output, domain exit codes, confirmation policy, double-redacted diagnostics, and a feature-gated Ratatui client only when explicitly assigned. The client never becomes a second authority. +9. Verify and generate local evidence with `guides/08-verify-and-package-evidence.md`. Run repository-specific format, check, Clippy, feature/target builds, tests, doctests, migration/concurrency/crash/provider proofs, benchmarks, and authorized soak/package steps. Populate `templates/release-evidence-manifest.yaml` when needed, but do not sign, publish, install globally, or claim platform/MSRV support from incomplete evidence. +10. Close the loop using `guides/09-close-the-loop.md` and `templates/implementation-handoff.md`. Report changed paths, exact commands/results, acceptance evidence, external effects, rollback/recovery, redaction, unsafe inventory, revalidation points, blockers, and peer handoffs. Preserve implementation checks -> Security -> affected-check reruns -> Quality. + +## Critical directives + +- Honor the exact authority boundary. Read and obey the named PRD, ADR, ledger, repository instructions, and gate state. Never start blocked/deferred work or promote a preference into an approval; implementation cannot consume authority it was never given. +- Keep agency and external effects fail-closed. Rust code may route inference but may not take over harness tools, approvals, repository access, memory, or user interaction. Never use live credentials, paid/subscription traffic, public publishing, Git initialization, signing identities, global installation, or auto-update execution without explicit authorization because those effects escape the bounded slice. +- Make concurrency and durability provable. Use bounded queues, explicit task ownership, reviewed cancellation/replay boundaries, atomic transactions, idempotency, and focused crash/concurrency evidence. Hidden retry, partial monetary state, or hand-waved shutdown creates data loss or double effects. +- Protect secrets and content by construction. Keep credentials in approved secret references. Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Preserve egress, redirect, DNS, and SSRF controls; redaction after leakage is not containment. +- Do not hide unsafe Rust or runtime failure. Default to no unsafe. Any exception requires minimal scope, a written invariant, targeted tests, and independent review. Avoid unchecked panics at daemon, adapter, state, and migration boundaries so failures remain structured, redacted, and recoverable. +- Respect peer ownership. Hand protocol meaning to the HTTP/MCP specialist, schema policy to the database specialist, security acceptance to `security-worker-bee`, dependency/license/advisory disposition to `dependency-audit-worker-bee`, CI/release topology to the DevOps/release specialist, and final acceptance to `quality-worker-bee`. Evidence generation is not peer approval. +- Verify before declaring completion. Run the current full relevant Rust gate and preserve implementation checks -> Security -> affected reruns -> Quality. Partial, stale, retry-only, unsigned, unreviewed, or single-platform results are not shipped or release-ready evidence. + +## Escalation + +Stop at the smallest safe, compilable/testable checkpoint when a missing decision affects safety, public compatibility, money, credentials, destructive behavior, platform support, signing, publication, or another external effect. Return the exact blocker, owning peer/gate, affected acceptance criteria, completed files/tests, command results, and first authorized next action. Do not silently guess or label the checkpoint shipped. + +- HTTP/REST or MCP semantics and compatibility -> `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`. +- Provider/model/product policy -> `ai-tools-platform-worker-bee` or the named product owner. +- Schema/data architecture -> `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- Threat acceptance, TLS/egress/redaction security, or credentials -> `security-worker-bee`. +- Dependency, advisory, license, source, and SBOM disposition -> `dependency-audit-worker-bee`. +- CI/CD topology, signing, installers, publication, or release operations -> the appropriate DevOps/release peer plus explicit user authorization. +- Final implementation-to-PRD audit -> `quality-worker-bee`, only after Security and affected reruns. + +## References to skill files + +Utilize the Read tool to understand your skills listed at `../skills/rust-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first. The research summary, synthesis, and index are the scaling pointers to the complete dated source-note corpus. + +Master indexes: +- `SKILL.md` — activation, inputs, procedure, directives, outputs, refresh points, and open decisions. +- `README.md` — layout, traceability, and maintenance posture. + +Principles and procedures: +- `guides/00-authority-and-principles.md` — authority reconstruction and fail-closed rules. +- `guides/01-inspect-workspace.md` — Cargo, async, persistence, security, and toolchain inventory. +- `guides/02-design-workspace-and-types.md` — crates, features, validated boundaries, typestate, errors, and architecture tests. +- `guides/03-implement-bounded-slices.md` — test-first acceptance slicing and patch discipline. +- `guides/04-prove-async-streams.md` — ownership, cancellation, backpressure, replay, disconnect, and shutdown. +- `guides/05-prove-persistence-and-state.md` — transactions, durability, migrations, crash recovery, and state machines. +- `guides/06-implement-adapters.md` — edge isolation, fake-first contracts, tracing, secrets, TLS, and prohibited effects. +- `guides/07-build-cli-and-tui.md` — Clap contracts, diagnostics, confirmation, Ratatui lifecycle, and TUI gate. +- `guides/08-verify-and-package-evidence.md` — verification ladder, package manifest, and closed release effects. +- `guides/09-close-the-loop.md` — handoff, evidence honesty, blocker record, and Security-before-Quality. + +Worked examples: +- `examples/01-happy-path-bounded-service-slice.md` — bounded fake-provider service, ordering, capacity, and shutdown. +- `examples/02-edge-visible-output-cancellation.md` — private replay proof and cancellation after visibility. +- `examples/03-edge-concurrent-budget-reservation.md` — transactional reservation, idempotency, contention, and recovery. +- `examples/04-release-evidence-with-closed-gates.md` — local package evidence with signing/publication blocked. + +Output templates: +- `templates/acceptance-slice-checklist.md` — bounded implementation checklist. +- `templates/implementation-handoff.md` — canonical completion/blocker handoff. +- `templates/release-evidence-manifest.yaml` — artifact, verification, supply-chain, provenance, and gate evidence. +- `templates/rust-decision-log.md` — drift-sensitive implementation decisions. + +Report artifacts: +- `reports/README.md` — archive and no-overwrite rules. +- `reports/implementation-handoff-report-template.md` — global archive wrapper. + +Research trail: +- `research/research-plan.md` — deep-research questions, order, source posture, and provenance caveat. +- `research/research-summary.md` — coverage, influential sources, open questions, and refresh points. +- `research/evidence-synthesis.md` — patterns, limitations, peer boundaries, and evidence model. +- `research/index.md` — complete inventory of every dated primary-source note. + +--- + +*Created by the Legendary Bee Factory.* diff --git a/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md b/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..bfdae086 100644 --- a/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,20 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`rust-worker-bee` / `rust-stinger` was ported in from a prior fork and registered here: Rust implementation and code review for Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, tests, and local packaging evidence. ## Path integrity @@ -41,7 +45,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.claude/skills/beekeeper-suit/SKILL.md b/.claude/skills/beekeeper-suit/SKILL.md index 1a137f45..a002505e 100644 --- a/.claude/skills/beekeeper-suit/SKILL.md +++ b/.claude/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,6 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | +| `rust-worker-bee` | Rust implementation and code review for production Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence | "implement this in Rust", "review this Cargo workspace", "fix this Tokio or SQLx service", "audit this SQLx transaction", "build the approved Rust PRD slice" | `rust-stinger` | | `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | @@ -251,7 +252,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `.claude/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `.claude/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.claude/skills/beekeeper-suit/guides/rust-worker-bee.md b/.claude/skills/beekeeper-suit/guides/rust-worker-bee.md new file mode 100644 index 00000000..7c2e21ad --- /dev/null +++ b/.claude/skills/beekeeper-suit/guides/rust-worker-bee.md @@ -0,0 +1,52 @@ +# rust-worker-bee + +## Domain +This Bee owns bounded implementation and code review for production Rust systems. It handles Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, decide dependency or release policy, issue final Quality acceptance, or authorize external effects. + +## Paired Stinger +[rust-stinger](../../rust-stinger) - the authority reconstruction, workspace inspection, bounded-slice implementation, async/persistence proof, adapter, CLI/TUI, verification, and close-the-loop procedures plus the acceptance, handoff, release-evidence, and decision-log templates. + +## Trigger phrases +- "Implement this in Rust." +- "Review this Cargo workspace." +- "Fix this Tokio or SQLx service." +- "Audit this SQLx transaction." +- "Build the approved Rust PRD slice." + +Also route proactively when a requested change or review touches Rust source, Cargo manifests or workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, or local Rust packaging evidence. + +## Do NOT route when +- The ask is HTTP/REST or MCP semantic and compatibility decisions: that is `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`; Rust implements their approved contracts. +- The ask is product, model, and provider policy: that is `ai-tools-platform-worker-bee` or the named product owner. +- The ask is schema architecture: that is `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- The ask is Security acceptance: that is `security-worker-bee`. +- The ask is dependency/license/advisory disposition: that is `dependency-audit-worker-bee`. +- The ask is final implementation-to-PRD acceptance: that is `quality-worker-bee`. +- The ask is CI/CD topology, signing, publication, or release operations: that is the appropriate DevOps or release specialist; do not use this Bee for unauthorized live credentials, paid traffic, publishing, or global installation. + +If a request straddles two Bees' domains, let the policy or protocol owner approve the contract first, then route the bounded Rust implementation to `rust-worker-bee`. + +## Inputs the Bee needs +- The exact repository or worktree, owned paths, branch/change boundary, and concurrent-work constraints. +- The authorizing PRD, ADR, ledger rows, acceptance criteria, gates, and repository instructions. +- The current Cargo graph, Rust source, features and targets, migrations, tests, and release configuration. +- Approved protocol, provider, persistence, security, CLI, platform, and operational contracts, including data-integrity and cancellation requirements. +- The required verification commands and explicit authorization for any external effect. + +If a missing input controls safety, public compatibility, money, credentials, signing, publication, or destructive behavior, invoke only to record the fail-closed blocker and smallest safe checkpoint; do not ask the Bee to guess. + +## Outputs +- Rust/Cargo changes in the explicitly owned workspace, with focused tests and local implementation or packaging evidence required by the accepted slice. +- An acceptance-linked Rust implementation handoff using `templates/implementation-handoff.md`, including changed paths, exact verification commands and results, safety evidence, rollback/recovery notes, and remaining gates. +- When release evidence is explicitly in scope, a populated local `templates/release-evidence-manifest.yaml`; signing and publication remain closed unless separately authorized. +- A precise blocker record instead of a completion claim when an owning decision, tool, gate, or required proof is missing. + +## Commonly sequenced with +- Plan execution loop: `rust-worker-bee` is the implementation Bee for Rust/Cargo work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Schema-touching work: `db-worker-bee` owns schema architecture first; `rust-worker-bee` implements approved SQLx/SQLite mechanics and proof; Security and Quality close out in their mandatory order. +- Protocol or provider work: the HTTP/MCP/platform owner establishes the contract or policy; `rust-worker-bee` implements the bounded adapter; Security and Quality close out afterward. + +## Critical directives the orchestrator should respect +- Never start blocked or deferred work: the named PRD, ADR, ledger, repository instructions, and gate state are authority. +- Keep harness agency and external effects fail-closed while requiring provable bounded concurrency, cancellation/replay behavior, transactions, crash recovery, redaction, and a default of no `unsafe`; no live credentials, paid traffic, global installation, signing, publication, or auto-update execution without explicit authorization. +- Preserve the verification order: implementation checks, Security, affected-check reruns, then Quality; partial or stale evidence is not shipped evidence. diff --git a/.claude/skills/rust-stinger/README.md b/.claude/skills/rust-stinger/README.md new file mode 100644 index 00000000..2498a96f --- /dev/null +++ b/.claude/skills/rust-stinger/README.md @@ -0,0 +1,16 @@ +# Rust Stinger + +Rust Stinger equips `rust-worker-bee` to implement and review production Cargo workspaces, async services, durable local state, operator surfaces, tests, and release evidence. It operationalizes the approved Command Brief while preserving protocol, Security, dependency, release, and Quality peer ownership. Its technical rules are traceable to [`research/research-summary.md`](research/research-summary.md) and the underlying primary-source notes. + +## Layout + +- `SKILL.md` — trigger, procedure, directives, outputs, and decision boundaries. +- `guides/` — numbered procedures matching every Command Brief action. +- `examples/` — worked happy-path and failure-boundary handoffs. +- `templates/` — reusable implementation, decision, and release-evidence stubs. +- `reports/` — report-shape template and future run archive. +- `research/` — immutable scripture-historian evidence packet. + +## Maintenance + +Update the research packet before changing version-sensitive guidance. The current packet marks Rust/Cargo, Tokio, SQLx, rustls, cargo-dist, platform support, and RustSec as explicit revalidation points; current-at-retrieval values are evidence snapshots, not defaults. diff --git a/.claude/skills/rust-stinger/SKILL.md b/.claude/skills/rust-stinger/SKILL.md new file mode 100644 index 00000000..8c2d427b --- /dev/null +++ b/.claude/skills/rust-stinger/SKILL.md @@ -0,0 +1,83 @@ +--- +name: "rust-stinger" +description: "Implements and reviews production Rust systems across Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui operator surfaces, tests, and release evidence. Use when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or invokes rust-worker-bee. Do not use it to invent protocol semantics, approve security or dependency policy, author the final Quality report, or publish a release." +license: MIT +--- + +# Rust Stinger + +Equip `rust-worker-bee` to own bounded Rust implementation while preserving the authority of the exact PRD, ADR, ledger, and peer specialists. Make async ownership, durability, state transitions, redaction, and release evidence mechanically reviewable. Stop at a recorded fail-closed boundary whenever a missing decision affects safety, compatibility, money, credentials, signing, publication, or another external effect. + +## Required inputs + +Before editing, obtain: + +- the exact repository or worktree, owned paths, and concurrent-work boundaries; +- the authorizing PRD/ADR/ledger rows, acceptance criteria, gates, and repository instructions; +- the existing Cargo graph, toolchain files, feature/target matrix, migrations, code, tests, and release configuration; +- approved protocol, provider, persistence, security, CLI, platform, and operational contracts; +- the required verification commands and explicit authorization for any external effect. + +If a missing input determines safety, public compatibility, monetary behavior, credentials, publication, or destructive behavior, return a blocker rather than choosing silently. + +## Procedure + +1. Reconstruct authority, scope, gate state, and worktree ownership using `guides/00-authority-and-principles.md`. +2. Inventory the Rust system and record revalidation points using `guides/01-inspect-workspace.md`. +3. Establish the smallest coherent crate, feature, type, and error design using `guides/02-design-workspace-and-types.md`. +4. Implement a test-first acceptance slice using `guides/03-implement-bounded-slices.md`. +5. Prove task, cancellation, stream, backpressure, timeout, retry, and shutdown behavior using `guides/04-prove-async-streams.md`. +6. Prove SQLite/SQLx transactions, migrations, crash recovery, and typed state transitions using `guides/05-prove-persistence-and-state.md`. +7. Implement provider and harness edges only behind approved contracts using `guides/06-implement-adapters.md`. +8. Build scriptable CLI and optional TUI surfaces using `guides/07-build-cli-and-tui.md`. +9. Run the complete owned verification and generate release evidence without publishing using `guides/08-verify-and-package-evidence.md`. +10. Produce the acceptance-linked handoff, route Security before Quality, and leave unresolved gates explicit using `guides/09-close-the-loop.md`. + +## Critical directives + +- Treat the named PRD, ADR, ledger, gate state, and repository instructions as authority. Never start blocked or deferred work. +- Keep provider code subordinate to the host harness: it may route inference but never acquire tools, approvals, repository access, memory, or user interaction. +- Default to bounded queues, explicit task owners, operation-level cancellation review, and no transparent replay after visible output or a harness-visible tool call. +- Put monetary/quota checks, reservations, reconciliation, idempotency, and aggregate updates in explicit transactions with concurrency and crash evidence. +- Keep credentials in approved secret references and start sensitive instrumentation with `skip_all`; allowlist only non-sensitive correlation and state fields. +- Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Enforce approved egress allowlists and never bypass redirect, DNS, or SSRF checks. +- Default to no `unsafe`. Any exception needs a minimal scope, written invariant, targeted tests, and independent review. +- Use fake providers and fixtures by default. Do not use live credentials, paid traffic, subscriptions, signing identities, publishing, auto-update, Git initialization, or destructive controls without explicit authorization. +- Never promote retrieval-time crate/tool versions, OS targets, durability settings, timeout values, signing systems, or soak thresholds into timeless defaults. Revalidate them at the decision point. +- Preserve peer authority: protocol semantics, product/provider policy, security acceptance, schema review, dependency/license disposition, CI topology, signing/publication, and final PRD Quality remain separate handoffs. +- Preserve verification order: implementation checks, Security, affected-check reruns, then Quality. Partial or stale evidence is not shipped evidence. + +See `guides/00-authority-and-principles.md` for the rationale and fail-closed decision table. + +## Output contract + +Produce a Rust implementation handoff from `templates/implementation-handoff.md`, backed by exact commands and artifacts. When release work is in scope, also populate `templates/release-evidence-manifest.yaml` without signing or publishing unless independently authorized. Past execution reports belong in `reports/`; see `reports/README.md`. + +## Examples + +- `examples/01-happy-path-bounded-service-slice.md` — Cargo/Axum/SQLx acceptance slice with deterministic evidence. +- `examples/02-edge-visible-output-cancellation.md` — cancellation after visible output, where replay must remain disabled. +- `examples/03-edge-concurrent-budget-reservation.md` — concurrent SQLite reservation and crash boundary. +- `examples/04-release-evidence-with-closed-gates.md` — package evidence generation with signing/publication held closed. + +## Research and refresh points + +Read `research/research-summary.md` and `research/evidence-synthesis.md` before making architecture or version-sensitive claims. Use `research/index.md` to locate primary notes. Re-fetch the Rust release/platform matrix, Tokio support policy, the selected SQLx transaction API, stable rustls APIs, cargo-dist behavior, and RustSec data at the point of use; the research packet records a 2026-07-24 snapshot, not permanent defaults. + +## Human decisions that remain open + +Do not resolve these from the Stinger alone: + +- supported OS/architecture/install matrix and minimum OS baselines; +- actual MSRV after the resolved graph and public features exist; +- SQLite power-loss durability and contended-writer behavior; +- durable replay/promotion event schema; +- first-milestone TUI scope; +- signing identity, attestation platform, installer formats, and publication authorization; +- quantitative soak pass/fail thresholds. + +Record the missing owner/decision, affected acceptance criteria, and first authorized next action in the handoff. + +## Paired owner + +This Stinger is paired with `rust-worker-bee`. diff --git a/.claude/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md b/.claude/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md new file mode 100644 index 00000000..e38c5359 --- /dev/null +++ b/.claude/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md @@ -0,0 +1,66 @@ +# Example 01 — Happy path: bounded service slice + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [verification](../guides/08-verify-and-package-evidence.md). + +## Input + +```text +Repo: /work/router +Owned paths: crates/router-daemon/**, crates/provider-fake/**, tests/stream_contract.rs +AC ROUTE-12: At most 16 in-flight requests; provider chunks preserve order; shutdown drains accepted turns in 2 seconds. +Gates: fake provider only; HTTP error schema already approved; no live credentials. +``` + +## Implementation pattern + +```rust +use tokio::sync::{mpsc, Semaphore}; +use tokio_util::sync::CancellationToken; + +struct RuntimeOwner { + cancel: CancellationToken, + capacity: std::sync::Arc, + queue: mpsc::Sender, +} + +impl RuntimeOwner { + async fn submit(&self, turn: Turn) -> Result<(), SubmitError> { + let permit = self.queue.reserve().await.map_err(|_| SubmitError::Stopping)?; + permit.send(turn); + Ok(()) + } +} +``` + +The bounded queue and reservation-before-send pattern follows Tokio's documented backpressure and cancellation behavior ([bounded MPSC](../research/async/2026-07-24-tokio-mpsc.md), [`reserve`](../research/async/2026-07-24-tokio-send-reserve.md)). The implementation also owns listener shutdown separately from joined background work ([Axum shutdown](../research/async/2026-07-24-axum-graceful-shutdown.md), [Tokio shutdown](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Focused proof + +```bash +cargo test -p router-daemon --test stream_contract bounded_admission +cargo test -p router-daemon --test stream_contract preserves_chunk_order +cargo test -p router-daemon --test shutdown drains_accepted_turns +cargo clippy -p router-daemon -p provider-fake --all-targets -- -D warnings +``` + +The contract test calls the Axum Router as a Tower service; a separate loopback test proves bind and shutdown ([research](../research/async/2026-07-24-axum-service-testing.md)). + +## Output + +```markdown +# Rust implementation handoff: ROUTE-12 bounded fake-provider route + +## Outcome +The fake-provider route admits no more than 16 concurrent turns, preserves chunk order, and drains accepted work during bounded shutdown. + +## Acceptance evidence +- ROUTE-12: three focused tests PASS; no live provider or credential path executed. + +## Safety and operations +- External effects used: none +- Shutdown: listener admission stops, root token cancels workers, owner joins tracked tasks. + +## Peer handoffs and remaining gates +- Security: ready for redaction and shutdown review. +- Quality: wait until Security and affected-check reruns complete. +``` diff --git a/.claude/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md b/.claude/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md new file mode 100644 index 00000000..b3454f06 --- /dev/null +++ b/.claude/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md @@ -0,0 +1,62 @@ +# Example 02 — Edge case: cancellation after visible output + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async/replay proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC REPLAY-07: A provider disconnect before output may be retried once. After any visible chunk or harness-visible tool call, the turn must never be replayed automatically. +Fixture: provider emits chunk seq=0, then disconnects. +``` + +## State pattern + +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Visibility { + None, + OutputSeen, + ToolCallSeen, +} + +enum Recovery { + ReplayEligible(NoVisibleEffect), + ResumeRequired { correlation_id: CorrelationId }, +} + +fn classify(trace: &TurnTrace) -> Recovery { + match trace.visibility { + Visibility::None => Recovery::ReplayEligible(NoVisibleEffect::new_private()), + Visibility::OutputSeen | Visibility::ToolCallSeen => Recovery::ResumeRequired { + correlation_id: trace.correlation_id, + }, + } +} +``` + +Keep the proof-token constructor private so callers cannot manufacture replay eligibility; rustls uses private verification markers for the same omitted-check defense ([research](../research/security/2026-07-24-rustls-verification-markers.md)). Use an explicit tagged durable representation rather than an ambiguous untagged enum ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). + +## Failure-focused proof + +```bash +cargo test -p router-core replay_before_output_is_single_use +cargo test -p provider-fake disconnect_after_first_chunk_disables_replay +cargo test -p provider-fake tool_call_visibility_disables_replay +cargo test -p router-daemon dropped_body_cancels_upstream_and_releases_permit +``` + +The last test matters because an Axum body is pull-driven and only preserves the desired backpressure if upstream production stops on disconnect ([research](../research/async/2026-07-24-axum-streaming-body.md)). Each selected future is reviewed individually because Tokio cancellation safety is operation-specific ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). + +## Output + +```markdown +## Outcome +Disconnect before visibility consumes one replay proof; disconnect after seq=0 returns `resume_required` and does not create a second provider request. + +## Acceptance evidence +- REPLAY-07: four focused tests PASS; fake request count remains 1 after visible output. + +## Safety and operations +- External effects used: none +- Recovery: correlation and last visible sequence persist; automatic replay remains disabled. +``` diff --git a/.claude/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md b/.claude/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md new file mode 100644 index 00000000..01e90549 --- /dev/null +++ b/.claude/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md @@ -0,0 +1,49 @@ +# Example 03 — Edge case: concurrent budget reservation + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded slices](../guides/03-implement-bounded-slices.md), [persistence/state proof](../guides/05-prove-persistence-and-state.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC BUDGET-09: Two processes racing for the last $0.10 cannot reserve more than the account balance. Duplicate idempotency keys return the original reservation. Crash before commit leaves no partial reservation. +Approved decision: BEGIN IMMEDIATE; durability PRAGMA remains separately gated. +``` + +## Transaction pattern + +```sql +UPDATE budget +SET reserved_microunits = reserved_microunits + ?1 +WHERE account_id = ?2 + AND limit_microunits - spent_microunits - reserved_microunits >= ?1 +RETURNING reserved_microunits; +``` + +Run the eligibility check, conditional update, reservation row, and idempotency record inside one tracked write transaction. SQLite permits one writer and `BEGIN IMMEDIATE` acquires write intent before the read/modify/write sequence ([research](../research/persistence/2026-07-24-sqlite-transactions.md)); SQLx 0.9 documents `begin_with`, but the selected version must be revalidated before using that API ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). + +## Failure-focused proof + +```bash +cargo test -p router-state concurrent_last_balance_has_one_winner +cargo test -p router-state duplicate_idempotency_key_returns_same_reservation +cargo test -p router-state kill_before_commit_recovers_all_or_none +cargo test -p router-state busy_timeout_returns_structured_contention +``` + +Use two real SQLite connections/processes; a process-local lock is not sufficient. Preserve database and WAL/SHM/journal companions in the crash fixture because recovery semantics depend on them ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). + +## Output + +```markdown +## Outcome +Exactly one racing process reserves the final balance; duplicate requests are idempotent; pre-commit crash recovery is all-or-none. + +## Acceptance evidence +- BUDGET-09: 100 deterministic race iterations PASS with exactly one winner; crash fixture PASS. + +## Peer handoffs and remaining gates +- Database: review schema/index and contention policy. +- Security: review account identifier handling and error redaction. +- Quality: wait until Security and reruns complete. +- Open: product owner must approve power-loss durability and busy UX before support claim. +``` diff --git a/.claude/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md b/.claude/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md new file mode 100644 index 00000000..57ea49d3 --- /dev/null +++ b/.claude/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md @@ -0,0 +1,45 @@ +# Example 04 — Release evidence with signing and publication closed + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [CLI/TUI boundary](../guides/07-build-cli-and-tui.md), [verification/release evidence](../guides/08-verify-and-package-evidence.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC RELEASE-04: Produce local macOS ARM64 package evidence and an uninstall transcript. +Not authorized: signing, attestation, GitHub release, registry publication, installer execution outside a temp prefix. +Open: final multi-platform matrix and signing identity. +``` + +## Local-only evidence commands + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo nextest run --profile release +cargo test --workspace --doc +cargo package --workspace +``` + +Then run the repository's pinned local package generator into a staging directory, calculate hashes, generate the approved SBOM/advisory/license reports, and install/uninstall only inside an isolated temporary prefix. `cargo package` verifies package contents/buildability but not provenance ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)); cargo-dist checksums are integrity evidence but are not signed proof ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). + +Do not invoke Cosign or a public release workflow: blob signing can create OIDC identity and transparency-log records ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). Re-run RustSec immediately at release time because advisory results are time-dependent ([research](../research/supply-chain/2026-07-24-rustsec.md)). + +## Output + +```markdown +## Outcome +Unsigned macOS ARM64 staging artifacts, hashes, SBOM, scans, and isolated install/uninstall transcript were generated locally. + +## Verification +- `cargo nextest run --profile release` — PASS +- `cargo test --workspace --doc` — PASS +- local staging install/uninstall — PASS +- signing — BLOCKED (no identity/authorization) +- publication — BLOCKED (no authorization) + +## Peer handoffs and remaining gates +- Dependency/license: review SBOM and scan dispositions. +- Release/Security: select signing identity and verify provenance policy. +- Quality: after Security and affected reruns. +- Platform: no support claim beyond the locally exercised target. +``` diff --git a/.claude/skills/rust-stinger/guides/00-authority-and-principles.md b/.claude/skills/rust-stinger/guides/00-authority-and-principles.md new file mode 100644 index 00000000..bf7946e2 --- /dev/null +++ b/.claude/skills/rust-stinger/guides/00-authority-and-principles.md @@ -0,0 +1,41 @@ +# 00 — Authority and principles + +## Purpose + +Reconstruct why the change is authorized, which paths are owned, which gates are open, and where Rust implementation authority ends. This guide covers Command Brief action 1 and every critical directive. + +## Procedure + +1. Read the repository instructions, exact PRD/sub-PRD, ADRs, execution ledger, acceptance criteria, and current Security/Quality evidence before source code. +2. Inspect `git status`, active branch/worktree, and owned paths. Treat unrelated or concurrent edits as user work. +3. Build a scope table with columns `AC`, `owned path`, `gate`, `proof`, and `peer handoff`. +4. Mark any blocked or deferred slice `BLOCKED`; do not prepare implementation behind it. +5. Record each decision that cannot be made locally: protocol semantics, provider/product policy, threat acceptance, schema policy, dependency/license exceptions, CI topology, signing, publication, or final Quality. +6. Confirm that all external effects are either `none` or separately authorized. + +## Fail-closed decision table + +| Missing fact | Required response | +|---|---| +| Safety or egress boundary | Stop and hand to Security/platform owner. | +| Public protocol meaning | Stop and hand to protocol owner. | +| Live credentials, paid traffic, or subscription use | Keep fake/fixture route only. | +| Destructive/billable CLI policy | Keep command disabled. | +| Signing, publication, installer execution, or auto-update | Generate local evidence only. | +| Target matrix, MSRV, durability, or soak threshold | Record a revalidation/TODO decision; do not declare support. | + +## Non-negotiable implementation posture + +- Use typed, explicit state at boundaries. Serde ignores unknown fields by default, so strict local control/config inputs need an intentional rejection or validated-conversion policy ([research](../research/boundaries/2026-07-24-serde-container-attributes.md)). +- Treat cancellation safety as a property of each awaited operation, not of async code generally ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +- Default sensitive instrumentation to `skip_all` because `#[instrument]` otherwise records function arguments ([research](../research/observability/2026-07-24-tracing-instrument.md)). +- Default to safe Rust and isolate any `unsafe` proof obligation behind the smallest safe abstraction ([research](../research/rust-cargo/2026-07-24-unsafe-rust.md)). +- Never equate a passing license/advisory tool with final legal or security acceptance; cargo-deny itself documents limits to license discovery ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Gate exit + +Proceed only when the assigned slice has authority, owned paths, acceptance proof, and peer handoffs. Otherwise populate `templates/implementation-handoff.md` as a precise blocker. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.claude/skills/rust-stinger/guides/01-inspect-workspace.md b/.claude/skills/rust-stinger/guides/01-inspect-workspace.md new file mode 100644 index 00000000..c389e466 --- /dev/null +++ b/.claude/skills/rust-stinger/guides/01-inspect-workspace.md @@ -0,0 +1,38 @@ +# 01 — Inspect the Rust workspace + +## Purpose + +Inventory the current workspace before changing it. This guide covers Command Brief action 2. + +## Inventory commands + +Run only commands supported by the repository, and record unavailable tools as blockers rather than installing them implicitly. + +```bash +git status --short --branch +cargo metadata --format-version 1 --no-deps +cargo tree --workspace -e features +cargo tree --workspace -e normal,build,dev +cargo test --workspace --no-run +``` + +Also inspect `Cargo.toml`, `Cargo.lock`, `rust-toolchain*`, `.cargo/config*`, `build.rs`, migrations, release profiles, `deny.toml`, nextest configuration, and CI/release manifests. + +## Inspection checklist + +- Draw the crate dependency direction and identify public type owners. +- Record workspace edition, resolver, toolchain pin, declared `rust-version`, default features, optional providers/TUI, targets, and binary entry points. +- Find all `unsafe`, panic/unwrap/expect paths in daemon/adapter/state/migration boundaries, global mutable state, spawned tasks, channels, `select!`, retries, time access, raw SQL, logging macros, secret exposure, TLS customization, and migrations. +- Locate every task owner and shutdown join path; Axum listener shutdown does not join arbitrary background tasks ([research](../research/async/2026-07-24-axum-graceful-shutdown.md)). +- Locate every bounded and unbounded queue; bounded Tokio MPSC expresses backpressure while unbounded channels do not encode a memory limit ([research](../research/async/2026-07-24-tokio-mpsc.md)). +- Verify effective SQLite journal, synchronous, foreign-key, busy-timeout, and checkpoint policy; SQLx does not select a journal mode by default ([research](../research/persistence/2026-07-24-sqlx-connect-options.md)). +- Separate current stable from declared MSRV. Cargo's `rust-version` participates in resolution but still needs CI proof across advertised features ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- Treat compiler target tiers as compiler guarantees, not product install/runtime proof ([research](../research/rust-cargo/2026-07-24-platform-support.md)). + +## Revalidation record + +Create or update `templates/rust-decision-log.md` for values likely to drift: toolchain, MSRV, target matrix, Tokio line, SQLx API, rustls stable API, package generator, and advisory snapshot. Do not copy current-at-retrieval numbers from research without rechecking. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.claude/skills/rust-stinger/guides/02-design-workspace-and-types.md b/.claude/skills/rust-stinger/guides/02-design-workspace-and-types.md new file mode 100644 index 00000000..140625db --- /dev/null +++ b/.claude/skills/rust-stinger/guides/02-design-workspace-and-types.md @@ -0,0 +1,52 @@ +# 02 — Design workspace and types + +## Purpose + +Establish the smallest coherent design without inventing peer-owned semantics. This guide covers Command Brief action 3. + +## Workspace rules + +1. Keep one owner per invariant; do not create a crate per noun. +2. Keep protocol/domain types inward, policy/state above them, provider adapters at edges, daemon/control as composition, and CLI/TUI as clients. +3. Keep test-support out of production dependency paths. +4. Declare `resolver = "3"` explicitly in a virtual Rust 2024 workspace; resolver choice is global, and version 3 is the Rust 2024 default ([research](../research/rust-cargo/2026-07-24-cargo-resolver-v3.md)). +5. Keep features additive, inspect feature unification, and make optional providers/TUI default-off unless the product contract requires otherwise ([research](../research/rust-cargo/2026-07-24-cargo-features.md)). +6. Centralize shared dependency versions/features only when it reduces drift without making edge features leak inward. + +## Typed boundary rules + +- Convert edge DTOs into validated domain newtypes before use. +- Prefer explicit tagged enums for durable safety state; untagged Serde enums try variants in order and can be ambiguous ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). +- Use private constructors and consumable marker/capability values for completed checks such as `NoVisibleOutput`, `ReservationHeld`, or `SafeTurnReviewed`. rustls uses non-constructible verification markers to prevent omitted-check control flow ([research](../research/security/2026-07-24-rustls-verification-markers.md)). +- Keep provider and harness SDK types in edge crates; normalize into protocol-neutral facts. +- Use structured errors with redacted public display and preserved internal sources; `thiserror` supports opaque public wrappers and causal chains, but redaction still depends on selected fields ([research](../research/boundaries/2026-07-24-thiserror.md)). + +## Minimal typestate pattern + +```rust +pub struct NoVisibleOutput(()); + +impl NoVisibleOutput { + fn after_preflight(trace: &TurnTrace) -> Option { + (!trace.visible_output && !trace.tool_call).then_some(Self(())) + } +} + +pub fn authorize_replay(proof: NoVisibleOutput) -> ReplayAuthorized { + let _consumed = proof; + ReplayAuthorized +} +``` + +Keep constructors private to the state-owning crate. Persist the underlying facts and rebuild proof only through the validated transition path. + +## Architecture test ideas + +- Compile-fail tests for private marker construction. +- Feature-matrix builds proving core crates do not acquire provider/TUI dependencies. +- Public API inspection confirming no harness/provider SDK types cross inward. +- `forbid(unsafe_code)` at crate roots where dependencies allow it; otherwise maintain an explicit inventory. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.claude/skills/rust-stinger/guides/03-implement-bounded-slices.md b/.claude/skills/rust-stinger/guides/03-implement-bounded-slices.md new file mode 100644 index 00000000..f793433b --- /dev/null +++ b/.claude/skills/rust-stinger/guides/03-implement-bounded-slices.md @@ -0,0 +1,34 @@ +# 03 — Implement bounded acceptance slices + +## Purpose + +Implement test-first, acceptance-linked changes while preserving concurrent work. This guide covers Command Brief action 4. + +## Slice loop + +1. Select one acceptance criterion whose dependencies and gates are open. +2. Name the observable outcome, owned files, and fastest focused proof. +3. Add a failing unit, contract, property, migration, concurrency, or failure-injection test. +4. Implement the narrowest code that satisfies the proof. +5. Run format, focused test, affected crate checks, and the repository's relevant gate. +6. Record the exact command/result and map it back to the criterion. +7. Re-read the diff for scope, redaction, panic/unsafe, retries, feature leakage, and external effects. + +## Test selection + +- Use direct Axum/Tower service calls for most request/middleware contracts without binding a port ([research](../research/async/2026-07-24-axum-service-testing.md)). +- Use Tokio paused time for timeout/backoff/breaker/pin behavior; only Tokio-controlled time is paused ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Use proptest for invariant-rich values and transition sequences, and persist failing seeds ([research](../research/testing/2026-07-24-proptest-index.md)). +- Use real temporary SQLite and multiple connections/processes for persistence concurrency; Loom cannot see operations not expressed through Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Use narrow loopback integration tests only for bind, listener shutdown, disconnect, and process behavior. + +## Patch discipline + +- Do not edit paths outside assigned ownership. +- Do not install missing tools, initialize Git, change public policy, run live providers, or publish as a convenience. +- Do not weaken a test to fit the implementation. +- Do not turn retries on to hide a race; nextest can mark retry-only success as flaky, and release profiles should fail it absent an approved quarantine ([research](../research/testing/2026-07-24-nextest-retries.md)). + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.claude/skills/rust-stinger/guides/04-prove-async-streams.md b/.claude/skills/rust-stinger/guides/04-prove-async-streams.md new file mode 100644 index 00000000..3fb29767 --- /dev/null +++ b/.claude/skills/rust-stinger/guides/04-prove-async-streams.md @@ -0,0 +1,36 @@ +# 04 — Prove async and stream correctness + +## Purpose + +Make task ownership, cancellation, timeout, retry, backpressure, ordering, shutdown, and cleanup observable. This guide covers Command Brief action 5. + +## Lifecycle model + +1. Name the root owner of every spawned task. +2. Define admission stop, cooperative cancellation signal, drain policy, join deadline, escalation, and cleanup. +3. Use bounded channels on hot paths and state the capacity rationale. +4. Review every `select!` awaited operation for documented cancellation safety; dropping and recreating a future must not lose observable work ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +5. Reserve channel capacity before expensive/fallible message construction when cancellation could otherwise lose the message; Tokio documents that cancelled `send` loses the message and queue position ([research](../research/async/2026-07-24-tokio-send-reserve.md)). +6. Call Tower readiness before dispatch and prove reserved capacity is released if dispatch/future is dropped ([research](../research/async/2026-07-24-tower-service-readiness.md)). +7. Record Tower layer order and test saturation, timeout, load shedding, and error mapping because layer order changes observable behavior ([research](../research/async/2026-07-24-tower-service-builder.md)). +8. Stop upstream production when an Axum response body is dropped; HTTP pull-based framing only provides backpressure if the producer is bounded and cancellation-aware ([research](../research/async/2026-07-24-axum-streaming-body.md)). +9. Detect shutdown, notify owned work, and wait for completion as separate phases ([research](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Replay boundary + +Track `visible_output`, `tool_call`, sequence/correlation ID, and reservation state as explicit facts. Once output or a harness-visible tool call occurs, consume/withhold the replay proof and return a structured terminal or recoverable state according to the approved contract; never infer safety from a transport error alone. + +## Required tests + +- cancellation before and after channel reservation; +- cancellation between `poll_ready` and `call`; +- client disconnect while producer is blocked; +- chunk ordering and correlation preservation; +- timeout at each side-effect boundary; +- retry only before the approved visibility boundary; +- shutdown under idle, saturated, streaming, and database-flush states; +- task/permit/handle cleanup after every failure path. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.claude/skills/rust-stinger/guides/05-prove-persistence-and-state.md b/.claude/skills/rust-stinger/guides/05-prove-persistence-and-state.md new file mode 100644 index 00000000..9e4f434c --- /dev/null +++ b/.claude/skills/rust-stinger/guides/05-prove-persistence-and-state.md @@ -0,0 +1,39 @@ +# 05 — Prove persistence and state machines + +## Purpose + +Make SQLx/SQLite transactions, locking, migrations, crash recovery, and state transitions atomic and testable. This guide covers Command Brief action 6. + +## Transaction rules + +1. Acquire write intent before reading mutable budget/quota state when the operation must serialize. SQLite allows one writer; deferred transactions can fail on read-to-write upgrade, while `BEGIN IMMEDIATE` attempts write acquisition at the start ([research](../research/persistence/2026-07-24-sqlite-transactions.md)). +2. Keep eligibility, reservation, aggregate update, and idempotency record in one transaction. +3. Use a conditional SQL update/constraint as the final oversubscription guard; an in-process mutex does not coordinate other processes. +4. Treat `SQLITE_BUSY` as a bounded, observable result. A timeout is not authority for invisible unbounded retry. +5. Use the selected SQLx version's tracked transaction API. `Connection::begin_with` is documented for SQLx 0.9; revalidate or design a version-specific alternative for other lines ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). +6. Centralize and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy. WAL improves reader/writer concurrency but still permits one writer and can grow under long readers ([research](../research/persistence/2026-07-24-sqlite-wal.md)). +7. Match product durability language to the chosen PRAGMAs; WAL with `synchronous=NORMAL` does not provide recent-transaction durability across power loss ([research](../research/persistence/2026-07-24-sqlite-pragma-durability.md)). + +## Migration rules + +- Embed migrations only after the database peer approves schema direction. +- Keep migrations forward-only; test old binary/new schema compatibility as required. +- Test interrupted migration, repeated startup, partial files, and crash/restart recovery. +- Preserve database, WAL, SHM, and journal companions together during recovery; SQLite's atomicity evidence relies on journal/WAL recovery and fault testing ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). +- Use compile-checked queries or checked-in offline metadata where practical; `migrate!` embeds migrations but does not replace compatibility/crash policy ([research](../research/persistence/2026-07-24-sqlx-migrations-queries.md)). + +## State-machine proof + +- Persist explicit tagged states/events and schema versions. +- Keep invalid transitions unconstructible through private types and consumed proof tokens. +- Model reservation, reconciliation, breaker, quota, pin, replay, recovery, and promotion in a reference state machine. +- Generate valid transition sequences, assert postconditions/invariants, shrink failures, and save regression seeds; upstream proptest state-machine support is sequential, so add independent concurrency evidence ([research](../research/testing/2026-07-24-proptest-state-machines.md)). +- Inject fake time, stale observations, duplicate commands, process crashes, busy writers, and restart recovery. + +## Open decision checkpoints + +> TODO: human decision before the relevant product slice — power-loss durability, busy timeout/UX, and final durable replay/promotion schema remain product/architecture decisions. + +## Worked examples + +See [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.claude/skills/rust-stinger/guides/06-implement-adapters.md b/.claude/skills/rust-stinger/guides/06-implement-adapters.md new file mode 100644 index 00000000..429b9550 --- /dev/null +++ b/.claude/skills/rust-stinger/guides/06-implement-adapters.md @@ -0,0 +1,37 @@ +# 06 — Implement adapters behind approved contracts + +## Purpose + +Implement provider and harness edges without granting providers agency or inventing protocol policy. This guide covers Command Brief action 7. + +## Boundary design + +1. Import approved protocol/domain types into edge crates; do not leak SDK types inward. +2. Normalize provider chunks, usage, finish reasons, and errors into the approved internal contract. +3. Preserve correlation, ordering, visibility, tool-call, retry, reservation, and cancellation facts explicitly. +4. Inject credentials only through approved secret-reference interfaces. Secret wrappers require explicit exposure and reduce accidental Debug/copying, but do not replace the secret store ([research](../research/security/2026-07-24-secrecy.md)). +5. Start provider/request functions with `#[instrument(skip_all)]` and add only allowlisted fields; function arguments are captured by default otherwise ([research](../research/observability/2026-07-24-tracing-instrument.md)). +6. Let libraries emit structured events while daemon/CLI binaries own subscriber and sink initialization; tracing advises libraries not to set a global subscriber ([research](../research/observability/2026-07-24-tracing-subscriber.md)). +7. Use stable rustls safe builders and approved roots. Custom verifier APIs are deliberately dangerous and require Security review ([research](../research/security/2026-07-24-rustls-config-builder.md)). +8. Keep unsupported, unauthorized, and unconfigured routes disabled. + +## Fake-first contract suite + +Use fake HTTP servers and fixtures for: + +- success and chunk-boundary variation; +- malformed/unknown fields and structured errors; +- disconnect and cancellation at every visible-output boundary; +- throttling, timeout, server error, retry eligibility, and backpressure; +- usage/reservation/reconciliation and duplicate idempotency keys; +- secret/header/prompt redaction in logs, crashes, metrics, diagnostics, and support exports. + +Direct Router/Tower calls cover most HTTP contracts without a live listener ([research](../research/async/2026-07-24-axum-service-testing.md)); keep a narrow loopback test for bind/shutdown/stream disconnect. + +## Prohibited effects + +Do not use live credentials, paid/subscription traffic, public endpoints, signing identity, or provider activation unless the gate explicitly authorizes them. Adapter implementation never gives a provider tools, approvals, filesystem/repository access, memory, or user interaction. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.claude/skills/rust-stinger/guides/07-build-cli-and-tui.md b/.claude/skills/rust-stinger/guides/07-build-cli-and-tui.md new file mode 100644 index 00000000..e1a7730d --- /dev/null +++ b/.claude/skills/rust-stinger/guides/07-build-cli-and-tui.md @@ -0,0 +1,30 @@ +# 07 — Build CLI and TUI surfaces + +## Purpose + +Build operable, scriptable, redacted operator clients without creating a second control authority. This guide covers Command Brief action 8. + +## CLI contract + +- Model commands and constrained arguments with Clap typed parsers and subcommands ([research](../research/cli-tui/2026-07-24-clap-parser.md)). +- Test parsing with non-exiting APIs; decide printing and process exit only at the binary boundary. +- Keep human help/errors separate from stable JSON/stdout schemas. Clap exposes rendering and exit information, but human formatting is not a machine protocol ([research](../research/cli-tui/2026-07-24-clap-errors.md)). +- Define a domain exit-code taxonomy for operational failures. +- Require a reviewed confirmation or explicit noninteractive policy for destructive or billable commands; keep them disabled if absent. +- Make diagnostics/support exports previewable, double-redacted, and free of prompt bodies, code, raw credentials, headers, and unsalted account identifiers. + +## Optional TUI contract + +- Keep the TUI feature-gated and thin over the same authenticated control client as the CLI. +- Prefer the main Ratatui crate unless a lower-level crate is specifically required; upstream recommends this for ordinary applications ([research](../research/cli-tui/2026-07-24-ratatui-architecture.md)). +- Use Ratatui's managed `run` lifecycle or explicitly handle fallible init/restore so success, error, panic, and cancellation restore the terminal ([research](../research/cli-tui/2026-07-24-ratatui-lifecycle.md)). +- Unit-test widgets against buffers and integration-test the whole UI with `TestBackend` ([research](../research/cli-tui/2026-07-24-ratatui-test-backend.md)). +- Add narrow platform/real-terminal smoke tests only where the supported matrix requires them. + +## Open decision checkpoint + +> TODO: human decision before implementation — whether the TUI is in the first executable milestone remains unresolved. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.claude/skills/rust-stinger/guides/08-verify-and-package-evidence.md b/.claude/skills/rust-stinger/guides/08-verify-and-package-evidence.md new file mode 100644 index 00000000..9796ac2c --- /dev/null +++ b/.claude/skills/rust-stinger/guides/08-verify-and-package-evidence.md @@ -0,0 +1,54 @@ +# 08 — Verify and package evidence + +## Purpose + +Run the complete owned Rust gate and generate reviewable package evidence without claiming peer acceptance or performing unauthorized external effects. This guide covers Command Brief action 9. + +## Verification ladder + +Adapt exact commands to the repository and record every result. + +```bash +cargo fmt --all -- --check +cargo check --workspace --all-targets +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo test --workspace --doc +cargo metadata --format-version 1 +cargo tree --workspace -e features +``` + +Add declared minimal/default/all-feature builds, MSRV checks, target builds, migration/concurrency/crash/fake-provider tests, property/model tests, benchmarks, and soak checks. Clippy guidance recommends `-Dwarnings` with the same compiler toolchain as compilation; new lints make the result toolchain-specific ([research](../research/rust-cargo/2026-07-24-clippy-ci.md)). Nextest does not run doctests, so retain a separate doc-test step ([research](../research/testing/2026-07-24-nextest.md)). + +## Evidence layers + +- Unit/contract: pure logic and direct Tower/Axum calls. +- Deterministic time: Tokio paused clock for time-driven behavior ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Property/state: proptest with saved seeds. +- Model concurrency: Loom only for small primitives expressed with Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Persistence/process: real SQLite, multiple writers, fault injection, kill/restart. +- Provider/stream: fake servers and transcript fixtures. +- Benchmark: Criterion on a controlled host; statistics do not remove noisy-host risk ([research](../research/testing/2026-07-24-criterion-analysis.md)). +- Soak: purpose-built fake-provider run with periodic RSS, task, queue, DB/WAL, handle, throughput, and error telemetry. + +> TODO: human decision before release qualification — define quantitative soak thresholds; no universal off-the-shelf eight-hour harness or product threshold exists in the research packet. + +## Release evidence packet + +Populate `templates/release-evidence-manifest.yaml` with target artifacts, hashes, toolchain/lockfile, tests, SBOM, advisory/license/source scans, install/uninstall transcripts, and verification commands. + +- Revalidate cargo-dist before generating archives/installers; it supports target artifacts, checksums, and several installers, while checksums alone are unsigned integrity values ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). +- Generate target/feature-aware SBOM evidence and record tool version; cargo-cyclonedx added reproducible timestamp and target support in its retrieval-time release ([research](../research/supply-chain/2026-07-24-cargo-cyclonedx.md)). +- Record advisory database time and lockfile/artifact hash because RustSec findings are point-in-time ([research](../research/supply-chain/2026-07-24-rustsec.md)). +- Treat cargo-deny output as evidence for the dependency owner, not license/legal clearance ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). +- Treat Cargo's native SBOM precursor as optional/nightly until stabilized ([research](../research/supply-chain/2026-07-24-cargo-sbom-unstable.md)). +- Do not confuse `cargo package` verification with provenance; Cargo states provenance is not verified ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)). +- Do not sign or publish. Cosign signing can create identity/transparency-log effects and needs explicit authorization ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). + +## Open decision checkpoints + +> TODO: human decisions before release — supported targets/baselines, MSRV, installer formats, signing/attestation identity, and publication authorization. + +## Worked examples + +See [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.claude/skills/rust-stinger/guides/09-close-the-loop.md b/.claude/skills/rust-stinger/guides/09-close-the-loop.md new file mode 100644 index 00000000..dd6bedc9 --- /dev/null +++ b/.claude/skills/rust-stinger/guides/09-close-the-loop.md @@ -0,0 +1,42 @@ +# 09 — Close the loop + +## Purpose + +Return acceptance-linked implementation evidence, limitations, recovery notes, and peer handoffs in the required order. This guide covers Command Brief action 10. + +## Completion procedure + +1. Re-read the requested acceptance criteria and current ledger/gates. +2. Run the final relevant Rust commands against the current tree; do not reuse stale results. +3. Populate `templates/implementation-handoff.md` with exact outcomes and changed paths. +4. For each criterion, cite a command, test, artifact, and result. +5. State external effects exactly: `none` or the recorded authorization/effect. +6. Explain migration, rollback, restart, and data recovery, including any irreversible step. +7. Explain prompt/secret/log/diagnostic handling and remaining Security questions. +8. Route the implemented state to Security. If fixes land, rerun affected implementation gates. +9. Route the post-Security state to Quality for final implementation-to-PRD audit. +10. Leave protocol, platform, dependency/license, CI/release, signing, publication, and other gates with their actual owners. + +## Evidence honesty rules + +- A current-stable toolchain is not a proven MSRV; Cargo requires verification of declared `rust-version` across supported functionality ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- A compiler-supported target is not a product-supported install/runtime target ([research](../research/rust-cargo/2026-07-24-platform-support.md)). +- Passing Loom is not general concurrency proof because unmodeled operations are invisible and state spaces are bounded ([research](../research/testing/2026-07-24-loom.md)). +- A retry-only test success is flaky evidence, not a clean pass ([research](../research/testing/2026-07-24-nextest-retries.md)). +- A generated checksum, SBOM, advisory scan, or license scan does not by itself prove signed provenance or peer acceptance ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md), [research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Blocked checkpoint + +When blocked, provide the smallest safe compilable/testable checkpoint if one exists, then name: + +- blocker and owning gate; +- affected acceptance criteria; +- files/tests completed; +- commands that passed, failed, or were unavailable; +- first authorized next action. + +Never call a partial checkpoint shipped or release-ready. + +## Worked examples + +See all four examples, especially [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.claude/skills/rust-stinger/reports/README.md b/.claude/skills/rust-stinger/reports/README.md new file mode 100644 index 00000000..bdb75008 --- /dev/null +++ b/.claude/skills/rust-stinger/reports/README.md @@ -0,0 +1,3 @@ +# Rust Stinger reports + +This folder accumulates dated implementation handoffs produced by `rust-worker-bee`; copy `implementation-handoff-report-template.md`, preserve exact command evidence, and never overwrite an earlier run. diff --git a/.claude/skills/rust-stinger/reports/implementation-handoff-report-template.md b/.claude/skills/rust-stinger/reports/implementation-handoff-report-template.md new file mode 100644 index 00000000..ccb48186 --- /dev/null +++ b/.claude/skills/rust-stinger/reports/implementation-handoff-report-template.md @@ -0,0 +1,15 @@ +# Rust implementation handoff: {{slice_name}} + +Use the complete reusable form in [`../templates/implementation-handoff.md`](../templates/implementation-handoff.md). Store a populated copy here as `YYYY-MM-DD-{{slice_slug}}.md` only when the orchestrator designates this global Stinger as the report archive; product-specific evidence normally remains in the product's authorized artifact path. + +Required sections: + +1. Outcome +2. Authority and scope +3. Acceptance evidence +4. Changed paths +5. Verification +6. Safety and operations +7. Revalidation points +8. Peer handoffs and remaining gates +9. Blocker, if any diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md new file mode 100644 index 00000000..ac6314f7 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/serve/struct.Serve.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: axum +stinger: rust-stinger +--- + +# Axum server graceful shutdown + +## Summary +Axum's `Serve::with_graceful_shutdown` binds server lifetime to a supplied future. It stops accepting new work when the signal resolves and waits for connections according to the server's graceful behavior. Application-owned background tasks still need separate ownership and joining. + +## Key quotations / statistics +- "Prepares a server to handle graceful shutdown" +- The signal is a future "that resolves to `()`" + +## Version/date caveat +Axum latest docs at retrieval; exact connection-drain semantics depend on the matching hyper/axum versions. + +## Annotations for stinger-forge +- Use for the loopback listener shutdown path. +- Pair with Tokio task tracking; server shutdown alone does not prove all background work stopped. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md new file mode 100644 index 00000000..dd8c0e33 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/src/axum/routing/mod.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: testing +stinger: rust-stinger +--- + +# Axum router testing as a Tower service + +## Summary +Axum routers can be converted to borrowed or owned Tower services and invoked directly with requests. This avoids binding a real socket for most contract and middleware tests, making state, status, headers, and body behavior deterministic while reserving live-listener tests for integration boundaries. + +## Key quotations / statistics +- "Use `as_service` to get a borrowed `Service` from a `Router`." +- "Use `into_service` to get an owned `Service`" + +## Version/date caveat +Source docs for Axum latest; test helpers and body collection APIs vary across axum/http-body-util releases. + +## Annotations for stinger-forge +- Supports in-process HTTP contract tests without network flakiness. +- Loopback bind and shutdown still require a smaller dedicated integration test. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md new file mode 100644 index 00000000..2c2c12f0 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/body/struct.Body.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: streaming +stinger: rust-stinger +--- + +# Axum streaming bodies + +## Summary +Axum 0.8.9 wraps `http_body::Body` and can create a response body from a fallible `Stream`. Consumers pull frames asynchronously through `poll_frame`; converting to a data-only stream discards trailers. Backpressure therefore propagates through polling only if the upstream producer is itself bounded and cancellation-aware. + +## Key quotations / statistics +- `from_stream`: "Create a new `Body` from a `Stream`." +- `poll_frame`: "Attempt to pull out the next data buffer of this stream." + +## Version/date caveat +Axum 0.8.9, http-body 1.1.0 at retrieval. Frame/trailer behavior must match the selected HTTP contract. + +## Annotations for stinger-forge +- Core source for streaming body construction and disconnect/cancellation tests. +- Do not collect unbounded streams into memory; test that dropping the body stops producer work and releases permits. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md new file mode 100644 index 00000000..653ee9c7 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/shutdown +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: shutdown +stinger: rust-stinger +--- + +# Tokio graceful shutdown + +## Summary +Tokio presents graceful shutdown as three explicit phases: detect the trigger, notify owned work, and wait for work to finish. It demonstrates cancellation tokens for cooperative notification and task trackers for joining all tracked work, allowing cleanup such as database flushes before termination. + +## Key quotations / statistics +- "Figuring out when to shut down." +- "Waiting for other parts of the program to shut down." + +## Version/date caveat +Conceptual Tokio topic page; exact APIs may live in `tokio-util` and must match the selected versions. + +## Annotations for stinger-forge +- Core source for task ownership and shutdown checklists. +- Supports a root cancellation token plus explicit join/timeout/escalation evidence. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md new file mode 100644 index 00000000..c0c0d4cf --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: backpressure +stinger: rust-stinger +--- + +# Tokio bounded MPSC channels + +## Summary +Tokio's bounded MPSC channel supplies backpressure by suspending senders when capacity is exhausted. Clean shutdown closes the receiver and drains buffered values; dropping the receiver drains and drops unread messages. Unbounded channels have infinite logical capacity and therefore cannot express a memory/backpressure bound. + +## Key quotations / statistics +- "the channel provides backpressure" +- "the receiver first calls `close`, which will prevent any further messages" + +## Version/date caveat +Retrieved against Tokio 1.53.1. Allocation details are explicitly implementation details and may change. + +## Annotations for stinger-forge +- Grounds bounded queue requirements and shutdown draining tests. +- Supports rejecting unbounded queues on stream/provider hot paths without a proven upper bound. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md new file mode 100644 index 00000000..d86db676 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/tokio/latest +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: tokio +stinger: rust-stinger +--- + +# Tokio current release and support policy + +## Summary +Docs.rs records Tokio 1.53.1 released 2026-07-20. Tokio states that 1.51.x is LTS through March 2027 with MSRV 1.71, while current minor releases may move faster. A fixed-minor daemon dependency can choose an LTS line, but the choice must be reconciled with required APIs and security fixes. + +## Key quotations / statistics +- "1.53.1 (2026-07-20)" +- "`1.51.x` - LTS release until March 2027. (MSRV 1.71)" + +## Version/date caveat +Patch versions and LTS designations can change; this is a retrieval-time snapshot. + +## Annotations for stinger-forge +- Use to frame current versus LTS version policy without choosing on the release peer's behalf. +- Record the transitive-dependency MSRV caveat stated by Tokio. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md new file mode 100644 index 00000000..09e162ed --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/macro.select.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: cancellation +stinger: rust-stinger +--- + +# Tokio `select!` cancellation safety + +## Summary +Tokio defines cancellation safety as dropping and recreating an incomplete future without observable loss. The docs enumerate safe and unsafe operations and warn that loops using non-cancellation-safe futures can lose data when another branch wins. This must be checked per awaited operation, not assumed because code is async. + +## Key quotations / statistics +- "it must be a no-op to drop that future and recreate it" +- "The lists in this section are not exhaustive." + +## Version/date caveat +Retrieved against Tokio 1.53.1; method-level cancellation guarantees may change and should be linked directly in code review. + +## Annotations for stinger-forge +- Core source for cancellation audits around streams, writes, queues, and database work. +- Supports focused tests for the exact boundary where visible output makes replay forbidden. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md new file mode 100644 index 00000000..60756cfc --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/src/tokio/sync/mpsc/bounded.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: permits +stinger: rust-stinger +--- + +# Tokio MPSC reserve and cancellation + +## Summary +The bounded-channel source documentation says cancelling `send` loses the message and the sender's queue position. Reserving capacity first returns a permit so message construction can occur only after capacity is secured. Outstanding permits also delay a receiver from observing final closure. + +## Key quotations / statistics +- "the message is dropped and will be lost" +- "To avoid losing messages, use `reserve`" + +## Version/date caveat +Source documentation for Tokio latest (1.53.1 at retrieval); treat internal implementation as unstable while relying on documented public behavior. + +## Annotations for stinger-forge +- Supports reserve-before-expensive-work and cancellation-focused queue tests. +- Shutdown code must account for outstanding permits, not only sender handles. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md new file mode 100644 index 00000000..dcce062a --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: middleware +stinger: rust-stinger +--- + +# Tower concurrency, buffering, and load shedding + +## Summary +`ServiceBuilder` exposes concurrency limits, buffers, timeouts, and load shedding as composable layers. Concurrency limits count in-flight requests through response-future completion. Load shedding converts lack of readiness into an immediate error rather than waiting. Layer order changes which work is bounded and which errors are visible. + +## Key quotations / statistics +- "Limit the max number of in-flight requests." +- "`LoadShed` immediately responds with an error" + +## Version/date caveat +Feature-gated Tower APIs; selected crate features and layer order must be recorded in the workspace. + +## Annotations for stinger-forge +- Supports explicit capacity/timeout/load-shed policy and layer-order tests. +- Protocol error mapping remains a peer decision; this source only establishes middleware behavior. + diff --git a/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md b/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md new file mode 100644 index 00000000..974e3456 --- /dev/null +++ b/.claude/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/trait.Service.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: readiness +stinger: rust-stinger +--- + +# Tower `Service` readiness contract + +## Summary +Tower separates readiness from dispatch. Callers must observe `poll_ready` before `call`; readiness may reserve shared resources, which implementations must release if dispatch never occurs or the response future is dropped. Capacity is therefore an ownership contract, not merely a performance hint. + +## Key quotations / statistics +- "Before dispatching a request, `poll_ready` must be called" +- readiness "may reserve shared resources" + +## Version/date caveat +Tower latest docs at retrieval; middleware can alter readiness semantics by layer order. + +## Annotations for stinger-forge +- Core evidence for backpressure-aware Tower services and adapters. +- Supports tests that cancel between readiness and call and assert permit/resource release. + diff --git a/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md new file mode 100644 index 00000000..fc5a2b46 --- /dev/null +++ b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/container-attrs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: validation +stinger: rust-stinger +--- + +# Serde container boundary attributes + +## Summary +Serde's container attributes allow unknown-field rejection, fallible conversion through `try_from`, transparent newtypes, defaults, and explicit tagging. Unknown fields are ignored by default in self-describing formats, so strict control/config inputs require an intentional choice rather than assuming fail-closed parsing. + +## Key quotations / statistics +- `deny_unknown_fields` will "Always error during deserialization when encountering unknown fields." +- By default, "unknown fields are ignored" + +## Version/date caveat +`deny_unknown_fields` cannot be combined with `flatten`; compatibility policy must account for that limitation. + +## Annotations for stinger-forge +- Grounds strict config/control-plane parsing and validated newtypes. +- Use separate input DTOs when forward-compatible wire payloads must retain unknown fields. + diff --git a/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md new file mode 100644 index 00000000..f2e288b8 --- /dev/null +++ b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/enum-representations.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: serde +stinger: rust-stinger +--- + +# Serde enum representations + +## Summary +Serde supports externally, internally, adjacently, and untagged enum encodings. Tagged enums make the selected variant explicit before or alongside content; untagged enums try variants in order and accept the first successful parse. For safety-state and protocol boundaries, representation choice affects ambiguity, forward compatibility, and error quality. + +## Key quotations / statistics +- Externally tagged data identifies "which variant we are dealing with before beginning to parse" +- Untagged "will try to match the data against each variant in order" + +## Version/date caveat +Serde project documentation; specific derive behavior still depends on the pinned serde version and enabled `alloc` feature. + +## Annotations for stinger-forge +- Supports explicit tagged enums for state/event boundaries where ambiguity is unacceptable. +- Protocol wire encoding remains the protocol peer's contract. + diff --git a/.claude/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md new file mode 100644 index 00000000..692d0b6e --- /dev/null +++ b/.claude/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/thiserror/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: errors +stinger: rust-stinger +--- + +# thiserror structured errors + +## Summary +thiserror 2.0.19 derives standard error implementations without becoming part of the public API contract. `source`, `from`, and `transparent` preserve causal chains, while an opaque public wrapper can hide a private evolving representation. Redaction still depends on the chosen fields and Display text. + +## Key quotations / statistics +- "Errors may use `error(transparent)` to forward the source and Display methods" +- "hiding implementation details ... behind an opaque error type" + +## Version/date caveat +Version 2.0.19 was published six days before retrieval; pin and test formatting if machine parsing depends on it. + +## Annotations for stinger-forge +- Supports domain error enums at crate boundaries and opaque public errors. +- Do not place secrets/prompts in source error values or formatted context. + diff --git a/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md new file mode 100644 index 00000000..e079d17a --- /dev/null +++ b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/type.Error.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: exits +stinger: rust-stinger +--- + +# Clap error and exit behavior + +## Summary +Clap errors expose their kind, rendered form, stderr/stdout routing, printing, and exit code. Library/test paths can use non-exiting parse APIs, while the process boundary decides when to print and exit. Operational failures after parsing need a separate stable exit-code taxonomy. + +## Key quotations / statistics +- The error API includes `exit_code`. +- The error API includes `use_stderr` and `render`. + +## Version/date caveat +Clap 4.6.2 at retrieval; exact human rendering is not a stable machine protocol. + +## Annotations for stinger-forge +- Supports separating parse errors from domain/transport exit codes. +- Require JSON/stdout contracts to avoid scraping colored human help/error output. + diff --git a/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md new file mode 100644 index 00000000..f15fca06 --- /dev/null +++ b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/parser/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: clap +stinger: rust-stinger +--- + +# Clap typed command-line parsing + +## Summary +Clap 4.6.2 provides `Parser`, `Subcommand`, `Args`, `CommandFactory`, and `ValueEnum` traits for typed command structures and introspection. These types support explicit command inventories, constrained values, generated help/completions, and parser tests independent of process execution. + +## Key quotations / statistics +- `ValueEnum`: "Parse arguments into enums." +- `CommandFactory`: "Create a `Command` relevant for a user-defined container." + +## Version/date caveat +Clap 4.6.2 at retrieval; help text and formatting can change across minor releases. + +## Annotations for stinger-forge +- Supports typed subcommands and deterministic parser contract tests. +- Machine-readable command output is an application schema layered above Clap. + diff --git a/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md new file mode 100644 index 00000000..98784587 --- /dev/null +++ b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: medium +topic: tui +stinger: rust-stinger +--- + +# Ratatui crate architecture + +## Summary +Ratatui's primary crate re-exports the application-facing surface, while lower-level workspace crates exist for custom widget libraries and backend-specific integrations. The docs recommend staying in the main crate unless a lower-level dependency is specifically needed, reducing feature and compile-time surface for ordinary applications. + +## Key quotations / statistics +- "Most application authors should stay in this `ratatui` crate." +- "Reach for other crates ... only when you specifically need a lower-level layer" + +## Version/date caveat +Ratatui 0.30.2; workspace decomposition may evolve. + +## Annotations for stinger-forge +- Supports avoiding premature internal TUI crate fragmentation. +- Feature-gate the entire TUI and keep domain/control logic outside it. + diff --git a/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md new file mode 100644 index 00000000..bc52308f --- /dev/null +++ b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/init/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: terminal +stinger: rust-stinger +--- + +# Ratatui terminal initialization and restoration + +## Summary +Ratatui 0.30.2 recommends `run` for ownership of terminal setup/cleanup, or fallible `try_init`/`try_restore` when the application needs explicit handling. Helpers manage raw mode, alternate screen, and a panic hook that restores the terminal. Manual construction transfers teardown responsibility to the application. + +## Key quotations / statistics +- `run` "automatically restores the terminal state" +- "All initialization functions install a panic hook" + +## Version/date caveat +`run` was introduced in 0.30.0; older examples may show manual lifecycle code. + +## Annotations for stinger-forge +- Grounds terminal cleanup on success, error, panic, and cancellation. +- Favor the headless CLI/control client; keep the TUI a thin optional surface. + diff --git a/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md new file mode 100644 index 00000000..afcd9d15 --- /dev/null +++ b/.claude/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/backend/struct.TestBackend.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: rendering +stinger: rust-stinger +--- + +# Ratatui `TestBackend` + +## Summary +Ratatui's `TestBackend` renders an integration-level terminal UI to an in-memory buffer and can assert lines, cursor, resize, and scrollback. The docs prefer direct widget-buffer tests for units and reserve `TestBackend` for whole-TUI integration, giving two appropriately sized evidence layers. + +## Key quotations / statistics +- "renders to an memory buffer" +- "preferable to write unit tests for widgets directly against the buffer" + +## Version/date caveat +Ratatui 0.30.2 at retrieval; snapshot glyph/width behavior can vary with terminal/unicode dependencies. + +## Annotations for stinger-forge +- Supports deterministic TUI rendering tests without a real terminal. +- Add narrow real-terminal smoke tests only where lifecycle/platform integration matters. + diff --git a/.claude/skills/rust-stinger/research/evidence-synthesis.md b/.claude/skills/rust-stinger/research/evidence-synthesis.md new file mode 100644 index 00000000..70a55448 --- /dev/null +++ b/.claude/skills/rust-stinger/research/evidence-synthesis.md @@ -0,0 +1,178 @@ +# Rust Stinger Evidence Synthesis + +This is an evidence map for Stinger Forge, not a replacement for the product ADR, protocol contract, Security review, dependency/license decision, release authorization, or Quality report. The 56 indexed source notes are authoritative inputs; this file connects them to the Command Brief's research questions and records the remaining decisions honestly. +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +## Current anchors at retrieval + +| Surface | Current evidence snapshot | Caveat | +|---|---|---| +| Rust | 1.97.1 released 2026-07-16 | Current stable is not automatically the product MSRV. | +| Cargo | Rust 2024 resolver v3; `rust-version`-aware fallback | Virtual workspaces must declare the resolver; CI must prove MSRV. | +| Tokio | 1.53.1 released 2026-07-20; 1.51.x LTS through March 2027 | Tokio's MSRV does not establish the whole graph's MSRV. | +| Axum | 0.8.9 docs snapshot | Pin compatible hyper/http-body/tower versions together. | +| SQLx | 0.9.0 docs snapshot | `begin_with` is version-specific; verify before applying to SQLx 0.8. | +| Clap / Ratatui | 4.6.2 / 0.30.2 | Human rendering and TUI APIs can change across minor versions. | +| rustls | 0.23.42 stable docs; 0.24 development docs also visible | Avoid accidental dependency on development APIs. | +| Testing | Loom 0.7.2; Criterion 0.8.2 | Model and benchmark results have explicit coverage/environment limits. | +| SBOM | cargo-cyclonedx 0.5.9 (2026-03-19) | Cargo native SBOM precursors remain unstable/nightly. | + +## 1. Tokio, Axum, and Tower ownership, cancellation, streaming, and shutdown + +The sources converge on a verifiable lifecycle made of distinct obligations: + +1. A root owner detects shutdown, signals cooperative cancellation, stops admission, and waits for every owned task. Tokio's shutdown guide explicitly separates trigger, notification, and joining. +2. Bounded MPSC channels express a capacity contract. Clean shutdown closes the receiver and drains it. `send` inside `select!` may lose the message; `reserve` obtains capacity first and makes that boundary testable. +3. Every `select!` branch needs method-level cancellation review. "Async" alone does not imply cancellation safety. +4. Tower readiness is a resource reservation. `poll_ready` must precede `call`, and capacity must be released if dispatch or its future is dropped. Concurrency-limit, buffer, timeout, and load-shed layer order changes observable behavior. +5. Axum can serve a fallible stream as a response body. HTTP consumers pull frames; the upstream producer must still be bounded and cancellation-aware. Dropping/disconnecting the body should stop producer work and release permits in focused tests. +6. `with_graceful_shutdown` owns listener/connection admission, not arbitrary background work. Background task ownership remains in Tokio task tracking. +7. Most router/middleware contracts can be tested by invoking the Router as a Tower service without binding a port. A narrower loopback integration test proves bind address, shutdown, and disconnect behavior. + +Primary notes: [Tokio shutdown](async/2026-07-24-tokio-graceful-shutdown.md), [MPSC](async/2026-07-24-tokio-mpsc.md), [`select!`](async/2026-07-24-tokio-select-cancellation.md), [reserve](async/2026-07-24-tokio-send-reserve.md), [Tower readiness](async/2026-07-24-tower-service-readiness.md), [Tower layers](async/2026-07-24-tower-service-builder.md), [Axum shutdown](async/2026-07-24-axum-graceful-shutdown.md), [Axum streaming](async/2026-07-24-axum-streaming-body.md), and [service testing](async/2026-07-24-axum-service-testing.md). + +## 2. SQLite and SQLx transactions, locking, and durability + +SQLite permits a single writer. `BEGIN DEFERRED` can read a stale budget view and then fail during write upgrade; `BEGIN IMMEDIATE` acquires write intent before the read-modify-write sequence. SQLx 0.9's `Connection::begin_with` provides a tracked custom transaction start, enabling `BEGIN IMMEDIATE` while preserving explicit commit/rollback and rollback-on-drop behavior. + +Evidence-supported invariants for reservations/reconciliations/breakers/migrations: + +- Acquire the write transaction before reading mutable budget/quota state. +- Keep eligibility check, reservation insert/update, aggregate update, and idempotency record in one transaction. +- Use conditional SQL constraints/updates as the final oversubscription guard; application locks are not sufficient across processes. +- Treat `SQLITE_BUSY` as a bounded, observable contention result. A busy timeout is not permission for invisible unbounded retry. +- Configure and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy through one connection-options path. +- WAL improves reader/writer concurrency but does not allow multiple writers. Long readers can starve checkpoints and grow the WAL. +- WAL plus `synchronous=NORMAL` can lose recent committed transactions after power loss. Product durability language must match the chosen PRAGMA contract. +- Crash evidence should kill/restart at transaction and checkpoint boundaries and verify all-or-none invariants. Preserve the database and its WAL/SHM/journal companions during recovery. +- Embedded migrations improve delivery but do not replace forward-only migration, old-binary/new-schema compatibility, and interruption tests. + +Primary notes: [transactions](persistence/2026-07-24-sqlite-transactions.md), [WAL](persistence/2026-07-24-sqlite-wal.md), [atomic commit](persistence/2026-07-24-sqlite-atomic-commit.md), [PRAGMAs](persistence/2026-07-24-sqlite-pragma-durability.md), [SQLx options](persistence/2026-07-24-sqlx-connect-options.md), [custom transactions](persistence/2026-07-24-sqlx-custom-transactions.md), and [queries/migrations](persistence/2026-07-24-sqlx-migrations-queries.md). + +## 3. Typed state machines and replay/promotion proof + +Rust's enums, newtypes, privacy, exhaustive matching, and ownership can make invalid transitions difficult to express. The strongest upstream example in this corpus is rustls: private marker values bind the fact that verification occurred and prevent skipping required checks before entering the traffic state. + +Evidence-supported design constraints for Forge to encode: + +- Persist durable facts as an explicit tagged enum/event schema; avoid ambiguous untagged parsing for safety state. +- Reject unknown fields on strict local control/config inputs unless an explicit compatibility contract requires otherwise. +- Use private constructors and non-forgeable capability/marker types for facts such as `NoVisibleOutput`, `NoToolCall`, `ReservationHeld`, or `SafeTurnReviewed`. +- Consume one-shot proof values on transition so replay/promotion cannot accidentally reuse authorization. +- Keep provider events and harness events in edge crates, normalize them into protocol-neutral domain facts, and let the state machine depend only on those facts. +- Represent terminal/irreversible states explicitly and test every transition plus serialization round trip against a reference model. +- Keep user-visible error codes separate from internal causal chains; neither should contain prompts, raw credentials, or headers. + +Primary notes: [Serde enums](boundaries/2026-07-24-serde-enum-representations.md), [strict attributes](boundaries/2026-07-24-serde-container-attributes.md), [thiserror](boundaries/2026-07-24-thiserror.md), [rustls builder typestate](security/2026-07-24-rustls-config-builder.md), and [verification markers](security/2026-07-24-rustls-verification-markers.md). + +## 4. Cargo workspace and MSRV evidence + +Resolver v3 is global at the top-level workspace. Features remain additive and can unify through dependency paths, so crate boundaries and feature design must prevent provider/TUI/TLS choices from leaking into protocol, policy, and state cores. + +A reviewable dependency direction for the accepted architecture is: + +```text +protocol/types <- policy/state <- provider adapters + ^ ^ ^ + | | | + daemon/control ----+--------------+ + ^ + CLI <- optional TUI + +test-support/evaluation may depend on public seams; +production crates must not depend on test-support. +``` + +This is a research-derived dependency constraint, not approval of exact crate names. Workspace review should look for: + +- one owner per invariant rather than a crate per noun; +- `resolver = "3"` in a virtual workspace; +- shared dependency versions/features declared centrally where that reduces drift; +- provider and TUI features default-off unless the product requires otherwise; +- `cargo tree -e features`, all-target/all-feature checks, and representative minimal-feature checks; +- public types flowing inward only from the approved protocol/domain crate, never harness/provider SDK types; +- a documented unsafe inventory, defaulting to `forbid(unsafe_code)` where possible. + +For a new removable local daemon, the credible starting toolchain is a pinned current stable release (1.97.1 at retrieval), with `package.rust-version` declared only after the full resolved graph and advertised features pass MSRV CI. Tokio 1.51.x is an available 2026 LTS line with MSRV 1.71, but that fact alone is not a reason to choose Rust 1.71 for the product. Re-check stable, platform tiers, and dependency MSRVs immediately before Forge freezes guidance. + +Primary notes: [current Rust](rust-cargo/2026-07-24-rust-release-1-97.md), [`rust-version`](rust-cargo/2026-07-24-cargo-rust-version.md), [resolver v3](rust-cargo/2026-07-24-cargo-resolver-v3.md), [features](rust-cargo/2026-07-24-cargo-features.md), [platform tiers](rust-cargo/2026-07-24-platform-support.md), [Cargo CI](rust-cargo/2026-07-24-cargo-ci-msrv.md), [Clippy](rust-cargo/2026-07-24-clippy-ci.md), and [Tokio release policy](async/2026-07-24-tokio-release-policy.md). + +## 5. Tracing, secrets, and TLS + +- `#[instrument]` captures all arguments by default, including Debug output. Sensitive functions should start from `skip_all` and add allowlisted identifiers/state fields. +- Libraries emit structured spans/events; binaries own subscriber/filter/sink initialization. Libraries should not set the global subscriber. +- Secret wrappers reduce accidental exposure and require explicit access, but do not replace a secret store and cannot prevent every copy during deserialization. +- rustls stable builders encode mandatory verifier/certificate choices and use safe defaults. Custom verifier APIs are deliberately marked dangerous and require Security review. +- TLS/provider selection, certificate roots, egress/redirect/DNS/SSRF controls, redaction acceptance, and crash-dump policy remain Security/platform decisions. + +Primary notes: [instrument capture](observability/2026-07-24-tracing-instrument.md), [subscriber ownership](observability/2026-07-24-tracing-subscriber.md), [secrecy](security/2026-07-24-secrecy.md), and [rustls](security/2026-07-24-rustls-config-builder.md). + +## 6. CLI and TUI evidence + +Clap supports typed subcommands, constrained enums, introspection, and non-exiting parse paths. Human help/error formatting should not become the machine protocol; define stable JSON/stdout schemas and a separate domain exit-code taxonomy. Destructive or billable commands need an explicit confirmation/noninteractive policy above Clap. + +Ratatui 0.30's `run` owns terminal initialization and restoration, including panic cleanup. Fallible init/restore APIs exist for explicit error handling. `TestBackend` provides deterministic integration rendering; direct buffer/widget tests are preferred for units. The TUI should remain feature-gated and depend on the same authenticated control client as the CLI rather than becoming a second authority. + +Primary notes: [Clap parser](cli-tui/2026-07-24-clap-parser.md), [Clap errors](cli-tui/2026-07-24-clap-errors.md), [terminal lifecycle](cli-tui/2026-07-24-ratatui-lifecycle.md), [TestBackend](cli-tui/2026-07-24-ratatui-test-backend.md), and [Ratatui architecture](cli-tui/2026-07-24-ratatui-architecture.md). + +## 7. Verification stack, including eight-hour soak evidence + +| Evidence layer | Primary mechanism | What it proves | Main limitation | +|---|---|---|---| +| Unit/contract | `cargo test`, direct Axum/Tower service calls | Pure logic, types, HTTP/service contracts | Does not prove listener/process behavior. | +| Deterministic time | Tokio `start_paused`, injected clocks | Timeouts, retry schedules, breakers, pins, promotion windows | Only controlled clocks advance. | +| Property/state | proptest + persisted seeds | Invariants across generated values/transition sequences | Current state-machine helper is sequential. | +| Model concurrency | Loom on small primitives | Explored synchronization interleavings | Requires Loom types; state explosion; not DB/process proof. | +| Persistence/concurrency | real temp SQLite, multiple connections/processes, fault injection | Write contention, idempotency, migration and crash recovery | Needs platform/filesystem coverage. | +| Provider/stream | fake HTTP servers and transcript fixtures | chunk ordering, cancellation, replay boundary, error normalization | Fixture drift must be managed; no live credentials. | +| Suite execution | cargo-nextest profiles, timeouts, JUnit | Isolation, classification, evidence export | Doctests remain separate; retries can mask flaws. | +| Microbenchmark | Criterion on controlled hosts | throughput/latency trends with confidence intervals | Noisy shared CI can mislead. | +| Eight-hour soak | purpose-built release harness under nextest/process supervisor | bounded memory/queues, handle/task cleanup, WAL growth/checkpoints, reconnect stability | No single crate proves this; requires explicit invariants and periodic telemetry. | + +An eight-hour soak should use fake providers and local fixtures, emit periodic bounded metrics (RSS, task count, queue depth, DB/WAL size, open handles, request/error counters), assert no monotonic leak or invariant breach, capture start/end versions/config/seeds, and fail on flaky retry. It is separate from Criterion and from Loom. + +Primary notes: [proptest state machines](testing/2026-07-24-proptest-state-machines.md), [Loom](testing/2026-07-24-loom.md), [Tokio time](testing/2026-07-24-tokio-time-testing.md), [nextest](testing/2026-07-24-nextest.md), [flaky retries](testing/2026-07-24-nextest-retries.md), and [Criterion](testing/2026-07-24-criterion-analysis.md). + +## 8. Packaging, SBOM, signing, and advisory evidence + +A credible 2026 release-evidence packet can contain target-specific archives/installers, hashes, install/uninstall transcripts, SBOM, embedded dependency metadata, advisory/license/source scan results, and provenance/signature verification. The tools have complementary roles: + +- cargo-dist builds target archives/installers and hashes; generated output and tool version must be pinned/reviewed. +- cargo-cyclonedx generates standardized SBOMs and supports `SOURCE_DATE_EPOCH`/target-aware output as of 0.5.9. +- cargo-auditable embeds dependency information in binaries for later scanning. +- cargo-deny supplies advisory/license/ban/source policy evidence but does not prove legal clearance. +- RustSec/cargo-audit produces point-in-time lockfile/binary advisory findings; record database time and lockfile/artifact hash. +- Cosign signs blobs and emits verification bundles; signing/publishing is an explicitly authorized external effect. +- Cargo's native SBOM precursor is still unstable/nightly and should remain supplemental for a stable baseline. +- `cargo package` verifies crate contents/buildability but explicitly does not prove provenance. + +Primary notes: [dist config](supply-chain/2026-07-24-cargo-dist-config.md), [dist attestations](supply-chain/2026-07-24-cargo-dist-attestations.md), [cargo-cyclonedx](supply-chain/2026-07-24-cargo-cyclonedx.md), [cargo-auditable](supply-chain/2026-07-24-cargo-auditable.md), [cargo-deny](supply-chain/2026-07-24-cargo-deny-checks.md), [license limits](supply-chain/2026-07-24-cargo-deny-license-limitations.md), [RustSec](supply-chain/2026-07-24-rustsec.md), [cargo-audit](supply-chain/2026-07-24-cargo-audit.md), [Cosign](supply-chain/2026-07-24-sigstore-cosign-blob.md), [Cargo SBOM](supply-chain/2026-07-24-cargo-sbom-unstable.md), and [cargo package](supply-chain/2026-07-24-cargo-package-verification.md). + +## Peer-boundary map + +| Area | Rust Bee may implement/prove | Peer retains final authority | +|---|---|---| +| HTTP/MCP/provider protocol | Approved types, adapters, fixtures, streaming behavior | Protocol semantics and compatibility | +| Security/TLS/secrets/logs | Safe defaults, redaction mechanics, tests | Threat model and acceptance | +| SQLite/SQLx | Transactions, migrations, concurrency/crash tests | Schema/data architecture review | +| Dependencies/SBOM/licenses | Generate exact reports/artifacts | Exceptions, license/advisory disposition | +| Release/CI | Rust build/package configuration and local proof | CI topology, signing identity, publication | +| Quality | Acceptance-linked implementation evidence | Final PRD implementation audit | + +## Open decisions for the user/orchestrator + +1. Exact supported OS/architecture/install matrix and minimum OS/glibc baselines. +2. Whether the initial toolchain pins current stable or a selected older stable after the dependency graph exists; no evidence supports claiming an MSRV before that graph is tested. +3. Required power-loss durability: WAL `FULL`, WAL `NORMAL`, or another documented contract. +4. Maximum writer wait/busy timeout and user-visible contention behavior. +5. Exact state/event schema for visible output, tool calls, reservation, replay prohibition, and safe-turn promotion. +6. Whether the optional TUI is inside the first executable milestone. +7. Release signing identity/attestation platform and which installer formats are authorized. +8. Quantitative pass/fail thresholds for the eight-hour soak (RSS slope, WAL growth, task/handle counts, throughput/error rate). + +## Tool provenance limitation + +The research packet uses the configured Context7 service plus current direct official/upstream documentation retrieval. No raw web-crawl JSON exists; this limitation is explicit so Forge does not mistake the corpus for a web-crawl corpus. + diff --git a/.claude/skills/rust-stinger/research/index.md b/.claude/skills/rust-stinger/research/index.md new file mode 100644 index 00000000..9636d31a --- /dev/null +++ b/.claude/skills/rust-stinger/research/index.md @@ -0,0 +1,64 @@ +# Research Index: rust-stinger + +Generated by scripture-historian. Updated after every source-file write. + +Snapshot: 2026-07-24. Version-sensitive values in this packet are evidence snapshots, not timeless defaults; revalidate at the point of use. + +| File | Source type | Authority | Relevance | Topic | +|---|---|---|---|---| +| `rust-cargo/2026-07-24-rust-release-1-97.md` | changelog | official | critical | toolchain | +| `rust-cargo/2026-07-24-cargo-rust-version.md` | official-docs | official | critical | msrv | +| `rust-cargo/2026-07-24-cargo-resolver-v3.md` | official-docs | official | critical | resolver | +| `rust-cargo/2026-07-24-cargo-features.md` | official-docs | official | high | features | +| `rust-cargo/2026-07-24-platform-support.md` | official-docs | official | critical | targets | +| `rust-cargo/2026-07-24-cargo-ci-msrv.md` | official-docs | official | high | ci | +| `rust-cargo/2026-07-24-clippy-ci.md` | official-docs | official | high | linting | +| `rust-cargo/2026-07-24-unsafe-rust.md` | official-docs | official | high | unsafe | +| `async/2026-07-24-tokio-release-policy.md` | changelog | official | critical | tokio | +| `async/2026-07-24-tokio-graceful-shutdown.md` | official-docs | official | critical | shutdown | +| `async/2026-07-24-tokio-mpsc.md` | official-docs | official | critical | backpressure | +| `async/2026-07-24-tokio-select-cancellation.md` | official-docs | official | critical | cancellation | +| `async/2026-07-24-tokio-send-reserve.md` | official-docs | official | high | permits | +| `async/2026-07-24-tower-service-readiness.md` | official-docs | official | critical | readiness | +| `async/2026-07-24-tower-service-builder.md` | official-docs | official | high | middleware | +| `async/2026-07-24-axum-graceful-shutdown.md` | official-docs | official | critical | axum | +| `async/2026-07-24-axum-service-testing.md` | official-docs | official | high | testing | +| `async/2026-07-24-axum-streaming-body.md` | official-docs | official | critical | streaming | +| `persistence/2026-07-24-sqlite-transactions.md` | official-docs | official | critical | transactions | +| `persistence/2026-07-24-sqlite-wal.md` | official-docs | official | critical | wal | +| `persistence/2026-07-24-sqlite-atomic-commit.md` | official-docs | official | critical | recovery | +| `persistence/2026-07-24-sqlite-pragma-durability.md` | official-docs | official | critical | durability | +| `persistence/2026-07-24-sqlx-connect-options.md` | official-docs | official | critical | sqlx | +| `persistence/2026-07-24-sqlx-migrations-queries.md` | official-docs | official | high | migrations | +| `persistence/2026-07-24-sqlx-custom-transactions.md` | official-docs | official | critical | locking | +| `boundaries/2026-07-24-serde-enum-representations.md` | official-docs | official | critical | serde | +| `boundaries/2026-07-24-serde-container-attributes.md` | official-docs | official | high | validation | +| `boundaries/2026-07-24-thiserror.md` | official-docs | official | high | errors | +| `observability/2026-07-24-tracing-instrument.md` | official-docs | official | critical | tracing | +| `observability/2026-07-24-tracing-subscriber.md` | official-docs | official | high | subscriber | +| `security/2026-07-24-secrecy.md` | official-docs | official | high | secrets | +| `security/2026-07-24-rustls-config-builder.md` | official-docs | official | critical | tls | +| `security/2026-07-24-rustls-verification-markers.md` | official-docs | official | critical | typestate | +| `cli-tui/2026-07-24-clap-parser.md` | official-docs | official | high | clap | +| `cli-tui/2026-07-24-clap-errors.md` | official-docs | official | high | exits | +| `cli-tui/2026-07-24-ratatui-lifecycle.md` | official-docs | official | high | terminal | +| `cli-tui/2026-07-24-ratatui-test-backend.md` | official-docs | official | high | rendering | +| `cli-tui/2026-07-24-ratatui-architecture.md` | official-docs | official | medium | tui | +| `testing/2026-07-24-proptest-state-machines.md` | official-docs | official | critical | proptest | +| `testing/2026-07-24-proptest-index.md` | official-docs | official | high | properties | +| `testing/2026-07-24-loom.md` | official-docs | official | critical | loom | +| `testing/2026-07-24-tokio-time-testing.md` | official-docs | official | critical | faketime | +| `testing/2026-07-24-nextest.md` | official-docs | official | high | nextest | +| `testing/2026-07-24-nextest-retries.md` | official-docs | official | high | flakiness | +| `testing/2026-07-24-criterion-analysis.md` | official-docs | official | high | benchmark | +| `supply-chain/2026-07-24-cargo-dist-config.md` | official-docs | official | critical | packaging | +| `supply-chain/2026-07-24-cargo-dist-attestations.md` | official-docs | official | high | provenance | +| `supply-chain/2026-07-24-cargo-cyclonedx.md` | changelog | official | critical | sbom | +| `supply-chain/2026-07-24-cargo-auditable.md` | github-readme | practitioner | high | auditability | +| `supply-chain/2026-07-24-cargo-deny-checks.md` | official-docs | official | high | policy | +| `supply-chain/2026-07-24-cargo-deny-license-limitations.md` | official-docs | official | high | licenses | +| `supply-chain/2026-07-24-rustsec.md` | official-docs | official | critical | advisories | +| `supply-chain/2026-07-24-cargo-audit.md` | github-readme | official | critical | cargo-audit | +| `supply-chain/2026-07-24-sigstore-cosign-blob.md` | official-docs | official | high | signing | +| `supply-chain/2026-07-24-cargo-sbom-unstable.md` | official-docs | official | high | cargo-sbom | +| `supply-chain/2026-07-24-cargo-package-verification.md` | official-docs | official | high | package | diff --git a/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md b/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md new file mode 100644 index 00000000..95f928d0 --- /dev/null +++ b/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/attr.instrument.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tracing +stinger: rust-stinger +--- + +# `tracing::instrument` field capture + +## Summary +`#[instrument]` records function arguments by default, using `Value` or `Debug`. `skip` and `skip_all` explicitly exclude arguments, and replacement fields can record safe identifiers. This default makes unreviewed instrumentation a direct secret/prompt leakage risk at sensitive boundaries. + +## Key quotations / statistics +- "By default, all arguments to the function are included as fields" +- `skip_all` can "skip all arguments" + +## Version/date caveat +Retrieved against tracing 0.1.44; macro capture policy is current at access time. + +## Annotations for stinger-forge +- Critical source for a `skip_all`-first rule on provider, prompt, credential, and SQL boundaries. +- Add explicit allowlisted correlation/state fields rather than relying on Debug. + diff --git a/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md b/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md new file mode 100644 index 00000000..0cffcd7a --- /dev/null +++ b/.claude/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: subscriber +stinger: rust-stinger +--- + +# tracing library/subscriber ownership + +## Summary +Tracing libraries emit spans/events but executables install subscribers that collect and format them. The docs warn libraries not to set a global default because that conflicts with downstream executables. This creates a clean crate boundary: libraries describe structured events; daemon/CLI binaries own filtering, sinks, and output format. + +## Key quotations / statistics +- "Libraries should link only to the `tracing` crate" +- "libraries should not call `set_global_default()`" + +## Version/date caveat +Tracing 0.1.44 documentation; subscriber features and ecosystem layers vary independently. + +## Annotations for stinger-forge +- Grounds observability dependency direction and binary-owned initialization. +- Security/redaction review remains a peer gate even when field ownership is correct. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md new file mode 100644 index 00000000..1a2dfba4 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/atomiccommit.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: recovery +stinger: rust-stinger +--- + +# SQLite atomic commit and crash recovery + +## Summary +SQLite documents how rollback journals provide atomic commit across process, OS, and power failures, including hot-journal recovery. It also documents assumptions and failure modes around filesystem locking, sync behavior, file renames, and deletion of journals. SQLite's own confidence rests on fault-injecting VFS crash tests, not code inspection alone. + +## Key quotations / statistics +- "either all database changes within a single transaction occur or none" +- "crash tests ... simulate incomplete sector writes" + +## Version/date caveat +This page primarily describes rollback-journal mode; WAL atomicity uses a different mechanism documented separately. + +## Annotations for stinger-forge +- Strong evidence for crash/restart and filesystem-fault tests around local state. +- Preserve database, WAL, SHM, and journal files together during recovery/support operations. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md new file mode 100644 index 00000000..cfe565e1 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md @@ -0,0 +1,26 @@ +--- +source_url: https://sqlite.org/pragma.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: durability +stinger: rust-stinger +--- + +# SQLite PRAGMA durability controls + +## Summary +SQLite's PRAGMA reference defines `journal_mode`, `synchronous`, `busy_timeout`, foreign-key enforcement, and checkpoint controls. The durability contract changes by journal mode and synchronous level; `OFF` does not sync, while WAL plus `NORMAL` trades away recent-transaction durability on power loss. + +## Key quotations / statistics +- "you lose durability across power loss with synchronous NORMAL in WAL mode" +- With `synchronous=OFF`, SQLite proceeds "without syncing" + +## Version/date caveat +Official reference retrieved 2026-07-24; platform VFS behavior can still weaken guarantees. + +## Annotations for stinger-forge +- Use to require explicit, tested connection PRAGMAs rather than driver defaults. +- Final durability policy is an architecture/product decision and should be recorded. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md new file mode 100644 index 00000000..02a13e90 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/lang_transaction.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: transactions +stinger: rust-stinger +--- + +# SQLite transaction semantics + +## Summary +SQLite permits multiple simultaneous readers but only one write transaction. `BEGIN DEFERRED` delays lock acquisition and can fail when upgrading a read to a write; `BEGIN IMMEDIATE` attempts to acquire the write transaction at the start and returns `SQLITE_BUSY` if another writer is active. Nested `BEGIN` transactions are not supported. + +## Key quotations / statistics +- "Transactions created using BEGIN...COMMIT do not nest." +- "BEGIN IMMEDIATE might fail with SQLITE_BUSY" + +## Version/date caveat +SQLite official page published within the six-month research window. Exact busy behavior also depends on connection busy timeout and transaction duration. + +## Annotations for stinger-forge +- Critical for reservation/reconciliation write serialization and busy-retry design. +- Supports acquiring write intent before reading budget state when the operation must be atomic. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md new file mode 100644 index 00000000..b3143ac4 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/wal.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: wal +stinger: rust-stinger +--- + +# SQLite write-ahead logging + +## Summary +WAL mode separates writes from checkpoints, permits readers alongside a writer, and persists as a database property. Automatic checkpoints occur at a default threshold of 1000 pages. Long readers can prevent checkpoint completion and grow the WAL; `synchronous=NORMAL` can lose recent committed transactions after power loss even while preserving database consistency. + +## Key quotations / statistics +- "By default, SQLite does a checkpoint automatically" at 1000 pages. +- With `synchronous=NORMAL`, "transactions are no longer durable" across power failure. + +## Version/date caveat +Official SQLite page updated in the research window; durability claims depend on VFS/filesystem correctness. + +## Annotations for stinger-forge +- Grounds explicit journal, synchronous, checkpoint, and reader-lifetime choices. +- Contradicts any blanket claim that WAL plus NORMAL implies full power-loss durability. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md new file mode 100644 index 00000000..dcc861a0 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/sqlite/struct.SqliteConnectOptions.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: sqlx +stinger: rust-stinger +--- + +# SQLx SQLite connection options + +## Summary +`SqliteConnectOptions` exposes journal, locking, synchronous, busy-timeout, foreign-key, and statement settings. SQLx deliberately does not select a journal mode by default; WAL persists in the database and switching away from it may require an exclusive lock. The default busy timeout is five seconds. + +## Key quotations / statistics +- "SQLx does not set a journal mode by default" +- "The default busy timeout is 5 seconds." + +## Version/date caveat +SQLx latest docs at retrieval (the docs index reported 0.9.0). Verify APIs against the actually pinned SQLx release. + +## Annotations for stinger-forge +- Grounds a single audited connection-options builder and startup verification of effective PRAGMAs. +- Prevent per-connection configuration drift in pools. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md new file mode 100644 index 00000000..b3ef08b7 --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/trait.Connection.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: locking +stinger: rust-stinger +--- + +# SQLx custom transaction start + +## Summary +SQLx 0.9.0 exposes `Connection::begin_with` to begin a tracked transaction using a database-specific statement. This permits SQLite `BEGIN IMMEDIATE` while retaining the `Transaction` commit/rollback API. The function rejects statements that do not actually enter a transaction, which is safer than issuing an unrelated raw statement and assuming tracking. + +## Key quotations / statistics +- "Begin a new transaction with a custom statement." +- It errors if the statement "does not put the connection into a transaction." + +## Version/date caveat +This API appears in SQLx 0.9.0; SQLx 0.8-era projects need a version-specific alternative and should not copy the call blindly. + +## Annotations for stinger-forge +- Resolves the primary SQLx mechanism for write-intent acquisition before budget reads. +- Pair with bounded busy handling, conditional updates, and concurrency/crash tests. + diff --git a/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md new file mode 100644 index 00000000..74a7899d --- /dev/null +++ b/.claude/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: migrations +stinger: rust-stinger +--- + +# SQLx query macros and embedded migrations + +## Summary +SQLx provides compile-time checked query macros and `migrate!`, which embeds migrations into the binary. Query macros require a build-time schema connection or checked-in `.sqlx` offline metadata. Embedded migrations improve deployability but do not replace forward-only migration policy, crash tests, and schema-version compatibility checks. + +## Key quotations / statistics +- "The `migrate!` macro embeds migrations into the binary" +- "The `query!` macro allows for statically checked SQL queries" + +## Version/date caveat +SQLx latest docs at retrieval; offline metadata commands and migration macro rebuild behavior vary by release/build system. + +## Annotations for stinger-forge +- Supports compile-checked repository queries and migration packaging tests. +- Database schema review remains a peer boundary; this source covers Rust integration mechanics. + diff --git a/.claude/skills/rust-stinger/research/research-plan.md b/.claude/skills/rust-stinger/research/research-plan.md new file mode 100644 index 00000000..7c00d1ca --- /dev/null +++ b/.claude/skills/rust-stinger/research/research-plan.md @@ -0,0 +1,91 @@ +# Research Plan: rust-stinger + +- **Depth tier:** deep +- **Time window:** 2026-07-24 back to 2026-01-24 (6 months) +- **Page budget target:** 1,000 page-equivalents across official documentation sets, upstream repositories, release notes, and standards/tooling references +- **Source breadth target:** official language/toolchain documentation, upstream crate documentation, upstream GitHub repositories, SQLite specifications, security advisories, release/changelog material, standards/provenance specifications +- **Discovery caveat:** The initial queries below are reconstructed from the Command Brief's primary research targets and research questions. Research used Context7 documentation retrieval and direct official/upstream pages; this limitation is preserved in the final summary. + +## Initial queries (derived from the Command Brief) + +- "Rust Cargo workspace architecture MSRV feature unification platform support 2026" +- "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" +- "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" +- "Rust typed state machines replay prohibition safe promotion error boundaries 2026" +- "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" +- "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" +- "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" +- "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +## Expansion queries + +### Branch from "Rust Cargo workspace architecture MSRV feature unification platform support 2026" + +- "Cargo resolver version 3 workspace dependency inheritance feature unification official" +- "Rust MSRV policy rust-version Cargo official platform support tier policy" +- "Cargo workspace compile time crate boundaries feature flags official guidance" +- "Rust API Guidelines unsafe code guidelines Clippy rustfmt official" + +### Branch from "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" + +- "Tokio task cancellation safety JoinSet CancellationToken graceful shutdown official" +- "Tokio bounded mpsc backpressure reserve Permit shutdown channel official" +- "Axum with_graceful_shutdown streaming Body cancellation official" +- "Tower Service readiness load shed concurrency limit timeout buffer backpressure official" +- "Tokio time pause advance deterministic tests tracing official" + +### Branch from "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" + +- "SQLite BEGIN IMMEDIATE transaction locking WAL busy timeout synchronous official" +- "SQLite atomic commit crash recovery WAL checkpoint durability official" +- "SQLx SQLite transaction acquire begin immediate migrations official" +- "SQLite concurrent reservation budget oversubscription conditional update RETURNING official" +- "SQLx offline mode compile checked queries migrations locking upstream" + +### Branch from "Rust typed state machines replay prohibition safe promotion error boundaries 2026" + +- "Rust enum typestate state machine exhaustive matching official" +- "Rust ownership newtype sealed traits visibility architecture boundaries official" +- "Serde tagged enums deny unknown fields boundary validation official" +- "thiserror source transparent structured error official" + +### Branch from "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" + +- "tracing instrument skip fields redaction EnvFilter JSON official" +- "secrecy SecretString expose_secret Debug redaction official" +- "rustls dangerous configuration certificate verification official" +- "Rust TLS certificate roots platform verifier rustls official" + +### Branch from "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" + +- "Clap derive value enum exit codes JSON output shell completion official" +- "Clap error handling try_parse_from CommandFactory official" +- "Ratatui terminal init restore panic hook test backend official" +- "Ratatui snapshot testing event loop cancellation official" + +### Branch from "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" + +- "proptest state machine strategy shrinking persistence official" +- "Loom model concurrency atomics Arc Mutex limitations official" +- "cargo-nextest retries slow timeout archive junit official" +- "Criterion benchmark statistical confidence regression official" +- "Tokio test start_paused timeout cancellation fake server soak evidence official" + +### Branch from "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +- "cargo-dist installers checksums GitHub releases provenance official" +- "cargo-cyclonedx SBOM Rust official upstream" +- "cargo-auditable binary dependency metadata official upstream" +- "cargo-deny advisories licenses bans sources official" +- "RustSec advisory database cargo-audit withdrawn unmaintained official" +- "Sigstore cosign sign blob attest SBOM keyless official" + +## Research order and rationale + +1. Establish language, Cargo, MSRV, and platform constraints because every later recommendation depends on the supported compiler and target contract. +2. Resolve runtime/service ownership and failure behavior across Tokio, Axum, and Tower. +3. Resolve SQLite/SQLx transaction, locking, and crash-durability semantics. +4. Collect type-boundary, serialization, error, observability, secret, and TLS sources. +5. Collect operator-surface sources for Clap and Ratatui. +6. Collect deterministic, property, model-concurrency, benchmark, and soak-test evidence. +7. Close with packaging, provenance, SBOM, signature, advisory, and release evidence while preserving dependency/release/security peer ownership. diff --git a/.claude/skills/rust-stinger/research/research-summary.md b/.claude/skills/rust-stinger/research/research-summary.md new file mode 100644 index 00000000..f8caa1bb --- /dev/null +++ b/.claude/skills/rust-stinger/research/research-summary.md @@ -0,0 +1,68 @@ +# Research Summary: rust-stinger + +- **Depth tier consumed:** deep, completed as a concise authoritative packet rather than an open-ended crawl +- **Time window:** 2026-01-24 through 2026-07-24 (6 months), with stable canonical reference pages used where the governing specification predates the window +- **Source notes:** 56 +- **Research/control artifacts:** 4 (`research-plan.md`, `index.md`, `evidence-synthesis.md`, `research-summary.md`) +- **Total Markdown files:** 60 +- **Primary-source posture:** 55 official/upstream sources and 1 upstream practitioner-maintained GitHub project note (`cargo-auditable`); no community forum/Reddit source was needed + +## Files by subfolder + +| Subfolder | Source files | +|---|---:| +| `async/` | 10 | +| `boundaries/` | 3 | +| `cli-tui/` | 5 | +| `observability/` | 2 | +| `persistence/` | 7 | +| `rust-cargo/` | 8 | +| `security/` | 3 | +| `supply-chain/` | 11 | +| `testing/` | 7 | +| **Total** | **56** | + +## Coverage against the Command Brief + +- Rust/Cargo workspace architecture, feature unification, MSRV, toolchain, platform tiers, Clippy, and unsafe policy: covered. +- Tokio/Axum/Tower task ownership, cancellation safety, bounded backpressure, readiness, graceful shutdown, streaming bodies, and service testing: covered. +- SQLite/SQLx transactions, `BEGIN IMMEDIATE`, busy behavior, WAL, checkpointing, durability, atomic commit/crash recovery, connection options, compile-checked queries, and migrations: covered. +- Typed boundaries/state machines, Serde strictness/tagging, structured errors, non-forgeable verification markers: covered. +- tracing/subscriber ownership, secret wrappers, rustls safe/dangerous configuration and typestate: covered. +- Clap CLI parsing/exit behavior and Ratatui lifecycle/test architecture: covered. +- proptest, Loom, deterministic Tokio time, nextest, Criterion, failure/concurrency/migration/fake-provider and eight-hour-soak evidence model: covered. +- cargo-dist, cargo-cyclonedx, cargo-auditable, cargo-deny, RustSec/cargo-audit, Cargo SBOM precursors/package verification, and Sigstore/Cosign: covered with peer-boundary caveats. + +## Five most influential sources + +1. [`async/2026-07-24-tokio-select-cancellation.md`](async/2026-07-24-tokio-select-cancellation.md) — establishes that cancellation safety is an operation-level property and identifies the central replay/data-loss review boundary. +2. [`async/2026-07-24-tower-service-readiness.md`](async/2026-07-24-tower-service-readiness.md) — makes backpressure a resource-reservation contract and exposes the readiness-to-call cancellation edge. +3. [`persistence/2026-07-24-sqlite-transactions.md`](persistence/2026-07-24-sqlite-transactions.md) plus [`persistence/2026-07-24-sqlx-custom-transactions.md`](persistence/2026-07-24-sqlx-custom-transactions.md) — together establish the one-writer rule and the SQLx 0.9 mechanism for tracked `BEGIN IMMEDIATE` transactions. +4. [`security/2026-07-24-rustls-verification-markers.md`](security/2026-07-24-rustls-verification-markers.md) — supplies upstream precedent for private proof tokens preventing skipped safety checks. +5. [`testing/2026-07-24-proptest-state-machines.md`](testing/2026-07-24-proptest-state-machines.md) — supplies the reference-model, invariant, shrinking, and regression-seed pattern for quota/breaker/promotion state. + +## Open questions that survived research + +- Final platform/installer matrix and minimum OS baselines. +- Declared MSRV after the real dependency graph and features exist. +- Required SQLite power-loss durability and busy/contended-write UX. +- Final durable state/event schema for replay prohibition and promotion. +- TUI inclusion in the first milestone. +- Signing/attestation identity and publication authorization. +- Numeric eight-hour-soak thresholds. + +## Sources Forge should re-fetch at build time + +- Rust release index and platform support (toolchain/target drift). +- Tokio current/LTS policy (1.53.1 and 1.51.x were current at retrieval). +- SQLx `Connection::begin_with` and migration/query docs against the selected SQLx version. +- rustls stable docs to avoid using 0.24 development APIs. +- cargo-dist configuration/changelog and GitHub attestation eligibility. +- RustSec advisory database immediately before any release recommendation. + +## Blocked or incomplete research + +- No subject area is blocked. +- Raw web-crawl JSON and ranked discovery records were not produced. Context7 plus direct official/upstream retrieval was used; the limitation is recorded in the plan and synthesis. +- No source establishes a universal off-the-shelf eight-hour Rust soak harness. The synthesis therefore records a composable evidence model and leaves numeric thresholds to the product/release owners. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md new file mode 100644 index 00000000..ae859eb9 --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/guide/continuous-integration.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: ci +stinger: rust-stinger +--- + +# Cargo continuous integration guidance + +## Summary +Cargo's CI guide explicitly recommends verifying `rust-version`, testing dependency freshness, and pinning the compiler when warnings are denied because new toolchains can add warnings. It illustrates `cargo hack check --rust-version --workspace --all-targets` and a full-feature Clippy job. + +## Key quotations / statistics +- "When publishing packages that specify `rust-version`, it is important to verify the correctness of that field." +- "CI can fail due to new toolchain versions because there are limited compatibility guarantees around warnings." + +## Version/date caveat +The guide names third-party tools as examples, not as Rust project guarantees. + +## Annotations for stinger-forge +- Grounds separate pinned-toolchain, MSRV, latest-dependency, and target/feature checks. +- Peer boundary: CI topology remains the release/DevOps specialist's decision. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md new file mode 100644 index 00000000..f521634a --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/features.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: features +stinger: rust-stinger +--- + +# Cargo features and feature unification + +## Summary +Cargo features are additive and can be unified across dependency paths. Resolver v2 and later avoid several unwanted unifications for target-specific, build/proc-macro, and inactive dev dependencies, but feature coupling still requires deliberate crate boundaries and CI combinations. Default features are part of the public dependency contract unless callers disable them consistently. + +## Key quotations / statistics +- "Features should be additive." +- Resolver v2 "avoids unifying features" across several dependency categories. + +## Version/date caveat +Stable Cargo documentation; individual dependency feature sets can change without a workspace architecture change. + +## Annotations for stinger-forge +- Supports feature hygiene, `cargo tree -e features`, and targeted feature-matrix checks. +- Relevant to keeping TUI/provider/TLS capabilities out of core crates by default. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md new file mode 100644 index 00000000..d1fcb298 --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/resolver.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: resolver +stinger: rust-stinger +--- + +# Cargo dependency resolver + +## Summary +Cargo resolver version 3 is the Rust 2024 default and changes incompatible-Rust-version handling from `allow` to `fallback`. Resolver choice is global to the top-level workspace and dependency manifests cannot override it; virtual workspaces must set it explicitly. This is a workspace architecture constraint, not a per-crate preference. + +## Key quotations / statistics +- "`3` (`edition = `2024` default, requires Rust 1.84+)" +- "The resolver is a global option that affects the entire workspace." + +## Version/date caveat +Stable Cargo docs as of retrieval. Resolver v3 sets selection behavior but does not prove every selected dependency actually honors its MSRV. + +## Annotations for stinger-forge +- Inform the workspace manifest checklist and feature/MSRV audit. +- Warn that a virtual workspace must explicitly declare `resolver = "3"`. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md new file mode 100644 index 00000000..a377739d --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/rust-version.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: msrv +stinger: rust-stinger +--- + +# Cargo `rust-version` + +## Summary +Cargo's `rust-version` field declares the minimum supported compiler and participates in diagnostics and dependency resolution. Workspace members can have different policies, but shared dependencies and feature unification mean the lowest supported member can constrain the whole workspace. The declared value needs CI proof rather than being treated as descriptive metadata. + +## Key quotations / statistics +- "The resolver may take Rust version into account when picking dependencies." +- "All functionality, including binaries and API, are available on the supported Rust versions under every feature." + +## Version/date caveat +Stable Cargo documentation retrieved against the Rust 1.97 release line; resolver behavior depends on workspace resolver selection. + +## Annotations for stinger-forge +- Grounds MSRV declaration and verification rules. +- Supports testing all public feature combinations claimed to work at MSRV. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md new file mode 100644 index 00000000..1155d39a --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/clippy/continuous_integration/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: linting +stinger: rust-stinger +--- + +# Clippy in continuous integration + +## Summary +Official Clippy guidance recommends treating Clippy warnings as CI failures and using the same toolchain as compilation for compatibility. Because new lints appear over time, a pinned toolchain or an explicit upgrade process prevents unrelated stable updates from unexpectedly breaking release branches. + +## Key quotations / statistics +- "It is recommended to run Clippy on CI with `-Dwarnings`." +- "use Clippy from the same toolchain, that you use for compiling your crate" + +## Version/date caveat +Lint inventories evolve with the compiler; a clean result is toolchain-specific. + +## Annotations for stinger-forge +- Supports the standard Rust verification gate and toolchain pinning. +- Avoid enabling all `restriction` lints indiscriminately; the Clippy index warns they may conflict. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md new file mode 100644 index 00000000..b1fb7d7a --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/rustc/platform-support.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: targets +stinger: rust-stinger +--- + +# Rust platform support + +## Summary +Rust classifies targets into three tiers with materially different build and test guarantees. Tier 1 targets build and pass tests in Rust CI; Tier 2 targets are guaranteed to build but may not be tested. A product target matrix therefore needs its own runtime/install/uninstall proof even when the compiler labels a target supported. + +## Key quotations / statistics +- "Tier 1 targets can be thought of as `guaranteed to work`." +- Tier 2 targets "can be thought of as `guaranteed to build`." + +## Version/date caveat +Target tiers and OS baselines can change between Rust releases; re-check during release planning. + +## Annotations for stinger-forge +- Use to separate compiler support from product support evidence. +- Supports explicit macOS/Linux/Windows target triples and host-tool requirements. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md new file mode 100644 index 00000000..46def630 --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md @@ -0,0 +1,26 @@ +--- +source_url: https://blog.rust-lang.org/releases/ +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: toolchain +stinger: rust-stinger +--- + +# Rust release announcements + +## Summary +The official release index records Rust 1.97.1 on 2026-07-16 and Rust 1.97.0 on 2026-07-09. It provides the current stable anchor for any 2026 toolchain discussion, but it does not itself establish the product's MSRV; that remains a deliberate compatibility decision verified independently. + +## Key quotations / statistics +- "July 16 | Announcing Rust 1.97.1" +- 2026 releases listed in the six-month window: 1.93.0 through 1.97.1. + +## Version/date caveat +Current stable at retrieval time; Rust releases on a regular cadence, so re-check immediately before freezing a toolchain. + +## Annotations for stinger-forge +- Use as the current-version anchor in toolchain/MSRV guidance. +- Distinguish "current stable" from the separately declared `package.rust-version` and CI-tested MSRV. + diff --git a/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md new file mode 100644 index 00000000..cf491309 --- /dev/null +++ b/.claude/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: unsafe +stinger: rust-stinger +--- + +# Unsafe Rust + +## Summary +The Rust Book defines the five operations requiring `unsafe`, stresses that unsafe code transfers proof obligations to the programmer, and recommends keeping unsafe blocks small behind safe abstractions. This supports a default `forbid(unsafe_code)` posture with narrowly reviewed exceptions. + +## Key quotations / statistics +- "Keep `unsafe` blocks small" +- "wrapping unsafe code in a safe function is a common abstraction" + +## Version/date caveat +The current Book uses the Rust 2024 edition. Low-level memory-model details must be checked against the Reference/Nomicon, not inferred from examples. + +## Annotations for stinger-forge +- Grounds unsafe inventory, documented invariants, and targeted tests. +- Note that the old Unsafe Code Guidelines reference describes itself as largely abandoned. + diff --git a/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md b/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md new file mode 100644 index 00000000..b7df5e59 --- /dev/null +++ b/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tls +stinger: rust-stinger +--- + +# rustls configuration typestate + +## Summary +rustls 0.23.42 uses builder typestates to require protocol/provider, peer verification, and certificate decisions in order. Normal builders select safe default protocol versions; custom verifiers sit behind a deliberately dangerous API. The builder demonstrates compile-time enforcement of required configuration steps. + +## Key quotations / statistics +- "use rustls' default cryptographic provider and safe defaults" +- Builder state "ensure[s] at compile time that each required configuration item is provided exactly once" + +## Version/date caveat +The stable docs reported rustls 0.23.42; rustls.dev also exposed 0.24.0-dev.0, so do not code to development APIs accidentally. + +## Annotations for stinger-forge +- Strong upstream example for typestate and TLS-safe defaults. +- Custom certificate verification requires explicit Security review. + diff --git a/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md b/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md new file mode 100644 index 00000000..b92aa6da --- /dev/null +++ b/.claude/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustls.dev/src/rustls/verify.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: typestate +stinger: rust-stinger +--- + +# rustls verification marker types + +## Summary +rustls uses non-constructible marker values to encode that certificate-chain and handshake-signature verification occurred before traffic state is reached. The source explicitly frames this as protection against omitted-check control flow. This is directly relevant as prior art for non-forgeable replay/promotion authorization tokens. + +## Key quotations / statistics +- "bind the fact some verification ... has taken place into protocol states" +- "compiler check that there are no `goto fail`-style elisions" + +## Version/date caveat +Source view from rustls.dev may track development rather than the pinned 0.23 release; use the pattern, not an internal type dependency. + +## Annotations for stinger-forge +- Key evidence for private constructors and capability tokens representing completed checks. +- Do not couple the router's state machine to rustls internal marker types. + diff --git a/.claude/skills/rust-stinger/research/security/2026-07-24-secrecy.md b/.claude/skills/rust-stinger/research/security/2026-07-24-secrecy.md new file mode 100644 index 00000000..c323990a --- /dev/null +++ b/.claude/skills/rust-stinger/research/security/2026-07-24-secrecy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/secrecy/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: secrets +stinger: rust-stinger +--- + +# secrecy secret wrappers + +## Summary +secrecy 0.10.3 wraps secret values so access requires an explicit exposure trait, reduces accidental Debug/logging/copying, and wipes supported owned values on drop. Optional Serde support permits deserialization but explicitly cannot prevent upstream deserializers from making copies. It is defense-in-depth, not a complete secret store. + +## Key quotations / statistics +- access is "only available through a special `ExposeSecret` trait" +- Serde support "doesn't guarantee ... additional copies" are not made. + +## Version/date caveat +MSRV is Rust 1.60; the project states future MSRV changes are outside SemVer guarantees but accompany a minor bump. + +## Annotations for stinger-forge +- Supports secret newtypes and narrow exposure sites. +- Secret acquisition/storage policy remains Security/platform-owned. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md new file mode 100644 index 00000000..7044e61a --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rustsec/rustsec/blob/main/cargo-audit/README.md +retrieved_on: 2026-07-24 +source_type: github-readme +authority: official +relevance: critical +topic: cargo-audit +stinger: rust-stinger +--- + +# RustSec cargo-audit + +## Summary +cargo-audit checks Cargo.lock against RustSec and can inspect binaries built with cargo-auditable. Its experimental `fix` command modifies manifests, while ignore entries require application-specific justification. The README states binary scanning is incomplete for ordinary optimized binaries but accurate when auditable metadata is embedded. + +## Key quotations / statistics +- "Audit your dependencies for crates with security vulnerabilities" +- Without auditable metadata it may miss "roughly half of the Rust dependencies" + +## Version/date caveat +README currently requires Rust 1.74 or later; pin cargo-audit independently from the product MSRV. + +## Annotations for stinger-forge +- Supports lockfile and shipped-binary audit evidence. +- Never run automatic fix as part of an evidence-only release gate without review. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md new file mode 100644 index 00000000..675c4a35 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rust-secure-code/cargo-auditable +retrieved_on: 2026-07-24 +source_type: github-readme +authority: practitioner +relevance: high +topic: auditability +stinger: rust-stinger +--- + +# cargo-auditable + +## Summary +cargo-auditable embeds Cargo dependency version information in production binaries so deployed artifacts can be scanned later. It integrates with cargo-dist and experimental Cargo SBOM precursor output. The project recommends recording artifact hash, Cargo.lock, compiler/LLVM versions, and build date alongside binaries because embedded dependency metadata alone is not complete provenance. + +## Key quotations / statistics +- "Make production Rust binaries auditable" +- record "the hash of every executable" with build metadata. + +## Version/date caveat +The upstream README mentions nightly `-Z sbom`; nightly Cargo features are not a stable release foundation without explicit approval. + +## Annotations for stinger-forge +- Supports artifact-to-lockfile traceability and post-build `cargo audit bin` checks. +- Treat it as complementary to external SBOMs and attestations. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md new file mode 100644 index 00000000..55fe7b91 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/cargo-cyclonedx/0.5.9/source/CHANGELOG.md +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: sbom +stinger: rust-stinger +--- + +# cargo-cyclonedx 0.5.9 changelog + +## Summary +cargo-cyclonedx 0.5.9, released 2026-03-19, added `SOURCE_DATE_EPOCH` support for reproducible SBOM timestamps and honors `CARGO_BUILD_TARGET` for target identity. It also fixed sparse-registry and package-URL correctness. SBOM generation still requires validation against the shipped artifact and selected features/target. + +## Key quotations / statistics +- "Support for the `SOURCE_DATE_EPOCH` environment variable" +- "`CARGO_BUILD_TARGET` ... determine[s] the target platform" + +## Version/date caveat +Version 0.5.9 is the current release reported at retrieval; coverage/format support should be checked before freezing. + +## Annotations for stinger-forge +- Strong 2026 source for reproducible target-specific CycloneDX generation. +- Final SBOM completeness/policy judgment belongs to dependency/release peers. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md new file mode 100644 index 00000000..fc653b53 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: policy +stinger: rust-stinger +--- + +# cargo-deny checks + +## Summary +cargo-deny evaluates licenses, duplicate/banned crates, advisories/yanks, and dependency sources from the resolved crate graph. Running the umbrella check uses defaults for sections not configured, so a repository needs an explicit reviewed policy rather than assuming tool defaults match its legal/security constraints. + +## Key quotations / statistics +- Checks include "licenses", "bans", "advisories", and "sources". +- Advisories cover vulnerabilities, unmaintained crates, and yanked versions. + +## Version/date caveat +Policy/schema changes across cargo-deny versions; pin both tool and configuration version. + +## Annotations for stinger-forge +- Supports Rust-side evidence generation for dependency peer review. +- The Bee may run/report it but must not own final license/advisory exceptions. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md new file mode 100644 index 00000000..7472fa31 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/licenses/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: licenses +stinger: rust-stinger +--- + +# cargo-deny license check limitations + +## Summary +cargo-deny evaluates SPDX expressions and license files but explicitly cannot exhaustively prove a crate's legal licensing. It trusts manifest/package evidence and documents absence, mismatch, and unconventional-placement gaps. Clarifications are hash-bound evidence, not permanent blanket waivers. + +## Key quotations / statistics +- "does not exhaustively search the entirety of the source code" +- It makes a "good-faith assumption" that crates define licensing correctly. + +## Version/date caveat +License-list versions and cargo-deny detection behavior evolve; legal review cannot be replaced by a passing scan. + +## Annotations for stinger-forge +- Prevent overclaiming `cargo deny` as legal clearance. +- Route exceptions and notices to dependency/legal/release peers with exact evidence. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md new file mode 100644 index 00000000..3ff88414 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/supplychain-security/attestations/github.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: provenance +stinger: rust-stinger +--- + +# cargo-dist GitHub artifact attestations + +## Summary +dist can enable GitHub artifact attestations, creating verifiable provenance linked to GitHub Actions and Sigstore. The feature is disabled by default and has repository/plan limitations. Verification uses `gh attestation verify`, so evidence must include both generation and consumer verification transcripts. + +## Key quotations / statistics +- "Artifact Attestations is disabled by default" +- Verification is supported via "`gh attestation verify`" + +## Version/date caveat +The page labels GitHub Artifact Attestations public beta and records eligibility constraints that may change. + +## Annotations for stinger-forge +- Supports provenance as an explicit opt-in release gate, not an assumed dist feature. +- Signing identity/workflow permissions remain release/security peer concerns. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md new file mode 100644 index 00000000..b239d4fa --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/reference/config.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: packaging +stinger: rust-stinger +--- + +# cargo-dist artifact and installer configuration + +## Summary +cargo-dist configures target builds, archives, checksums, source tarballs, extra artifacts, and shell/PowerShell/npm/Homebrew/MSI installers. It can integrate cargo-auditable and cargo-cyclonedx. Checksums are unsigned integrity values; the docs explicitly describe stronger signed checksums as future work. + +## Key quotations / statistics +- Default checksum is "sha256". +- "Future work is planned to support more robust signed checksums." + +## Version/date caveat +Current docs include settings introduced through dist 0.31-era behavior; pin the generator because generated workflows/installers change. + +## Annotations for stinger-forge +- Grounds release manifest, artifact naming, installer matrix, and checksum evidence. +- Release topology/publication/signing authorization remains with the release peer. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md new file mode 100644 index 00000000..91f1b2d0 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/commands/cargo-package.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: package +stinger: rust-stinger +--- + +# Cargo package verification + +## Summary +`cargo package` builds a distributable crate archive, lists controlled contents, injects best-effort VCS metadata, and rebuilds the extracted package to verify a clean package. The VCS metadata does not prove source provenance, and `--no-verify`/`--allow-dirty` weaken evidence. + +## Key quotations / statistics +- It rebuilds "from scratch" from the package. +- "the provenance of the package is not verified" + +## Version/date caveat +Stable Cargo 1.97-era docs; binary release archives produced by dist have separate contents and verification. + +## Annotations for stinger-forge +- Supports package-content and clean-build checks for publishable crates. +- Do not confuse crate packaging proof with signed binary artifact provenance. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md new file mode 100644 index 00000000..e9bcda24 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/unstable.html#sbom +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: cargo-sbom +stinger: rust-stinger +--- + +# Cargo unstable SBOM precursors + +## Summary +Nightly Cargo's `-Z sbom` emits per-artifact JSON precursor files containing dependencies, target, features, and compiler data. These are inputs for SBOM tools, not complete standardized SBOMs. Because the feature is unstable and requires nightly, a stable release pipeline should treat it as supplemental unless explicitly approved. + +## Key quotations / statistics +- "generate so-called SBOM pre-cursor files" +- Files contain "dependencies, target, features and the used rustc compiler" + +## Version/date caveat +Unstable Cargo feature tracked by issue/RFC; schema and availability may change without stable guarantees. + +## Annotations for stinger-forge +- Record as optional deeper artifact evidence. +- Prefer stable cargo-cyclonedx/cargo-auditable paths for baseline release guidance. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md new file mode 100644 index 00000000..5053b24a --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustsec.org/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: advisories +stinger: rust-stinger +--- + +# RustSec Advisory Database + +## Summary +RustSec is the canonical community-maintained advisory database for crates.io packages and supports Cargo.lock auditing through cargo-audit and automation. Findings are time-dependent because the database changes after a build; release evidence needs a reviewed-on timestamp and repeatable lockfile input. + +## Key quotations / statistics +- "repository of security advisories filed against Rust crates" +- Maintained by the "Rust Secure Code Working Group" + +## Version/date caveat +Advisory results are a point-in-time snapshot; re-run at release and in ongoing maintenance. + +## Annotations for stinger-forge +- Require recorded database/update time and lockfile hash with audit evidence. +- Security/dependency peers own disposition, ignore expiry, and remediation acceptance. + diff --git a/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md new file mode 100644 index 00000000..dc01d8e6 --- /dev/null +++ b/.claude/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.sigstore.dev/cosign/signing/signing_with_blobs/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: signing +stinger: rust-stinger +--- + +# Cosign blob signing + +## Summary +Cosign signs ordinary files with keyless OIDC identities, local/KMS/hardware-backed keys, and emits a recommended bundle containing signature, certificate, and transparency-log proof. Noninteractive signing can create external effects and identity records, so it must remain an explicitly authorized release step. + +## Key quotations / statistics +- "using a bundle is the recommended way of signing a blob" +- The bundle includes "proof of transparency log inclusion" + +## Version/date caveat +Sigstore public infrastructure, identity claims, and command flags can change; capture the CLI version and verification policy. + +## Annotations for stinger-forge +- Supports signing/verification transcript requirements, not automatic invocation. +- Signing identity and publication remain peer/user-authorized boundaries. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md new file mode 100644 index 00000000..da0b82ba --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md @@ -0,0 +1,26 @@ +--- +source_url: https://bheisler.github.io/criterion.rs/book/analysis.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: benchmark +stinger: rust-stinger +--- + +# Criterion analysis process + +## Summary +Criterion performs warmup, measurement, statistical analysis, and comparison to saved baselines. It retains outliers, uses regression and bootstrap confidence intervals, and applies configurable significance/noise thresholds. Results still require a stable environment; statistical sophistication does not eliminate host noise. + +## Key quotations / statistics +- "Each benchmark ... goes through four phases" +- "outlier samples are not dropped" + +## Version/date caveat +Criterion docs reported crate 0.8.2 elsewhere in the corpus. The project warns virtualized CI can be too noisy for reliable wall-time regressions. + +## Annotations for stinger-forge +- Use for controlled local/release-host microbenchmarks and saved evidence. +- Eight-hour soak evidence is a distinct workload with invariants/resource telemetry, not a Criterion benchmark. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-loom.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-loom.md new file mode 100644 index 00000000..2745add5 --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-loom.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/loom/latest/loom/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: loom +stinger: rust-stinger +--- + +# Loom concurrency model checking + +## Summary +Loom 0.7.2 deterministically explores valid thread interleavings under a modeled memory model. Code under test must use Loom replacement synchronization types; unmodeled operations are invisible. State spaces grow exponentially, so Loom is best applied to small concurrency primitives with controlled preemption bounds and separate release-mode jobs. + +## Key quotations / statistics +- "runs tests many times, permuting the possible concurrent executions" +- "All sources of non-determism must be via loom types" + +## Version/date caveat +Loom documents limitations for relaxed ordering, hidden operations, and combinatorial explosion; passing Loom is not universal concurrency proof. + +## Annotations for stinger-forge +- Use selectively for small reservation/permit/task-state primitives. +- Do not wrap ordinary database/business logic in Loom merely to claim model checking. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md new file mode 100644 index 00000000..a5d135bd --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md @@ -0,0 +1,26 @@ +--- +source_url: https://nexte.st/docs/features/retries/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: flakiness +stinger: rust-stinger +--- + +# Nextest retries and flaky results + +## Summary +Nextest labels tests that pass only after retry as flaky and can make flaky outcomes fail the profile. JUnit output distinguishes flaky and rerun failures. This supports visibility while preserving a strict default for correctness/concurrency tests. + +## Key quotations / statistics +- "If a test succeeds during a retry, the test is marked flaky." +- "Flaky test detection is integrated with nextest's JUnit support." + +## Version/date caveat +Behavior described includes versioned JUnit changes; confirm the pinned nextest release's config schema. + +## Annotations for stinger-forge +- Require `flaky-result = "fail"` for release evidence unless a peer-approved quarantine exists. +- Never use retries to mask model, migration, or cancellation races. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest.md new file mode 100644 index 00000000..394ee869 --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-nextest.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.nexte.st/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: nextest +stinger: rust-stinger +--- + +# cargo-nextest capabilities + +## Summary +cargo-nextest supplies parallel test execution, per-test settings, timeouts, retries/flaky classification, archives/partitions, record/replay, and JUnit output across major platforms. It does not run doctests, which remain a separate `cargo test --doc` step. + +## Key quotations / statistics +- "Automatically retry some tests, mark them as heavy, run them serially" +- "Doctests are currently not supported" + +## Version/date caveat +Feature availability can depend on nextest version and execution platform; pin the runner used for release evidence. + +## Annotations for stinger-forge +- Grounds profiles for unit/integration/slow/soak classes and explicit doctest coverage. +- Retries must expose flakiness, not convert a nondeterministic gate into a silent pass. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md new file mode 100644 index 00000000..6f58e586 --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: properties +stinger: rust-stinger +--- + +# Proptest guide + +## Summary +The upstream guide covers strategies, shrinking, failure persistence, configuration, and state-machine testing. Property tests are most useful for invariant-rich inputs and transition sequences; they supplement rather than replace example-based contract tests whose exact output is part of a public API. + +## Key quotations / statistics +- Guide sections include "Shrinking Basics" and "Failure Persistence". +- The guide includes dedicated "State Machine testing" material. + +## Version/date caveat +The guide reflects upstream main documentation; exact APIs must be checked against the pinned crate release. + +## Annotations for stinger-forge +- Supports corpus persistence and reproducible seeds as evidence artifacts. +- Define invariants and input strategies in domain/test-support crates, not production adapters. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md new file mode 100644 index 00000000..31b60956 --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/state-machine.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: proptest +stinger: rust-stinger +--- + +# Proptest state-machine testing + +## Summary +Proptest state-machine testing generates sequences of valid transitions from a reference model, applies them to the system under test, checks postconditions/invariants, and shrinks failures to a minimal reproducer. It persists regression seeds. Current upstream support is sequential; concurrency behavior needs another technique such as Loom or explicit multi-client integration tests. + +## Key quotations / statistics +- "checking properties of a system under test ... against an abstract reference state machine" +- "only sequential strategy is supported" + +## Version/date caveat +State-machine support lives in the separate `proptest-state-machine` crate and may not version-lock with all proptest releases. + +## Annotations for stinger-forge +- Primary evidence for quota, reservation, reconciliation, breaker, pin, and promotion model tests. +- Pair with deterministic persistence fixtures and independent concurrency evidence. + diff --git a/.claude/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md b/.claude/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md new file mode 100644 index 00000000..67495488 --- /dev/null +++ b/.claude/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/testing +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: faketime +stinger: rust-stinger +--- + +# Tokio deterministic time testing + +## Summary +Tokio test utilities pause the runtime clock and advance timer-driven futures when no other work can progress. `#[tokio::test(start_paused = true)]` makes backoff, timeout, breaker, pin, and promotion timing tests fast and deterministic, provided production time access is routed through Tokio time or an injected clock. + +## Key quotations / statistics +- "Pausing time has the effect that any time-related future may become ready early." +- `start_paused` requires the `test-util` feature. + +## Version/date caveat +Only Tokio's clock is paused; `std::time` and external systems do not automatically follow it. + +## Annotations for stinger-forge +- Critical source for fake-clock tests and avoiding wall-clock sleeps. +- Explicitly yield/advance and assert temporal ordering, not elapsed host time. + diff --git a/.claude/skills/rust-stinger/templates/acceptance-slice-checklist.md b/.claude/skills/rust-stinger/templates/acceptance-slice-checklist.md new file mode 100644 index 00000000..456968f0 --- /dev/null +++ b/.claude/skills/rust-stinger/templates/acceptance-slice-checklist.md @@ -0,0 +1,16 @@ +# Rust acceptance slice checklist: {{slice_name}} + +- [ ] Read repository instructions, PRD/ADR/ledger, criteria, gates, and current Security/Quality evidence. +- [ ] Confirm repository/worktree and exact owned paths. +- [ ] Preserve unrelated and concurrent edits. +- [ ] Map each changed path and test to {{AC_IDS}}. +- [ ] Inventory crate/features/targets/tasks/channels/migrations/errors/config/logs/unsafe. +- [ ] Record version-sensitive decisions and revalidation points. +- [ ] Add a focused failing test before implementation. +- [ ] Prove cancellation, backpressure, retry/replay, shutdown, and cleanup where affected. +- [ ] Prove transactions, migrations, idempotency, concurrency, and crash recovery where affected. +- [ ] Use fake providers/fixtures unless a live gate is explicitly authorized. +- [ ] Run format, compile/check, Clippy, tests, docs, and affected specialized gates. +- [ ] Generate release evidence locally without signing/publishing unless authorized. +- [ ] Route Security, rerun affected checks after fixes, then route Quality. +- [ ] Report exact commands, results, external effects, limitations, blockers, and rollback/recovery. diff --git a/.claude/skills/rust-stinger/templates/implementation-handoff.md b/.claude/skills/rust-stinger/templates/implementation-handoff.md new file mode 100644 index 00000000..c4b6b5cc --- /dev/null +++ b/.claude/skills/rust-stinger/templates/implementation-handoff.md @@ -0,0 +1,53 @@ +# Rust implementation handoff: {{slice_name}} + +## Outcome + +{{what_is_now_true}} + +## Authority and scope + +- Repository/worktree: `{{absolute_path}}` +- Source authority: `{{prd_or_adr_path}}` +- Owned paths: {{owned_paths}} +- Gates consumed: {{gate_ids_or_none}} +- Concurrent/user edits preserved: {{evidence}} + +## Acceptance evidence + +- {{AC_ID}}: {{command_test_or_artifact}} — {{PASS_FAIL_BLOCKED}} + +## Changed paths + +- `{{path}}` — {{reason}} + +## Verification + +- `{{exact_command}}` — {{PASS_FAIL_BLOCKED}} + +## Safety and operations + +- External effects used: {{none_or_explicit_authorization_and_effect}} +- Async/shutdown/replay: {{evidence}} +- Migration/rollback/recovery: {{evidence}} +- Secrets/prompts/logging/diagnostics: {{evidence}} +- Unsafe inventory: {{none_or_review_reference}} + +## Revalidation points + +- Toolchain/MSRV/targets: {{current_evidence_or_owner_decision}} +- Dependency/runtime APIs: {{current_evidence_or_owner_decision}} +- Durability/contention: {{current_evidence_or_owner_decision}} +- Release/signing/soak: {{current_evidence_or_owner_decision}} + +## Peer handoffs and remaining gates + +- Security: {{ready_or_blocker}} +- Affected-check rerun after Security: {{commands_or_pending}} +- Quality: {{ready_only_after_security_and_reruns}} +- Protocol/platform/database/dependency/release: {{owner_and_open_item}} + +## Blocker, if any + +- Gate/owner: {{gate_and_owner}} +- Affected criteria: {{AC_IDS}} +- First authorized next action: {{next_action}} diff --git a/.claude/skills/rust-stinger/templates/release-evidence-manifest.yaml b/.claude/skills/rust-stinger/templates/release-evidence-manifest.yaml new file mode 100644 index 00000000..9b030b14 --- /dev/null +++ b/.claude/skills/rust-stinger/templates/release-evidence-manifest.yaml @@ -0,0 +1,63 @@ +schema_version: "{{schema_version}}" +release_candidate: "{{version_or_commit}}" +generated_at: "{{ISO_8601_UTC}}" +external_effects_authorized: {{true_or_false}} +authorization_reference: "{{reference_or_NONE}}" + +source: + repository: "{{repository}}" + commit: "{{commit_sha}}" + dirty: {{true_or_false}} + lockfile_sha256: "{{sha256}}" + toolchain: "{{rustc_and_cargo_versions}}" + msrv_status: "{{PROVEN_UNDECIDED_NOT_CLAIMED}}" + +artifacts: + - target: "{{rust_target_triple}}" + path: "{{artifact_path}}" + sha256: "{{sha256}}" + build_command: "{{exact_command}}" + build_result: "{{PASS_FAIL_BLOCKED}}" + runtime_smoke: "{{evidence}}" + install_transcript: "{{path_or_NOT_RUN}}" + uninstall_transcript: "{{path_or_NOT_RUN}}" + +verification: + formatting: "{{command_and_result}}" + clippy: "{{command_and_result}}" + unit_contract_integration: "{{command_and_result}}" + doctests: "{{command_and_result}}" + property_model_concurrency: "{{command_and_result}}" + migrations_crash_recovery: "{{command_and_result}}" + benchmarks: "{{command_and_result}}" + soak: "{{command_result_thresholds_or_BLOCKED}}" + +supply_chain: + sbom: + path: "{{path_or_NOT_GENERATED}}" + tool_version: "{{version}}" + sha256: "{{sha256}}" + advisories: + database_updated_at: "{{ISO_8601_UTC}}" + command: "{{exact_command}}" + result: "{{PASS_FAIL_REVIEW_REQUIRED}}" + dependency_license_source_scan: "{{path_command_and_result}}" + embedded_audit_metadata: "{{evidence_or_NOT_ENABLED}}" + +provenance: + signing_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + attestation_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + signer_identity: "{{identity_or_NONE}}" + verification_transcript: "{{path_or_NONE}}" + +peer_handoffs: + security: "{{owner_status_report}}" + dependency_license: "{{owner_status_report}}" + release_devops: "{{owner_status_report}}" + quality: "{{owner_status_report_after_security}}" + +open_gates: + - id: "{{gate_id}}" + owner: "{{owner}}" + blocker: "{{missing_decision_or_evidence}}" + next_action: "{{first_authorized_action}}" diff --git a/.claude/skills/rust-stinger/templates/rust-decision-log.md b/.claude/skills/rust-stinger/templates/rust-decision-log.md new file mode 100644 index 00000000..d53a705d --- /dev/null +++ b/.claude/skills/rust-stinger/templates/rust-decision-log.md @@ -0,0 +1,25 @@ +# Rust decision log + +| Decision | Chosen value | Evidence date | Source or test | Revalidate when | Owner | +|---|---|---|---|---|---| +| Toolchain pin | {{value}} | {{YYYY-MM-DD}} | {{source_or_command}} | Before upgrade/release | {{owner}} | +| MSRV | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{feature_matrix_command}} | Dependency/feature change | {{owner}} | +| Product targets/baselines | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{runtime_install_evidence}} | Release matrix change | {{owner}} | +| Tokio line | {{value}} | {{YYYY-MM-DD}} | {{support_policy_and_tests}} | Runtime upgrade | {{owner}} | +| SQLx transaction API | {{value}} | {{YYYY-MM-DD}} | {{selected_version_docs_and_tests}} | SQLx upgrade | {{owner}} | +| SQLite PRAGMAs | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{durability_decision_and_crash_tests}} | Persistence policy change | {{owner}} | +| rustls configuration | {{value}} | {{YYYY-MM-DD}} | {{stable_docs_and_security_review}} | rustls/root-policy change | {{owner}} | +| Package generator | {{value}} | {{YYYY-MM-DD}} | {{version_and_diff_review}} | Generator upgrade | {{owner}} | +| Signing/attestation | {{value_or_UNAUTHORIZED}} | {{YYYY-MM-DD}} | {{approval_and_verification_policy}} | Every release | {{owner}} | +| Soak thresholds | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{performance_SLO_source}} | Workload/platform change | {{owner}} | + +## Rationale and alternatives + +### {{decision_name}} + +- Context: {{context}} +- Decision: {{decision}} +- Evidence: {{evidence}} +- Alternatives: {{alternatives}} +- Consequences: {{consequences}} +- Peer approval/gate: {{approval_or_open_gate}} diff --git a/.codex/agents/rust-worker-bee.toml b/.codex/agents/rust-worker-bee.toml new file mode 100644 index 00000000..2419606e --- /dev/null +++ b/.codex/agents/rust-worker-bee.toml @@ -0,0 +1,3 @@ +name = "rust-worker-bee" +description = "Rust implementation and code-review specialist for production `*.rs`, `Cargo.toml`, Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence. Use proactively when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or a PR touches Rust/Cargo surfaces. Do NOT invoke to invent HTTP/MCP semantics, approve Security or dependency/license policy, design CI topology, author final Quality, or perform unauthorized live/provider/release effects." +developer_instructions = "# Rust Worker Bee\n\nBefore doing anything else, read your paired Stinger at `.agents/skills/rust-stinger/SKILL.md` in full and follow it as your operating manual. Stay within the exact scope and file ownership assigned by the parent orchestrator. Preserve unrelated and concurrent edits. Return concise acceptance-linked implementation and verification evidence to the parent thread.\n\n## Identity & responsibility\n\nrust-worker-bee is the roster's implementation and code-review owner for production Rust systems. It owns bounded Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against already approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, dispose of dependency/license findings, design CI topology, issue final Quality acceptance, or authorize live credentials, paid traffic, signing, publication, or release effects.\n\n## Paired Stinger\n\n[`.agents/skills/rust-stinger/`](.agents/skills/rust-stinger/)\n\nRead `.agents/skills/rust-stinger/SKILL.md` in full first. It is the master index. Then read the guides and reusable artifacts named by the selected procedure steps.\n\n## Activation contract\n\nActivate proactively when the assigned implementation or review touches:\n\n- Rust source (*.rs), Cargo.toml, Cargo.lock, Cargo workspaces, rust-toolchain*, build.rs, crate migrations, features, targets, or Rust release configuration.\n- Tokio task ownership, cancellation, backpressure, streams, timeouts, retries, shutdown, Axum routes/bodies, or Tower services/middleware.\n- SQLx/SQLite transactions, migrations, idempotency, concurrency, durability mechanics, crash recovery, or persisted state machines.\n- Clap commands, deterministic exit/output contracts, an explicitly scoped Ratatui client, Rust unit/property/contract/integration/concurrency/failure/soak tests, or local Rust packaging evidence.\n- Requests such as \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio service\", \"audit this SQLx transaction\", or a PRD slice whose accepted architecture requires Rust.\n\nDo not act as final authority for HTTP/MCP/provider semantics, Security acceptance, schema architecture, product/provider policy, dependency/license/advisory disposition, CI/CD topology, release/signing/publication, or implementation-to-PRD Quality. Implement an approved contract, produce evidence, and hand those decisions to their owners.\n\n## Procedure\n\n1. Reconstruct authority and ownership. Read repository instructions, the exact PRD/sub-PRD, ADRs, execution ledger rows, acceptance criteria, gates, current Security/Quality evidence, worktree state, and assigned paths. Build an acceptance-to-path-to-proof map with `guides/00-authority-and-principles.md`. Do not start blocked or deferred work.\n2. Inspect before editing. Use `guides/01-inspect-workspace.md` to inventory the Cargo graph, toolchain/MSRV claims, features, targets, crate boundaries, unsafe/panic paths, tasks/channels, configuration, migrations, SQL, logs, secrets, tests, benchmarks, and release files. Record missing tools as blockers instead of installing them implicitly.\n3. Choose the smallest coherent design with `guides/02-design-workspace-and-types.md`: one owner per invariant, edge types at edges, validated domain types, structured redacted errors, private proof tokens, additive/default-off optional features, and no provider acquisition of harness agency. Escalate an unapproved protocol or architecture decision.\n4. Implement a bounded test-first slice with `guides/03-implement-bounded-slices.md` and `templates/acceptance-slice-checklist.md`. Add the focused failing proof, patch only owned paths, run the narrow gate, and map every change/result to an acceptance criterion.\n5. Where affected, prove task owners, bounded admission, cancellation safety, channel/Tower reservations, ordering, visibility/replay, timeout, retry, disconnect cleanup, and joined shutdown using `guides/04-prove-async-streams.md`. Never transparently replay after visible output or a harness-visible tool call unless the approved contract explicitly permits it.\n6. Where affected, prove SQLx/SQLite transaction intent, conditional guards, idempotency, contention, PRAGMAs, migrations, crash recovery, and state transitions with `guides/05-prove-persistence-and-state.md`. Do not choose durability, busy behavior, schema policy, or monetary semantics while their owning decision is open.\n7. Implement adapters behind approved contracts using `guides/06-implement-adapters.md`. Normalize edge types, preserve correlation/visibility/reservation facts, use approved secret references, default sensitive tracing to `skip_all`, keep egress/TLS controls intact, and use fake servers/fixtures unless live use has explicit authorization.\n8. Build operator clients with `guides/07-build-cli-and-tui.md`: typed Clap parsing, stable machine output, domain exit codes, confirmation policy, double-redacted diagnostics, and a feature-gated Ratatui client only when explicitly assigned. The client never becomes a second authority.\n9. Verify and generate local evidence with `guides/08-verify-and-package-evidence.md`. Run repository-specific format, check, Clippy, feature/target builds, tests, doctests, migration/concurrency/crash/provider proofs, benchmarks, and authorized soak/package steps. Populate `templates/release-evidence-manifest.yaml` when needed, but do not sign, publish, install globally, or claim platform/MSRV support from incomplete evidence.\n10. Close the loop using `guides/09-close-the-loop.md` and `templates/implementation-handoff.md`. Report changed paths, exact commands/results, acceptance evidence, external effects, rollback/recovery, redaction, unsafe inventory, revalidation points, blockers, and peer handoffs. Preserve implementation checks -> Security -> affected-check reruns -> Quality.\n\n## Critical directives\n\n- Honor the exact authority boundary. Read and obey the named PRD, ADR, ledger, repository instructions, and gate state. Never start blocked/deferred work or promote a preference into an approval; implementation cannot consume authority it was never given.\n- Keep agency and external effects fail-closed. Rust code may route inference but may not take over harness tools, approvals, repository access, memory, or user interaction. Never use live credentials, paid/subscription traffic, public publishing, Git initialization, signing identities, global installation, or auto-update execution without explicit authorization because those effects escape the bounded slice.\n- Make concurrency and durability provable. Use bounded queues, explicit task ownership, reviewed cancellation/replay boundaries, atomic transactions, idempotency, and focused crash/concurrency evidence. Hidden retry, partial monetary state, or hand-waved shutdown creates data loss or double effects.\n- Protect secrets and content by construction. Keep credentials in approved secret references. Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Preserve egress, redirect, DNS, and SSRF controls; redaction after leakage is not containment.\n- Do not hide unsafe Rust or runtime failure. Default to no unsafe. Any exception requires minimal scope, a written invariant, targeted tests, and independent review. Avoid unchecked panics at daemon, adapter, state, and migration boundaries so failures remain structured, redacted, and recoverable.\n- Respect peer ownership. Hand protocol meaning to the HTTP/MCP specialist, schema policy to the database specialist, security acceptance to `security-worker-bee`, dependency/license/advisory disposition to `dependency-audit-worker-bee`, CI/release topology to the DevOps/release specialist, and final acceptance to `quality-worker-bee`. Evidence generation is not peer approval.\n- Verify before declaring completion. Run the current full relevant Rust gate and preserve implementation checks -> Security -> affected reruns -> Quality. Partial, stale, retry-only, unsigned, unreviewed, or single-platform results are not shipped or release-ready evidence.\n\n## Escalation\n\nStop at the smallest safe, compilable/testable checkpoint when a missing decision affects safety, public compatibility, money, credentials, destructive behavior, platform support, signing, publication, or another external effect. Return the exact blocker, owning peer/gate, affected acceptance criteria, completed files/tests, command results, and first authorized next action. Do not silently guess or label the checkpoint shipped.\n\n- HTTP/REST or MCP semantics and compatibility -> `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`.\n- Provider/model/product policy -> `ai-tools-platform-worker-bee` or the named product owner.\n- Schema/data architecture -> `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof.\n- Threat acceptance, TLS/egress/redaction security, or credentials -> `security-worker-bee`.\n- Dependency, advisory, license, source, and SBOM disposition -> `dependency-audit-worker-bee`.\n- CI/CD topology, signing, installers, publication, or release operations -> the appropriate DevOps/release peer plus explicit user authorization.\n- Final implementation-to-PRD audit -> `quality-worker-bee`, only after Security and affected reruns.\n\n## References to skill files\n\nUtilize the Read tool to understand your skills listed at `.agents/skills/rust-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first. The research summary, synthesis, and index are the scaling pointers to the complete dated source-note corpus.\n\nMaster indexes:\n- `SKILL.md` — activation, inputs, procedure, directives, outputs, refresh points, and open decisions.\n- `README.md` — layout, traceability, and maintenance posture.\n\nPrinciples and procedures:\n- `guides/00-authority-and-principles.md` — authority reconstruction and fail-closed rules.\n- `guides/01-inspect-workspace.md` — Cargo, async, persistence, security, and toolchain inventory.\n- `guides/02-design-workspace-and-types.md` — crates, features, validated boundaries, typestate, errors, and architecture tests.\n- `guides/03-implement-bounded-slices.md` — test-first acceptance slicing and patch discipline.\n- `guides/04-prove-async-streams.md` — ownership, cancellation, backpressure, replay, disconnect, and shutdown.\n- `guides/05-prove-persistence-and-state.md` — transactions, durability, migrations, crash recovery, and state machines.\n- `guides/06-implement-adapters.md` — edge isolation, fake-first contracts, tracing, secrets, TLS, and prohibited effects.\n- `guides/07-build-cli-and-tui.md` — Clap contracts, diagnostics, confirmation, Ratatui lifecycle, and TUI gate.\n- `guides/08-verify-and-package-evidence.md` — verification ladder, package manifest, and closed release effects.\n- `guides/09-close-the-loop.md` — handoff, evidence honesty, blocker record, and Security-before-Quality.\n\nWorked examples:\n- `examples/01-happy-path-bounded-service-slice.md` — bounded fake-provider service, ordering, capacity, and shutdown.\n- `examples/02-edge-visible-output-cancellation.md` — private replay proof and cancellation after visibility.\n- `examples/03-edge-concurrent-budget-reservation.md` — transactional reservation, idempotency, contention, and recovery.\n- `examples/04-release-evidence-with-closed-gates.md` — local package evidence with signing/publication blocked.\n\nOutput templates:\n- `templates/acceptance-slice-checklist.md` — bounded implementation checklist.\n- `templates/implementation-handoff.md` — canonical completion/blocker handoff.\n- `templates/release-evidence-manifest.yaml` — artifact, verification, supply-chain, provenance, and gate evidence.\n- `templates/rust-decision-log.md` — drift-sensitive implementation decisions.\n\nReport artifacts:\n- `reports/README.md` — archive and no-overwrite rules.\n- `reports/implementation-handoff-report-template.md` — global archive wrapper.\n\nResearch trail:\n- `research/research-plan.md` — deep-research questions, order, source posture, and provenance caveat.\n- `research/research-summary.md` — coverage, influential sources, open questions, and refresh points.\n- `research/evidence-synthesis.md` — patterns, limitations, peer boundaries, and evidence model.\n- `research/index.md` — complete inventory of every dated primary-source note.\n\n---\n\n*Created by the Legendary Bee Factory.*\n" diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..bfdae086 100644 --- a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,20 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`rust-worker-bee` / `rust-stinger` was ported in from a prior fork and registered here: Rust implementation and code review for Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, tests, and local packaging evidence. ## Path integrity @@ -41,7 +45,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md index c4fb309f..bc45542d 100644 --- a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,6 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | +| `rust-worker-bee` | Rust implementation and code review for production Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence | "implement this in Rust", "review this Cargo workspace", "fix this Tokio or SQLx service", "audit this SQLx transaction", "build the approved Rust PRD slice" | `rust-stinger` | | `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | @@ -251,7 +252,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/rust-worker-bee.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/rust-worker-bee.md new file mode 100644 index 00000000..7c2e21ad --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/rust-worker-bee.md @@ -0,0 +1,52 @@ +# rust-worker-bee + +## Domain +This Bee owns bounded implementation and code review for production Rust systems. It handles Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, decide dependency or release policy, issue final Quality acceptance, or authorize external effects. + +## Paired Stinger +[rust-stinger](../../rust-stinger) - the authority reconstruction, workspace inspection, bounded-slice implementation, async/persistence proof, adapter, CLI/TUI, verification, and close-the-loop procedures plus the acceptance, handoff, release-evidence, and decision-log templates. + +## Trigger phrases +- "Implement this in Rust." +- "Review this Cargo workspace." +- "Fix this Tokio or SQLx service." +- "Audit this SQLx transaction." +- "Build the approved Rust PRD slice." + +Also route proactively when a requested change or review touches Rust source, Cargo manifests or workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, or local Rust packaging evidence. + +## Do NOT route when +- The ask is HTTP/REST or MCP semantic and compatibility decisions: that is `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`; Rust implements their approved contracts. +- The ask is product, model, and provider policy: that is `ai-tools-platform-worker-bee` or the named product owner. +- The ask is schema architecture: that is `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- The ask is Security acceptance: that is `security-worker-bee`. +- The ask is dependency/license/advisory disposition: that is `dependency-audit-worker-bee`. +- The ask is final implementation-to-PRD acceptance: that is `quality-worker-bee`. +- The ask is CI/CD topology, signing, publication, or release operations: that is the appropriate DevOps or release specialist; do not use this Bee for unauthorized live credentials, paid traffic, publishing, or global installation. + +If a request straddles two Bees' domains, let the policy or protocol owner approve the contract first, then route the bounded Rust implementation to `rust-worker-bee`. + +## Inputs the Bee needs +- The exact repository or worktree, owned paths, branch/change boundary, and concurrent-work constraints. +- The authorizing PRD, ADR, ledger rows, acceptance criteria, gates, and repository instructions. +- The current Cargo graph, Rust source, features and targets, migrations, tests, and release configuration. +- Approved protocol, provider, persistence, security, CLI, platform, and operational contracts, including data-integrity and cancellation requirements. +- The required verification commands and explicit authorization for any external effect. + +If a missing input controls safety, public compatibility, money, credentials, signing, publication, or destructive behavior, invoke only to record the fail-closed blocker and smallest safe checkpoint; do not ask the Bee to guess. + +## Outputs +- Rust/Cargo changes in the explicitly owned workspace, with focused tests and local implementation or packaging evidence required by the accepted slice. +- An acceptance-linked Rust implementation handoff using `templates/implementation-handoff.md`, including changed paths, exact verification commands and results, safety evidence, rollback/recovery notes, and remaining gates. +- When release evidence is explicitly in scope, a populated local `templates/release-evidence-manifest.yaml`; signing and publication remain closed unless separately authorized. +- A precise blocker record instead of a completion claim when an owning decision, tool, gate, or required proof is missing. + +## Commonly sequenced with +- Plan execution loop: `rust-worker-bee` is the implementation Bee for Rust/Cargo work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Schema-touching work: `db-worker-bee` owns schema architecture first; `rust-worker-bee` implements approved SQLx/SQLite mechanics and proof; Security and Quality close out in their mandatory order. +- Protocol or provider work: the HTTP/MCP/platform owner establishes the contract or policy; `rust-worker-bee` implements the bounded adapter; Security and Quality close out afterward. + +## Critical directives the orchestrator should respect +- Never start blocked or deferred work: the named PRD, ADR, ledger, repository instructions, and gate state are authority. +- Keep harness agency and external effects fail-closed while requiring provable bounded concurrency, cancellation/replay behavior, transactions, crash recovery, redaction, and a default of no `unsafe`; no live credentials, paid traffic, global installation, signing, publication, or auto-update execution without explicit authorization. +- Preserve the verification order: implementation checks, Security, affected-check reruns, then Quality; partial or stale evidence is not shipped evidence. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/README.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/README.md new file mode 100644 index 00000000..2498a96f --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/README.md @@ -0,0 +1,16 @@ +# Rust Stinger + +Rust Stinger equips `rust-worker-bee` to implement and review production Cargo workspaces, async services, durable local state, operator surfaces, tests, and release evidence. It operationalizes the approved Command Brief while preserving protocol, Security, dependency, release, and Quality peer ownership. Its technical rules are traceable to [`research/research-summary.md`](research/research-summary.md) and the underlying primary-source notes. + +## Layout + +- `SKILL.md` — trigger, procedure, directives, outputs, and decision boundaries. +- `guides/` — numbered procedures matching every Command Brief action. +- `examples/` — worked happy-path and failure-boundary handoffs. +- `templates/` — reusable implementation, decision, and release-evidence stubs. +- `reports/` — report-shape template and future run archive. +- `research/` — immutable scripture-historian evidence packet. + +## Maintenance + +Update the research packet before changing version-sensitive guidance. The current packet marks Rust/Cargo, Tokio, SQLx, rustls, cargo-dist, platform support, and RustSec as explicit revalidation points; current-at-retrieval values are evidence snapshots, not defaults. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/SKILL.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/SKILL.md new file mode 100644 index 00000000..8c2d427b --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/SKILL.md @@ -0,0 +1,83 @@ +--- +name: "rust-stinger" +description: "Implements and reviews production Rust systems across Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui operator surfaces, tests, and release evidence. Use when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or invokes rust-worker-bee. Do not use it to invent protocol semantics, approve security or dependency policy, author the final Quality report, or publish a release." +license: MIT +--- + +# Rust Stinger + +Equip `rust-worker-bee` to own bounded Rust implementation while preserving the authority of the exact PRD, ADR, ledger, and peer specialists. Make async ownership, durability, state transitions, redaction, and release evidence mechanically reviewable. Stop at a recorded fail-closed boundary whenever a missing decision affects safety, compatibility, money, credentials, signing, publication, or another external effect. + +## Required inputs + +Before editing, obtain: + +- the exact repository or worktree, owned paths, and concurrent-work boundaries; +- the authorizing PRD/ADR/ledger rows, acceptance criteria, gates, and repository instructions; +- the existing Cargo graph, toolchain files, feature/target matrix, migrations, code, tests, and release configuration; +- approved protocol, provider, persistence, security, CLI, platform, and operational contracts; +- the required verification commands and explicit authorization for any external effect. + +If a missing input determines safety, public compatibility, monetary behavior, credentials, publication, or destructive behavior, return a blocker rather than choosing silently. + +## Procedure + +1. Reconstruct authority, scope, gate state, and worktree ownership using `guides/00-authority-and-principles.md`. +2. Inventory the Rust system and record revalidation points using `guides/01-inspect-workspace.md`. +3. Establish the smallest coherent crate, feature, type, and error design using `guides/02-design-workspace-and-types.md`. +4. Implement a test-first acceptance slice using `guides/03-implement-bounded-slices.md`. +5. Prove task, cancellation, stream, backpressure, timeout, retry, and shutdown behavior using `guides/04-prove-async-streams.md`. +6. Prove SQLite/SQLx transactions, migrations, crash recovery, and typed state transitions using `guides/05-prove-persistence-and-state.md`. +7. Implement provider and harness edges only behind approved contracts using `guides/06-implement-adapters.md`. +8. Build scriptable CLI and optional TUI surfaces using `guides/07-build-cli-and-tui.md`. +9. Run the complete owned verification and generate release evidence without publishing using `guides/08-verify-and-package-evidence.md`. +10. Produce the acceptance-linked handoff, route Security before Quality, and leave unresolved gates explicit using `guides/09-close-the-loop.md`. + +## Critical directives + +- Treat the named PRD, ADR, ledger, gate state, and repository instructions as authority. Never start blocked or deferred work. +- Keep provider code subordinate to the host harness: it may route inference but never acquire tools, approvals, repository access, memory, or user interaction. +- Default to bounded queues, explicit task owners, operation-level cancellation review, and no transparent replay after visible output or a harness-visible tool call. +- Put monetary/quota checks, reservations, reconciliation, idempotency, and aggregate updates in explicit transactions with concurrency and crash evidence. +- Keep credentials in approved secret references and start sensitive instrumentation with `skip_all`; allowlist only non-sensitive correlation and state fields. +- Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Enforce approved egress allowlists and never bypass redirect, DNS, or SSRF checks. +- Default to no `unsafe`. Any exception needs a minimal scope, written invariant, targeted tests, and independent review. +- Use fake providers and fixtures by default. Do not use live credentials, paid traffic, subscriptions, signing identities, publishing, auto-update, Git initialization, or destructive controls without explicit authorization. +- Never promote retrieval-time crate/tool versions, OS targets, durability settings, timeout values, signing systems, or soak thresholds into timeless defaults. Revalidate them at the decision point. +- Preserve peer authority: protocol semantics, product/provider policy, security acceptance, schema review, dependency/license disposition, CI topology, signing/publication, and final PRD Quality remain separate handoffs. +- Preserve verification order: implementation checks, Security, affected-check reruns, then Quality. Partial or stale evidence is not shipped evidence. + +See `guides/00-authority-and-principles.md` for the rationale and fail-closed decision table. + +## Output contract + +Produce a Rust implementation handoff from `templates/implementation-handoff.md`, backed by exact commands and artifacts. When release work is in scope, also populate `templates/release-evidence-manifest.yaml` without signing or publishing unless independently authorized. Past execution reports belong in `reports/`; see `reports/README.md`. + +## Examples + +- `examples/01-happy-path-bounded-service-slice.md` — Cargo/Axum/SQLx acceptance slice with deterministic evidence. +- `examples/02-edge-visible-output-cancellation.md` — cancellation after visible output, where replay must remain disabled. +- `examples/03-edge-concurrent-budget-reservation.md` — concurrent SQLite reservation and crash boundary. +- `examples/04-release-evidence-with-closed-gates.md` — package evidence generation with signing/publication held closed. + +## Research and refresh points + +Read `research/research-summary.md` and `research/evidence-synthesis.md` before making architecture or version-sensitive claims. Use `research/index.md` to locate primary notes. Re-fetch the Rust release/platform matrix, Tokio support policy, the selected SQLx transaction API, stable rustls APIs, cargo-dist behavior, and RustSec data at the point of use; the research packet records a 2026-07-24 snapshot, not permanent defaults. + +## Human decisions that remain open + +Do not resolve these from the Stinger alone: + +- supported OS/architecture/install matrix and minimum OS baselines; +- actual MSRV after the resolved graph and public features exist; +- SQLite power-loss durability and contended-writer behavior; +- durable replay/promotion event schema; +- first-milestone TUI scope; +- signing identity, attestation platform, installer formats, and publication authorization; +- quantitative soak pass/fail thresholds. + +Record the missing owner/decision, affected acceptance criteria, and first authorized next action in the handoff. + +## Paired owner + +This Stinger is paired with `rust-worker-bee`. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md new file mode 100644 index 00000000..e38c5359 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md @@ -0,0 +1,66 @@ +# Example 01 — Happy path: bounded service slice + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [verification](../guides/08-verify-and-package-evidence.md). + +## Input + +```text +Repo: /work/router +Owned paths: crates/router-daemon/**, crates/provider-fake/**, tests/stream_contract.rs +AC ROUTE-12: At most 16 in-flight requests; provider chunks preserve order; shutdown drains accepted turns in 2 seconds. +Gates: fake provider only; HTTP error schema already approved; no live credentials. +``` + +## Implementation pattern + +```rust +use tokio::sync::{mpsc, Semaphore}; +use tokio_util::sync::CancellationToken; + +struct RuntimeOwner { + cancel: CancellationToken, + capacity: std::sync::Arc, + queue: mpsc::Sender, +} + +impl RuntimeOwner { + async fn submit(&self, turn: Turn) -> Result<(), SubmitError> { + let permit = self.queue.reserve().await.map_err(|_| SubmitError::Stopping)?; + permit.send(turn); + Ok(()) + } +} +``` + +The bounded queue and reservation-before-send pattern follows Tokio's documented backpressure and cancellation behavior ([bounded MPSC](../research/async/2026-07-24-tokio-mpsc.md), [`reserve`](../research/async/2026-07-24-tokio-send-reserve.md)). The implementation also owns listener shutdown separately from joined background work ([Axum shutdown](../research/async/2026-07-24-axum-graceful-shutdown.md), [Tokio shutdown](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Focused proof + +```bash +cargo test -p router-daemon --test stream_contract bounded_admission +cargo test -p router-daemon --test stream_contract preserves_chunk_order +cargo test -p router-daemon --test shutdown drains_accepted_turns +cargo clippy -p router-daemon -p provider-fake --all-targets -- -D warnings +``` + +The contract test calls the Axum Router as a Tower service; a separate loopback test proves bind and shutdown ([research](../research/async/2026-07-24-axum-service-testing.md)). + +## Output + +```markdown +# Rust implementation handoff: ROUTE-12 bounded fake-provider route + +## Outcome +The fake-provider route admits no more than 16 concurrent turns, preserves chunk order, and drains accepted work during bounded shutdown. + +## Acceptance evidence +- ROUTE-12: three focused tests PASS; no live provider or credential path executed. + +## Safety and operations +- External effects used: none +- Shutdown: listener admission stops, root token cancels workers, owner joins tracked tasks. + +## Peer handoffs and remaining gates +- Security: ready for redaction and shutdown review. +- Quality: wait until Security and affected-check reruns complete. +``` diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md new file mode 100644 index 00000000..b3454f06 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md @@ -0,0 +1,62 @@ +# Example 02 — Edge case: cancellation after visible output + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async/replay proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC REPLAY-07: A provider disconnect before output may be retried once. After any visible chunk or harness-visible tool call, the turn must never be replayed automatically. +Fixture: provider emits chunk seq=0, then disconnects. +``` + +## State pattern + +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Visibility { + None, + OutputSeen, + ToolCallSeen, +} + +enum Recovery { + ReplayEligible(NoVisibleEffect), + ResumeRequired { correlation_id: CorrelationId }, +} + +fn classify(trace: &TurnTrace) -> Recovery { + match trace.visibility { + Visibility::None => Recovery::ReplayEligible(NoVisibleEffect::new_private()), + Visibility::OutputSeen | Visibility::ToolCallSeen => Recovery::ResumeRequired { + correlation_id: trace.correlation_id, + }, + } +} +``` + +Keep the proof-token constructor private so callers cannot manufacture replay eligibility; rustls uses private verification markers for the same omitted-check defense ([research](../research/security/2026-07-24-rustls-verification-markers.md)). Use an explicit tagged durable representation rather than an ambiguous untagged enum ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). + +## Failure-focused proof + +```bash +cargo test -p router-core replay_before_output_is_single_use +cargo test -p provider-fake disconnect_after_first_chunk_disables_replay +cargo test -p provider-fake tool_call_visibility_disables_replay +cargo test -p router-daemon dropped_body_cancels_upstream_and_releases_permit +``` + +The last test matters because an Axum body is pull-driven and only preserves the desired backpressure if upstream production stops on disconnect ([research](../research/async/2026-07-24-axum-streaming-body.md)). Each selected future is reviewed individually because Tokio cancellation safety is operation-specific ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). + +## Output + +```markdown +## Outcome +Disconnect before visibility consumes one replay proof; disconnect after seq=0 returns `resume_required` and does not create a second provider request. + +## Acceptance evidence +- REPLAY-07: four focused tests PASS; fake request count remains 1 after visible output. + +## Safety and operations +- External effects used: none +- Recovery: correlation and last visible sequence persist; automatic replay remains disabled. +``` diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md new file mode 100644 index 00000000..01e90549 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md @@ -0,0 +1,49 @@ +# Example 03 — Edge case: concurrent budget reservation + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded slices](../guides/03-implement-bounded-slices.md), [persistence/state proof](../guides/05-prove-persistence-and-state.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC BUDGET-09: Two processes racing for the last $0.10 cannot reserve more than the account balance. Duplicate idempotency keys return the original reservation. Crash before commit leaves no partial reservation. +Approved decision: BEGIN IMMEDIATE; durability PRAGMA remains separately gated. +``` + +## Transaction pattern + +```sql +UPDATE budget +SET reserved_microunits = reserved_microunits + ?1 +WHERE account_id = ?2 + AND limit_microunits - spent_microunits - reserved_microunits >= ?1 +RETURNING reserved_microunits; +``` + +Run the eligibility check, conditional update, reservation row, and idempotency record inside one tracked write transaction. SQLite permits one writer and `BEGIN IMMEDIATE` acquires write intent before the read/modify/write sequence ([research](../research/persistence/2026-07-24-sqlite-transactions.md)); SQLx 0.9 documents `begin_with`, but the selected version must be revalidated before using that API ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). + +## Failure-focused proof + +```bash +cargo test -p router-state concurrent_last_balance_has_one_winner +cargo test -p router-state duplicate_idempotency_key_returns_same_reservation +cargo test -p router-state kill_before_commit_recovers_all_or_none +cargo test -p router-state busy_timeout_returns_structured_contention +``` + +Use two real SQLite connections/processes; a process-local lock is not sufficient. Preserve database and WAL/SHM/journal companions in the crash fixture because recovery semantics depend on them ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). + +## Output + +```markdown +## Outcome +Exactly one racing process reserves the final balance; duplicate requests are idempotent; pre-commit crash recovery is all-or-none. + +## Acceptance evidence +- BUDGET-09: 100 deterministic race iterations PASS with exactly one winner; crash fixture PASS. + +## Peer handoffs and remaining gates +- Database: review schema/index and contention policy. +- Security: review account identifier handling and error redaction. +- Quality: wait until Security and reruns complete. +- Open: product owner must approve power-loss durability and busy UX before support claim. +``` diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md new file mode 100644 index 00000000..57ea49d3 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md @@ -0,0 +1,45 @@ +# Example 04 — Release evidence with signing and publication closed + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [CLI/TUI boundary](../guides/07-build-cli-and-tui.md), [verification/release evidence](../guides/08-verify-and-package-evidence.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC RELEASE-04: Produce local macOS ARM64 package evidence and an uninstall transcript. +Not authorized: signing, attestation, GitHub release, registry publication, installer execution outside a temp prefix. +Open: final multi-platform matrix and signing identity. +``` + +## Local-only evidence commands + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo nextest run --profile release +cargo test --workspace --doc +cargo package --workspace +``` + +Then run the repository's pinned local package generator into a staging directory, calculate hashes, generate the approved SBOM/advisory/license reports, and install/uninstall only inside an isolated temporary prefix. `cargo package` verifies package contents/buildability but not provenance ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)); cargo-dist checksums are integrity evidence but are not signed proof ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). + +Do not invoke Cosign or a public release workflow: blob signing can create OIDC identity and transparency-log records ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). Re-run RustSec immediately at release time because advisory results are time-dependent ([research](../research/supply-chain/2026-07-24-rustsec.md)). + +## Output + +```markdown +## Outcome +Unsigned macOS ARM64 staging artifacts, hashes, SBOM, scans, and isolated install/uninstall transcript were generated locally. + +## Verification +- `cargo nextest run --profile release` — PASS +- `cargo test --workspace --doc` — PASS +- local staging install/uninstall — PASS +- signing — BLOCKED (no identity/authorization) +- publication — BLOCKED (no authorization) + +## Peer handoffs and remaining gates +- Dependency/license: review SBOM and scan dispositions. +- Release/Security: select signing identity and verify provenance policy. +- Quality: after Security and affected reruns. +- Platform: no support claim beyond the locally exercised target. +``` diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/00-authority-and-principles.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/00-authority-and-principles.md new file mode 100644 index 00000000..bf7946e2 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/00-authority-and-principles.md @@ -0,0 +1,41 @@ +# 00 — Authority and principles + +## Purpose + +Reconstruct why the change is authorized, which paths are owned, which gates are open, and where Rust implementation authority ends. This guide covers Command Brief action 1 and every critical directive. + +## Procedure + +1. Read the repository instructions, exact PRD/sub-PRD, ADRs, execution ledger, acceptance criteria, and current Security/Quality evidence before source code. +2. Inspect `git status`, active branch/worktree, and owned paths. Treat unrelated or concurrent edits as user work. +3. Build a scope table with columns `AC`, `owned path`, `gate`, `proof`, and `peer handoff`. +4. Mark any blocked or deferred slice `BLOCKED`; do not prepare implementation behind it. +5. Record each decision that cannot be made locally: protocol semantics, provider/product policy, threat acceptance, schema policy, dependency/license exceptions, CI topology, signing, publication, or final Quality. +6. Confirm that all external effects are either `none` or separately authorized. + +## Fail-closed decision table + +| Missing fact | Required response | +|---|---| +| Safety or egress boundary | Stop and hand to Security/platform owner. | +| Public protocol meaning | Stop and hand to protocol owner. | +| Live credentials, paid traffic, or subscription use | Keep fake/fixture route only. | +| Destructive/billable CLI policy | Keep command disabled. | +| Signing, publication, installer execution, or auto-update | Generate local evidence only. | +| Target matrix, MSRV, durability, or soak threshold | Record a revalidation/TODO decision; do not declare support. | + +## Non-negotiable implementation posture + +- Use typed, explicit state at boundaries. Serde ignores unknown fields by default, so strict local control/config inputs need an intentional rejection or validated-conversion policy ([research](../research/boundaries/2026-07-24-serde-container-attributes.md)). +- Treat cancellation safety as a property of each awaited operation, not of async code generally ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +- Default sensitive instrumentation to `skip_all` because `#[instrument]` otherwise records function arguments ([research](../research/observability/2026-07-24-tracing-instrument.md)). +- Default to safe Rust and isolate any `unsafe` proof obligation behind the smallest safe abstraction ([research](../research/rust-cargo/2026-07-24-unsafe-rust.md)). +- Never equate a passing license/advisory tool with final legal or security acceptance; cargo-deny itself documents limits to license discovery ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Gate exit + +Proceed only when the assigned slice has authority, owned paths, acceptance proof, and peer handoffs. Otherwise populate `templates/implementation-handoff.md` as a precise blocker. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/01-inspect-workspace.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/01-inspect-workspace.md new file mode 100644 index 00000000..c389e466 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/01-inspect-workspace.md @@ -0,0 +1,38 @@ +# 01 — Inspect the Rust workspace + +## Purpose + +Inventory the current workspace before changing it. This guide covers Command Brief action 2. + +## Inventory commands + +Run only commands supported by the repository, and record unavailable tools as blockers rather than installing them implicitly. + +```bash +git status --short --branch +cargo metadata --format-version 1 --no-deps +cargo tree --workspace -e features +cargo tree --workspace -e normal,build,dev +cargo test --workspace --no-run +``` + +Also inspect `Cargo.toml`, `Cargo.lock`, `rust-toolchain*`, `.cargo/config*`, `build.rs`, migrations, release profiles, `deny.toml`, nextest configuration, and CI/release manifests. + +## Inspection checklist + +- Draw the crate dependency direction and identify public type owners. +- Record workspace edition, resolver, toolchain pin, declared `rust-version`, default features, optional providers/TUI, targets, and binary entry points. +- Find all `unsafe`, panic/unwrap/expect paths in daemon/adapter/state/migration boundaries, global mutable state, spawned tasks, channels, `select!`, retries, time access, raw SQL, logging macros, secret exposure, TLS customization, and migrations. +- Locate every task owner and shutdown join path; Axum listener shutdown does not join arbitrary background tasks ([research](../research/async/2026-07-24-axum-graceful-shutdown.md)). +- Locate every bounded and unbounded queue; bounded Tokio MPSC expresses backpressure while unbounded channels do not encode a memory limit ([research](../research/async/2026-07-24-tokio-mpsc.md)). +- Verify effective SQLite journal, synchronous, foreign-key, busy-timeout, and checkpoint policy; SQLx does not select a journal mode by default ([research](../research/persistence/2026-07-24-sqlx-connect-options.md)). +- Separate current stable from declared MSRV. Cargo's `rust-version` participates in resolution but still needs CI proof across advertised features ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- Treat compiler target tiers as compiler guarantees, not product install/runtime proof ([research](../research/rust-cargo/2026-07-24-platform-support.md)). + +## Revalidation record + +Create or update `templates/rust-decision-log.md` for values likely to drift: toolchain, MSRV, target matrix, Tokio line, SQLx API, rustls stable API, package generator, and advisory snapshot. Do not copy current-at-retrieval numbers from research without rechecking. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/02-design-workspace-and-types.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/02-design-workspace-and-types.md new file mode 100644 index 00000000..140625db --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/02-design-workspace-and-types.md @@ -0,0 +1,52 @@ +# 02 — Design workspace and types + +## Purpose + +Establish the smallest coherent design without inventing peer-owned semantics. This guide covers Command Brief action 3. + +## Workspace rules + +1. Keep one owner per invariant; do not create a crate per noun. +2. Keep protocol/domain types inward, policy/state above them, provider adapters at edges, daemon/control as composition, and CLI/TUI as clients. +3. Keep test-support out of production dependency paths. +4. Declare `resolver = "3"` explicitly in a virtual Rust 2024 workspace; resolver choice is global, and version 3 is the Rust 2024 default ([research](../research/rust-cargo/2026-07-24-cargo-resolver-v3.md)). +5. Keep features additive, inspect feature unification, and make optional providers/TUI default-off unless the product contract requires otherwise ([research](../research/rust-cargo/2026-07-24-cargo-features.md)). +6. Centralize shared dependency versions/features only when it reduces drift without making edge features leak inward. + +## Typed boundary rules + +- Convert edge DTOs into validated domain newtypes before use. +- Prefer explicit tagged enums for durable safety state; untagged Serde enums try variants in order and can be ambiguous ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). +- Use private constructors and consumable marker/capability values for completed checks such as `NoVisibleOutput`, `ReservationHeld`, or `SafeTurnReviewed`. rustls uses non-constructible verification markers to prevent omitted-check control flow ([research](../research/security/2026-07-24-rustls-verification-markers.md)). +- Keep provider and harness SDK types in edge crates; normalize into protocol-neutral facts. +- Use structured errors with redacted public display and preserved internal sources; `thiserror` supports opaque public wrappers and causal chains, but redaction still depends on selected fields ([research](../research/boundaries/2026-07-24-thiserror.md)). + +## Minimal typestate pattern + +```rust +pub struct NoVisibleOutput(()); + +impl NoVisibleOutput { + fn after_preflight(trace: &TurnTrace) -> Option { + (!trace.visible_output && !trace.tool_call).then_some(Self(())) + } +} + +pub fn authorize_replay(proof: NoVisibleOutput) -> ReplayAuthorized { + let _consumed = proof; + ReplayAuthorized +} +``` + +Keep constructors private to the state-owning crate. Persist the underlying facts and rebuild proof only through the validated transition path. + +## Architecture test ideas + +- Compile-fail tests for private marker construction. +- Feature-matrix builds proving core crates do not acquire provider/TUI dependencies. +- Public API inspection confirming no harness/provider SDK types cross inward. +- `forbid(unsafe_code)` at crate roots where dependencies allow it; otherwise maintain an explicit inventory. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/03-implement-bounded-slices.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/03-implement-bounded-slices.md new file mode 100644 index 00000000..f793433b --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/03-implement-bounded-slices.md @@ -0,0 +1,34 @@ +# 03 — Implement bounded acceptance slices + +## Purpose + +Implement test-first, acceptance-linked changes while preserving concurrent work. This guide covers Command Brief action 4. + +## Slice loop + +1. Select one acceptance criterion whose dependencies and gates are open. +2. Name the observable outcome, owned files, and fastest focused proof. +3. Add a failing unit, contract, property, migration, concurrency, or failure-injection test. +4. Implement the narrowest code that satisfies the proof. +5. Run format, focused test, affected crate checks, and the repository's relevant gate. +6. Record the exact command/result and map it back to the criterion. +7. Re-read the diff for scope, redaction, panic/unsafe, retries, feature leakage, and external effects. + +## Test selection + +- Use direct Axum/Tower service calls for most request/middleware contracts without binding a port ([research](../research/async/2026-07-24-axum-service-testing.md)). +- Use Tokio paused time for timeout/backoff/breaker/pin behavior; only Tokio-controlled time is paused ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Use proptest for invariant-rich values and transition sequences, and persist failing seeds ([research](../research/testing/2026-07-24-proptest-index.md)). +- Use real temporary SQLite and multiple connections/processes for persistence concurrency; Loom cannot see operations not expressed through Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Use narrow loopback integration tests only for bind, listener shutdown, disconnect, and process behavior. + +## Patch discipline + +- Do not edit paths outside assigned ownership. +- Do not install missing tools, initialize Git, change public policy, run live providers, or publish as a convenience. +- Do not weaken a test to fit the implementation. +- Do not turn retries on to hide a race; nextest can mark retry-only success as flaky, and release profiles should fail it absent an approved quarantine ([research](../research/testing/2026-07-24-nextest-retries.md)). + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/04-prove-async-streams.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/04-prove-async-streams.md new file mode 100644 index 00000000..3fb29767 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/04-prove-async-streams.md @@ -0,0 +1,36 @@ +# 04 — Prove async and stream correctness + +## Purpose + +Make task ownership, cancellation, timeout, retry, backpressure, ordering, shutdown, and cleanup observable. This guide covers Command Brief action 5. + +## Lifecycle model + +1. Name the root owner of every spawned task. +2. Define admission stop, cooperative cancellation signal, drain policy, join deadline, escalation, and cleanup. +3. Use bounded channels on hot paths and state the capacity rationale. +4. Review every `select!` awaited operation for documented cancellation safety; dropping and recreating a future must not lose observable work ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +5. Reserve channel capacity before expensive/fallible message construction when cancellation could otherwise lose the message; Tokio documents that cancelled `send` loses the message and queue position ([research](../research/async/2026-07-24-tokio-send-reserve.md)). +6. Call Tower readiness before dispatch and prove reserved capacity is released if dispatch/future is dropped ([research](../research/async/2026-07-24-tower-service-readiness.md)). +7. Record Tower layer order and test saturation, timeout, load shedding, and error mapping because layer order changes observable behavior ([research](../research/async/2026-07-24-tower-service-builder.md)). +8. Stop upstream production when an Axum response body is dropped; HTTP pull-based framing only provides backpressure if the producer is bounded and cancellation-aware ([research](../research/async/2026-07-24-axum-streaming-body.md)). +9. Detect shutdown, notify owned work, and wait for completion as separate phases ([research](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Replay boundary + +Track `visible_output`, `tool_call`, sequence/correlation ID, and reservation state as explicit facts. Once output or a harness-visible tool call occurs, consume/withhold the replay proof and return a structured terminal or recoverable state according to the approved contract; never infer safety from a transport error alone. + +## Required tests + +- cancellation before and after channel reservation; +- cancellation between `poll_ready` and `call`; +- client disconnect while producer is blocked; +- chunk ordering and correlation preservation; +- timeout at each side-effect boundary; +- retry only before the approved visibility boundary; +- shutdown under idle, saturated, streaming, and database-flush states; +- task/permit/handle cleanup after every failure path. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/05-prove-persistence-and-state.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/05-prove-persistence-and-state.md new file mode 100644 index 00000000..9e4f434c --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/05-prove-persistence-and-state.md @@ -0,0 +1,39 @@ +# 05 — Prove persistence and state machines + +## Purpose + +Make SQLx/SQLite transactions, locking, migrations, crash recovery, and state transitions atomic and testable. This guide covers Command Brief action 6. + +## Transaction rules + +1. Acquire write intent before reading mutable budget/quota state when the operation must serialize. SQLite allows one writer; deferred transactions can fail on read-to-write upgrade, while `BEGIN IMMEDIATE` attempts write acquisition at the start ([research](../research/persistence/2026-07-24-sqlite-transactions.md)). +2. Keep eligibility, reservation, aggregate update, and idempotency record in one transaction. +3. Use a conditional SQL update/constraint as the final oversubscription guard; an in-process mutex does not coordinate other processes. +4. Treat `SQLITE_BUSY` as a bounded, observable result. A timeout is not authority for invisible unbounded retry. +5. Use the selected SQLx version's tracked transaction API. `Connection::begin_with` is documented for SQLx 0.9; revalidate or design a version-specific alternative for other lines ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). +6. Centralize and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy. WAL improves reader/writer concurrency but still permits one writer and can grow under long readers ([research](../research/persistence/2026-07-24-sqlite-wal.md)). +7. Match product durability language to the chosen PRAGMAs; WAL with `synchronous=NORMAL` does not provide recent-transaction durability across power loss ([research](../research/persistence/2026-07-24-sqlite-pragma-durability.md)). + +## Migration rules + +- Embed migrations only after the database peer approves schema direction. +- Keep migrations forward-only; test old binary/new schema compatibility as required. +- Test interrupted migration, repeated startup, partial files, and crash/restart recovery. +- Preserve database, WAL, SHM, and journal companions together during recovery; SQLite's atomicity evidence relies on journal/WAL recovery and fault testing ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). +- Use compile-checked queries or checked-in offline metadata where practical; `migrate!` embeds migrations but does not replace compatibility/crash policy ([research](../research/persistence/2026-07-24-sqlx-migrations-queries.md)). + +## State-machine proof + +- Persist explicit tagged states/events and schema versions. +- Keep invalid transitions unconstructible through private types and consumed proof tokens. +- Model reservation, reconciliation, breaker, quota, pin, replay, recovery, and promotion in a reference state machine. +- Generate valid transition sequences, assert postconditions/invariants, shrink failures, and save regression seeds; upstream proptest state-machine support is sequential, so add independent concurrency evidence ([research](../research/testing/2026-07-24-proptest-state-machines.md)). +- Inject fake time, stale observations, duplicate commands, process crashes, busy writers, and restart recovery. + +## Open decision checkpoints + +> TODO: human decision before the relevant product slice — power-loss durability, busy timeout/UX, and final durable replay/promotion schema remain product/architecture decisions. + +## Worked examples + +See [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/06-implement-adapters.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/06-implement-adapters.md new file mode 100644 index 00000000..429b9550 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/06-implement-adapters.md @@ -0,0 +1,37 @@ +# 06 — Implement adapters behind approved contracts + +## Purpose + +Implement provider and harness edges without granting providers agency or inventing protocol policy. This guide covers Command Brief action 7. + +## Boundary design + +1. Import approved protocol/domain types into edge crates; do not leak SDK types inward. +2. Normalize provider chunks, usage, finish reasons, and errors into the approved internal contract. +3. Preserve correlation, ordering, visibility, tool-call, retry, reservation, and cancellation facts explicitly. +4. Inject credentials only through approved secret-reference interfaces. Secret wrappers require explicit exposure and reduce accidental Debug/copying, but do not replace the secret store ([research](../research/security/2026-07-24-secrecy.md)). +5. Start provider/request functions with `#[instrument(skip_all)]` and add only allowlisted fields; function arguments are captured by default otherwise ([research](../research/observability/2026-07-24-tracing-instrument.md)). +6. Let libraries emit structured events while daemon/CLI binaries own subscriber and sink initialization; tracing advises libraries not to set a global subscriber ([research](../research/observability/2026-07-24-tracing-subscriber.md)). +7. Use stable rustls safe builders and approved roots. Custom verifier APIs are deliberately dangerous and require Security review ([research](../research/security/2026-07-24-rustls-config-builder.md)). +8. Keep unsupported, unauthorized, and unconfigured routes disabled. + +## Fake-first contract suite + +Use fake HTTP servers and fixtures for: + +- success and chunk-boundary variation; +- malformed/unknown fields and structured errors; +- disconnect and cancellation at every visible-output boundary; +- throttling, timeout, server error, retry eligibility, and backpressure; +- usage/reservation/reconciliation and duplicate idempotency keys; +- secret/header/prompt redaction in logs, crashes, metrics, diagnostics, and support exports. + +Direct Router/Tower calls cover most HTTP contracts without a live listener ([research](../research/async/2026-07-24-axum-service-testing.md)); keep a narrow loopback test for bind/shutdown/stream disconnect. + +## Prohibited effects + +Do not use live credentials, paid/subscription traffic, public endpoints, signing identity, or provider activation unless the gate explicitly authorizes them. Adapter implementation never gives a provider tools, approvals, filesystem/repository access, memory, or user interaction. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/07-build-cli-and-tui.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/07-build-cli-and-tui.md new file mode 100644 index 00000000..e1a7730d --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/07-build-cli-and-tui.md @@ -0,0 +1,30 @@ +# 07 — Build CLI and TUI surfaces + +## Purpose + +Build operable, scriptable, redacted operator clients without creating a second control authority. This guide covers Command Brief action 8. + +## CLI contract + +- Model commands and constrained arguments with Clap typed parsers and subcommands ([research](../research/cli-tui/2026-07-24-clap-parser.md)). +- Test parsing with non-exiting APIs; decide printing and process exit only at the binary boundary. +- Keep human help/errors separate from stable JSON/stdout schemas. Clap exposes rendering and exit information, but human formatting is not a machine protocol ([research](../research/cli-tui/2026-07-24-clap-errors.md)). +- Define a domain exit-code taxonomy for operational failures. +- Require a reviewed confirmation or explicit noninteractive policy for destructive or billable commands; keep them disabled if absent. +- Make diagnostics/support exports previewable, double-redacted, and free of prompt bodies, code, raw credentials, headers, and unsalted account identifiers. + +## Optional TUI contract + +- Keep the TUI feature-gated and thin over the same authenticated control client as the CLI. +- Prefer the main Ratatui crate unless a lower-level crate is specifically required; upstream recommends this for ordinary applications ([research](../research/cli-tui/2026-07-24-ratatui-architecture.md)). +- Use Ratatui's managed `run` lifecycle or explicitly handle fallible init/restore so success, error, panic, and cancellation restore the terminal ([research](../research/cli-tui/2026-07-24-ratatui-lifecycle.md)). +- Unit-test widgets against buffers and integration-test the whole UI with `TestBackend` ([research](../research/cli-tui/2026-07-24-ratatui-test-backend.md)). +- Add narrow platform/real-terminal smoke tests only where the supported matrix requires them. + +## Open decision checkpoint + +> TODO: human decision before implementation — whether the TUI is in the first executable milestone remains unresolved. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/08-verify-and-package-evidence.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/08-verify-and-package-evidence.md new file mode 100644 index 00000000..9796ac2c --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/08-verify-and-package-evidence.md @@ -0,0 +1,54 @@ +# 08 — Verify and package evidence + +## Purpose + +Run the complete owned Rust gate and generate reviewable package evidence without claiming peer acceptance or performing unauthorized external effects. This guide covers Command Brief action 9. + +## Verification ladder + +Adapt exact commands to the repository and record every result. + +```bash +cargo fmt --all -- --check +cargo check --workspace --all-targets +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo test --workspace --doc +cargo metadata --format-version 1 +cargo tree --workspace -e features +``` + +Add declared minimal/default/all-feature builds, MSRV checks, target builds, migration/concurrency/crash/fake-provider tests, property/model tests, benchmarks, and soak checks. Clippy guidance recommends `-Dwarnings` with the same compiler toolchain as compilation; new lints make the result toolchain-specific ([research](../research/rust-cargo/2026-07-24-clippy-ci.md)). Nextest does not run doctests, so retain a separate doc-test step ([research](../research/testing/2026-07-24-nextest.md)). + +## Evidence layers + +- Unit/contract: pure logic and direct Tower/Axum calls. +- Deterministic time: Tokio paused clock for time-driven behavior ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Property/state: proptest with saved seeds. +- Model concurrency: Loom only for small primitives expressed with Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Persistence/process: real SQLite, multiple writers, fault injection, kill/restart. +- Provider/stream: fake servers and transcript fixtures. +- Benchmark: Criterion on a controlled host; statistics do not remove noisy-host risk ([research](../research/testing/2026-07-24-criterion-analysis.md)). +- Soak: purpose-built fake-provider run with periodic RSS, task, queue, DB/WAL, handle, throughput, and error telemetry. + +> TODO: human decision before release qualification — define quantitative soak thresholds; no universal off-the-shelf eight-hour harness or product threshold exists in the research packet. + +## Release evidence packet + +Populate `templates/release-evidence-manifest.yaml` with target artifacts, hashes, toolchain/lockfile, tests, SBOM, advisory/license/source scans, install/uninstall transcripts, and verification commands. + +- Revalidate cargo-dist before generating archives/installers; it supports target artifacts, checksums, and several installers, while checksums alone are unsigned integrity values ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). +- Generate target/feature-aware SBOM evidence and record tool version; cargo-cyclonedx added reproducible timestamp and target support in its retrieval-time release ([research](../research/supply-chain/2026-07-24-cargo-cyclonedx.md)). +- Record advisory database time and lockfile/artifact hash because RustSec findings are point-in-time ([research](../research/supply-chain/2026-07-24-rustsec.md)). +- Treat cargo-deny output as evidence for the dependency owner, not license/legal clearance ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). +- Treat Cargo's native SBOM precursor as optional/nightly until stabilized ([research](../research/supply-chain/2026-07-24-cargo-sbom-unstable.md)). +- Do not confuse `cargo package` verification with provenance; Cargo states provenance is not verified ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)). +- Do not sign or publish. Cosign signing can create identity/transparency-log effects and needs explicit authorization ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). + +## Open decision checkpoints + +> TODO: human decisions before release — supported targets/baselines, MSRV, installer formats, signing/attestation identity, and publication authorization. + +## Worked examples + +See [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/09-close-the-loop.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/09-close-the-loop.md new file mode 100644 index 00000000..dd6bedc9 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/guides/09-close-the-loop.md @@ -0,0 +1,42 @@ +# 09 — Close the loop + +## Purpose + +Return acceptance-linked implementation evidence, limitations, recovery notes, and peer handoffs in the required order. This guide covers Command Brief action 10. + +## Completion procedure + +1. Re-read the requested acceptance criteria and current ledger/gates. +2. Run the final relevant Rust commands against the current tree; do not reuse stale results. +3. Populate `templates/implementation-handoff.md` with exact outcomes and changed paths. +4. For each criterion, cite a command, test, artifact, and result. +5. State external effects exactly: `none` or the recorded authorization/effect. +6. Explain migration, rollback, restart, and data recovery, including any irreversible step. +7. Explain prompt/secret/log/diagnostic handling and remaining Security questions. +8. Route the implemented state to Security. If fixes land, rerun affected implementation gates. +9. Route the post-Security state to Quality for final implementation-to-PRD audit. +10. Leave protocol, platform, dependency/license, CI/release, signing, publication, and other gates with their actual owners. + +## Evidence honesty rules + +- A current-stable toolchain is not a proven MSRV; Cargo requires verification of declared `rust-version` across supported functionality ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- A compiler-supported target is not a product-supported install/runtime target ([research](../research/rust-cargo/2026-07-24-platform-support.md)). +- Passing Loom is not general concurrency proof because unmodeled operations are invisible and state spaces are bounded ([research](../research/testing/2026-07-24-loom.md)). +- A retry-only test success is flaky evidence, not a clean pass ([research](../research/testing/2026-07-24-nextest-retries.md)). +- A generated checksum, SBOM, advisory scan, or license scan does not by itself prove signed provenance or peer acceptance ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md), [research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Blocked checkpoint + +When blocked, provide the smallest safe compilable/testable checkpoint if one exists, then name: + +- blocker and owning gate; +- affected acceptance criteria; +- files/tests completed; +- commands that passed, failed, or were unavailable; +- first authorized next action. + +Never call a partial checkpoint shipped or release-ready. + +## Worked examples + +See all four examples, especially [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/README.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/README.md new file mode 100644 index 00000000..bdb75008 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/README.md @@ -0,0 +1,3 @@ +# Rust Stinger reports + +This folder accumulates dated implementation handoffs produced by `rust-worker-bee`; copy `implementation-handoff-report-template.md`, preserve exact command evidence, and never overwrite an earlier run. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/implementation-handoff-report-template.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/implementation-handoff-report-template.md new file mode 100644 index 00000000..ccb48186 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/reports/implementation-handoff-report-template.md @@ -0,0 +1,15 @@ +# Rust implementation handoff: {{slice_name}} + +Use the complete reusable form in [`../templates/implementation-handoff.md`](../templates/implementation-handoff.md). Store a populated copy here as `YYYY-MM-DD-{{slice_slug}}.md` only when the orchestrator designates this global Stinger as the report archive; product-specific evidence normally remains in the product's authorized artifact path. + +Required sections: + +1. Outcome +2. Authority and scope +3. Acceptance evidence +4. Changed paths +5. Verification +6. Safety and operations +7. Revalidation points +8. Peer handoffs and remaining gates +9. Blocker, if any diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md new file mode 100644 index 00000000..ac6314f7 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/serve/struct.Serve.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: axum +stinger: rust-stinger +--- + +# Axum server graceful shutdown + +## Summary +Axum's `Serve::with_graceful_shutdown` binds server lifetime to a supplied future. It stops accepting new work when the signal resolves and waits for connections according to the server's graceful behavior. Application-owned background tasks still need separate ownership and joining. + +## Key quotations / statistics +- "Prepares a server to handle graceful shutdown" +- The signal is a future "that resolves to `()`" + +## Version/date caveat +Axum latest docs at retrieval; exact connection-drain semantics depend on the matching hyper/axum versions. + +## Annotations for stinger-forge +- Use for the loopback listener shutdown path. +- Pair with Tokio task tracking; server shutdown alone does not prove all background work stopped. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md new file mode 100644 index 00000000..dd8c0e33 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/src/axum/routing/mod.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: testing +stinger: rust-stinger +--- + +# Axum router testing as a Tower service + +## Summary +Axum routers can be converted to borrowed or owned Tower services and invoked directly with requests. This avoids binding a real socket for most contract and middleware tests, making state, status, headers, and body behavior deterministic while reserving live-listener tests for integration boundaries. + +## Key quotations / statistics +- "Use `as_service` to get a borrowed `Service` from a `Router`." +- "Use `into_service` to get an owned `Service`" + +## Version/date caveat +Source docs for Axum latest; test helpers and body collection APIs vary across axum/http-body-util releases. + +## Annotations for stinger-forge +- Supports in-process HTTP contract tests without network flakiness. +- Loopback bind and shutdown still require a smaller dedicated integration test. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md new file mode 100644 index 00000000..2c2c12f0 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/body/struct.Body.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: streaming +stinger: rust-stinger +--- + +# Axum streaming bodies + +## Summary +Axum 0.8.9 wraps `http_body::Body` and can create a response body from a fallible `Stream`. Consumers pull frames asynchronously through `poll_frame`; converting to a data-only stream discards trailers. Backpressure therefore propagates through polling only if the upstream producer is itself bounded and cancellation-aware. + +## Key quotations / statistics +- `from_stream`: "Create a new `Body` from a `Stream`." +- `poll_frame`: "Attempt to pull out the next data buffer of this stream." + +## Version/date caveat +Axum 0.8.9, http-body 1.1.0 at retrieval. Frame/trailer behavior must match the selected HTTP contract. + +## Annotations for stinger-forge +- Core source for streaming body construction and disconnect/cancellation tests. +- Do not collect unbounded streams into memory; test that dropping the body stops producer work and releases permits. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md new file mode 100644 index 00000000..653ee9c7 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/shutdown +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: shutdown +stinger: rust-stinger +--- + +# Tokio graceful shutdown + +## Summary +Tokio presents graceful shutdown as three explicit phases: detect the trigger, notify owned work, and wait for work to finish. It demonstrates cancellation tokens for cooperative notification and task trackers for joining all tracked work, allowing cleanup such as database flushes before termination. + +## Key quotations / statistics +- "Figuring out when to shut down." +- "Waiting for other parts of the program to shut down." + +## Version/date caveat +Conceptual Tokio topic page; exact APIs may live in `tokio-util` and must match the selected versions. + +## Annotations for stinger-forge +- Core source for task ownership and shutdown checklists. +- Supports a root cancellation token plus explicit join/timeout/escalation evidence. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md new file mode 100644 index 00000000..c0c0d4cf --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: backpressure +stinger: rust-stinger +--- + +# Tokio bounded MPSC channels + +## Summary +Tokio's bounded MPSC channel supplies backpressure by suspending senders when capacity is exhausted. Clean shutdown closes the receiver and drains buffered values; dropping the receiver drains and drops unread messages. Unbounded channels have infinite logical capacity and therefore cannot express a memory/backpressure bound. + +## Key quotations / statistics +- "the channel provides backpressure" +- "the receiver first calls `close`, which will prevent any further messages" + +## Version/date caveat +Retrieved against Tokio 1.53.1. Allocation details are explicitly implementation details and may change. + +## Annotations for stinger-forge +- Grounds bounded queue requirements and shutdown draining tests. +- Supports rejecting unbounded queues on stream/provider hot paths without a proven upper bound. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md new file mode 100644 index 00000000..d86db676 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/tokio/latest +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: tokio +stinger: rust-stinger +--- + +# Tokio current release and support policy + +## Summary +Docs.rs records Tokio 1.53.1 released 2026-07-20. Tokio states that 1.51.x is LTS through March 2027 with MSRV 1.71, while current minor releases may move faster. A fixed-minor daemon dependency can choose an LTS line, but the choice must be reconciled with required APIs and security fixes. + +## Key quotations / statistics +- "1.53.1 (2026-07-20)" +- "`1.51.x` - LTS release until March 2027. (MSRV 1.71)" + +## Version/date caveat +Patch versions and LTS designations can change; this is a retrieval-time snapshot. + +## Annotations for stinger-forge +- Use to frame current versus LTS version policy without choosing on the release peer's behalf. +- Record the transitive-dependency MSRV caveat stated by Tokio. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md new file mode 100644 index 00000000..09e162ed --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/macro.select.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: cancellation +stinger: rust-stinger +--- + +# Tokio `select!` cancellation safety + +## Summary +Tokio defines cancellation safety as dropping and recreating an incomplete future without observable loss. The docs enumerate safe and unsafe operations and warn that loops using non-cancellation-safe futures can lose data when another branch wins. This must be checked per awaited operation, not assumed because code is async. + +## Key quotations / statistics +- "it must be a no-op to drop that future and recreate it" +- "The lists in this section are not exhaustive." + +## Version/date caveat +Retrieved against Tokio 1.53.1; method-level cancellation guarantees may change and should be linked directly in code review. + +## Annotations for stinger-forge +- Core source for cancellation audits around streams, writes, queues, and database work. +- Supports focused tests for the exact boundary where visible output makes replay forbidden. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md new file mode 100644 index 00000000..60756cfc --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/src/tokio/sync/mpsc/bounded.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: permits +stinger: rust-stinger +--- + +# Tokio MPSC reserve and cancellation + +## Summary +The bounded-channel source documentation says cancelling `send` loses the message and the sender's queue position. Reserving capacity first returns a permit so message construction can occur only after capacity is secured. Outstanding permits also delay a receiver from observing final closure. + +## Key quotations / statistics +- "the message is dropped and will be lost" +- "To avoid losing messages, use `reserve`" + +## Version/date caveat +Source documentation for Tokio latest (1.53.1 at retrieval); treat internal implementation as unstable while relying on documented public behavior. + +## Annotations for stinger-forge +- Supports reserve-before-expensive-work and cancellation-focused queue tests. +- Shutdown code must account for outstanding permits, not only sender handles. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md new file mode 100644 index 00000000..dcce062a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: middleware +stinger: rust-stinger +--- + +# Tower concurrency, buffering, and load shedding + +## Summary +`ServiceBuilder` exposes concurrency limits, buffers, timeouts, and load shedding as composable layers. Concurrency limits count in-flight requests through response-future completion. Load shedding converts lack of readiness into an immediate error rather than waiting. Layer order changes which work is bounded and which errors are visible. + +## Key quotations / statistics +- "Limit the max number of in-flight requests." +- "`LoadShed` immediately responds with an error" + +## Version/date caveat +Feature-gated Tower APIs; selected crate features and layer order must be recorded in the workspace. + +## Annotations for stinger-forge +- Supports explicit capacity/timeout/load-shed policy and layer-order tests. +- Protocol error mapping remains a peer decision; this source only establishes middleware behavior. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md new file mode 100644 index 00000000..974e3456 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/trait.Service.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: readiness +stinger: rust-stinger +--- + +# Tower `Service` readiness contract + +## Summary +Tower separates readiness from dispatch. Callers must observe `poll_ready` before `call`; readiness may reserve shared resources, which implementations must release if dispatch never occurs or the response future is dropped. Capacity is therefore an ownership contract, not merely a performance hint. + +## Key quotations / statistics +- "Before dispatching a request, `poll_ready` must be called" +- readiness "may reserve shared resources" + +## Version/date caveat +Tower latest docs at retrieval; middleware can alter readiness semantics by layer order. + +## Annotations for stinger-forge +- Core evidence for backpressure-aware Tower services and adapters. +- Supports tests that cancel between readiness and call and assert permit/resource release. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md new file mode 100644 index 00000000..fc5a2b46 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/container-attrs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: validation +stinger: rust-stinger +--- + +# Serde container boundary attributes + +## Summary +Serde's container attributes allow unknown-field rejection, fallible conversion through `try_from`, transparent newtypes, defaults, and explicit tagging. Unknown fields are ignored by default in self-describing formats, so strict control/config inputs require an intentional choice rather than assuming fail-closed parsing. + +## Key quotations / statistics +- `deny_unknown_fields` will "Always error during deserialization when encountering unknown fields." +- By default, "unknown fields are ignored" + +## Version/date caveat +`deny_unknown_fields` cannot be combined with `flatten`; compatibility policy must account for that limitation. + +## Annotations for stinger-forge +- Grounds strict config/control-plane parsing and validated newtypes. +- Use separate input DTOs when forward-compatible wire payloads must retain unknown fields. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md new file mode 100644 index 00000000..f2e288b8 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/enum-representations.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: serde +stinger: rust-stinger +--- + +# Serde enum representations + +## Summary +Serde supports externally, internally, adjacently, and untagged enum encodings. Tagged enums make the selected variant explicit before or alongside content; untagged enums try variants in order and accept the first successful parse. For safety-state and protocol boundaries, representation choice affects ambiguity, forward compatibility, and error quality. + +## Key quotations / statistics +- Externally tagged data identifies "which variant we are dealing with before beginning to parse" +- Untagged "will try to match the data against each variant in order" + +## Version/date caveat +Serde project documentation; specific derive behavior still depends on the pinned serde version and enabled `alloc` feature. + +## Annotations for stinger-forge +- Supports explicit tagged enums for state/event boundaries where ambiguity is unacceptable. +- Protocol wire encoding remains the protocol peer's contract. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md new file mode 100644 index 00000000..692d0b6e --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/thiserror/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: errors +stinger: rust-stinger +--- + +# thiserror structured errors + +## Summary +thiserror 2.0.19 derives standard error implementations without becoming part of the public API contract. `source`, `from`, and `transparent` preserve causal chains, while an opaque public wrapper can hide a private evolving representation. Redaction still depends on the chosen fields and Display text. + +## Key quotations / statistics +- "Errors may use `error(transparent)` to forward the source and Display methods" +- "hiding implementation details ... behind an opaque error type" + +## Version/date caveat +Version 2.0.19 was published six days before retrieval; pin and test formatting if machine parsing depends on it. + +## Annotations for stinger-forge +- Supports domain error enums at crate boundaries and opaque public errors. +- Do not place secrets/prompts in source error values or formatted context. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md new file mode 100644 index 00000000..e079d17a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/type.Error.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: exits +stinger: rust-stinger +--- + +# Clap error and exit behavior + +## Summary +Clap errors expose their kind, rendered form, stderr/stdout routing, printing, and exit code. Library/test paths can use non-exiting parse APIs, while the process boundary decides when to print and exit. Operational failures after parsing need a separate stable exit-code taxonomy. + +## Key quotations / statistics +- The error API includes `exit_code`. +- The error API includes `use_stderr` and `render`. + +## Version/date caveat +Clap 4.6.2 at retrieval; exact human rendering is not a stable machine protocol. + +## Annotations for stinger-forge +- Supports separating parse errors from domain/transport exit codes. +- Require JSON/stdout contracts to avoid scraping colored human help/error output. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md new file mode 100644 index 00000000..f15fca06 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/parser/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: clap +stinger: rust-stinger +--- + +# Clap typed command-line parsing + +## Summary +Clap 4.6.2 provides `Parser`, `Subcommand`, `Args`, `CommandFactory`, and `ValueEnum` traits for typed command structures and introspection. These types support explicit command inventories, constrained values, generated help/completions, and parser tests independent of process execution. + +## Key quotations / statistics +- `ValueEnum`: "Parse arguments into enums." +- `CommandFactory`: "Create a `Command` relevant for a user-defined container." + +## Version/date caveat +Clap 4.6.2 at retrieval; help text and formatting can change across minor releases. + +## Annotations for stinger-forge +- Supports typed subcommands and deterministic parser contract tests. +- Machine-readable command output is an application schema layered above Clap. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md new file mode 100644 index 00000000..98784587 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: medium +topic: tui +stinger: rust-stinger +--- + +# Ratatui crate architecture + +## Summary +Ratatui's primary crate re-exports the application-facing surface, while lower-level workspace crates exist for custom widget libraries and backend-specific integrations. The docs recommend staying in the main crate unless a lower-level dependency is specifically needed, reducing feature and compile-time surface for ordinary applications. + +## Key quotations / statistics +- "Most application authors should stay in this `ratatui` crate." +- "Reach for other crates ... only when you specifically need a lower-level layer" + +## Version/date caveat +Ratatui 0.30.2; workspace decomposition may evolve. + +## Annotations for stinger-forge +- Supports avoiding premature internal TUI crate fragmentation. +- Feature-gate the entire TUI and keep domain/control logic outside it. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md new file mode 100644 index 00000000..bc52308f --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/init/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: terminal +stinger: rust-stinger +--- + +# Ratatui terminal initialization and restoration + +## Summary +Ratatui 0.30.2 recommends `run` for ownership of terminal setup/cleanup, or fallible `try_init`/`try_restore` when the application needs explicit handling. Helpers manage raw mode, alternate screen, and a panic hook that restores the terminal. Manual construction transfers teardown responsibility to the application. + +## Key quotations / statistics +- `run` "automatically restores the terminal state" +- "All initialization functions install a panic hook" + +## Version/date caveat +`run` was introduced in 0.30.0; older examples may show manual lifecycle code. + +## Annotations for stinger-forge +- Grounds terminal cleanup on success, error, panic, and cancellation. +- Favor the headless CLI/control client; keep the TUI a thin optional surface. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md new file mode 100644 index 00000000..afcd9d15 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/backend/struct.TestBackend.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: rendering +stinger: rust-stinger +--- + +# Ratatui `TestBackend` + +## Summary +Ratatui's `TestBackend` renders an integration-level terminal UI to an in-memory buffer and can assert lines, cursor, resize, and scrollback. The docs prefer direct widget-buffer tests for units and reserve `TestBackend` for whole-TUI integration, giving two appropriately sized evidence layers. + +## Key quotations / statistics +- "renders to an memory buffer" +- "preferable to write unit tests for widgets directly against the buffer" + +## Version/date caveat +Ratatui 0.30.2 at retrieval; snapshot glyph/width behavior can vary with terminal/unicode dependencies. + +## Annotations for stinger-forge +- Supports deterministic TUI rendering tests without a real terminal. +- Add narrow real-terminal smoke tests only where lifecycle/platform integration matters. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/evidence-synthesis.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/evidence-synthesis.md new file mode 100644 index 00000000..70a55448 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/evidence-synthesis.md @@ -0,0 +1,178 @@ +# Rust Stinger Evidence Synthesis + +This is an evidence map for Stinger Forge, not a replacement for the product ADR, protocol contract, Security review, dependency/license decision, release authorization, or Quality report. The 56 indexed source notes are authoritative inputs; this file connects them to the Command Brief's research questions and records the remaining decisions honestly. +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +## Current anchors at retrieval + +| Surface | Current evidence snapshot | Caveat | +|---|---|---| +| Rust | 1.97.1 released 2026-07-16 | Current stable is not automatically the product MSRV. | +| Cargo | Rust 2024 resolver v3; `rust-version`-aware fallback | Virtual workspaces must declare the resolver; CI must prove MSRV. | +| Tokio | 1.53.1 released 2026-07-20; 1.51.x LTS through March 2027 | Tokio's MSRV does not establish the whole graph's MSRV. | +| Axum | 0.8.9 docs snapshot | Pin compatible hyper/http-body/tower versions together. | +| SQLx | 0.9.0 docs snapshot | `begin_with` is version-specific; verify before applying to SQLx 0.8. | +| Clap / Ratatui | 4.6.2 / 0.30.2 | Human rendering and TUI APIs can change across minor versions. | +| rustls | 0.23.42 stable docs; 0.24 development docs also visible | Avoid accidental dependency on development APIs. | +| Testing | Loom 0.7.2; Criterion 0.8.2 | Model and benchmark results have explicit coverage/environment limits. | +| SBOM | cargo-cyclonedx 0.5.9 (2026-03-19) | Cargo native SBOM precursors remain unstable/nightly. | + +## 1. Tokio, Axum, and Tower ownership, cancellation, streaming, and shutdown + +The sources converge on a verifiable lifecycle made of distinct obligations: + +1. A root owner detects shutdown, signals cooperative cancellation, stops admission, and waits for every owned task. Tokio's shutdown guide explicitly separates trigger, notification, and joining. +2. Bounded MPSC channels express a capacity contract. Clean shutdown closes the receiver and drains it. `send` inside `select!` may lose the message; `reserve` obtains capacity first and makes that boundary testable. +3. Every `select!` branch needs method-level cancellation review. "Async" alone does not imply cancellation safety. +4. Tower readiness is a resource reservation. `poll_ready` must precede `call`, and capacity must be released if dispatch or its future is dropped. Concurrency-limit, buffer, timeout, and load-shed layer order changes observable behavior. +5. Axum can serve a fallible stream as a response body. HTTP consumers pull frames; the upstream producer must still be bounded and cancellation-aware. Dropping/disconnecting the body should stop producer work and release permits in focused tests. +6. `with_graceful_shutdown` owns listener/connection admission, not arbitrary background work. Background task ownership remains in Tokio task tracking. +7. Most router/middleware contracts can be tested by invoking the Router as a Tower service without binding a port. A narrower loopback integration test proves bind address, shutdown, and disconnect behavior. + +Primary notes: [Tokio shutdown](async/2026-07-24-tokio-graceful-shutdown.md), [MPSC](async/2026-07-24-tokio-mpsc.md), [`select!`](async/2026-07-24-tokio-select-cancellation.md), [reserve](async/2026-07-24-tokio-send-reserve.md), [Tower readiness](async/2026-07-24-tower-service-readiness.md), [Tower layers](async/2026-07-24-tower-service-builder.md), [Axum shutdown](async/2026-07-24-axum-graceful-shutdown.md), [Axum streaming](async/2026-07-24-axum-streaming-body.md), and [service testing](async/2026-07-24-axum-service-testing.md). + +## 2. SQLite and SQLx transactions, locking, and durability + +SQLite permits a single writer. `BEGIN DEFERRED` can read a stale budget view and then fail during write upgrade; `BEGIN IMMEDIATE` acquires write intent before the read-modify-write sequence. SQLx 0.9's `Connection::begin_with` provides a tracked custom transaction start, enabling `BEGIN IMMEDIATE` while preserving explicit commit/rollback and rollback-on-drop behavior. + +Evidence-supported invariants for reservations/reconciliations/breakers/migrations: + +- Acquire the write transaction before reading mutable budget/quota state. +- Keep eligibility check, reservation insert/update, aggregate update, and idempotency record in one transaction. +- Use conditional SQL constraints/updates as the final oversubscription guard; application locks are not sufficient across processes. +- Treat `SQLITE_BUSY` as a bounded, observable contention result. A busy timeout is not permission for invisible unbounded retry. +- Configure and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy through one connection-options path. +- WAL improves reader/writer concurrency but does not allow multiple writers. Long readers can starve checkpoints and grow the WAL. +- WAL plus `synchronous=NORMAL` can lose recent committed transactions after power loss. Product durability language must match the chosen PRAGMA contract. +- Crash evidence should kill/restart at transaction and checkpoint boundaries and verify all-or-none invariants. Preserve the database and its WAL/SHM/journal companions during recovery. +- Embedded migrations improve delivery but do not replace forward-only migration, old-binary/new-schema compatibility, and interruption tests. + +Primary notes: [transactions](persistence/2026-07-24-sqlite-transactions.md), [WAL](persistence/2026-07-24-sqlite-wal.md), [atomic commit](persistence/2026-07-24-sqlite-atomic-commit.md), [PRAGMAs](persistence/2026-07-24-sqlite-pragma-durability.md), [SQLx options](persistence/2026-07-24-sqlx-connect-options.md), [custom transactions](persistence/2026-07-24-sqlx-custom-transactions.md), and [queries/migrations](persistence/2026-07-24-sqlx-migrations-queries.md). + +## 3. Typed state machines and replay/promotion proof + +Rust's enums, newtypes, privacy, exhaustive matching, and ownership can make invalid transitions difficult to express. The strongest upstream example in this corpus is rustls: private marker values bind the fact that verification occurred and prevent skipping required checks before entering the traffic state. + +Evidence-supported design constraints for Forge to encode: + +- Persist durable facts as an explicit tagged enum/event schema; avoid ambiguous untagged parsing for safety state. +- Reject unknown fields on strict local control/config inputs unless an explicit compatibility contract requires otherwise. +- Use private constructors and non-forgeable capability/marker types for facts such as `NoVisibleOutput`, `NoToolCall`, `ReservationHeld`, or `SafeTurnReviewed`. +- Consume one-shot proof values on transition so replay/promotion cannot accidentally reuse authorization. +- Keep provider events and harness events in edge crates, normalize them into protocol-neutral domain facts, and let the state machine depend only on those facts. +- Represent terminal/irreversible states explicitly and test every transition plus serialization round trip against a reference model. +- Keep user-visible error codes separate from internal causal chains; neither should contain prompts, raw credentials, or headers. + +Primary notes: [Serde enums](boundaries/2026-07-24-serde-enum-representations.md), [strict attributes](boundaries/2026-07-24-serde-container-attributes.md), [thiserror](boundaries/2026-07-24-thiserror.md), [rustls builder typestate](security/2026-07-24-rustls-config-builder.md), and [verification markers](security/2026-07-24-rustls-verification-markers.md). + +## 4. Cargo workspace and MSRV evidence + +Resolver v3 is global at the top-level workspace. Features remain additive and can unify through dependency paths, so crate boundaries and feature design must prevent provider/TUI/TLS choices from leaking into protocol, policy, and state cores. + +A reviewable dependency direction for the accepted architecture is: + +```text +protocol/types <- policy/state <- provider adapters + ^ ^ ^ + | | | + daemon/control ----+--------------+ + ^ + CLI <- optional TUI + +test-support/evaluation may depend on public seams; +production crates must not depend on test-support. +``` + +This is a research-derived dependency constraint, not approval of exact crate names. Workspace review should look for: + +- one owner per invariant rather than a crate per noun; +- `resolver = "3"` in a virtual workspace; +- shared dependency versions/features declared centrally where that reduces drift; +- provider and TUI features default-off unless the product requires otherwise; +- `cargo tree -e features`, all-target/all-feature checks, and representative minimal-feature checks; +- public types flowing inward only from the approved protocol/domain crate, never harness/provider SDK types; +- a documented unsafe inventory, defaulting to `forbid(unsafe_code)` where possible. + +For a new removable local daemon, the credible starting toolchain is a pinned current stable release (1.97.1 at retrieval), with `package.rust-version` declared only after the full resolved graph and advertised features pass MSRV CI. Tokio 1.51.x is an available 2026 LTS line with MSRV 1.71, but that fact alone is not a reason to choose Rust 1.71 for the product. Re-check stable, platform tiers, and dependency MSRVs immediately before Forge freezes guidance. + +Primary notes: [current Rust](rust-cargo/2026-07-24-rust-release-1-97.md), [`rust-version`](rust-cargo/2026-07-24-cargo-rust-version.md), [resolver v3](rust-cargo/2026-07-24-cargo-resolver-v3.md), [features](rust-cargo/2026-07-24-cargo-features.md), [platform tiers](rust-cargo/2026-07-24-platform-support.md), [Cargo CI](rust-cargo/2026-07-24-cargo-ci-msrv.md), [Clippy](rust-cargo/2026-07-24-clippy-ci.md), and [Tokio release policy](async/2026-07-24-tokio-release-policy.md). + +## 5. Tracing, secrets, and TLS + +- `#[instrument]` captures all arguments by default, including Debug output. Sensitive functions should start from `skip_all` and add allowlisted identifiers/state fields. +- Libraries emit structured spans/events; binaries own subscriber/filter/sink initialization. Libraries should not set the global subscriber. +- Secret wrappers reduce accidental exposure and require explicit access, but do not replace a secret store and cannot prevent every copy during deserialization. +- rustls stable builders encode mandatory verifier/certificate choices and use safe defaults. Custom verifier APIs are deliberately marked dangerous and require Security review. +- TLS/provider selection, certificate roots, egress/redirect/DNS/SSRF controls, redaction acceptance, and crash-dump policy remain Security/platform decisions. + +Primary notes: [instrument capture](observability/2026-07-24-tracing-instrument.md), [subscriber ownership](observability/2026-07-24-tracing-subscriber.md), [secrecy](security/2026-07-24-secrecy.md), and [rustls](security/2026-07-24-rustls-config-builder.md). + +## 6. CLI and TUI evidence + +Clap supports typed subcommands, constrained enums, introspection, and non-exiting parse paths. Human help/error formatting should not become the machine protocol; define stable JSON/stdout schemas and a separate domain exit-code taxonomy. Destructive or billable commands need an explicit confirmation/noninteractive policy above Clap. + +Ratatui 0.30's `run` owns terminal initialization and restoration, including panic cleanup. Fallible init/restore APIs exist for explicit error handling. `TestBackend` provides deterministic integration rendering; direct buffer/widget tests are preferred for units. The TUI should remain feature-gated and depend on the same authenticated control client as the CLI rather than becoming a second authority. + +Primary notes: [Clap parser](cli-tui/2026-07-24-clap-parser.md), [Clap errors](cli-tui/2026-07-24-clap-errors.md), [terminal lifecycle](cli-tui/2026-07-24-ratatui-lifecycle.md), [TestBackend](cli-tui/2026-07-24-ratatui-test-backend.md), and [Ratatui architecture](cli-tui/2026-07-24-ratatui-architecture.md). + +## 7. Verification stack, including eight-hour soak evidence + +| Evidence layer | Primary mechanism | What it proves | Main limitation | +|---|---|---|---| +| Unit/contract | `cargo test`, direct Axum/Tower service calls | Pure logic, types, HTTP/service contracts | Does not prove listener/process behavior. | +| Deterministic time | Tokio `start_paused`, injected clocks | Timeouts, retry schedules, breakers, pins, promotion windows | Only controlled clocks advance. | +| Property/state | proptest + persisted seeds | Invariants across generated values/transition sequences | Current state-machine helper is sequential. | +| Model concurrency | Loom on small primitives | Explored synchronization interleavings | Requires Loom types; state explosion; not DB/process proof. | +| Persistence/concurrency | real temp SQLite, multiple connections/processes, fault injection | Write contention, idempotency, migration and crash recovery | Needs platform/filesystem coverage. | +| Provider/stream | fake HTTP servers and transcript fixtures | chunk ordering, cancellation, replay boundary, error normalization | Fixture drift must be managed; no live credentials. | +| Suite execution | cargo-nextest profiles, timeouts, JUnit | Isolation, classification, evidence export | Doctests remain separate; retries can mask flaws. | +| Microbenchmark | Criterion on controlled hosts | throughput/latency trends with confidence intervals | Noisy shared CI can mislead. | +| Eight-hour soak | purpose-built release harness under nextest/process supervisor | bounded memory/queues, handle/task cleanup, WAL growth/checkpoints, reconnect stability | No single crate proves this; requires explicit invariants and periodic telemetry. | + +An eight-hour soak should use fake providers and local fixtures, emit periodic bounded metrics (RSS, task count, queue depth, DB/WAL size, open handles, request/error counters), assert no monotonic leak or invariant breach, capture start/end versions/config/seeds, and fail on flaky retry. It is separate from Criterion and from Loom. + +Primary notes: [proptest state machines](testing/2026-07-24-proptest-state-machines.md), [Loom](testing/2026-07-24-loom.md), [Tokio time](testing/2026-07-24-tokio-time-testing.md), [nextest](testing/2026-07-24-nextest.md), [flaky retries](testing/2026-07-24-nextest-retries.md), and [Criterion](testing/2026-07-24-criterion-analysis.md). + +## 8. Packaging, SBOM, signing, and advisory evidence + +A credible 2026 release-evidence packet can contain target-specific archives/installers, hashes, install/uninstall transcripts, SBOM, embedded dependency metadata, advisory/license/source scan results, and provenance/signature verification. The tools have complementary roles: + +- cargo-dist builds target archives/installers and hashes; generated output and tool version must be pinned/reviewed. +- cargo-cyclonedx generates standardized SBOMs and supports `SOURCE_DATE_EPOCH`/target-aware output as of 0.5.9. +- cargo-auditable embeds dependency information in binaries for later scanning. +- cargo-deny supplies advisory/license/ban/source policy evidence but does not prove legal clearance. +- RustSec/cargo-audit produces point-in-time lockfile/binary advisory findings; record database time and lockfile/artifact hash. +- Cosign signs blobs and emits verification bundles; signing/publishing is an explicitly authorized external effect. +- Cargo's native SBOM precursor is still unstable/nightly and should remain supplemental for a stable baseline. +- `cargo package` verifies crate contents/buildability but explicitly does not prove provenance. + +Primary notes: [dist config](supply-chain/2026-07-24-cargo-dist-config.md), [dist attestations](supply-chain/2026-07-24-cargo-dist-attestations.md), [cargo-cyclonedx](supply-chain/2026-07-24-cargo-cyclonedx.md), [cargo-auditable](supply-chain/2026-07-24-cargo-auditable.md), [cargo-deny](supply-chain/2026-07-24-cargo-deny-checks.md), [license limits](supply-chain/2026-07-24-cargo-deny-license-limitations.md), [RustSec](supply-chain/2026-07-24-rustsec.md), [cargo-audit](supply-chain/2026-07-24-cargo-audit.md), [Cosign](supply-chain/2026-07-24-sigstore-cosign-blob.md), [Cargo SBOM](supply-chain/2026-07-24-cargo-sbom-unstable.md), and [cargo package](supply-chain/2026-07-24-cargo-package-verification.md). + +## Peer-boundary map + +| Area | Rust Bee may implement/prove | Peer retains final authority | +|---|---|---| +| HTTP/MCP/provider protocol | Approved types, adapters, fixtures, streaming behavior | Protocol semantics and compatibility | +| Security/TLS/secrets/logs | Safe defaults, redaction mechanics, tests | Threat model and acceptance | +| SQLite/SQLx | Transactions, migrations, concurrency/crash tests | Schema/data architecture review | +| Dependencies/SBOM/licenses | Generate exact reports/artifacts | Exceptions, license/advisory disposition | +| Release/CI | Rust build/package configuration and local proof | CI topology, signing identity, publication | +| Quality | Acceptance-linked implementation evidence | Final PRD implementation audit | + +## Open decisions for the user/orchestrator + +1. Exact supported OS/architecture/install matrix and minimum OS/glibc baselines. +2. Whether the initial toolchain pins current stable or a selected older stable after the dependency graph exists; no evidence supports claiming an MSRV before that graph is tested. +3. Required power-loss durability: WAL `FULL`, WAL `NORMAL`, or another documented contract. +4. Maximum writer wait/busy timeout and user-visible contention behavior. +5. Exact state/event schema for visible output, tool calls, reservation, replay prohibition, and safe-turn promotion. +6. Whether the optional TUI is inside the first executable milestone. +7. Release signing identity/attestation platform and which installer formats are authorized. +8. Quantitative pass/fail thresholds for the eight-hour soak (RSS slope, WAL growth, task/handle counts, throughput/error rate). + +## Tool provenance limitation + +The research packet uses the configured Context7 service plus current direct official/upstream documentation retrieval. No raw web-crawl JSON exists; this limitation is explicit so Forge does not mistake the corpus for a web-crawl corpus. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/index.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/index.md new file mode 100644 index 00000000..9636d31a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/index.md @@ -0,0 +1,64 @@ +# Research Index: rust-stinger + +Generated by scripture-historian. Updated after every source-file write. + +Snapshot: 2026-07-24. Version-sensitive values in this packet are evidence snapshots, not timeless defaults; revalidate at the point of use. + +| File | Source type | Authority | Relevance | Topic | +|---|---|---|---|---| +| `rust-cargo/2026-07-24-rust-release-1-97.md` | changelog | official | critical | toolchain | +| `rust-cargo/2026-07-24-cargo-rust-version.md` | official-docs | official | critical | msrv | +| `rust-cargo/2026-07-24-cargo-resolver-v3.md` | official-docs | official | critical | resolver | +| `rust-cargo/2026-07-24-cargo-features.md` | official-docs | official | high | features | +| `rust-cargo/2026-07-24-platform-support.md` | official-docs | official | critical | targets | +| `rust-cargo/2026-07-24-cargo-ci-msrv.md` | official-docs | official | high | ci | +| `rust-cargo/2026-07-24-clippy-ci.md` | official-docs | official | high | linting | +| `rust-cargo/2026-07-24-unsafe-rust.md` | official-docs | official | high | unsafe | +| `async/2026-07-24-tokio-release-policy.md` | changelog | official | critical | tokio | +| `async/2026-07-24-tokio-graceful-shutdown.md` | official-docs | official | critical | shutdown | +| `async/2026-07-24-tokio-mpsc.md` | official-docs | official | critical | backpressure | +| `async/2026-07-24-tokio-select-cancellation.md` | official-docs | official | critical | cancellation | +| `async/2026-07-24-tokio-send-reserve.md` | official-docs | official | high | permits | +| `async/2026-07-24-tower-service-readiness.md` | official-docs | official | critical | readiness | +| `async/2026-07-24-tower-service-builder.md` | official-docs | official | high | middleware | +| `async/2026-07-24-axum-graceful-shutdown.md` | official-docs | official | critical | axum | +| `async/2026-07-24-axum-service-testing.md` | official-docs | official | high | testing | +| `async/2026-07-24-axum-streaming-body.md` | official-docs | official | critical | streaming | +| `persistence/2026-07-24-sqlite-transactions.md` | official-docs | official | critical | transactions | +| `persistence/2026-07-24-sqlite-wal.md` | official-docs | official | critical | wal | +| `persistence/2026-07-24-sqlite-atomic-commit.md` | official-docs | official | critical | recovery | +| `persistence/2026-07-24-sqlite-pragma-durability.md` | official-docs | official | critical | durability | +| `persistence/2026-07-24-sqlx-connect-options.md` | official-docs | official | critical | sqlx | +| `persistence/2026-07-24-sqlx-migrations-queries.md` | official-docs | official | high | migrations | +| `persistence/2026-07-24-sqlx-custom-transactions.md` | official-docs | official | critical | locking | +| `boundaries/2026-07-24-serde-enum-representations.md` | official-docs | official | critical | serde | +| `boundaries/2026-07-24-serde-container-attributes.md` | official-docs | official | high | validation | +| `boundaries/2026-07-24-thiserror.md` | official-docs | official | high | errors | +| `observability/2026-07-24-tracing-instrument.md` | official-docs | official | critical | tracing | +| `observability/2026-07-24-tracing-subscriber.md` | official-docs | official | high | subscriber | +| `security/2026-07-24-secrecy.md` | official-docs | official | high | secrets | +| `security/2026-07-24-rustls-config-builder.md` | official-docs | official | critical | tls | +| `security/2026-07-24-rustls-verification-markers.md` | official-docs | official | critical | typestate | +| `cli-tui/2026-07-24-clap-parser.md` | official-docs | official | high | clap | +| `cli-tui/2026-07-24-clap-errors.md` | official-docs | official | high | exits | +| `cli-tui/2026-07-24-ratatui-lifecycle.md` | official-docs | official | high | terminal | +| `cli-tui/2026-07-24-ratatui-test-backend.md` | official-docs | official | high | rendering | +| `cli-tui/2026-07-24-ratatui-architecture.md` | official-docs | official | medium | tui | +| `testing/2026-07-24-proptest-state-machines.md` | official-docs | official | critical | proptest | +| `testing/2026-07-24-proptest-index.md` | official-docs | official | high | properties | +| `testing/2026-07-24-loom.md` | official-docs | official | critical | loom | +| `testing/2026-07-24-tokio-time-testing.md` | official-docs | official | critical | faketime | +| `testing/2026-07-24-nextest.md` | official-docs | official | high | nextest | +| `testing/2026-07-24-nextest-retries.md` | official-docs | official | high | flakiness | +| `testing/2026-07-24-criterion-analysis.md` | official-docs | official | high | benchmark | +| `supply-chain/2026-07-24-cargo-dist-config.md` | official-docs | official | critical | packaging | +| `supply-chain/2026-07-24-cargo-dist-attestations.md` | official-docs | official | high | provenance | +| `supply-chain/2026-07-24-cargo-cyclonedx.md` | changelog | official | critical | sbom | +| `supply-chain/2026-07-24-cargo-auditable.md` | github-readme | practitioner | high | auditability | +| `supply-chain/2026-07-24-cargo-deny-checks.md` | official-docs | official | high | policy | +| `supply-chain/2026-07-24-cargo-deny-license-limitations.md` | official-docs | official | high | licenses | +| `supply-chain/2026-07-24-rustsec.md` | official-docs | official | critical | advisories | +| `supply-chain/2026-07-24-cargo-audit.md` | github-readme | official | critical | cargo-audit | +| `supply-chain/2026-07-24-sigstore-cosign-blob.md` | official-docs | official | high | signing | +| `supply-chain/2026-07-24-cargo-sbom-unstable.md` | official-docs | official | high | cargo-sbom | +| `supply-chain/2026-07-24-cargo-package-verification.md` | official-docs | official | high | package | diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md new file mode 100644 index 00000000..95f928d0 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/attr.instrument.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tracing +stinger: rust-stinger +--- + +# `tracing::instrument` field capture + +## Summary +`#[instrument]` records function arguments by default, using `Value` or `Debug`. `skip` and `skip_all` explicitly exclude arguments, and replacement fields can record safe identifiers. This default makes unreviewed instrumentation a direct secret/prompt leakage risk at sensitive boundaries. + +## Key quotations / statistics +- "By default, all arguments to the function are included as fields" +- `skip_all` can "skip all arguments" + +## Version/date caveat +Retrieved against tracing 0.1.44; macro capture policy is current at access time. + +## Annotations for stinger-forge +- Critical source for a `skip_all`-first rule on provider, prompt, credential, and SQL boundaries. +- Add explicit allowlisted correlation/state fields rather than relying on Debug. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md new file mode 100644 index 00000000..0cffcd7a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: subscriber +stinger: rust-stinger +--- + +# tracing library/subscriber ownership + +## Summary +Tracing libraries emit spans/events but executables install subscribers that collect and format them. The docs warn libraries not to set a global default because that conflicts with downstream executables. This creates a clean crate boundary: libraries describe structured events; daemon/CLI binaries own filtering, sinks, and output format. + +## Key quotations / statistics +- "Libraries should link only to the `tracing` crate" +- "libraries should not call `set_global_default()`" + +## Version/date caveat +Tracing 0.1.44 documentation; subscriber features and ecosystem layers vary independently. + +## Annotations for stinger-forge +- Grounds observability dependency direction and binary-owned initialization. +- Security/redaction review remains a peer gate even when field ownership is correct. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md new file mode 100644 index 00000000..1a2dfba4 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/atomiccommit.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: recovery +stinger: rust-stinger +--- + +# SQLite atomic commit and crash recovery + +## Summary +SQLite documents how rollback journals provide atomic commit across process, OS, and power failures, including hot-journal recovery. It also documents assumptions and failure modes around filesystem locking, sync behavior, file renames, and deletion of journals. SQLite's own confidence rests on fault-injecting VFS crash tests, not code inspection alone. + +## Key quotations / statistics +- "either all database changes within a single transaction occur or none" +- "crash tests ... simulate incomplete sector writes" + +## Version/date caveat +This page primarily describes rollback-journal mode; WAL atomicity uses a different mechanism documented separately. + +## Annotations for stinger-forge +- Strong evidence for crash/restart and filesystem-fault tests around local state. +- Preserve database, WAL, SHM, and journal files together during recovery/support operations. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md new file mode 100644 index 00000000..cfe565e1 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md @@ -0,0 +1,26 @@ +--- +source_url: https://sqlite.org/pragma.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: durability +stinger: rust-stinger +--- + +# SQLite PRAGMA durability controls + +## Summary +SQLite's PRAGMA reference defines `journal_mode`, `synchronous`, `busy_timeout`, foreign-key enforcement, and checkpoint controls. The durability contract changes by journal mode and synchronous level; `OFF` does not sync, while WAL plus `NORMAL` trades away recent-transaction durability on power loss. + +## Key quotations / statistics +- "you lose durability across power loss with synchronous NORMAL in WAL mode" +- With `synchronous=OFF`, SQLite proceeds "without syncing" + +## Version/date caveat +Official reference retrieved 2026-07-24; platform VFS behavior can still weaken guarantees. + +## Annotations for stinger-forge +- Use to require explicit, tested connection PRAGMAs rather than driver defaults. +- Final durability policy is an architecture/product decision and should be recorded. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md new file mode 100644 index 00000000..02a13e90 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/lang_transaction.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: transactions +stinger: rust-stinger +--- + +# SQLite transaction semantics + +## Summary +SQLite permits multiple simultaneous readers but only one write transaction. `BEGIN DEFERRED` delays lock acquisition and can fail when upgrading a read to a write; `BEGIN IMMEDIATE` attempts to acquire the write transaction at the start and returns `SQLITE_BUSY` if another writer is active. Nested `BEGIN` transactions are not supported. + +## Key quotations / statistics +- "Transactions created using BEGIN...COMMIT do not nest." +- "BEGIN IMMEDIATE might fail with SQLITE_BUSY" + +## Version/date caveat +SQLite official page published within the six-month research window. Exact busy behavior also depends on connection busy timeout and transaction duration. + +## Annotations for stinger-forge +- Critical for reservation/reconciliation write serialization and busy-retry design. +- Supports acquiring write intent before reading budget state when the operation must be atomic. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md new file mode 100644 index 00000000..b3143ac4 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/wal.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: wal +stinger: rust-stinger +--- + +# SQLite write-ahead logging + +## Summary +WAL mode separates writes from checkpoints, permits readers alongside a writer, and persists as a database property. Automatic checkpoints occur at a default threshold of 1000 pages. Long readers can prevent checkpoint completion and grow the WAL; `synchronous=NORMAL` can lose recent committed transactions after power loss even while preserving database consistency. + +## Key quotations / statistics +- "By default, SQLite does a checkpoint automatically" at 1000 pages. +- With `synchronous=NORMAL`, "transactions are no longer durable" across power failure. + +## Version/date caveat +Official SQLite page updated in the research window; durability claims depend on VFS/filesystem correctness. + +## Annotations for stinger-forge +- Grounds explicit journal, synchronous, checkpoint, and reader-lifetime choices. +- Contradicts any blanket claim that WAL plus NORMAL implies full power-loss durability. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md new file mode 100644 index 00000000..dcc861a0 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/sqlite/struct.SqliteConnectOptions.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: sqlx +stinger: rust-stinger +--- + +# SQLx SQLite connection options + +## Summary +`SqliteConnectOptions` exposes journal, locking, synchronous, busy-timeout, foreign-key, and statement settings. SQLx deliberately does not select a journal mode by default; WAL persists in the database and switching away from it may require an exclusive lock. The default busy timeout is five seconds. + +## Key quotations / statistics +- "SQLx does not set a journal mode by default" +- "The default busy timeout is 5 seconds." + +## Version/date caveat +SQLx latest docs at retrieval (the docs index reported 0.9.0). Verify APIs against the actually pinned SQLx release. + +## Annotations for stinger-forge +- Grounds a single audited connection-options builder and startup verification of effective PRAGMAs. +- Prevent per-connection configuration drift in pools. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md new file mode 100644 index 00000000..b3ef08b7 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/trait.Connection.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: locking +stinger: rust-stinger +--- + +# SQLx custom transaction start + +## Summary +SQLx 0.9.0 exposes `Connection::begin_with` to begin a tracked transaction using a database-specific statement. This permits SQLite `BEGIN IMMEDIATE` while retaining the `Transaction` commit/rollback API. The function rejects statements that do not actually enter a transaction, which is safer than issuing an unrelated raw statement and assuming tracking. + +## Key quotations / statistics +- "Begin a new transaction with a custom statement." +- It errors if the statement "does not put the connection into a transaction." + +## Version/date caveat +This API appears in SQLx 0.9.0; SQLx 0.8-era projects need a version-specific alternative and should not copy the call blindly. + +## Annotations for stinger-forge +- Resolves the primary SQLx mechanism for write-intent acquisition before budget reads. +- Pair with bounded busy handling, conditional updates, and concurrency/crash tests. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md new file mode 100644 index 00000000..74a7899d --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: migrations +stinger: rust-stinger +--- + +# SQLx query macros and embedded migrations + +## Summary +SQLx provides compile-time checked query macros and `migrate!`, which embeds migrations into the binary. Query macros require a build-time schema connection or checked-in `.sqlx` offline metadata. Embedded migrations improve deployability but do not replace forward-only migration policy, crash tests, and schema-version compatibility checks. + +## Key quotations / statistics +- "The `migrate!` macro embeds migrations into the binary" +- "The `query!` macro allows for statically checked SQL queries" + +## Version/date caveat +SQLx latest docs at retrieval; offline metadata commands and migration macro rebuild behavior vary by release/build system. + +## Annotations for stinger-forge +- Supports compile-checked repository queries and migration packaging tests. +- Database schema review remains a peer boundary; this source covers Rust integration mechanics. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-plan.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-plan.md new file mode 100644 index 00000000..7c00d1ca --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-plan.md @@ -0,0 +1,91 @@ +# Research Plan: rust-stinger + +- **Depth tier:** deep +- **Time window:** 2026-07-24 back to 2026-01-24 (6 months) +- **Page budget target:** 1,000 page-equivalents across official documentation sets, upstream repositories, release notes, and standards/tooling references +- **Source breadth target:** official language/toolchain documentation, upstream crate documentation, upstream GitHub repositories, SQLite specifications, security advisories, release/changelog material, standards/provenance specifications +- **Discovery caveat:** The initial queries below are reconstructed from the Command Brief's primary research targets and research questions. Research used Context7 documentation retrieval and direct official/upstream pages; this limitation is preserved in the final summary. + +## Initial queries (derived from the Command Brief) + +- "Rust Cargo workspace architecture MSRV feature unification platform support 2026" +- "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" +- "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" +- "Rust typed state machines replay prohibition safe promotion error boundaries 2026" +- "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" +- "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" +- "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" +- "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +## Expansion queries + +### Branch from "Rust Cargo workspace architecture MSRV feature unification platform support 2026" + +- "Cargo resolver version 3 workspace dependency inheritance feature unification official" +- "Rust MSRV policy rust-version Cargo official platform support tier policy" +- "Cargo workspace compile time crate boundaries feature flags official guidance" +- "Rust API Guidelines unsafe code guidelines Clippy rustfmt official" + +### Branch from "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" + +- "Tokio task cancellation safety JoinSet CancellationToken graceful shutdown official" +- "Tokio bounded mpsc backpressure reserve Permit shutdown channel official" +- "Axum with_graceful_shutdown streaming Body cancellation official" +- "Tower Service readiness load shed concurrency limit timeout buffer backpressure official" +- "Tokio time pause advance deterministic tests tracing official" + +### Branch from "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" + +- "SQLite BEGIN IMMEDIATE transaction locking WAL busy timeout synchronous official" +- "SQLite atomic commit crash recovery WAL checkpoint durability official" +- "SQLx SQLite transaction acquire begin immediate migrations official" +- "SQLite concurrent reservation budget oversubscription conditional update RETURNING official" +- "SQLx offline mode compile checked queries migrations locking upstream" + +### Branch from "Rust typed state machines replay prohibition safe promotion error boundaries 2026" + +- "Rust enum typestate state machine exhaustive matching official" +- "Rust ownership newtype sealed traits visibility architecture boundaries official" +- "Serde tagged enums deny unknown fields boundary validation official" +- "thiserror source transparent structured error official" + +### Branch from "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" + +- "tracing instrument skip fields redaction EnvFilter JSON official" +- "secrecy SecretString expose_secret Debug redaction official" +- "rustls dangerous configuration certificate verification official" +- "Rust TLS certificate roots platform verifier rustls official" + +### Branch from "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" + +- "Clap derive value enum exit codes JSON output shell completion official" +- "Clap error handling try_parse_from CommandFactory official" +- "Ratatui terminal init restore panic hook test backend official" +- "Ratatui snapshot testing event loop cancellation official" + +### Branch from "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" + +- "proptest state machine strategy shrinking persistence official" +- "Loom model concurrency atomics Arc Mutex limitations official" +- "cargo-nextest retries slow timeout archive junit official" +- "Criterion benchmark statistical confidence regression official" +- "Tokio test start_paused timeout cancellation fake server soak evidence official" + +### Branch from "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +- "cargo-dist installers checksums GitHub releases provenance official" +- "cargo-cyclonedx SBOM Rust official upstream" +- "cargo-auditable binary dependency metadata official upstream" +- "cargo-deny advisories licenses bans sources official" +- "RustSec advisory database cargo-audit withdrawn unmaintained official" +- "Sigstore cosign sign blob attest SBOM keyless official" + +## Research order and rationale + +1. Establish language, Cargo, MSRV, and platform constraints because every later recommendation depends on the supported compiler and target contract. +2. Resolve runtime/service ownership and failure behavior across Tokio, Axum, and Tower. +3. Resolve SQLite/SQLx transaction, locking, and crash-durability semantics. +4. Collect type-boundary, serialization, error, observability, secret, and TLS sources. +5. Collect operator-surface sources for Clap and Ratatui. +6. Collect deterministic, property, model-concurrency, benchmark, and soak-test evidence. +7. Close with packaging, provenance, SBOM, signature, advisory, and release evidence while preserving dependency/release/security peer ownership. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-summary.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-summary.md new file mode 100644 index 00000000..f8caa1bb --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/research-summary.md @@ -0,0 +1,68 @@ +# Research Summary: rust-stinger + +- **Depth tier consumed:** deep, completed as a concise authoritative packet rather than an open-ended crawl +- **Time window:** 2026-01-24 through 2026-07-24 (6 months), with stable canonical reference pages used where the governing specification predates the window +- **Source notes:** 56 +- **Research/control artifacts:** 4 (`research-plan.md`, `index.md`, `evidence-synthesis.md`, `research-summary.md`) +- **Total Markdown files:** 60 +- **Primary-source posture:** 55 official/upstream sources and 1 upstream practitioner-maintained GitHub project note (`cargo-auditable`); no community forum/Reddit source was needed + +## Files by subfolder + +| Subfolder | Source files | +|---|---:| +| `async/` | 10 | +| `boundaries/` | 3 | +| `cli-tui/` | 5 | +| `observability/` | 2 | +| `persistence/` | 7 | +| `rust-cargo/` | 8 | +| `security/` | 3 | +| `supply-chain/` | 11 | +| `testing/` | 7 | +| **Total** | **56** | + +## Coverage against the Command Brief + +- Rust/Cargo workspace architecture, feature unification, MSRV, toolchain, platform tiers, Clippy, and unsafe policy: covered. +- Tokio/Axum/Tower task ownership, cancellation safety, bounded backpressure, readiness, graceful shutdown, streaming bodies, and service testing: covered. +- SQLite/SQLx transactions, `BEGIN IMMEDIATE`, busy behavior, WAL, checkpointing, durability, atomic commit/crash recovery, connection options, compile-checked queries, and migrations: covered. +- Typed boundaries/state machines, Serde strictness/tagging, structured errors, non-forgeable verification markers: covered. +- tracing/subscriber ownership, secret wrappers, rustls safe/dangerous configuration and typestate: covered. +- Clap CLI parsing/exit behavior and Ratatui lifecycle/test architecture: covered. +- proptest, Loom, deterministic Tokio time, nextest, Criterion, failure/concurrency/migration/fake-provider and eight-hour-soak evidence model: covered. +- cargo-dist, cargo-cyclonedx, cargo-auditable, cargo-deny, RustSec/cargo-audit, Cargo SBOM precursors/package verification, and Sigstore/Cosign: covered with peer-boundary caveats. + +## Five most influential sources + +1. [`async/2026-07-24-tokio-select-cancellation.md`](async/2026-07-24-tokio-select-cancellation.md) — establishes that cancellation safety is an operation-level property and identifies the central replay/data-loss review boundary. +2. [`async/2026-07-24-tower-service-readiness.md`](async/2026-07-24-tower-service-readiness.md) — makes backpressure a resource-reservation contract and exposes the readiness-to-call cancellation edge. +3. [`persistence/2026-07-24-sqlite-transactions.md`](persistence/2026-07-24-sqlite-transactions.md) plus [`persistence/2026-07-24-sqlx-custom-transactions.md`](persistence/2026-07-24-sqlx-custom-transactions.md) — together establish the one-writer rule and the SQLx 0.9 mechanism for tracked `BEGIN IMMEDIATE` transactions. +4. [`security/2026-07-24-rustls-verification-markers.md`](security/2026-07-24-rustls-verification-markers.md) — supplies upstream precedent for private proof tokens preventing skipped safety checks. +5. [`testing/2026-07-24-proptest-state-machines.md`](testing/2026-07-24-proptest-state-machines.md) — supplies the reference-model, invariant, shrinking, and regression-seed pattern for quota/breaker/promotion state. + +## Open questions that survived research + +- Final platform/installer matrix and minimum OS baselines. +- Declared MSRV after the real dependency graph and features exist. +- Required SQLite power-loss durability and busy/contended-write UX. +- Final durable state/event schema for replay prohibition and promotion. +- TUI inclusion in the first milestone. +- Signing/attestation identity and publication authorization. +- Numeric eight-hour-soak thresholds. + +## Sources Forge should re-fetch at build time + +- Rust release index and platform support (toolchain/target drift). +- Tokio current/LTS policy (1.53.1 and 1.51.x were current at retrieval). +- SQLx `Connection::begin_with` and migration/query docs against the selected SQLx version. +- rustls stable docs to avoid using 0.24 development APIs. +- cargo-dist configuration/changelog and GitHub attestation eligibility. +- RustSec advisory database immediately before any release recommendation. + +## Blocked or incomplete research + +- No subject area is blocked. +- Raw web-crawl JSON and ranked discovery records were not produced. Context7 plus direct official/upstream retrieval was used; the limitation is recorded in the plan and synthesis. +- No source establishes a universal off-the-shelf eight-hour Rust soak harness. The synthesis therefore records a composable evidence model and leaves numeric thresholds to the product/release owners. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md new file mode 100644 index 00000000..ae859eb9 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/guide/continuous-integration.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: ci +stinger: rust-stinger +--- + +# Cargo continuous integration guidance + +## Summary +Cargo's CI guide explicitly recommends verifying `rust-version`, testing dependency freshness, and pinning the compiler when warnings are denied because new toolchains can add warnings. It illustrates `cargo hack check --rust-version --workspace --all-targets` and a full-feature Clippy job. + +## Key quotations / statistics +- "When publishing packages that specify `rust-version`, it is important to verify the correctness of that field." +- "CI can fail due to new toolchain versions because there are limited compatibility guarantees around warnings." + +## Version/date caveat +The guide names third-party tools as examples, not as Rust project guarantees. + +## Annotations for stinger-forge +- Grounds separate pinned-toolchain, MSRV, latest-dependency, and target/feature checks. +- Peer boundary: CI topology remains the release/DevOps specialist's decision. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md new file mode 100644 index 00000000..f521634a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/features.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: features +stinger: rust-stinger +--- + +# Cargo features and feature unification + +## Summary +Cargo features are additive and can be unified across dependency paths. Resolver v2 and later avoid several unwanted unifications for target-specific, build/proc-macro, and inactive dev dependencies, but feature coupling still requires deliberate crate boundaries and CI combinations. Default features are part of the public dependency contract unless callers disable them consistently. + +## Key quotations / statistics +- "Features should be additive." +- Resolver v2 "avoids unifying features" across several dependency categories. + +## Version/date caveat +Stable Cargo documentation; individual dependency feature sets can change without a workspace architecture change. + +## Annotations for stinger-forge +- Supports feature hygiene, `cargo tree -e features`, and targeted feature-matrix checks. +- Relevant to keeping TUI/provider/TLS capabilities out of core crates by default. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md new file mode 100644 index 00000000..d1fcb298 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/resolver.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: resolver +stinger: rust-stinger +--- + +# Cargo dependency resolver + +## Summary +Cargo resolver version 3 is the Rust 2024 default and changes incompatible-Rust-version handling from `allow` to `fallback`. Resolver choice is global to the top-level workspace and dependency manifests cannot override it; virtual workspaces must set it explicitly. This is a workspace architecture constraint, not a per-crate preference. + +## Key quotations / statistics +- "`3` (`edition = `2024` default, requires Rust 1.84+)" +- "The resolver is a global option that affects the entire workspace." + +## Version/date caveat +Stable Cargo docs as of retrieval. Resolver v3 sets selection behavior but does not prove every selected dependency actually honors its MSRV. + +## Annotations for stinger-forge +- Inform the workspace manifest checklist and feature/MSRV audit. +- Warn that a virtual workspace must explicitly declare `resolver = "3"`. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md new file mode 100644 index 00000000..a377739d --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/rust-version.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: msrv +stinger: rust-stinger +--- + +# Cargo `rust-version` + +## Summary +Cargo's `rust-version` field declares the minimum supported compiler and participates in diagnostics and dependency resolution. Workspace members can have different policies, but shared dependencies and feature unification mean the lowest supported member can constrain the whole workspace. The declared value needs CI proof rather than being treated as descriptive metadata. + +## Key quotations / statistics +- "The resolver may take Rust version into account when picking dependencies." +- "All functionality, including binaries and API, are available on the supported Rust versions under every feature." + +## Version/date caveat +Stable Cargo documentation retrieved against the Rust 1.97 release line; resolver behavior depends on workspace resolver selection. + +## Annotations for stinger-forge +- Grounds MSRV declaration and verification rules. +- Supports testing all public feature combinations claimed to work at MSRV. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md new file mode 100644 index 00000000..1155d39a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/clippy/continuous_integration/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: linting +stinger: rust-stinger +--- + +# Clippy in continuous integration + +## Summary +Official Clippy guidance recommends treating Clippy warnings as CI failures and using the same toolchain as compilation for compatibility. Because new lints appear over time, a pinned toolchain or an explicit upgrade process prevents unrelated stable updates from unexpectedly breaking release branches. + +## Key quotations / statistics +- "It is recommended to run Clippy on CI with `-Dwarnings`." +- "use Clippy from the same toolchain, that you use for compiling your crate" + +## Version/date caveat +Lint inventories evolve with the compiler; a clean result is toolchain-specific. + +## Annotations for stinger-forge +- Supports the standard Rust verification gate and toolchain pinning. +- Avoid enabling all `restriction` lints indiscriminately; the Clippy index warns they may conflict. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md new file mode 100644 index 00000000..b1fb7d7a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/rustc/platform-support.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: targets +stinger: rust-stinger +--- + +# Rust platform support + +## Summary +Rust classifies targets into three tiers with materially different build and test guarantees. Tier 1 targets build and pass tests in Rust CI; Tier 2 targets are guaranteed to build but may not be tested. A product target matrix therefore needs its own runtime/install/uninstall proof even when the compiler labels a target supported. + +## Key quotations / statistics +- "Tier 1 targets can be thought of as `guaranteed to work`." +- Tier 2 targets "can be thought of as `guaranteed to build`." + +## Version/date caveat +Target tiers and OS baselines can change between Rust releases; re-check during release planning. + +## Annotations for stinger-forge +- Use to separate compiler support from product support evidence. +- Supports explicit macOS/Linux/Windows target triples and host-tool requirements. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md new file mode 100644 index 00000000..46def630 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md @@ -0,0 +1,26 @@ +--- +source_url: https://blog.rust-lang.org/releases/ +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: toolchain +stinger: rust-stinger +--- + +# Rust release announcements + +## Summary +The official release index records Rust 1.97.1 on 2026-07-16 and Rust 1.97.0 on 2026-07-09. It provides the current stable anchor for any 2026 toolchain discussion, but it does not itself establish the product's MSRV; that remains a deliberate compatibility decision verified independently. + +## Key quotations / statistics +- "July 16 | Announcing Rust 1.97.1" +- 2026 releases listed in the six-month window: 1.93.0 through 1.97.1. + +## Version/date caveat +Current stable at retrieval time; Rust releases on a regular cadence, so re-check immediately before freezing a toolchain. + +## Annotations for stinger-forge +- Use as the current-version anchor in toolchain/MSRV guidance. +- Distinguish "current stable" from the separately declared `package.rust-version` and CI-tested MSRV. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md new file mode 100644 index 00000000..cf491309 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: unsafe +stinger: rust-stinger +--- + +# Unsafe Rust + +## Summary +The Rust Book defines the five operations requiring `unsafe`, stresses that unsafe code transfers proof obligations to the programmer, and recommends keeping unsafe blocks small behind safe abstractions. This supports a default `forbid(unsafe_code)` posture with narrowly reviewed exceptions. + +## Key quotations / statistics +- "Keep `unsafe` blocks small" +- "wrapping unsafe code in a safe function is a common abstraction" + +## Version/date caveat +The current Book uses the Rust 2024 edition. Low-level memory-model details must be checked against the Reference/Nomicon, not inferred from examples. + +## Annotations for stinger-forge +- Grounds unsafe inventory, documented invariants, and targeted tests. +- Note that the old Unsafe Code Guidelines reference describes itself as largely abandoned. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md new file mode 100644 index 00000000..b7df5e59 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tls +stinger: rust-stinger +--- + +# rustls configuration typestate + +## Summary +rustls 0.23.42 uses builder typestates to require protocol/provider, peer verification, and certificate decisions in order. Normal builders select safe default protocol versions; custom verifiers sit behind a deliberately dangerous API. The builder demonstrates compile-time enforcement of required configuration steps. + +## Key quotations / statistics +- "use rustls' default cryptographic provider and safe defaults" +- Builder state "ensure[s] at compile time that each required configuration item is provided exactly once" + +## Version/date caveat +The stable docs reported rustls 0.23.42; rustls.dev also exposed 0.24.0-dev.0, so do not code to development APIs accidentally. + +## Annotations for stinger-forge +- Strong upstream example for typestate and TLS-safe defaults. +- Custom certificate verification requires explicit Security review. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md new file mode 100644 index 00000000..b92aa6da --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustls.dev/src/rustls/verify.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: typestate +stinger: rust-stinger +--- + +# rustls verification marker types + +## Summary +rustls uses non-constructible marker values to encode that certificate-chain and handshake-signature verification occurred before traffic state is reached. The source explicitly frames this as protection against omitted-check control flow. This is directly relevant as prior art for non-forgeable replay/promotion authorization tokens. + +## Key quotations / statistics +- "bind the fact some verification ... has taken place into protocol states" +- "compiler check that there are no `goto fail`-style elisions" + +## Version/date caveat +Source view from rustls.dev may track development rather than the pinned 0.23 release; use the pattern, not an internal type dependency. + +## Annotations for stinger-forge +- Key evidence for private constructors and capability tokens representing completed checks. +- Do not couple the router's state machine to rustls internal marker types. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-secrecy.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-secrecy.md new file mode 100644 index 00000000..c323990a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/security/2026-07-24-secrecy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/secrecy/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: secrets +stinger: rust-stinger +--- + +# secrecy secret wrappers + +## Summary +secrecy 0.10.3 wraps secret values so access requires an explicit exposure trait, reduces accidental Debug/logging/copying, and wipes supported owned values on drop. Optional Serde support permits deserialization but explicitly cannot prevent upstream deserializers from making copies. It is defense-in-depth, not a complete secret store. + +## Key quotations / statistics +- access is "only available through a special `ExposeSecret` trait" +- Serde support "doesn't guarantee ... additional copies" are not made. + +## Version/date caveat +MSRV is Rust 1.60; the project states future MSRV changes are outside SemVer guarantees but accompany a minor bump. + +## Annotations for stinger-forge +- Supports secret newtypes and narrow exposure sites. +- Secret acquisition/storage policy remains Security/platform-owned. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md new file mode 100644 index 00000000..7044e61a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rustsec/rustsec/blob/main/cargo-audit/README.md +retrieved_on: 2026-07-24 +source_type: github-readme +authority: official +relevance: critical +topic: cargo-audit +stinger: rust-stinger +--- + +# RustSec cargo-audit + +## Summary +cargo-audit checks Cargo.lock against RustSec and can inspect binaries built with cargo-auditable. Its experimental `fix` command modifies manifests, while ignore entries require application-specific justification. The README states binary scanning is incomplete for ordinary optimized binaries but accurate when auditable metadata is embedded. + +## Key quotations / statistics +- "Audit your dependencies for crates with security vulnerabilities" +- Without auditable metadata it may miss "roughly half of the Rust dependencies" + +## Version/date caveat +README currently requires Rust 1.74 or later; pin cargo-audit independently from the product MSRV. + +## Annotations for stinger-forge +- Supports lockfile and shipped-binary audit evidence. +- Never run automatic fix as part of an evidence-only release gate without review. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md new file mode 100644 index 00000000..675c4a35 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rust-secure-code/cargo-auditable +retrieved_on: 2026-07-24 +source_type: github-readme +authority: practitioner +relevance: high +topic: auditability +stinger: rust-stinger +--- + +# cargo-auditable + +## Summary +cargo-auditable embeds Cargo dependency version information in production binaries so deployed artifacts can be scanned later. It integrates with cargo-dist and experimental Cargo SBOM precursor output. The project recommends recording artifact hash, Cargo.lock, compiler/LLVM versions, and build date alongside binaries because embedded dependency metadata alone is not complete provenance. + +## Key quotations / statistics +- "Make production Rust binaries auditable" +- record "the hash of every executable" with build metadata. + +## Version/date caveat +The upstream README mentions nightly `-Z sbom`; nightly Cargo features are not a stable release foundation without explicit approval. + +## Annotations for stinger-forge +- Supports artifact-to-lockfile traceability and post-build `cargo audit bin` checks. +- Treat it as complementary to external SBOMs and attestations. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md new file mode 100644 index 00000000..55fe7b91 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/cargo-cyclonedx/0.5.9/source/CHANGELOG.md +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: sbom +stinger: rust-stinger +--- + +# cargo-cyclonedx 0.5.9 changelog + +## Summary +cargo-cyclonedx 0.5.9, released 2026-03-19, added `SOURCE_DATE_EPOCH` support for reproducible SBOM timestamps and honors `CARGO_BUILD_TARGET` for target identity. It also fixed sparse-registry and package-URL correctness. SBOM generation still requires validation against the shipped artifact and selected features/target. + +## Key quotations / statistics +- "Support for the `SOURCE_DATE_EPOCH` environment variable" +- "`CARGO_BUILD_TARGET` ... determine[s] the target platform" + +## Version/date caveat +Version 0.5.9 is the current release reported at retrieval; coverage/format support should be checked before freezing. + +## Annotations for stinger-forge +- Strong 2026 source for reproducible target-specific CycloneDX generation. +- Final SBOM completeness/policy judgment belongs to dependency/release peers. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md new file mode 100644 index 00000000..fc653b53 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: policy +stinger: rust-stinger +--- + +# cargo-deny checks + +## Summary +cargo-deny evaluates licenses, duplicate/banned crates, advisories/yanks, and dependency sources from the resolved crate graph. Running the umbrella check uses defaults for sections not configured, so a repository needs an explicit reviewed policy rather than assuming tool defaults match its legal/security constraints. + +## Key quotations / statistics +- Checks include "licenses", "bans", "advisories", and "sources". +- Advisories cover vulnerabilities, unmaintained crates, and yanked versions. + +## Version/date caveat +Policy/schema changes across cargo-deny versions; pin both tool and configuration version. + +## Annotations for stinger-forge +- Supports Rust-side evidence generation for dependency peer review. +- The Bee may run/report it but must not own final license/advisory exceptions. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md new file mode 100644 index 00000000..7472fa31 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/licenses/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: licenses +stinger: rust-stinger +--- + +# cargo-deny license check limitations + +## Summary +cargo-deny evaluates SPDX expressions and license files but explicitly cannot exhaustively prove a crate's legal licensing. It trusts manifest/package evidence and documents absence, mismatch, and unconventional-placement gaps. Clarifications are hash-bound evidence, not permanent blanket waivers. + +## Key quotations / statistics +- "does not exhaustively search the entirety of the source code" +- It makes a "good-faith assumption" that crates define licensing correctly. + +## Version/date caveat +License-list versions and cargo-deny detection behavior evolve; legal review cannot be replaced by a passing scan. + +## Annotations for stinger-forge +- Prevent overclaiming `cargo deny` as legal clearance. +- Route exceptions and notices to dependency/legal/release peers with exact evidence. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md new file mode 100644 index 00000000..3ff88414 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/supplychain-security/attestations/github.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: provenance +stinger: rust-stinger +--- + +# cargo-dist GitHub artifact attestations + +## Summary +dist can enable GitHub artifact attestations, creating verifiable provenance linked to GitHub Actions and Sigstore. The feature is disabled by default and has repository/plan limitations. Verification uses `gh attestation verify`, so evidence must include both generation and consumer verification transcripts. + +## Key quotations / statistics +- "Artifact Attestations is disabled by default" +- Verification is supported via "`gh attestation verify`" + +## Version/date caveat +The page labels GitHub Artifact Attestations public beta and records eligibility constraints that may change. + +## Annotations for stinger-forge +- Supports provenance as an explicit opt-in release gate, not an assumed dist feature. +- Signing identity/workflow permissions remain release/security peer concerns. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md new file mode 100644 index 00000000..b239d4fa --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/reference/config.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: packaging +stinger: rust-stinger +--- + +# cargo-dist artifact and installer configuration + +## Summary +cargo-dist configures target builds, archives, checksums, source tarballs, extra artifacts, and shell/PowerShell/npm/Homebrew/MSI installers. It can integrate cargo-auditable and cargo-cyclonedx. Checksums are unsigned integrity values; the docs explicitly describe stronger signed checksums as future work. + +## Key quotations / statistics +- Default checksum is "sha256". +- "Future work is planned to support more robust signed checksums." + +## Version/date caveat +Current docs include settings introduced through dist 0.31-era behavior; pin the generator because generated workflows/installers change. + +## Annotations for stinger-forge +- Grounds release manifest, artifact naming, installer matrix, and checksum evidence. +- Release topology/publication/signing authorization remains with the release peer. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md new file mode 100644 index 00000000..91f1b2d0 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/commands/cargo-package.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: package +stinger: rust-stinger +--- + +# Cargo package verification + +## Summary +`cargo package` builds a distributable crate archive, lists controlled contents, injects best-effort VCS metadata, and rebuilds the extracted package to verify a clean package. The VCS metadata does not prove source provenance, and `--no-verify`/`--allow-dirty` weaken evidence. + +## Key quotations / statistics +- It rebuilds "from scratch" from the package. +- "the provenance of the package is not verified" + +## Version/date caveat +Stable Cargo 1.97-era docs; binary release archives produced by dist have separate contents and verification. + +## Annotations for stinger-forge +- Supports package-content and clean-build checks for publishable crates. +- Do not confuse crate packaging proof with signed binary artifact provenance. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md new file mode 100644 index 00000000..e9bcda24 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/unstable.html#sbom +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: cargo-sbom +stinger: rust-stinger +--- + +# Cargo unstable SBOM precursors + +## Summary +Nightly Cargo's `-Z sbom` emits per-artifact JSON precursor files containing dependencies, target, features, and compiler data. These are inputs for SBOM tools, not complete standardized SBOMs. Because the feature is unstable and requires nightly, a stable release pipeline should treat it as supplemental unless explicitly approved. + +## Key quotations / statistics +- "generate so-called SBOM pre-cursor files" +- Files contain "dependencies, target, features and the used rustc compiler" + +## Version/date caveat +Unstable Cargo feature tracked by issue/RFC; schema and availability may change without stable guarantees. + +## Annotations for stinger-forge +- Record as optional deeper artifact evidence. +- Prefer stable cargo-cyclonedx/cargo-auditable paths for baseline release guidance. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md new file mode 100644 index 00000000..5053b24a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustsec.org/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: advisories +stinger: rust-stinger +--- + +# RustSec Advisory Database + +## Summary +RustSec is the canonical community-maintained advisory database for crates.io packages and supports Cargo.lock auditing through cargo-audit and automation. Findings are time-dependent because the database changes after a build; release evidence needs a reviewed-on timestamp and repeatable lockfile input. + +## Key quotations / statistics +- "repository of security advisories filed against Rust crates" +- Maintained by the "Rust Secure Code Working Group" + +## Version/date caveat +Advisory results are a point-in-time snapshot; re-run at release and in ongoing maintenance. + +## Annotations for stinger-forge +- Require recorded database/update time and lockfile hash with audit evidence. +- Security/dependency peers own disposition, ignore expiry, and remediation acceptance. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md new file mode 100644 index 00000000..dc01d8e6 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.sigstore.dev/cosign/signing/signing_with_blobs/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: signing +stinger: rust-stinger +--- + +# Cosign blob signing + +## Summary +Cosign signs ordinary files with keyless OIDC identities, local/KMS/hardware-backed keys, and emits a recommended bundle containing signature, certificate, and transparency-log proof. Noninteractive signing can create external effects and identity records, so it must remain an explicitly authorized release step. + +## Key quotations / statistics +- "using a bundle is the recommended way of signing a blob" +- The bundle includes "proof of transparency log inclusion" + +## Version/date caveat +Sigstore public infrastructure, identity claims, and command flags can change; capture the CLI version and verification policy. + +## Annotations for stinger-forge +- Supports signing/verification transcript requirements, not automatic invocation. +- Signing identity and publication remain peer/user-authorized boundaries. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md new file mode 100644 index 00000000..da0b82ba --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md @@ -0,0 +1,26 @@ +--- +source_url: https://bheisler.github.io/criterion.rs/book/analysis.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: benchmark +stinger: rust-stinger +--- + +# Criterion analysis process + +## Summary +Criterion performs warmup, measurement, statistical analysis, and comparison to saved baselines. It retains outliers, uses regression and bootstrap confidence intervals, and applies configurable significance/noise thresholds. Results still require a stable environment; statistical sophistication does not eliminate host noise. + +## Key quotations / statistics +- "Each benchmark ... goes through four phases" +- "outlier samples are not dropped" + +## Version/date caveat +Criterion docs reported crate 0.8.2 elsewhere in the corpus. The project warns virtualized CI can be too noisy for reliable wall-time regressions. + +## Annotations for stinger-forge +- Use for controlled local/release-host microbenchmarks and saved evidence. +- Eight-hour soak evidence is a distinct workload with invariants/resource telemetry, not a Criterion benchmark. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-loom.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-loom.md new file mode 100644 index 00000000..2745add5 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-loom.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/loom/latest/loom/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: loom +stinger: rust-stinger +--- + +# Loom concurrency model checking + +## Summary +Loom 0.7.2 deterministically explores valid thread interleavings under a modeled memory model. Code under test must use Loom replacement synchronization types; unmodeled operations are invisible. State spaces grow exponentially, so Loom is best applied to small concurrency primitives with controlled preemption bounds and separate release-mode jobs. + +## Key quotations / statistics +- "runs tests many times, permuting the possible concurrent executions" +- "All sources of non-determism must be via loom types" + +## Version/date caveat +Loom documents limitations for relaxed ordering, hidden operations, and combinatorial explosion; passing Loom is not universal concurrency proof. + +## Annotations for stinger-forge +- Use selectively for small reservation/permit/task-state primitives. +- Do not wrap ordinary database/business logic in Loom merely to claim model checking. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md new file mode 100644 index 00000000..a5d135bd --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md @@ -0,0 +1,26 @@ +--- +source_url: https://nexte.st/docs/features/retries/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: flakiness +stinger: rust-stinger +--- + +# Nextest retries and flaky results + +## Summary +Nextest labels tests that pass only after retry as flaky and can make flaky outcomes fail the profile. JUnit output distinguishes flaky and rerun failures. This supports visibility while preserving a strict default for correctness/concurrency tests. + +## Key quotations / statistics +- "If a test succeeds during a retry, the test is marked flaky." +- "Flaky test detection is integrated with nextest's JUnit support." + +## Version/date caveat +Behavior described includes versioned JUnit changes; confirm the pinned nextest release's config schema. + +## Annotations for stinger-forge +- Require `flaky-result = "fail"` for release evidence unless a peer-approved quarantine exists. +- Never use retries to mask model, migration, or cancellation races. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest.md new file mode 100644 index 00000000..394ee869 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-nextest.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.nexte.st/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: nextest +stinger: rust-stinger +--- + +# cargo-nextest capabilities + +## Summary +cargo-nextest supplies parallel test execution, per-test settings, timeouts, retries/flaky classification, archives/partitions, record/replay, and JUnit output across major platforms. It does not run doctests, which remain a separate `cargo test --doc` step. + +## Key quotations / statistics +- "Automatically retry some tests, mark them as heavy, run them serially" +- "Doctests are currently not supported" + +## Version/date caveat +Feature availability can depend on nextest version and execution platform; pin the runner used for release evidence. + +## Annotations for stinger-forge +- Grounds profiles for unit/integration/slow/soak classes and explicit doctest coverage. +- Retries must expose flakiness, not convert a nondeterministic gate into a silent pass. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md new file mode 100644 index 00000000..6f58e586 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: properties +stinger: rust-stinger +--- + +# Proptest guide + +## Summary +The upstream guide covers strategies, shrinking, failure persistence, configuration, and state-machine testing. Property tests are most useful for invariant-rich inputs and transition sequences; they supplement rather than replace example-based contract tests whose exact output is part of a public API. + +## Key quotations / statistics +- Guide sections include "Shrinking Basics" and "Failure Persistence". +- The guide includes dedicated "State Machine testing" material. + +## Version/date caveat +The guide reflects upstream main documentation; exact APIs must be checked against the pinned crate release. + +## Annotations for stinger-forge +- Supports corpus persistence and reproducible seeds as evidence artifacts. +- Define invariants and input strategies in domain/test-support crates, not production adapters. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md new file mode 100644 index 00000000..31b60956 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/state-machine.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: proptest +stinger: rust-stinger +--- + +# Proptest state-machine testing + +## Summary +Proptest state-machine testing generates sequences of valid transitions from a reference model, applies them to the system under test, checks postconditions/invariants, and shrinks failures to a minimal reproducer. It persists regression seeds. Current upstream support is sequential; concurrency behavior needs another technique such as Loom or explicit multi-client integration tests. + +## Key quotations / statistics +- "checking properties of a system under test ... against an abstract reference state machine" +- "only sequential strategy is supported" + +## Version/date caveat +State-machine support lives in the separate `proptest-state-machine` crate and may not version-lock with all proptest releases. + +## Annotations for stinger-forge +- Primary evidence for quota, reservation, reconciliation, breaker, pin, and promotion model tests. +- Pair with deterministic persistence fixtures and independent concurrency evidence. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md new file mode 100644 index 00000000..67495488 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/testing +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: faketime +stinger: rust-stinger +--- + +# Tokio deterministic time testing + +## Summary +Tokio test utilities pause the runtime clock and advance timer-driven futures when no other work can progress. `#[tokio::test(start_paused = true)]` makes backoff, timeout, breaker, pin, and promotion timing tests fast and deterministic, provided production time access is routed through Tokio time or an injected clock. + +## Key quotations / statistics +- "Pausing time has the effect that any time-related future may become ready early." +- `start_paused` requires the `test-util` feature. + +## Version/date caveat +Only Tokio's clock is paused; `std::time` and external systems do not automatically follow it. + +## Annotations for stinger-forge +- Critical source for fake-clock tests and avoiding wall-clock sleeps. +- Explicitly yield/advance and assert temporal ordering, not elapsed host time. + diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/acceptance-slice-checklist.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/acceptance-slice-checklist.md new file mode 100644 index 00000000..456968f0 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/acceptance-slice-checklist.md @@ -0,0 +1,16 @@ +# Rust acceptance slice checklist: {{slice_name}} + +- [ ] Read repository instructions, PRD/ADR/ledger, criteria, gates, and current Security/Quality evidence. +- [ ] Confirm repository/worktree and exact owned paths. +- [ ] Preserve unrelated and concurrent edits. +- [ ] Map each changed path and test to {{AC_IDS}}. +- [ ] Inventory crate/features/targets/tasks/channels/migrations/errors/config/logs/unsafe. +- [ ] Record version-sensitive decisions and revalidation points. +- [ ] Add a focused failing test before implementation. +- [ ] Prove cancellation, backpressure, retry/replay, shutdown, and cleanup where affected. +- [ ] Prove transactions, migrations, idempotency, concurrency, and crash recovery where affected. +- [ ] Use fake providers/fixtures unless a live gate is explicitly authorized. +- [ ] Run format, compile/check, Clippy, tests, docs, and affected specialized gates. +- [ ] Generate release evidence locally without signing/publishing unless authorized. +- [ ] Route Security, rerun affected checks after fixes, then route Quality. +- [ ] Report exact commands, results, external effects, limitations, blockers, and rollback/recovery. diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/implementation-handoff.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/implementation-handoff.md new file mode 100644 index 00000000..c4b6b5cc --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/implementation-handoff.md @@ -0,0 +1,53 @@ +# Rust implementation handoff: {{slice_name}} + +## Outcome + +{{what_is_now_true}} + +## Authority and scope + +- Repository/worktree: `{{absolute_path}}` +- Source authority: `{{prd_or_adr_path}}` +- Owned paths: {{owned_paths}} +- Gates consumed: {{gate_ids_or_none}} +- Concurrent/user edits preserved: {{evidence}} + +## Acceptance evidence + +- {{AC_ID}}: {{command_test_or_artifact}} — {{PASS_FAIL_BLOCKED}} + +## Changed paths + +- `{{path}}` — {{reason}} + +## Verification + +- `{{exact_command}}` — {{PASS_FAIL_BLOCKED}} + +## Safety and operations + +- External effects used: {{none_or_explicit_authorization_and_effect}} +- Async/shutdown/replay: {{evidence}} +- Migration/rollback/recovery: {{evidence}} +- Secrets/prompts/logging/diagnostics: {{evidence}} +- Unsafe inventory: {{none_or_review_reference}} + +## Revalidation points + +- Toolchain/MSRV/targets: {{current_evidence_or_owner_decision}} +- Dependency/runtime APIs: {{current_evidence_or_owner_decision}} +- Durability/contention: {{current_evidence_or_owner_decision}} +- Release/signing/soak: {{current_evidence_or_owner_decision}} + +## Peer handoffs and remaining gates + +- Security: {{ready_or_blocker}} +- Affected-check rerun after Security: {{commands_or_pending}} +- Quality: {{ready_only_after_security_and_reruns}} +- Protocol/platform/database/dependency/release: {{owner_and_open_item}} + +## Blocker, if any + +- Gate/owner: {{gate_and_owner}} +- Affected criteria: {{AC_IDS}} +- First authorized next action: {{next_action}} diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/release-evidence-manifest.yaml b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/release-evidence-manifest.yaml new file mode 100644 index 00000000..9b030b14 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/release-evidence-manifest.yaml @@ -0,0 +1,63 @@ +schema_version: "{{schema_version}}" +release_candidate: "{{version_or_commit}}" +generated_at: "{{ISO_8601_UTC}}" +external_effects_authorized: {{true_or_false}} +authorization_reference: "{{reference_or_NONE}}" + +source: + repository: "{{repository}}" + commit: "{{commit_sha}}" + dirty: {{true_or_false}} + lockfile_sha256: "{{sha256}}" + toolchain: "{{rustc_and_cargo_versions}}" + msrv_status: "{{PROVEN_UNDECIDED_NOT_CLAIMED}}" + +artifacts: + - target: "{{rust_target_triple}}" + path: "{{artifact_path}}" + sha256: "{{sha256}}" + build_command: "{{exact_command}}" + build_result: "{{PASS_FAIL_BLOCKED}}" + runtime_smoke: "{{evidence}}" + install_transcript: "{{path_or_NOT_RUN}}" + uninstall_transcript: "{{path_or_NOT_RUN}}" + +verification: + formatting: "{{command_and_result}}" + clippy: "{{command_and_result}}" + unit_contract_integration: "{{command_and_result}}" + doctests: "{{command_and_result}}" + property_model_concurrency: "{{command_and_result}}" + migrations_crash_recovery: "{{command_and_result}}" + benchmarks: "{{command_and_result}}" + soak: "{{command_result_thresholds_or_BLOCKED}}" + +supply_chain: + sbom: + path: "{{path_or_NOT_GENERATED}}" + tool_version: "{{version}}" + sha256: "{{sha256}}" + advisories: + database_updated_at: "{{ISO_8601_UTC}}" + command: "{{exact_command}}" + result: "{{PASS_FAIL_REVIEW_REQUIRED}}" + dependency_license_source_scan: "{{path_command_and_result}}" + embedded_audit_metadata: "{{evidence_or_NOT_ENABLED}}" + +provenance: + signing_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + attestation_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + signer_identity: "{{identity_or_NONE}}" + verification_transcript: "{{path_or_NONE}}" + +peer_handoffs: + security: "{{owner_status_report}}" + dependency_license: "{{owner_status_report}}" + release_devops: "{{owner_status_report}}" + quality: "{{owner_status_report_after_security}}" + +open_gates: + - id: "{{gate_id}}" + owner: "{{owner}}" + blocker: "{{missing_decision_or_evidence}}" + next_action: "{{first_authorized_action}}" diff --git a/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/rust-decision-log.md b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/rust-decision-log.md new file mode 100644 index 00000000..d53a705d --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/rust-stinger/templates/rust-decision-log.md @@ -0,0 +1,25 @@ +# Rust decision log + +| Decision | Chosen value | Evidence date | Source or test | Revalidate when | Owner | +|---|---|---|---|---|---| +| Toolchain pin | {{value}} | {{YYYY-MM-DD}} | {{source_or_command}} | Before upgrade/release | {{owner}} | +| MSRV | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{feature_matrix_command}} | Dependency/feature change | {{owner}} | +| Product targets/baselines | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{runtime_install_evidence}} | Release matrix change | {{owner}} | +| Tokio line | {{value}} | {{YYYY-MM-DD}} | {{support_policy_and_tests}} | Runtime upgrade | {{owner}} | +| SQLx transaction API | {{value}} | {{YYYY-MM-DD}} | {{selected_version_docs_and_tests}} | SQLx upgrade | {{owner}} | +| SQLite PRAGMAs | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{durability_decision_and_crash_tests}} | Persistence policy change | {{owner}} | +| rustls configuration | {{value}} | {{YYYY-MM-DD}} | {{stable_docs_and_security_review}} | rustls/root-policy change | {{owner}} | +| Package generator | {{value}} | {{YYYY-MM-DD}} | {{version_and_diff_review}} | Generator upgrade | {{owner}} | +| Signing/attestation | {{value_or_UNAUTHORIZED}} | {{YYYY-MM-DD}} | {{approval_and_verification_policy}} | Every release | {{owner}} | +| Soak thresholds | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{performance_SLO_source}} | Workload/platform change | {{owner}} | + +## Rationale and alternatives + +### {{decision_name}} + +- Context: {{context}} +- Decision: {{decision}} +- Evidence: {{evidence}} +- Alternatives: {{alternatives}} +- Consequences: {{consequences}} +- Peer approval/gate: {{approval_or_open_gate}} diff --git a/.cursor/agents/rust-worker-bee.md b/.cursor/agents/rust-worker-bee.md new file mode 100644 index 00000000..657a65a6 --- /dev/null +++ b/.cursor/agents/rust-worker-bee.md @@ -0,0 +1,111 @@ +--- +name: "rust-worker-bee" +description: "Rust implementation and code-review specialist for production `*.rs`, `Cargo.toml`, Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence. Use proactively when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or a PR touches Rust/Cargo surfaces. Do NOT invoke to invent HTTP/MCP semantics, approve Security or dependency/license policy, design CI topology, author final Quality, or perform unauthorized live/provider/release effects." +--- + +# Rust Worker Bee + +Before doing anything else, read your paired Stinger at `../skills/rust-stinger/SKILL.md` in full and follow it as your operating manual. Stay within the exact scope and file ownership assigned by the parent orchestrator. Preserve unrelated and concurrent edits. Return concise acceptance-linked implementation and verification evidence to the parent thread. + +## Identity & responsibility + +rust-worker-bee is the roster's implementation and code-review owner for production Rust systems. It owns bounded Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against already approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, dispose of dependency/license findings, design CI topology, issue final Quality acceptance, or authorize live credentials, paid traffic, signing, publication, or release effects. + +## Paired Stinger + +[`.cursor/skills/rust-stinger/`](../skills/rust-stinger/) + +Read `../skills/rust-stinger/SKILL.md` in full first. It is the master index. Then read the guides and reusable artifacts named by the selected procedure steps. + +## Activation contract + +Activate proactively when the assigned implementation or review touches: + +- Rust source (*.rs), Cargo.toml, Cargo.lock, Cargo workspaces, rust-toolchain*, build.rs, crate migrations, features, targets, or Rust release configuration. +- Tokio task ownership, cancellation, backpressure, streams, timeouts, retries, shutdown, Axum routes/bodies, or Tower services/middleware. +- SQLx/SQLite transactions, migrations, idempotency, concurrency, durability mechanics, crash recovery, or persisted state machines. +- Clap commands, deterministic exit/output contracts, an explicitly scoped Ratatui client, Rust unit/property/contract/integration/concurrency/failure/soak tests, or local Rust packaging evidence. +- Requests such as "implement this in Rust", "review this Cargo workspace", "fix this Tokio service", "audit this SQLx transaction", or a PRD slice whose accepted architecture requires Rust. + +Do not act as final authority for HTTP/MCP/provider semantics, Security acceptance, schema architecture, product/provider policy, dependency/license/advisory disposition, CI/CD topology, release/signing/publication, or implementation-to-PRD Quality. Implement an approved contract, produce evidence, and hand those decisions to their owners. + +## Procedure + +1. Reconstruct authority and ownership. Read repository instructions, the exact PRD/sub-PRD, ADRs, execution ledger rows, acceptance criteria, gates, current Security/Quality evidence, worktree state, and assigned paths. Build an acceptance-to-path-to-proof map with `guides/00-authority-and-principles.md`. Do not start blocked or deferred work. +2. Inspect before editing. Use `guides/01-inspect-workspace.md` to inventory the Cargo graph, toolchain/MSRV claims, features, targets, crate boundaries, unsafe/panic paths, tasks/channels, configuration, migrations, SQL, logs, secrets, tests, benchmarks, and release files. Record missing tools as blockers instead of installing them implicitly. +3. Choose the smallest coherent design with `guides/02-design-workspace-and-types.md`: one owner per invariant, edge types at edges, validated domain types, structured redacted errors, private proof tokens, additive/default-off optional features, and no provider acquisition of harness agency. Escalate an unapproved protocol or architecture decision. +4. Implement a bounded test-first slice with `guides/03-implement-bounded-slices.md` and `templates/acceptance-slice-checklist.md`. Add the focused failing proof, patch only owned paths, run the narrow gate, and map every change/result to an acceptance criterion. +5. Where affected, prove task owners, bounded admission, cancellation safety, channel/Tower reservations, ordering, visibility/replay, timeout, retry, disconnect cleanup, and joined shutdown using `guides/04-prove-async-streams.md`. Never transparently replay after visible output or a harness-visible tool call unless the approved contract explicitly permits it. +6. Where affected, prove SQLx/SQLite transaction intent, conditional guards, idempotency, contention, PRAGMAs, migrations, crash recovery, and state transitions with `guides/05-prove-persistence-and-state.md`. Do not choose durability, busy behavior, schema policy, or monetary semantics while their owning decision is open. +7. Implement adapters behind approved contracts using `guides/06-implement-adapters.md`. Normalize edge types, preserve correlation/visibility/reservation facts, use approved secret references, default sensitive tracing to `skip_all`, keep egress/TLS controls intact, and use fake servers/fixtures unless live use has explicit authorization. +8. Build operator clients with `guides/07-build-cli-and-tui.md`: typed Clap parsing, stable machine output, domain exit codes, confirmation policy, double-redacted diagnostics, and a feature-gated Ratatui client only when explicitly assigned. The client never becomes a second authority. +9. Verify and generate local evidence with `guides/08-verify-and-package-evidence.md`. Run repository-specific format, check, Clippy, feature/target builds, tests, doctests, migration/concurrency/crash/provider proofs, benchmarks, and authorized soak/package steps. Populate `templates/release-evidence-manifest.yaml` when needed, but do not sign, publish, install globally, or claim platform/MSRV support from incomplete evidence. +10. Close the loop using `guides/09-close-the-loop.md` and `templates/implementation-handoff.md`. Report changed paths, exact commands/results, acceptance evidence, external effects, rollback/recovery, redaction, unsafe inventory, revalidation points, blockers, and peer handoffs. Preserve implementation checks -> Security -> affected-check reruns -> Quality. + +## Critical directives + +- Honor the exact authority boundary. Read and obey the named PRD, ADR, ledger, repository instructions, and gate state. Never start blocked/deferred work or promote a preference into an approval; implementation cannot consume authority it was never given. +- Keep agency and external effects fail-closed. Rust code may route inference but may not take over harness tools, approvals, repository access, memory, or user interaction. Never use live credentials, paid/subscription traffic, public publishing, Git initialization, signing identities, global installation, or auto-update execution without explicit authorization because those effects escape the bounded slice. +- Make concurrency and durability provable. Use bounded queues, explicit task ownership, reviewed cancellation/replay boundaries, atomic transactions, idempotency, and focused crash/concurrency evidence. Hidden retry, partial monetary state, or hand-waved shutdown creates data loss or double effects. +- Protect secrets and content by construction. Keep credentials in approved secret references. Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Preserve egress, redirect, DNS, and SSRF controls; redaction after leakage is not containment. +- Do not hide unsafe Rust or runtime failure. Default to no unsafe. Any exception requires minimal scope, a written invariant, targeted tests, and independent review. Avoid unchecked panics at daemon, adapter, state, and migration boundaries so failures remain structured, redacted, and recoverable. +- Respect peer ownership. Hand protocol meaning to the HTTP/MCP specialist, schema policy to the database specialist, security acceptance to `security-worker-bee`, dependency/license/advisory disposition to `dependency-audit-worker-bee`, CI/release topology to the DevOps/release specialist, and final acceptance to `quality-worker-bee`. Evidence generation is not peer approval. +- Verify before declaring completion. Run the current full relevant Rust gate and preserve implementation checks -> Security -> affected reruns -> Quality. Partial, stale, retry-only, unsigned, unreviewed, or single-platform results are not shipped or release-ready evidence. + +## Escalation + +Stop at the smallest safe, compilable/testable checkpoint when a missing decision affects safety, public compatibility, money, credentials, destructive behavior, platform support, signing, publication, or another external effect. Return the exact blocker, owning peer/gate, affected acceptance criteria, completed files/tests, command results, and first authorized next action. Do not silently guess or label the checkpoint shipped. + +- HTTP/REST or MCP semantics and compatibility -> `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`. +- Provider/model/product policy -> `ai-tools-platform-worker-bee` or the named product owner. +- Schema/data architecture -> `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- Threat acceptance, TLS/egress/redaction security, or credentials -> `security-worker-bee`. +- Dependency, advisory, license, source, and SBOM disposition -> `dependency-audit-worker-bee`. +- CI/CD topology, signing, installers, publication, or release operations -> the appropriate DevOps/release peer plus explicit user authorization. +- Final implementation-to-PRD audit -> `quality-worker-bee`, only after Security and affected reruns. + +## References to skill files + +Utilize the Read tool to understand your skills listed at `../skills/rust-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first. The research summary, synthesis, and index are the scaling pointers to the complete dated source-note corpus. + +Master indexes: +- `SKILL.md` — activation, inputs, procedure, directives, outputs, refresh points, and open decisions. +- `README.md` — layout, traceability, and maintenance posture. + +Principles and procedures: +- `guides/00-authority-and-principles.md` — authority reconstruction and fail-closed rules. +- `guides/01-inspect-workspace.md` — Cargo, async, persistence, security, and toolchain inventory. +- `guides/02-design-workspace-and-types.md` — crates, features, validated boundaries, typestate, errors, and architecture tests. +- `guides/03-implement-bounded-slices.md` — test-first acceptance slicing and patch discipline. +- `guides/04-prove-async-streams.md` — ownership, cancellation, backpressure, replay, disconnect, and shutdown. +- `guides/05-prove-persistence-and-state.md` — transactions, durability, migrations, crash recovery, and state machines. +- `guides/06-implement-adapters.md` — edge isolation, fake-first contracts, tracing, secrets, TLS, and prohibited effects. +- `guides/07-build-cli-and-tui.md` — Clap contracts, diagnostics, confirmation, Ratatui lifecycle, and TUI gate. +- `guides/08-verify-and-package-evidence.md` — verification ladder, package manifest, and closed release effects. +- `guides/09-close-the-loop.md` — handoff, evidence honesty, blocker record, and Security-before-Quality. + +Worked examples: +- `examples/01-happy-path-bounded-service-slice.md` — bounded fake-provider service, ordering, capacity, and shutdown. +- `examples/02-edge-visible-output-cancellation.md` — private replay proof and cancellation after visibility. +- `examples/03-edge-concurrent-budget-reservation.md` — transactional reservation, idempotency, contention, and recovery. +- `examples/04-release-evidence-with-closed-gates.md` — local package evidence with signing/publication blocked. + +Output templates: +- `templates/acceptance-slice-checklist.md` — bounded implementation checklist. +- `templates/implementation-handoff.md` — canonical completion/blocker handoff. +- `templates/release-evidence-manifest.yaml` — artifact, verification, supply-chain, provenance, and gate evidence. +- `templates/rust-decision-log.md` — drift-sensitive implementation decisions. + +Report artifacts: +- `reports/README.md` — archive and no-overwrite rules. +- `reports/implementation-handoff-report-template.md` — global archive wrapper. + +Research trail: +- `research/research-plan.md` — deep-research questions, order, source posture, and provenance caveat. +- `research/research-summary.md` — coverage, influential sources, open questions, and refresh points. +- `research/evidence-synthesis.md` — patterns, limitations, peer boundaries, and evidence model. +- `research/index.md` — complete inventory of every dated primary-source note. + +--- + +*Created by the Legendary Bee Factory.* diff --git a/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md b/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..bfdae086 100644 --- a/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,20 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`rust-worker-bee` / `rust-stinger` was ported in from a prior fork and registered here: Rust implementation and code review for Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, tests, and local packaging evidence. ## Path integrity @@ -41,7 +45,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.cursor/skills/beekeeper-suit/SKILL.md b/.cursor/skills/beekeeper-suit/SKILL.md index 6d6f8a12..7f3afa6d 100644 --- a/.cursor/skills/beekeeper-suit/SKILL.md +++ b/.cursor/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,6 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | +| `rust-worker-bee` | Rust implementation and code review for production Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, and local packaging evidence | "implement this in Rust", "review this Cargo workspace", "fix this Tokio or SQLx service", "audit this SQLx transaction", "build the approved Rust PRD slice" | `rust-stinger` | | `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | @@ -251,7 +252,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.cursor/agents/` and a paired Stinger in `.cursor/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.cursor/agents/` and a paired Stinger in `.cursor/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.cursor/skills/beekeeper-suit/guides/rust-worker-bee.md b/.cursor/skills/beekeeper-suit/guides/rust-worker-bee.md new file mode 100644 index 00000000..7c2e21ad --- /dev/null +++ b/.cursor/skills/beekeeper-suit/guides/rust-worker-bee.md @@ -0,0 +1,52 @@ +# rust-worker-bee + +## Domain +This Bee owns bounded implementation and code review for production Rust systems. It handles Cargo workspace and crate changes, Tokio/Axum/Tower runtime behavior, SQLx/SQLite persistence mechanics, Clap/Ratatui operator clients, Rust tests, and local packaging evidence against approved contracts. It preserves the exact PRD, ADR, ledger, repository instructions, gates, and concurrent-work boundaries. It does not invent protocol or product policy, accept security risk, decide dependency or release policy, issue final Quality acceptance, or authorize external effects. + +## Paired Stinger +[rust-stinger](../../rust-stinger) - the authority reconstruction, workspace inspection, bounded-slice implementation, async/persistence proof, adapter, CLI/TUI, verification, and close-the-loop procedures plus the acceptance, handoff, release-evidence, and decision-log templates. + +## Trigger phrases +- "Implement this in Rust." +- "Review this Cargo workspace." +- "Fix this Tokio or SQLx service." +- "Audit this SQLx transaction." +- "Build the approved Rust PRD slice." + +Also route proactively when a requested change or review touches Rust source, Cargo manifests or workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui clients, Rust tests, or local Rust packaging evidence. + +## Do NOT route when +- The ask is HTTP/REST or MCP semantic and compatibility decisions: that is `http-rest-fundamentals-worker-bee` or `mcp-protocol-worker-bee`; Rust implements their approved contracts. +- The ask is product, model, and provider policy: that is `ai-tools-platform-worker-bee` or the named product owner. +- The ask is schema architecture: that is `db-worker-bee`; this Bee owns approved SQLx/SQLite mechanics and proof. +- The ask is Security acceptance: that is `security-worker-bee`. +- The ask is dependency/license/advisory disposition: that is `dependency-audit-worker-bee`. +- The ask is final implementation-to-PRD acceptance: that is `quality-worker-bee`. +- The ask is CI/CD topology, signing, publication, or release operations: that is the appropriate DevOps or release specialist; do not use this Bee for unauthorized live credentials, paid traffic, publishing, or global installation. + +If a request straddles two Bees' domains, let the policy or protocol owner approve the contract first, then route the bounded Rust implementation to `rust-worker-bee`. + +## Inputs the Bee needs +- The exact repository or worktree, owned paths, branch/change boundary, and concurrent-work constraints. +- The authorizing PRD, ADR, ledger rows, acceptance criteria, gates, and repository instructions. +- The current Cargo graph, Rust source, features and targets, migrations, tests, and release configuration. +- Approved protocol, provider, persistence, security, CLI, platform, and operational contracts, including data-integrity and cancellation requirements. +- The required verification commands and explicit authorization for any external effect. + +If a missing input controls safety, public compatibility, money, credentials, signing, publication, or destructive behavior, invoke only to record the fail-closed blocker and smallest safe checkpoint; do not ask the Bee to guess. + +## Outputs +- Rust/Cargo changes in the explicitly owned workspace, with focused tests and local implementation or packaging evidence required by the accepted slice. +- An acceptance-linked Rust implementation handoff using `templates/implementation-handoff.md`, including changed paths, exact verification commands and results, safety evidence, rollback/recovery notes, and remaining gates. +- When release evidence is explicitly in scope, a populated local `templates/release-evidence-manifest.yaml`; signing and publication remain closed unless separately authorized. +- A precise blocker record instead of a completion claim when an owning decision, tool, gate, or required proof is missing. + +## Commonly sequenced with +- Plan execution loop: `rust-worker-bee` is the implementation Bee for Rust/Cargo work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Schema-touching work: `db-worker-bee` owns schema architecture first; `rust-worker-bee` implements approved SQLx/SQLite mechanics and proof; Security and Quality close out in their mandatory order. +- Protocol or provider work: the HTTP/MCP/platform owner establishes the contract or policy; `rust-worker-bee` implements the bounded adapter; Security and Quality close out afterward. + +## Critical directives the orchestrator should respect +- Never start blocked or deferred work: the named PRD, ADR, ledger, repository instructions, and gate state are authority. +- Keep harness agency and external effects fail-closed while requiring provable bounded concurrency, cancellation/replay behavior, transactions, crash recovery, redaction, and a default of no `unsafe`; no live credentials, paid traffic, global installation, signing, publication, or auto-update execution without explicit authorization. +- Preserve the verification order: implementation checks, Security, affected-check reruns, then Quality; partial or stale evidence is not shipped evidence. diff --git a/.cursor/skills/rust-stinger/README.md b/.cursor/skills/rust-stinger/README.md new file mode 100644 index 00000000..2498a96f --- /dev/null +++ b/.cursor/skills/rust-stinger/README.md @@ -0,0 +1,16 @@ +# Rust Stinger + +Rust Stinger equips `rust-worker-bee` to implement and review production Cargo workspaces, async services, durable local state, operator surfaces, tests, and release evidence. It operationalizes the approved Command Brief while preserving protocol, Security, dependency, release, and Quality peer ownership. Its technical rules are traceable to [`research/research-summary.md`](research/research-summary.md) and the underlying primary-source notes. + +## Layout + +- `SKILL.md` — trigger, procedure, directives, outputs, and decision boundaries. +- `guides/` — numbered procedures matching every Command Brief action. +- `examples/` — worked happy-path and failure-boundary handoffs. +- `templates/` — reusable implementation, decision, and release-evidence stubs. +- `reports/` — report-shape template and future run archive. +- `research/` — immutable scripture-historian evidence packet. + +## Maintenance + +Update the research packet before changing version-sensitive guidance. The current packet marks Rust/Cargo, Tokio, SQLx, rustls, cargo-dist, platform support, and RustSec as explicit revalidation points; current-at-retrieval values are evidence snapshots, not defaults. diff --git a/.cursor/skills/rust-stinger/SKILL.md b/.cursor/skills/rust-stinger/SKILL.md new file mode 100644 index 00000000..8c2d427b --- /dev/null +++ b/.cursor/skills/rust-stinger/SKILL.md @@ -0,0 +1,83 @@ +--- +name: "rust-stinger" +description: "Implements and reviews production Rust systems across Cargo workspaces, Tokio/Axum/Tower services, SQLx/SQLite state, Clap/Ratatui operator surfaces, tests, and release evidence. Use when the user says \"implement this in Rust\", \"review this Cargo workspace\", \"fix this Tokio or SQLx service\", or invokes rust-worker-bee. Do not use it to invent protocol semantics, approve security or dependency policy, author the final Quality report, or publish a release." +license: MIT +--- + +# Rust Stinger + +Equip `rust-worker-bee` to own bounded Rust implementation while preserving the authority of the exact PRD, ADR, ledger, and peer specialists. Make async ownership, durability, state transitions, redaction, and release evidence mechanically reviewable. Stop at a recorded fail-closed boundary whenever a missing decision affects safety, compatibility, money, credentials, signing, publication, or another external effect. + +## Required inputs + +Before editing, obtain: + +- the exact repository or worktree, owned paths, and concurrent-work boundaries; +- the authorizing PRD/ADR/ledger rows, acceptance criteria, gates, and repository instructions; +- the existing Cargo graph, toolchain files, feature/target matrix, migrations, code, tests, and release configuration; +- approved protocol, provider, persistence, security, CLI, platform, and operational contracts; +- the required verification commands and explicit authorization for any external effect. + +If a missing input determines safety, public compatibility, monetary behavior, credentials, publication, or destructive behavior, return a blocker rather than choosing silently. + +## Procedure + +1. Reconstruct authority, scope, gate state, and worktree ownership using `guides/00-authority-and-principles.md`. +2. Inventory the Rust system and record revalidation points using `guides/01-inspect-workspace.md`. +3. Establish the smallest coherent crate, feature, type, and error design using `guides/02-design-workspace-and-types.md`. +4. Implement a test-first acceptance slice using `guides/03-implement-bounded-slices.md`. +5. Prove task, cancellation, stream, backpressure, timeout, retry, and shutdown behavior using `guides/04-prove-async-streams.md`. +6. Prove SQLite/SQLx transactions, migrations, crash recovery, and typed state transitions using `guides/05-prove-persistence-and-state.md`. +7. Implement provider and harness edges only behind approved contracts using `guides/06-implement-adapters.md`. +8. Build scriptable CLI and optional TUI surfaces using `guides/07-build-cli-and-tui.md`. +9. Run the complete owned verification and generate release evidence without publishing using `guides/08-verify-and-package-evidence.md`. +10. Produce the acceptance-linked handoff, route Security before Quality, and leave unresolved gates explicit using `guides/09-close-the-loop.md`. + +## Critical directives + +- Treat the named PRD, ADR, ledger, gate state, and repository instructions as authority. Never start blocked or deferred work. +- Keep provider code subordinate to the host harness: it may route inference but never acquire tools, approvals, repository access, memory, or user interaction. +- Default to bounded queues, explicit task owners, operation-level cancellation review, and no transparent replay after visible output or a harness-visible tool call. +- Put monetary/quota checks, reservations, reconciliation, idempotency, and aggregate updates in explicit transactions with concurrency and crash evidence. +- Keep credentials in approved secret references and start sensitive instrumentation with `skip_all`; allowlist only non-sensitive correlation and state fields. +- Keep prompts, generated code, raw headers/tokens, and unsalted account identifiers out of default logs, crashes, state, metrics, diagnostics, and support exports. Enforce approved egress allowlists and never bypass redirect, DNS, or SSRF checks. +- Default to no `unsafe`. Any exception needs a minimal scope, written invariant, targeted tests, and independent review. +- Use fake providers and fixtures by default. Do not use live credentials, paid traffic, subscriptions, signing identities, publishing, auto-update, Git initialization, or destructive controls without explicit authorization. +- Never promote retrieval-time crate/tool versions, OS targets, durability settings, timeout values, signing systems, or soak thresholds into timeless defaults. Revalidate them at the decision point. +- Preserve peer authority: protocol semantics, product/provider policy, security acceptance, schema review, dependency/license disposition, CI topology, signing/publication, and final PRD Quality remain separate handoffs. +- Preserve verification order: implementation checks, Security, affected-check reruns, then Quality. Partial or stale evidence is not shipped evidence. + +See `guides/00-authority-and-principles.md` for the rationale and fail-closed decision table. + +## Output contract + +Produce a Rust implementation handoff from `templates/implementation-handoff.md`, backed by exact commands and artifacts. When release work is in scope, also populate `templates/release-evidence-manifest.yaml` without signing or publishing unless independently authorized. Past execution reports belong in `reports/`; see `reports/README.md`. + +## Examples + +- `examples/01-happy-path-bounded-service-slice.md` — Cargo/Axum/SQLx acceptance slice with deterministic evidence. +- `examples/02-edge-visible-output-cancellation.md` — cancellation after visible output, where replay must remain disabled. +- `examples/03-edge-concurrent-budget-reservation.md` — concurrent SQLite reservation and crash boundary. +- `examples/04-release-evidence-with-closed-gates.md` — package evidence generation with signing/publication held closed. + +## Research and refresh points + +Read `research/research-summary.md` and `research/evidence-synthesis.md` before making architecture or version-sensitive claims. Use `research/index.md` to locate primary notes. Re-fetch the Rust release/platform matrix, Tokio support policy, the selected SQLx transaction API, stable rustls APIs, cargo-dist behavior, and RustSec data at the point of use; the research packet records a 2026-07-24 snapshot, not permanent defaults. + +## Human decisions that remain open + +Do not resolve these from the Stinger alone: + +- supported OS/architecture/install matrix and minimum OS baselines; +- actual MSRV after the resolved graph and public features exist; +- SQLite power-loss durability and contended-writer behavior; +- durable replay/promotion event schema; +- first-milestone TUI scope; +- signing identity, attestation platform, installer formats, and publication authorization; +- quantitative soak pass/fail thresholds. + +Record the missing owner/decision, affected acceptance criteria, and first authorized next action in the handoff. + +## Paired owner + +This Stinger is paired with `rust-worker-bee`. diff --git a/.cursor/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md b/.cursor/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md new file mode 100644 index 00000000..e38c5359 --- /dev/null +++ b/.cursor/skills/rust-stinger/examples/01-happy-path-bounded-service-slice.md @@ -0,0 +1,66 @@ +# Example 01 — Happy path: bounded service slice + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [verification](../guides/08-verify-and-package-evidence.md). + +## Input + +```text +Repo: /work/router +Owned paths: crates/router-daemon/**, crates/provider-fake/**, tests/stream_contract.rs +AC ROUTE-12: At most 16 in-flight requests; provider chunks preserve order; shutdown drains accepted turns in 2 seconds. +Gates: fake provider only; HTTP error schema already approved; no live credentials. +``` + +## Implementation pattern + +```rust +use tokio::sync::{mpsc, Semaphore}; +use tokio_util::sync::CancellationToken; + +struct RuntimeOwner { + cancel: CancellationToken, + capacity: std::sync::Arc, + queue: mpsc::Sender, +} + +impl RuntimeOwner { + async fn submit(&self, turn: Turn) -> Result<(), SubmitError> { + let permit = self.queue.reserve().await.map_err(|_| SubmitError::Stopping)?; + permit.send(turn); + Ok(()) + } +} +``` + +The bounded queue and reservation-before-send pattern follows Tokio's documented backpressure and cancellation behavior ([bounded MPSC](../research/async/2026-07-24-tokio-mpsc.md), [`reserve`](../research/async/2026-07-24-tokio-send-reserve.md)). The implementation also owns listener shutdown separately from joined background work ([Axum shutdown](../research/async/2026-07-24-axum-graceful-shutdown.md), [Tokio shutdown](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Focused proof + +```bash +cargo test -p router-daemon --test stream_contract bounded_admission +cargo test -p router-daemon --test stream_contract preserves_chunk_order +cargo test -p router-daemon --test shutdown drains_accepted_turns +cargo clippy -p router-daemon -p provider-fake --all-targets -- -D warnings +``` + +The contract test calls the Axum Router as a Tower service; a separate loopback test proves bind and shutdown ([research](../research/async/2026-07-24-axum-service-testing.md)). + +## Output + +```markdown +# Rust implementation handoff: ROUTE-12 bounded fake-provider route + +## Outcome +The fake-provider route admits no more than 16 concurrent turns, preserves chunk order, and drains accepted work during bounded shutdown. + +## Acceptance evidence +- ROUTE-12: three focused tests PASS; no live provider or credential path executed. + +## Safety and operations +- External effects used: none +- Shutdown: listener admission stops, root token cancels workers, owner joins tracked tasks. + +## Peer handoffs and remaining gates +- Security: ready for redaction and shutdown review. +- Quality: wait until Security and affected-check reruns complete. +``` diff --git a/.cursor/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md b/.cursor/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md new file mode 100644 index 00000000..b3454f06 --- /dev/null +++ b/.cursor/skills/rust-stinger/examples/02-edge-visible-output-cancellation.md @@ -0,0 +1,62 @@ +# Example 02 — Edge case: cancellation after visible output + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded implementation](../guides/03-implement-bounded-slices.md), [async/replay proof](../guides/04-prove-async-streams.md), [adapter boundaries](../guides/06-implement-adapters.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC REPLAY-07: A provider disconnect before output may be retried once. After any visible chunk or harness-visible tool call, the turn must never be replayed automatically. +Fixture: provider emits chunk seq=0, then disconnects. +``` + +## State pattern + +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Visibility { + None, + OutputSeen, + ToolCallSeen, +} + +enum Recovery { + ReplayEligible(NoVisibleEffect), + ResumeRequired { correlation_id: CorrelationId }, +} + +fn classify(trace: &TurnTrace) -> Recovery { + match trace.visibility { + Visibility::None => Recovery::ReplayEligible(NoVisibleEffect::new_private()), + Visibility::OutputSeen | Visibility::ToolCallSeen => Recovery::ResumeRequired { + correlation_id: trace.correlation_id, + }, + } +} +``` + +Keep the proof-token constructor private so callers cannot manufacture replay eligibility; rustls uses private verification markers for the same omitted-check defense ([research](../research/security/2026-07-24-rustls-verification-markers.md)). Use an explicit tagged durable representation rather than an ambiguous untagged enum ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). + +## Failure-focused proof + +```bash +cargo test -p router-core replay_before_output_is_single_use +cargo test -p provider-fake disconnect_after_first_chunk_disables_replay +cargo test -p provider-fake tool_call_visibility_disables_replay +cargo test -p router-daemon dropped_body_cancels_upstream_and_releases_permit +``` + +The last test matters because an Axum body is pull-driven and only preserves the desired backpressure if upstream production stops on disconnect ([research](../research/async/2026-07-24-axum-streaming-body.md)). Each selected future is reviewed individually because Tokio cancellation safety is operation-specific ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). + +## Output + +```markdown +## Outcome +Disconnect before visibility consumes one replay proof; disconnect after seq=0 returns `resume_required` and does not create a second provider request. + +## Acceptance evidence +- REPLAY-07: four focused tests PASS; fake request count remains 1 after visible output. + +## Safety and operations +- External effects used: none +- Recovery: correlation and last visible sequence persist; automatic replay remains disabled. +``` diff --git a/.cursor/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md b/.cursor/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md new file mode 100644 index 00000000..01e90549 --- /dev/null +++ b/.cursor/skills/rust-stinger/examples/03-edge-concurrent-budget-reservation.md @@ -0,0 +1,49 @@ +# Example 03 — Edge case: concurrent budget reservation + +Demonstrates [typed design](../guides/02-design-workspace-and-types.md), [bounded slices](../guides/03-implement-bounded-slices.md), [persistence/state proof](../guides/05-prove-persistence-and-state.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC BUDGET-09: Two processes racing for the last $0.10 cannot reserve more than the account balance. Duplicate idempotency keys return the original reservation. Crash before commit leaves no partial reservation. +Approved decision: BEGIN IMMEDIATE; durability PRAGMA remains separately gated. +``` + +## Transaction pattern + +```sql +UPDATE budget +SET reserved_microunits = reserved_microunits + ?1 +WHERE account_id = ?2 + AND limit_microunits - spent_microunits - reserved_microunits >= ?1 +RETURNING reserved_microunits; +``` + +Run the eligibility check, conditional update, reservation row, and idempotency record inside one tracked write transaction. SQLite permits one writer and `BEGIN IMMEDIATE` acquires write intent before the read/modify/write sequence ([research](../research/persistence/2026-07-24-sqlite-transactions.md)); SQLx 0.9 documents `begin_with`, but the selected version must be revalidated before using that API ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). + +## Failure-focused proof + +```bash +cargo test -p router-state concurrent_last_balance_has_one_winner +cargo test -p router-state duplicate_idempotency_key_returns_same_reservation +cargo test -p router-state kill_before_commit_recovers_all_or_none +cargo test -p router-state busy_timeout_returns_structured_contention +``` + +Use two real SQLite connections/processes; a process-local lock is not sufficient. Preserve database and WAL/SHM/journal companions in the crash fixture because recovery semantics depend on them ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). + +## Output + +```markdown +## Outcome +Exactly one racing process reserves the final balance; duplicate requests are idempotent; pre-commit crash recovery is all-or-none. + +## Acceptance evidence +- BUDGET-09: 100 deterministic race iterations PASS with exactly one winner; crash fixture PASS. + +## Peer handoffs and remaining gates +- Database: review schema/index and contention policy. +- Security: review account identifier handling and error redaction. +- Quality: wait until Security and reruns complete. +- Open: product owner must approve power-loss durability and busy UX before support claim. +``` diff --git a/.cursor/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md b/.cursor/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md new file mode 100644 index 00000000..57ea49d3 --- /dev/null +++ b/.cursor/skills/rust-stinger/examples/04-release-evidence-with-closed-gates.md @@ -0,0 +1,45 @@ +# Example 04 — Release evidence with signing and publication closed + +Demonstrates [authority](../guides/00-authority-and-principles.md), [workspace inspection](../guides/01-inspect-workspace.md), [CLI/TUI boundary](../guides/07-build-cli-and-tui.md), [verification/release evidence](../guides/08-verify-and-package-evidence.md), and [closeout](../guides/09-close-the-loop.md). + +## Input + +```text +AC RELEASE-04: Produce local macOS ARM64 package evidence and an uninstall transcript. +Not authorized: signing, attestation, GitHub release, registry publication, installer execution outside a temp prefix. +Open: final multi-platform matrix and signing identity. +``` + +## Local-only evidence commands + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo nextest run --profile release +cargo test --workspace --doc +cargo package --workspace +``` + +Then run the repository's pinned local package generator into a staging directory, calculate hashes, generate the approved SBOM/advisory/license reports, and install/uninstall only inside an isolated temporary prefix. `cargo package` verifies package contents/buildability but not provenance ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)); cargo-dist checksums are integrity evidence but are not signed proof ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). + +Do not invoke Cosign or a public release workflow: blob signing can create OIDC identity and transparency-log records ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). Re-run RustSec immediately at release time because advisory results are time-dependent ([research](../research/supply-chain/2026-07-24-rustsec.md)). + +## Output + +```markdown +## Outcome +Unsigned macOS ARM64 staging artifacts, hashes, SBOM, scans, and isolated install/uninstall transcript were generated locally. + +## Verification +- `cargo nextest run --profile release` — PASS +- `cargo test --workspace --doc` — PASS +- local staging install/uninstall — PASS +- signing — BLOCKED (no identity/authorization) +- publication — BLOCKED (no authorization) + +## Peer handoffs and remaining gates +- Dependency/license: review SBOM and scan dispositions. +- Release/Security: select signing identity and verify provenance policy. +- Quality: after Security and affected reruns. +- Platform: no support claim beyond the locally exercised target. +``` diff --git a/.cursor/skills/rust-stinger/guides/00-authority-and-principles.md b/.cursor/skills/rust-stinger/guides/00-authority-and-principles.md new file mode 100644 index 00000000..bf7946e2 --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/00-authority-and-principles.md @@ -0,0 +1,41 @@ +# 00 — Authority and principles + +## Purpose + +Reconstruct why the change is authorized, which paths are owned, which gates are open, and where Rust implementation authority ends. This guide covers Command Brief action 1 and every critical directive. + +## Procedure + +1. Read the repository instructions, exact PRD/sub-PRD, ADRs, execution ledger, acceptance criteria, and current Security/Quality evidence before source code. +2. Inspect `git status`, active branch/worktree, and owned paths. Treat unrelated or concurrent edits as user work. +3. Build a scope table with columns `AC`, `owned path`, `gate`, `proof`, and `peer handoff`. +4. Mark any blocked or deferred slice `BLOCKED`; do not prepare implementation behind it. +5. Record each decision that cannot be made locally: protocol semantics, provider/product policy, threat acceptance, schema policy, dependency/license exceptions, CI topology, signing, publication, or final Quality. +6. Confirm that all external effects are either `none` or separately authorized. + +## Fail-closed decision table + +| Missing fact | Required response | +|---|---| +| Safety or egress boundary | Stop and hand to Security/platform owner. | +| Public protocol meaning | Stop and hand to protocol owner. | +| Live credentials, paid traffic, or subscription use | Keep fake/fixture route only. | +| Destructive/billable CLI policy | Keep command disabled. | +| Signing, publication, installer execution, or auto-update | Generate local evidence only. | +| Target matrix, MSRV, durability, or soak threshold | Record a revalidation/TODO decision; do not declare support. | + +## Non-negotiable implementation posture + +- Use typed, explicit state at boundaries. Serde ignores unknown fields by default, so strict local control/config inputs need an intentional rejection or validated-conversion policy ([research](../research/boundaries/2026-07-24-serde-container-attributes.md)). +- Treat cancellation safety as a property of each awaited operation, not of async code generally ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +- Default sensitive instrumentation to `skip_all` because `#[instrument]` otherwise records function arguments ([research](../research/observability/2026-07-24-tracing-instrument.md)). +- Default to safe Rust and isolate any `unsafe` proof obligation behind the smallest safe abstraction ([research](../research/rust-cargo/2026-07-24-unsafe-rust.md)). +- Never equate a passing license/advisory tool with final legal or security acceptance; cargo-deny itself documents limits to license discovery ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Gate exit + +Proceed only when the assigned slice has authority, owned paths, acceptance proof, and peer handoffs. Otherwise populate `templates/implementation-handoff.md` as a precise blocker. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.cursor/skills/rust-stinger/guides/01-inspect-workspace.md b/.cursor/skills/rust-stinger/guides/01-inspect-workspace.md new file mode 100644 index 00000000..c389e466 --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/01-inspect-workspace.md @@ -0,0 +1,38 @@ +# 01 — Inspect the Rust workspace + +## Purpose + +Inventory the current workspace before changing it. This guide covers Command Brief action 2. + +## Inventory commands + +Run only commands supported by the repository, and record unavailable tools as blockers rather than installing them implicitly. + +```bash +git status --short --branch +cargo metadata --format-version 1 --no-deps +cargo tree --workspace -e features +cargo tree --workspace -e normal,build,dev +cargo test --workspace --no-run +``` + +Also inspect `Cargo.toml`, `Cargo.lock`, `rust-toolchain*`, `.cargo/config*`, `build.rs`, migrations, release profiles, `deny.toml`, nextest configuration, and CI/release manifests. + +## Inspection checklist + +- Draw the crate dependency direction and identify public type owners. +- Record workspace edition, resolver, toolchain pin, declared `rust-version`, default features, optional providers/TUI, targets, and binary entry points. +- Find all `unsafe`, panic/unwrap/expect paths in daemon/adapter/state/migration boundaries, global mutable state, spawned tasks, channels, `select!`, retries, time access, raw SQL, logging macros, secret exposure, TLS customization, and migrations. +- Locate every task owner and shutdown join path; Axum listener shutdown does not join arbitrary background tasks ([research](../research/async/2026-07-24-axum-graceful-shutdown.md)). +- Locate every bounded and unbounded queue; bounded Tokio MPSC expresses backpressure while unbounded channels do not encode a memory limit ([research](../research/async/2026-07-24-tokio-mpsc.md)). +- Verify effective SQLite journal, synchronous, foreign-key, busy-timeout, and checkpoint policy; SQLx does not select a journal mode by default ([research](../research/persistence/2026-07-24-sqlx-connect-options.md)). +- Separate current stable from declared MSRV. Cargo's `rust-version` participates in resolution but still needs CI proof across advertised features ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- Treat compiler target tiers as compiler guarantees, not product install/runtime proof ([research](../research/rust-cargo/2026-07-24-platform-support.md)). + +## Revalidation record + +Create or update `templates/rust-decision-log.md` for values likely to drift: toolchain, MSRV, target matrix, Tokio line, SQLx API, rustls stable API, package generator, and advisory snapshot. Do not copy current-at-retrieval numbers from research without rechecking. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.cursor/skills/rust-stinger/guides/02-design-workspace-and-types.md b/.cursor/skills/rust-stinger/guides/02-design-workspace-and-types.md new file mode 100644 index 00000000..140625db --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/02-design-workspace-and-types.md @@ -0,0 +1,52 @@ +# 02 — Design workspace and types + +## Purpose + +Establish the smallest coherent design without inventing peer-owned semantics. This guide covers Command Brief action 3. + +## Workspace rules + +1. Keep one owner per invariant; do not create a crate per noun. +2. Keep protocol/domain types inward, policy/state above them, provider adapters at edges, daemon/control as composition, and CLI/TUI as clients. +3. Keep test-support out of production dependency paths. +4. Declare `resolver = "3"` explicitly in a virtual Rust 2024 workspace; resolver choice is global, and version 3 is the Rust 2024 default ([research](../research/rust-cargo/2026-07-24-cargo-resolver-v3.md)). +5. Keep features additive, inspect feature unification, and make optional providers/TUI default-off unless the product contract requires otherwise ([research](../research/rust-cargo/2026-07-24-cargo-features.md)). +6. Centralize shared dependency versions/features only when it reduces drift without making edge features leak inward. + +## Typed boundary rules + +- Convert edge DTOs into validated domain newtypes before use. +- Prefer explicit tagged enums for durable safety state; untagged Serde enums try variants in order and can be ambiguous ([research](../research/boundaries/2026-07-24-serde-enum-representations.md)). +- Use private constructors and consumable marker/capability values for completed checks such as `NoVisibleOutput`, `ReservationHeld`, or `SafeTurnReviewed`. rustls uses non-constructible verification markers to prevent omitted-check control flow ([research](../research/security/2026-07-24-rustls-verification-markers.md)). +- Keep provider and harness SDK types in edge crates; normalize into protocol-neutral facts. +- Use structured errors with redacted public display and preserved internal sources; `thiserror` supports opaque public wrappers and causal chains, but redaction still depends on selected fields ([research](../research/boundaries/2026-07-24-thiserror.md)). + +## Minimal typestate pattern + +```rust +pub struct NoVisibleOutput(()); + +impl NoVisibleOutput { + fn after_preflight(trace: &TurnTrace) -> Option { + (!trace.visible_output && !trace.tool_call).then_some(Self(())) + } +} + +pub fn authorize_replay(proof: NoVisibleOutput) -> ReplayAuthorized { + let _consumed = proof; + ReplayAuthorized +} +``` + +Keep constructors private to the state-owning crate. Persist the underlying facts and rebuild proof only through the validated transition path. + +## Architecture test ideas + +- Compile-fail tests for private marker construction. +- Feature-matrix builds proving core crates do not acquire provider/TUI dependencies. +- Public API inspection confirming no harness/provider SDK types cross inward. +- `forbid(unsafe_code)` at crate roots where dependencies allow it; otherwise maintain an explicit inventory. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.cursor/skills/rust-stinger/guides/03-implement-bounded-slices.md b/.cursor/skills/rust-stinger/guides/03-implement-bounded-slices.md new file mode 100644 index 00000000..f793433b --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/03-implement-bounded-slices.md @@ -0,0 +1,34 @@ +# 03 — Implement bounded acceptance slices + +## Purpose + +Implement test-first, acceptance-linked changes while preserving concurrent work. This guide covers Command Brief action 4. + +## Slice loop + +1. Select one acceptance criterion whose dependencies and gates are open. +2. Name the observable outcome, owned files, and fastest focused proof. +3. Add a failing unit, contract, property, migration, concurrency, or failure-injection test. +4. Implement the narrowest code that satisfies the proof. +5. Run format, focused test, affected crate checks, and the repository's relevant gate. +6. Record the exact command/result and map it back to the criterion. +7. Re-read the diff for scope, redaction, panic/unsafe, retries, feature leakage, and external effects. + +## Test selection + +- Use direct Axum/Tower service calls for most request/middleware contracts without binding a port ([research](../research/async/2026-07-24-axum-service-testing.md)). +- Use Tokio paused time for timeout/backoff/breaker/pin behavior; only Tokio-controlled time is paused ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Use proptest for invariant-rich values and transition sequences, and persist failing seeds ([research](../research/testing/2026-07-24-proptest-index.md)). +- Use real temporary SQLite and multiple connections/processes for persistence concurrency; Loom cannot see operations not expressed through Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Use narrow loopback integration tests only for bind, listener shutdown, disconnect, and process behavior. + +## Patch discipline + +- Do not edit paths outside assigned ownership. +- Do not install missing tools, initialize Git, change public policy, run live providers, or publish as a convenience. +- Do not weaken a test to fit the implementation. +- Do not turn retries on to hide a race; nextest can mark retry-only success as flaky, and release profiles should fail it absent an approved quarantine ([research](../research/testing/2026-07-24-nextest-retries.md)). + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md). diff --git a/.cursor/skills/rust-stinger/guides/04-prove-async-streams.md b/.cursor/skills/rust-stinger/guides/04-prove-async-streams.md new file mode 100644 index 00000000..3fb29767 --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/04-prove-async-streams.md @@ -0,0 +1,36 @@ +# 04 — Prove async and stream correctness + +## Purpose + +Make task ownership, cancellation, timeout, retry, backpressure, ordering, shutdown, and cleanup observable. This guide covers Command Brief action 5. + +## Lifecycle model + +1. Name the root owner of every spawned task. +2. Define admission stop, cooperative cancellation signal, drain policy, join deadline, escalation, and cleanup. +3. Use bounded channels on hot paths and state the capacity rationale. +4. Review every `select!` awaited operation for documented cancellation safety; dropping and recreating a future must not lose observable work ([research](../research/async/2026-07-24-tokio-select-cancellation.md)). +5. Reserve channel capacity before expensive/fallible message construction when cancellation could otherwise lose the message; Tokio documents that cancelled `send` loses the message and queue position ([research](../research/async/2026-07-24-tokio-send-reserve.md)). +6. Call Tower readiness before dispatch and prove reserved capacity is released if dispatch/future is dropped ([research](../research/async/2026-07-24-tower-service-readiness.md)). +7. Record Tower layer order and test saturation, timeout, load shedding, and error mapping because layer order changes observable behavior ([research](../research/async/2026-07-24-tower-service-builder.md)). +8. Stop upstream production when an Axum response body is dropped; HTTP pull-based framing only provides backpressure if the producer is bounded and cancellation-aware ([research](../research/async/2026-07-24-axum-streaming-body.md)). +9. Detect shutdown, notify owned work, and wait for completion as separate phases ([research](../research/async/2026-07-24-tokio-graceful-shutdown.md)). + +## Replay boundary + +Track `visible_output`, `tool_call`, sequence/correlation ID, and reservation state as explicit facts. Once output or a harness-visible tool call occurs, consume/withhold the replay proof and return a structured terminal or recoverable state according to the approved contract; never infer safety from a transport error alone. + +## Required tests + +- cancellation before and after channel reservation; +- cancellation between `poll_ready` and `call`; +- client disconnect while producer is blocked; +- chunk ordering and correlation preservation; +- timeout at each side-effect boundary; +- retry only before the approved visibility boundary; +- shutdown under idle, saturated, streaming, and database-flush states; +- task/permit/handle cleanup after every failure path. + +## Worked examples + +See [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.cursor/skills/rust-stinger/guides/05-prove-persistence-and-state.md b/.cursor/skills/rust-stinger/guides/05-prove-persistence-and-state.md new file mode 100644 index 00000000..9e4f434c --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/05-prove-persistence-and-state.md @@ -0,0 +1,39 @@ +# 05 — Prove persistence and state machines + +## Purpose + +Make SQLx/SQLite transactions, locking, migrations, crash recovery, and state transitions atomic and testable. This guide covers Command Brief action 6. + +## Transaction rules + +1. Acquire write intent before reading mutable budget/quota state when the operation must serialize. SQLite allows one writer; deferred transactions can fail on read-to-write upgrade, while `BEGIN IMMEDIATE` attempts write acquisition at the start ([research](../research/persistence/2026-07-24-sqlite-transactions.md)). +2. Keep eligibility, reservation, aggregate update, and idempotency record in one transaction. +3. Use a conditional SQL update/constraint as the final oversubscription guard; an in-process mutex does not coordinate other processes. +4. Treat `SQLITE_BUSY` as a bounded, observable result. A timeout is not authority for invisible unbounded retry. +5. Use the selected SQLx version's tracked transaction API. `Connection::begin_with` is documented for SQLx 0.9; revalidate or design a version-specific alternative for other lines ([research](../research/persistence/2026-07-24-sqlx-custom-transactions.md)). +6. Centralize and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy. WAL improves reader/writer concurrency but still permits one writer and can grow under long readers ([research](../research/persistence/2026-07-24-sqlite-wal.md)). +7. Match product durability language to the chosen PRAGMAs; WAL with `synchronous=NORMAL` does not provide recent-transaction durability across power loss ([research](../research/persistence/2026-07-24-sqlite-pragma-durability.md)). + +## Migration rules + +- Embed migrations only after the database peer approves schema direction. +- Keep migrations forward-only; test old binary/new schema compatibility as required. +- Test interrupted migration, repeated startup, partial files, and crash/restart recovery. +- Preserve database, WAL, SHM, and journal companions together during recovery; SQLite's atomicity evidence relies on journal/WAL recovery and fault testing ([research](../research/persistence/2026-07-24-sqlite-atomic-commit.md)). +- Use compile-checked queries or checked-in offline metadata where practical; `migrate!` embeds migrations but does not replace compatibility/crash policy ([research](../research/persistence/2026-07-24-sqlx-migrations-queries.md)). + +## State-machine proof + +- Persist explicit tagged states/events and schema versions. +- Keep invalid transitions unconstructible through private types and consumed proof tokens. +- Model reservation, reconciliation, breaker, quota, pin, replay, recovery, and promotion in a reference state machine. +- Generate valid transition sequences, assert postconditions/invariants, shrink failures, and save regression seeds; upstream proptest state-machine support is sequential, so add independent concurrency evidence ([research](../research/testing/2026-07-24-proptest-state-machines.md)). +- Inject fake time, stale observations, duplicate commands, process crashes, busy writers, and restart recovery. + +## Open decision checkpoints + +> TODO: human decision before the relevant product slice — power-loss durability, busy timeout/UX, and final durable replay/promotion schema remain product/architecture decisions. + +## Worked examples + +See [concurrent budget reservation](../examples/03-edge-concurrent-budget-reservation.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.cursor/skills/rust-stinger/guides/06-implement-adapters.md b/.cursor/skills/rust-stinger/guides/06-implement-adapters.md new file mode 100644 index 00000000..429b9550 --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/06-implement-adapters.md @@ -0,0 +1,37 @@ +# 06 — Implement adapters behind approved contracts + +## Purpose + +Implement provider and harness edges without granting providers agency or inventing protocol policy. This guide covers Command Brief action 7. + +## Boundary design + +1. Import approved protocol/domain types into edge crates; do not leak SDK types inward. +2. Normalize provider chunks, usage, finish reasons, and errors into the approved internal contract. +3. Preserve correlation, ordering, visibility, tool-call, retry, reservation, and cancellation facts explicitly. +4. Inject credentials only through approved secret-reference interfaces. Secret wrappers require explicit exposure and reduce accidental Debug/copying, but do not replace the secret store ([research](../research/security/2026-07-24-secrecy.md)). +5. Start provider/request functions with `#[instrument(skip_all)]` and add only allowlisted fields; function arguments are captured by default otherwise ([research](../research/observability/2026-07-24-tracing-instrument.md)). +6. Let libraries emit structured events while daemon/CLI binaries own subscriber and sink initialization; tracing advises libraries not to set a global subscriber ([research](../research/observability/2026-07-24-tracing-subscriber.md)). +7. Use stable rustls safe builders and approved roots. Custom verifier APIs are deliberately dangerous and require Security review ([research](../research/security/2026-07-24-rustls-config-builder.md)). +8. Keep unsupported, unauthorized, and unconfigured routes disabled. + +## Fake-first contract suite + +Use fake HTTP servers and fixtures for: + +- success and chunk-boundary variation; +- malformed/unknown fields and structured errors; +- disconnect and cancellation at every visible-output boundary; +- throttling, timeout, server error, retry eligibility, and backpressure; +- usage/reservation/reconciliation and duplicate idempotency keys; +- secret/header/prompt redaction in logs, crashes, metrics, diagnostics, and support exports. + +Direct Router/Tower calls cover most HTTP contracts without a live listener ([research](../research/async/2026-07-24-axum-service-testing.md)); keep a narrow loopback test for bind/shutdown/stream disconnect. + +## Prohibited effects + +Do not use live credentials, paid/subscription traffic, public endpoints, signing identity, or provider activation unless the gate explicitly authorizes them. Adapter implementation never gives a provider tools, approvals, filesystem/repository access, memory, or user interaction. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.cursor/skills/rust-stinger/guides/07-build-cli-and-tui.md b/.cursor/skills/rust-stinger/guides/07-build-cli-and-tui.md new file mode 100644 index 00000000..e1a7730d --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/07-build-cli-and-tui.md @@ -0,0 +1,30 @@ +# 07 — Build CLI and TUI surfaces + +## Purpose + +Build operable, scriptable, redacted operator clients without creating a second control authority. This guide covers Command Brief action 8. + +## CLI contract + +- Model commands and constrained arguments with Clap typed parsers and subcommands ([research](../research/cli-tui/2026-07-24-clap-parser.md)). +- Test parsing with non-exiting APIs; decide printing and process exit only at the binary boundary. +- Keep human help/errors separate from stable JSON/stdout schemas. Clap exposes rendering and exit information, but human formatting is not a machine protocol ([research](../research/cli-tui/2026-07-24-clap-errors.md)). +- Define a domain exit-code taxonomy for operational failures. +- Require a reviewed confirmation or explicit noninteractive policy for destructive or billable commands; keep them disabled if absent. +- Make diagnostics/support exports previewable, double-redacted, and free of prompt bodies, code, raw credentials, headers, and unsalted account identifiers. + +## Optional TUI contract + +- Keep the TUI feature-gated and thin over the same authenticated control client as the CLI. +- Prefer the main Ratatui crate unless a lower-level crate is specifically required; upstream recommends this for ordinary applications ([research](../research/cli-tui/2026-07-24-ratatui-architecture.md)). +- Use Ratatui's managed `run` lifecycle or explicitly handle fallible init/restore so success, error, panic, and cancellation restore the terminal ([research](../research/cli-tui/2026-07-24-ratatui-lifecycle.md)). +- Unit-test widgets against buffers and integration-test the whole UI with `TestBackend` ([research](../research/cli-tui/2026-07-24-ratatui-test-backend.md)). +- Add narrow platform/real-terminal smoke tests only where the supported matrix requires them. + +## Open decision checkpoint + +> TODO: human decision before implementation — whether the TUI is in the first executable milestone remains unresolved. + +## Worked examples + +See [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md) and [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md). diff --git a/.cursor/skills/rust-stinger/guides/08-verify-and-package-evidence.md b/.cursor/skills/rust-stinger/guides/08-verify-and-package-evidence.md new file mode 100644 index 00000000..9796ac2c --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/08-verify-and-package-evidence.md @@ -0,0 +1,54 @@ +# 08 — Verify and package evidence + +## Purpose + +Run the complete owned Rust gate and generate reviewable package evidence without claiming peer acceptance or performing unauthorized external effects. This guide covers Command Brief action 9. + +## Verification ladder + +Adapt exact commands to the repository and record every result. + +```bash +cargo fmt --all -- --check +cargo check --workspace --all-targets +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo test --workspace --doc +cargo metadata --format-version 1 +cargo tree --workspace -e features +``` + +Add declared minimal/default/all-feature builds, MSRV checks, target builds, migration/concurrency/crash/fake-provider tests, property/model tests, benchmarks, and soak checks. Clippy guidance recommends `-Dwarnings` with the same compiler toolchain as compilation; new lints make the result toolchain-specific ([research](../research/rust-cargo/2026-07-24-clippy-ci.md)). Nextest does not run doctests, so retain a separate doc-test step ([research](../research/testing/2026-07-24-nextest.md)). + +## Evidence layers + +- Unit/contract: pure logic and direct Tower/Axum calls. +- Deterministic time: Tokio paused clock for time-driven behavior ([research](../research/testing/2026-07-24-tokio-time-testing.md)). +- Property/state: proptest with saved seeds. +- Model concurrency: Loom only for small primitives expressed with Loom types ([research](../research/testing/2026-07-24-loom.md)). +- Persistence/process: real SQLite, multiple writers, fault injection, kill/restart. +- Provider/stream: fake servers and transcript fixtures. +- Benchmark: Criterion on a controlled host; statistics do not remove noisy-host risk ([research](../research/testing/2026-07-24-criterion-analysis.md)). +- Soak: purpose-built fake-provider run with periodic RSS, task, queue, DB/WAL, handle, throughput, and error telemetry. + +> TODO: human decision before release qualification — define quantitative soak thresholds; no universal off-the-shelf eight-hour harness or product threshold exists in the research packet. + +## Release evidence packet + +Populate `templates/release-evidence-manifest.yaml` with target artifacts, hashes, toolchain/lockfile, tests, SBOM, advisory/license/source scans, install/uninstall transcripts, and verification commands. + +- Revalidate cargo-dist before generating archives/installers; it supports target artifacts, checksums, and several installers, while checksums alone are unsigned integrity values ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md)). +- Generate target/feature-aware SBOM evidence and record tool version; cargo-cyclonedx added reproducible timestamp and target support in its retrieval-time release ([research](../research/supply-chain/2026-07-24-cargo-cyclonedx.md)). +- Record advisory database time and lockfile/artifact hash because RustSec findings are point-in-time ([research](../research/supply-chain/2026-07-24-rustsec.md)). +- Treat cargo-deny output as evidence for the dependency owner, not license/legal clearance ([research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). +- Treat Cargo's native SBOM precursor as optional/nightly until stabilized ([research](../research/supply-chain/2026-07-24-cargo-sbom-unstable.md)). +- Do not confuse `cargo package` verification with provenance; Cargo states provenance is not verified ([research](../research/supply-chain/2026-07-24-cargo-package-verification.md)). +- Do not sign or publish. Cosign signing can create identity/transparency-log effects and needs explicit authorization ([research](../research/supply-chain/2026-07-24-sigstore-cosign-blob.md)). + +## Open decision checkpoints + +> TODO: human decisions before release — supported targets/baselines, MSRV, installer formats, signing/attestation identity, and publication authorization. + +## Worked examples + +See [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [happy-path bounded service](../examples/01-happy-path-bounded-service-slice.md). diff --git a/.cursor/skills/rust-stinger/guides/09-close-the-loop.md b/.cursor/skills/rust-stinger/guides/09-close-the-loop.md new file mode 100644 index 00000000..dd6bedc9 --- /dev/null +++ b/.cursor/skills/rust-stinger/guides/09-close-the-loop.md @@ -0,0 +1,42 @@ +# 09 — Close the loop + +## Purpose + +Return acceptance-linked implementation evidence, limitations, recovery notes, and peer handoffs in the required order. This guide covers Command Brief action 10. + +## Completion procedure + +1. Re-read the requested acceptance criteria and current ledger/gates. +2. Run the final relevant Rust commands against the current tree; do not reuse stale results. +3. Populate `templates/implementation-handoff.md` with exact outcomes and changed paths. +4. For each criterion, cite a command, test, artifact, and result. +5. State external effects exactly: `none` or the recorded authorization/effect. +6. Explain migration, rollback, restart, and data recovery, including any irreversible step. +7. Explain prompt/secret/log/diagnostic handling and remaining Security questions. +8. Route the implemented state to Security. If fixes land, rerun affected implementation gates. +9. Route the post-Security state to Quality for final implementation-to-PRD audit. +10. Leave protocol, platform, dependency/license, CI/release, signing, publication, and other gates with their actual owners. + +## Evidence honesty rules + +- A current-stable toolchain is not a proven MSRV; Cargo requires verification of declared `rust-version` across supported functionality ([research](../research/rust-cargo/2026-07-24-cargo-rust-version.md)). +- A compiler-supported target is not a product-supported install/runtime target ([research](../research/rust-cargo/2026-07-24-platform-support.md)). +- Passing Loom is not general concurrency proof because unmodeled operations are invisible and state spaces are bounded ([research](../research/testing/2026-07-24-loom.md)). +- A retry-only test success is flaky evidence, not a clean pass ([research](../research/testing/2026-07-24-nextest-retries.md)). +- A generated checksum, SBOM, advisory scan, or license scan does not by itself prove signed provenance or peer acceptance ([research](../research/supply-chain/2026-07-24-cargo-dist-config.md), [research](../research/supply-chain/2026-07-24-cargo-deny-license-limitations.md)). + +## Blocked checkpoint + +When blocked, provide the smallest safe compilable/testable checkpoint if one exists, then name: + +- blocker and owning gate; +- affected acceptance criteria; +- files/tests completed; +- commands that passed, failed, or were unavailable; +- first authorized next action. + +Never call a partial checkpoint shipped or release-ready. + +## Worked examples + +See all four examples, especially [release evidence with closed gates](../examples/04-release-evidence-with-closed-gates.md) and [visible-output cancellation](../examples/02-edge-visible-output-cancellation.md). diff --git a/.cursor/skills/rust-stinger/reports/README.md b/.cursor/skills/rust-stinger/reports/README.md new file mode 100644 index 00000000..bdb75008 --- /dev/null +++ b/.cursor/skills/rust-stinger/reports/README.md @@ -0,0 +1,3 @@ +# Rust Stinger reports + +This folder accumulates dated implementation handoffs produced by `rust-worker-bee`; copy `implementation-handoff-report-template.md`, preserve exact command evidence, and never overwrite an earlier run. diff --git a/.cursor/skills/rust-stinger/reports/implementation-handoff-report-template.md b/.cursor/skills/rust-stinger/reports/implementation-handoff-report-template.md new file mode 100644 index 00000000..ccb48186 --- /dev/null +++ b/.cursor/skills/rust-stinger/reports/implementation-handoff-report-template.md @@ -0,0 +1,15 @@ +# Rust implementation handoff: {{slice_name}} + +Use the complete reusable form in [`../templates/implementation-handoff.md`](../templates/implementation-handoff.md). Store a populated copy here as `YYYY-MM-DD-{{slice_slug}}.md` only when the orchestrator designates this global Stinger as the report archive; product-specific evidence normally remains in the product's authorized artifact path. + +Required sections: + +1. Outcome +2. Authority and scope +3. Acceptance evidence +4. Changed paths +5. Verification +6. Safety and operations +7. Revalidation points +8. Peer handoffs and remaining gates +9. Blocker, if any diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md new file mode 100644 index 00000000..ac6314f7 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/serve/struct.Serve.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: axum +stinger: rust-stinger +--- + +# Axum server graceful shutdown + +## Summary +Axum's `Serve::with_graceful_shutdown` binds server lifetime to a supplied future. It stops accepting new work when the signal resolves and waits for connections according to the server's graceful behavior. Application-owned background tasks still need separate ownership and joining. + +## Key quotations / statistics +- "Prepares a server to handle graceful shutdown" +- The signal is a future "that resolves to `()`" + +## Version/date caveat +Axum latest docs at retrieval; exact connection-drain semantics depend on the matching hyper/axum versions. + +## Annotations for stinger-forge +- Use for the loopback listener shutdown path. +- Pair with Tokio task tracking; server shutdown alone does not prove all background work stopped. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md new file mode 100644 index 00000000..dd8c0e33 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-service-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/src/axum/routing/mod.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: testing +stinger: rust-stinger +--- + +# Axum router testing as a Tower service + +## Summary +Axum routers can be converted to borrowed or owned Tower services and invoked directly with requests. This avoids binding a real socket for most contract and middleware tests, making state, status, headers, and body behavior deterministic while reserving live-listener tests for integration boundaries. + +## Key quotations / statistics +- "Use `as_service` to get a borrowed `Service` from a `Router`." +- "Use `into_service` to get an owned `Service`" + +## Version/date caveat +Source docs for Axum latest; test helpers and body collection APIs vary across axum/http-body-util releases. + +## Annotations for stinger-forge +- Supports in-process HTTP contract tests without network flakiness. +- Loopback bind and shutdown still require a smaller dedicated integration test. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md new file mode 100644 index 00000000..2c2c12f0 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-axum-streaming-body.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/axum/latest/axum/body/struct.Body.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: streaming +stinger: rust-stinger +--- + +# Axum streaming bodies + +## Summary +Axum 0.8.9 wraps `http_body::Body` and can create a response body from a fallible `Stream`. Consumers pull frames asynchronously through `poll_frame`; converting to a data-only stream discards trailers. Backpressure therefore propagates through polling only if the upstream producer is itself bounded and cancellation-aware. + +## Key quotations / statistics +- `from_stream`: "Create a new `Body` from a `Stream`." +- `poll_frame`: "Attempt to pull out the next data buffer of this stream." + +## Version/date caveat +Axum 0.8.9, http-body 1.1.0 at retrieval. Frame/trailer behavior must match the selected HTTP contract. + +## Annotations for stinger-forge +- Core source for streaming body construction and disconnect/cancellation tests. +- Do not collect unbounded streams into memory; test that dropping the body stops producer work and releases permits. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md new file mode 100644 index 00000000..653ee9c7 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-graceful-shutdown.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/shutdown +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: shutdown +stinger: rust-stinger +--- + +# Tokio graceful shutdown + +## Summary +Tokio presents graceful shutdown as three explicit phases: detect the trigger, notify owned work, and wait for work to finish. It demonstrates cancellation tokens for cooperative notification and task trackers for joining all tracked work, allowing cleanup such as database flushes before termination. + +## Key quotations / statistics +- "Figuring out when to shut down." +- "Waiting for other parts of the program to shut down." + +## Version/date caveat +Conceptual Tokio topic page; exact APIs may live in `tokio-util` and must match the selected versions. + +## Annotations for stinger-forge +- Core source for task ownership and shutdown checklists. +- Supports a root cancellation token plus explicit join/timeout/escalation evidence. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md new file mode 100644 index 00000000..c0c0d4cf --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-mpsc.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: backpressure +stinger: rust-stinger +--- + +# Tokio bounded MPSC channels + +## Summary +Tokio's bounded MPSC channel supplies backpressure by suspending senders when capacity is exhausted. Clean shutdown closes the receiver and drains buffered values; dropping the receiver drains and drops unread messages. Unbounded channels have infinite logical capacity and therefore cannot express a memory/backpressure bound. + +## Key quotations / statistics +- "the channel provides backpressure" +- "the receiver first calls `close`, which will prevent any further messages" + +## Version/date caveat +Retrieved against Tokio 1.53.1. Allocation details are explicitly implementation details and may change. + +## Annotations for stinger-forge +- Grounds bounded queue requirements and shutdown draining tests. +- Supports rejecting unbounded queues on stream/provider hot paths without a proven upper bound. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md new file mode 100644 index 00000000..d86db676 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-release-policy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/tokio/latest +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: tokio +stinger: rust-stinger +--- + +# Tokio current release and support policy + +## Summary +Docs.rs records Tokio 1.53.1 released 2026-07-20. Tokio states that 1.51.x is LTS through March 2027 with MSRV 1.71, while current minor releases may move faster. A fixed-minor daemon dependency can choose an LTS line, but the choice must be reconciled with required APIs and security fixes. + +## Key quotations / statistics +- "1.53.1 (2026-07-20)" +- "`1.51.x` - LTS release until March 2027. (MSRV 1.71)" + +## Version/date caveat +Patch versions and LTS designations can change; this is a retrieval-time snapshot. + +## Annotations for stinger-forge +- Use to frame current versus LTS version policy without choosing on the release peer's behalf. +- Record the transitive-dependency MSRV caveat stated by Tokio. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md new file mode 100644 index 00000000..09e162ed --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-select-cancellation.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/tokio/macro.select.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: cancellation +stinger: rust-stinger +--- + +# Tokio `select!` cancellation safety + +## Summary +Tokio defines cancellation safety as dropping and recreating an incomplete future without observable loss. The docs enumerate safe and unsafe operations and warn that loops using non-cancellation-safe futures can lose data when another branch wins. This must be checked per awaited operation, not assumed because code is async. + +## Key quotations / statistics +- "it must be a no-op to drop that future and recreate it" +- "The lists in this section are not exhaustive." + +## Version/date caveat +Retrieved against Tokio 1.53.1; method-level cancellation guarantees may change and should be linked directly in code review. + +## Annotations for stinger-forge +- Core source for cancellation audits around streams, writes, queues, and database work. +- Supports focused tests for the exact boundary where visible output makes replay forbidden. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md new file mode 100644 index 00000000..60756cfc --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tokio-send-reserve.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tokio/latest/src/tokio/sync/mpsc/bounded.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: permits +stinger: rust-stinger +--- + +# Tokio MPSC reserve and cancellation + +## Summary +The bounded-channel source documentation says cancelling `send` loses the message and the sender's queue position. Reserving capacity first returns a permit so message construction can occur only after capacity is secured. Outstanding permits also delay a receiver from observing final closure. + +## Key quotations / statistics +- "the message is dropped and will be lost" +- "To avoid losing messages, use `reserve`" + +## Version/date caveat +Source documentation for Tokio latest (1.53.1 at retrieval); treat internal implementation as unstable while relying on documented public behavior. + +## Annotations for stinger-forge +- Supports reserve-before-expensive-work and cancellation-focused queue tests. +- Shutdown code must account for outstanding permits, not only sender handles. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md new file mode 100644 index 00000000..dcce062a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: middleware +stinger: rust-stinger +--- + +# Tower concurrency, buffering, and load shedding + +## Summary +`ServiceBuilder` exposes concurrency limits, buffers, timeouts, and load shedding as composable layers. Concurrency limits count in-flight requests through response-future completion. Load shedding converts lack of readiness into an immediate error rather than waiting. Layer order changes which work is bounded and which errors are visible. + +## Key quotations / statistics +- "Limit the max number of in-flight requests." +- "`LoadShed` immediately responds with an error" + +## Version/date caveat +Feature-gated Tower APIs; selected crate features and layer order must be recorded in the workspace. + +## Annotations for stinger-forge +- Supports explicit capacity/timeout/load-shed policy and layer-order tests. +- Protocol error mapping remains a peer decision; this source only establishes middleware behavior. + diff --git a/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md b/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md new file mode 100644 index 00000000..974e3456 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/async/2026-07-24-tower-service-readiness.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tower/latest/tower/trait.Service.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: readiness +stinger: rust-stinger +--- + +# Tower `Service` readiness contract + +## Summary +Tower separates readiness from dispatch. Callers must observe `poll_ready` before `call`; readiness may reserve shared resources, which implementations must release if dispatch never occurs or the response future is dropped. Capacity is therefore an ownership contract, not merely a performance hint. + +## Key quotations / statistics +- "Before dispatching a request, `poll_ready` must be called" +- readiness "may reserve shared resources" + +## Version/date caveat +Tower latest docs at retrieval; middleware can alter readiness semantics by layer order. + +## Annotations for stinger-forge +- Core evidence for backpressure-aware Tower services and adapters. +- Supports tests that cancel between readiness and call and assert permit/resource release. + diff --git a/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md new file mode 100644 index 00000000..fc5a2b46 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-container-attributes.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/container-attrs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: validation +stinger: rust-stinger +--- + +# Serde container boundary attributes + +## Summary +Serde's container attributes allow unknown-field rejection, fallible conversion through `try_from`, transparent newtypes, defaults, and explicit tagging. Unknown fields are ignored by default in self-describing formats, so strict control/config inputs require an intentional choice rather than assuming fail-closed parsing. + +## Key quotations / statistics +- `deny_unknown_fields` will "Always error during deserialization when encountering unknown fields." +- By default, "unknown fields are ignored" + +## Version/date caveat +`deny_unknown_fields` cannot be combined with `flatten`; compatibility policy must account for that limitation. + +## Annotations for stinger-forge +- Grounds strict config/control-plane parsing and validated newtypes. +- Use separate input DTOs when forward-compatible wire payloads must retain unknown fields. + diff --git a/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md new file mode 100644 index 00000000..f2e288b8 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-serde-enum-representations.md @@ -0,0 +1,26 @@ +--- +source_url: https://serde.rs/enum-representations.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: serde +stinger: rust-stinger +--- + +# Serde enum representations + +## Summary +Serde supports externally, internally, adjacently, and untagged enum encodings. Tagged enums make the selected variant explicit before or alongside content; untagged enums try variants in order and accept the first successful parse. For safety-state and protocol boundaries, representation choice affects ambiguity, forward compatibility, and error quality. + +## Key quotations / statistics +- Externally tagged data identifies "which variant we are dealing with before beginning to parse" +- Untagged "will try to match the data against each variant in order" + +## Version/date caveat +Serde project documentation; specific derive behavior still depends on the pinned serde version and enabled `alloc` feature. + +## Annotations for stinger-forge +- Supports explicit tagged enums for state/event boundaries where ambiguity is unacceptable. +- Protocol wire encoding remains the protocol peer's contract. + diff --git a/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md new file mode 100644 index 00000000..692d0b6e --- /dev/null +++ b/.cursor/skills/rust-stinger/research/boundaries/2026-07-24-thiserror.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/thiserror/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: errors +stinger: rust-stinger +--- + +# thiserror structured errors + +## Summary +thiserror 2.0.19 derives standard error implementations without becoming part of the public API contract. `source`, `from`, and `transparent` preserve causal chains, while an opaque public wrapper can hide a private evolving representation. Redaction still depends on the chosen fields and Display text. + +## Key quotations / statistics +- "Errors may use `error(transparent)` to forward the source and Display methods" +- "hiding implementation details ... behind an opaque error type" + +## Version/date caveat +Version 2.0.19 was published six days before retrieval; pin and test formatting if machine parsing depends on it. + +## Annotations for stinger-forge +- Supports domain error enums at crate boundaries and opaque public errors. +- Do not place secrets/prompts in source error values or formatted context. + diff --git a/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md new file mode 100644 index 00000000..e079d17a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-errors.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/type.Error.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: exits +stinger: rust-stinger +--- + +# Clap error and exit behavior + +## Summary +Clap errors expose their kind, rendered form, stderr/stdout routing, printing, and exit code. Library/test paths can use non-exiting parse APIs, while the process boundary decides when to print and exit. Operational failures after parsing need a separate stable exit-code taxonomy. + +## Key quotations / statistics +- The error API includes `exit_code`. +- The error API includes `use_stderr` and `render`. + +## Version/date caveat +Clap 4.6.2 at retrieval; exact human rendering is not a stable machine protocol. + +## Annotations for stinger-forge +- Supports separating parse errors from domain/transport exit codes. +- Require JSON/stdout contracts to avoid scraping colored human help/error output. + diff --git a/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md new file mode 100644 index 00000000..f15fca06 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-clap-parser.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/clap/latest/clap/parser/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: clap +stinger: rust-stinger +--- + +# Clap typed command-line parsing + +## Summary +Clap 4.6.2 provides `Parser`, `Subcommand`, `Args`, `CommandFactory`, and `ValueEnum` traits for typed command structures and introspection. These types support explicit command inventories, constrained values, generated help/completions, and parser tests independent of process execution. + +## Key quotations / statistics +- `ValueEnum`: "Parse arguments into enums." +- `CommandFactory`: "Create a `Command` relevant for a user-defined container." + +## Version/date caveat +Clap 4.6.2 at retrieval; help text and formatting can change across minor releases. + +## Annotations for stinger-forge +- Supports typed subcommands and deterministic parser contract tests. +- Machine-readable command output is an application schema layered above Clap. + diff --git a/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md new file mode 100644 index 00000000..98784587 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-architecture.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: medium +topic: tui +stinger: rust-stinger +--- + +# Ratatui crate architecture + +## Summary +Ratatui's primary crate re-exports the application-facing surface, while lower-level workspace crates exist for custom widget libraries and backend-specific integrations. The docs recommend staying in the main crate unless a lower-level dependency is specifically needed, reducing feature and compile-time surface for ordinary applications. + +## Key quotations / statistics +- "Most application authors should stay in this `ratatui` crate." +- "Reach for other crates ... only when you specifically need a lower-level layer" + +## Version/date caveat +Ratatui 0.30.2; workspace decomposition may evolve. + +## Annotations for stinger-forge +- Supports avoiding premature internal TUI crate fragmentation. +- Feature-gate the entire TUI and keep domain/control logic outside it. + diff --git a/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md new file mode 100644 index 00000000..bc52308f --- /dev/null +++ b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-lifecycle.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/init/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: terminal +stinger: rust-stinger +--- + +# Ratatui terminal initialization and restoration + +## Summary +Ratatui 0.30.2 recommends `run` for ownership of terminal setup/cleanup, or fallible `try_init`/`try_restore` when the application needs explicit handling. Helpers manage raw mode, alternate screen, and a panic hook that restores the terminal. Manual construction transfers teardown responsibility to the application. + +## Key quotations / statistics +- `run` "automatically restores the terminal state" +- "All initialization functions install a panic hook" + +## Version/date caveat +`run` was introduced in 0.30.0; older examples may show manual lifecycle code. + +## Annotations for stinger-forge +- Grounds terminal cleanup on success, error, panic, and cancellation. +- Favor the headless CLI/control client; keep the TUI a thin optional surface. + diff --git a/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md new file mode 100644 index 00000000..afcd9d15 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/cli-tui/2026-07-24-ratatui-test-backend.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/ratatui/latest/ratatui/backend/struct.TestBackend.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: rendering +stinger: rust-stinger +--- + +# Ratatui `TestBackend` + +## Summary +Ratatui's `TestBackend` renders an integration-level terminal UI to an in-memory buffer and can assert lines, cursor, resize, and scrollback. The docs prefer direct widget-buffer tests for units and reserve `TestBackend` for whole-TUI integration, giving two appropriately sized evidence layers. + +## Key quotations / statistics +- "renders to an memory buffer" +- "preferable to write unit tests for widgets directly against the buffer" + +## Version/date caveat +Ratatui 0.30.2 at retrieval; snapshot glyph/width behavior can vary with terminal/unicode dependencies. + +## Annotations for stinger-forge +- Supports deterministic TUI rendering tests without a real terminal. +- Add narrow real-terminal smoke tests only where lifecycle/platform integration matters. + diff --git a/.cursor/skills/rust-stinger/research/evidence-synthesis.md b/.cursor/skills/rust-stinger/research/evidence-synthesis.md new file mode 100644 index 00000000..70a55448 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/evidence-synthesis.md @@ -0,0 +1,178 @@ +# Rust Stinger Evidence Synthesis + +This is an evidence map for Stinger Forge, not a replacement for the product ADR, protocol contract, Security review, dependency/license decision, release authorization, or Quality report. The 56 indexed source notes are authoritative inputs; this file connects them to the Command Brief's research questions and records the remaining decisions honestly. +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +Snapshot: 2026-07-24. Version-sensitive values are evidence snapshots, not timeless defaults; revalidate at the point of use. + +## Current anchors at retrieval + +| Surface | Current evidence snapshot | Caveat | +|---|---|---| +| Rust | 1.97.1 released 2026-07-16 | Current stable is not automatically the product MSRV. | +| Cargo | Rust 2024 resolver v3; `rust-version`-aware fallback | Virtual workspaces must declare the resolver; CI must prove MSRV. | +| Tokio | 1.53.1 released 2026-07-20; 1.51.x LTS through March 2027 | Tokio's MSRV does not establish the whole graph's MSRV. | +| Axum | 0.8.9 docs snapshot | Pin compatible hyper/http-body/tower versions together. | +| SQLx | 0.9.0 docs snapshot | `begin_with` is version-specific; verify before applying to SQLx 0.8. | +| Clap / Ratatui | 4.6.2 / 0.30.2 | Human rendering and TUI APIs can change across minor versions. | +| rustls | 0.23.42 stable docs; 0.24 development docs also visible | Avoid accidental dependency on development APIs. | +| Testing | Loom 0.7.2; Criterion 0.8.2 | Model and benchmark results have explicit coverage/environment limits. | +| SBOM | cargo-cyclonedx 0.5.9 (2026-03-19) | Cargo native SBOM precursors remain unstable/nightly. | + +## 1. Tokio, Axum, and Tower ownership, cancellation, streaming, and shutdown + +The sources converge on a verifiable lifecycle made of distinct obligations: + +1. A root owner detects shutdown, signals cooperative cancellation, stops admission, and waits for every owned task. Tokio's shutdown guide explicitly separates trigger, notification, and joining. +2. Bounded MPSC channels express a capacity contract. Clean shutdown closes the receiver and drains it. `send` inside `select!` may lose the message; `reserve` obtains capacity first and makes that boundary testable. +3. Every `select!` branch needs method-level cancellation review. "Async" alone does not imply cancellation safety. +4. Tower readiness is a resource reservation. `poll_ready` must precede `call`, and capacity must be released if dispatch or its future is dropped. Concurrency-limit, buffer, timeout, and load-shed layer order changes observable behavior. +5. Axum can serve a fallible stream as a response body. HTTP consumers pull frames; the upstream producer must still be bounded and cancellation-aware. Dropping/disconnecting the body should stop producer work and release permits in focused tests. +6. `with_graceful_shutdown` owns listener/connection admission, not arbitrary background work. Background task ownership remains in Tokio task tracking. +7. Most router/middleware contracts can be tested by invoking the Router as a Tower service without binding a port. A narrower loopback integration test proves bind address, shutdown, and disconnect behavior. + +Primary notes: [Tokio shutdown](async/2026-07-24-tokio-graceful-shutdown.md), [MPSC](async/2026-07-24-tokio-mpsc.md), [`select!`](async/2026-07-24-tokio-select-cancellation.md), [reserve](async/2026-07-24-tokio-send-reserve.md), [Tower readiness](async/2026-07-24-tower-service-readiness.md), [Tower layers](async/2026-07-24-tower-service-builder.md), [Axum shutdown](async/2026-07-24-axum-graceful-shutdown.md), [Axum streaming](async/2026-07-24-axum-streaming-body.md), and [service testing](async/2026-07-24-axum-service-testing.md). + +## 2. SQLite and SQLx transactions, locking, and durability + +SQLite permits a single writer. `BEGIN DEFERRED` can read a stale budget view and then fail during write upgrade; `BEGIN IMMEDIATE` acquires write intent before the read-modify-write sequence. SQLx 0.9's `Connection::begin_with` provides a tracked custom transaction start, enabling `BEGIN IMMEDIATE` while preserving explicit commit/rollback and rollback-on-drop behavior. + +Evidence-supported invariants for reservations/reconciliations/breakers/migrations: + +- Acquire the write transaction before reading mutable budget/quota state. +- Keep eligibility check, reservation insert/update, aggregate update, and idempotency record in one transaction. +- Use conditional SQL constraints/updates as the final oversubscription guard; application locks are not sufficient across processes. +- Treat `SQLITE_BUSY` as a bounded, observable contention result. A busy timeout is not permission for invisible unbounded retry. +- Configure and verify journal mode, synchronous level, foreign keys, busy timeout, and checkpoint policy through one connection-options path. +- WAL improves reader/writer concurrency but does not allow multiple writers. Long readers can starve checkpoints and grow the WAL. +- WAL plus `synchronous=NORMAL` can lose recent committed transactions after power loss. Product durability language must match the chosen PRAGMA contract. +- Crash evidence should kill/restart at transaction and checkpoint boundaries and verify all-or-none invariants. Preserve the database and its WAL/SHM/journal companions during recovery. +- Embedded migrations improve delivery but do not replace forward-only migration, old-binary/new-schema compatibility, and interruption tests. + +Primary notes: [transactions](persistence/2026-07-24-sqlite-transactions.md), [WAL](persistence/2026-07-24-sqlite-wal.md), [atomic commit](persistence/2026-07-24-sqlite-atomic-commit.md), [PRAGMAs](persistence/2026-07-24-sqlite-pragma-durability.md), [SQLx options](persistence/2026-07-24-sqlx-connect-options.md), [custom transactions](persistence/2026-07-24-sqlx-custom-transactions.md), and [queries/migrations](persistence/2026-07-24-sqlx-migrations-queries.md). + +## 3. Typed state machines and replay/promotion proof + +Rust's enums, newtypes, privacy, exhaustive matching, and ownership can make invalid transitions difficult to express. The strongest upstream example in this corpus is rustls: private marker values bind the fact that verification occurred and prevent skipping required checks before entering the traffic state. + +Evidence-supported design constraints for Forge to encode: + +- Persist durable facts as an explicit tagged enum/event schema; avoid ambiguous untagged parsing for safety state. +- Reject unknown fields on strict local control/config inputs unless an explicit compatibility contract requires otherwise. +- Use private constructors and non-forgeable capability/marker types for facts such as `NoVisibleOutput`, `NoToolCall`, `ReservationHeld`, or `SafeTurnReviewed`. +- Consume one-shot proof values on transition so replay/promotion cannot accidentally reuse authorization. +- Keep provider events and harness events in edge crates, normalize them into protocol-neutral domain facts, and let the state machine depend only on those facts. +- Represent terminal/irreversible states explicitly and test every transition plus serialization round trip against a reference model. +- Keep user-visible error codes separate from internal causal chains; neither should contain prompts, raw credentials, or headers. + +Primary notes: [Serde enums](boundaries/2026-07-24-serde-enum-representations.md), [strict attributes](boundaries/2026-07-24-serde-container-attributes.md), [thiserror](boundaries/2026-07-24-thiserror.md), [rustls builder typestate](security/2026-07-24-rustls-config-builder.md), and [verification markers](security/2026-07-24-rustls-verification-markers.md). + +## 4. Cargo workspace and MSRV evidence + +Resolver v3 is global at the top-level workspace. Features remain additive and can unify through dependency paths, so crate boundaries and feature design must prevent provider/TUI/TLS choices from leaking into protocol, policy, and state cores. + +A reviewable dependency direction for the accepted architecture is: + +```text +protocol/types <- policy/state <- provider adapters + ^ ^ ^ + | | | + daemon/control ----+--------------+ + ^ + CLI <- optional TUI + +test-support/evaluation may depend on public seams; +production crates must not depend on test-support. +``` + +This is a research-derived dependency constraint, not approval of exact crate names. Workspace review should look for: + +- one owner per invariant rather than a crate per noun; +- `resolver = "3"` in a virtual workspace; +- shared dependency versions/features declared centrally where that reduces drift; +- provider and TUI features default-off unless the product requires otherwise; +- `cargo tree -e features`, all-target/all-feature checks, and representative minimal-feature checks; +- public types flowing inward only from the approved protocol/domain crate, never harness/provider SDK types; +- a documented unsafe inventory, defaulting to `forbid(unsafe_code)` where possible. + +For a new removable local daemon, the credible starting toolchain is a pinned current stable release (1.97.1 at retrieval), with `package.rust-version` declared only after the full resolved graph and advertised features pass MSRV CI. Tokio 1.51.x is an available 2026 LTS line with MSRV 1.71, but that fact alone is not a reason to choose Rust 1.71 for the product. Re-check stable, platform tiers, and dependency MSRVs immediately before Forge freezes guidance. + +Primary notes: [current Rust](rust-cargo/2026-07-24-rust-release-1-97.md), [`rust-version`](rust-cargo/2026-07-24-cargo-rust-version.md), [resolver v3](rust-cargo/2026-07-24-cargo-resolver-v3.md), [features](rust-cargo/2026-07-24-cargo-features.md), [platform tiers](rust-cargo/2026-07-24-platform-support.md), [Cargo CI](rust-cargo/2026-07-24-cargo-ci-msrv.md), [Clippy](rust-cargo/2026-07-24-clippy-ci.md), and [Tokio release policy](async/2026-07-24-tokio-release-policy.md). + +## 5. Tracing, secrets, and TLS + +- `#[instrument]` captures all arguments by default, including Debug output. Sensitive functions should start from `skip_all` and add allowlisted identifiers/state fields. +- Libraries emit structured spans/events; binaries own subscriber/filter/sink initialization. Libraries should not set the global subscriber. +- Secret wrappers reduce accidental exposure and require explicit access, but do not replace a secret store and cannot prevent every copy during deserialization. +- rustls stable builders encode mandatory verifier/certificate choices and use safe defaults. Custom verifier APIs are deliberately marked dangerous and require Security review. +- TLS/provider selection, certificate roots, egress/redirect/DNS/SSRF controls, redaction acceptance, and crash-dump policy remain Security/platform decisions. + +Primary notes: [instrument capture](observability/2026-07-24-tracing-instrument.md), [subscriber ownership](observability/2026-07-24-tracing-subscriber.md), [secrecy](security/2026-07-24-secrecy.md), and [rustls](security/2026-07-24-rustls-config-builder.md). + +## 6. CLI and TUI evidence + +Clap supports typed subcommands, constrained enums, introspection, and non-exiting parse paths. Human help/error formatting should not become the machine protocol; define stable JSON/stdout schemas and a separate domain exit-code taxonomy. Destructive or billable commands need an explicit confirmation/noninteractive policy above Clap. + +Ratatui 0.30's `run` owns terminal initialization and restoration, including panic cleanup. Fallible init/restore APIs exist for explicit error handling. `TestBackend` provides deterministic integration rendering; direct buffer/widget tests are preferred for units. The TUI should remain feature-gated and depend on the same authenticated control client as the CLI rather than becoming a second authority. + +Primary notes: [Clap parser](cli-tui/2026-07-24-clap-parser.md), [Clap errors](cli-tui/2026-07-24-clap-errors.md), [terminal lifecycle](cli-tui/2026-07-24-ratatui-lifecycle.md), [TestBackend](cli-tui/2026-07-24-ratatui-test-backend.md), and [Ratatui architecture](cli-tui/2026-07-24-ratatui-architecture.md). + +## 7. Verification stack, including eight-hour soak evidence + +| Evidence layer | Primary mechanism | What it proves | Main limitation | +|---|---|---|---| +| Unit/contract | `cargo test`, direct Axum/Tower service calls | Pure logic, types, HTTP/service contracts | Does not prove listener/process behavior. | +| Deterministic time | Tokio `start_paused`, injected clocks | Timeouts, retry schedules, breakers, pins, promotion windows | Only controlled clocks advance. | +| Property/state | proptest + persisted seeds | Invariants across generated values/transition sequences | Current state-machine helper is sequential. | +| Model concurrency | Loom on small primitives | Explored synchronization interleavings | Requires Loom types; state explosion; not DB/process proof. | +| Persistence/concurrency | real temp SQLite, multiple connections/processes, fault injection | Write contention, idempotency, migration and crash recovery | Needs platform/filesystem coverage. | +| Provider/stream | fake HTTP servers and transcript fixtures | chunk ordering, cancellation, replay boundary, error normalization | Fixture drift must be managed; no live credentials. | +| Suite execution | cargo-nextest profiles, timeouts, JUnit | Isolation, classification, evidence export | Doctests remain separate; retries can mask flaws. | +| Microbenchmark | Criterion on controlled hosts | throughput/latency trends with confidence intervals | Noisy shared CI can mislead. | +| Eight-hour soak | purpose-built release harness under nextest/process supervisor | bounded memory/queues, handle/task cleanup, WAL growth/checkpoints, reconnect stability | No single crate proves this; requires explicit invariants and periodic telemetry. | + +An eight-hour soak should use fake providers and local fixtures, emit periodic bounded metrics (RSS, task count, queue depth, DB/WAL size, open handles, request/error counters), assert no monotonic leak or invariant breach, capture start/end versions/config/seeds, and fail on flaky retry. It is separate from Criterion and from Loom. + +Primary notes: [proptest state machines](testing/2026-07-24-proptest-state-machines.md), [Loom](testing/2026-07-24-loom.md), [Tokio time](testing/2026-07-24-tokio-time-testing.md), [nextest](testing/2026-07-24-nextest.md), [flaky retries](testing/2026-07-24-nextest-retries.md), and [Criterion](testing/2026-07-24-criterion-analysis.md). + +## 8. Packaging, SBOM, signing, and advisory evidence + +A credible 2026 release-evidence packet can contain target-specific archives/installers, hashes, install/uninstall transcripts, SBOM, embedded dependency metadata, advisory/license/source scan results, and provenance/signature verification. The tools have complementary roles: + +- cargo-dist builds target archives/installers and hashes; generated output and tool version must be pinned/reviewed. +- cargo-cyclonedx generates standardized SBOMs and supports `SOURCE_DATE_EPOCH`/target-aware output as of 0.5.9. +- cargo-auditable embeds dependency information in binaries for later scanning. +- cargo-deny supplies advisory/license/ban/source policy evidence but does not prove legal clearance. +- RustSec/cargo-audit produces point-in-time lockfile/binary advisory findings; record database time and lockfile/artifact hash. +- Cosign signs blobs and emits verification bundles; signing/publishing is an explicitly authorized external effect. +- Cargo's native SBOM precursor is still unstable/nightly and should remain supplemental for a stable baseline. +- `cargo package` verifies crate contents/buildability but explicitly does not prove provenance. + +Primary notes: [dist config](supply-chain/2026-07-24-cargo-dist-config.md), [dist attestations](supply-chain/2026-07-24-cargo-dist-attestations.md), [cargo-cyclonedx](supply-chain/2026-07-24-cargo-cyclonedx.md), [cargo-auditable](supply-chain/2026-07-24-cargo-auditable.md), [cargo-deny](supply-chain/2026-07-24-cargo-deny-checks.md), [license limits](supply-chain/2026-07-24-cargo-deny-license-limitations.md), [RustSec](supply-chain/2026-07-24-rustsec.md), [cargo-audit](supply-chain/2026-07-24-cargo-audit.md), [Cosign](supply-chain/2026-07-24-sigstore-cosign-blob.md), [Cargo SBOM](supply-chain/2026-07-24-cargo-sbom-unstable.md), and [cargo package](supply-chain/2026-07-24-cargo-package-verification.md). + +## Peer-boundary map + +| Area | Rust Bee may implement/prove | Peer retains final authority | +|---|---|---| +| HTTP/MCP/provider protocol | Approved types, adapters, fixtures, streaming behavior | Protocol semantics and compatibility | +| Security/TLS/secrets/logs | Safe defaults, redaction mechanics, tests | Threat model and acceptance | +| SQLite/SQLx | Transactions, migrations, concurrency/crash tests | Schema/data architecture review | +| Dependencies/SBOM/licenses | Generate exact reports/artifacts | Exceptions, license/advisory disposition | +| Release/CI | Rust build/package configuration and local proof | CI topology, signing identity, publication | +| Quality | Acceptance-linked implementation evidence | Final PRD implementation audit | + +## Open decisions for the user/orchestrator + +1. Exact supported OS/architecture/install matrix and minimum OS/glibc baselines. +2. Whether the initial toolchain pins current stable or a selected older stable after the dependency graph exists; no evidence supports claiming an MSRV before that graph is tested. +3. Required power-loss durability: WAL `FULL`, WAL `NORMAL`, or another documented contract. +4. Maximum writer wait/busy timeout and user-visible contention behavior. +5. Exact state/event schema for visible output, tool calls, reservation, replay prohibition, and safe-turn promotion. +6. Whether the optional TUI is inside the first executable milestone. +7. Release signing identity/attestation platform and which installer formats are authorized. +8. Quantitative pass/fail thresholds for the eight-hour soak (RSS slope, WAL growth, task/handle counts, throughput/error rate). + +## Tool provenance limitation + +The research packet uses the configured Context7 service plus current direct official/upstream documentation retrieval. No raw web-crawl JSON exists; this limitation is explicit so Forge does not mistake the corpus for a web-crawl corpus. + diff --git a/.cursor/skills/rust-stinger/research/index.md b/.cursor/skills/rust-stinger/research/index.md new file mode 100644 index 00000000..9636d31a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/index.md @@ -0,0 +1,64 @@ +# Research Index: rust-stinger + +Generated by scripture-historian. Updated after every source-file write. + +Snapshot: 2026-07-24. Version-sensitive values in this packet are evidence snapshots, not timeless defaults; revalidate at the point of use. + +| File | Source type | Authority | Relevance | Topic | +|---|---|---|---|---| +| `rust-cargo/2026-07-24-rust-release-1-97.md` | changelog | official | critical | toolchain | +| `rust-cargo/2026-07-24-cargo-rust-version.md` | official-docs | official | critical | msrv | +| `rust-cargo/2026-07-24-cargo-resolver-v3.md` | official-docs | official | critical | resolver | +| `rust-cargo/2026-07-24-cargo-features.md` | official-docs | official | high | features | +| `rust-cargo/2026-07-24-platform-support.md` | official-docs | official | critical | targets | +| `rust-cargo/2026-07-24-cargo-ci-msrv.md` | official-docs | official | high | ci | +| `rust-cargo/2026-07-24-clippy-ci.md` | official-docs | official | high | linting | +| `rust-cargo/2026-07-24-unsafe-rust.md` | official-docs | official | high | unsafe | +| `async/2026-07-24-tokio-release-policy.md` | changelog | official | critical | tokio | +| `async/2026-07-24-tokio-graceful-shutdown.md` | official-docs | official | critical | shutdown | +| `async/2026-07-24-tokio-mpsc.md` | official-docs | official | critical | backpressure | +| `async/2026-07-24-tokio-select-cancellation.md` | official-docs | official | critical | cancellation | +| `async/2026-07-24-tokio-send-reserve.md` | official-docs | official | high | permits | +| `async/2026-07-24-tower-service-readiness.md` | official-docs | official | critical | readiness | +| `async/2026-07-24-tower-service-builder.md` | official-docs | official | high | middleware | +| `async/2026-07-24-axum-graceful-shutdown.md` | official-docs | official | critical | axum | +| `async/2026-07-24-axum-service-testing.md` | official-docs | official | high | testing | +| `async/2026-07-24-axum-streaming-body.md` | official-docs | official | critical | streaming | +| `persistence/2026-07-24-sqlite-transactions.md` | official-docs | official | critical | transactions | +| `persistence/2026-07-24-sqlite-wal.md` | official-docs | official | critical | wal | +| `persistence/2026-07-24-sqlite-atomic-commit.md` | official-docs | official | critical | recovery | +| `persistence/2026-07-24-sqlite-pragma-durability.md` | official-docs | official | critical | durability | +| `persistence/2026-07-24-sqlx-connect-options.md` | official-docs | official | critical | sqlx | +| `persistence/2026-07-24-sqlx-migrations-queries.md` | official-docs | official | high | migrations | +| `persistence/2026-07-24-sqlx-custom-transactions.md` | official-docs | official | critical | locking | +| `boundaries/2026-07-24-serde-enum-representations.md` | official-docs | official | critical | serde | +| `boundaries/2026-07-24-serde-container-attributes.md` | official-docs | official | high | validation | +| `boundaries/2026-07-24-thiserror.md` | official-docs | official | high | errors | +| `observability/2026-07-24-tracing-instrument.md` | official-docs | official | critical | tracing | +| `observability/2026-07-24-tracing-subscriber.md` | official-docs | official | high | subscriber | +| `security/2026-07-24-secrecy.md` | official-docs | official | high | secrets | +| `security/2026-07-24-rustls-config-builder.md` | official-docs | official | critical | tls | +| `security/2026-07-24-rustls-verification-markers.md` | official-docs | official | critical | typestate | +| `cli-tui/2026-07-24-clap-parser.md` | official-docs | official | high | clap | +| `cli-tui/2026-07-24-clap-errors.md` | official-docs | official | high | exits | +| `cli-tui/2026-07-24-ratatui-lifecycle.md` | official-docs | official | high | terminal | +| `cli-tui/2026-07-24-ratatui-test-backend.md` | official-docs | official | high | rendering | +| `cli-tui/2026-07-24-ratatui-architecture.md` | official-docs | official | medium | tui | +| `testing/2026-07-24-proptest-state-machines.md` | official-docs | official | critical | proptest | +| `testing/2026-07-24-proptest-index.md` | official-docs | official | high | properties | +| `testing/2026-07-24-loom.md` | official-docs | official | critical | loom | +| `testing/2026-07-24-tokio-time-testing.md` | official-docs | official | critical | faketime | +| `testing/2026-07-24-nextest.md` | official-docs | official | high | nextest | +| `testing/2026-07-24-nextest-retries.md` | official-docs | official | high | flakiness | +| `testing/2026-07-24-criterion-analysis.md` | official-docs | official | high | benchmark | +| `supply-chain/2026-07-24-cargo-dist-config.md` | official-docs | official | critical | packaging | +| `supply-chain/2026-07-24-cargo-dist-attestations.md` | official-docs | official | high | provenance | +| `supply-chain/2026-07-24-cargo-cyclonedx.md` | changelog | official | critical | sbom | +| `supply-chain/2026-07-24-cargo-auditable.md` | github-readme | practitioner | high | auditability | +| `supply-chain/2026-07-24-cargo-deny-checks.md` | official-docs | official | high | policy | +| `supply-chain/2026-07-24-cargo-deny-license-limitations.md` | official-docs | official | high | licenses | +| `supply-chain/2026-07-24-rustsec.md` | official-docs | official | critical | advisories | +| `supply-chain/2026-07-24-cargo-audit.md` | github-readme | official | critical | cargo-audit | +| `supply-chain/2026-07-24-sigstore-cosign-blob.md` | official-docs | official | high | signing | +| `supply-chain/2026-07-24-cargo-sbom-unstable.md` | official-docs | official | high | cargo-sbom | +| `supply-chain/2026-07-24-cargo-package-verification.md` | official-docs | official | high | package | diff --git a/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md b/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md new file mode 100644 index 00000000..95f928d0 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-instrument.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/attr.instrument.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tracing +stinger: rust-stinger +--- + +# `tracing::instrument` field capture + +## Summary +`#[instrument]` records function arguments by default, using `Value` or `Debug`. `skip` and `skip_all` explicitly exclude arguments, and replacement fields can record safe identifiers. This default makes unreviewed instrumentation a direct secret/prompt leakage risk at sensitive boundaries. + +## Key quotations / statistics +- "By default, all arguments to the function are included as fields" +- `skip_all` can "skip all arguments" + +## Version/date caveat +Retrieved against tracing 0.1.44; macro capture policy is current at access time. + +## Annotations for stinger-forge +- Critical source for a `skip_all`-first rule on provider, prompt, credential, and SQL boundaries. +- Add explicit allowlisted correlation/state fields rather than relying on Debug. + diff --git a/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md b/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md new file mode 100644 index 00000000..0cffcd7a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/observability/2026-07-24-tracing-subscriber.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/tracing/latest/tracing/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: subscriber +stinger: rust-stinger +--- + +# tracing library/subscriber ownership + +## Summary +Tracing libraries emit spans/events but executables install subscribers that collect and format them. The docs warn libraries not to set a global default because that conflicts with downstream executables. This creates a clean crate boundary: libraries describe structured events; daemon/CLI binaries own filtering, sinks, and output format. + +## Key quotations / statistics +- "Libraries should link only to the `tracing` crate" +- "libraries should not call `set_global_default()`" + +## Version/date caveat +Tracing 0.1.44 documentation; subscriber features and ecosystem layers vary independently. + +## Annotations for stinger-forge +- Grounds observability dependency direction and binary-owned initialization. +- Security/redaction review remains a peer gate even when field ownership is correct. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md new file mode 100644 index 00000000..1a2dfba4 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-atomic-commit.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/atomiccommit.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: recovery +stinger: rust-stinger +--- + +# SQLite atomic commit and crash recovery + +## Summary +SQLite documents how rollback journals provide atomic commit across process, OS, and power failures, including hot-journal recovery. It also documents assumptions and failure modes around filesystem locking, sync behavior, file renames, and deletion of journals. SQLite's own confidence rests on fault-injecting VFS crash tests, not code inspection alone. + +## Key quotations / statistics +- "either all database changes within a single transaction occur or none" +- "crash tests ... simulate incomplete sector writes" + +## Version/date caveat +This page primarily describes rollback-journal mode; WAL atomicity uses a different mechanism documented separately. + +## Annotations for stinger-forge +- Strong evidence for crash/restart and filesystem-fault tests around local state. +- Preserve database, WAL, SHM, and journal files together during recovery/support operations. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md new file mode 100644 index 00000000..cfe565e1 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-pragma-durability.md @@ -0,0 +1,26 @@ +--- +source_url: https://sqlite.org/pragma.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: durability +stinger: rust-stinger +--- + +# SQLite PRAGMA durability controls + +## Summary +SQLite's PRAGMA reference defines `journal_mode`, `synchronous`, `busy_timeout`, foreign-key enforcement, and checkpoint controls. The durability contract changes by journal mode and synchronous level; `OFF` does not sync, while WAL plus `NORMAL` trades away recent-transaction durability on power loss. + +## Key quotations / statistics +- "you lose durability across power loss with synchronous NORMAL in WAL mode" +- With `synchronous=OFF`, SQLite proceeds "without syncing" + +## Version/date caveat +Official reference retrieved 2026-07-24; platform VFS behavior can still weaken guarantees. + +## Annotations for stinger-forge +- Use to require explicit, tested connection PRAGMAs rather than driver defaults. +- Final durability policy is an architecture/product decision and should be recorded. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md new file mode 100644 index 00000000..02a13e90 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/lang_transaction.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: transactions +stinger: rust-stinger +--- + +# SQLite transaction semantics + +## Summary +SQLite permits multiple simultaneous readers but only one write transaction. `BEGIN DEFERRED` delays lock acquisition and can fail when upgrading a read to a write; `BEGIN IMMEDIATE` attempts to acquire the write transaction at the start and returns `SQLITE_BUSY` if another writer is active. Nested `BEGIN` transactions are not supported. + +## Key quotations / statistics +- "Transactions created using BEGIN...COMMIT do not nest." +- "BEGIN IMMEDIATE might fail with SQLITE_BUSY" + +## Version/date caveat +SQLite official page published within the six-month research window. Exact busy behavior also depends on connection busy timeout and transaction duration. + +## Annotations for stinger-forge +- Critical for reservation/reconciliation write serialization and busy-retry design. +- Supports acquiring write intent before reading budget state when the operation must be atomic. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md new file mode 100644 index 00000000..b3143ac4 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlite-wal.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.sqlite.org/wal.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: wal +stinger: rust-stinger +--- + +# SQLite write-ahead logging + +## Summary +WAL mode separates writes from checkpoints, permits readers alongside a writer, and persists as a database property. Automatic checkpoints occur at a default threshold of 1000 pages. Long readers can prevent checkpoint completion and grow the WAL; `synchronous=NORMAL` can lose recent committed transactions after power loss even while preserving database consistency. + +## Key quotations / statistics +- "By default, SQLite does a checkpoint automatically" at 1000 pages. +- With `synchronous=NORMAL`, "transactions are no longer durable" across power failure. + +## Version/date caveat +Official SQLite page updated in the research window; durability claims depend on VFS/filesystem correctness. + +## Annotations for stinger-forge +- Grounds explicit journal, synchronous, checkpoint, and reader-lifetime choices. +- Contradicts any blanket claim that WAL plus NORMAL implies full power-loss durability. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md new file mode 100644 index 00000000..dcc861a0 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-connect-options.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/sqlite/struct.SqliteConnectOptions.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: sqlx +stinger: rust-stinger +--- + +# SQLx SQLite connection options + +## Summary +`SqliteConnectOptions` exposes journal, locking, synchronous, busy-timeout, foreign-key, and statement settings. SQLx deliberately does not select a journal mode by default; WAL persists in the database and switching away from it may require an exclusive lock. The default busy timeout is five seconds. + +## Key quotations / statistics +- "SQLx does not set a journal mode by default" +- "The default busy timeout is 5 seconds." + +## Version/date caveat +SQLx latest docs at retrieval (the docs index reported 0.9.0). Verify APIs against the actually pinned SQLx release. + +## Annotations for stinger-forge +- Grounds a single audited connection-options builder and startup verification of effective PRAGMAs. +- Prevent per-connection configuration drift in pools. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md new file mode 100644 index 00000000..b3ef08b7 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-custom-transactions.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/sqlx/trait.Connection.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: locking +stinger: rust-stinger +--- + +# SQLx custom transaction start + +## Summary +SQLx 0.9.0 exposes `Connection::begin_with` to begin a tracked transaction using a database-specific statement. This permits SQLite `BEGIN IMMEDIATE` while retaining the `Transaction` commit/rollback API. The function rejects statements that do not actually enter a transaction, which is safer than issuing an unrelated raw statement and assuming tracking. + +## Key quotations / statistics +- "Begin a new transaction with a custom statement." +- It errors if the statement "does not put the connection into a transaction." + +## Version/date caveat +This API appears in SQLx 0.9.0; SQLx 0.8-era projects need a version-specific alternative and should not copy the call blindly. + +## Annotations for stinger-forge +- Resolves the primary SQLx mechanism for write-intent acquisition before budget reads. +- Pair with bounded busy handling, conditional updates, and concurrency/crash tests. + diff --git a/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md new file mode 100644 index 00000000..74a7899d --- /dev/null +++ b/.cursor/skills/rust-stinger/research/persistence/2026-07-24-sqlx-migrations-queries.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/sqlx/latest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: migrations +stinger: rust-stinger +--- + +# SQLx query macros and embedded migrations + +## Summary +SQLx provides compile-time checked query macros and `migrate!`, which embeds migrations into the binary. Query macros require a build-time schema connection or checked-in `.sqlx` offline metadata. Embedded migrations improve deployability but do not replace forward-only migration policy, crash tests, and schema-version compatibility checks. + +## Key quotations / statistics +- "The `migrate!` macro embeds migrations into the binary" +- "The `query!` macro allows for statically checked SQL queries" + +## Version/date caveat +SQLx latest docs at retrieval; offline metadata commands and migration macro rebuild behavior vary by release/build system. + +## Annotations for stinger-forge +- Supports compile-checked repository queries and migration packaging tests. +- Database schema review remains a peer boundary; this source covers Rust integration mechanics. + diff --git a/.cursor/skills/rust-stinger/research/research-plan.md b/.cursor/skills/rust-stinger/research/research-plan.md new file mode 100644 index 00000000..7c00d1ca --- /dev/null +++ b/.cursor/skills/rust-stinger/research/research-plan.md @@ -0,0 +1,91 @@ +# Research Plan: rust-stinger + +- **Depth tier:** deep +- **Time window:** 2026-07-24 back to 2026-01-24 (6 months) +- **Page budget target:** 1,000 page-equivalents across official documentation sets, upstream repositories, release notes, and standards/tooling references +- **Source breadth target:** official language/toolchain documentation, upstream crate documentation, upstream GitHub repositories, SQLite specifications, security advisories, release/changelog material, standards/provenance specifications +- **Discovery caveat:** The initial queries below are reconstructed from the Command Brief's primary research targets and research questions. Research used Context7 documentation retrieval and direct official/upstream pages; this limitation is preserved in the final summary. + +## Initial queries (derived from the Command Brief) + +- "Rust Cargo workspace architecture MSRV feature unification platform support 2026" +- "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" +- "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" +- "Rust typed state machines replay prohibition safe promotion error boundaries 2026" +- "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" +- "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" +- "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" +- "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +## Expansion queries + +### Branch from "Rust Cargo workspace architecture MSRV feature unification platform support 2026" + +- "Cargo resolver version 3 workspace dependency inheritance feature unification official" +- "Rust MSRV policy rust-version Cargo official platform support tier policy" +- "Cargo workspace compile time crate boundaries feature flags official guidance" +- "Rust API Guidelines unsafe code guidelines Clippy rustfmt official" + +### Branch from "Tokio Axum Tower cancellation backpressure graceful shutdown streaming testing 2026" + +- "Tokio task cancellation safety JoinSet CancellationToken graceful shutdown official" +- "Tokio bounded mpsc backpressure reserve Permit shutdown channel official" +- "Axum with_graceful_shutdown streaming Body cancellation official" +- "Tower Service readiness load shed concurrency limit timeout buffer backpressure official" +- "Tokio time pause advance deterministic tests tracing official" + +### Branch from "SQLite SQLx transactions locking WAL durability migrations concurrent reservations 2026" + +- "SQLite BEGIN IMMEDIATE transaction locking WAL busy timeout synchronous official" +- "SQLite atomic commit crash recovery WAL checkpoint durability official" +- "SQLx SQLite transaction acquire begin immediate migrations official" +- "SQLite concurrent reservation budget oversubscription conditional update RETURNING official" +- "SQLx offline mode compile checked queries migrations locking upstream" + +### Branch from "Rust typed state machines replay prohibition safe promotion error boundaries 2026" + +- "Rust enum typestate state machine exhaustive matching official" +- "Rust ownership newtype sealed traits visibility architecture boundaries official" +- "Serde tagged enums deny unknown fields boundary validation official" +- "thiserror source transparent structured error official" + +### Branch from "Rust tracing secrets rustls redaction TLS operational diagnostics 2026" + +- "tracing instrument skip fields redaction EnvFilter JSON official" +- "secrecy SecretString expose_secret Debug redaction official" +- "rustls dangerous configuration certificate verification official" +- "Rust TLS certificate roots platform verifier rustls official" + +### Branch from "Clap Ratatui scriptable CLI terminal lifecycle testing accessibility 2026" + +- "Clap derive value enum exit codes JSON output shell completion official" +- "Clap error handling try_parse_from CommandFactory official" +- "Ratatui terminal init restore panic hook test backend official" +- "Ratatui snapshot testing event loop cancellation official" + +### Branch from "Rust proptest Loom nextest Criterion deterministic time soak testing 2026" + +- "proptest state machine strategy shrinking persistence official" +- "Loom model concurrency atomics Arc Mutex limitations official" +- "cargo-nextest retries slow timeout archive junit official" +- "Criterion benchmark statistical confidence regression official" +- "Tokio test start_paused timeout cancellation fake server soak evidence official" + +### Branch from "Rust packaging reproducible builds cargo-dist SBOM signing RustSec cargo-deny cargo-auditable 2026" + +- "cargo-dist installers checksums GitHub releases provenance official" +- "cargo-cyclonedx SBOM Rust official upstream" +- "cargo-auditable binary dependency metadata official upstream" +- "cargo-deny advisories licenses bans sources official" +- "RustSec advisory database cargo-audit withdrawn unmaintained official" +- "Sigstore cosign sign blob attest SBOM keyless official" + +## Research order and rationale + +1. Establish language, Cargo, MSRV, and platform constraints because every later recommendation depends on the supported compiler and target contract. +2. Resolve runtime/service ownership and failure behavior across Tokio, Axum, and Tower. +3. Resolve SQLite/SQLx transaction, locking, and crash-durability semantics. +4. Collect type-boundary, serialization, error, observability, secret, and TLS sources. +5. Collect operator-surface sources for Clap and Ratatui. +6. Collect deterministic, property, model-concurrency, benchmark, and soak-test evidence. +7. Close with packaging, provenance, SBOM, signature, advisory, and release evidence while preserving dependency/release/security peer ownership. diff --git a/.cursor/skills/rust-stinger/research/research-summary.md b/.cursor/skills/rust-stinger/research/research-summary.md new file mode 100644 index 00000000..f8caa1bb --- /dev/null +++ b/.cursor/skills/rust-stinger/research/research-summary.md @@ -0,0 +1,68 @@ +# Research Summary: rust-stinger + +- **Depth tier consumed:** deep, completed as a concise authoritative packet rather than an open-ended crawl +- **Time window:** 2026-01-24 through 2026-07-24 (6 months), with stable canonical reference pages used where the governing specification predates the window +- **Source notes:** 56 +- **Research/control artifacts:** 4 (`research-plan.md`, `index.md`, `evidence-synthesis.md`, `research-summary.md`) +- **Total Markdown files:** 60 +- **Primary-source posture:** 55 official/upstream sources and 1 upstream practitioner-maintained GitHub project note (`cargo-auditable`); no community forum/Reddit source was needed + +## Files by subfolder + +| Subfolder | Source files | +|---|---:| +| `async/` | 10 | +| `boundaries/` | 3 | +| `cli-tui/` | 5 | +| `observability/` | 2 | +| `persistence/` | 7 | +| `rust-cargo/` | 8 | +| `security/` | 3 | +| `supply-chain/` | 11 | +| `testing/` | 7 | +| **Total** | **56** | + +## Coverage against the Command Brief + +- Rust/Cargo workspace architecture, feature unification, MSRV, toolchain, platform tiers, Clippy, and unsafe policy: covered. +- Tokio/Axum/Tower task ownership, cancellation safety, bounded backpressure, readiness, graceful shutdown, streaming bodies, and service testing: covered. +- SQLite/SQLx transactions, `BEGIN IMMEDIATE`, busy behavior, WAL, checkpointing, durability, atomic commit/crash recovery, connection options, compile-checked queries, and migrations: covered. +- Typed boundaries/state machines, Serde strictness/tagging, structured errors, non-forgeable verification markers: covered. +- tracing/subscriber ownership, secret wrappers, rustls safe/dangerous configuration and typestate: covered. +- Clap CLI parsing/exit behavior and Ratatui lifecycle/test architecture: covered. +- proptest, Loom, deterministic Tokio time, nextest, Criterion, failure/concurrency/migration/fake-provider and eight-hour-soak evidence model: covered. +- cargo-dist, cargo-cyclonedx, cargo-auditable, cargo-deny, RustSec/cargo-audit, Cargo SBOM precursors/package verification, and Sigstore/Cosign: covered with peer-boundary caveats. + +## Five most influential sources + +1. [`async/2026-07-24-tokio-select-cancellation.md`](async/2026-07-24-tokio-select-cancellation.md) — establishes that cancellation safety is an operation-level property and identifies the central replay/data-loss review boundary. +2. [`async/2026-07-24-tower-service-readiness.md`](async/2026-07-24-tower-service-readiness.md) — makes backpressure a resource-reservation contract and exposes the readiness-to-call cancellation edge. +3. [`persistence/2026-07-24-sqlite-transactions.md`](persistence/2026-07-24-sqlite-transactions.md) plus [`persistence/2026-07-24-sqlx-custom-transactions.md`](persistence/2026-07-24-sqlx-custom-transactions.md) — together establish the one-writer rule and the SQLx 0.9 mechanism for tracked `BEGIN IMMEDIATE` transactions. +4. [`security/2026-07-24-rustls-verification-markers.md`](security/2026-07-24-rustls-verification-markers.md) — supplies upstream precedent for private proof tokens preventing skipped safety checks. +5. [`testing/2026-07-24-proptest-state-machines.md`](testing/2026-07-24-proptest-state-machines.md) — supplies the reference-model, invariant, shrinking, and regression-seed pattern for quota/breaker/promotion state. + +## Open questions that survived research + +- Final platform/installer matrix and minimum OS baselines. +- Declared MSRV after the real dependency graph and features exist. +- Required SQLite power-loss durability and busy/contended-write UX. +- Final durable state/event schema for replay prohibition and promotion. +- TUI inclusion in the first milestone. +- Signing/attestation identity and publication authorization. +- Numeric eight-hour-soak thresholds. + +## Sources Forge should re-fetch at build time + +- Rust release index and platform support (toolchain/target drift). +- Tokio current/LTS policy (1.53.1 and 1.51.x were current at retrieval). +- SQLx `Connection::begin_with` and migration/query docs against the selected SQLx version. +- rustls stable docs to avoid using 0.24 development APIs. +- cargo-dist configuration/changelog and GitHub attestation eligibility. +- RustSec advisory database immediately before any release recommendation. + +## Blocked or incomplete research + +- No subject area is blocked. +- Raw web-crawl JSON and ranked discovery records were not produced. Context7 plus direct official/upstream retrieval was used; the limitation is recorded in the plan and synthesis. +- No source establishes a universal off-the-shelf eight-hour Rust soak harness. The synthesis therefore records a composable evidence model and leaves numeric thresholds to the product/release owners. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md new file mode 100644 index 00000000..ae859eb9 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-ci-msrv.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/guide/continuous-integration.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: ci +stinger: rust-stinger +--- + +# Cargo continuous integration guidance + +## Summary +Cargo's CI guide explicitly recommends verifying `rust-version`, testing dependency freshness, and pinning the compiler when warnings are denied because new toolchains can add warnings. It illustrates `cargo hack check --rust-version --workspace --all-targets` and a full-feature Clippy job. + +## Key quotations / statistics +- "When publishing packages that specify `rust-version`, it is important to verify the correctness of that field." +- "CI can fail due to new toolchain versions because there are limited compatibility guarantees around warnings." + +## Version/date caveat +The guide names third-party tools as examples, not as Rust project guarantees. + +## Annotations for stinger-forge +- Grounds separate pinned-toolchain, MSRV, latest-dependency, and target/feature checks. +- Peer boundary: CI topology remains the release/DevOps specialist's decision. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md new file mode 100644 index 00000000..f521634a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-features.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/features.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: features +stinger: rust-stinger +--- + +# Cargo features and feature unification + +## Summary +Cargo features are additive and can be unified across dependency paths. Resolver v2 and later avoid several unwanted unifications for target-specific, build/proc-macro, and inactive dev dependencies, but feature coupling still requires deliberate crate boundaries and CI combinations. Default features are part of the public dependency contract unless callers disable them consistently. + +## Key quotations / statistics +- "Features should be additive." +- Resolver v2 "avoids unifying features" across several dependency categories. + +## Version/date caveat +Stable Cargo documentation; individual dependency feature sets can change without a workspace architecture change. + +## Annotations for stinger-forge +- Supports feature hygiene, `cargo tree -e features`, and targeted feature-matrix checks. +- Relevant to keeping TUI/provider/TLS capabilities out of core crates by default. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md new file mode 100644 index 00000000..d1fcb298 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-resolver-v3.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/resolver.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: resolver +stinger: rust-stinger +--- + +# Cargo dependency resolver + +## Summary +Cargo resolver version 3 is the Rust 2024 default and changes incompatible-Rust-version handling from `allow` to `fallback`. Resolver choice is global to the top-level workspace and dependency manifests cannot override it; virtual workspaces must set it explicitly. This is a workspace architecture constraint, not a per-crate preference. + +## Key quotations / statistics +- "`3` (`edition = `2024` default, requires Rust 1.84+)" +- "The resolver is a global option that affects the entire workspace." + +## Version/date caveat +Stable Cargo docs as of retrieval. Resolver v3 sets selection behavior but does not prove every selected dependency actually honors its MSRV. + +## Annotations for stinger-forge +- Inform the workspace manifest checklist and feature/MSRV audit. +- Warn that a virtual workspace must explicitly declare `resolver = "3"`. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md new file mode 100644 index 00000000..a377739d --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-cargo-rust-version.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/cargo/reference/rust-version.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: msrv +stinger: rust-stinger +--- + +# Cargo `rust-version` + +## Summary +Cargo's `rust-version` field declares the minimum supported compiler and participates in diagnostics and dependency resolution. Workspace members can have different policies, but shared dependencies and feature unification mean the lowest supported member can constrain the whole workspace. The declared value needs CI proof rather than being treated as descriptive metadata. + +## Key quotations / statistics +- "The resolver may take Rust version into account when picking dependencies." +- "All functionality, including binaries and API, are available on the supported Rust versions under every feature." + +## Version/date caveat +Stable Cargo documentation retrieved against the Rust 1.97 release line; resolver behavior depends on workspace resolver selection. + +## Annotations for stinger-forge +- Grounds MSRV declaration and verification rules. +- Supports testing all public feature combinations claimed to work at MSRV. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md new file mode 100644 index 00000000..1155d39a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-clippy-ci.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/stable/clippy/continuous_integration/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: linting +stinger: rust-stinger +--- + +# Clippy in continuous integration + +## Summary +Official Clippy guidance recommends treating Clippy warnings as CI failures and using the same toolchain as compilation for compatibility. Because new lints appear over time, a pinned toolchain or an explicit upgrade process prevents unrelated stable updates from unexpectedly breaking release branches. + +## Key quotations / statistics +- "It is recommended to run Clippy on CI with `-Dwarnings`." +- "use Clippy from the same toolchain, that you use for compiling your crate" + +## Version/date caveat +Lint inventories evolve with the compiler; a clean result is toolchain-specific. + +## Annotations for stinger-forge +- Supports the standard Rust verification gate and toolchain pinning. +- Avoid enabling all `restriction` lints indiscriminately; the Clippy index warns they may conflict. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md new file mode 100644 index 00000000..b1fb7d7a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-platform-support.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/rustc/platform-support.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: targets +stinger: rust-stinger +--- + +# Rust platform support + +## Summary +Rust classifies targets into three tiers with materially different build and test guarantees. Tier 1 targets build and pass tests in Rust CI; Tier 2 targets are guaranteed to build but may not be tested. A product target matrix therefore needs its own runtime/install/uninstall proof even when the compiler labels a target supported. + +## Key quotations / statistics +- "Tier 1 targets can be thought of as `guaranteed to work`." +- Tier 2 targets "can be thought of as `guaranteed to build`." + +## Version/date caveat +Target tiers and OS baselines can change between Rust releases; re-check during release planning. + +## Annotations for stinger-forge +- Use to separate compiler support from product support evidence. +- Supports explicit macOS/Linux/Windows target triples and host-tool requirements. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md new file mode 100644 index 00000000..46def630 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-rust-release-1-97.md @@ -0,0 +1,26 @@ +--- +source_url: https://blog.rust-lang.org/releases/ +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: toolchain +stinger: rust-stinger +--- + +# Rust release announcements + +## Summary +The official release index records Rust 1.97.1 on 2026-07-16 and Rust 1.97.0 on 2026-07-09. It provides the current stable anchor for any 2026 toolchain discussion, but it does not itself establish the product's MSRV; that remains a deliberate compatibility decision verified independently. + +## Key quotations / statistics +- "July 16 | Announcing Rust 1.97.1" +- 2026 releases listed in the six-month window: 1.93.0 through 1.97.1. + +## Version/date caveat +Current stable at retrieval time; Rust releases on a regular cadence, so re-check immediately before freezing a toolchain. + +## Annotations for stinger-forge +- Use as the current-version anchor in toolchain/MSRV guidance. +- Distinguish "current stable" from the separately declared `package.rust-version` and CI-tested MSRV. + diff --git a/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md new file mode 100644 index 00000000..cf491309 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/rust-cargo/2026-07-24-unsafe-rust.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: unsafe +stinger: rust-stinger +--- + +# Unsafe Rust + +## Summary +The Rust Book defines the five operations requiring `unsafe`, stresses that unsafe code transfers proof obligations to the programmer, and recommends keeping unsafe blocks small behind safe abstractions. This supports a default `forbid(unsafe_code)` posture with narrowly reviewed exceptions. + +## Key quotations / statistics +- "Keep `unsafe` blocks small" +- "wrapping unsafe code in a safe function is a common abstraction" + +## Version/date caveat +The current Book uses the Rust 2024 edition. Low-level memory-model details must be checked against the Reference/Nomicon, not inferred from examples. + +## Annotations for stinger-forge +- Grounds unsafe inventory, documented invariants, and targeted tests. +- Note that the old Unsafe Code Guidelines reference describes itself as largely abandoned. + diff --git a/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md b/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md new file mode 100644 index 00000000..b7df5e59 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-config-builder.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: tls +stinger: rust-stinger +--- + +# rustls configuration typestate + +## Summary +rustls 0.23.42 uses builder typestates to require protocol/provider, peer verification, and certificate decisions in order. Normal builders select safe default protocol versions; custom verifiers sit behind a deliberately dangerous API. The builder demonstrates compile-time enforcement of required configuration steps. + +## Key quotations / statistics +- "use rustls' default cryptographic provider and safe defaults" +- Builder state "ensure[s] at compile time that each required configuration item is provided exactly once" + +## Version/date caveat +The stable docs reported rustls 0.23.42; rustls.dev also exposed 0.24.0-dev.0, so do not code to development APIs accidentally. + +## Annotations for stinger-forge +- Strong upstream example for typestate and TLS-safe defaults. +- Custom certificate verification requires explicit Security review. + diff --git a/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md b/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md new file mode 100644 index 00000000..b92aa6da --- /dev/null +++ b/.cursor/skills/rust-stinger/research/security/2026-07-24-rustls-verification-markers.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustls.dev/src/rustls/verify.rs.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: typestate +stinger: rust-stinger +--- + +# rustls verification marker types + +## Summary +rustls uses non-constructible marker values to encode that certificate-chain and handshake-signature verification occurred before traffic state is reached. The source explicitly frames this as protection against omitted-check control flow. This is directly relevant as prior art for non-forgeable replay/promotion authorization tokens. + +## Key quotations / statistics +- "bind the fact some verification ... has taken place into protocol states" +- "compiler check that there are no `goto fail`-style elisions" + +## Version/date caveat +Source view from rustls.dev may track development rather than the pinned 0.23 release; use the pattern, not an internal type dependency. + +## Annotations for stinger-forge +- Key evidence for private constructors and capability tokens representing completed checks. +- Do not couple the router's state machine to rustls internal marker types. + diff --git a/.cursor/skills/rust-stinger/research/security/2026-07-24-secrecy.md b/.cursor/skills/rust-stinger/research/security/2026-07-24-secrecy.md new file mode 100644 index 00000000..c323990a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/security/2026-07-24-secrecy.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/secrecy/latest +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: secrets +stinger: rust-stinger +--- + +# secrecy secret wrappers + +## Summary +secrecy 0.10.3 wraps secret values so access requires an explicit exposure trait, reduces accidental Debug/logging/copying, and wipes supported owned values on drop. Optional Serde support permits deserialization but explicitly cannot prevent upstream deserializers from making copies. It is defense-in-depth, not a complete secret store. + +## Key quotations / statistics +- access is "only available through a special `ExposeSecret` trait" +- Serde support "doesn't guarantee ... additional copies" are not made. + +## Version/date caveat +MSRV is Rust 1.60; the project states future MSRV changes are outside SemVer guarantees but accompany a minor bump. + +## Annotations for stinger-forge +- Supports secret newtypes and narrow exposure sites. +- Secret acquisition/storage policy remains Security/platform-owned. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md new file mode 100644 index 00000000..7044e61a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-audit.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rustsec/rustsec/blob/main/cargo-audit/README.md +retrieved_on: 2026-07-24 +source_type: github-readme +authority: official +relevance: critical +topic: cargo-audit +stinger: rust-stinger +--- + +# RustSec cargo-audit + +## Summary +cargo-audit checks Cargo.lock against RustSec and can inspect binaries built with cargo-auditable. Its experimental `fix` command modifies manifests, while ignore entries require application-specific justification. The README states binary scanning is incomplete for ordinary optimized binaries but accurate when auditable metadata is embedded. + +## Key quotations / statistics +- "Audit your dependencies for crates with security vulnerabilities" +- Without auditable metadata it may miss "roughly half of the Rust dependencies" + +## Version/date caveat +README currently requires Rust 1.74 or later; pin cargo-audit independently from the product MSRV. + +## Annotations for stinger-forge +- Supports lockfile and shipped-binary audit evidence. +- Never run automatic fix as part of an evidence-only release gate without review. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md new file mode 100644 index 00000000..675c4a35 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-auditable.md @@ -0,0 +1,26 @@ +--- +source_url: https://github.com/rust-secure-code/cargo-auditable +retrieved_on: 2026-07-24 +source_type: github-readme +authority: practitioner +relevance: high +topic: auditability +stinger: rust-stinger +--- + +# cargo-auditable + +## Summary +cargo-auditable embeds Cargo dependency version information in production binaries so deployed artifacts can be scanned later. It integrates with cargo-dist and experimental Cargo SBOM precursor output. The project recommends recording artifact hash, Cargo.lock, compiler/LLVM versions, and build date alongside binaries because embedded dependency metadata alone is not complete provenance. + +## Key quotations / statistics +- "Make production Rust binaries auditable" +- record "the hash of every executable" with build metadata. + +## Version/date caveat +The upstream README mentions nightly `-Z sbom`; nightly Cargo features are not a stable release foundation without explicit approval. + +## Annotations for stinger-forge +- Supports artifact-to-lockfile traceability and post-build `cargo audit bin` checks. +- Treat it as complementary to external SBOMs and attestations. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md new file mode 100644 index 00000000..55fe7b91 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-cyclonedx.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/crate/cargo-cyclonedx/0.5.9/source/CHANGELOG.md +retrieved_on: 2026-07-24 +source_type: changelog +authority: official +relevance: critical +topic: sbom +stinger: rust-stinger +--- + +# cargo-cyclonedx 0.5.9 changelog + +## Summary +cargo-cyclonedx 0.5.9, released 2026-03-19, added `SOURCE_DATE_EPOCH` support for reproducible SBOM timestamps and honors `CARGO_BUILD_TARGET` for target identity. It also fixed sparse-registry and package-URL correctness. SBOM generation still requires validation against the shipped artifact and selected features/target. + +## Key quotations / statistics +- "Support for the `SOURCE_DATE_EPOCH` environment variable" +- "`CARGO_BUILD_TARGET` ... determine[s] the target platform" + +## Version/date caveat +Version 0.5.9 is the current release reported at retrieval; coverage/format support should be checked before freezing. + +## Annotations for stinger-forge +- Strong 2026 source for reproducible target-specific CycloneDX generation. +- Final SBOM completeness/policy judgment belongs to dependency/release peers. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md new file mode 100644 index 00000000..fc653b53 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-checks.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: policy +stinger: rust-stinger +--- + +# cargo-deny checks + +## Summary +cargo-deny evaluates licenses, duplicate/banned crates, advisories/yanks, and dependency sources from the resolved crate graph. Running the umbrella check uses defaults for sections not configured, so a repository needs an explicit reviewed policy rather than assuming tool defaults match its legal/security constraints. + +## Key quotations / statistics +- Checks include "licenses", "bans", "advisories", and "sources". +- Advisories cover vulnerabilities, unmaintained crates, and yanked versions. + +## Version/date caveat +Policy/schema changes across cargo-deny versions; pin both tool and configuration version. + +## Annotations for stinger-forge +- Supports Rust-side evidence generation for dependency peer review. +- The Bee may run/report it but must not own final license/advisory exceptions. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md new file mode 100644 index 00000000..7472fa31 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-deny-license-limitations.md @@ -0,0 +1,26 @@ +--- +source_url: https://embarkstudios.github.io/cargo-deny/checks/licenses/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: licenses +stinger: rust-stinger +--- + +# cargo-deny license check limitations + +## Summary +cargo-deny evaluates SPDX expressions and license files but explicitly cannot exhaustively prove a crate's legal licensing. It trusts manifest/package evidence and documents absence, mismatch, and unconventional-placement gaps. Clarifications are hash-bound evidence, not permanent blanket waivers. + +## Key quotations / statistics +- "does not exhaustively search the entirety of the source code" +- It makes a "good-faith assumption" that crates define licensing correctly. + +## Version/date caveat +License-list versions and cargo-deny detection behavior evolve; legal review cannot be replaced by a passing scan. + +## Annotations for stinger-forge +- Prevent overclaiming `cargo deny` as legal clearance. +- Route exceptions and notices to dependency/legal/release peers with exact evidence. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md new file mode 100644 index 00000000..3ff88414 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-attestations.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/supplychain-security/attestations/github.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: provenance +stinger: rust-stinger +--- + +# cargo-dist GitHub artifact attestations + +## Summary +dist can enable GitHub artifact attestations, creating verifiable provenance linked to GitHub Actions and Sigstore. The feature is disabled by default and has repository/plan limitations. Verification uses `gh attestation verify`, so evidence must include both generation and consumer verification transcripts. + +## Key quotations / statistics +- "Artifact Attestations is disabled by default" +- Verification is supported via "`gh attestation verify`" + +## Version/date caveat +The page labels GitHub Artifact Attestations public beta and records eligibility constraints that may change. + +## Annotations for stinger-forge +- Supports provenance as an explicit opt-in release gate, not an assumed dist feature. +- Signing identity/workflow permissions remain release/security peer concerns. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md new file mode 100644 index 00000000..b239d4fa --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-dist-config.md @@ -0,0 +1,26 @@ +--- +source_url: https://axodotdev.github.io/cargo-dist/book/reference/config.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: packaging +stinger: rust-stinger +--- + +# cargo-dist artifact and installer configuration + +## Summary +cargo-dist configures target builds, archives, checksums, source tarballs, extra artifacts, and shell/PowerShell/npm/Homebrew/MSI installers. It can integrate cargo-auditable and cargo-cyclonedx. Checksums are unsigned integrity values; the docs explicitly describe stronger signed checksums as future work. + +## Key quotations / statistics +- Default checksum is "sha256". +- "Future work is planned to support more robust signed checksums." + +## Version/date caveat +Current docs include settings introduced through dist 0.31-era behavior; pin the generator because generated workflows/installers change. + +## Annotations for stinger-forge +- Grounds release manifest, artifact naming, installer matrix, and checksum evidence. +- Release topology/publication/signing authorization remains with the release peer. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md new file mode 100644 index 00000000..91f1b2d0 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-package-verification.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/commands/cargo-package.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: package +stinger: rust-stinger +--- + +# Cargo package verification + +## Summary +`cargo package` builds a distributable crate archive, lists controlled contents, injects best-effort VCS metadata, and rebuilds the extracted package to verify a clean package. The VCS metadata does not prove source provenance, and `--no-verify`/`--allow-dirty` weaken evidence. + +## Key quotations / statistics +- It rebuilds "from scratch" from the package. +- "the provenance of the package is not verified" + +## Version/date caveat +Stable Cargo 1.97-era docs; binary release archives produced by dist have separate contents and verification. + +## Annotations for stinger-forge +- Supports package-content and clean-build checks for publishable crates. +- Do not confuse crate packaging proof with signed binary artifact provenance. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md new file mode 100644 index 00000000..e9bcda24 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-cargo-sbom-unstable.md @@ -0,0 +1,26 @@ +--- +source_url: https://doc.rust-lang.org/cargo/reference/unstable.html#sbom +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: cargo-sbom +stinger: rust-stinger +--- + +# Cargo unstable SBOM precursors + +## Summary +Nightly Cargo's `-Z sbom` emits per-artifact JSON precursor files containing dependencies, target, features, and compiler data. These are inputs for SBOM tools, not complete standardized SBOMs. Because the feature is unstable and requires nightly, a stable release pipeline should treat it as supplemental unless explicitly approved. + +## Key quotations / statistics +- "generate so-called SBOM pre-cursor files" +- Files contain "dependencies, target, features and the used rustc compiler" + +## Version/date caveat +Unstable Cargo feature tracked by issue/RFC; schema and availability may change without stable guarantees. + +## Annotations for stinger-forge +- Record as optional deeper artifact evidence. +- Prefer stable cargo-cyclonedx/cargo-auditable paths for baseline release guidance. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md new file mode 100644 index 00000000..5053b24a --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-rustsec.md @@ -0,0 +1,26 @@ +--- +source_url: https://rustsec.org/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: advisories +stinger: rust-stinger +--- + +# RustSec Advisory Database + +## Summary +RustSec is the canonical community-maintained advisory database for crates.io packages and supports Cargo.lock auditing through cargo-audit and automation. Findings are time-dependent because the database changes after a build; release evidence needs a reviewed-on timestamp and repeatable lockfile input. + +## Key quotations / statistics +- "repository of security advisories filed against Rust crates" +- Maintained by the "Rust Secure Code Working Group" + +## Version/date caveat +Advisory results are a point-in-time snapshot; re-run at release and in ongoing maintenance. + +## Annotations for stinger-forge +- Require recorded database/update time and lockfile hash with audit evidence. +- Security/dependency peers own disposition, ignore expiry, and remediation acceptance. + diff --git a/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md new file mode 100644 index 00000000..dc01d8e6 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/supply-chain/2026-07-24-sigstore-cosign-blob.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.sigstore.dev/cosign/signing/signing_with_blobs/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: signing +stinger: rust-stinger +--- + +# Cosign blob signing + +## Summary +Cosign signs ordinary files with keyless OIDC identities, local/KMS/hardware-backed keys, and emits a recommended bundle containing signature, certificate, and transparency-log proof. Noninteractive signing can create external effects and identity records, so it must remain an explicitly authorized release step. + +## Key quotations / statistics +- "using a bundle is the recommended way of signing a blob" +- The bundle includes "proof of transparency log inclusion" + +## Version/date caveat +Sigstore public infrastructure, identity claims, and command flags can change; capture the CLI version and verification policy. + +## Annotations for stinger-forge +- Supports signing/verification transcript requirements, not automatic invocation. +- Signing identity and publication remain peer/user-authorized boundaries. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md new file mode 100644 index 00000000..da0b82ba --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-criterion-analysis.md @@ -0,0 +1,26 @@ +--- +source_url: https://bheisler.github.io/criterion.rs/book/analysis.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: benchmark +stinger: rust-stinger +--- + +# Criterion analysis process + +## Summary +Criterion performs warmup, measurement, statistical analysis, and comparison to saved baselines. It retains outliers, uses regression and bootstrap confidence intervals, and applies configurable significance/noise thresholds. Results still require a stable environment; statistical sophistication does not eliminate host noise. + +## Key quotations / statistics +- "Each benchmark ... goes through four phases" +- "outlier samples are not dropped" + +## Version/date caveat +Criterion docs reported crate 0.8.2 elsewhere in the corpus. The project warns virtualized CI can be too noisy for reliable wall-time regressions. + +## Annotations for stinger-forge +- Use for controlled local/release-host microbenchmarks and saved evidence. +- Eight-hour soak evidence is a distinct workload with invariants/resource telemetry, not a Criterion benchmark. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-loom.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-loom.md new file mode 100644 index 00000000..2745add5 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-loom.md @@ -0,0 +1,26 @@ +--- +source_url: https://docs.rs/loom/latest/loom/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: loom +stinger: rust-stinger +--- + +# Loom concurrency model checking + +## Summary +Loom 0.7.2 deterministically explores valid thread interleavings under a modeled memory model. Code under test must use Loom replacement synchronization types; unmodeled operations are invisible. State spaces grow exponentially, so Loom is best applied to small concurrency primitives with controlled preemption bounds and separate release-mode jobs. + +## Key quotations / statistics +- "runs tests many times, permuting the possible concurrent executions" +- "All sources of non-determism must be via loom types" + +## Version/date caveat +Loom documents limitations for relaxed ordering, hidden operations, and combinatorial explosion; passing Loom is not universal concurrency proof. + +## Annotations for stinger-forge +- Use selectively for small reservation/permit/task-state primitives. +- Do not wrap ordinary database/business logic in Loom merely to claim model checking. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md new file mode 100644 index 00000000..a5d135bd --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest-retries.md @@ -0,0 +1,26 @@ +--- +source_url: https://nexte.st/docs/features/retries/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: flakiness +stinger: rust-stinger +--- + +# Nextest retries and flaky results + +## Summary +Nextest labels tests that pass only after retry as flaky and can make flaky outcomes fail the profile. JUnit output distinguishes flaky and rerun failures. This supports visibility while preserving a strict default for correctness/concurrency tests. + +## Key quotations / statistics +- "If a test succeeds during a retry, the test is marked flaky." +- "Flaky test detection is integrated with nextest's JUnit support." + +## Version/date caveat +Behavior described includes versioned JUnit changes; confirm the pinned nextest release's config schema. + +## Annotations for stinger-forge +- Require `flaky-result = "fail"` for release evidence unless a peer-approved quarantine exists. +- Never use retries to mask model, migration, or cancellation races. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest.md new file mode 100644 index 00000000..394ee869 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-nextest.md @@ -0,0 +1,26 @@ +--- +source_url: https://www.nexte.st/ +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: nextest +stinger: rust-stinger +--- + +# cargo-nextest capabilities + +## Summary +cargo-nextest supplies parallel test execution, per-test settings, timeouts, retries/flaky classification, archives/partitions, record/replay, and JUnit output across major platforms. It does not run doctests, which remain a separate `cargo test --doc` step. + +## Key quotations / statistics +- "Automatically retry some tests, mark them as heavy, run them serially" +- "Doctests are currently not supported" + +## Version/date caveat +Feature availability can depend on nextest version and execution platform; pin the runner used for release evidence. + +## Annotations for stinger-forge +- Grounds profiles for unit/integration/slow/soak classes and explicit doctest coverage. +- Retries must expose flakiness, not convert a nondeterministic gate into a silent pass. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md new file mode 100644 index 00000000..6f58e586 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-index.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/index.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: high +topic: properties +stinger: rust-stinger +--- + +# Proptest guide + +## Summary +The upstream guide covers strategies, shrinking, failure persistence, configuration, and state-machine testing. Property tests are most useful for invariant-rich inputs and transition sequences; they supplement rather than replace example-based contract tests whose exact output is part of a public API. + +## Key quotations / statistics +- Guide sections include "Shrinking Basics" and "Failure Persistence". +- The guide includes dedicated "State Machine testing" material. + +## Version/date caveat +The guide reflects upstream main documentation; exact APIs must be checked against the pinned crate release. + +## Annotations for stinger-forge +- Supports corpus persistence and reproducible seeds as evidence artifacts. +- Define invariants and input strategies in domain/test-support crates, not production adapters. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md new file mode 100644 index 00000000..31b60956 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-proptest-state-machines.md @@ -0,0 +1,26 @@ +--- +source_url: https://proptest-rs.github.io/proptest/proptest/state-machine.html +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: proptest +stinger: rust-stinger +--- + +# Proptest state-machine testing + +## Summary +Proptest state-machine testing generates sequences of valid transitions from a reference model, applies them to the system under test, checks postconditions/invariants, and shrinks failures to a minimal reproducer. It persists regression seeds. Current upstream support is sequential; concurrency behavior needs another technique such as Loom or explicit multi-client integration tests. + +## Key quotations / statistics +- "checking properties of a system under test ... against an abstract reference state machine" +- "only sequential strategy is supported" + +## Version/date caveat +State-machine support lives in the separate `proptest-state-machine` crate and may not version-lock with all proptest releases. + +## Annotations for stinger-forge +- Primary evidence for quota, reservation, reconciliation, breaker, pin, and promotion model tests. +- Pair with deterministic persistence fixtures and independent concurrency evidence. + diff --git a/.cursor/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md b/.cursor/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md new file mode 100644 index 00000000..67495488 --- /dev/null +++ b/.cursor/skills/rust-stinger/research/testing/2026-07-24-tokio-time-testing.md @@ -0,0 +1,26 @@ +--- +source_url: https://tokio.rs/tokio/topics/testing +retrieved_on: 2026-07-24 +source_type: official-docs +authority: official +relevance: critical +topic: faketime +stinger: rust-stinger +--- + +# Tokio deterministic time testing + +## Summary +Tokio test utilities pause the runtime clock and advance timer-driven futures when no other work can progress. `#[tokio::test(start_paused = true)]` makes backoff, timeout, breaker, pin, and promotion timing tests fast and deterministic, provided production time access is routed through Tokio time or an injected clock. + +## Key quotations / statistics +- "Pausing time has the effect that any time-related future may become ready early." +- `start_paused` requires the `test-util` feature. + +## Version/date caveat +Only Tokio's clock is paused; `std::time` and external systems do not automatically follow it. + +## Annotations for stinger-forge +- Critical source for fake-clock tests and avoiding wall-clock sleeps. +- Explicitly yield/advance and assert temporal ordering, not elapsed host time. + diff --git a/.cursor/skills/rust-stinger/templates/acceptance-slice-checklist.md b/.cursor/skills/rust-stinger/templates/acceptance-slice-checklist.md new file mode 100644 index 00000000..456968f0 --- /dev/null +++ b/.cursor/skills/rust-stinger/templates/acceptance-slice-checklist.md @@ -0,0 +1,16 @@ +# Rust acceptance slice checklist: {{slice_name}} + +- [ ] Read repository instructions, PRD/ADR/ledger, criteria, gates, and current Security/Quality evidence. +- [ ] Confirm repository/worktree and exact owned paths. +- [ ] Preserve unrelated and concurrent edits. +- [ ] Map each changed path and test to {{AC_IDS}}. +- [ ] Inventory crate/features/targets/tasks/channels/migrations/errors/config/logs/unsafe. +- [ ] Record version-sensitive decisions and revalidation points. +- [ ] Add a focused failing test before implementation. +- [ ] Prove cancellation, backpressure, retry/replay, shutdown, and cleanup where affected. +- [ ] Prove transactions, migrations, idempotency, concurrency, and crash recovery where affected. +- [ ] Use fake providers/fixtures unless a live gate is explicitly authorized. +- [ ] Run format, compile/check, Clippy, tests, docs, and affected specialized gates. +- [ ] Generate release evidence locally without signing/publishing unless authorized. +- [ ] Route Security, rerun affected checks after fixes, then route Quality. +- [ ] Report exact commands, results, external effects, limitations, blockers, and rollback/recovery. diff --git a/.cursor/skills/rust-stinger/templates/implementation-handoff.md b/.cursor/skills/rust-stinger/templates/implementation-handoff.md new file mode 100644 index 00000000..c4b6b5cc --- /dev/null +++ b/.cursor/skills/rust-stinger/templates/implementation-handoff.md @@ -0,0 +1,53 @@ +# Rust implementation handoff: {{slice_name}} + +## Outcome + +{{what_is_now_true}} + +## Authority and scope + +- Repository/worktree: `{{absolute_path}}` +- Source authority: `{{prd_or_adr_path}}` +- Owned paths: {{owned_paths}} +- Gates consumed: {{gate_ids_or_none}} +- Concurrent/user edits preserved: {{evidence}} + +## Acceptance evidence + +- {{AC_ID}}: {{command_test_or_artifact}} — {{PASS_FAIL_BLOCKED}} + +## Changed paths + +- `{{path}}` — {{reason}} + +## Verification + +- `{{exact_command}}` — {{PASS_FAIL_BLOCKED}} + +## Safety and operations + +- External effects used: {{none_or_explicit_authorization_and_effect}} +- Async/shutdown/replay: {{evidence}} +- Migration/rollback/recovery: {{evidence}} +- Secrets/prompts/logging/diagnostics: {{evidence}} +- Unsafe inventory: {{none_or_review_reference}} + +## Revalidation points + +- Toolchain/MSRV/targets: {{current_evidence_or_owner_decision}} +- Dependency/runtime APIs: {{current_evidence_or_owner_decision}} +- Durability/contention: {{current_evidence_or_owner_decision}} +- Release/signing/soak: {{current_evidence_or_owner_decision}} + +## Peer handoffs and remaining gates + +- Security: {{ready_or_blocker}} +- Affected-check rerun after Security: {{commands_or_pending}} +- Quality: {{ready_only_after_security_and_reruns}} +- Protocol/platform/database/dependency/release: {{owner_and_open_item}} + +## Blocker, if any + +- Gate/owner: {{gate_and_owner}} +- Affected criteria: {{AC_IDS}} +- First authorized next action: {{next_action}} diff --git a/.cursor/skills/rust-stinger/templates/release-evidence-manifest.yaml b/.cursor/skills/rust-stinger/templates/release-evidence-manifest.yaml new file mode 100644 index 00000000..9b030b14 --- /dev/null +++ b/.cursor/skills/rust-stinger/templates/release-evidence-manifest.yaml @@ -0,0 +1,63 @@ +schema_version: "{{schema_version}}" +release_candidate: "{{version_or_commit}}" +generated_at: "{{ISO_8601_UTC}}" +external_effects_authorized: {{true_or_false}} +authorization_reference: "{{reference_or_NONE}}" + +source: + repository: "{{repository}}" + commit: "{{commit_sha}}" + dirty: {{true_or_false}} + lockfile_sha256: "{{sha256}}" + toolchain: "{{rustc_and_cargo_versions}}" + msrv_status: "{{PROVEN_UNDECIDED_NOT_CLAIMED}}" + +artifacts: + - target: "{{rust_target_triple}}" + path: "{{artifact_path}}" + sha256: "{{sha256}}" + build_command: "{{exact_command}}" + build_result: "{{PASS_FAIL_BLOCKED}}" + runtime_smoke: "{{evidence}}" + install_transcript: "{{path_or_NOT_RUN}}" + uninstall_transcript: "{{path_or_NOT_RUN}}" + +verification: + formatting: "{{command_and_result}}" + clippy: "{{command_and_result}}" + unit_contract_integration: "{{command_and_result}}" + doctests: "{{command_and_result}}" + property_model_concurrency: "{{command_and_result}}" + migrations_crash_recovery: "{{command_and_result}}" + benchmarks: "{{command_and_result}}" + soak: "{{command_result_thresholds_or_BLOCKED}}" + +supply_chain: + sbom: + path: "{{path_or_NOT_GENERATED}}" + tool_version: "{{version}}" + sha256: "{{sha256}}" + advisories: + database_updated_at: "{{ISO_8601_UTC}}" + command: "{{exact_command}}" + result: "{{PASS_FAIL_REVIEW_REQUIRED}}" + dependency_license_source_scan: "{{path_command_and_result}}" + embedded_audit_metadata: "{{evidence_or_NOT_ENABLED}}" + +provenance: + signing_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + attestation_status: "{{UNAUTHORIZED_NOT_RUN_GENERATED_VERIFIED}}" + signer_identity: "{{identity_or_NONE}}" + verification_transcript: "{{path_or_NONE}}" + +peer_handoffs: + security: "{{owner_status_report}}" + dependency_license: "{{owner_status_report}}" + release_devops: "{{owner_status_report}}" + quality: "{{owner_status_report_after_security}}" + +open_gates: + - id: "{{gate_id}}" + owner: "{{owner}}" + blocker: "{{missing_decision_or_evidence}}" + next_action: "{{first_authorized_action}}" diff --git a/.cursor/skills/rust-stinger/templates/rust-decision-log.md b/.cursor/skills/rust-stinger/templates/rust-decision-log.md new file mode 100644 index 00000000..d53a705d --- /dev/null +++ b/.cursor/skills/rust-stinger/templates/rust-decision-log.md @@ -0,0 +1,25 @@ +# Rust decision log + +| Decision | Chosen value | Evidence date | Source or test | Revalidate when | Owner | +|---|---|---|---|---|---| +| Toolchain pin | {{value}} | {{YYYY-MM-DD}} | {{source_or_command}} | Before upgrade/release | {{owner}} | +| MSRV | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{feature_matrix_command}} | Dependency/feature change | {{owner}} | +| Product targets/baselines | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{runtime_install_evidence}} | Release matrix change | {{owner}} | +| Tokio line | {{value}} | {{YYYY-MM-DD}} | {{support_policy_and_tests}} | Runtime upgrade | {{owner}} | +| SQLx transaction API | {{value}} | {{YYYY-MM-DD}} | {{selected_version_docs_and_tests}} | SQLx upgrade | {{owner}} | +| SQLite PRAGMAs | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{durability_decision_and_crash_tests}} | Persistence policy change | {{owner}} | +| rustls configuration | {{value}} | {{YYYY-MM-DD}} | {{stable_docs_and_security_review}} | rustls/root-policy change | {{owner}} | +| Package generator | {{value}} | {{YYYY-MM-DD}} | {{version_and_diff_review}} | Generator upgrade | {{owner}} | +| Signing/attestation | {{value_or_UNAUTHORIZED}} | {{YYYY-MM-DD}} | {{approval_and_verification_policy}} | Every release | {{owner}} | +| Soak thresholds | {{value_or_UNDECIDED}} | {{YYYY-MM-DD}} | {{performance_SLO_source}} | Workload/platform change | {{owner}} | + +## Rationale and alternatives + +### {{decision_name}} + +- Context: {{context}} +- Decision: {{decision}} +- Evidence: {{evidence}} +- Alternatives: {{alternatives}} +- Consequences: {{consequences}} +- Peer approval/gate: {{approval_or_open_gate}}