# Workspace and crate checks

> Cargo workspace scale, fast-check profile, scripts/check-crate and scripts/gate-crate, and how to validate a single ported crate plus seams-init.

- Repository: malisper/pgrust
- GitHub: https://github.com/malisper/pgrust
- Human docs: https://grok-wiki.com/public/docs/malisper-pgrust-7e0c8e82bc21
- Complete Markdown: https://grok-wiki.com/public/docs/malisper-pgrust-7e0c8e82bc21/llms-full.txt

## Source Files

- `Cargo.toml`
- `scripts/check-crate`
- `scripts/gate-crate`
- `scripts/cargo-fast-check`
- `.cargo/config.toml`
- `crates/_support/seam/init/src/lib.rs`

---

---
title: "Workspace and crate checks"
description: "Cargo workspace scale, fast-check profile, scripts/check-crate and scripts/gate-crate, and how to validate a single ported crate plus seams-init."
---

pgrust is a single Cargo workspace of **1466** members (`resolver = "2"`) under `crates/`. Day-to-day validation of a ported package uses `scripts/check-crate` and `scripts/gate-crate` with the `fast-check` profile so typecheck stays cheaper than a full workspace link. Cross-crate seam wiring is aggregated in the package colloquially called **seams-init** (`[package] name = "init"` at `crates/_support/seam/init`), which owns `init_all()`, the `postgres` binary entry shell, and the wiring/recurrence tests.

## Workspace scale and layout

| Fact | Value |
| --- | --- |
| Workspace members | 1466 (`Cargo.toml` `[workspace].members`) |
| Resolver | `"2"` |
| Default edition / publish | `edition = "2021"`, `publish = false` (`[workspace.package]`) |
| Package-name surface | Cargo `-p` selects **package** names (e.g. `pgcrypto`, `init`), not path segments |

Top-level trees under `crates/`:

| Tree | Role (approx. package count) |
| --- | --- |
| `backend/` | Core server port (~1248) |
| `_support/` | Shared types, seam core, init aggregator, todo guard (~125) |
| `common/` | Shared portability / utilities (~46) |
| `port/` | Port layer (~18) |
| `contrib/` | Ported contrib modules (~17) |
| `pl/` | PL/pgSQL-related crates (~8) |
| `interfaces/` | libpq-related (~3) |
| `wasm-libc-shim/` | Wasm link shim (1) |

:::files
crates/
  _support/
    seam/
      init/          # package name: init  (docs/scripts: "seams-init")
      seam_core/
    todo_guard/      # package name: todo_guard
    types/ ...
  backend/ ...
  common/ ...
  contrib/ ...
  interfaces/ ...
  pl/ ...
  port/ ...
  wasm-libc-shim/
scripts/
  cargo-fast-check
  check-crate
  gate-crate
.cargo/
  config.toml        # alias fast-check; default env
:::

About **600** packages are `*_seams` companions (underscore suffix, nested under the owner area). They are separate workspace members with package names like `detoast_seams`, not top-level `crates/<name>-seams` directories.

## Why full-workspace cargo is expensive

Root `Cargo.toml` notes that **linking dominates build time**. Profiles deliberately lighten debuginfo and turn off incremental compilation:

| Profile | Key settings |
| --- | --- |
| `dev` | `debug = "line-tables-only"`, `split-debuginfo = "unpacked"`, `incremental = false` |
| `dev.build-override` | `debug = 0`, `codegen-units = 256` |
| **`fast-check`** | inherits `dev`; `debug = 0`, `split-debuginfo = "off"`, `incremental = false` |
| `release` | `debug = 0`, `strip = "symbols"`, `lto = false`, `codegen-units = 1` |

`.cargo/config.toml` also forces `CARGO_INCREMENTAL = "0"` for every build unless already set in the environment.

Prefer **package-scoped** checks (`-p <package>`) over `cargo check --workspace` when iterating on one crate.

## Fast-check profile and wrappers

### Profile definition

```toml
# Cargo.toml
[profile.fast-check]
inherits = "dev"
debug = 0
split-debuginfo = "off"
incremental = false
```

### Cargo alias

```toml
# .cargo/config.toml
[alias]
fast-check = "check --profile fast-check"
```

Equivalent invocations:

```bash
cargo fast-check -p pgcrypto
cargo check --profile fast-check -p pgcrypto
scripts/cargo-fast-check -p pgcrypto
```

`scripts/cargo-fast-check` `cd`s to the repo root and runs:

```sh
exec cargo check --profile fast-check "$@"
```

### Default path env for builds

`.cargo/config.toml` sets (only if unset in the process environment):

| Variable | Default | Purpose |
| --- | --- | --- |
| `CARGO_INCREMENTAL` | `0` | Matches non-incremental workspace policy |
| `PGRUST_PGSHAREDIR` | `/tmp/pgrust_share` | Bake-in for share/tz `option_env!` lookups |

Override when needed, for example:

```bash
PGRUST_PGSHAREDIR="$PWD/vendor/postgres-18.3/share" cargo build --release --locked --bin postgres
```

## `scripts/check-crate`

Typecheck one Cargo package under `fast-check`, then optionally a sibling seams package.

### Usage

```text
scripts/check-crate <crate> [cargo-check-args...]
```

Exit code **2** if `<crate>` is missing.

### Behavior

1. Resolve repo root from the script path and `cd` there.
2. Run:
   ```bash
   cargo check --profile fast-check -p "$crate" "$@"
   ```
3. If directory `crates/$crate-seams` exists (hyphen before `seams`), also run:
   ```bash
   cargo check --profile fast-check -p "$crate-seams" "$@"
   ```

### Constraints

| Input | Meaning |
| --- | --- |
| `<crate>` | Cargo **package** name passed to `-p` (e.g. `pgcrypto`, `detoast`, `init`) |
| Extra args | Forwarded to both `cargo check` invocations |

<Warning>
The optional companion check looks for a **top-level** directory `crates/<package>-seams` and package name `<package>-seams`. The live tree almost exclusively uses nested `*_seams` packages (underscore). For those, pass the seams package explicitly if you need it:

```bash
scripts/check-crate detoast
cargo check --profile fast-check -p detoast_seams
```
</Warning>

## `scripts/gate-crate`

Local gate for one package: typecheck + unit tests, with an optional wider gate.

### Usage

```text
scripts/gate-crate [--full] <crate>
```

Exit code **2** if the package argument is missing.

### Pipeline

```mermaid
flowchart TD
  A["scripts/gate-crate [--full] PACKAGE"] --> B["scripts/check-crate PACKAGE"]
  B --> C["cargo check --profile fast-check -p PACKAGE"]
  B --> D{"crates/PACKAGE-seams exists?"}
  D -->|yes| E["cargo check --profile fast-check -p PACKAGE-seams"]
  D -->|no| F["skip companion"]
  C --> G["cargo test -p PACKAGE"]
  E --> G
  F --> G
  G --> H{"--full?"}
  H -->|no| I["done"]
  H -->|yes| J["cargo test -p seams-init"]
  J --> K["cargo test -p no-todo-guard"]
```

| Step | Command | Intent |
| --- | --- | --- |
| 1 | `scripts/check-crate "$crate"` | Fast typecheck (+ optional hyphen seams companion) |
| 2 | `cargo test -p "$crate"` | Package unit/integration tests |
| 3 (only `--full`) | `cargo test -p seams-init` | Aggregator / wiring tests (see package-name note) |
| 4 (only `--full`) | `cargo test -p no-todo-guard` | Workspace `todo!()` scan tests (see package-name note) |

### Package-name mapping for `--full`

Comments and scripts refer to historical labels **seams-init** and **no-todo-guard**. Cargo metadata package names are:

| Colloquial / script `-p` | Actual `[package] name` | Path |
| --- | --- | --- |
| `seams-init` | `init` | `crates/_support/seam/init` |
| `no-todo-guard` | `todo_guard` | `crates/_support/todo_guard` |

`scripts/gate-crate --full` currently passes the colloquial names into Cargo. Prefer the real package names when invoking Cargo directly:

```bash
cargo test -p init
cargo test -p todo_guard
# strict todo scan (ignored until tree is clean):
cargo test -p todo_guard -- --ignored
```

## Validate a single ported crate

<Steps>
  <Step title="Identify the Cargo package name">
    Read `[package].name` in the crate’s `Cargo.toml` (often matches the directory leaf: `pgcrypto`, `citext`, `detoast`). Use that string for `-p` and the gate scripts—not the full path under `crates/`.
  </Step>
  <Step title="Typecheck with fast-check">
    ```bash
    scripts/check-crate pgcrypto
    # or
    cargo fast-check -p pgcrypto
    ```
    Success: `cargo check` exits 0 for the package under profile `fast-check`.
  </Step>
  <Step title="Run package tests">
    ```bash
    scripts/gate-crate pgcrypto
    # equivalent core of the gate:
    # scripts/check-crate pgcrypto && cargo test -p pgcrypto
    ```
  </Step>
  <Step title="If the crate installs seams, wire seams-init">
    Owner crates that install seams expose `pub fn init_seams()`. The aggregator must:
    1. Depend on the package in `crates/_support/seam/init/Cargo.toml`.
    2. Call `<lib>::init_seams();` once inside `init::init_all()` in `crates/_support/seam/init/src/lib.rs` (kept as one call per ported crate).

    `init_all()` contains no `set()` logic of its own—only ordered calls into owners.
  </Step>
  <Step title="Run aggregator tests">
    ```bash
    cargo test -p init
    ```
    Notable tests:
    - Unit module `recurrence_guard`: every crate that installs seams via `init_seams()` must be called from `init_all()` (catches merge silent-drop of wiring lines).
    - Integration `tests/no_double_install.rs`: drives a full `init_all()` once and fails on `"seam installed twice: ..."` double-`set()`.
    - Builtin completeness helpers under `builtin_gap_baseline` / related registry tests.
  </Step>
  <Step title="Optional full local gate">
    ```bash
    scripts/gate-crate --full pgcrypto
    ```
    After the package gate, runs the script’s full-step `cargo test` targets. Use `cargo test -p init` / `cargo test -p todo_guard` if the historical package labels fail to resolve.
  </Step>
</Steps>

### Expected signals

| Check | Healthy signal |
| --- | --- |
| `check-crate` / `cargo fast-check -p …` | Exit 0; no type/link errors for that package graph |
| `cargo test -p <crate>` | Exit 0; crate’s own tests pass |
| `cargo test -p init` | Exit 0; recurrence + no-double-install and related tests pass |
| `todo_guard` report | `report_todo_count` always runs; strict `no_todo_or_unimplemented_in_tree` is `#[ignore]` until the tree is clean |

## seams-init (`init`) role in the gate

### Runtime path

The `postgres` binary lives in the `init` package (`[[bin]] name = "postgres"`). Startup:

1. Create top memory context.
2. Call `init::init_all()` (every owner’s `init_seams()`).
3. Dispatch via `backend_main_main::pg_main` / `main_main::pg_main`.

That is the process-level reason package tests on `init` matter after wiring a new seam owner: boot installs seams only through this aggregator.

### Guard classes covered by `init` tests

| Guard | What it catches |
| --- | --- |
| Recurrence / wiring | Seam-installing crate missing from `init_all()` (compile-time invisible; fails the unit test) |
| No double install | Two owners `set()` the same seam slot in one `init_all()` pass |
| Builtin gap baseline | Live builtin registry gap held to a checked-in baseline set |
| Optional runtime smoke | `runtime_seam_miss_smoke` (ignored by default; needs a built `postgres` binary) |

Empty `init_seams()` functions exist on some crates solely so the recurrence/uniformity machinery stays consistent even when no `set()` is required.

## `todo_guard` (no-todo-guard)

Package `todo_guard` scans for real `todo!()` / `unimplemented!()` under crate sources (comments and string literals excluded).

| Test | Behavior |
| --- | --- |
| `report_todo_count` | Always on; prints count (use `-- --nocapture` for the list); does not fail |
| `no_todo_or_unimplemented_in_tree` | Strict gate; currently `#[ignore]` until offender count is zero |

```bash
cargo test -p todo_guard -- --nocapture
cargo test -p todo_guard -- --ignored
```

## Example commands

<CodeGroup>
```bash title="Single package typecheck"
scripts/check-crate hstore
cargo fast-check -p hstore
```

```bash title="Package gate"
scripts/gate-crate hstore
```

```bash title="Package + aggregator + todo_guard (script)"
scripts/gate-crate --full hstore
```

```bash title="Direct aggregator / guard packages"
cargo test -p init
cargo test -p todo_guard -- --nocapture
```

```bash title="Explicit seams companion (underscore)"
cargo check --profile fast-check -p detoast
cargo check --profile fast-check -p detoast_seams
```
</CodeGroup>

## Failure modes

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| `package ID specification ... did not match any packages` | Wrong `-p` name (path vs package), or script `--full` colloquial names `seams-init` / `no-todo-guard` | Use `init` / `todo_guard` or the real `[package].name` |
| Companion seams never checked by `check-crate` | Expects `crates/<name>-seams`; tree uses nested `*_seams` | Check `-p <name>_seams` explicitly |
| Recurrence_guard panic listing unwired crates | New `init_seams()` + `::set(` without `init_all()` line / dep | Add path dep + `<lib>::init_seams();` in `init` |
| `"seam installed twice: ..."` in `no_double_install` | Two owners install the same seam | Remove duplicate install; keep single owner |
| Wrong tz/share at runtime after rebuild | Built without correct `PGRUST_PGSHAREDIR` | Override env or use intended share path; see install-path docs |
| Full workspace check thrashing disk/CPU | 1400+ members, linking-heavy | Stay on `scripts/check-crate` / `-p` scope |

## Related pages

<CardGroup>
  <Card title="Seams and builtin libraries" href="/seams-and-builtins">
    Seam registration model, seams-init aggregation, and dfmgr builtin registration.
  </Card>
  <Card title="Build from source" href="/build-from-source">
    Host packages, PGRUST_PGSHAREDIR bake-in, and `cargo build --release --locked --bin postgres`.
  </Card>
  <Card title="Install paths and share directory" href="/install-paths">
    Build-time path env vars, `-L` override, and share/tz failure modes.
  </Card>
  <Card title="Run regression tests" href="/regression-tests">
    Clone-only `scripts/run-regression` against vendored PG 18.3 oracles.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Runtime GUCs and build-time `PGRUST_*` path variables.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Stack, io_method, share path, and related operational failures.
  </Card>
</CardGroup>