feat(engine): single-source logic engine generating TypeScript, Python, Go and Rust

.github/workflows/engine.yml

@@ -0,0 +1,64 @@
+name: Engine
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "engine/**"
+      - "core/**"
+      - ".github/workflows/engine.yml"
+  push:
+    branches: [main]
+    paths:
+      - "engine/**"
+      - "core/**"
+      - ".github/workflows/engine.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify the engine and the core it generates
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # The engine has its own toolchain: Node runs its TypeScript directly, and the generated
+      # Python and Go are compiled by the runner's own preinstalled toolchains.
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+
+      - name: Install the engine's dependencies
+        run: npm ci
+        working-directory: engine
+
+      # The generated output is committed, so the three formatters decide its bytes. Prettier and
+      # gofmt come with the engine's install and with Go; ruff is pinned to the version in
+      # `engine/toolchain.lock.json`, and `verify` fails outright if any of the three is missing.
+      - name: Install ruff, the Python formatter
+        run: pipx install ruff==0.15.8
+
+      - name: Verify
+        # Compiles, generates every target in both idiom modes, regenerates and diffs for
+        # determinism, runs each target's linters over the output, and runs the differential
+        # conformance harness against the published package and across the three targets.
+        run: node ../engine/scripts/verify.ts .
+        working-directory: core
+
+      - name: Check the committed output is what the engine emits
+        # `out/` is committed so it can be read in review; the verification above regenerated it,
+        # so a diff here means the sources changed without the output being regenerated.
+        run: git diff --exit-code --stat -- out
+        working-directory: core

.gitignore

@@ -19,3 +19,6 @@ reports/*
 !reports/api/
 reports/api/*
 !reports/api/brazilian-utils.api.md
+
+# Scratch git worktrees, created when a task is run in isolation from the checkout.
+.claude/worktrees/

core/.gitignore

@@ -0,0 +1,14 @@
+# The generated output of the four targets is committed on purpose: reading it is the point of
+# this project, so a reviewer should see what the engine produces without having to run it.
+# `npm run verify` regenerates it and fails if what is committed drifts from what the engine emits.
+#
+# The `--no-idioms` trees are a comparison the verification builds, not an artifact anyone reads,
+# and the interpreter and build caches are not ours.
+out/*-plain/
+**/__pycache__/
+out/**/.ruff_cache/
+out/**/target/
+node_modules
+
+# Cargo build artifacts from the benchmark harness, the same as the generated crate above.
+bench/rust/target/

core/README.md

@@ -0,0 +1,47 @@
+# Brazilian Utils core
+
+The single-source core of Brazilian Utils: each utility is written **once**, in the engine's
+restricted subset, and generated for TypeScript, Python and Go.
+
+```sh
+npm run check        # types, ranges, refinements, effects
+npm run build        # generate every target, in both idiom modes
+npm run conformance  # interpreter vs the npm package vs every target
+npm run verify       # all of it, plus linters and a determinism check
+```
+
+## Layout
+
+```
+source/
+  is-valid-cpf.ts             one utility per file: one export, at the root
+  is-valid-cnpj.ts
+  format-cnpj.ts
+  get-holidays.ts
+  is-business-day.ts
+  get-address-info-by-cep.ts
+  format-currency.ts
+  generate-cpf.ts
+  generate-cnpj.ts
+  lib/                        library code: check digits, masks, JSON, Easter, random
+conformance/
+  cases.ts                    vectors, seeded inputs and the scripted Http
+  run.ts                      the differential runner
+docs/
+  contracts.md                what the published package does, measured
+  survey.md                   every utility of the package, by feature
+out/                          generated, and committed so it can be read in review
+```
+
+## What the core owes, and what the DX owes
+
+The core takes already-normalized values and returns semantic ones. Coercion stays in the
+handwritten DX of each language: reading a number as a string, defaulting an options object,
+turning a host `Date` into a civil date. [`docs/contracts.md`](docs/contracts.md) records that
+split for every pilot, with the behavior measured from `../src` rather than assumed.
+
+## Status
+
+Nine utilities, generated for three languages, verified against the published package on every
+case that can be reproduced offline. [`docs/survey.md`](docs/survey.md) counts what the rest of
+the package would need.