diff --git a/.boj/project-memories.a2ml b/.boj/project-memories.a2ml index 45c045aa..8fd15490 100644 --- a/.boj/project-memories.a2ml +++ b/.boj/project-memories.a2ml @@ -61,8 +61,7 @@ schema_version = "1.0.0" "complexity / tier / implementation_time" "FromStr impl" "auto-detect by extension (if applicable)" - "FFI: kind_to_u8 / kind_from_u8" - "STATE.a2ml backend count update") + "FFI: kind_to_u8 / kind_from_u8") (minimum-tests 3 "unit tests per new backend file")) ; =================================================================== diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bf45f03b..4e7398d6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,7 +37,8 @@ Copyright (c) Jonathan D.A. Jewell ## Banned Languages - No TypeScript (use AffineScript) -- No Node.js / npm / bun (use Deno) +- No Node.js runtime (use Bun). Runtime order: Bun > Deno > pnpm > npm; Deno is permitted at tier 2, npm only as the last resort, and `package-lock.json` is never tracked. +- JS dependencies go in `package.json`, pinned by `bun.lock`; both are required. - No Go (use Rust) - No Python (use Julia or Rust) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a980200c..0fc9d84d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,7 +21,8 @@ Copyright (c) Jonathan D.A. Jewell - [ ] Tests pass (`just test` or equivalent) - [ ] Code is formatted (`just fmt` or equivalent) - [ ] Linter is clean (no new warnings or errors) -- [ ] No banned language patterns (no TypeScript, no npm/bun, no Go/Python) +- [ ] No banned language patterns (no TypeScript or ReScript, no Node.js runtime, no Go/Python) +- [ ] JS runs on Bun first (Bun > Deno > pnpm > npm; npm only as the last resort), with dependencies in `package.json` + `bun.lock` and no `package-lock.json` - [ ] No `unsafe` blocks without `// SAFETY:` comments - [ ] No banned functions (`believe_me`, `unsafeCoerce`, `Obj.magic`, `Admitted`, `sorry`) - [ ] SPDX license headers present on all new/modified source files diff --git a/docs/AI-CONVENTIONS.adoc b/docs/AI-CONVENTIONS.adoc index 00f302f6..67819f05 100644 --- a/docs/AI-CONVENTIONS.adoc +++ b/docs/AI-CONVENTIONS.adoc @@ -85,8 +85,11 @@ four kept for a live reader. | TypeScript | AffineScript -| Node.js / npm / bun -| Deno +| Node.js +| Bun + +| yarn +| Bun | Go | Rust @@ -96,6 +99,16 @@ four kept for a live reader. |=== +== JavaScript Runtime + +Order: *Bun > Deno > pnpm > npm*. Bun is tier 1 and comes first everywhere; +Deno is permitted at tier 2; npm is the last resort (permitted, never +preferred), and `package-lock.json` is never tracked. JS dependencies are +declared in `package.json` and pinned by `bun.lock`; both are required, and +`bun install --production` installs production dependencies. A runtime is not +a language: no TypeScript under any runtime (new application code is +AffineScript). + == Container Standard * Runtime: *Podman* (never Docker). diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc index e0c75145..2d1b2298 100644 --- a/docs/history/A2ML-REMOVED.adoc +++ b/docs/history/A2ML-REMOVED.adoc @@ -82,9 +82,9 @@ The deed carriers are `boj-server_chora.deed` (the one repo deed) and | The `(anchor)` clause of `boj-server_chora.deed`, written as `hyperpolymath.anchor/2`, under A7 section 6.4: version to `(metadata :version)`; authority, `(semantic-authority)`, `(implementation-policy)`, `(golden-path)` and `(satellite-policy)` field for field. Not translated (no 6.4 row): `[metadata] last-updated`, `[anchor] repo` and `purpose`, `[identity]` and `[semantic-authority-files]` (whose paths do not exist in this repo). | `0-AI-MANIFEST.a2ml` -| 781 -| `c9e945d66d069efbdee9d9d3c3de451f1f52e924da1fccae131c900fbfe69420` -| `6bf1f8c7f3805520515a5106f68b8cc8d53ad993` +| 5054 +| `147b9d52b16ea780dcdd318ccfeabe4fe0da1bd433ba7020b250d349a2b0bcb4` +| `e8f6c4b3a23f10a9002a336598e8af403da1aa52` | AI manifest (S-expression shape): identity, purpose, context tiers, canonical locations, structure, critical invariants, session lifecycle, format meta. | Replaced by the pointer-only `0-AI-MANIFEST.deed` (A7 ruling Q15). Its sections are not the table of `ai-manifest-decision.adoc`, so nothing was translated. Its canonical locations named files now removed. @@ -296,7 +296,7 @@ The deed carriers are `boj-server_chora.deed` (the one repo deed) and | `abdb3ecb8fae889a5ae4a9e84ffe5dc6d76c55acbe35a7ca47b8c16106671498` | `4a684faaf9b80241083987d6ba03ce3d43548b51` | Trust contractile: threat model, DNS, email, TLS, Cloudflare edge, headers, container and dependency supply chain, gateway, proofs, verification ladder, signature block. -| Deleted: no mapping spec, no machine reader. `trust.ncl` now names `Trustfile.deed`, not yet written. Runbook steps that flip a Trustfile status (`docs/integration/hcg-tier2-rollout-runbook.adoc`) have no target until it exists. +| Deleted: no mapping spec, no machine reader. `trust.ncl` now names `Trustfile.deed`, not yet written. Its one live status, `[CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status` (`PENDING`), now lives in the "Tier-2 gateway status" item under v1.1.0 "Gateway sidecar" in `docs/status/ROADMAP.adoc`; the rollout runbook (`docs/integration/hcg-tier2-rollout-runbook.adoc` §1.4, §5.3, §6.4) records and flips it there. Its `[HTTP_CAPABILITY_GATEWAY]` status (`ACCEPTED-PLANNED`) did not translate; the ROADMAP item is the one record. Both move to `Trustfile.deed` when it is written. | `.machine_readable/integrations/feedback-o-tron.a2ml` | 621 @@ -411,16 +411,20 @@ Deleting it would unsuppress the audited findings. It goes when the deed reader ships and the registry is written as that praxis deed. | `.boj/project-memories.a2ml` -| 4749 (was 4848) -| `54574c577980394826b9d3dd776a7660e5ec0751fbcc5139824eab172dbc6df9` (was `2dc552adf90d7958ad4ccf5ff531e361e883ab14ed1498c25b18e8fb1ffdc0d8`) -| `45c045aaa7a879faaa845efc4e66b85a1f09adf5` (was `63e457ad40043135e31034ff397fe692811b2e73`) +| 4709 (was 4848) +| `fd7ee161f277f4f39501a0b92cd9505d5a910bd39fbaf7576318db5f848e9f20` (was `2dc552adf90d7958ad4ccf5ff531e361e883ab14ed1498c25b18e8fb1ffdc0d8`) +| `8fd15490a7d8824f97ec1c391fa2955fb46d9e84` (was `63e457ad40043135e31034ff397fe692811b2e73`) | The standing worker briefing. The owner's coord-tui hook (`~/.config/coord-tui/coord-hooks.sh`, outside this repository) prepends it to a worker's system prompt when it exists at this path (recorded in the retired STATE journal, 2026-04-27). Deleting it would silently drop the briefing. Its on-start step 3 ("Read the plan": `cat .machine_readable/6a2/STATE.a2ml`) -was deleted, since that file is gone. It goes when that hook reads another -form. +was deleted, since that file is gone, and so was the backend template's +`required-wiring` item "STATE.a2ml backend count update". That template +describes ECHIDNA prover backends (`src/rust/provers/*.rs`, not in this +repository), so their count is ECHIDNA's status to record, not boj-server's; +boj-server's own current status is `docs/status/ROADMAP.adoc`. It goes when +that hook reads another form. | `panll/src/Boj.a2ml` | 2996 diff --git a/docs/integration/gateway-observability-spec.adoc b/docs/integration/gateway-observability-spec.adoc index c803e358..7a75ecac 100644 --- a/docs/integration/gateway-observability-spec.adoc +++ b/docs/integration/gateway-observability-spec.adoc @@ -665,7 +665,7 @@ duration, not a different signal set. === 7. References * Rollout runbook — `+docs/integration/hcg-tier2-rollout-runbook.md+` -(§4 signal list, §5 rollback triggers, §6 Trustfile flip). +(§4 signal list, §5 rollback triggers, §6 status flip). * Sister spec (BoJ side) — `+docs/integration/boj-side-observability-spec.md+` (events, metric names, instrumentation sites for the §3 templates above). diff --git a/docs/integration/hcg-tier2-rollout-runbook.adoc b/docs/integration/hcg-tier2-rollout-runbook.adoc index 2d8da4d3..850df63a 100644 --- a/docs/integration/hcg-tier2-rollout-runbook.adoc +++ b/docs/integration/hcg-tier2-rollout-runbook.adoc @@ -73,17 +73,27 @@ HCG-fronted, percentage-by-percentage (§3). (§4). . *Rollback* — detection, immediate-bypass, and permanent-disable procedures (§5). -. *Post-rollout verification + Trustfile flip* — the final acceptance +. *Post-rollout verification + status flip* — the final acceptance steps that close `+standards#100+` (§6). +*Where the tier-2 status lives.* The legacy Trustfile that held +`+[CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status+` was +retired on 2026-11-14 with no mapping spec to translate it, and its +paired `+Trustfile.deed+` is not yet written +(`+docs/history/A2ML-REMOVED.adoc+` gives the retired file's blob id). +Until it is, the tier-2 gateway status is the "Tier-2 gateway status" +item under v1.1.0 "Gateway sidecar" in `+docs/status/ROADMAP.adoc+`. +§1.4 checks that item, and the status flips in §5.3 and §6.4 edit it. + What is *out of scope*: * HCG internals (policy DSL, ETS table layout, proxy code paths) — covered in `+http-capability-gateway/docs/+`. -* Cloudflare-edge configuration (tier 1) — covered in -`+Trustfile.a2ml [CLOUDFLARE_EDGE_SECURITY]+`. -* BEAM supervisor / cartridge rate-limiting (tier 3/4) — covered -separately in `+Trustfile.a2ml+`. +* Cloudflare-edge configuration (tier 1) — was covered in the retired +Trustfile's `+[CLOUDFLARE_EDGE_SECURITY]+` section (archived in git +history; see `+docs/history/A2ML-REMOVED.adoc+`). +* BEAM supervisor / cartridge rate-limiting (tier 3/4) — was covered +separately in the same retired Trustfile. * Horizontal scaling of BoJ behind the gateway (single-backend limitation, noted as post-Phase-E in the plan). @@ -144,9 +154,10 @@ Cowboy TLS config (http-capability-gateway#10). `+elixir/lib/boj_rest/trust_policy.ex+` line 73 (`+def satisfies?(_required, _trust, false), do: false+`), merged in boj-server#106 (commit `+40e46f6f+`). -* [x] Phase C `+[SEAMS]+` declaration: -`+.machine_readable/contractiles/trust/Trustfile.a2ml [SEAMS]+` -(boj-server#90). +* [x] Phase C `+[SEAMS]+` declaration: the `+[SEAMS]+` section of the +then-current Trustfile (boj-server#90; that file was retired on +2026-11-14 and is archived in git history, see +`+docs/history/A2ML-REMOVED.adoc+`). ==== 1.3 Operational prerequisites — `+!OWNER:+` block @@ -203,10 +214,10 @@ BoJ access logs`") and rollback trigger §5.1 row 4 are unobservable via Prometheus — the only signal path is BoJ structured logs, which the §4 dashboards do not currently consume. Spec landed; the wiring PR follows the spec’s §7 checklist. -* [ ] -`+Trustfile.a2ml [CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status+` -currently `+"PENDING — http-capability-gateway wiring forthcoming"+` -(line 900). _The flip to a real status is the *last* action; see §6._ +* [ ] Tier-2 gateway status (the "Tier-2 gateway status" item in +`+docs/status/ROADMAP.adoc+`) currently +`+"PENDING — http-capability-gateway wiring forthcoming"+`. _The flip +to a real status is the *last* action; see §6._ ==== 1.5 Gateway-side prerequisites @@ -504,8 +515,8 @@ gateway version`": [arabic] . Remove the gateway k9-svc deployment per its spec at `+container/gateway-deploy.k9.ncl+`. -. Update -`+Trustfile.a2ml [CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status+` +. Update the "Tier-2 gateway status" item in +`+docs/status/ROADMAP.adoc+` to `+"DISABLED — see incident "+` (replace the placeholder `+"PENDING — http-capability-gateway wiring forthcoming"+` only if it was already flipped to `+"DEPLOYED"+` per §6.4; otherwise leave @@ -540,7 +551,7 @@ the wrong tier-2). Choose (b) for code-regression issues. ''''' -=== 6. Post-rollout verification + Trustfile flip +=== 6. Post-rollout verification + status flip The acceptance criteria of `+standards#100+` close out here. @@ -562,24 +573,21 @@ before declaring done. drill or otherwise) are recorded with timestamps and outcome. The runbook has been exercised, not only written. -==== 6.4 Trustfile flip — final action - -Edit `+.machine_readable/contractiles/trust/Trustfile.a2ml+` line ~900: +==== 6.4 Status flip — final action -[source,yaml] ----- -tier_2_gateway: - provider: "http-capability-gateway / svalinn" - mechanisms: ["per-IP token-bucket sliding window", "per-capability-token", "per-endpoint"] - status: "DEPLOYED" - deployed_at: "" - deployment_evidence: - - "standards#100 close-out comment " - - "incidents (planned + unplanned) " ----- +Edit the "Tier-2 gateway status" item under v1.1.0 "Gateway sidecar" +in `+docs/status/ROADMAP.adoc+`: tick it, and replace its status with +`+DEPLOYED+`, the `+deployed_at+` ISO-8601 timestamp of the §3.3 +sign-off, and the deployment evidence (the `+standards#100+` close-out +comment link and the incident links, planned and unplanned). This +commit is the one §6.5 links. -Also update `+[HTTP_CAPABILITY_GATEWAY]+` section per plan §E -acceptance: `+status: "DEPLOYED"+` with `+deployed_at+` timestamp. +The retired Trustfile also carried an `+[HTTP_CAPABILITY_GATEWAY]+` +section (`+status: "ACCEPTED-PLANNED"+`) that plan §E acceptance asked +to flip to `+DEPLOYED+`. It went with the file, so the ROADMAP item is +the one status record. When `+Trustfile.deed+` is written +(`+.machine_readable/contractiles/trust/trust.ncl+` names it), the +status moves there and this step is updated to match. ==== 6.5 Channel close-out @@ -599,8 +607,9 @@ Elixir/Cowboy/Plug HTTP-governance layer that sits between Cloudflare edge (tier 1) and BoJ’s gnosis handler (tier 3). * *BoJ* — `+hyperpolymath/boj-server+`, the consumer of HCG. * *Tier 2* — the placement of HCG in the four-tier rate-limit -architecture declared in -`+Trustfile.a2ml [CLOUDFLARE_EDGE_SECURITY].rate_limiting+`. +architecture declared in the retired Trustfile's +`+[CLOUDFLARE_EDGE_SECURITY].rate_limiting+` (archived in git history; +see `+docs/history/A2ML-REMOVED.adoc+`). * *§3 invariant 3* — the Phase A contract requirement that BoJ ignores `+X-Trust-Level+` from any non-loopback caller. Enforced both gateway-side (header strip) and BoJ-side (`+TrustPolicy.satisfies?/3+` @@ -627,10 +636,13 @@ signals. perf-contract. * `+elixir/lib/boj_rest/trust_policy.ex+` — `+satisfies?/3+` Phase C enforcement. -* `+.machine_readable/contractiles/trust/Trustfile.a2ml+` — -`+[CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway+` (current -`+PENDING+` site; §6.4 flip target) + `+[SEAMS]+` (Phase C -gateway↔BoJ-gnosis declaration). +* `+docs/status/ROADMAP.adoc+` — the "Tier-2 gateway status" item +under v1.1.0 "Gateway sidecar" (current `+PENDING+` site; §6.4 flip +target). +* `+docs/history/A2ML-REMOVED.adoc+` — the ledger row for the retired +Trustfile, whose `+[CLOUDFLARE_EDGE_SECURITY].rate_limiting+` and +`+[SEAMS]+` (Phase C gateway↔BoJ-gnosis declaration) sections are +archived in git history. * `+scripts/hcg-policy-smoke.sh+` — §1.5 operator pre-check: deny-path smoke (gateway-alone) + optional `+--with-backend+` allow-path smoke against the live policy. diff --git a/docs/status/ROADMAP.adoc b/docs/status/ROADMAP.adoc index 9de0c316..76a6c88b 100644 --- a/docs/status/ROADMAP.adoc +++ b/docs/status/ROADMAP.adoc @@ -100,6 +100,7 @@ Gateway sidecar (`http-capability-gateway` in front of boj-server): * [x] Implement `PolicyLoader.load_from_boj_catalog/1` in `http-capability-gateway` — reads `BOJ_CARTRIDGES_ROOT/*/cartridge.json` at boot, infers per-cartridge invoke exposure from `auth.method` (`none` → `public`, others → `authenticated`). Zero manual policy maintenance thereafter. See `docs/gateway-catalog-integration.adoc`. * [x] Update `compose.dev.yaml` with gateway sidecar entry (port 7800 → boj-rest:7700) * [x] Retire static `gateway-policy.yaml` — catalog mode live 2026-04-25; file kept as reference only +* [ ] Tier-2 gateway status: `PENDING — http-capability-gateway wiring forthcoming`. Production rollout under `standards#100` per `docs/integration/hcg-tier2-rollout-runbook.adoc`, whose §6.4 flips this item to `DEPLOYED` (with `deployed_at` and the evidence links) as its last action, and whose §5.3 sets it to `DISABLED` on a permanent disable. This status was `[CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status` in the Trustfile retired on 2026-11-14 (`docs/history/A2ML-REMOVED.adoc`); it moves to `Trustfile.deed` when that is written. == Future Directions diff --git a/docs/wikis/Developer-Guide.adoc b/docs/wikis/Developer-Guide.adoc index e131d7ce..e4692830 100644 --- a/docs/wikis/Developer-Guide.adoc +++ b/docs/wikis/Developer-Guide.adoc @@ -205,23 +205,53 @@ The third axis allows community extensions to specialise a cartridge for a speci === Write an extension descriptor -Write the descriptor as a cartridge manifest (currently `cartridge.json`); see -link:../EXTENSIBILITY.adoc[EXTENSIBILITY] §1 for the format. The fields are: +Write the descriptor as a cartridge manifest, `cartridge.json`, valid against +`schemas/cartridge-v1.json` (the mirror `BojRest.Catalog` validates every +manifest against at boot; a manifest that fails is rejected). A minimal +manifest: -[source,toml] +[source,json] ---- -[extension] -name = "database-mcp-pg" -domain = "database" -backend = "postgresql" -tier = "ayo" -protocols = ["mcp", "rest"] - -[metadata] -author = "Your Name " -description = "PostgreSQL-native database cartridge" +{ + "$schema": "https://hyperpolymath.dev/standards/cartridges/cartridge-v1.json", + "spdx": "MPL-2.0", + "copyright": "Copyright (c) 2026 Your Name ", + "name": "database-pg-mcp", + "version": "0.1.0", + "description": "PostgreSQL-native database cartridge", + "domain": "database", + "category": "domain", + "tier": "Ayo", + "protocols": ["MCP", "REST"], + "auth": { + "method": "none", + "env_var": null, + "credential_source": null + }, + "api": { + "base_url": "local://database-pg-mcp", + "content_type": "application/json" + }, + "tools": [ + { + "name": "pg_query", + "description": "Run a read-only SQL query", + "inputSchema": { + "type": "object", + "properties": { "sql": { "type": "string" } }, + "required": ["sql"] + } + } + ] +} ---- +The schema requires the role suffix last in `name` (`-mcp`, `-lsp`, ...), so +a PostgreSQL specialisation of `database-mcp` is named `database-pg-mcp`. +Community extensions are `Ayo` tier. The schema has no `backend` field, so the +backend label (third axis) is set through the FFI +(`boj_catalogue_set_backend`, link:../EXTENSIBILITY.adoc[EXTENSIBILITY] §4). + === Build a shared library Export the BoJ cartridge invoke contract: @@ -239,14 +269,14 @@ int boj_ext_invoke(const char* tool, const char* params_json, curl -X POST http://localhost:7700/community/submit \ -H 'Content-Type: application/json' \ -d '{ - "name": "database-mcp-pg", + "name": "database-pg-mcp", "author": "Your Name ", "description": "PostgreSQL-native database cartridge", "hash": "a1b2c3...64-char-sha256" }' ---- -See link:../EXTENSIBILITY.md[`docs/EXTENSIBILITY.adoc`] for the full guide. +See link:../EXTENSIBILITY.adoc[`docs/EXTENSIBILITY.adoc`] for the full guide. == Running Tests