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
3 changes: 1 addition & 2 deletions .boj/project-memories.a2ml
Original file line number Diff line number Diff line change
Expand Up @@ -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"))

; ===================================================================
Expand Down
3 changes: 2 additions & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
## 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)

Expand Down
3 changes: 2 additions & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
- [ ] 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
Expand Down
17 changes: 15 additions & 2 deletions docs/AI-CONVENTIONS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,11 @@ four kept for a live reader.
| TypeScript
| AffineScript

| Node.js / npm / bun
| Deno
| Node.js
| Bun

| yarn
| Bun

| Go
| Rust
Expand All @@ -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
Comment on lines +104 to +106

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reconcile the runtime policy with the repository deed

At session startup this document requires agents to read boj-server_chora.deed, but that deed's implementation-policy allows JavaScript only as Deno and expressly forbids npm, while these new lines require Bun first and permit npm as a fallback. An agent following both mandatory sources therefore has no consistent policy for Bun/npm changes; synchronize the deed with this policy or retain the existing restrictions here until the canonical source is updated.

Useful? React with 👍 / 👎.

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).
Expand Down
22 changes: 13 additions & 9 deletions docs/history/A2ML-REMOVED.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/integration/gateway-observability-spec.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
86 changes: 49 additions & 37 deletions docs/integration/hcg-tier2-rollout-runbook.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 <issue-id>"+` (replace the placeholder
`+"PENDING — http-capability-gateway wiring forthcoming"+` only if it
was already flipped to `+"DEPLOYED"+` per §6.4; otherwise leave
Expand Down Expand Up @@ -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.

Expand All @@ -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: "<ISO-8601 timestamp of §3.3 sign-off>"
deployment_evidence:
- "standards#100 close-out comment <link>"
- "incidents (planned + unplanned) <links>"
----
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

Expand All @@ -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+`
Expand All @@ -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.
1 change: 1 addition & 0 deletions docs/status/ROADMAP.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Qualify when permanent disable changes the status

When a gateway version is permanently disabled before the final §6.4 flip—such as during the rollout or seven-day soak—§5.3 explicitly leaves this item at PENDING and only records the incident. Therefore the new claim that §5.3 sets it to DISABLED is false for that common failure path and can mislead readers of the canonical status record; either describe the condition here or make §5.3 always record permanent disables.

Useful? React with 👍 / 👎.


== Future Directions

Expand Down
60 changes: 45 additions & 15 deletions docs/wikis/Developer-Guide.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <you@example.com>"
description = "PostgreSQL-native database cartridge"
{
"$schema": "https://hyperpolymath.dev/standards/cartridges/cartridge-v1.json",
"spdx": "MPL-2.0",
"copyright": "Copyright (c) 2026 Your Name <you@example.com>",
"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"]
}
}
]
}
Comment on lines +245 to +246

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Mark the shared-library manifest as an FFI cartridge

When a developer installs this manifest and follows the next section to build a shared library, the missing top-level ffi entry makes BojRest.Router.dispatch/4 select JsWorkerPool and look for <cartridges_root>/database-pg-mcp/mod.js; the built library is never invoked. Add the ffi.so_path metadata and document the current cartridge ABI, or change the example to provide the JavaScript module that this manifest currently selects.

Useful? React with 👍 / 👎.

----

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:
Expand All @@ -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 <you@example.com>",
"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

Expand Down
Loading