Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
- **Rust IR parity sentinel packet**: Pulled the parity sentinel backlog item
into design packet `0013`, defining comparator inputs, normalization, hash
behavior, and failure output for the next JS/Rust parity check.
- **JS/Rust table parity sentinel**: Added `pnpm parity:ir` and the
`js-table-vs-rust-table.v0` projection so Wesley can compare legacy JS table
IR with Rust L1 over an explicit table-compatible corpus before broadening
parity coverage.
- **Expanded Rust L1 fixture corpus**: Added directive-heavy,
schema-extension, legacy-alias, and invalid duplicate-directive fixtures for
the v0.0.6 compiler-truth lane.
Expand All @@ -26,6 +30,16 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve

### Fixed

- **Parity sentinel evidence contract**: `pnpm parity:ir --json` now records
canonical projected legacy and Rust bytes, and Rust L1 hash checks remove
top-level metadata before comparing against `wesley schema hash` or tracked
`*.l1.hash` outputs.
- **Parity projection ordering**: The `js-table-vs-rust-table.v0` projection now
sorts table names with deterministic code-point ordering instead of
locale-aware collation.
- **Parity custom fixture sidecars**: `pnpm parity:ir --fixture` now skips
tracked `*.l1.hash` checks for non-`.graphql` custom SDL paths instead of
reading the schema file as its own hash sidecar.
- **Rust directive alias normalization**: Rust L1 lowering now canonicalizes
the current core Wesley directive aliases to `wes_*` names and rejects
duplicate canonical directives instead of allowing last-write-wins drift,
Expand Down
20 changes: 11 additions & 9 deletions docs/BEARING.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,22 +104,24 @@ base platform.
The immediate focus is **v0.0.6 Rust IR parity and module-boundary
enforcement**:

Current evidence now includes complete v0.0.5 publication proof and an expanded
Current evidence now includes complete v0.0.5 publication proof, an expanded
Rust L1 corpus for directive-heavy SDL, schema extensions, legacy aliases, and
invalid duplicate-directive coverage.
invalid duplicate-directive coverage, plus `pnpm parity:ir` for the
`js-table-vs-rust-table.v0` compatibility projection over the first
table-compatible sentinel corpus.

The next pulls are:

1. Implement the JS/Rust parity sentinel command from design packet
[0013-rust-ir-parity-sentinel](./design/0013-rust-ir-parity-sentinel/rust-ir-parity-sentinel.md).
2. Land the `js-table-vs-rust-table.v0` projection/crosswalk before comparing
legacy JS table IR with Rust L1 bytes.
3. Pull the domain-empty core boundary card into enforcement work so product
1. Broaden parity sentinel coverage only after naming fair projections for
non-table extension semantics and scale/performance fixtures.
2. Pull the domain-empty core boundary card into enforcement work so product
and database behavior stays outside generic Wesley.
4. Continue the IR contract fixture lane for stable invalid-SDL diagnostics,
3. Continue the IR contract fixture lane for stable invalid-SDL diagnostics,
including codes and spans where available.
5. Keep `wesley-postgres` visible as the database extraction home and avoid
4. Keep `wesley-postgres` visible as the database extraction home and avoid
reshaping sibling work from Wesley release branches.
5. Use the parity sentinel output as compatibility evidence before retiring or
demoting legacy Node lowering.

Echo and jedit do not need more Wesley feature gravity for their current work.
Wesley should coordinate on compatibility only when a concrete artifact, hash,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,24 @@ tests.
related core aliases to ensure Rust L1 emits canonical `@wes_*` directive
names. (**COMPLETE for the current core compiler alias set**)

## JS/Rust Parity Sentinel Corpus

`pnpm parity:ir` is the current JS/Rust compatibility sentinel. It is separate
from `pnpm fixtures:ir` and compares a named projection rather than raw legacy
table IR against raw Rust L1 IR.

The v0 projection is `js-table-vs-rust-table.v0`. Its default corpus is the
table-compatible subset:

- `small-schema.graphql`
- `medium-schema.graphql`
- `directive-heavy-schema.graphql`
- `legacy-alias-schema.graphql`

`schema-extensions-schema.graphql` remains Rust L1 extension-folding coverage
until Wesley defines a fair non-table JS/Rust projection. `large-schema.graphql`
remains scale coverage outside the default v0 compatibility sentinel.

## Baseline Performance (JS)

*Captured on: May 5, 2026*
Expand All @@ -107,7 +125,20 @@ This command shells through the native Wesley CLI and overwrites only the
tracked `*.l1.json` and `*.l1.hash` outputs. It exits nonzero if any fixture
fails to lower or hash.

### Verify Rust Parity
### Verify JS/Rust Table Parity

```bash
pnpm parity:ir
```

This command lowers the explicit v0 sentinel corpus through both the legacy JS
adapter and the Rust CLI, compares the `js-table-vs-rust-table.v0` projection,
records canonical projected bytes in JSON output, verifies the Rust
`schema hash` command against current Rust semantic L1 bytes after top-level
`metadata` removal, and checks tracked Rust L1 hashes for `.graphql` fixtures
when sidecars are present.

### Verify Rust Tests

```bash
cd crates/wesley-core && cargo test
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ The normalizer removes envelope-only data and keeps semantic data intact.
- Remove top-level `metadata`.
- Sort object keys with Wesley canonical JSON ordering before hashing.
- Preserve array order.
- Sort projection-created table arrays by deterministic code-point name order.
- Preserve directive argument values exactly after each lowerer has produced
semantic IR.
- Require lowerers to emit canonical directive names for core Wesley aliases.
Expand Down Expand Up @@ -149,15 +150,42 @@ Each failure should include:
- the next decision: fix Rust, fix JS compatibility, update Rust goldens, or
record an intentional compatibility break

## Current Slice
## Implemented Slice

This first v0.0.6 slice does not implement the sentinel command yet.
The first command slice implements the `js-table-vs-rust-table.v0` projection
and exposes it as:

It does pull the backlog card into design, expands the Rust L1 corpus, and
closes one blocker the sentinel would otherwise expose immediately: Rust L1
lowering now canonicalizes the core Wesley directive aliases before writing
semantic IR, rejects duplicate canonical core directives, and preserves
repeated custom directives as ordered values.
```bash
pnpm parity:ir
```

The v0 corpus is explicit and table-compatible:

- `test/fixtures/ir-parity/small-schema.graphql`
- `test/fixtures/ir-parity/medium-schema.graphql`
- `test/fixtures/ir-parity/directive-heavy-schema.graphql`
- `test/fixtures/ir-parity/legacy-alias-schema.graphql`

The command lowers each fixture through the legacy JS adapter and the Rust CLI,
projects both outputs into the shared table shape, compares canonical projected
bytes and hashes, verifies `wesley schema hash` against the current Rust L1
semantic bytes after top-level `metadata` removal, checks tracked Rust L1 hashes
for `.graphql` fixtures when sidecars are present, and reports the first
mismatch path when projection parity fails.
JSON output records the canonical projected `legacyBytes` and `rustBytes`
alongside their hashes so reviewers can archive or inspect the exact compared
bytes.

`schema-extensions-schema.graphql` and `large-schema.graphql` remain outside
the default v0 sentinel corpus. The former still carries non-table Rust L1
coverage that needs a separate projection before it is fair parity evidence;
the latter is scale coverage rather than the first compatibility sentinel.

The preceding design slice also pulled the backlog card into design, expanded
the Rust L1 corpus, and closed one blocker the sentinel would otherwise expose
immediately: Rust L1 lowering now canonicalizes the core Wesley directive
aliases before writing semantic IR, rejects duplicate canonical core
directives, and preserves repeated custom directives as ordered values.

## Playback Questions

Expand All @@ -169,8 +197,8 @@ repeated custom directives as ordered values.
4. Does the fixture corpus now cover directive-heavy SDL, schema extensions,
legacy aliases, and at least one invalid-SDL case?
5. Does Rust L1 preserve canonical directive names for supported aliases?
6. Is the next implementation slice narrow enough to add a `pnpm parity:ir`
check without changing the Rust golden-regeneration command?
6. Does `pnpm parity:ir` compare the v0 table-compatible corpus without
changing the Rust golden-regeneration command?

## Non-Goals

Expand Down
39 changes: 39 additions & 0 deletions docs/method/backlog/bad-code/DX_format-check-toolchain-gap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Format Check Toolchain Gap

- Lane: `bad-code`
- Legend: `DX`

## Why now

`package.json` exposes `pnpm run format` and `pnpm run format:check`, but the
workspace does not currently install a `prettier` binary. During the
`js-table-vs-rust-table.v0` parity sentinel slice, `pnpm run format:check`
failed before inspecting files:

```text
sh: prettier: command not found
```

That makes the formatting gate look available when it is not actually
re-runnable from a clean local checkout.

## Hill

The repository either installs and pins the formatter needed by the existing
format scripts or removes/renames the scripts so local validation does not
advertise a dead command.

## Done looks like

- `pnpm run format:check` runs from a clean checkout without relying on a
globally installed formatter.
- The formatter version is pinned in workspace-managed package metadata.
- `pnpm run validate` no longer fails solely because the formatter binary is
unavailable.
- The chosen formatter behavior is documented in `scripts/README.md` or the
contributor-facing docs if it remains a supported gate.

## Repo Evidence

- `package.json`
- `scripts/README.md`
4 changes: 4 additions & 0 deletions docs/method/backlog/bad-code/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,7 @@ the hill is "this no longer bothers us."
## Emitters

- [Rust emitter consumer model parity](SOURCE_rust-emitter-consumer-model-parity.md)

## Developer Experience

- [Format Check Toolchain Gap](DX_format-check-toolchain-gap.md)
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@
"wesley": "node packages/wesley-host-node/bin/wesley.mjs",
"meta:fix-packages": "node scripts/fix-package-metadata.mjs",
"ci": "pnpm validate && pnpm generate:example && node packages/wesley-host-node/bin/wesley.mjs validate-bundle --bundle test/fixtures/examples/.wesley --schemas schemas/",
"fixtures:ir": "node scripts/generate-ir-fixtures.mjs"
"fixtures:ir": "node scripts/generate-ir-fixtures.mjs",
"parity:ir": "node scripts/check-ir-parity.mjs"
},
"keywords": [
"graphql",
Expand Down
1 change: 1 addition & 0 deletions scripts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ This directory contains helper scripts that power development workflows. Run the
| Script | Description | Usage |
| --- | --- | --- |
| `check-doc-links.mjs` | Scans every markdown file for relative links that point to missing targets. Fails with a non-zero exit code if any are broken. | `pnpm exec node scripts/check-doc-links.mjs` (no arguments) |
| `check-ir-parity.mjs` | Compares the legacy JS table projection with the Rust L1 projection over the explicit v0 IR parity corpus. | `pnpm parity:ir` |
| `clean.mjs` | Removes generated artifacts such as `.wesley-cache/`, `out/`, and fixture outputs to return the workspace to a pristine state. | `pnpm run clean` (no arguments) |
| `fix-package-metadata.mjs` | Normalises `package.json` metadata across all workspaces (author, license, repository, etc.). | `pnpm exec node scripts/fix-package-metadata.mjs` (no arguments) |
| `install-hooks.sh` | Sets `core.hooksPath` to `.githooks`, ensuring local Git hooks run. Safe to rerun. | `bash scripts/install-hooks.sh` |
Expand Down
Loading
Loading