From f6accdffad8bb243e98100ffa7bb648790f3c2e9 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 23:08:53 +0100 Subject: [PATCH 1/2] =?UTF-8?q?policy:=20Deno=20is=20to=20go,=20Bun=20goes?= =?UTF-8?q?=20first=20=E2=80=94=20correct=20the=20governing=20document?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner ruling 2026-08-26: "deno is to go and bun is the way we are going, put it first everywhere unless not possible and explain why if not". This file is what agents read first and it currently says the opposite, so it is corrected before any repo is touched - otherwise every future agent re-derives the wrong conclusion from the governing document. :89 Deno "tier 2, grandfathered, need not migrate" -> BEING REMOVED; existing projects must migrate to Bun, and where Bun genuinely cannot be used the reason must be DOCUMENTED, not left silently on Deno :187 "No package.json for runtime deps - use deno.json imports" -> Use package.json + bun.lock; Bun is npm-compatible and a manifest is REQUIRED :188 "No node_modules in production - Deno caches automatically" -> bun install --production, pinned via bun.lock :198 "JS deps: Deno (deno.json imports)" -> JS deps: Bun (package.json + bun.lock), bunx for one-off tooling :182 portable Deno CLI scripts are the convert-now bucket -> ...and anything not yet portable to AffineScript moves to Bun WHY :187 MATTERS MOST. "No package.json for runtime deps" did not express a preference - it told repos not to declare their dependencies at all. hyperpolymath/ubicity is the worked example: its sources import zod and glob, it had NO manifest of any kind, and it could not build under ANY toolchain. Fixed in ubicity#107 by deriving a manifest from the imports; the rule that caused it is fixed here. Policy text only - no code, no workflows. The policy table (30 rows) and blockquote structure are intact. NOTED, NOT CHANGED: :197 still reads "Fallback: Nix (flake.nix)". Nix was deprecated for Guix by ADR-2026-STACK-MIGRATION, so that looks stale too, but it is a separate ruling and is not folded into a Deno/Bun correction. Follow-on: 30 repos carry a live deno.json - working task runners, not orphaned config - tracked separately for migration with documented exceptions. --- .claude/CLAUDE.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1db40f2c..51f564c5 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -86,7 +86,7 @@ for the canonical statement. |---------------|----------|-------| | **AffineScript** | Primary application code | Compiles to typed-wasm; affine/linear types. Replaces ReScript across the estate (RS/TS/JS → AffineScript → typed-wasm). | | **Bun** | JS/TS runtime & package management (tier 1) | Default for all new work. Executes `.ts` directly, no build step. Uses an npm-compatible `package.json` plus `bun.lock` — both are expected, not anti-patterns. | -| **Deno** | JS/TS runtime (tier 2) | Grandfathered. Existing Deno projects need not migrate; prefer over pnpm/npm where Bun cannot be used. | +| **Deno** | ~~JS/TS runtime~~ **BEING REMOVED** | Owner ruling 2026-08-26: *"deno is to go and bun is the way we are going, put it first everywhere unless not possible and explain why if not."* Existing Deno projects **must migrate to Bun**. Where Bun genuinely cannot be used, the reason must be documented in the repo — not left silently on Deno. | | **Rust/SPARK** | Performance-critical, systems, WASM, CLI tools, safety-critical | "Rust" always means "Rust/SPARK" per terminology note above. Preferred over Ada where reachable. | | **Zig** | **APIs, FFIs, gateways, client SDKs (estate default 2026-05-28)**, memory-safe systems where Rust/SPARK is overkill | Zig is the estate-wide default for all API/FFI/gateway/client-SDK work unless explicitly special-cased; Idris2 owns ABIs. Completed V-lang→Zig migration 2026-05-28. | | **Idris2** | Formal verification (primary, ABI-style proofs) | ATS2 rejected. Proven-library status in `proven` repo. | @@ -126,6 +126,17 @@ for the canonical statement. > > ReScript's ban is uncontested, and its migration destination is **AffineScript**. +> **SUPERSEDED 2026-08-26 — Deno is no longer tier 2.** The owner ruled: +> *"deno is to go and bun is the way we are going, put it first everywhere unless not +> possible and explain why if not."* The "Bun > Deno > pnpm > npm" ordering above described +> a **preference**; it is now a **removal**. Deno's row has been updated accordingly. +> +> This matters because this file is what agents read first. While it said Deno was +> "grandfathered … need not migrate", agents correctly declined to migrate — and the +> dependency rules below compounded it: *"No package.json for runtime deps — use deno.json +> imports"* left repos with **no manifest at all**. `hyperpolymath/ubicity` could not build +> under any toolchain for exactly this reason (see ubicity#107). Both rules are corrected. + ### BANNED - Do Not Use | Banned | Replacement | Notes | @@ -179,13 +190,13 @@ Both are FOSS with independent governance (no Big Tech). (`docs/migrations/js-to-affinescript`) carves out MCP/LSP protocol glue and VSCode-host code (*"MCP glue … Should NOT appear in `portable now`"*). Those stay until the AffineScript MCP/LSP/VSCode bindings ship (affinescript#446). - Genuinely-portable Deno CLI scripts are the convert-now bucket. + Genuinely-portable Deno CLI scripts are the convert-now bucket; anything not yet portable to AffineScript moves to **Bun**, not left on Deno. - **Compile-verify, wire-first.** A port is not done until the `.affine` builds green (`just check`) and the compiled output is wired as the live entry with the original removed *in the same PR*. Never ship an unbuilt `.affine` or delete a working `.ts`/`.res` for one that has not compiled. -2. **No package.json for runtime deps** - Use deno.json imports -3. **No node_modules in production** - Deno caches deps automatically +2. **Use `package.json` + `bun.lock` for JS runtime deps** - Bun is npm-compatible; a manifest is REQUIRED. (This line previously said "No package.json - use deno.json imports", which left repos with undeclared dependencies that could not build under any toolchain.) +3. **`bun install --production` for production deps** - Bun resolves from `package.json` and pins via `bun.lock` 4. **No Go code** - Use Rust instead 5. **No Python** - All Python must be rewritten 6. **No Kotlin/Swift for mobile** - Use Tauri 2.0+ or Dioxus @@ -195,7 +206,7 @@ Both are FOSS with independent governance (no Big Tech). - **Primary**: Guix (guix.scm) - **Fallback**: Nix (flake.nix) -- **JS deps**: Deno (deno.json imports) +- **JS deps**: **Bun** (`package.json` + `bun.lock`); `bunx ` to run one-off tooling ### Documentation Format From c5912a19b1d1b500f416a8804522ff531d1b18e3 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 27 Aug 2026 00:42:17 +0100 Subject: [PATCH 2/2] policy: no TypeScript at all; Deno moves to BANNED; pin bunx Review feedback on #655 plus a tightened owner ruling. 1. NO TYPESCRIPT (owner, 2026-08-27). Asked about the Bun row advertising direct .ts execution, the owner ruled: "no typescript ... that should not exist at all." Every .ts reference is removed from the Bun row, including "JS/TS" in its label; it now reads "JS runtime". The blockquote sentence "TypeScript is permitted only where AffineScript cannot reach" is marked TOO PERMISSIVE. FLAGGED, NOT RESOLVED: this collides with the "TypeScript Exemptions (Approved)" table, which documents real technical carve-outs (.d.ts files, the npm/Node-native VS Code extension host, MCP/LSP glue). Those are not stylistic and cannot simply be deleted, so they are left standing and marked for an explicit owner decision rather than settled unilaterally. 2. DENO MOVED OUT OF ALLOWED INTO BANNED (codacy, #655). A struck-through row in an ALLOWED table is ambiguous to the agents that read this file - codacy raised exactly that. Deno now appears once, in BANNED, carrying the ruling and pointing at the #658 assessment. 3. UNPINNED bunx (coderabbitai, Security & Privacy). A bare `bunx ` can fetch a package outside package.json/bun.lock and can start Node via a shebang. Guidance now requires a declared devDependency plus `bunx --no-install --bun `. NOT TAKEN: "a npm-compatible" (LanguageTool is wrong; "an" is correct before a vowel sound). "Remove the historical commentary" - the history is why the file was wrong before, and deleting it invites the same drift back. STILL FLAGGED, unchanged: "Fallback: Nix (flake.nix)" is stale under ADR-2026-STACK-MIGRATION, but that is a separate ruling and is deliberately not folded into a Deno/Bun change. --- .claude/CLAUDE.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 51f564c5..91bfe5f2 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -85,8 +85,7 @@ for the canonical statement. | Language/Tool | Use Case | Notes | |---------------|----------|-------| | **AffineScript** | Primary application code | Compiles to typed-wasm; affine/linear types. Replaces ReScript across the estate (RS/TS/JS → AffineScript → typed-wasm). | -| **Bun** | JS/TS runtime & package management (tier 1) | Default for all new work. Executes `.ts` directly, no build step. Uses an npm-compatible `package.json` plus `bun.lock` — both are expected, not anti-patterns. | -| **Deno** | ~~JS/TS runtime~~ **BEING REMOVED** | Owner ruling 2026-08-26: *"deno is to go and bun is the way we are going, put it first everywhere unless not possible and explain why if not."* Existing Deno projects **must migrate to Bun**. Where Bun genuinely cannot be used, the reason must be documented in the repo — not left silently on Deno. | +| **Bun** | JS runtime & package management (tier 1) | Default for all new work. Runs compiled ESM/JS directly — no bundler step. Uses an npm-compatible `package.json` plus `bun.lock` — both are expected, not anti-patterns. | | **Rust/SPARK** | Performance-critical, systems, WASM, CLI tools, safety-critical | "Rust" always means "Rust/SPARK" per terminology note above. Preferred over Ada where reachable. | | **Zig** | **APIs, FFIs, gateways, client SDKs (estate default 2026-05-28)**, memory-safe systems where Rust/SPARK is overkill | Zig is the estate-wide default for all API/FFI/gateway/client-SDK work unless explicitly special-cased; Idris2 owns ABIs. Completed V-lang→Zig migration 2026-05-28. | | **Idris2** | Formal verification (primary, ABI-style proofs) | ATS2 rejected. Proven-library status in `proven` repo. | @@ -120,16 +119,29 @@ for the canonical statement. > > The distinction that keeps both documents coherent: **Bun is the runtime, tier 1 > and unchanged; AffineScript is the language for new application code.** Those -> were run together in the withdrawn text. TypeScript is permitted only where -> AffineScript cannot reach — the same narrow, transitional carve-out JavaScript -> holds below. +> were run together in the withdrawn text. +> +> ⚠ **TIGHTENED 2026-08-27 — owner ruling.** Asked about the Bun row advertising direct +> `.ts` execution, the owner ruled: *"no typescript … that should not exist at all."* +> The previous sentence here read "TypeScript is permitted only where AffineScript cannot +> reach". That is now **too permissive**: TypeScript is not a fallback tier, and no tool +> description in this file may advertise TypeScript support. Every `.ts` reference has been +> removed from the Bun row, including "JS/TS" in its label. +> +> ⚠ **This collides with the "TypeScript Exemptions (Approved)" table below**, which +> documents real technical carve-outs — `.d.ts` declaration files, the VS Code extension +> host (npm/Node-native, `@vscode/test-electron` has no alternative), and MCP/LSP protocol +> glue. Those are **not** stylistic preferences and cannot simply be deleted. They are left +> standing and flagged for an explicit owner decision: either retire each carve-out with a +> migration path, or restate the rule as "no new TypeScript, these listed exemptions +> excepted". **Not resolved unilaterally.** > > ReScript's ban is uncontested, and its migration destination is **AffineScript**. > **SUPERSEDED 2026-08-26 — Deno is no longer tier 2.** The owner ruled: > *"deno is to go and bun is the way we are going, put it first everywhere unless not > possible and explain why if not."* The "Bun > Deno > pnpm > npm" ordering above described -> a **preference**; it is now a **removal**. Deno's row has been updated accordingly. +> a **preference**; it is now a **removal**. Deno has been **moved out of ALLOWED into BANNED** accordingly - a struck-through row in an ALLOWED table is ambiguous to the agents that read this file (codacy raised exactly that on #655). > > This matters because this file is what agents read first. While it said Deno was > "grandfathered … need not migrate", agents correctly declined to migrate — and the @@ -143,6 +155,7 @@ for the canonical statement. |--------|-------------|-------| | TypeScript | AffineScript | RS/TS/JS → AffineScript → typed-wasm. | | **ReScript** | AffineScript | Banned in new code as of 2026-04-30. Existing `.res` files migrate to `.affine` directly (do not pass through ReScript). | +| **Deno** | Bun | **Being removed.** Owner ruling 2026-08-26: *"deno is to go and bun is the way we are going, put it first everywhere unless not possible and explain why if not."* Existing Deno projects must migrate to Bun; where Bun genuinely cannot be used, the reason must be documented in the repo. Assessment of all 30 remaining `deno.json` locations: #658. | | Node.js | Bun | Bun is Node-compatible; run the code, drop the runtime. | | npm | Bun | npm is tier 4 — *permitted, never preferred*, not banned. `package-lock.json` must still not be tracked (standards#67). | | yarn | Bun | yarn is not in the tier list at all. |