Repository navigation
docs: fix EXTENSIBILITY examples, retire stale Trustfile references, strip the AI manifest to pointers - #386
Conversation
…strip the AI manifest to pointers - docs/EXTENSIBILITY.adoc: the descriptor example was TOML under a .json name; it is now a cartridge.json that validates against schemas/cartridge-v1.json, named with the role suffix the schema requires (database-pg-mcp, not database-mcp-pg). The C boj_ext_invoke export is replaced by the ADR-0006 five-symbol Zig FFI of the cartridge template, the C registration example by Zig extern declarations matching ffi/zig/src/catalogue.zig, and the menu JSON by the shape boj_menu_json writes. The REST examples now say what the router serves: /community/submit is specified but not routed, and /cartridges takes no domain or backend parameters. Spec link points at README.adoc; no http:// URLs remain. - Trustfile: Trustfile.a2ml was retired on 2026-11-14 (#383) with no mapping spec; its successor Trustfile.deed is not yet written and the tier-2 status lives in docs/status/ROADMAP.adoc. Integration docs, the maintenance checklist, the v1 plan, elixir/README.adoc and the contractiles README now say so instead of pointing at the old file. ADRs and dated audits keep their historical wording. - 0-AI-MANIFEST.deed: pointer-only per A7 ruling Q15. :canonical-name, :repo-uuid and :beholding-chora are removed; boj-server_chora.deed carries the same three values unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC
|
Caution Review failedThe pull request is closed. Summary
Merge Risk:
|
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
🔍 Hypatia Security ScanFindings: 68 issues detected
View findings (sorted by severity)[
{
"line": 70,
"reason": "believe_me undermines formal verification (4 occurrences, CWE-704, line 70, 269, 279, 289)",
"type": "believe_me",
"file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafetyLemmas.idr",
"level": "epi",
"rule_module": "code_safety",
"action": "flag",
"severity": "critical",
"evidence": [
{
"span": {
"file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafetyLemmas.idr",
"end_line": 70,
"start_line": 70
},
"rule": "code_safety/believe_me",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Step uses `peter-evans/repository-dispatch` with `token: ${{ secrets.FARM_DISPATCH_TOKEN }}` but has no `if: secrets.FARM_DISPATCH_TOKEN != ''` gate. On repos where the secret hasn't been propagated the action fails on every push, red-maining the repo. Add the step-level gate (or env+if pattern) so the missing-secret path is a clean skip instead of a red.",
"type": "secret_action_without_presence_gate",
"file": ".github/workflows/instant-sync.yml",
"level": "epi",
"rule_module": "workflow_audit",
"action": "peter-evans/repository-dispatch",
"severity": "high",
"fix_recipe": "add_secret_presence_gate",
"evidence": [
{
"span": {
"file": ".github/workflows/instant-sync.yml",
"end_line": 0,
"start_line": 0
},
"rule": "workflow_audit/secret_action_without_presence_gate",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 29,
"reason": "job `deploy` in .github/workflows/pages-deploy.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring; it holds the credential next to fetched code (a piped installer or a dependency install/build) in the same step",
"type": "RE001",
"file": ".github/workflows/pages-deploy.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/pages-deploy.yml",
"end_line": 29,
"start_line": 29
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code scanning (Hypatia): hypatia/workflow_audit/secret_action_without_presence_gate -- Hypatia workflow_audit: secret_action_without_presence_gate -- 41 day(s) old [STALE]",
"type": "CSA001",
"file": ".github/workflows/instant-sync.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/instant-sync.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code scanning (Hypatia): hypatia/code_safety/believe_me -- Hypatia code_safety: believe_me -- 44 day(s) old [STALE]",
"type": "CSA001",
"file": "src/abi/Boj/SafetyLemmas.idr",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": "src/abi/Boj/SafetyLemmas.idr",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert PinnedDependenciesID (medium) at .github/workflows/proofs.yml is 33 days old (threshold: 30 days) -- overdue for remediation",
"type": "CSA003",
"file": ".github/workflows/proofs.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/proofs.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert hypatia/workflow_audit/secret_action_without_presence_gate (high) at .github/workflows/instant-sync.yml is 41 days old (threshold: 7 days) -- overdue for remediation",
"type": "CSA003",
"file": ".github/workflows/instant-sync.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/instant-sync.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert hypatia/workflow_audit/missing_timeout_minutes (medium) at .github/workflows/pages-deploy.yml is 41 days old (threshold: 30 days) -- overdue for remediation",
"type": "CSA003",
"file": ".github/workflows/pages-deploy.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/pages-deploy.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert hypatia/code_safety/zig_bit_cast (medium) at ffi/zig/src/cartridge_shim.zig is 44 days old (threshold: 30 days) -- overdue for remediation",
"type": "CSA003",
"file": "ffi/zig/src/cartridge_shim.zig",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": "ffi/zig/src/cartridge_shim.zig",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert hypatia/code_safety/believe_me (high) at src/abi/Boj/SafetyLemmas.idr is 44 days old (threshold: 7 days) -- overdue for remediation",
"type": "CSA003",
"file": "src/abi/Boj/SafetyLemmas.idr",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": "src/abi/Boj/SafetyLemmas.idr",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert PinnedDependenciesID (medium) at .github/workflows/push-email-notify.yml is 54 days old (threshold: 30 days) -- overdue for remediation",
"type": "CSA003",
"file": ".github/workflows/push-email-notify.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/push-email-notify.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Code-scanning alert PinnedDependenciesID (medium) at .github/workflows/dogfood-gate.yml is 54 days old (threshold: 30 days) -- overdue for remediation",
"type": "CSA003",
"file": ".github/workflows/dogfood-gate.yml",
"level": "epi",
"rule_module": "code_scanning_alerts",
"action": "escalate",
"severity": "high",
"evidence": [
{
"span": {
"file": ".github/workflows/dogfood-gate.yml",
"end_line": 0,
"start_line": 0
},
"rule": "code_scanning_alerts/CSA003",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"reason": "Job `deploy` in pages-deploy.yml has no `timeout-minutes:` declaration. Default is 6 hours — a stuck codeload fetch or runner hang can burn budget. Add `timeout-minutes: 10` (or proportional).",
"type": "missing_timeout_minutes",
"file": ".github/workflows/pages-deploy.yml",
"level": "epi",
"rule_module": "workflow_audit",
"action": "flag",
"severity": "medium",
"recipe_id": "recipe-add-workflow-timeout-minutes",
"job": "deploy",
"evidence": [
{
"span": {
"file": ".github/workflows/pages-deploy.yml",
"end_line": 0,
"start_line": 0
},
"rule": "workflow_audit/missing_timeout_minutes",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 44,
"reason": "job `build-and-push` in .github/workflows/container-publish.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/container-publish.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/container-publish.yml",
"end_line": 44,
"start_line": 44
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 37,
"reason": "job `sonarqube` in .github/workflows/build.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/build.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/build.yml",
"end_line": 37,
"start_line": 37
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 88,
"reason": "job `publish-bun` in .github/workflows/publish.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/publish.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/publish.yml",
"end_line": 88,
"start_line": 88
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 122,
"reason": "job `publish-jsr` in .github/workflows/publish.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/publish.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/publish.yml",
"end_line": 122,
"start_line": 122
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 34,
"reason": "job `dispatch` in .github/workflows/instant-sync.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/instant-sync.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/instant-sync.yml",
"end_line": 34,
"start_line": 34
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 278,
"reason": "job `scan` in .github/workflows/hypatia-scan.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring; it holds the credential next to fetched code (a piped installer or a dependency install/build)",
"type": "RE001",
"file": ".github/workflows/hypatia-scan.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/hypatia-scan.yml",
"end_line": 278,
"start_line": 278
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 46,
"reason": "job `notify` in .github/workflows/push-email-notify.yml references `secrets.*` but does not install `step-security/harden-runner` or declare its egress — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/push-email-notify.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/push-email-notify.yml",
"end_line": 46,
"start_line": 46
},
"rule": "research_extensions/RE001",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 38,
"reason": "workflow .github/workflows/fuzz.yml:38 step `Run core FFI fuzz tests` swallows non-zero exit via `continue-on-error: true` AND `|| true` — failures will be masked",
"type": "RE005",
"file": ".github/workflows/fuzz.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/fuzz.yml",
"end_line": 38,
"start_line": 38
},
"rule": "research_extensions/RE005",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 224,
"reason": "workflow .github/workflows/abi-drift.yml:224 step `Scope cartridges to verify` swallows non-zero exit via `|| true` — failures will be masked",
"type": "RE005",
"file": ".github/workflows/abi-drift.yml",
"level": "epi",
"rule_module": "research_extensions",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/abi-drift.yml",
"end_line": 224,
"start_line": 224
},
"rule": "research_extensions/RE005",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 22,
"reason": "workflow .github/workflows/pages-deploy.yml:22 job `deploy` has no `timeout-minutes:` — defaults to 360 min on hang",
"type": "WH006",
"file": ".github/workflows/pages-deploy.yml",
"level": "epi",
"rule_module": "workflow_hardening",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": ".github/workflows/pages-deploy.yml",
"end_line": 22,
"start_line": 22
},
"rule": "workflow_hardening/WH006",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 175,
"reason": "Zig @bitCast reinterprets bits without type checking (1 occurrences, CWE-704, line 175)",
"type": "zig_bit_cast",
"file": "/home/runner/work/boj-server/boj-server/ffi/zig/src/cartridge_shim.zig",
"level": "epi",
"rule_module": "code_safety",
"action": "flag",
"severity": "medium",
"evidence": [
{
"span": {
"file": "/home/runner/work/boj-server/boj-server/ffi/zig/src/cartridge_shim.zig",
"end_line": 175,
"start_line": 175
},
"rule": "code_safety/zig_bit_cast",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
},
{
"line": 58,
"reason": "Secret found: Generic API key (placeholder-shaped value — verify it is not a real credential)",
"type": "secret_detected",
"file": "/home/runner/work/boj-server/boj-server/tools/cartridge-provisioner/README.adoc",
"level": "epi",
"rule_module": "security_errors",
"action": "report",
"severity": "medium",
"evidence": [
{
"span": {
"file": "/home/runner/work/boj-server/boj-server/tools/cartridge-provisioner/README.adoc",
"end_line": 58,
"start_line": 58
},
"rule": "security_errors/secret_detected",
"observations": 1,
"rule_version": "0.1.0"
}
],
"support": {
"kind": "pattern"
}
}
]Powered by Hypatia Neurosymbolic CI/CD Intelligence |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ae1f6e982a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| fn registerPg() bool { | ||
| if (boj_catalogue_init() != 0) return false; |
There was a problem hiding this comment.
Initialize the catalogue only once before registrations
When this helper is called after the host has registered its core or other extension cartridges, boj_catalogue_init() resets catalogue_count to zero and clears the catalogue, so registering this PostgreSQL cartridge silently removes every prior entry. Initialization should remain a one-time host startup operation; this per-extension helper should only call the registration and configuration functions.
Useful? React with 👍 / 👎.
| // Required export: | ||
| int boj_ext_invoke(const char* tool, const char* params_json, | ||
| char* result_buf, size_t result_len); | ||
| const shim = @import("cartridge_shim.zig"); |
There was a problem hiding this comment.
Point the import at the checked-in shim
Following this newly documented build example fails because templates/cartridge-template/ffi/ contains no cartridge_shim.zig, and its build.zig does not provide a module under that name. The checked-in shim itself documents a relative import from ffi/zig/src/cartridge_shim.zig; use that path or require users to copy/wire the shim before claiming the template builds with the adjacent build.zig.
Useful? React with 👍 / 👎.
| > manifests read today are `cartridge.json`. The Elixir catalog | ||
| > (`elixir/lib/boj_rest/catalog.ex`) validates each one against the bundled | ||
| > schema mirror `schemas/cartridge-v1.json` (see `schemas/SCHEMA-MIRROR.adoc`) |
There was a problem hiding this comment.
Replace the invalid starter manifest
When a developer follows this instruction and starts from templates/cartridge-template/cartridge.json, the strict Elixir catalog rejects the result before they make any backend-specific changes: that template's my-new-cartridge name lacks a role suffix, it omits the required $schema, spdx, copyright, category, and api properties, and its auth object omits two required fields. Either update the referenced template to conform to schemas/cartridge-v1.json or stop presenting it as the valid starting point.
Useful? React with 👍 / 👎.
| -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" | ||
| "repository": "https://github.com/you/database-pg-mcp" | ||
| }' |
There was a problem hiding this comment.
Keep the submission payload compatible with the state machine
Once this route is implemented against the cited ffi/zig/src/community.zig state machine, this payload cannot be submitted: boj_community_submit requires a description and an exactly 64-character hash, and it has no repository argument or storage field. The existing docs/API-CONTRACT.adoc and developer guide consequently still specify description and hash; either retain those fields here or update the state machine and API contract together before advertising the repository-based request.
Useful? React with 👍 / 👎.
Summary
Small debts, docs and metadata only. No code, workflow, licence or lockfile changes.
Changes
docs/EXTENSIBILITY.adoc.cartridge.json. It is now acartridge.jsonthat validates againstschemas/cartridge-v1.json(checked with ajv, draft 2020-12). It uses the role-suffixed name the schema requires:database-pg-mcp. The schema rejectsdatabase-mcp-pg.boj_ext_invokeexport is replaced by the ADR-0006 five-symbol Zig FFI, taken fromtemplates/cartridge-template/ffi/cartridge_ffi.zig.#include "boj_catalogue.h"registration is replaced by Zigexterndeclarations that matchffi/zig/src/catalogue.zig. Constants are fromgenerated/abi/boj_catalogue.h.boj_menu_jsonwrites.POST /community/submitis specified (openapi, gateway policy) butrouter.exdoes not serve it./cartridgestakes nodomainorbackendparameters. The examples use"$BOJ_URL"instead ofhttp://localhost.README.adoc. The doc also says the backend label lives in the catalogue, not incartridge.json.Trustfile references.
Trustfile.a2mlwas retired in chore(a2ml): move boj-server off A2ML; CLAUDE.md follows the current runtime ruling #383 with no mapping spec.Trustfile.deedis not yet written, and the tier-2 status lives indocs/status/ROADMAP.adoc. Updated these files to say so:[x]is now unchecked)elixir/README.adocTrustfile.hsandlust/IntentfileADRs 0003/0004, the dated audit and the 3b completion snapshot keep their historical wording.
0-AI-MANIFEST.deedis now pointer-only, per A7 ruling Q15.:canonical-name,:repo-uuidand:beholding-choraare removed.boj-server_chora.deedcarries identical values, and no id or domain was changed.Testing
deed_lint.js:OK 0-AI-MANIFEST.deed,OK boj-server_chora.deed1725beball pass: workflows-parse, lock-sync, close-lock, duplicate-keys, licence-consistency, language-policy, ts-allowlist, package-policy, docs-presence, uuid-v8--strict, trusted-base, exemption and debt ratchets.validate-a2ml.sh,validate-k9.sh,check-shebang-first.shandjust validate-rsr..adocwith 0 warnings.git diff --summaryshows no mode changes.Generated by Claude Code